@acropole/skills 1.7.0 → 1.7.1

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.
@@ -1912,3 +1912,318 @@ readonly features = signal<readonly (ListEditorPair & { id?: string })[]>([]);
1912
1912
  - Campos extras do item (`id`, `sort_order`...) sobrevivem à edição; recalcule a ordem pelo índice ao salvar.
1913
1913
  - Colar vários itens de uma vez é o `hm-bulk-input`.
1914
1914
 
1915
+ ## 39. Formatação no idioma ativo e campos de moeda/percentual
1916
+
1917
+ ```html
1918
+ <p>{{ total | hmCurrency }} · {{ 0.155 | hmPercent }} · {{ 15.5 | hmPercent: 'points' }}</p>
1919
+ <p>{{ arquivo.bytes | hmFileSize }} · enviado {{ arquivo.enviadoEm | hmRelativeTime: { now: relogio() } }}</p>
1920
+ <p>Duração: {{ execucao.ms | hmDuration }}</p>
1921
+
1922
+ <hm-currency-input label="Valor do pedido" currency="BRL" formControlName="valor" />
1923
+ <hm-percent-input label="Desconto" valueScale="points" formControlName="desconto" />
1924
+ ```
1925
+ ```ts
1926
+ import { formatCurrency } from '@trismegisto/primitives';
1927
+ readonly relogio = signal(Date.now()); // atualize a cada minuto para "há 5 minutos" envelhecer
1928
+ // fora do template (CSV, título da aba): a mesma regra, com o locale explícito
1929
+ const texto = formatCurrency(1234.5, 'pt-BR', 'BRL'); // 'R$ 1.234,50'
1930
+ ```
1931
+ - Os campos guardam **número** no modelo (moeda em unidades, não centavos) e escrevem no formato do idioma; não use
1932
+ `hm-input type="number"` com prefixo "R$".
1933
+ - `hmPercent` recebe fração (`0.155` → 16%); valor já em pontos leva `'points'`. A moeda é dado, não idioma: em
1934
+ inglês, reais continuam reais.
1935
+
1936
+ ## 40. Data com hora, mês, faixa de horário e seleção hierárquica
1937
+
1938
+ ```html
1939
+ <hm-datetime-picker label="Início da manutenção" [interval]="15" defaultTime="08:00" formControlName="inicio" />
1940
+ <hm-month-picker label="Competência" formControlName="competencia" /> <!-- 'AAAA-MM' -->
1941
+ <hm-time-range label="Expediente" [interval]="30" overnight showDuration formControlName="expediente" />
1942
+
1943
+ <hm-tree-select label="Centro de custo" [nodes]="centros()" leavesOnly showPath searchable formControlName="centro" />
1944
+ <hm-tree-select-multi label="Unidades" [nodes]="unidades()" [maxChips]="3" formControlName="unidades" />
1945
+ <hm-cascader label="Categoria" [nodes]="categorias()" [loadChildren]="carregarFilhos" formControlName="categoria" />
1946
+ ```
1947
+ - `nodes` é `TreeNode[]` (o mesmo do `hm-tree`); carga sob demanda por `loadChildren`.
1948
+ - `hm-time-range` vale `{ start, end }` (`'HH:mm'`); `overnight` aceita virar a meia-noite (plantão 22:00–06:00).
1949
+ - Mês sem dia é `hm-month-picker`, não um `hm-date-picker` com o dia 1 escondido.
1950
+
1951
+ ## 41. Formulário acessível: resumo de erros, anúncio, skip link e alterações não salvas
1952
+
1953
+ ```html
1954
+ <form [formGroup]="form" (ngSubmit)="enviar()" novalidate>
1955
+ <hm-form-error-summary [errors]="erros()" />
1956
+ <hm-input formControlName="nome" label="Nome" />
1957
+ <hm-input formControlName="email" label="E-mail" type="email" />
1958
+ <hm-save-status [status]="salvamento()" [savedAt]="salvoEm()" retryable (retry)="enviar()" />
1959
+ <hm-button type="submit">Salvar</hm-button>
1960
+ </form>
1961
+ ```
1962
+ ```ts
1963
+ import { formErrorsFrom, HERMES_MESSAGES, HermesAnnouncer, registerUnsavedChanges, type FormErrorItem } from '@trismegisto/angular';
1964
+ private readonly catalogo = inject(HERMES_MESSAGES);
1965
+ private readonly anunciador = inject(HermesAnnouncer);
1966
+ readonly #alteracoes = registerUnsavedChanges(() => this.form.dirty); // campo da classe (contexto de injeção)
1967
+ readonly erros = signal<FormErrorItem[]>([]);
1968
+
1969
+ enviar(): void {
1970
+ this.form.markAllAsTouched();
1971
+ // a lista é o retrato do envio: montada aqui, não a cada tecla
1972
+ this.erros.set(formErrorsFrom(this.form, { nome: 'Nome', email: 'E-mail' }, this.catalogo));
1973
+ if (this.form.invalid) return;
1974
+ // … salvar; depois: this.form.markAsPristine(); this.anunciador.announce('Cadastro salvo.');
1975
+ }
1976
+ ```
1977
+ ```ts
1978
+ // rotas + app
1979
+ { path: 'pedido/:id', component: PedidoPage, canDeactivate: [hermesUnsavedChangesGuard] }
1980
+ providers: [provideHermesUnsavedChanges({ beforeUnload: true })] // aviso nativo ao recarregar/fechar
1981
+ ```
1982
+ - O resumo recebe o foco quando aparece; cada link leva ao campo. Sem erros, não desenha nada.
1983
+ - `hm-skip-link` é o primeiro item da página (`target` = id do conteúdo; vazio = o `<main>`). Com spine, ligue
1984
+ `SpineConfig.features.skipLink` e `features.unsavedChanges` (a tela registra com `registerSpineUnsavedChanges`).
1985
+ - Não crie região `aria-live` na tela: `HermesAnnouncer.announce(texto)` (ou `[hmAnnounce]`).
1986
+ - `hm-modal` já deixa a página de trás `inert` enquanto está aberto; não ponha `inert`/`aria-hidden` à mão.
1987
+
1988
+ ## 42. Overlays e ações: popconfirm, split button, tour e bottom sheet
1989
+
1990
+ ```html
1991
+ <hm-button intent="danger" emphasis="medium" [hmPopconfirmTrigger]="confirmar">Arquivar</hm-button>
1992
+ <hm-popconfirm #confirmar heading="Arquivar o projeto?" message="Ele sai da lista, mas pode ser restaurado."
1993
+ intent="danger" (confirmed)="arquivarProjeto()" />
1994
+
1995
+ <hm-split-button label="Salvar" [items]="variacoes" (clicked)="salvar()" (chosen)="salvarComo($event)" />
1996
+
1997
+ <hm-tour [(open)]="tourAberto" [steps]="passos" (finished)="marcarVisto()" (skipped)="marcarVisto()" />
1998
+
1999
+ <hm-bottom-sheet [(open)]="acoesAbertas" heading="Arquivo" [actions]="acoesArquivo" (chosen)="executar($event)" />
2000
+ <hm-progress shape="circle" label="Envio" [value]="enviados()" [max]="total()" showValue />
2001
+ ```
2002
+ ```ts
2003
+ import type { MenuItem } from '@trismegisto/angular';
2004
+ import type { BottomSheetAction, TourStep } from '@trismegisto/primitives';
2005
+ readonly variacoes: MenuItem[] = [{ id: 'rascunho', label: 'Salvar como rascunho' }, { id: 'copia', label: 'Salvar uma cópia' }];
2006
+ readonly passos: TourStep[] = [
2007
+ { target: '#novo-pedido', title: 'Novo pedido', body: 'Comece por aqui.' },
2008
+ { target: '#filtros', title: 'Filtros', body: 'Refine a lista e salve combinações.' },
2009
+ ];
2010
+ readonly acoesArquivo: BottomSheetAction[] = [{ id: 'baixar', label: 'Baixar', icon: 'download' }, { id: 'excluir', label: 'Excluir', intent: 'danger' }];
2011
+ ```
2012
+ - Popconfirm é para ação reversível ou de baixo risco; exclusão definitiva continua `HermesDialogService.confirm({ danger: true })`.
2013
+ - `hm-bottom-sheet` com `snapPoints` (`[0.5, 0.9]`) vira painel com alturas de parada; com `actions`, é action sheet.
2014
+ - Os textos padrão (Cancelar, Pular, Concluir…) vêm do catálogo da peça; troque só o que precisar pelo input
2015
+ `texts` (ex.: `[texts]="{ … }"` no `hm-popconfirm`).
2016
+
2017
+ ## 43. Data grid com edição inline e tree table
2018
+
2019
+ ```html
2020
+ <hm-data-grid caption="Itens do orçamento" [rows]="itens()" [columns]="colunas" editMode="cell" editBatch
2021
+ (editSaved)="salvar($event)">
2022
+ <ng-template hmCellEditor="centro" let-row let-value="value" let-set="set" let-commit="commit" let-label="label">
2023
+ <hm-tree-select [label]="label" labelHidden [nodes]="centros()" [value]="value" (valueChange)="set($event); commit()" />
2024
+ </ng-template>
2025
+ </hm-data-grid>
2026
+
2027
+ <hm-data-grid caption="Estrutura" [rows]="raizes()" [columns]="colunasArvore"
2028
+ [treeChildren]="filhos" [columnGroups]="grupos" [striped]="false"
2029
+ treePagination="roots" [treeChildPageSize]="10" itemsLabel="estruturas" />
2030
+ ```
2031
+ ```ts
2032
+ readonly colunas: GridColumn<Item>[] = [
2033
+ { key: 'descricao', title: 'Descrição', value: (i) => i.descricao, editor: { required: true } },
2034
+ { key: 'quantidade', title: 'Qtd.', type: 'number', value: (i) => String(i.quantidade),
2035
+ editor: { min: 1, validate: (v) => (Number(v) > 999 ? 'Máximo 999.' : null) } },
2036
+ { key: 'centro', title: 'Centro de custo', value: (i) => i.centroNome,
2037
+ editor: { type: 'custom', value: (i) => i.centro } },
2038
+ ];
2039
+ salvar({ changes }: DataGridEditSave<Item>): void {
2040
+ // a grade não grava nada: persista e devolva as linhas novas em `rows`
2041
+ }
2042
+ readonly filhos = (linha: No) => linha.filhos ?? null;
2043
+ readonly grupos: GridColumnGroup[] = [{ key: 'plano', title: 'Planejado', columns: ['inicio', 'fim'] }];
2044
+ ```
2045
+ - Coluna sem `editor` não edita. `editMode="row"` abre a linha inteira com Salvar/Cancelar.
2046
+ - Textos da edição: `texts` (parcial). Métodos: `editRow(id)`, `saveEdits()`, `discardEdits()`.
2047
+ - Paginação da tree table (3.3.11): por padrão (`treePagination="rows"`) a página corta a lista visível, filhos
2048
+ inclusive. Com `"roots"`, a página conta só as raízes e cada uma vem com todos os filhos abertos, sem separar
2049
+ uma raiz dos filhos entre páginas. `treeChildPageSize` mostra os N primeiros filhos de cada pai e a linha
2050
+ "Mostrar mais"; com busca, todos os achados aparecem.
2051
+
2052
+ ## 44. Gráficos novos: sparkline, bullet, waterfall, bolhas e medidor animado
2053
+
2054
+ ```ts
2055
+ import { HmSparklineChartComponent, HmBulletChartComponent, HmWaterfallChartComponent, HmScatterChartComponent,
2056
+ HmGaugeChartComponent } from '@trismegisto/charts';
2057
+ ```
2058
+ ```html
2059
+ <hm-stat-card label="Receita" [value]="receita()">
2060
+ <hm-sparkline-chart footer label="Receita nos últimos 30 dias" [data]="ultimos30()" [categories]="dias()" [area]="true" />
2061
+ </hm-stat-card>
2062
+ <hm-bullet-chart label="Metas do trimestre" [items]="[{ name: 'Vendas', value: 72, target: 80, ranges: [50, 80, 100] }]" />
2063
+ <hm-waterfall-chart label="Do bruto ao líquido" [steps]="[{ name: 'Bruto', value: 1000 }, { name: 'Impostos', value: -180 }, { name: 'Líquido', total: true }]" />
2064
+ <hm-scatter-chart label="Lojas" xLabel="Ticket médio" yLabel="Margem" sizeLabel="Clientes"
2065
+ [series]="[{ name: 'Lojas', data: [{ x: 120, y: 0.18, size: 900, name: 'Centro' }] }]" />
2066
+ <hm-gauge-chart label="Uso do disco" [value]="72" [animated]="true" [needle]="true" caption="72% de 500 GB" />
2067
+ ```
2068
+ - Bolhas não são um componente novo: é o `hm-scatter-chart` com `size` nos pontos (área proporcional; a tabela
2069
+ ganha a coluna de tamanho).
2070
+ - O medidor anima arco, agulha e número juntos e respeita `prefers-reduced-motion`.
2071
+ - Burndown/burnup: `burndownSeries({ start, end, scope, completed, today })` (`@trismegisto/primitives`) +
2072
+ `hm-line-chart`; com `today`, os dias futuros saem `null` (não preencha com zero).
2073
+
2074
+ ## 45. Campos e visualizadores: tags, cor, avaliação, JSON, logs, galeria e PDF
2075
+
2076
+ ```html
2077
+ <hm-tag-input label="Etiquetas" [suggestions]="sugestoes" [max]="8" [validate]="semEspaco" formControlName="tags" />
2078
+ <hm-color-picker label="Cor do quadro" [swatches]="cores" clearable formControlName="cor" />
2079
+ <hm-rating label="Nota do atendimento" allowHalf formControlName="nota" />
2080
+
2081
+ <hm-json-viewer label="Resposta" [data]="payload()" [expandDepth]="1" searchable copyable />
2082
+ <hm-log-viewer label="Saída do job" [entries]="linhas()" [(follow)]="seguir" height="24rem" />
2083
+ <hm-image-gallery label="Fotos da vistoria" [images]="fotos()" />
2084
+ <hm-pdf-viewer label="Contrato" [src]="contratoUrl()" fileName="contrato.pdf" />
2085
+ ```
2086
+ - Os textos dessas sete peças são sobrescritos pelo input `texts` (parcial); `messages` nelas continua sendo o
2087
+ texto por chave de erro do formulário.
2088
+ - `hm-image-gallery` abre o `hm-lightbox` sozinho; o `hm-lightbox` avulso serve para abrir a partir de outra lista.
2089
+
2090
+ ## 46. Workflow e tarefas: status com motivo, Gantt editável e raias
2091
+
2092
+ ```html
2093
+ <hm-status-select label="Situação" [definition]="fluxo" [(value)]="chamado.status" [apply]="false"
2094
+ (transition)="mudarStatus($event)" />
2095
+ <hm-level-select label="Prioridade" scale="priority" [(value)]="chamado.prioridade" allowEmpty />
2096
+
2097
+ <hm-gantt label="Cronograma" [items]="cronograma()" editable [editStep]="1" (taskChange)="remarcar($event)" />
2098
+
2099
+ <hm-swimlane-board [(columns)]="colunas" [lanes]="raias" [laneOf]="raiaDe" [itemLabel]="tituloDe"
2100
+ allowLaneChange [canMoveLane]="podeTrocar" (laneChange)="trocarRaia($event)">
2101
+ <ng-template hmKanbanCard let-tarefa>
2102
+ <hm-task-card [task]="tarefa" [statuses]="fluxo.statuses" [showStatus]="false" />
2103
+ </ng-template>
2104
+ </hm-swimlane-board>
2105
+ ```
2106
+ ```ts
2107
+ import type { GanttTaskChange, StatusTransitionEvent } from '@trismegisto/angular';
2108
+ import type { TaskItem, WorkflowDefinition } from '@trismegisto/primitives';
2109
+ readonly fluxo: WorkflowDefinition = {
2110
+ statuses: [
2111
+ { id: 'aberto', label: 'Aberto', category: 'todo' },
2112
+ { id: 'andamento', label: 'Em andamento', category: 'active' },
2113
+ { id: 'resolvido', label: 'Resolvido', category: 'done' },
2114
+ ],
2115
+ transitions: [
2116
+ { from: 'aberto', to: 'andamento' },
2117
+ { from: 'andamento', to: 'resolvido', reason: 'required' }, // pede o motivo antes de emitir
2118
+ ],
2119
+ };
2120
+ async mudarStatus(e: StatusTransitionEvent): Promise<void> { /* grava e.to e e.reason; depois atualiza o valor */ }
2121
+ remarcar(e: GanttTaskChange): void { /* grava e.start/e.end e devolve `items` atualizado */ }
2122
+ readonly raiaDe = (t: TaskItem) => t.assignee?.id ?? 'sem-responsavel';
2123
+ readonly tituloDe = (t: TaskItem) => t.title;
2124
+ ```
2125
+ - Sem `editable`, o Gantt só mostra; com ele, e sem tratar `(taskChange)`, a barra volta ao lugar ao soltar.
2126
+ - Sem `allowLaneChange`, o cartão só muda de coluna dentro da raia (comportamento antigo).
2127
+ - As peças não gravam: o app aplica a mudança e devolve o input (`items`, `columns`, `value`).
2128
+
2129
+ ## 47. Pessoas, acesso e conta
2130
+
2131
+ ```html
2132
+ <hm-entity-picker label="Responsáveis" kind="user" multiple [entities]="pessoas()" formControlName="responsaveis" />
2133
+ <hm-member-list label="Membros da equipe" [members]="membros()" [roles]="papeis" editable invitable
2134
+ (roleChange)="trocarPapel($event)" (remove)="remover($event)" (invite)="convidar()" />
2135
+ <hm-permission-matrix label="Permissões por papel" [roles]="papeis" [permissions]="permissoes" [(grants)]="concessoes" />
2136
+ <hm-org-chart label="Organograma" [nodes]="organograma()" [expandDepth]="2" zoomable (nodeSelect)="abrir($event)" />
2137
+ <hm-account-avatar [name]="pessoa.nome" [imageUrl]="pessoa.foto" presence="online" />
2138
+
2139
+ <hm-sign-up-form [policy]="politicaSenha" requireTerms (submitted)="cadastrar($event)" />
2140
+ <hm-passkey-button mode="sign-in" [state]="estadoPasskey()" (activate)="entrarComPasskey()" />
2141
+ <hm-cookie-banner [categories]="categoriasCookies" (saved)="gravarConsentimento($event)" />
2142
+ ```
2143
+ - Seletor de pessoa/equipe/papel/grupo é `hm-entity-picker` (`kind`), não um combobox montado à mão.
2144
+ - A cerimônia WebAuthn (`navigator.credentials`) e o login social são do app; os botões só emitem e mostram o
2145
+ `state` devolvido. Com o login por SSO dos apps, os formulários de conta servem para provedores próprios.
2146
+ - Acesso efetivo (papéis da matriz + política): `effectiveAccess`/`canAccess` (`@trismegisto/primitives`).
2147
+
2148
+ ## 48. Agenda editável, horários, arquivos, relatórios e dev
2149
+
2150
+ ```html
2151
+ <hm-event-calendar label="Agenda da equipe" [events]="eventos()" [(view)]="vista" editable [snapMinutes]="15"
2152
+ (rangeChange)="buscar($event)" (eventChange)="mover($event)" />
2153
+ <hm-recurrence-editor label="Repetir" [(rule)]="regra" [startDate]="inicio" />
2154
+ <hm-slot-picker label="Escolha um horário" [availability]="disponibilidade" [booked]="ocupados()"
2155
+ [duration]="30" (book)="reservar($event)" />
2156
+
2157
+ <hm-file-list label="Arquivos" [files]="arquivos()" [(collection)]="colecao" (open)="abrir($event)"
2158
+ (favoriteChange)="favoritar($event)" />
2159
+ <hm-file-versions label="Versões" [versions]="versoes()" restorable (restore)="restaurar($event)" />
2160
+ <hm-report-history label="Envios" [runs]="execucoes()" (retry)="reenviar($event)" />
2161
+ <hm-api-exchange [request]="req()" [response]="res()" [sensitiveHeaders]="['authorization']" />
2162
+ ```
2163
+ - Evento que se repete: `recurrence` no `CalendarEvent` (regra ou RRULE); a agenda expande as ocorrências.
2164
+ `(eventChange)` traz `kind` (move/resize), `start`, `end`: o app grava e devolve `events`.
2165
+ - `.ics`: `formatICalendar`/`parseICalendar`; horários em comum: `commonFreeRanges` (`@trismegisto/primitives`).
2166
+
2167
+ ## 49. Comércio, pagamento e endereço
2168
+
2169
+ ```html
2170
+ <hm-cart [lines]="linhas()" [discounts]="descontos()" [shipping]="frete()" currency="BRL" showCoupon
2171
+ [couponError]="erroCupom()" (quantityChange)="alterar($event)" (remove)="remover($event)"
2172
+ (applyCoupon)="aplicarCupom($event)" (checkout)="finalizar()" />
2173
+
2174
+ <hm-address-field country="BR" legend="Endereço de entrega" formControlName="entrega"
2175
+ (postalCodeComplete)="buscarCep($event)" />
2176
+
2177
+ <hm-payment-form [amount]="total()" currency="BRL" [methods]="meiosSalvos()" [tokenize]="tokenizar"
2178
+ [maxInstallments]="6" [shippingAddress]="form.value.entrega" (submitted)="pagar($event)" />
2179
+ ```
2180
+ ```ts
2181
+ import type { PostalAddress } from '@trismegisto/primitives';
2182
+ import { formatAddressLines } from '@trismegisto/primitives';
2183
+ // o número do cartão nunca chega ao app: o provedor tokeniza
2184
+ readonly tokenizar: CardTokenizer = (cartao) => this.provedor.criarToken(cartao);
2185
+ pagar(p: PaymentSubmission): void { /* p.token ou p.methodId, p.installments, p.billingAddress */ }
2186
+ const linhas = formatAddressLines(endereco); // exibir/imprimir na convenção do país
2187
+ ```
2188
+ - Endereço é sempre `PostalAddress` + `hm-address-field` (exibição: `hm-address-view`/`hm-address-card`/
2189
+ `hm-address-picker`). Não crie modelo de endereço próprio.
2190
+ - O carrinho não guarda estado: recebe `lines` e emite pedidos; validar estoque e cupom é do app (`couponError`).
2191
+
2192
+ ## 50. Monitoramento, integrações, mapas e entradas especializadas
2193
+
2194
+ ```html
2195
+ <hm-incident-card [incident]="incidente()" (action)="agir($event)" />
2196
+ <hm-alert-rule-editor label="Regra de alerta" [metrics]="metricas" [channels]="canais" [(value)]="regra" (save)="gravar()" />
2197
+ <hm-metric-explorer label="Latência" [metrics]="metricas" [(query)]="consulta" [series]="series()" />
2198
+ <hm-integration-catalog [integrations]="integracoes()" (connect)="conectar($event)" (disconnect)="desconectar($event)" />
2199
+ <hm-sync-status [run]="ultimaSync()" [now]="agora()" (syncNow)="sincronizar()" />
2200
+
2201
+ <hm-map label="Entregas de hoje">
2202
+ <hm-map-cluster>
2203
+ @for (e of entregas(); track e.id) { <hm-map-marker [position]="e.posicao" [label]="e.cliente" /> }
2204
+ </hm-map-cluster>
2205
+ </hm-map>
2206
+ <hm-vehicle-plate-input label="Placa" formControlName="placa" />
2207
+ <hm-identity-document-input label="Documento" [(country)]="pais" formControlName="documento" />
2208
+ ```
2209
+ - Essas peças recebem tudo pronto e só emitem (`action`, `connect`, `syncNow`…); autorização OAuth, rota e imagens
2210
+ do street view vêm do provedor do app. `hm-sync-status` não tem relógio: atualize `now`.
2211
+ - Textos de monitoramento/integrações: input `texts` (parcial), como nas outras peças.
2212
+
2213
+ ## 51. Exemplos integrados (referência de implementação)
2214
+
2215
+ Telas inteiras feitas só com peças da lib, como um app consumidor faria, com dados, estado e cada diálogo em
2216
+ arquivo próprio (site do Trismegisto › Componentes › página do exemplo › aba Código). Antes de montar uma tela
2217
+ dessas áreas, leia o exemplo correspondente:
2218
+
2219
+ | Exemplo | Grupo do site | Mostra |
2220
+ |---|---|---|
2221
+ | Calendar app | Calendário | `hm-event-calendar` com séries e arrastar, convidados, locais com conflito, disponibilidade, horário em comum, `.ics` |
2222
+ | Org chart explorer | Pessoas e acesso | `hm-org-chart` com centenas de pessoas: busca, filtro, zoom, painel de detalhe |
2223
+ | Projects app | Workflow e projetos | tarefas, raias, backlog/sprints, Gantt, carga, aprovações, riscos, SLA, burndown |
2224
+ | Store app | Comércio | vitrine com filtros, produto, carrinho com cupom, checkout, pagamento tokenizado, pedidos, devolução |
2225
+ | Billing app | Pagamentos e finanças | troca de plano com proração, meios de pagamento, faturas, conciliação |
2226
+ | Ops console app | Monitoramento | métricas, alertas que viram incidentes, deploys, manutenção, integrações |
2227
+ | People admin app | Pessoas e acesso | diretório, organograma, papéis e permissões, pedidos de acesso, troca de conta |
2228
+ | Files app | Arquivos | árvore de pastas, grade/lista, envio, visor por tipo, versões, compartilhamento, cota |
2229
+ | 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>`.
@@ -68,7 +68,13 @@ Todos os componentes são **standalone**: importe a classe no `imports` do compo
68
68
  1. **Nenhum valor visual cravado no app.** Cor, espaçamento, raio, sombra, duração e altura de controle vêm de
69
69
  `var(--hm-*)`. Um `#hex` ou um `px` de espaçamento num SCSS de tela é bug: não acompanha tema escuro,
