@acropole/skills 0.0.0-stage → 1.0.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 (90) hide show
  1. package/README.md +180 -2
  2. package/agents/revisor-deploy.md +73 -0
  3. package/agents/revisor-documentacao.md +78 -0
  4. package/agents/revisor-orfeu.md +80 -0
  5. package/agents/revisor-trismegisto.md +81 -0
  6. package/bin/install.js +252 -0
  7. package/package.json +15 -4
  8. package/skills/acropole/SKILL.md +75 -0
  9. package/skills/acropole/references/fluxos/doctor.md +55 -0
  10. package/skills/acropole/references/fluxos/endpoint-novo.md +22 -0
  11. package/skills/acropole/references/fluxos/revisar.md +56 -0
  12. package/skills/acropole/references/fluxos/tela-nova.md +27 -0
  13. package/skills/acropole/scripts/doctor.mjs +439 -0
  14. package/skills/angular/SKILL.md +152 -0
  15. package/skills/angular/references/armadilhas.md +95 -0
  16. package/skills/angular/references/dados.md +251 -0
  17. package/skills/angular/references/estrutura.md +260 -0
  18. package/skills/angular/references/features.md +219 -0
  19. package/skills/angular/references/testes-build.md +230 -0
  20. package/skills/angular/scripts/checar.mjs +182 -0
  21. package/skills/angular/scripts/nucleo.mjs +227 -0
  22. package/skills/apollo/SKILL.md +222 -0
  23. package/skills/apollo/references/armadilhas.md +95 -0
  24. package/skills/apollo/references/envelope-erros.md +120 -0
  25. package/skills/apollo/references/estrutura-bootstrap.md +299 -0
  26. package/skills/apollo/references/schema-resolvers.md +183 -0
  27. package/skills/apollo/references/subscriptions.md +224 -0
  28. package/skills/apollo/references/testes-build.md +180 -0
  29. package/skills/apollo/scripts/checar.mjs +160 -0
  30. package/skills/apollo/scripts/nucleo.mjs +227 -0
  31. package/skills/docker/SKILL.md +102 -0
  32. package/skills/docker/references/modelos.md +251 -0
  33. package/skills/docker/references/porques.md +282 -0
  34. package/skills/documentacao/SKILL.md +146 -0
  35. package/skills/documentacao/references/checklist-coerencia.md +59 -0
  36. package/skills/documentacao/references/ligar-app-novo.md +107 -0
  37. package/skills/documentacao/references/modelo-especificacao.md +51 -0
  38. package/skills/documentacao/references/modelo-readme.md +75 -0
  39. package/skills/documentacao/scripts/checar.mjs +454 -0
  40. package/skills/documentacao/scripts/nucleo.mjs +227 -0
  41. package/skills/express/SKILL.md +154 -0
  42. package/skills/express/references/dados.md +180 -0
  43. package/skills/express/references/estrutura.md +154 -0
  44. package/skills/express/references/middlewares.md +227 -0
  45. package/skills/express/references/rotas-erros.md +274 -0
  46. package/skills/express/references/testes-deploy.md +150 -0
  47. package/skills/express/scripts/checar.mjs +115 -0
  48. package/skills/express/scripts/nucleo.mjs +227 -0
  49. package/skills/fastapi/SKILL.md +129 -0
  50. package/skills/fastapi/references/banco.md +185 -0
  51. package/skills/fastapi/references/estrutura.md +281 -0
  52. package/skills/fastapi/references/integracoes.md +145 -0
  53. package/skills/fastapi/references/rotas-erros.md +140 -0
  54. package/skills/fastapi/references/testes-deploy.md +190 -0
  55. package/skills/fastapi/scripts/checar.mjs +108 -0
  56. package/skills/fastapi/scripts/nucleo.mjs +227 -0
  57. package/skills/hefesto/SKILL.md +119 -0
  58. package/skills/hefesto/references/conceitos.md +131 -0
  59. package/skills/hefesto/references/diagnostico.md +70 -0
  60. package/skills/hefesto/references/fluxo.md +122 -0
  61. package/skills/hefesto/references/preparar-app.md +105 -0
  62. package/skills/orfeu/SKILL.md +162 -0
  63. package/skills/orfeu/references/angular-api.md +201 -0
  64. package/skills/orfeu/references/angular-armadilhas.md +116 -0
  65. package/skills/orfeu/references/angular-recipes.md +474 -0
  66. package/skills/orfeu/references/angular.md +212 -0
  67. package/skills/orfeu/references/diferencas.md +56 -0
  68. package/skills/orfeu/references/node-api.md +348 -0
  69. package/skills/orfeu/references/node-armadilhas.md +158 -0
  70. package/skills/orfeu/references/node-recipes.md +534 -0
  71. package/skills/orfeu/references/node.md +204 -0
  72. package/skills/orfeu/references/python-api.md +346 -0
  73. package/skills/orfeu/references/python-recipes.md +479 -0
  74. package/skills/orfeu/references/python.md +234 -0
  75. package/skills/orfeu/scripts/checar.mjs +126 -0
  76. package/skills/orfeu/scripts/nucleo.mjs +227 -0
  77. package/skills/trismegisto/SKILL.md +194 -0
  78. package/skills/trismegisto/references/angular-api.md +2788 -0
  79. package/skills/trismegisto/references/angular-exports.md +4020 -0
  80. package/skills/trismegisto/references/angular-recipes.md +1883 -0
  81. package/skills/trismegisto/references/angular-types.md +492 -0
  82. package/skills/trismegisto/references/angular.md +390 -0
  83. package/skills/trismegisto/references/catalogo/icones.json +912 -0
  84. package/skills/trismegisto/references/catalogo/seletores.json +7013 -0
  85. package/skills/trismegisto/references/catalogo/tokens.json +240 -0
  86. package/skills/trismegisto/references/spine-api.md +1530 -0
  87. package/skills/trismegisto/references/spine-recipes.md +581 -0
  88. package/skills/trismegisto/references/spine.md +343 -0
  89. package/skills/trismegisto/scripts/checar.mjs +216 -0
  90. package/skills/trismegisto/scripts/nucleo.mjs +227 -0