70
70
  família nem densidade. Grupos principais:
71
- - Cor: `--hm-surface`, `--hm-surface-raised`, `--hm-text`, `--hm-muted`, `--hm-border`, `--hm-divider`,
71
+ - Superfícies, por elevação (o que fica por cima clareia nos dois temas):
72
+ `--hm-surface` é o fundo da página (cinza claro no claro, o mais escuro no escuro);
73
+ `--hm-surface-raised` é card, painel, campo e corpo de tabela (branco no claro);
74
+ `--hm-surface-overlay` é o que flutua (menu, popover, modal, drawer, toast);
75
+ `--hm-surface-muted` é o tom de apoio DENTRO de um card (cabeçalho de tabela, código, trilho), não elevação.
76
+ Elemento interno de um card não usa `--hm-surface`: vira um "buraco" com a cor da página.
77
+ - Cor: `--hm-text`, `--hm-muted`, `--hm-border`, `--hm-divider`,
72
78
  `--hm-accent`, `--hm-action`, `--hm-on-action`, `--hm-hover`, `--hm-focus-color`;
73
79
  status: `--hm-{info,success,warning,danger}` e `--hm-{…}-bg`.
74
80
  - Espaço: `--hm-space-{xxxs,nano,micro,xs,sm,md,lg,xl,2xl,3xl}`. Controle: `--hm-control-height{,-dense,-large}`.
@@ -130,6 +136,9 @@ escolha o que o resto do app usa, não misture no mesmo campo:
130
136
  <hm-input label="Busca" [(value)]="term" />
131
137
  ```
132
138
 
139
+ - **Signal Forms** também: `[formField]="meuForm.campo"` (`FormField` e `form()` de `@angular/forms/signals`) em
140
+ qualquer campo `hm-*`, inclusive os de validador próprio (`hm-input type="number"`, moeda/percentual, documento,
141
+ IBAN, placa, `hm-address-field`).
133
142
  - Two-way sem formulário: `[(value)]` em todos, exceto `hm-checkbox` (`[(checked)]`),
134
143
  `hm-combobox-multi` (`[(selected)]`, lista de valores), `hm-file-upload` (`[(files)]`, lista de
135
144
  `UploadFile`) e `hm-reorder-list` (`[(items)]`, a lista na ordem nova). `hm-dual-list` usa `[(value)]`
@@ -141,8 +150,7 @@ escolha o que o resto do app usa, não misture no mesmo campo:
141
150
  - Texto por chave de erro: `[messages]="{ email: 'Informe um e-mail válido.' }"`; sem isso, catálogo da lib.
142
151
  - Desabilitar: `form.disable()`/`control.disable()` ou o input `[disabled]` sem formulário.
143
152
  - Texto de apoio: `hint` em todos (`help` ainda funciona, depreciado).
144
- - `hm-field` virou **`hm-input`** (mesma API). `hm-field` ainda existe na 1.0, **depreciado** e com aviso no
145
- console em desenvolvimento: não use em código novo.
153
+ - `hm-field` virou **`hm-input`** (mesma API); o `hm-field` saiu na 3.3.1.
146
154
  - `[control]="form.controls.x"` (contrato 0.1.x) **foi removido** (depreciado desde 0.2.0): use
147
155
  `[formControl]="form.controls.x"` (com `ReactiveFormsModule`) ou `formControlName="x"`. Só o
148
156
  `hm-settings-section` mantém um `[control]` próprio (o `FormGroup` da seção).
@@ -293,16 +301,60 @@ escolha o que o resto do app usa, não misture no mesmo campo:
293
301
  | Itens que deslizam ao reordenar (lista, kanban, grade) | diretiva `[hmFlip]="lista()"` no contêiner (`hmFlipItems=".cartao"` para itens mais fundos; ou `#f="hmFlip"` + `f.capture()` antes de mudar o estado) |