@@ -0,0 +1,492 @@
1
+ # Tipos públicos — @trismegisto/angular 1.0
2
+
3
+ Guia comentado dos tipos de dados mais usados. Todos importáveis de `@trismegisto/angular` (vários são
4
+ reexportados de `@trismegisto/primitives`), salvo onde indicado. A lista **completa** e exata de cada ponto de
5
+ import — com a declaração de todo tipo, interface, função, constante e serviço — é gerada a cada build em
6
+ `angular-exports.md`; em caso de divergência, vale o `angular-exports.md`.
7
+
8
+ ## Valores enumerados
9
+
10
+ ```ts
11
+ type ButtonEmphasis = 'high' | 'medium' | 'minimal';
12
+ type ButtonIntent = 'primary' | 'success' | 'warning' | 'danger';
13
+ type ButtonSize = 'small' | 'medium' | 'large';
14
+ type IconButtonEmphasis = 'filled' | 'outlined' | 'subtle';
15
+ type AlertVariant = 'error' | 'warning' | 'info' | 'success'; // também é o ToastVariant
16
+ type BadgeIntent = 'primary' | 'success' | 'warning' | 'danger';
17
+ type TagColor = 'primary' | 'info' | 'success' | 'warning' | 'danger' | 'neutral' | 'error'; // 'error' depreciado → 'danger'
18
+ type ModalSize = 'small' | 'medium' | 'large' | 'xlarge' | 'full'; // hm-modal, hm-drawer, hm-wizard; full = tela cheia
19
+ type IconSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | number | string;
20
+ type IconStatus = 'info' | 'success' | 'warning' | 'danger' | 'neutral';
21
+ type PopoverSide = 'top' | 'bottom' | 'left' | 'right';
22
+ type PopoverAlign = 'start' | 'center' | 'end';
23
+ type SkeletonShape = 'text' | 'list' | 'card' | 'cards';
24
+ type StateScreenSituation = 'empty' | 'success' | 'error' | 'attention' | 'done' | 'locked' | 'unlocked'
25
+ | 'forbidden' | 'not-found' | 'session-expired';
26
+ type DateValueFormat = 'iso' | 'dd/mm/yyyy';
27
+ type HermesThemeMode = 'light' | 'dark' | 'system';
28
+ type HermesDensity = 'comfortable' | 'compact';
29
+ type TreeSelectionMode = 'none' | 'single' | 'multiple'; // hm-tree [selectionMode]
30
+ type SplitterOrientation = 'horizontal' | 'vertical'; // arranjo dos PAINÉIS (horizontal = lado a lado)
31
+ type ChipVariant = 'outlined' | 'filled'; type ChipSize = 'small' | 'medium';
32
+ type CopyButtonVariant = 'icon' | 'text';
33
+ type SearchFieldSize = 'small' | 'medium' | 'large';
34
+ type PageHeaderLevel = 1 | 2 | 3 | 4 | 5 | 6;
35
+ type DividerOrientation = 'horizontal' | 'vertical';
36
+ type DividerEmphasis = 'subtle' | 'strong'; type DividerThickness = 'hairline' | 'thin';
37
+ type DividerSpacing = 'none' | 'small' | 'medium' | 'large'; type DividerLabelAlign = 'start' | 'center' | 'end';
38
+ type DescriptionListLabelPosition = 'top' | 'start'; type DescriptionListVariant = 'plain' | 'outlined';
39
+ type LegendIntent = 'accent' | 'success' | 'warning' | 'danger' | 'info' | 'neutral';
40
+ type LegendOrientation = 'horizontal' | 'vertical'; type LegendMarker = 'dot' | 'square' | 'line';
41
+ type FileUploadSize = 'small' | 'medium' | 'large'; // altura da área de soltar
42
+ type FileUploadStatus = 'pending' | 'uploading' | 'done' | 'error';
43
+ type FileRejectionReason = 'type' | 'size' | 'totalSize' | 'count' | 'duplicate';
44
+ type StepperOrientation = 'horizontal' | 'vertical'; // hm-stepper / hm-wizard
45
+ type WizardMode = 'modal' | 'page';
46
+ type TimelineOrientation = 'vertical' | 'horizontal';
47
+ type TimelineStatus = 'completed' | 'current' | 'pending' | 'error';
48
+ type TimelineOutcome = 'running' | 'completed' | 'failed'; // hm-timeline [outcome]
49
+ type AvatarGroupSize = 'small' | 'medium' | 'large';
50
+ type DualListSize = 'small' | 'medium' | 'large'; type ReorderListSize = 'small' | 'medium' | 'large';
51
+ type ShortcutAction = 'auto' | 'click' | 'focus' | 'none'; // [hmShortcutAction]; auto = foca campo, clica no resto
52
+ type ShortcutPlatform = 'mac' | 'other';
53
+ type DataGridExportFormat = 'csv' | 'excel'; // excel = CSV com BOM UTF-8 e separador do idioma
54
+ type DataGridPersistStorage = 'local' | 'session';
55
+ ```
56
+
57
+ Vocabulário de status: `'danger'` em botão, badge, ícone, progresso, legenda e tag (`'error'` na tag
58
+ continua aceito, depreciado, com aviso no console em dev). O alerta/toast (`AlertVariant`) segue com `'error'`.
59
+
60
+ ## Menu
61
+
62
+ ```ts
63
+ interface MenuItem {
64
+ readonly id: string; // único: é o valor emitido em (chosen) e a chave do @for
65
+ readonly label: string;
66
+ readonly icon?: string;
67
+ readonly shortcut?: string; // só exibição, não registra a tecla
68
+ readonly disabled?: boolean;
69
+ readonly danger?: boolean;
70
+ readonly separatorAbove?: boolean;
71
+ readonly groupTitle?: string;
72
+ readonly children?: readonly MenuItem[]; // submenu, um nível
73
+ readonly type?: MenuItemType; // 'checkbox' | 'radio' — item marcável (menuitemcheckbox/menuitemradio)
74
+ readonly checked?: boolean;
75
+ readonly group?: string; // rádio: itens do mesmo grupo se excluem
76
+ readonly value?: string; // rádio: valor (padrão: o id)
77
+ }
78
+
79
+ interface MenuItemChange { // (checkedChange) de hm-menu, hm-menu-button, hm-menubar
80
+ readonly id: string; readonly type: MenuItemType; readonly checked: boolean;
81
+ readonly group?: string; readonly value?: string;
82
+ }
83
+ // applyMenuItemChange(items, change) → nova lista; menuRadioValue(items, group) → valor marcado ou null
84
+
85
+ interface MenubarMenu { readonly id: string; readonly label: string; readonly items: readonly MenuItem[]; readonly disabled?: boolean }
86
+
87
+ interface PopoverAnchor { // para hm-menu posicionado à mão
88
+ readonly x: number; readonly y: number;
89
+ readonly right?: number; readonly bottom?: number; // com os dois, vira pop-over ancorado no gatilho
90
+ readonly side?: PopoverSide; readonly align?: PopoverAlign;
91
+ }
92
+ ```
93
+
94
+ Menu de contexto: `[hmContextMenu]="items"` recebe os mesmos `MenuItem[]` e emite o `id` em `(chosen)`.
95
+
96
+ ## Data grid
97
+
98
+ ```ts
99
+ interface GridColumn<T> { // alias: DataGridColumn<T>
100
+ readonly key: string; // também é o nome do template de célula: <ng-template hmCell="key">
101
+ readonly title: string;
102
+ readonly value: (row: T) => string; // texto exibido, buscado e filtrado
103
+ readonly raw?: (row: T) => unknown; // valor para ordenar (ex.: número cru)
104
+ readonly type?: 'text' | 'number' | 'date' | 'boolean';
105
+ readonly sortable?: boolean;
106
+ readonly filterable?: boolean; // padrão true
107
+ readonly searchable?: boolean; // padrão: colunas de texto
108
+ readonly align?: 'start' | 'end';
109
+ readonly initialWidth?: string; // comprimento CSS
110
+ readonly hideable?: boolean; // padrão true
111
+ readonly hidden?: boolean;
112
+ readonly exportable?: boolean; // entra no CSV exportado; padrão true (desligue em colunas só visuais)
113
+ readonly pinned?: 'start' | 'end'; // coluna fixa ao rolar de lado (a pessoa muda pelo columnManager)
114
+ }
115
+
116
+ interface DataGridRowAction<T> {
117
+ readonly id: string; readonly icon: string; readonly label: string;
118
+ readonly danger?: boolean; readonly separatorAbove?: boolean;
119
+ readonly available?: (row: T) => boolean;
120
+ }
121
+
122
+ interface DataGridActionTriggered<T> { readonly action: string; readonly row: T; }
123
+ interface GridSort { readonly key: string; readonly direction: SortDirection; }
124
+ type GridSelection = ReadonlySet<string>; // ids vindos de [rowId]
125
+ interface PaginationState { readonly page: number; readonly size: number; } // page começa em 1
126
+ ```
127
+
128
+ Paginação no servidor: passe `[totalItems]` e reaja a `[(pageState)]`/`[(sort)]` buscando a página; `rows` passa
129
+ a ser só a página atual.
130
+
131
+ ### Recursos avançados do data grid
132
+
133
+ Tudo abaixo sai de `@trismegisto/angular` (os tipos de agregação e do filtro composto são definidos em
134
+ `@trismegisto/primitives` e reexportados na raiz).
135
+
136
+ ```ts
137
+ interface DataGridExportOptions {
138
+ readonly format?: DataGridExportFormat; // padrão 'csv'
139
+ readonly fileName?: string; // sem extensão; padrão: exportFileName ou o caption
140
+ readonly download?: boolean; // false = só devolve o texto. Padrão true
141
+ }
142
+ // grid.exportCsv(options?): string · grid.clearPersistedState(): void
143
+
144
+ type GridAggregateFn = 'sum' | 'avg' | 'min' | 'max' | 'count';
145
+ type GridAggregates = Readonly<Record<string, GridAggregateFn>>; // [aggregates]="{ total: 'sum' }"
146
+ type GridAggregateFormatter = (value: number, fn: GridAggregateFn, key: string) => string;
147
+
148
+ type GridFilterOperator = 'contains' | 'equals' | 'notEquals' | 'startsWith'
149
+ | 'greaterThan' | 'lessThan' | 'between' | 'before' | 'after';
150
+ type GridFilterConnector = 'and' | 'or';
151
+ interface GridFilterCondition {
152
+ readonly id: string; // identidade estável (chip, track)
153
+ readonly column: string; // key da coluna
154
+ readonly operator: GridFilterOperator;
155
+ readonly value: string; // texto: número com '.', data 'AAAA-MM-DD'
156
+ readonly valueTo?: string; // só em 'between'
157
+ }
158
+ interface GridFilterQuery { readonly connector: GridFilterConnector; readonly conditions: readonly GridFilterCondition[]; }
159
+ const EMPTY_GRID_QUERY: GridFilterQuery; // { connector: 'and', conditions: [] }
160
+ ```
161
+
162
+ Operadores por tipo de coluna (o 1º é o padrão de uma condição nova): texto `contains`, `equals`,
163
+ `startsWith`, `notEquals`; número `equals`, `notEquals`, `greaterThan`, `lessThan`, `between`; data
164
+ `before`, `after`, `between`, `equals`; booleano `equals`. `filterQuery` é serializável (vai inteiro para
165
+ a persistência e serve para mandar ao backend).
166
+
167
+ `persistKey` grava ordenação, filtros (inclusive `filterQuery`), colunas (visibilidade, largura, ordem) e
168
+ itens por página na chave `<storagePrefix>_grid_<persistKey>` — o mesmo `storagePrefix` do
169
+ `HERMES_THEME_CONFIG`.
170
+
171
+ ## Navegação
172
+
173
+ ```ts
174
+ interface SidebarNode {
175
+ id: string;
176
+ label: string;
177
+ icon?: string;
178
+ route: string | readonly unknown[];
179
+ children?: readonly SidebarNode[];
180
+ hidden?: boolean;
181
+ }
182
+
183
+ interface TabItem { // hm-tab-bar / hm-workspace
184
+ readonly id: string; readonly label: string; readonly icon?: string;
185
+ readonly pinned?: boolean; // sem botão de fechar
186
+ }
187
+
188
+ interface BreadcrumbItem { // hm-breadcrumb [items], hm-page-header [breadcrumb]
189
+ readonly label: string;
190
+ readonly routerLink?: string | readonly unknown[];
191
+ readonly queryParams?: Readonly<Record<string, string>>;
192
+ readonly href?: string;
193
+ readonly target?: string;
194
+ readonly icon?: string; // decorativo
195
+ }
196
+
197
+ interface TreeNode { // hm-tree
198
+ readonly id: string;
199
+ readonly label: string;
200
+ readonly leaf?: boolean;
201
+ readonly children?: readonly TreeNode[];
202
+ readonly expandable?: boolean; // filhos carregados sob demanda via [loadChildren]
203
+ readonly disabled?: boolean;
204
+ readonly icon?: string;
205
+ readonly link?: string; // vira nó de navegação
206
+ readonly data?: unknown; // carga livre, lida em <ng-template hmTreeNode>
207
+ }
208
+
209
+ interface TreeSelectionChange { readonly id: string; readonly selected: boolean; } // (changed), modo de caixas
210
+
211
+ // [loadChildren]: lista inteira (forma antiga) ou página; com hasMore aparece "Carregar mais" no fim dos filhos.
212
+ // Falha (Promise rejeitada/erro no Observable) = erro no nó com "Tentar de novo" (o nó continua aberto).
213
+ type TreeChildrenLoader = (node: TreeNode, context: { offset: number; page: number })
214
+ => Promise<TreeChildrenResult> | Observable<TreeChildrenResult>;
215
+ type TreeChildrenResult = readonly TreeNode[] | { readonly children: readonly TreeNode[]; readonly hasMore?: boolean };
216
+ // [(selection)] em selectionMode 'single'/'multiple': ReadonlySet<string> (ids dos nós)
217
+ ```
218
+
219
+ ## Opções de formulário
220
+
221
+ ```ts
222
+ interface ComboboxOption { // hm-combobox, hm-combobox-multi
223
+ readonly value: string; readonly label: string;
224
+ readonly disabled?: boolean; readonly icon?: string;
225
+ readonly swatchBackground?: string; readonly swatchBorder?: string;
226
+ }
227
+
228
+ interface FilterBarField { // hm-filter-bar
229
+ readonly key: string; readonly label: string;
230
+ readonly type: 'text' | 'select' | 'multiselect' | 'date-range' | 'boolean';
231
+ readonly options?: readonly ComboboxOption[]; readonly placeholder?: string;
232
+ }
233
+ // FilterBarValue = { [key]: string | string[] | DateRange | boolean } — só os campos ativos
234
+ interface SavedFilter { readonly id: string; readonly name: string; readonly value: FilterBarValue; readonly isDefault?: boolean; }
235
+ interface FilterBarStorage { // [storage] do hm-filter-bar; síncrono ou Promise
236
+ get(key: string): readonly SavedFilter[] | null | Promise<readonly SavedFilter[] | null>;
237
+ set(key: string, filters: readonly SavedFilter[]): void | Promise<void>;
238
+ }
239
+
240
+ interface RadioOption { // hm-radio
241
+ readonly value: string; readonly label: string;
242
+ readonly description?: string; // uma linha explicando a consequência da escolha
243
+ readonly icon?: string; // decorativo, antes do rótulo
244
+ readonly danger?: boolean; // destrutiva: cor + ícone de alerta + "ação destrutiva" (leitor de tela)
245
+ readonly disabled?: boolean; // só esta opção
246
+ readonly disabledReason?: string; // desabilita e mostra o motivo (aria-describedby)
247
+ }
248
+ // <hm-radio appearance="card"> = cada opção num cartão (ícone, título, descrição); padrão 'list'
249
+ type RadioLayout = 'stacked' | 'inline'; // inline = lado a lado, quebra linha em tela estreita
250
+
251
+ interface CheckboxGroupOption { // hm-checkbox-group (valor string[], na ordem das opções)
252
+ readonly value: string; readonly label: string;
253
+ readonly description?: string; // aria-describedby da caixa
254
+ readonly disabled?: boolean;
255
+ }
256
+ type CheckboxGroupLayout = 'stacked' | 'inline';
257
+
258
+ interface SegmentedOption<T extends string = string> {
259
+ value: T; label: string; icon?: string; disabled?: boolean;
260
+ }
261
+ ```
262
+
263
+ ## hm-input
264
+
265
+ ```ts
266
+ type InputType = 'text' | 'email' | 'tel' | 'url' | 'number' | 'search' | 'password';
267
+ type InputValue = string | number | null; // number (vazio = null) quando type="number"
268
+ type InputMaskValue = 'raw' | 'masked'; // raw (padrão): '12345678901'; masked: '123.456.789-01'
269
+ type InputMode = 'none' | 'text' | 'decimal' | 'numeric' | 'tel' | 'search' | 'email' | 'url';
270
+ ```
271
+
272
+ Máscaras — de `@trismegisto/primitives` (não reexportadas por `@trismegisto/angular`):
273
+
274
+ ```ts
275
+ type MaskPreset = 'cpf' | 'cnpj' | 'cep' | 'phone'; // cnpj alfanumérico; phone fixo ou celular pelo nº de dígitos
276
+ type HermesMask = MaskPreset | string; // padrão: 9 = dígito, A = letra, * = letra ou dígito, \ escapa
277
+ applyMask('12345678901', 'cpf'); // '123.456.789-01'
278
+ unmask('123.456.789-01', 'cpf'); // '12345678901'
279
+ isMaskComplete('123.456', 'cpf'); // false — use num validator para "preenchido por inteiro"
280
+ conformMask(text, caret, mask, { previous?, deleteBackward? }); // { masked, raw, caret } — para <input> próprio
281
+ ```
282
+
283
+ ## Leitura e legenda
284
+
285
+ ```ts
286
+ interface DescriptionListItem { // hm-description-list [items]
287
+ readonly term: string;
288
+ readonly value?: string | number | null; // null/undefined/'' mostram "—" ("Não informado" no leitor)
289
+ readonly fullWidth?: boolean;
290
+ readonly children?: readonly DescriptionListItem[]; // com filhos = bloco expansível (botão aria-expanded no termo)
291
+ readonly expanded?: boolean; // bloco começa aberto; depois, abrir/fechar é estado da lista
292
+ readonly editable?: boolean; // edição inline: Enter/blur salva, Esc cancela → (valueChange)
293
+ }
294
+
295
+ interface DescriptionListValueChange { // hm-description-list (valueChange), só itens por [items]
296
+ readonly item: DescriptionListItem; // o mesmo objeto recebido
297
+ readonly path: readonly number[]; // [2, 0] = primeiro filho do terceiro par
298
+ readonly value: string; // texto digitado — atualize o seu items
299
+ }
300
+ // Composição: <hm-description-item term="Rede" [(expanded)]="aberto"> com itens filhos dentro;
301
+ // <hm-description-item term="IP" [(value)]="ip" [editable]="true" />.
302
+
303
+ interface LegendItem { // hm-legend [items]
304
+ readonly label: string; // o significado, sempre visível
305
+ readonly intent?: LegendIntent;
306
+ readonly color?: string; // cor de série (de preferência um token); vence intent
307
+ readonly value?: string | number;
308
+ readonly description?: string;
309
+ }
310
+ ```
311
+
312
+ ## Feedback
313
+
314
+ ```ts
315
+ // HermesToastService (injetável, providedIn root; exige <hm-toast-stack /> no shell)
316
+ success(message: string, options?: ToastPushOptions): void;
317
+ error(...), warning(...), info(...);
318
+ push(variant: AlertVariant, message: string, options?: ToastPushOptions): void;
319
+ dismiss(id: string): void;
320
+
321
+ interface ToastPushOptions {
322
+ readonly title?: string;
323
+ readonly duration?: number; // ms; com action e sem duration, fica ao menos 10 s
324
+ readonly action?: ToastAction; // botão no cartão (ex.: "Desfazer")
325
+ }
326
+ interface ToastAction { readonly label: string; readonly run: () => void; }
327
+
328
+ interface CarouselSlide { readonly title: string; readonly text: string; readonly image: string; readonly alt: string; }
329
+ ```
330
+
331
+ Diálogo:
332
+
333
+ ```ts
334
+ // hm-modal
335
+ beforeClose: (() => boolean | Promise<boolean>) | null; // false segura o X/Esc/fundo; não vale para [(open)] mudado por código
336
+
337
+ interface HermesConfirmOptions { // HermesDialogService.confirm e hm-wizard [confirmCancel] (objeto parcial)
338
+ readonly heading: string; readonly message: string;
339
+ readonly confirmLabel?: string; readonly cancelLabel?: string; readonly danger?: boolean;
340
+ }
341
+ ```
342
+
343
+ ## Envio de arquivos (hm-file-upload)
344
+
345
+ ```ts
346
+ interface UploadFile<F = File> { // um item de [(files)] — imutável
347
+ readonly id: string;
348
+ readonly file: F;
349
+ readonly status: FileUploadStatus;
350
+ readonly progress: number; // 0–100 (em 'uploading')
351
+ readonly error?: string; // texto pronto para a tela, em 'error'
352
+ }
353
+ type UploadFilePatch = Partial<Pick<UploadFile, 'status' | 'progress' | 'error'>>; // fileUpload.update(id, patch)
354
+ interface FileRejection<F = File> { readonly file: F; readonly reason: FileRejectionReason; } // (rejected)
355
+
356
+ /** Envio delegado ao componente ([uploader]): resolver = enviado; rejeitar = falha (Error.message vira o texto). */
357
+ type FileUploader = (file: File, report: (progress: number) => void, signal: AbortSignal) => Promise<unknown>;
358
+ ```
359
+
360
+ Métodos públicos (via `viewChild(FileUploadComponent)`): `addFiles(files)`, `update(id, patch)`, `remove(id)`,
361
+ `retry(id)`. Outputs: `added: UploadFile[]`, `rejected: FileRejection[]`, `removed: UploadFile`, `retried: UploadFile`
362
+ (sem `uploader`, o app reenvia). `remove` durante o envio aborta o `signal`.
363
+ Sem componente: `validateFiles`, `formatFileSize`, `describeAccept`, `patchUploadFile` em `@trismegisto/primitives`.
364
+
365
+ ## Etapas (hm-stepper, hm-step, hm-wizard)
366
+
367
+ ```ts
368
+ type HermesStepGuard = () => boolean | Promise<boolean>; // hm-step [canAdvance]: regra que não cabe num formulário
369
+
370
+ interface HermesStepSummaryEntry { readonly term: string; readonly value?: string | number | null; }
371
+ // hm-step [summary]: template ou função lida na hora em que a revisão aparece (valor atual do formulário)
372
+ type HermesStepSummary = TemplateRef<unknown> | (() => readonly HermesStepSummaryEntry[]);
373
+ ```
374
+
375
+ `hm-wizard [summary]="true"`: acrescenta a etapa final "Revisão" (`summaryLabel`, `summaryDescription`) com uma seção
376
+ por `hm-step` que tenha `summary` (função → `hm-description-list`; template → livre) e um "Editar {etapa}" que volta
377
+ a ela. O Concluir passa para a revisão. Sem nenhuma etapa com `summary`, a página não aparece. Não escreva uma etapa
378
+ "Revisão" à mão.
379
+
380
+ `hm-step`: `label`, `description`, `optional`, `disabled`, `error` (forçar erro, ex.: recusa do servidor),
381
+ `completed` (`boolean | null`), `stepControl` (`AbstractControl` — inválido ao avançar marca tudo como tocado),
382
+ `canAdvance`. Validação só bloqueia no modo `linear` e nunca em etapa `optional`. Conteúdo de etapa fechada não
383
+ é destruído (o formulário mantém o que foi digitado).
384
+
385
+ `hm-stepper` (público, por `viewChild`): `next(): Promise<boolean>`, `previous()`, `goTo(i): Promise<boolean>`,
386
+ `complete(): Promise<boolean>`, `reset()`; signals `current`, `isFirst`, `isLast`, `validating`.
387
+ Situação de etapa em `@trismegisto/primitives`: `type StepStatus = 'pending' | 'current' | 'completed' | 'error' | 'disabled'`.
388
+
389
+ ## Diálogo de configurações em modo formulário (hm-settings-dialog)
390
+
391
+ ```ts
392
+ interface HermesSettingsCloseHandler { // hm-settings-dialog [closeHandler]
393
+ readonly onSubmit?: () => boolean | Promise<boolean>; // OK, só depois de TODAS as seções válidas; true fecha
394
+ readonly onCancel?: () => boolean | Promise<boolean>; // Cancelar, X e Esc; true fecha
395
+ }
396
+ ```
397
+
398
+ Com `closeHandler` (ou `actions`) aparece o rodapé Cancelar/Salvar (`submitLabel`, `cancelLabel`) e clicar fora não
399
+ fecha. `hm-settings-section [control]` (FormGroup) ou `[invalid]`: seção inválida fica marcada na navegação e barra o
400
+ OK (abre a primeira inválida e foca o campo). Enquanto `onSubmit` espera, o Salvar carrega e a janela trava; `false`
401
+ fica aberto, rejeição mostra a falha no rodapé; `true` fecha e emite `(submitted)`. Não valide dentro do `onSubmit`.
402
+
403
+ ## Linha do tempo e pessoas
404
+
405
+ ```ts
406
+ type TimelineDateValue = Date | string | number | null | undefined; // hm-timeline-item [date]: Date, ISO ou epoch
407
+
408
+ interface AvatarGroupPerson { // hm-avatar-group [people]
409
+ readonly name: string; // vira o texto lido (o avatar é decorativo)
410
+ readonly imageUrl?: string | null; // sem foto, iniciais
411
+ }
412
+ ```
413
+
414
+ `hm-timeline-item`: `key` (comparado com `current` do `hm-timeline`), `label` (obrigatório), `date`, `description`,
415
+ `status` (`TimelineStatus | null` — vazio deriva de `current`/`outcome`), `icon`. Data formatada pelo idioma do
416
+ catálogo (`dateFormat` no `hm-timeline`, `Intl.DateTimeFormatOptions`).
417
+
418
+ ## Listas de escolha e ordem
419
+
420
+ ```ts
421
+ interface DualListItem { // hm-dual-list [items]; o valor é readonly string[] (ids), na ordem de items
422
+ readonly id: string;
423
+ readonly label: string;
424
+ readonly description?: string; // também entra na busca
425
+ readonly disabled?: boolean; // visível e focável, mas não muda de lado
426
+ }
427
+
428
+ interface ReorderListItem { // hm-reorder-list [(items)]
429
+ readonly id: string; readonly label: string; readonly description?: string;
430
+ }
431
+ interface ReorderListMove { readonly item: ReorderListItem; readonly from: number; readonly to: number; } // (moved)
432
+ interface ReorderListRemoval { readonly item: ReorderListItem; readonly index: number; } // (removed), com removable
433
+ interface ReorderListItemContext { readonly $implicit: ReorderListItem; readonly index: number; } // <ng-template let-item let-index="index">
434
+ ```
435
+
436
+ `hm-reorder-list` publica a ordem nova só **ao soltar**. `hm-dual-list` tem `moveMarked(side)`/`moveAll(side)`
437
+ públicos (`side: 'available' | 'selected'`).
438
+
439
+ ## Atalhos de teclado
440
+
441
+ ```ts
442
+ interface HermesShortcut { // HermesShortcutService.register(shortcut) → () => void (remove)
443
+ readonly keys: string | readonly string[]; // 'Mod+K', ['Mod+K', '/'], sequência 'G H'
444
+ readonly description: string; // como aparece no hm-shortcut-list
445
+ readonly group?: string; // 'navigation' | 'actions' | 'editing' | 'view' | 'general' (traduzidos) ou nome livre
446
+ readonly allowInInputs?: boolean; // dispara com foco em campo editável. Padrão false
447
+ readonly handler: (event: KeyboardEvent) => void | boolean; // false = "não tratei" (segue sem preventDefault)
448
+ readonly preventDefault?: boolean; // padrão true
449
+ }
450
+
451
+ interface HermesShortcutItem { // hm-shortcut-list [items]: atalhos só declarados (Esc do diálogo, Alt+← do navegador)
452
+ readonly keys: string | readonly string[]; readonly description: string; readonly group?: string;
453
+ }
454
+
455
+ interface HermesShortcutConfig { // provideHermesShortcuts(config)
456
+ readonly platform?: ShortcutPlatform; // padrão: detectada
457
+ readonly sequenceTimeout?: number; // ms entre passos de 'G H'. Padrão 1000
458
+ readonly characterKeys?: boolean; // atalhos de tecla única ligados de início. Padrão true
459
+ readonly groupOrder?: readonly string[]; // ordem dos grupos no painel
460
+ }
461
+ ```
462
+
463
+ Serviço: `register`, `setCharacterKeys(bool)`, `characterKeys` (signal), `list` (signal dos registrados),
464
+ `format(keys)`, `ariaKeyShortcuts(keys)`, `groupName(group)`, `platform`. `Mod` = Ctrl no Windows/Linux, ⌘ no macOS.
465
+ Dois registros na mesma tecla: vale o mais recente (aviso `[hermes-shortcuts]` em dev). Atalho só de caractere
466
+ (`'?'`, `'G H'`) obedece a `characterKeys` (WCAG 2.1.4); guardar a escolha entre sessões é do app.
467
+
468
+ Diretiva `[hmShortcut]` (`exportAs: 'hmShortcut'`): `hmShortcut` (obrigatório), `hmShortcutDescription`,
469
+ `hmShortcutGroup`, `hmShortcutAllowInInputs`, `hmShortcutDisabled`, `hmShortcutAction`; output
470
+ `hmShortcutTriggered`. Põe `aria-keyshortcuts` no alvo; alvo desabilitado não reage.
471
+
472
+ ## Lista, vazio, alternância, conversa, anexo e prompt
473
+
474
+ ```ts
475
+ type ItemAppearance = 'plain' | 'outlined' | 'muted'; type ItemSize = 'small' | 'medium';
476
+ type EmptyAppearance = 'plain' | 'dashed'; type EmptySize = 'small' | 'medium';
477
+ type EmptyHeadingLevel = 0 | 2 | 3 | 4 | 5 | 6; // 0 = texto em destaque, não título
478
+ type ToggleGroupValue = string | readonly string[]; // texto no modo único, lista com `multiple`
479
+ type ToggleGroupAppearance = 'outlined' | 'subtle';
480
+ type ToggleGroupSize = 'small' | 'medium' | 'large'; type ToggleGroupOrientation = 'horizontal' | 'vertical';
481
+ type MessageAlign = 'start' | 'end'; // end = mensagem de quem está usando
482
+ type MessageStatus = 'sending' | 'sent' | 'delivered' | 'read' | 'failed';
483
+ type BubbleVariant = 'received' | 'sent' | 'system' | 'emphasis';
484
+ interface BubbleReaction { readonly emoji: string; readonly count: number; readonly label?: string; readonly selected?: boolean }
485
+ type MessageDividerVariant = 'separator' | 'inline';
486
+ type MessageScrollerLive = 'polite' | 'off';
487
+ type AttachmentStatus = 'idle' | FileUploadStatus; // 'pending' | 'uploading' | 'done' | 'error'
488
+ type AttachmentGroupLayout = 'list' | 'inline' | 'grid';
489
+ type TextareaSubmitKey = 'none' | 'mod-enter' | 'enter';
490
+ type TextareaAddonSlot = 'prefix' | 'suffix' | 'actions' | 'actionsEnd';
491
+ type HermesDirection = 'ltr' | 'rtl'; // elementDirection(el) / isRtl(el)
492
+ ```