294
302
  | Bloco que aparece ao rolar (conteúdo editorial) | diretiva `hmReveal` (`[hmRevealDelay]` para escalonar); nunca em formulário/erro. Movimento: tudo respeita `prefers-reduced-motion` sozinho |
295
303
  | Pessoa criar/ajustar uma família de cor do app | `hm-theme-builder` (`baseFamily`, `exportFormats`, `headingLevel`, `(draftChange)`); a regra de contraste em TS: `familyContrastChecks(draftContrastInput(draft))` (`@trismegisto/primitives`). Trocar entre famílias prontas é `hm-theme-picker` |
304
+ | Valor em dinheiro / percentual (campo) | `hm-currency-input` (`currency`, `fractionDigits`; número no modelo, texto no formato do idioma) e `hm-percent-input` (`valueScale` fraction/points) — não `hm-input type="number"` com "R$" no prefixo |
305
+ | Número, dinheiro, %, "há 5 minutos", duração, tamanho de arquivo no template | pipes `hmNumber`, `hmCurrency` (`'BRL'` padrão), `hmPercent` (fração; `'points'` para pontos), `hmRelativeTime` (`{ now }` para envelhecer), `hmDuration` (ms), `hmFileSize`; em TS `formatNumber`/`formatCurrency`/`formatPercent`/`formatRelativeTime`/`formatDuration`/`formatFileSize` (`@trismegisto/primitives`, com o `locale`) |
306
+ | Data com hora / mês de referência / faixa de horário | `hm-datetime-picker` (`interval`, `defaultTime`), `hm-month-picker` (`AAAA-MM`; `valueFormat="first-day"`), `hm-time-range` (`{ start, end }`, `overnight`, `showDuration`) |
307
+ | Escolher um nó de uma hierarquia num formulário | `hm-tree-select` (`nodes: TreeNode[]`, `leavesOnly`, `showPath`, `searchable`, `loadChildren`), múltiplo `hm-tree-select-multi` (`maxChips`); por colunas (país › estado › cidade) `hm-cascader` (`changeOnSelect`) |
308
+ | Lista de erros no topo ao enviar | `hm-form-error-summary [errors]` com `formErrorsFrom(form, rótulos, inject(HERMES_MESSAGES))` no envio (recebe o foco; links levam ao campo) — receitas §41 |
309
+ | Anunciar algo do app ao leitor de tela | `inject(HermesAnnouncer).announce(texto)` (`'assertive'` como 2º argumento só para urgência) ou `[hmAnnounce]`; não crie região `aria-live` própria |
310
+ | "Pular para o conteúdo" | `hm-skip-link` (`target` = id; vazio = o `<main>`) como primeiro item; no spine, `features.skipLink: true` |
311
+ | Avisar ao sair com alterações não salvas | `canDeactivate: [hermesUnsavedChangesGuard]` + `registerUnsavedChanges(() => form.dirty)` na tela; `provideHermesUnsavedChanges({ beforeUnload: true })`; no spine, `features.unsavedChanges` + `registerSpineUnsavedChanges` |
312
+ | Salvando / salvo às 14:32 / falhou | `hm-save-status` (`status` idle/dirty/saving/saved/error, `savedAt`, `retryable` → `(retry)`) |
313
+ | Índice da página com a seção atual | `hm-anchor-nav` (`items`, `sticky`, `offset`, `(activeChange)`) |
314
+ | Confirmar sem modal, ancorado no botão | `hm-popconfirm` (`heading`, `message`, `intent`, `(confirmed)`) + `[hmPopconfirmTrigger]`; destrutivo e irreversível continua `HermesDialogService.confirm` |
315
+ | Ação principal + variações no mesmo botão | `hm-split-button` (`label`, `items: MenuItem[]`, `(clicked)` principal, `(chosen)` variação) |
316
+ | Tour guiado / coachmark | `hm-tour` (`[(open)]`, `steps: TourStep[]` com `target`/`title`/`body`, `(finished)`/`(skipped)`) |
317
+ | Painel de baixo no celular / action sheet | `hm-bottom-sheet` (`[(open)]`, `snapPoints`, `[(snap)]`, `actions` → `(chosen)`); navegação inferior `hm-bottom-navigation` + `hm-bottom-navigation-item` (`hideAbove`) |
318
+ | Progresso circular | `hm-progress shape="circle"` |
319
+ | Mega menu | `hm-navigation-menu-item wide` com colunas `hm-navigation-menu-group` (`label`, `description`) |
320
+ | Editar na tabela | `hm-data-grid editMode="cell"` ou `"row"` + `editor` na coluna (`GridColumnEditor`: `type`, `validate`, `apply`); `(editSaved)` com as mudanças (a grade não grava: devolva `rows`); `editBatch` para salvar em lote; editor próprio `<ng-template hmCellEditor="chave">` — receitas §43 |
321
+ | Linhas com filhos (tree table), cabeçalho em dois níveis, sem zebra | `hm-data-grid` com `treeChildren` (`treeHasChildren` para carga sob demanda; `treePagination="roots"` pagina por raiz, `treeChildPageSize` mostra os filhos aos poucos), `columnGroups`, `[striped]="false"` |
322
+ | Mini gráfico de tendência / meta × realizado / cascata / bolhas | `hm-sparkline-chart` (`data`), `hm-bullet-chart` (`items: BulletItem[]`), `hm-waterfall-chart` (`steps`), `hm-scatter-chart` com `size` nos pontos + `sizeLabel`; medidor `hm-gauge-chart` (`animated`, `needle`, `ticks`) |
323
+ | Tags livres / cor / nota em estrelas (campos) | `hm-tag-input` (`suggestions`, `validate`, `max`), `hm-color-picker` (`swatches`), `hm-rating` (`allowHalf`, `readonly`) |
324
+ | JSON em árvore / logs / galeria / PDF | `hm-json-viewer` (`data`, `expandDepth`, `searchable`), `hm-log-viewer` (`entries: LogEntry[]`, `[(follow)]`, `[(levels)]`), `hm-image-gallery` + `hm-lightbox` (`images: GalleryImage[]`), `hm-pdf-viewer` (`src`, `page`, `zoom`) |
325
+ | Status com transições e motivo | `hm-status-select` (`definition: WorkflowDefinition`, `[(value)]`, `(transition)`; `[apply]="false"` para o app aplicar), `hm-status-badge`, `hm-reason-dialog`, `hm-change-history` |
326
+ | Prioridade, severidade, impacto, risco | `hm-level-badge`/`hm-level-select` (`scale` pronta ou `LevelScale` própria, `allowEmpty`) |
327
+ | Responsável, aprovação, prazo, SLA, execução | `hm-assignee-select` (`people`, `allowUnassigned`), `hm-approval` (`steps`, `(approve)`/`(reject)`), `hm-deadline`, `hm-sla`, `hm-execution-status` |
328
+ | Tarefas, raias, backlog, carga, Gantt, riscos | `hm-task-card`/`hm-task-list`/`hm-task-detail`/`hm-task-editor`, `hm-swimlane-board` (`lanes`, `laneOf`; troca de raia só com `allowLaneChange`), `hm-backlog`, `hm-workload`, `hm-workflow-editor`, `hm-gantt` (`items: GanttItem[]`; arrastar só com `editable` → `(taskChange)`), `hm-risk-register`; burndown = `burndownSeries` + `hm-line-chart` — receitas §46 |
329
+ | Escolher pessoa, equipe, papel, grupo… | `hm-entity-picker` (`entities: PeopleEntity[]`, `kind`, `multiple`) — não um `hm-combobox` com avatar montado à mão |
330
+ | Cartão de pessoa / lista de membros / organograma / permissões | `hm-user-card` (`jobTitle`, `roleName`, `presence`), `hm-member-list`, `hm-org-chart` (`nodes: OrgChartNode[]`), `hm-permission-matrix` (`[(grants)]`), `hm-access-summary`, `hm-access-policy-editor`, `hm-access-request`/`hm-access-request-review` |
331
+ | Cadastro, senha, verificação, passkey, troca de conta, consentimento | `hm-sign-up-form`, `hm-password-strength`, `hm-forgot-password-form`/`hm-new-password-form`, `hm-email-verification`, `hm-social-sign-in`/`hm-passkey-button`/`hm-magic-link-form` (a cerimônia e o provedor são do app), `hm-account-switcher`, `hm-account-closure`, `hm-terms-acceptance`, `hm-consent-preferences`, `hm-cookie-banner` |
332
+ | Presença, menções, reações | `hm-account-avatar presence`, `hm-textarea [mentionCandidates]` + `hm-mention-text`, `hm-message [reactions]` + `[reactionChoices]` → `(reactionToggle)` |
333
+ | Evento que se repete / arrastar evento | `recurrence` no `CalendarEvent` + `hm-recurrence-editor` (`[(rule)]`); `hm-event-calendar editable` → `(eventChange)` (o app grava e devolve `events`) |
334
+ | Horários livres para marcar / disponibilidade / agenda por recurso | `hm-slot-picker` (`availability`, `booked`, `duration` → `(book)`), `hm-availability-editor` (`WeeklyAvailability`), `hm-resource-calendar`, `hm-appointment-details` |
335
+ | Arquivos (recentes, favoritos), versões, permissões, cota | `hm-file-list`, `hm-file-versions`, `hm-file-permissions`, `hm-storage-usage` |
336
+ | Relatório agendado / histórico de envio | `hm-report-schedule` (`[(value)]`), `hm-report-history` (`runs`, `(retry)`) |
337
+ | Requisição e resposta de API / endpoint / feature flags | `hm-api-exchange` (`request`, `response`, `sensitiveHeaders`), `hm-endpoint-card`, `hm-feature-flags` (`flags` → `(toggle)`) |
338
+ | Produto, preço, carrinho, pedido, entrega, devolução | `hm-product-card`/`hm-product-list`/`hm-product-detail`/`hm-variant-picker`, `hm-price` (`amount`, `compareAt`), `hm-stock-status`, `hm-cart` (`lines`, `(quantityChange)`, `(checkout)`), `hm-order-summary`, `hm-order-detail`/`hm-order-status`/`hm-order-timeline`, `hm-shipping-options`, `hm-shipment-tracking`, `hm-return-request` |
339
+ | Meio de pagamento, cartão/IBAN/conta, pagamento, fatura, plano, finanças | `hm-payment-method-picker`, `hm-credit-card-field`, `hm-iban-field`, `hm-bank-account-field`, `hm-payment-form` (`tokenize` do provedor), `hm-transaction-detail`/`hm-transaction-status`/`hm-transaction-timeline`, `hm-payment-history`, `hm-invoice`, `hm-pricing-table`, `hm-plan-picker`, `hm-subscription-card`, `hm-usage-meter`, `hm-financial-summary`, `hm-balance-card`, `hm-budget-variance`, `hm-reconciliation` |
340
+ | Saúde, incidentes, alertas, métricas, trace, deploy, manutenção | `hm-health-status`, `hm-service-status-list`, `hm-uptime-bar`, `hm-sla-summary`, `hm-resource-usage`, `hm-incident-card`/`hm-incident-detail`, `hm-alert-rule-editor`, `hm-alert-history`, `hm-metric-explorer`, `hm-trace-waterfall`, `hm-service-map`, `hm-deploy-pipeline`, `hm-release-timeline`, `hm-environment-picker`, `hm-maintenance-window` |
341
+ | Integrações, conexão, webhooks, sincronização, mapeamento | `hm-integration-catalog`/`hm-integration-card`/`hm-integration-detail`, `hm-connected-account`, `hm-connection-wizard`, `hm-credentials-form`, `hm-database-connection-form`, `hm-connection-test`, `hm-webhook-editor`, `hm-webhook-deliveries`, `hm-sync-status`, `hm-sync-history`, `hm-field-mapping`, `hm-data-source-picker` |
342
+ | Endereço (campo e exibição) | `hm-address-field` (`PostalAddress`; `country`, `requiredFields`, `hiddenFields`, `(postalCodeComplete)` para buscar o CEP) com `hm-location-select`; exibir: `hm-address-view`/`hm-address-card`/`hm-address-picker`; em TS `formatAddressLines` |
343
+ | Placa / documento de outro país | `hm-vehicle-plate-input` (Mercosul e antiga), `hm-identity-document-input` (`[(country)]`, `[(documentType)]`) |
344
+ | Muitos marcadores, rota, street view | `hm-map-cluster` (em volta dos `hm-map-marker`), `hm-map-route` + `hm-route-directions`, `hm-street-view` (`@trismegisto/maps`; rota e imagens vêm do provedor do app) |
345
+ | Agente de IA: conversa, etapas, ferramentas, perguntas, campo de mensagem | `hm-message-scroller` + `hm-message`/`hm-bubble` (`scrollToMessage(id)`), `hm-prompt-input` (`[(value)]`, `attachments`, `models`/`efforts`, `streaming` → `(submitted)`/`(stopped)`/`(filesAdded)`), `hm-questionnaire` (`questions`, `[(answers)]`, `shortcuts` → `(submitted)`; estado em `@trismegisto/primitives/questionnaire`), `hm-trace` + `hm-agent-tool` (`parameters`, `result`, `error`), `hm-tool-confirmation` (aprovação, fora do trace), `hm-reasoning`, `hm-chain-of-thought` + `hm-agent-search-results`, `hm-agent-plan`/`hm-agent-task`/`hm-agent-queue`/`hm-subagent`, `hm-agent-sources`/`hm-inline-citation`, `hm-context-usage`, `hm-model-selector`, `hm-checkpoint`, `hm-file-tree`, `hm-agent-terminal`, `hm-test-results`, `hm-stack-trace`, `hm-prompt-suggestions` |
296
346
 
297
347
  Inputs exatos de cada um: `angular-api.md`.
298
348
 
299
349
  ## 5. Quando não existe componente
300
350
 
301
- Hoje não há peça genérica conhecida faltando. **Não invente** um `hm-*` que não esteja em `angular-api.md`
302
- (ou, para mapas e gráficos, nos pacotes `@trismegisto/maps`/`@trismegisto/charts`): o build quebra.
351
+ **Não invente** um `hm-*` que não esteja em `angular-api.md` (ou, para mapas e gráficos, nos pacotes
352
+ `@trismegisto/maps`/`@trismegisto/charts`): o build quebra. Antes de compor, confira as famílias de domínio genérico
353
+ (workflow, pessoas, comércio, pagamentos, monitoramento, integrações… — SKILL.md §6 e as linhas acima): muita tela
354
+ "de negócio" já tem peça.
303
355
 
304
- Se a peça de que você precisa não está no catálogo (por exemplo, algo de domínio do app, como a marca ou um
305
- cartão de negócio), componha com os `hm-*` existentes e as classes utilitárias do `@trismegisto/core`; só crie
356
+ Se a peça de que você precisa não está no catálogo (algo específico do app, como a marca ou um cartão com regra
357
+ de negócio própria), componha com os `hm-*` existentes e as classes utilitárias do `@trismegisto/core`; só crie
306
358
  HTML/CSS próprio quando nem isso resolver.
307
359
 
308
360
  Ao criar algo local assim: use apenas tokens, mantenha acessível (rótulo, foco visível, teclado) e marque com
@@ -324,9 +376,14 @@ Esta skill descreve a 2.0.0. Ao migrar código de uma 0.x:
324
376
  - ilustrações `hm-illustration-file-upload`, `hm-illustration-file-transfer`, `hm-illustration-message` e as
325
377
  situações `uploading`, `transfer` e `message` do `hm-state-screen` → use outra situação (ex.: `empty`) ou
326
378
  projete outro desenho no slot `[illustration]`.
327
- - **Depreciados** (ainda funcionam, com aviso em desenvolvimento; não use em código novo): `hm-field` → `hm-input`;
328
- `help` → `hint`; `busy` → `loading` (botão); `hm-tag color="error"` → `"danger"`; `[startControl]`/`[endControl]`
329
- e `start`/`end` do `hm-date-range-picker` → valor `DateRange`; `STATE_PAGE_PRESETS` (fixo em pt-BR) → `statePagePreset(kind, messages)`.
379
+ - **Removidos na 3.3.1**: `hm-field` → `hm-input`; `STATE_PAGE_PRESETS` → `statePagePreset(kind, messages)`;
380
+ `provideHermesMessages` → `provideHermesI18n`; `[requiredManual]` do `hm-combobox` → `required`; `help` do
381
+ `hm-combobox-multi` → `hint`; `[(start)]`/`[(end)]` do `hm-date-range-picker` → `[(value)]` com `DateRange`;
382
+ `HermesSidebarService.doc` → `inject(DOCUMENT)`. `hm-session-recovery` sem `allowedOrigins` só aceita a mesma
383
+ origem.
384
+ - **Depreciados** (ainda funcionam, com aviso em desenvolvimento; não use em código novo): `help` → `hint`
385
+ (`hm-combobox`, `hm-textarea`, `hm-radio`, `hm-switch`); `busy` → `loading` (botão); `hm-tag color="error"` →
386
+ `"danger"`; `[startControl]`/`[endControl]` do `hm-date-range-picker` → valor `DateRange`.
330
387
  `angular-api.md` marca cada item depreciado.
331
388
  - **Ilustrações** e páginas de estado (`hm-state-page`, inclusive `outdated`): `../SKILL.md` §5.
332
389
 
@@ -113,6 +113,7 @@
113
113
  "bookmark-element",
114
114
  "box-open",
115
115
  "box-plot",
116
+ "breadcrumbs",
116
117
  "briefcase",
117
118
  "briefcase-bag",
118
119
  "browser-click",
@@ -260,6 +261,7 @@
260
261
  "container",
261
262
  "container-group",
262
263
  "container-volume",
264
+ "content-placeholder",
263
265
  "contract",
264
266
  "control-lun",
265
267
  "copy",
@@ -530,6 +532,7 @@
530
532
  "list",
531
533
  "list-bullets",
532
534
  "list-check",
535
+ "loading-ring",
533
536
  "lock",
534
537
  "lock-close",
535
538
  "lock-open",
@@ -604,6 +607,8 @@
604
607
  "outdent",
605
608
  "paint-roller",
606
609
  "palmTree",
610
+ "panel-center",
611
+ "panel-split",
607
612
  "paper-detached",
608
613
  "paperclip",
609
614
  "passport",
@@ -766,6 +771,7 @@
766
771
  "star-fill",
767
772
  "step-forward",
768
773
  "step-forward-2",
774
+ "step-progress",
769
775
  "stop",
770
776
  "storage",
771
777
  "storage-adapter",
@@ -788,6 +794,7 @@
788
794
  "switch",
789
795
  "sync",
790
796
  "t-square",
797
+ "tab-panel",
791
798
  "table",
792
799
  "table-edit",
793
800
  "table-pen",