@acropole/skills 1.2.0 → 1.4.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 (41) hide show
  1. package/README.md +4 -3
  2. package/package.json +4 -4
  3. package/skills/acropole/SKILL.md +2 -0
  4. package/skills/acropole/references/arquitetura.md +29 -5
  5. package/skills/acropole/references/fluxos/app-novo.md +4 -4
  6. package/skills/acropole/references/fluxos/tela-nova.md +1 -1
  7. package/skills/apollo/references/subscriptions.md +10 -4
  8. package/skills/apollo/references/testes-build.md +1 -0
  9. package/skills/auto-servico/SKILL.md +153 -0
  10. package/skills/auto-servico/references/diagnostico.md +42 -0
  11. package/skills/auto-servico/references/roteiros.md +63 -0
  12. package/skills/auto-servico/references/tools.md +108 -0
  13. package/skills/docker/SKILL.md +3 -0
  14. package/skills/docker/references/podman-local.md +73 -0
  15. package/skills/express/references/dados.md +3 -1
  16. package/skills/fastapi/SKILL.md +4 -4
  17. package/skills/fastapi/references/banco.md +53 -50
  18. package/skills/fastapi/references/estrutura.md +2 -2
  19. package/skills/fastapi/references/integracoes.md +8 -0
  20. package/skills/hefesto/SKILL.md +49 -14
  21. package/skills/hefesto/references/diagnostico.md +15 -5
  22. package/skills/hefesto/references/fluxo.md +64 -35
  23. package/skills/hefesto/references/mcp-diagnostico.md +44 -0
  24. package/skills/hefesto/references/mcp-roteiros.md +53 -0
  25. package/skills/hefesto/references/mcp-tools.md +94 -0
  26. package/skills/orfeu/SKILL.md +1 -1
  27. package/skills/orfeu/references/diferencas.md +1 -1
  28. package/skills/orfeu/references/node.md +1 -1
  29. package/skills/orquestracao/SKILL.md +1 -1
  30. package/skills/orquestracao/templates/spec.md +1 -1
  31. package/skills/trismegisto/SKILL.md +4 -4
  32. package/skills/trismegisto/references/angular-api.md +653 -507
  33. package/skills/trismegisto/references/angular-exports.md +541 -130
  34. package/skills/trismegisto/references/angular-types.md +1 -1
  35. package/skills/trismegisto/references/angular.md +28 -8
  36. package/skills/trismegisto/references/catalogo/icones.json +5 -0
  37. package/skills/trismegisto/references/catalogo/seletores.json +452 -31
  38. package/skills/trismegisto/references/catalogo/tokens.json +136 -16
  39. package/skills/trismegisto/references/spine-api.md +181 -44
  40. package/skills/trismegisto/references/spine-recipes.md +1 -1
  41. package/skills/trismegisto/references/spine.md +4 -3
@@ -1,6 +1,6 @@
1
1
  # Exports por ponto de import — @trismegisto/angular
2
2
 
3
- > **Gerado** a partir do código-fonte da versão 1.0.0, a cada `npm run sync` do @acropole/skills (junto com o `angular-api.md`).
3
+ > **Gerado** a partir do código-fonte da versão 2.0.1, a cada `npm run sync` do @acropole/skills (junto com o `angular-api.md`).
4
4
 
5
5
  Tudo que cada `@trismegisto/angular/<ponto>` exporta: serviços (com os membros públicos), funções, constantes,
6
6
  tokens de injeção e tipos (com a declaração). Componentes, diretivas e pipes aparecem só pelo nome — inputs,
@@ -11,7 +11,7 @@ outputs e slots estão no `angular-api.md`. A raiz `@trismegisto/angular` reexpo
11
11
 
12
12
  - `AccordionPanelComponent` — `hm-accordion-panel` (ver angular-api.md)
13
13
  - `AccordionComponent` — `hm-accordion` (ver angular-api.md)
14
- - **`HermesAccordionGroup`** (classe) — Contrato que `hm-accordion` publica por injeção para os `hm-accordion-panel` dentro dele.
14
+ - **`HermesAccordionGroup`** (classe) — O que o `hm-accordion` oferece por injeção aos painéis que contém. Em arquivo próprio para o painel injetar o grupo sem importar o componente que, por sua vez, consulta os painéis.
15
15
 
16
16
  ```ts
17
17
  abstract class HermesAccordionGroup {
@@ -22,7 +22,7 @@ abstract class HermesAccordionGroup {
22
22
 
23
23
  ## `@trismegisto/angular/account-avatar`
24
24
 
25
- - `AccountAvatarSize` — Escala de tamanho do avatar (a mesma do `hm-avatar-group`).
25
+ - `AccountAvatarSize` — Diâmetros do avatar: `small`, `medium` e `large`. É a mesma escala da pilha de avatares (`AvatarGroupSize` do `hm-avatar-group`), para os dois combinarem lado a lado.
26
26
 
27
27
  ```ts
28
28
  type AccountAvatarSize = 'small' | 'medium' | 'large';
@@ -32,22 +32,21 @@ type AccountAvatarSize = 'small' | 'medium' | 'large';
32
32
 
33
33
  ## `@trismegisto/angular/alert`
34
34
 
35
- - `AlertGroupComponent` — `hm-alert-group` (ver angular-api.md)
36
- - **`HermesAlertGroup`** (classe) — Contrato que `hm-alert-group` publica por injeção para os `hm-alert` dentro dele.
35
+ - `AlertSize`
37
36
 
38
37
  ```ts
39
- abstract class HermesAlertGroup {
40
- }
38
+ type AlertSize = 'small' | 'medium';
41
39
  ```
42
40
 
43
- - `AlertSize` — `medium` (padrão) ou `small`: respiro, texto e ícone menores para painel, cartão e formulário.
41
+ - `AlertComponent` — `hm-alert` (ver angular-api.md)
42
+ - `AlertGroupComponent` — `hm-alert-group` (ver angular-api.md)
43
+ - **`HermesAlertGroup`** (classe) — O que o `hm-alert` precisa saber do grupo que o contém. Fica num arquivo à parte para o alerta não importar o componente do grupo (e o grupo, que importa o alerta, não fechar um ciclo).
44
44
 
45
45
  ```ts
46
- type AlertSize = 'small' | 'medium';
46
+ abstract class HermesAlertGroup {
47
+ }
47
48
  ```
48
49
 
49
- - `AlertComponent` — `hm-alert` (ver angular-api.md)
50
-
51
50
  ## `@trismegisto/angular/attachment`
52
51
 
53
52
  - `AttachmentStatus` — Situação do anexo: `idle` (arquivo já disponível, sem envio em jogo) ou uma das situações de envio do `hm-file-upload` (`pending`, `uploading`, `done`, `error`), com os mesmos textos.
@@ -64,13 +63,13 @@ type AttachmentGroupLayout = 'list' | 'inline' | 'grid';
64
63
  ```
65
64
 
66
65
  - `AttachmentGroupComponent` — `hm-attachment-group` (ver angular-api.md)
67
- - `function fileExtension(name: string): string` — Extensão minúscula, sem o ponto (`'Relatório.PDF'` → `'pdf'`); sem extensão, `''`.
68
- - `function isImageFile(name: string, type = ''): boolean` — O arquivo é uma imagem (pelo MIME ou, sem ele, pela extensão)?
69
- - `function fileIconName(name: string, type = ''): string` — Nome do ícone do catálogo para o arquivo.
66
+ - `function fileExtension(name: string): string` — Extensão em minúsculas (`'Relatório.PDF'` → `'pdf'`); `''` sem extensão ou em `.gitignore`.
67
+ - `function isImageFile(name: string, type = ''): boolean` — É imagem? Com MIME, ele decide; sem MIME, a extensão.
68
+ - `function fileIconName(name: string, type = ''): string` — Nome do ícone do catálogo para o arquivo; `'file'` quando o tipo não é conhecido.
70
69
 
71
70
  ## `@trismegisto/angular/avatar-group`
72
71
 
73
- - `AvatarGroupPerson` — Uma pessoa da pilha: o mesmo par que o `hm-account-avatar` consome.
72
+ - `AvatarGroupPerson` — Uma pessoa da pilha. Sem `imageUrl` (ou com foto que não carrega), aparecem as iniciais.
74
73
 
75
74
  ```ts
76
75
  interface AvatarGroupPerson {
@@ -79,7 +78,7 @@ interface AvatarGroupPerson {
79
78
  }
80
79
  ```
81
80
 
82
- - `AvatarGroupSize`
81
+ - `AvatarGroupSize` — Mesma escala do `hm-account-avatar`.
83
82
 
84
83
  ```ts
85
84
  type AvatarGroupSize = 'small' | 'medium' | 'large';
@@ -135,7 +134,7 @@ interface BubbleReaction {
135
134
 
136
135
  ## `@trismegisto/angular/button`
137
136
 
138
- - `ButtonGroupRegistry` — Registro de um `hm-button` no `hm-button-group` que o contém (ver button-group.component.ts).
137
+ - `ButtonGroupRegistry` — O que um contêiner de botões (o `hm-button-group`) precisa expor para os botões se inscreverem nele.
139
138
 
140
139
  ```ts
141
140
  interface ButtonGroupRegistry {
@@ -239,7 +238,7 @@ type CheckboxGroupLayout = 'stacked' | 'inline';
239
238
  ## `@trismegisto/angular/chip`
240
239
 
241
240
  - `ChipGroupComponent` — `hm-chip-group` (ver angular-api.md)
242
- - **`HermesChipGroup`** (classe) — Contrato que `hm-chip-group` publica por injeção para os `hm-chip` dentro dele.
241
+ - **`HermesChipGroup`** (classe) — Interface do `hm-chip-group` vista por um `hm-chip` filho, resolvida por DI (opcional: a ficha também funciona solta).
243
242
 
244
243
  ```ts
245
244
  abstract class HermesChipGroup {
@@ -260,10 +259,190 @@ type ChipSize = 'small' | 'medium';
260
259
 
261
260
  - `ChipComponent` — `hm-chip` (ver angular-api.md)
262
261
 
262
+ ## `@trismegisto/angular/code-diff`
263
+
264
+ - `CodeDiffLayoutInput`
265
+
266
+ ```ts
267
+ type CodeDiffLayoutInput = CodeDiffLayout | 'auto';
268
+ ```
269
+
270
+ - `CodeDiffCopyTarget`
271
+
272
+ ```ts
273
+ type CodeDiffCopyTarget = 'modified' | 'original' | 'patch' | 'none';
274
+ ```
275
+
276
+ - `CodeDiffComponent` — `hm-code-diff` (ver angular-api.md)
277
+ - `TextDiff` _(de `@trismegisto/primitives`)_
278
+
279
+ ```ts
280
+ interface TextDiff {
281
+ readonly changes: readonly TextDiffChange[];
282
+ readonly originalLineCount: number;
283
+ readonly modifiedLineCount: number;
284
+ readonly identical: boolean;
285
+ readonly approximate: boolean;
286
+ readonly finalNewline: { readonly original: boolean; readonly modified: boolean };
287
+ readonly stats: { readonly added: number; readonly removed: number; readonly changed: number };
288
+ }
289
+ ```
290
+
291
+ - `TextDiffSummary` _(de `@trismegisto/primitives`)_
292
+
293
+ ```ts
294
+ interface TextDiffSummary {
295
+ readonly added: number;
296
+ readonly removed: number;
297
+ readonly changed: number;
298
+ readonly changes: number;
299
+ readonly identical: boolean;
300
+ readonly approximate: boolean;
301
+ }
302
+ ```
303
+
304
+ - `TextDiffWhitespace` _(de `@trismegisto/primitives`)_ — Diferença entre dois textos (o cálculo por trás do `hm-code-diff`), puro e determinístico — pode ir para um Web Worker sem mudar a API.
305
+
306
+ ```ts
307
+ type TextDiffWhitespace = 'exact' | 'ignore-edges' | 'ignore-all';
308
+ ```
309
+
310
+ - `TextDiffIntraline` _(de `@trismegisto/primitives`)_
311
+
312
+ ```ts
313
+ type TextDiffIntraline = 'none' | 'word' | 'char';
314
+ ```
315
+
263
316
  ## `@trismegisto/angular/code-input`
264
317
 
265
318
  - `CodeInputComponent` — `hm-code-input` (ver angular-api.md)
266
319
 
320
+ ## `@trismegisto/angular/code-viewer`
321
+
322
+ - `CodeViewerComponent` — `hm-code-viewer` (ver angular-api.md)
323
+ - **`CodeLanguagesService`** (classe)
324
+
325
+ ```ts
326
+ class CodeLanguagesService {
327
+ readonly registry
328
+ readonly version = signal(…)
329
+ register(...languages: readonly (CodeLanguage | CodeLanguageLoader)[]): void
330
+ resolve(idOrAlias: string): CodeLanguage | Promise<CodeLanguage> | null
331
+ readonly resolveLoaded
332
+ label(idOrAlias: string): string | null
333
+ }
334
+ ```
335
+
336
+ - `function provideCodeLanguages(...languages: readonly (CodeLanguage | CodeLanguageLoader)[]): EnvironmentProviders` — Registra linguagens no app:
337
+ - `ResolvedCodeLanguage` — Resultado da resolução de `language`/`filename` de um componente.
338
+
339
+ ```ts
340
+ interface ResolvedCodeLanguage {
341
+ readonly language: CodeLanguage;
342
+ readonly pending: Promise<CodeLanguage> | null;
343
+ }
344
+ ```
345
+
346
+ - `function resolveCodeLanguageInput( service: CodeLanguagesService, language: string | CodeLanguage | null | undefined, filename: string, prefix: string, ): ResolvedCodeLanguage` — `language` (objeto, id/alias) ou, sem ele, a inferida de `filename`. Desconhecida = texto puro e um aviso de desenvolvimento por id (`prefix` = `[hermes-code-viewer]`/`[hermes-code-diff]`).
347
+ - `CodeLineRef` — Onde a linha mora no modelo (o que a cópia usa para montar o texto, nunca o DOM).
348
+
349
+ ```ts
350
+ interface CodeLineRef {
351
+ readonly line: number;
352
+ readonly side: 'original' | 'modified' | null;
353
+ readonly row: number;
354
+ }
355
+ ```
356
+
357
+ - **`CodeLineRegistry`** (classe) — Registro elemento → linha, dono: o componente (viewer ou diff).
358
+
359
+ ```ts
360
+ class CodeLineRegistry {
361
+ set(element: Element, ref: CodeLineRef): void
362
+ delete(element: Element): void
363
+ get(element: Element): CodeLineRef | undefined
364
+ }
365
+ ```
366
+
367
+ - `const CODE_LINE_REGISTRY: InjectionToken<CodeLineRegistry>`
368
+ - `const CODE_INVISIBLE_CLASS = 'hm-code-viewer__invisible'` — Classe do marcador de caractere invisível (a cópia o reconhece e devolve o caractere original).
369
+ - `CodeLineDirective` — `[hmCodeLine]` (ver angular-api.md)
370
+ - `const CODE_SLICE_MS = 8` — Fatia máxima de trabalho de fundo (ms) antes de devolver o navegador.
371
+ - `function scheduleCodeTask(win: Window | null, task: () => void): () => void` — Agenda `task` para quando o navegador estiver ocioso (`requestIdleCallback`, senão `setTimeout`).
372
+ - `CodeModelPoint`
373
+
374
+ ```ts
375
+ interface CodeModelPoint {
376
+ readonly ref: CodeLineRef;
377
+ readonly offset: number;
378
+ }
379
+ ```
380
+
381
+ - `function codeModelPoint( node: Node, offset: number, edge: 'start' | 'end', lines: readonly Element[], registry: CodeLineRegistry, length: (ref: CodeLineRef) => number, ): CodeModelPoint | null` — Ponta da seleção (nó + deslocamento do DOM) → linha do modelo + deslocamento no texto original. Fora de uma linha (número, marcador de diff, espaço entre linhas): a linha mais próxima na direção certa (`start` → começo…
382
+ - `function selectionInside(doc: Document, root: Element): Selection | null` — As duas pontas da seleção dentro de `root`, ou `null` se ela não estiver inteira dentro dele.
383
+ - `function cssLengthToPx(value: string, rootFontSize: number, fontSize = rootFontSize): number | null` — Medida CSS (`48rem`, `640px`, `30em`) → px. `fontSize` = do elemento (para `em`).
384
+ - `function isPrimaryShortcut(event: KeyboardEvent, key: string): boolean` — Ctrl/⌘ (sem Alt) + tecla.
385
+ - `CodeLanguage` _(de `@trismegisto/primitives`)_
386
+
387
+ ```ts
388
+ interface CodeLanguage {
389
+ readonly id: string;
390
+ readonly label: string;
391
+ readonly aliases?: readonly string[];
392
+ readonly extensions?: readonly string[];
393
+ readonly grammar: CodeGrammar;
394
+ }
395
+ ```
396
+
397
+ - `CodeLanguageLoader` _(de `@trismegisto/primitives`)_ — Linguagem carregada sob demanda (o registro chama `load` uma vez só).
398
+
399
+ ```ts
400
+ interface CodeLanguageLoader {
401
+ readonly id: string;
402
+ readonly label: string;
403
+ readonly aliases?: readonly string[];
404
+ readonly extensions?: readonly string[];
405
+ readonly load: () => Promise<CodeLanguage>;
406
+ }
407
+ ```
408
+
409
+ - `CodeTokenKind` _(de `@trismegisto/primitives`)_
410
+
411
+ ```ts
412
+ type CodeTokenKind = (typeof CODE_TOKEN_KINDS)[number];
413
+ ```
414
+
415
+ - `CodeToken` _(de `@trismegisto/primitives`)_ — Um trecho classificado da linha: índices em UTF-16, `[start, end)`.
416
+
417
+ ```ts
418
+ interface CodeToken {
419
+ readonly start: number;
420
+ readonly end: number;
421
+ readonly kind: CodeTokenKind;
422
+ }
423
+ ```
424
+
425
+ - `CodeLineTokens` _(de `@trismegisto/primitives`)_
426
+
427
+ ```ts
428
+ interface CodeLineTokens {
429
+ readonly tokens: readonly CodeToken[];
430
+ readonly endState: CodeTokenizerState;
431
+ }
432
+ ```
433
+
434
+ - `CodeViewerHeader` _(de `@trismegisto/primitives`)_
435
+
436
+ ```ts
437
+ type CodeViewerHeader = 'auto' | 'show' | 'hide';
438
+ ```
439
+
440
+ - `CodeViewerVirtualize` _(de `@trismegisto/primitives`)_
441
+
442
+ ```ts
443
+ type CodeViewerVirtualize = 'auto' | 'always' | 'never';
444
+ ```
445
+
267
446
  ## `@trismegisto/angular/combobox`
268
447
 
269
448
  - `ComboboxSize`
@@ -273,7 +452,7 @@ type ComboboxSize = 'small' | 'medium' | 'large';
273
452
  ```
274
453
 
275
454
  - `ComboboxComponent` — `hm-combobox` (ver angular-api.md)
276
- - `ComboboxOption` _(de `@trismegisto/primitives`)_ — `value` identifica a opção; `label` é o texto pesquisável e mostrado. `raw`/`swatchBackground`+ `swatchBorder` (sempre os dois juntos — só o fundo deixaria a opção sem moldura num tema onde o fundo se aproxima da superf…
455
+ - `ComboboxOption` _(de `@trismegisto/primitives`)_ — Uma opção da lista. `label` é ao mesmo tempo o que aparece e o que a busca compara.
277
456
 
278
457
  ```ts
279
458
  interface ComboboxOption {
@@ -286,6 +465,19 @@ interface ComboboxOption {
286
465
  }
287
466
  ```
288
467
 
468
+ - `ɵComboboxOverlay`
469
+ - `ɵrevealOption`
470
+ - `ɵComboboxOverlayParts` — Onde o cartão de uma lista de combobox se pendura e para onde o foco volta.
471
+
472
+ ```ts
473
+ interface ComboboxOverlayParts {
474
+ readonly card: () => HTMLElement | undefined;
475
+ readonly anchor: () => HTMLElement | undefined;
476
+ readonly focusTarget: () => HTMLElement | undefined;
477
+ readonly isOpen: () => boolean;
478
+ }
479
+ ```
480
+
289
481
  ## `@trismegisto/angular/combobox-multi`
290
482
 
291
483
  - `ComboboxMultiComponent` — `hm-combobox-multi` (ver angular-api.md)
@@ -343,7 +535,7 @@ type PaletteStatusKind = '' | 'idle' | 'empty' | 'loading' | 'error';
343
535
 
344
536
  ## `@trismegisto/angular/copy-button`
345
537
 
346
- - `CopyButtonVariant` — `icon`: só o ícone (padrão do `hm-icon-button`); `text`: ícone + rótulo visível.
538
+ - `CopyButtonVariant` — `icon`: só o ícone (o `label` vira o nome acessível). `text`: ícone e texto visível.
347
539
 
348
540
  ```ts
349
541
  type CopyButtonVariant = 'icon' | 'text';
@@ -358,6 +550,15 @@ type CopyButtonVariant = 'icon' | 'text';
358
550
  - `DataGridColumnFilterComponent` — `hm-data-grid-column-filter` (ver angular-api.md)
359
551
  - `DataGridHeaderDirective` — `ng-template[hmColumnHeader]` (ver angular-api.md)
360
552
  - `DataGridComponent` — `hm-data-grid` (ver angular-api.md)
553
+ - `DataGridActionConfirm` — Confirmação de uma ação por linha (`HermesDialogService.confirm`). `confirmLabel` padrão: o rótulo da ação; `danger` padrão: o `danger` da ação.
554
+
555
+ ```ts
556
+ type DataGridActionConfirm = Omit<HermesConfirmOptions, 'danger' | 'confirmLabel'> & {
557
+ readonly danger?: boolean;
558
+ readonly confirmLabel?: string;
559
+ };
560
+ ```
561
+
361
562
  - `DataGridRowAction` — Ação por linha, desenhada como item do menu da última coluna.
362
563
 
363
564
  ```ts
@@ -368,6 +569,7 @@ interface DataGridRowAction<T = unknown> {
368
569
  readonly danger?: boolean;
369
570
  readonly separatorAbove?: boolean;
370
571
  readonly available?: (row: T) => boolean;
572
+ readonly confirm?: DataGridActionConfirm | ((row: T) => DataGridActionConfirm);
371
573
  }
372
574
  ```
373
575
 
@@ -400,7 +602,7 @@ interface DataGridFooterContext {
400
602
  }
401
603
  ```
402
604
 
403
- - `DataGridRowState` — Veredito da linha inteira, quando ela tem um — a tinta é reforço, nunca o portador do significado: quem usa continua devendo uma coluna que diga o que houve (WCAG 1.4.1).
605
+ - `DataGridRowState` — Fundo de status da linha (`rowState`). É só visual: o motivo do status precisa estar escrito em alguma célula, porque cor sozinha não chega a todo mundo (WCAG 1.4.1).
404
606
 
405
607
  ```ts
406
608
  type DataGridRowState = 'error' | 'warning';
@@ -412,7 +614,7 @@ type DataGridRowState = 'error' | 'warning';
412
614
  type DataGridRowDetail = 'enabled' | 'disabled' | 'hidden';
413
615
  ```
414
616
 
415
- - `DataGridColumn` _(de `@trismegisto/primitives`)_ — Definição de coluna. `value` devolve o texto já formatado que a célula mostra; `raw` (quando existe) devolve o valor comparável/filtrável — separar os dois é o que permite filtrar por `>18` numa coluna que exibe "18 ano…
617
+ - `DataGridColumn` _(de `@trismegisto/primitives`)_
416
618
 
417
619
  ```ts
418
620
  interface GridColumn<T> {
@@ -433,7 +635,7 @@ interface GridColumn<T> {
433
635
  }
434
636
  ```
435
637
 
436
- - `DataGridExportFormat` — `csv`: RFC 4180 (vírgula, sem BOM). `excel`: BOM UTF-8 e o separador do idioma (`;` em pt-BR/es).
638
+ - `DataGridExportFormat` — `csv` is plain RFC 4180; `excel` adds a BOM and the locale's list separator so spreadsheets open it right.
437
639
 
438
640
  ```ts
439
641
  type DataGridExportFormat = 'csv' | 'excel';
@@ -455,7 +657,7 @@ interface DataGridExportOptions {
455
657
  type DataGridPersistStorage = 'local' | 'session';
456
658
  ```
457
659
 
458
- - `DataGridSelectionMode` — `'single'` = rádio por linha (uma só); `'multiple'` = checkbox (o antigo `selectable`).
660
+ - `DataGridSelectionMode` — `'single'` = rádio por linha; `'multiple'` = caixa por linha e "selecionar todos" da página.
459
661
 
460
662
  ```ts
461
663
  type DataGridSelectionMode = 'none' | 'single' | 'multiple';
@@ -778,7 +980,7 @@ type DragListOrientation = 'vertical' | 'horizontal' | 'grid';
778
980
 
779
981
  ## `@trismegisto/angular/drawer`
780
982
 
781
- - `DrawerPosition` — Borda de onde o painel sai: fim da linha (direita em LTR), começo da linha ou de baixo.
983
+ - `DrawerPosition` — Borda de onde o painel entra: `end` (padrão — a direita, em escrita da esquerda para a direita), `start` (a borda oposta) ou `bottom` (folha que sobe de baixo, boa para celular).
782
984
 
783
985
  ```ts
784
986
  type DrawerPosition = 'end' | 'start' | 'bottom';
@@ -940,7 +1142,7 @@ type FieldType = 'text' | 'password';
940
1142
  type FileUploadSize = 'small' | 'medium' | 'large';
941
1143
  ```
942
1144
 
943
- - `FileUploader` — Envio opcional feito pelo próprio componente: recebe o arquivo, uma função para informar o progresso (0–100) e um `AbortSignal` (abortado quando a pessoa remove o arquivo durante o envio). Resolver = enviado; rejeitar =…
1145
+ - `FileUploader` — Envia um arquivo: chama `report(0–100)` conforme avança e resolve ao terminar. Rejeitar marca o item como falho (a `message` do `Error` vira o texto). O `signal` é abortado quando o item sai da lista.
944
1146
 
945
1147
  ```ts
946
1148
  type FileUploader = (file: File, report: (progress: number) => void, signal: AbortSignal) => Promise<unknown>;
@@ -1167,7 +1369,10 @@ type IconFlip = 'horizontal' | 'vertical';
1167
1369
  - `const ICON_ANGLE_DOUBLE: RegisteredIcon`
1168
1370
  - `const ICON_ARROW: RegisteredIcon`
1169
1371
  - `const ICON_ARROWS_HORIZONTAL: RegisteredIcon`
1372
+ - `const ICON_BLOCK_QUOTE: RegisteredIcon`
1373
+ - `const ICON_BOLD: RegisteredIcon`
1170
1374
  - `const ICON_BOOKMARK: RegisteredIcon`
1375
+ - `const ICON_BULLET_LIST: RegisteredIcon`
1171
1376
  - `const ICON_CALENDAR: RegisteredIcon`
1172
1377
  - `const ICON_CHECK: RegisteredIcon`
1173
1378
  - `const ICON_CHECK_CIRCLE: RegisteredIcon`
@@ -1175,8 +1380,12 @@ type IconFlip = 'horizontal' | 'vertical';
1175
1380
  - `const ICON_CIRCLE: RegisteredIcon`
1176
1381
  - `const ICON_CLOCK: RegisteredIcon`
1177
1382
  - `const ICON_CLOUD_UP: RegisteredIcon`
1383
+ - `const ICON_CODE: RegisteredIcon`
1384
+ - `const ICON_CODE_BLOCK: RegisteredIcon`
1178
1385
  - `const ICON_COG: RegisteredIcon`
1179
1386
  - `const ICON_COPY: RegisteredIcon`
1387
+ - `const ICON_DETAIL_COLLAPSE: RegisteredIcon`
1388
+ - `const ICON_DETAIL_EXPAND: RegisteredIcon`
1180
1389
  - `const ICON_DOCUMENT_CSV: RegisteredIcon`
1181
1390
  - `const ICON_DOCUMENT_DOC: RegisteredIcon`
1182
1391
  - `const ICON_DOCUMENT_IMAGE: RegisteredIcon`
@@ -1186,6 +1395,7 @@ type IconFlip = 'horizontal' | 'vertical';
1186
1395
  - `const ICON_DRAG_HANDLE: RegisteredIcon`
1187
1396
  - `const ICON_ELLIPSIS_HORIZONTAL: RegisteredIcon`
1188
1397
  - `const ICON_ELLIPSIS_VERTICAL: RegisteredIcon`
1398
+ - `const ICON_ERASER: RegisteredIcon`
1189
1399
  - `const ICON_ERROR_STANDARD: RegisteredIcon`
1190
1400
  - `const ICON_EXCLAMATION_CIRCLE: RegisteredIcon`
1191
1401
  - `const ICON_EXCLAMATION_TRIANGLE: RegisteredIcon`
@@ -1197,36 +1407,48 @@ type IconFlip = 'horizontal' | 'vertical';
1197
1407
  - `const ICON_FILTER_GRID: RegisteredIcon`
1198
1408
  - `const ICON_FILTER_GRID_CIRCLE: RegisteredIcon`
1199
1409
  - `const ICON_GRID: RegisteredIcon`
1410
+ - `const ICON_IMAGE: RegisteredIcon`
1200
1411
  - `const ICON_INFO_CIRCLE: RegisteredIcon`
1412
+ - `const ICON_ITALIC: RegisteredIcon`
1201
1413
  - `const ICON_KEY: RegisteredIcon`
1202
1414
  - `const ICON_KEYBOARD: RegisteredIcon`
1415
+ - `const ICON_LINK: RegisteredIcon`
1203
1416
  - `const ICON_LIST: RegisteredIcon`
1204
1417
  - `const ICON_LOGIN: RegisteredIcon`
1205
1418
  - `const ICON_MENU: RegisteredIcon`
1206
1419
  - `const ICON_MINUS: RegisteredIcon`
1207
1420
  - `const ICON_NODE: RegisteredIcon`
1421
+ - `const ICON_NUMBER_LIST: RegisteredIcon`
1208
1422
  - `const ICON_PAUSE: RegisteredIcon`
1209
1423
  - `const ICON_PENCIL: RegisteredIcon`
1210
1424
  - `const ICON_PIN: RegisteredIcon`
1211
1425
  - `const ICON_PLAY: RegisteredIcon`
1212
1426
  - `const ICON_PLUS: RegisteredIcon`
1427
+ - `const ICON_REDO: RegisteredIcon`
1213
1428
  - `const ICON_REFRESH: RegisteredIcon`
1429
+ - `const ICON_ROTATE_LEFT: RegisteredIcon`
1430
+ - `const ICON_ROTATE_RIGHT: RegisteredIcon`
1214
1431
  - `const ICON_SEARCH: RegisteredIcon`
1215
1432
  - `const ICON_STAR: RegisteredIcon`
1216
1433
  - `const ICON_STEP_FORWARD_2: RegisteredIcon`
1434
+ - `const ICON_STRIKETHROUGH: RegisteredIcon`
1217
1435
  - `const ICON_SUCCESS_STANDARD: RegisteredIcon`
1218
1436
  - `const ICON_TEXT: RegisteredIcon`
1219
1437
  - `const ICON_TIMES: RegisteredIcon`
1220
1438
  - `const ICON_TIMES_CIRCLE: RegisteredIcon`
1221
1439
  - `const ICON_TOOLS: RegisteredIcon`
1222
1440
  - `const ICON_TRASH: RegisteredIcon`
1441
+ - `const ICON_UNDERLINE: RegisteredIcon`
1223
1442
  - `const ICON_UNDO: RegisteredIcon`
1224
1443
  - `const ICON_UPLOAD: RegisteredIcon`
1225
1444
  - `const ICON_USER: RegisteredIcon`
1226
1445
  - `const ICON_VIEW_COLUMNS: RegisteredIcon`
1446
+ - `const ICON_VIEW_LIST: RegisteredIcon`
1227
1447
  - `const ICON_WINDOW_MAX: RegisteredIcon`
1228
1448
  - `const ICON_WINDOW_MIN: RegisteredIcon`
1229
1449
  - `const ICON_WINDOW_RESTORE: RegisteredIcon`
1450
+ - `const ICON_ZOOM_IN: RegisteredIcon`
1451
+ - `const ICON_ZOOM_OUT: RegisteredIcon`
1230
1452
  - `const HERMES_INTERNAL_ICONS: readonly RegisteredIcon[]` — Todos os ícones internos (compatibilidade). Importar este array leva TODOS para o bundle; os componentes não o usam — cada um registra só os seus (`<PASTA>_ICONS`).
1231
1453
  - `function provideHermesIcons(...items: (RegisteredIcon | readonly RegisteredIcon[])[]): EnvironmentProviders` — Registra ícones no bootstrap — um catálogo só, nenhum vem embutido de graça. Pro caso comum de "quero tudo": `provideHermesIcons(HERMES_ICONS)`, de `@trismegisto/icons/catalog` — não tem mais como esquecer de registrar…
1232
1454
  - `function provideHermesIconLoader( loader: () => Promise<RegisteredIcon | readonly RegisteredIcon[]>, ): EnvironmentProviders` — Registra ícones vindos de um carregador assíncrono, **fora do bundle inicial** — o caso do catálogo inteiro (~1,5 MB sem compressão), que vira um chunk à parte baixado logo depois do bootstrap:
@@ -1270,7 +1492,7 @@ type IconFlip = 'horizontal' | 'vertical';
1270
1492
 
1271
1493
  ## `@trismegisto/angular/illustration-shared`
1272
1494
 
1273
- - `IllustrationIdRef` — Um id interno do SVG e as formas de referenciá-lo.
1495
+ - `IllustrationIdRef` — Referência a um elemento definidor de SVG (`<clipPath>`, gradiente, máscara, filtro).
1274
1496
 
1275
1497
  ```ts
1276
1498
  interface IllustrationIdRef {
@@ -1280,7 +1502,7 @@ interface IllustrationIdRef {
1280
1502
  }
1281
1503
  ```
1282
1504
 
1283
- - `function illustrationIds<const K extends string>(name: string, ...keys: readonly K[]): Readonly<Record<K, IllustrationIdRef>>` — Ids únicos por instância para os `<clipPath>`, gradientes, máscaras etc. de uma ilustração.
1505
+ - `function illustrationIds<const K extends string>( name: string, ...keys: readonly K[] ): Readonly<Record<K, IllustrationIdRef>>` — Ids de SVG próprios de uma instância de ilustração, no formato `hm-illustration-<nome>-<n>-<chave>`. Cada chamada reserva um `n` novo, compartilhado pelas chaves dela. Não toca no DOM (seguro em SSR).
1284
1506
 
1285
1507
  ## `@trismegisto/angular/illustration-success`
1286
1508
 
@@ -1290,6 +1512,105 @@ interface IllustrationIdRef {
1290
1512
 
1291
1513
  - `IllustrationUnlockedComponent` — `hm-illustration-unlocked` (ver angular-api.md)
1292
1514
 
1515
+ ## `@trismegisto/angular/image-crop`
1516
+
1517
+ - `ImageCropComponent` — `hm-image-crop` (ver angular-api.md)
1518
+ - `ImageCropError` _(de `@trismegisto/primitives`)_ — Falha de carga ou de geração; `message` já vem do catálogo, pronta para a tela.
1519
+
1520
+ ```ts
1521
+ interface ImageCropError {
1522
+ readonly code: ImageCropErrorCode;
1523
+ readonly message: string;
1524
+ readonly cause?: unknown;
1525
+ }
1526
+ ```
1527
+
1528
+ - `ImageCropErrorCode` _(de `@trismegisto/primitives`)_
1529
+
1530
+ ```ts
1531
+ type ImageCropErrorCode = 'type' | 'size' | 'pixels' | 'url' | 'network' | 'decode' | 'empty' | 'encode';
1532
+ ```
1533
+
1534
+ - `ImageCropExportOptions` _(de `@trismegisto/primitives`)_ — Ajustes de uma geração (`exportImage`); o que faltar vem dos inputs do componente.
1535
+
1536
+ ```ts
1537
+ interface ImageCropExportOptions {
1538
+ readonly type?: ImageCropOutputType;
1539
+ readonly quality?: number;
1540
+ readonly maxWidth?: number;
1541
+ readonly maxHeight?: number;
1542
+ readonly fill?: string;
1543
+ readonly mask?: boolean;
1544
+ readonly as?: 'blob' | 'data-url';
1545
+ }
1546
+ ```
1547
+
1548
+ - `ImageCropInfo` _(de `@trismegisto/primitives`)_ — Imagem carregada: tamanho da imagem orientada (sem o giro do usuário), formato e bytes.
1549
+
1550
+ ```ts
1551
+ interface ImageCropInfo {
1552
+ readonly width: number;
1553
+ readonly height: number;
1554
+ readonly type: ImageCropType;
1555
+ readonly bytes: number;
1556
+ }
1557
+ ```
1558
+
1559
+ - `ImageCropOutputType` _(de `@trismegisto/primitives`)_ — Formatos de saída que o canvas codifica.
1560
+
1561
+ ```ts
1562
+ type ImageCropOutputType = 'image/png' | 'image/jpeg' | 'image/webp';
1563
+ ```
1564
+
1565
+ - `ImageCropRegion` _(de `@trismegisto/primitives`)_ — Área de recorte em pixels inteiros da imagem orientada e girada.
1566
+
1567
+ ```ts
1568
+ interface ImageCropRegion {
1569
+ readonly x: number;
1570
+ readonly y: number;
1571
+ readonly width: number;
1572
+ readonly height: number;
1573
+ }
1574
+ ```
1575
+
1576
+ - `ImageCropResult` _(de `@trismegisto/primitives`)_
1577
+
1578
+ ```ts
1579
+ interface ImageCropResult {
1580
+ readonly blob: Blob;
1581
+ readonly dataUrl?: string;
1582
+ readonly type: string;
1583
+ readonly width: number;
1584
+ readonly height: number;
1585
+ readonly region: ImageCropRegion;
1586
+ readonly rotation: ImageCropRotation;
1587
+ }
1588
+ ```
1589
+
1590
+ - `ImageCropRotation` _(de `@trismegisto/primitives`)_ — Giro no sentido horário, em quartos de volta.
1591
+
1592
+ ```ts
1593
+ type ImageCropRotation = 0 | 90 | 180 | 270;
1594
+ ```
1595
+
1596
+ - `ImageCropShape` _(de `@trismegisto/primitives`)_
1597
+
1598
+ ```ts
1599
+ type ImageCropShape = 'rect' | 'round';
1600
+ ```
1601
+
1602
+ - `ImageCropSource` _(de `@trismegisto/primitives`)_ — Imagem a recortar: arquivo/`Blob`, endereço `http(s)`/relativo, `blob:` ou `data:image/…`.
1603
+
1604
+ ```ts
1605
+ type ImageCropSource = Blob | string | null;
1606
+ ```
1607
+
1608
+ - `ImageCropType` _(de `@trismegisto/primitives`)_ — Formatos de ENTRADA reconhecidos (pelos bytes, nunca pelo tipo declarado).
1609
+
1610
+ ```ts
1611
+ type ImageCropType = 'image/png' | 'image/jpeg' | 'image/gif' | 'image/webp' | 'image/avif' | 'image/bmp';
1612
+ ```
1613
+
1293
1614
  ## `@trismegisto/angular/input`
1294
1615
 
1295
1616
  - `InputType`
@@ -1457,7 +1778,7 @@ type LegendOrientation = 'horizontal' | 'vertical';
1457
1778
  type LegendMarker = 'dot' | 'square' | 'line';
1458
1779
  ```
1459
1780
 
1460
- - `LegendItem` — Um item da legenda.
1781
+ - `LegendItem`
1461
1782
 
1462
1783
  ```ts
1463
1784
  interface LegendItem {
@@ -1563,7 +1884,7 @@ type MessageScrollerLive = 'polite' | 'off';
1563
1884
 
1564
1885
  ## `@trismegisto/angular/navigation-menu`
1565
1886
 
1566
- - **`HermesNavigationMenu`** (classe) — Contrato que `hm-navigation-menu` publica por injeção para os itens e links dentro dele.
1887
+ - **`HermesNavigationMenu`** (classe) — Token de injeção que `hm-navigation-menu` fornece aos itens e links filhos. Os filhos dependem só desta classe abstrata, nunca do componente concreto.
1567
1888
 
1568
1889
  ```ts
1569
1890
  abstract class HermesNavigationMenu {
@@ -1575,10 +1896,6 @@ abstract class HermesNavigationMenu {
1575
1896
  - `NavigationMenuItemComponent` — `hm-navigation-menu-item` (ver angular-api.md)
1576
1897
  - `NavigationMenuLinkComponent` — `hm-navigation-menu-link` (ver angular-api.md)
1577
1898
 
1578
- ## `@trismegisto/angular/opening-scene`
1579
-
1580
- - `OpeningSceneComponent` — `hm-opening-scene` (ver angular-api.md)
1581
-
1582
1899
  ## `@trismegisto/angular/page-header`
1583
1900
 
1584
1901
  - `PageHeaderLevel`
@@ -1591,7 +1908,7 @@ type PageHeaderLevel = 1 | 2 | 3 | 4 | 5 | 6;
1591
1908
 
1592
1909
  ## `@trismegisto/angular/paginator`
1593
1910
 
1594
- - `PaginatorVariant` — `full`: pontas, números e itens por página. `simple`: só anterior/próxima (+ "Página X").
1911
+ - `PaginatorVariant`
1595
1912
 
1596
1913
  ```ts
1597
1914
  type PaginatorVariant = 'full' | 'simple';
@@ -1729,13 +2046,13 @@ interface RadioOption {
1729
2046
  }
1730
2047
  ```
1731
2048
 
1732
- - `RadioAppearance` — Desenho do grupo: lista de rádios (padrão) ou cartões clicáveis (opção explicada, com ícone).
2049
+ - `RadioAppearance` — `list` (padrão): círculo ao lado do texto. `card`: cada opção vira um cartão clicável.
1733
2050
 
1734
2051
  ```ts
1735
2052
  type RadioAppearance = 'list' | 'card';
1736
2053
  ```
1737
2054
 
1738
- - `RadioLayout` — Disposição das opções: `'stacked'` (padrão, uma por linha) ou `'inline'` (lado a lado, quebrando linha sem espaço).
2055
+ - `RadioLayout` — `stacked` (padrão): uma opção por linha. `inline`: lado a lado, quebrando linha.
1739
2056
 
1740
2057
  ```ts
1741
2058
  type RadioLayout = 'stacked' | 'inline';
@@ -1791,6 +2108,11 @@ interface ReorderListItemContext {
1791
2108
 
1792
2109
  - `ReorderListComponent` — `hm-reorder-list` (ver angular-api.md)
1793
2110
 
2111
+ ## `@trismegisto/angular/rich-text`
2112
+
2113
+ - `RichTextComponent` — `hm-rich-text` (ver angular-api.md)
2114
+ - `const RichTextValidators =` — Validadores para o valor do `hm-rich-text` (HTML canônico). `Validators.required` do Angular já funciona sem adaptação: o documento vazio vale `''`.
2115
+
1794
2116
  ## `@trismegisto/angular/search-field`
1795
2117
 
1796
2118
  - `SearchFieldSize`
@@ -1835,6 +2157,7 @@ type SegmentedControlEmphasis = 'subtle' | 'action';
1835
2157
  ## `@trismegisto/angular/session-recovery`
1836
2158
 
1837
2159
  - `SessionRecoveryComponent` — `hm-session-recovery` (ver angular-api.md)
2160
+ - `function safeReturnUrl(origin: string | null | undefined, document: Document, allowed?: readonly string[] | null): string | null` — `origin` resolvido contra a página e validado: só `http:`/`https:` e, com `allowed`, só a mesma origem da página ou uma das listadas. Devolve o `href` normalizado ou `null`.
1838
2161
 
1839
2162
  ## `@trismegisto/angular/settings`
1840
2163
 
@@ -1936,7 +2259,7 @@ class HermesShortcutService {
1936
2259
  ## `@trismegisto/angular/sidebar`
1937
2260
 
1938
2261
  - `SidebarGroupComponent` — `hm-sidebar-group` (ver angular-api.md)
1939
- - **`HermesSidebarGroup`** (classe) — Contrato que `hm-sidebar-group` publica por injeção para o que está dentro dele (`hm-sidebar-link` e grupos aninhados). Em arquivo próprio para não fechar um ciclo de importação entre o link e o grupo.
2262
+ - **`HermesSidebarGroup`** (classe) — O que um `hm-sidebar-group` oferece por injeção aos links e grupos dentro dele.
1940
2263
 
1941
2264
  ```ts
1942
2265
  abstract class HermesSidebarGroup {
@@ -1944,7 +2267,7 @@ abstract class HermesSidebarGroup {
1944
2267
  ```
1945
2268
 
1946
2269
  - `SidebarLinkComponent` — `hm-sidebar-link` (ver angular-api.md)
1947
- - `SidebarNode` — Um nó da árvore de navegação que o `hm-sidebar-node` sabe desenhar. Genérico: não conhece rota nem domínio.
2270
+ - `SidebarNode` — Um nó da árvore de navegação: folha vira link; nó com filhos visíveis vira grupo.
1948
2271
 
1949
2272
  ```ts
1950
2273
  interface SidebarNode {
@@ -1959,7 +2282,7 @@ interface SidebarNode {
1959
2282
 
1960
2283
  - `SidebarNodeComponent` — `hm-sidebar-node` (ver angular-api.md)
1961
2284
  - `SidebarComponent` — `hm-sidebar` (ver angular-api.md)
1962
- - `const HERMES_SIDEBAR_CONFIG = new InjectionToken<Pick<SidebarStoreOptions, 'storageKey' | 'defaultMode'>>`
2285
+ - `const HERMES_SIDEBAR_CONFIG = new InjectionToken<Pick<SidebarStoreOptions, 'storageKey' | 'defaultMode'>>` — Chave de gravação e modo inicial da navegação lateral (o spine fornece `{ storageKey: `${ns}_sidebar` }`).
1963
2286
  - **`HermesSidebarService`** (classe)
1964
2287
 
1965
2288
  ```ts
@@ -1970,19 +2293,19 @@ class HermesSidebarService {
1970
2293
  readonly overlaid = computed(…)
1971
2294
  readonly mobileOpen = computed(…)
1972
2295
  readonly groups = computed(…)
1973
- setMode(mode: SidebarMode): void { this.store.setMode(mode); }
1974
- peekPointer(inside: boolean): void { this.store.peekPointer(inside); }
1975
- peekFocus(inside: boolean): void { this.store.peekFocus(inside); }
1976
- toggleMobile(): void { this.store.toggleMobile(); }
1977
- closeMobile(): void { this.store.closeMobile(); }
1978
- ensureExpanded(): void { this.store.ensureExpanded(); }
2296
+ setMode(mode: SidebarMode): void
2297
+ peekPointer(inside: boolean): void
2298
+ peekFocus(inside: boolean): void
2299
+ toggleMobile(): void
2300
+ closeMobile(): void
2301
+ ensureExpanded(): void
1979
2302
  isGroupOpen(id: string, byDefault: boolean): boolean
1980
- setGroupOpen(id: string, open: boolean): void { this.store.setGroupOpen(id, open); }
1981
- resetGroups(): void { this.store.resetGroups(); }
1982
- registerGroup(id: string): void { this.store.registerGroup(id); }
1983
- unregisterGroup(id: string): void { this.store.unregisterGroup(id); }
1984
- setAllGroups(open: boolean): void { this.store.setAllGroups(open); }
1985
- get doc(): Document { return this.document; }
2303
+ setGroupOpen(id: string, open: boolean): void
2304
+ resetGroups(): void
2305
+ registerGroup(id: string): void
2306
+ unregisterGroup(id: string): void
2307
+ setAllGroups(open: boolean): void
2308
+ get doc(): Document
1986
2309
  }
1987
2310
  ```
1988
2311
 
@@ -2035,13 +2358,13 @@ type SpinnerSize = 'small' | 'medium' | 'large';
2035
2358
 
2036
2359
  ## `@trismegisto/angular/stat-card`
2037
2360
 
2038
- - `StatCardSize` — Escala de tamanho do cartão: muda o destaque do valor, o disco do ícone e o respiro.
2361
+ - `StatCardSize` — Escala do cartão: disco do ícone, corpo do valor e (em `large`) o respiro interno.
2039
2362
 
2040
2363
  ```ts
2041
2364
  type StatCardSize = 'small' | 'medium' | 'large';
2042
2365
  ```
2043
2366
 
2044
- - `StatCardDetail` — Um fragmento do detalhamento (`23 MPLS`, `19 Internet`), com um ponto colorido opcional.
2367
+ - `StatCardDetail` — Um pedaço do detalhamento do número (ex.: quantos de cada tipo), com marcador colorido opcional.
2045
2368
 
2046
2369
  ```ts
2047
2370
  interface StatCardDetail {
@@ -2050,13 +2373,13 @@ interface StatCardDetail {
2050
2373
  }
2051
2374
  ```
2052
2375
 
2053
- - `StatCardTrendDirection` — Direção da variação. A seta e o texto lido pelo leitor de tela vêm dela.
2376
+ - `StatCardTrendDirection`
2054
2377
 
2055
2378
  ```ts
2056
2379
  type StatCardTrendDirection = 'up' | 'down' | 'flat';
2057
2380
  ```
2058
2381
 
2059
- - `StatCardTrend` — Variação do número em relação a um período (`+8%` em relação à semana passada). A direção (alta/queda) não diz se é bom ou ruim — isso é `intent`: alta de incidentes é `danger`.
2382
+ - `StatCardTrend` — Variação do número. `direction` e `intent` são eixos separados: uma alta pode ser ruim (mais falhas → `danger`). `value` chega formatado; `label` diz contra o que se compara.
2060
2383
 
2061
2384
  ```ts
2062
2385
  interface StatCardTrend {
@@ -2071,7 +2394,7 @@ interface StatCardTrend {
2071
2394
 
2072
2395
  ## `@trismegisto/angular/stat-group`
2073
2396
 
2074
- - `StatGroupMetric` — Uma métrica do grupo: `{ label: 'Concluídos', value: '28', caption: 'hoje' }`.
2397
+ - `StatGroupMetric` — Um par rótulo/valor do grupo; `caption` é a legenda sob o valor e `intent` vence o tom do grupo.
2075
2398
 
2076
2399
  ```ts
2077
2400
  interface StatGroupMetric {
@@ -2127,7 +2450,7 @@ interface StatePagePreset extends StatePageVisual {
2127
2450
 
2128
2451
  ## `@trismegisto/angular/state-screen`
2129
2452
 
2130
- - `StateScreenSituation` — As situações de feedback que a tela cobre. O nome descreve o **estado da tela**, não a ilustração: quem escolhe o desenho é a situação.
2453
+ - `StateScreenSituation` — Situação mostrada; escolhe a ilustração padrão.
2131
2454
 
2132
2455
  ```ts
2133
2456
  type StateScreenSituation =
@@ -2147,13 +2470,20 @@ type StateScreenSituation =
2147
2470
 
2148
2471
  ## `@trismegisto/angular/stepper`
2149
2472
 
2150
- - `HermesStepGuard` — Pergunta assíncrona ou síncrona "a etapa pode avançar?", feita ao clicar em Avançar.
2473
+ - **`HermesStepGroup`** (classe) — O que um `hm-step` consulta no componente que o agrupa. O `hm-stepper` fornece este token, e um componente que o embrulhe (o `hm-wizard`, por exemplo) pode fornecê-lo no lugar dele.
2474
+
2475
+ ```ts
2476
+ abstract class HermesStepGroup {
2477
+ }
2478
+ ```
2479
+
2480
+ - `HermesStepGuard` — Guarda extra antes de sair adiante de uma etapa. `false`, exceção ou rejeição seguram a etapa.
2151
2481
 
2152
2482
  ```ts
2153
2483
  type HermesStepGuard = () => boolean | Promise<boolean>;
2154
2484
  ```
2155
2485
 
2156
- - `HermesStepSummaryEntry` — Um par termo/valor do resumo de uma etapa (o mesmo formato do `[items]` do `hm-description-list`).
2486
+ - `HermesStepSummaryEntry`
2157
2487
 
2158
2488
  ```ts
2159
2489
  interface HermesStepSummaryEntry {
@@ -2162,7 +2492,7 @@ interface HermesStepSummaryEntry {
2162
2492
  }
2163
2493
  ```
2164
2494
 
2165
- - `HermesStepSummary` — O que a etapa coletou, para a página de resumo do `hm-wizard` (`summary`): um template (conteúdo livre) ou uma função que devolve os pares termo/valor — chamada na hora em que o resumo aparece, com os valores atuais do…
2495
+ - `HermesStepSummary` — O que a etapa resume na página de revisão do `hm-wizard`: um template ou pares termo/valor.
2166
2496
 
2167
2497
  ```ts
2168
2498
  type HermesStepSummary = TemplateRef<unknown> | (() => readonly HermesStepSummaryEntry[]);
@@ -2176,16 +2506,10 @@ type StepperOrientation = 'horizontal' | 'vertical';
2176
2506
  ```
2177
2507
 
2178
2508
  - `StepperComponent` — `hm-stepper` (ver angular-api.md)
2179
- - **`HermesStepGroup`** (classe) — Contrato que `hm-stepper` (e `hm-wizard`, que delega ao stepper interno) publica por injeção para os `hm-step` dentro dele.
2180
-
2181
- ```ts
2182
- abstract class HermesStepGroup {
2183
- }
2184
- ```
2185
2509
 
2186
2510
  ## `@trismegisto/angular/switch`
2187
2511
 
2188
- - `SwitchLabelPosition` — De que lado do controle o rótulo fica.
2512
+ - `SwitchLabelPosition`
2189
2513
 
2190
2514
  ```ts
2191
2515
  type SwitchLabelPosition = 'before' | 'after';
@@ -2195,7 +2519,7 @@ type SwitchLabelPosition = 'before' | 'after';
2195
2519
 
2196
2520
  ## `@trismegisto/angular/tab-bar`
2197
2521
 
2198
- - `TabDragData` — Dados de uma aba em arrasto (o `data()` do item no serviço de arrastar e soltar, tipo `TAB_DRAG_TYPE`).
2522
+ - `TabDragData` — Dados de uma aba em arrasto (o que uma zona de soltura enxerga em `item.data()`).
2199
2523
 
2200
2524
  ```ts
2201
2525
  interface TabDragData {
@@ -2205,7 +2529,7 @@ interface TabDragData {
2205
2529
  }
2206
2530
  ```
2207
2531
 
2208
- - `TabReceivedEvent` — Aba de outra fileira do mesmo `tabGroup` solta nesta (`tabReceived`).
2532
+ - `TabReceivedEvent` — Aba de outra fileira do mesmo grupo solta nesta.
2209
2533
 
2210
2534
  ```ts
2211
2535
  interface TabReceivedEvent {
@@ -2216,7 +2540,7 @@ interface TabReceivedEvent {
2216
2540
  ```
2217
2541
 
2218
2542
  - `TabBarComponent` — `hm-tab-bar` (ver angular-api.md)
2219
- - `TabItem` _(de `@trismegisto/primitives`)_ — Barra de abas "de navegador" (SDD): escolher, fechar, reordenar e arrastar para fora. Sem framework — a lógica de teclado, arrasto e o estado das abas abertas, que qualquer wrapper (Angular, React) usa do mesmo jeito.
2543
+ - `TabItem` _(de `@trismegisto/primitives`)_ — Uma aba aberta. `icon` é um nome do catálogo de ícones; `pinned` tira o X e impede o fechamento pelo store.
2220
2544
 
2221
2545
  ```ts
2222
2546
  interface TabItem {
@@ -2231,26 +2555,26 @@ interface TabItem {
2231
2555
 
2232
2556
  - `TabComponent` — `hm-tab` (ver angular-api.md)
2233
2557
  - `TabsComponent` — `hm-tabs` (ver angular-api.md)
2234
- - **`HermesTabGroup`** (classe) — Contrato que `hm-tabs` publica por injeção para os `hm-tab` dentro dele.
2558
+ - **`HermesTabGroup`** (classe) — O que o `hm-tabs` oferece por injeção aos `hm-tab` que ele contém.
2235
2559
 
2236
2560
  ```ts
2237
2561
  abstract class HermesTabGroup {
2238
2562
  }
2239
2563
  ```
2240
2564
 
2241
- - `HermesTabsMode` — `tabs`: tablist com painéis (padrão). `nav`: links de rota com `aria-current="page"`.
2565
+ - `HermesTabsMode` — `tabs`: lista de abas com painéis; `nav`: subnavegação por rotas, sem painel.
2242
2566
 
2243
2567
  ```ts
2244
2568
  type HermesTabsMode = 'tabs' | 'nav';
2245
2569
  ```
2246
2570
 
2247
- - `HermesTabsOrientation` — Direção da faixa de abas (WAI-ARIA APG: ←/→ no horizontal, ↑/↓ no vertical).
2571
+ - `HermesTabsOrientation`
2248
2572
 
2249
2573
  ```ts
2250
2574
  type HermesTabsOrientation = 'horizontal' | 'vertical';
2251
2575
  ```
2252
2576
 
2253
- - `HermesTabsOverflow` — O que fazer quando as abas não cabem na faixa horizontal: `menu` (padrão) leva as que sobram para o botão "Mais"; `wrap` mantém o comportamento antigo (a fileira quebra/rola).
2577
+ - `HermesTabsOverflow` — O que fazer com as abas que não cabem na faixa horizontal: menu "Mais" ou quebrar em linhas.
2254
2578
 
2255
2579
  ```ts
2256
2580
  type HermesTabsOverflow = 'menu' | 'wrap';
@@ -2260,7 +2584,7 @@ type HermesTabsOverflow = 'menu' | 'wrap';
2260
2584
 
2261
2585
  ## `@trismegisto/angular/tag`
2262
2586
 
2263
- - `TagColor` — Cor semântica da etiqueta — o mesmo vocabulário de `hm-button`/`hm-badge`/`hm-icon`/`hm-progress` e dos tokens (`--hm-danger`): `danger` é o vermelho de erro/perigo. `error` continua aceito como apelido **depreciado** d…
2587
+ - `TagColor` — Cor da etiqueta. `error` é o nome antigo de `danger` (depreciado; continua funcionando).
2264
2588
 
2265
2589
  ```ts
2266
2590
  type TagColor = 'primary' | 'info' | 'success' | 'warning' | 'danger' | 'neutral' | 'error';
@@ -2587,7 +2911,7 @@ class HermesMenuItemHarness extends ComponentHarness {
2587
2911
  }
2588
2912
  ```
2589
2913
 
2590
- - **`HermesMenuHarness`** (classe) — O cartão de um `hm-menu` aberto. Ele é movido para o `<body>` ao abrir, então procure com o loader da raiz do documento (`TestbedHarnessEnvironment.documentRootLoader(fixture)`) — ou, mais simples, use o `HermesMenuButt…
2914
+ - **`HermesMenuHarness`** (classe) — O cartão de um `hm-menu` aberto. Aberto, ele vive no `<body>`, então procure com o loader da raiz do documento (`TestbedHarnessEnvironment.documentRootLoader(fixture)`) — ou, mais simples, use o `HermesMenuButtonHarness…
2591
2915
 
2592
2916
  ```ts
2593
2917
  class HermesMenuHarness extends ComponentHarness {
@@ -2749,14 +3073,14 @@ class HermesDataGridHarness extends ComponentHarness {
2749
3073
 
2750
3074
  ## `@trismegisto/angular/textarea`
2751
3075
 
2752
- - `TextareaSubmitKey` — Tecla que envia (`submitted`): `none` (padrão — Enter só quebra linha), `mod-enter` (Ctrl+Enter, ou Cmd+Enter no macOS) ou `enter` (Enter envia, Shift+Enter quebra linha — padrão de conversa).
3076
+ - `TextareaSubmitKey` — Tecla que envia o texto (`submitted`): nunca, Ctrl/⌘+Enter, ou Enter (Shift+Enter quebra linha).
2753
3077
 
2754
3078
  ```ts
2755
3079
  type TextareaSubmitKey = 'none' | 'mod-enter' | 'enter';
2756
3080
  ```
2757
3081
 
2758
3082
  - `TextareaComponent` — `hm-textarea` (ver angular-api.md)
2759
- - `TextareaAddonSlot` — Onde o conteúdo projetado entra no `hm-textarea`.
3083
+ - `TextareaAddonSlot`
2760
3084
 
2761
3085
  ```ts
2762
3086
  type TextareaAddonSlot = 'prefix' | 'suffix' | 'actions' | 'actionsEnd';
@@ -2841,7 +3165,7 @@ class HermesToastService {
2841
3165
 
2842
3166
  ## `@trismegisto/angular/toggle-group`
2843
3167
 
2844
- - **`HermesToggleGroup`** (classe) — Contrato que `hm-toggle-group` publica por injeção para os `hm-toggle-group-item` dentro dele.
3168
+ - **`HermesToggleGroup`** (classe) — O que um `hm-toggle-group-item` enxerga do `hm-toggle-group` que o contém (fornecido por DI).
2845
3169
 
2846
3170
  ```ts
2847
3171
  abstract class HermesToggleGroup {
@@ -2877,7 +3201,7 @@ type ToggleGroupOrientation = 'horizontal' | 'vertical';
2877
3201
 
2878
3202
  ## `@trismegisto/angular/toggletip`
2879
3203
 
2880
- - `ToggletipSide` — Lado preferido de abertura do balão; ele vira sozinho quando não cabe.
3204
+ - `ToggletipSide`
2881
3205
 
2882
3206
  ```ts
2883
3207
  type ToggletipSide = 'bottom' | 'top';
@@ -2895,13 +3219,13 @@ type ToggletipSide = 'bottom' | 'top';
2895
3219
 
2896
3220
  ## `@trismegisto/angular/tree`
2897
3221
 
2898
- - `TreeCanDrop` — Pode soltar `node` em `position` de `target`? (`canDrop` do hm-tree).
3222
+ - `TreeCanDrop` — Decide se `node` pode ser solto em `position` relativo a `target`.
2899
3223
 
2900
3224
  ```ts
2901
3225
  type TreeCanDrop = (node: TreeNode, target: TreeNode, position: TreeDropPosition) => boolean;
2902
3226
  ```
2903
3227
 
2904
- - `TreeMoveEvent` — Nó solto em outro lugar (`moved`). O hm-tree não muda `nodes`: aplique com `moveTreeNode`.
3228
+ - `TreeMoveEvent` — Nó solto num lugar novo. `from`/`to` são as localizações antes e depois (índice já sem a origem).
2905
3229
 
2906
3230
  ```ts
2907
3231
  interface TreeMoveEvent {
@@ -2914,7 +3238,7 @@ interface TreeMoveEvent {
2914
3238
  }
2915
3239
  ```
2916
3240
 
2917
- - `TreeNodeActionEvent` — Ação escolhida no menu de contexto de um nó (`nodeAction`).
3241
+ - `TreeNodeActionEvent`
2918
3242
 
2919
3243
  ```ts
2920
3244
  interface TreeNodeActionEvent {
@@ -2923,13 +3247,13 @@ interface TreeNodeActionEvent {
2923
3247
  }
2924
3248
  ```
2925
3249
 
2926
- - `TreeNodeActions` — Itens do menu de contexto: os mesmos para todo nó, ou filtrados/calculados por nó.
3250
+ - `TreeNodeActions` — Itens do menu de contexto: a mesma lista para todos ou calculada por nó.
2927
3251
 
2928
3252
  ```ts
2929
3253
  type TreeNodeActions = readonly MenuItem[] | ((node: TreeNode) => readonly MenuItem[]);
2930
3254
  ```
2931
3255
 
2932
- - `TreeLoadContext` — Onde a carga está: quantos filhos do nó já chegaram e qual página é esta (0 = a primeira).
3256
+ - `TreeLoadContext` — Qual página pedir: `offset` = filhos já recebidos, `page` = páginas já recebidas.
2933
3257
 
2934
3258
  ```ts
2935
3259
  interface TreeLoadContext {
@@ -2938,7 +3262,7 @@ interface TreeLoadContext {
2938
3262
  }
2939
3263
  ```
2940
3264
 
2941
- - `TreeChildrenLoader` — Carregador de filhos sob demanda — Promise ou Observable (o primeiro valor vale). Devolve a lista inteira (forma de sempre) ou uma página `{ children, hasMore }`: com `hasMore`, a árvore mostra "Carregar mais" no fim do…
3265
+ - `TreeChildrenLoader`
2942
3266
 
2943
3267
  ```ts
2944
3268
  type TreeChildrenLoader = (
@@ -2947,7 +3271,7 @@ type TreeChildrenLoader = (
2947
3271
  ) => Promise<TreeChildrenResult> | Observable<TreeChildrenResult>;
2948
3272
  ```
2949
3273
 
2950
- - `TreeNodeTemplateContext` — Contexto do template customizado de nó (`<ng-template hmTreeNode let-node let-row="row">`).
3274
+ - `TreeNodeTemplateContext`
2951
3275
 
2952
3276
  ```ts
2953
3277
  interface TreeNodeTemplateContext {
@@ -2959,7 +3283,7 @@ interface TreeNodeTemplateContext {
2959
3283
 
2960
3284
  - `TreeNodeTemplateDirective` — `ng-template[hmTreeNode]` (ver angular-api.md)
2961
3285
  - `TreeComponent` — `hm-tree` (ver angular-api.md)
2962
- - `TreeChildrenPage` _(de `@trismegisto/primitives`)_ — Uma página de filhos: o que chegou e se ainda há mais para pedir ("carregar mais").
3286
+ - `TreeChildrenPage` _(de `@trismegisto/primitives`)_
2963
3287
 
2964
3288
  ```ts
2965
3289
  interface TreeChildrenPage {
@@ -2968,19 +3292,19 @@ interface TreeChildrenPage {
2968
3292
  }
2969
3293
  ```
2970
3294
 
2971
- - `TreeChildrenResult` _(de `@trismegisto/primitives`)_ — O que um `loadChildren` pode devolver: a lista inteira (forma antiga) ou uma página.
3295
+ - `TreeChildrenResult` _(de `@trismegisto/primitives`)_
2972
3296
 
2973
3297
  ```ts
2974
3298
  type TreeChildrenResult = readonly TreeNode[] | TreeChildrenPage;
2975
3299
  ```
2976
3300
 
2977
- - `TreeDropPosition` _(de `@trismegisto/primitives`)_ — Onde soltar em relação ao nó-alvo: antes, dentro (último filho) ou depois.
3301
+ - `TreeDropPosition` _(de `@trismegisto/primitives`)_
2978
3302
 
2979
3303
  ```ts
2980
3304
  type TreeDropPosition = DropPosition;
2981
3305
  ```
2982
3306
 
2983
- - `TreeLocation` _(de `@trismegisto/primitives`)_ — Lugar de um nó: id do pai (`null` = raiz) e posição entre os irmãos (a partir de 0).
3307
+ - `TreeLocation` _(de `@trismegisto/primitives`)_
2984
3308
 
2985
3309
  ```ts
2986
3310
  interface TreeLocation {
@@ -3014,7 +3338,7 @@ interface TreeSelectionChange {
3014
3338
  }
3015
3339
  ```
3016
3340
 
3017
- - `TreeSelectionMode` _(de `@trismegisto/primitives`)_ — `none`: só ativa; `single`: um nó por vez; `multiple`: vários, com Ctrl/Shift e Ctrl+A.
3341
+ - `TreeSelectionMode` _(de `@trismegisto/primitives`)_
3018
3342
 
3019
3343
  ```ts
3020
3344
  type TreeSelectionMode = 'none' | 'single' | 'multiple';
@@ -3202,13 +3526,13 @@ enum HermesLoadingState {
3202
3526
  }
3203
3527
  ```
3204
3528
 
3205
- - `AlertVariant`
3529
+ - `AlertVariant` — Tom do alerta (também usado pelo toast).
3206
3530
 
3207
3531
  ```ts
3208
3532
  type AlertVariant = 'error' | 'warning' | 'info' | 'success';
3209
3533
  ```
3210
3534
 
3211
- - `ButtonEmphasis` — Montagem das classes CSS `hm-*` (definidas em @trismegisto/core) — igual em qualquer framework.
3535
+ - `ButtonEmphasis` — Nomes de classe CSS dos botões do `@trismegisto/core`. Ficam aqui (sem framework) porque também são usados direto no HTML, sem Angular, e por componentes que só "vestem" um elemento próprio como botão (upload de arquivo…
3212
3536
 
3213
3537
  ```ts
3214
3538
  type ButtonEmphasis = 'high' | 'medium' | 'minimal';
@@ -3232,7 +3556,7 @@ type ButtonSize = 'small' | 'medium' | 'large';
3232
3556
  type IconButtonEmphasis = 'filled' | 'outlined' | 'subtle';
3233
3557
  ```
3234
3558
 
3235
- - `ModalSize` — Degraus de largura dos overlays (`hm-modal`, `hm-drawer`, `hm-wizard`, `HermesDialogService`). `xlarge` é o degrau acima de `large` (tabelas, comparações lado a lado); `full` ocupa a tela inteira (sem véu à vista, sem c…
3559
+ - `ModalSize` — Tamanhos de diálogo (modal, drawer, wizard). Mora aqui por histórico do pacote.
3236
3560
 
3237
3561
  ```ts
3238
3562
  type ModalSize = 'small' | 'medium' | 'large' | 'xlarge' | 'full';
@@ -3240,7 +3564,7 @@ type ModalSize = 'small' | 'medium' | 'large' | 'xlarge' | 'full';
3240
3564
 
3241
3565
  - `HermesIcon`
3242
3566
  - `IconBadge`
3243
- - `MenuItem` — Pop-over e menu de contexto: posicionamento e teclado, sem DOM nem framework.
3567
+ - `MenuItem`
3244
3568
 
3245
3569
  ```ts
3246
3570
  interface MenuItem {
@@ -3284,7 +3608,7 @@ type MenuItemType = 'checkbox' | 'radio';
3284
3608
  type PopoverAlign = 'start' | 'center' | 'end';
3285
3609
  ```
3286
3610
 
3287
- - `PopoverAnchor` — Onde o menu abre, em coordenadas de viewport.
3611
+ - `PopoverAnchor` — De onde o cartão nasce, em px de viewport.
3288
3612
 
3289
3613
  ```ts
3290
3614
  interface PopoverAnchor {
@@ -3297,7 +3621,7 @@ interface PopoverAnchor {
3297
3621
  }
3298
3622
  ```
3299
3623
 
3300
- - `PopoverSide`
3624
+ - `PopoverSide` — Régua de posicionamento dos cartões ancorados (menus, dicas, popovers, listas de combobox) e o passo de teclado das listas verticais que eles mostram.
3301
3625
 
3302
3626
  ```ts
3303
3627
  type PopoverSide = 'top' | 'bottom' | 'left' | 'right';
@@ -3318,7 +3642,7 @@ interface TabBarState {
3318
3642
  }
3319
3643
  ```
3320
3644
 
3321
- - `TabReorder`
3645
+ - `TabReorder` — Pedido de mudança de posição: `index` é a posição final da aba.
3322
3646
 
3323
3647
  ```ts
3324
3648
  interface TabReorder {
@@ -3328,7 +3652,7 @@ interface TabReorder {
3328
3652
  ```
3329
3653
 
3330
3654
  - `function createTabBarStore(initial: TabBarState): TabBarStore`
3331
- - `AlertAppearance` — Onde o alerta mora: `inline` (padrão) é a caixa no meio do conteúdo; `banner` é a faixa de app no topo, largura total, sem cantos.
3655
+ - `AlertAppearance` — `inline` fica no fluxo do conteúdo; `banner` é a faixa de largura total do app.
3332
3656
 
3333
3657
  ```ts
3334
3658
  type AlertAppearance = 'inline' | 'banner';
@@ -3351,7 +3675,88 @@ interface FloatingRect {
3351
3675
  type FloatingWindowState = 'normal' | 'minimized' | 'maximized';
3352
3676
  ```
3353
3677
 
3354
- - `BulkCase` — Caixa aplicada a cada item depois do trim.
3678
+ - `RichTextTool` — Ferramentas da barra, na ordem; `'|'` separa grupos.
3679
+
3680
+ ```ts
3681
+ type RichTextTool =
3682
+ | 'bold'
3683
+ | 'italic'
3684
+ | 'underline'
3685
+ | 'strike'
3686
+ | 'code'
3687
+ | 'link'
3688
+ | 'blockType'
3689
+ | 'bulletList'
3690
+ | 'orderedList'
3691
+ | 'quote'
3692
+ | 'codeBlock'
3693
+ | 'undo'
3694
+ | 'redo'
3695
+ | 'clear'
3696
+ | '|';
3697
+ ```
3698
+
3699
+ - `RichTextFormatTool` — O que `apply()` executa: uma ferramenta (sem o separador e o menu de estilo) ou um tipo de bloco.
3700
+
3701
+ ```ts
3702
+ type RichTextFormatTool =
3703
+ | Exclude<RichTextTool, '|' | 'blockType'>
3704
+ | 'paragraph'
3705
+ | `heading${RichTextHeadingLevel}`;
3706
+ ```
3707
+
3708
+ - `RichTextHeadingLevel`
3709
+
3710
+ ```ts
3711
+ type RichTextHeadingLevel = 2 | 3 | 4;
3712
+ ```
3713
+
3714
+ - `RichTextPasteMode`
3715
+
3716
+ ```ts
3717
+ type RichTextPasteMode = 'formatted' | 'plain';
3718
+ ```
3719
+
3720
+ - `RichTextSchema`
3721
+
3722
+ ```ts
3723
+ interface RichTextSchema {
3724
+ readonly marks: number;
3725
+ readonly link: boolean;
3726
+ readonly headingLevels: readonly RichTextHeadingLevel[];
3727
+ readonly bulletList: boolean;
3728
+ readonly orderedList: boolean;
3729
+ readonly quote: boolean;
3730
+ readonly codeBlock: boolean;
3731
+ readonly protocols: readonly string[];
3732
+ readonly allowRelativeLinks: boolean;
3733
+ }
3734
+ ```
3735
+
3736
+ - `RichTextSchemaOptions`
3737
+
3738
+ ```ts
3739
+ interface RichTextSchemaOptions {
3740
+ readonly tools?: readonly RichTextTool[];
3741
+ readonly headingLevels?: readonly RichTextHeadingLevel[];
3742
+ readonly linkProtocols?: readonly string[];
3743
+ readonly allowRelativeLinks?: boolean;
3744
+ }
3745
+ ```
3746
+
3747
+ - `RichTextParser` — Adaptador de parser: `(html) => Document`. No navegador, o padrão é o `DOMParser`.
3748
+
3749
+ ```ts
3750
+ type RichTextParser = (html: string) => Document;
3751
+ ```
3752
+
3753
+ - `const RICH_TEXT_DEFAULT_TOOLS: readonly RichTextTool[]`
3754
+ - `function richTextSchema(options: RichTextSchemaOptions = {}): RichTextSchema` — Monta o esquema a partir das ferramentas, níveis de título e regras de link da instância.
3755
+ - `function sanitizeRichText(html: unknown, schema: RichTextSchema = richTextSchema(), parse?: RichTextParser): string` — Entrada qualquer → HTML canônico (§5 da especificação). Vazio, `null` ou não-string → `''`.
3756
+ - `function richTextPlainText(html: string): string` — Texto puro de um HTML (canônico): blocos por `\n`, `br` → `\n`, entidades decodificadas.
3757
+ - `function richTextLength(html: string): number` — Contagem de caracteres (grafemas, sem quebras de linha) de um HTML.
3758
+ - `function normalizeRichTextUrl(raw: string, schema: RichTextSchema = richTextSchema()): string | null` — URL digitada ou recebida → `href` aceito, ou `null`. Esquema comparado em minúsculas com os protocolos do esquema, depois de tirar espaços/caracteres de controle no meio dele (`java\tscript:` é `javascript:`); `//host`…
3759
+ - `BulkCase`
3355
3760
 
3356
3761
  ```ts
3357
3762
  type BulkCase = 'preserve' | 'lower' | 'upper';
@@ -3367,7 +3772,7 @@ interface BulkInvalidItem {
3367
3772
  }
3368
3773
  ```
3369
3774
 
3370
- - `BulkInvalidReason` — `format`: reprovado pela validação sem texto próprio; `custom`: com o texto em `message`; `limit`: passou do máximo.
3775
+ - `BulkInvalidReason`
3371
3776
 
3372
3777
  ```ts
3373
3778
  type BulkInvalidReason = 'format' | 'custom' | 'limit';
@@ -3396,19 +3801,19 @@ interface BulkParseResult {
3396
3801
  }
3397
3802
  ```
3398
3803
 
3399
- - `BulkSeparator` — Separadores aceitos. `space` fica fora do padrão: nome de pessoa tem espaço.
3804
+ - `BulkSeparator` — Entrada em lote: um texto colado (lista do Excel, e-mails separados por vírgula, códigos um por linha) vira uma lista de itens válidos, mais o relatório do que foi recusado. Sem framework.
3400
3805
 
3401
3806
  ```ts
3402
3807
  type BulkSeparator = 'newline' | 'comma' | 'semicolon' | 'space' | 'tab';
3403
3808
  ```
3404
3809
 
3405
- - `BulkValidator` — Validação do app. Regex: vale o que casa. Função: `true` (ou `null`/`undefined`/`''`) vale; `false` é inválido com o motivo padrão; uma string é inválido com ESSE motivo (texto do app, já no idioma dele).
3810
+ - `BulkValidator`
3406
3811
 
3407
3812
  ```ts
3408
3813
  type BulkValidator = RegExp | ((item: string) => boolean | string | null | undefined);
3409
3814
  ```
3410
3815
 
3411
- - `UploadFile` — Um arquivo na lista do `hm-file-upload`. Imutável: mudanças geram um objeto novo.
3816
+ - `UploadFile` — Um arquivo na lista do campo, com a situação do envio.
3412
3817
 
3413
3818
  ```ts
3414
3819
  interface UploadFile<F extends FileLike = File> {
@@ -3420,13 +3825,13 @@ interface UploadFile<F extends FileLike = File> {
3420
3825
  }
3421
3826
  ```
3422
3827
 
3423
- - `UploadFilePatch` — O que dá para mudar num item depois de criado.
3828
+ - `UploadFilePatch`
3424
3829
 
3425
3830
  ```ts
3426
3831
  type UploadFilePatch = Partial<Pick<UploadFile<FileLike>, 'status' | 'progress' | 'error'>>;
3427
3832
  ```
3428
3833
 
3429
- - `FileUploadStatus` — Situação de um arquivo na lista: na fila, enviando, enviado, falhou.
3834
+ - `FileUploadStatus`
3430
3835
 
3431
3836
  ```ts
3432
3837
  type FileUploadStatus = 'pending' | 'uploading' | 'done' | 'error';
@@ -3441,19 +3846,19 @@ interface FileRejection<F extends FileLike = File> {
3441
3846
  }
3442
3847
  ```
3443
3848
 
3444
- - `FileRejectionReason` — Por que um arquivo não entrou na lista.
3849
+ - `FileRejectionReason`
3445
3850
 
3446
3851
  ```ts
3447
3852
  type FileRejectionReason = 'type' | 'size' | 'totalSize' | 'count' | 'duplicate';
3448
3853
  ```
3449
3854
 
3450
- - `PageWindowItem` — A janela de números de página em volta da atual — desliza em vez de paginar em blocos, então ir de 7 pra 8 não troca a fileira inteira. Pontas sempre visíveis, com "salto" (reticências) no meio quando há intervalo.
3855
+ - `PageWindowItem`
3451
3856
 
3452
3857
  ```ts
3453
3858
  type PageWindowItem = number | 'gap';
3454
3859
  ```
3455
3860
 
3456
- - `PaginationState` — Paginação client-side: fatia uma lista já filtrada (e, se aplicável, ordenada). Não sabe de onde vem a lista nem em que critério está — só corta por página e tamanho.
3861
+ - `PaginationState` — Paginação como funções puras sobre `{ page, size }` (página 1-based). Nada aqui sabe de onde vem a lista: quem chama informa o total de itens quando a operação depende dele.
3457
3862
 
3458
3863
  ```ts
3459
3864
  interface PaginationState {
@@ -3498,7 +3903,7 @@ interface DisplayDatePattern {
3498
3903
  - `function displayDatePattern(locale: string): DisplayDatePattern`
3499
3904
  - `function formatDisplayDate(value: string | null | undefined, pattern: DisplayDatePattern = DEFAULT_DATE_PATTERN): string` — ISO → texto no padrão do idioma (vazio se inválido).
3500
3905
  - `function parseDisplayDate(text: string, pattern: DisplayDatePattern = DEFAULT_DATE_PATTERN): IsoDate | null` — Texto digitado no padrão do idioma → ISO; data que não existe (31/02) → null.
3501
- - `GridColumn` — Definição de coluna. `value` devolve o texto já formatado que a célula mostra; `raw` (quando existe) devolve o valor comparável/filtrável — separar os dois é o que permite filtrar por `>18` numa coluna que exibe "18 ano…
3906
+ - `GridColumn`
3502
3907
 
3503
3908
  ```ts
3504
3909
  interface GridColumn<T> {
@@ -3519,7 +3924,7 @@ interface GridColumn<T> {
3519
3924
  }
3520
3925
  ```
3521
3926
 
3522
- - `GridColumnState` — Preferência da pessoa sobre uma coluna — separada da definição, que é de quem desenvolve.
3927
+ - `GridColumnState`
3523
3928
 
3524
3929
  ```ts
3525
3930
  interface GridColumnState {
@@ -3529,19 +3934,19 @@ interface GridColumnState {
3529
3934
  }
3530
3935
  ```
3531
3936
 
3532
- - `GridColumnType`
3937
+ - `GridColumnType` — Motor puro do `hm-data-grid`: definição de coluna, estado das colunas, ordenação, seleção por id, busca global e filtro por coluna. Sem DOM nem framework — o componente Angular só liga isto a sinais.
3533
3938
 
3534
3939
  ```ts
3535
3940
  type GridColumnType = 'text' | 'number' | 'date' | 'boolean';
3536
3941
  ```
3537
3942
 
3538
- - `GridColumnFilterValue` — Filtro de UMA coluna — texto livre (substring, colunas sem poucos valores distintos) OU um conjunto de valores marcados (`columnFilterOptions` devolveu uma lista pra essa coluna). Nunca os dois ao mesmo tempo: o pop-ove…
3943
+ - `GridColumnFilterValue` — Texto livre (contém) ou lista de valores exibidos marcados.
3539
3944
 
3540
3945
  ```ts
3541
3946
  type GridColumnFilterValue = string | readonly string[];
3542
3947
  ```
3543
3948
 
3544
- - `GridFilterOption` — Um valor de opção, pro pop-over de filtro de uma coluna categórica.
3949
+ - `GridFilterOption`
3545
3950
 
3546
3951
  ```ts
3547
3952
  interface GridFilterOption {
@@ -3550,13 +3955,13 @@ interface GridFilterOption {
3550
3955
  }
3551
3956
  ```
3552
3957
 
3553
- - `GridSelection` — Seleção de linhas por id — persiste entre páginas de propósito: nunca se guarda "linhas selecionadas da página atual", sempre o conjunto completo de ids.
3958
+ - `GridSelection`
3554
3959
 
3555
3960
  ```ts
3556
3961
  type GridSelection = ReadonlySet<string>;
3557
3962
  ```
3558
3963
 
3559
- - `GridSort` — Ordenação de uma coluna; a prioridade é a posição na lista. O grid só GUARDA a intenção — quem reordena de verdade os dados é quem os possui (ver `hm-data-grid`'s doc: apresentacional).
3964
+ - `GridSort`
3560
3965
 
3561
3966
  ```ts
3562
3967
  interface GridSort {
@@ -3594,7 +3999,7 @@ type GridFilterOperator =
3594
3999
  type GridFilterConnector = 'and' | 'or';
3595
4000
  ```
3596
4001
 
3597
- - `GridFilterCondition` — Uma condição. `value`/`valueTo` são texto (número com `.` decimal, data `AAAA-MM-DD`, como os `<input type="number|date">` devolvem); `valueTo` só vale em `between`.
4002
+ - `GridFilterCondition`
3598
4003
 
3599
4004
  ```ts
3600
4005
  interface GridFilterCondition {
@@ -3606,7 +4011,7 @@ interface GridFilterCondition {
3606
4011
  }
3607
4012
  ```
3608
4013
 
3609
- - `GridFilterQuery` — Condições combinadas por um conector (todas = E, qualquer uma = OU).
4014
+ - `GridFilterQuery`
3610
4015
 
3611
4016
  ```ts
3612
4017
  interface GridFilterQuery {
@@ -3633,7 +4038,7 @@ type GridAggregates = Readonly<Record<string, GridAggregateFn>>;
3633
4038
  type GridAggregateFormatter = (value: number, fn: GridAggregateFn, key: string) => string;
3634
4039
  ```
3635
4040
 
3636
- - `GridCsvSeparator` — Separador de campo: `,` (RFC 4180), `;` (o que o Excel espera onde a vírgula é decimal) ou tab.
4041
+ - `GridCsvSeparator`
3637
4042
 
3638
4043
  ```ts
3639
4044
  type GridCsvSeparator = ',' | ';' | '\t';
@@ -3645,22 +4050,22 @@ type GridCsvSeparator = ',' | ';' | '\t';
3645
4050
  - `function menuRadioValue(items: readonly MenuItem[], group: string): string | null` — Valor do rádio marcado num grupo (`value` ou `id`), ou `null` se nenhum estiver marcado.
3646
4051
  - `const HOVER_OPEN_DELAY = 500` — Atraso padrão para abrir ao passar o mouse (ms): evita abrir em quem só cruza o gatilho.
3647
4052
  - `const HOVER_CLOSE_DELAY = 300` — Atraso padrão para fechar ao sair (ms): dá tempo de levar o mouse do gatilho até o cartão.
3648
- - `TimelineDateValue` — Valor aceito como data de um item: `Date`, ISO (`'2026-10-03T14:30'`) ou epoch em milissegundos.
4053
+ - `TimelineDateValue`
3649
4054
 
3650
4055
  ```ts
3651
4056
  type TimelineDateValue = Date | string | number | null | undefined;
3652
4057
  ```
3653
4058
 
3654
- - `TimelineOutcome` — Como o processo inteiro está: ainda correndo, concluído ou parado com falha.
4059
+ - `TimelineOutcome`
3655
4060
 
3656
4061
  ```ts
3657
4062
  type TimelineOutcome = 'running' | 'completed' | 'failed';
3658
4063
  ```
3659
4064
 
3660
- - `TimelineStatus` — Situação de um item: concluído, o atual, ainda não aconteceu, ou parou com erro.
4065
+ - `TimelineStatus` — Linha do tempo: a situação de cada marco de um processo que se acompanha (não se navega). A situação vem do próprio item quando ele a declara; senão é deduzida de qual é o marco atual e de como o processo terminou (ou s…
3661
4066
 
3662
4067
  ```ts
3663
- type TimelineStatus = 'completed' | 'current' | 'pending' | 'error';
4068
+ type TimelineStatus = 'completed' | 'current' | 'processing' | 'pending' | 'error';
3664
4069
  ```
3665
4070
 
3666
4071
  - `DualListItem`
@@ -3722,6 +4127,12 @@ type ShortcutKeyName =
3722
4127
  type ShortcutPlatform = 'mac' | 'other';
3723
4128
  ```
3724
4129
 
4130
+ - `CodeDiffLayout`
4131
+
4132
+ ```ts
4133
+ type CodeDiffLayout = 'split' | 'unified';
4134
+ ```
4135
+
3725
4136
  - `CertificateAltName`
3726
4137
 
3727
4138
  ```ts
@@ -3825,13 +4236,13 @@ type CertificateValidityState = 'valid' | 'expiring' | 'expired' | 'not-yet-vali
3825
4236
  type SplitterOrientation = 'horizontal' | 'vertical';
3826
4237
  ```
3827
4238
 
3828
- - `ToastVariant`
4239
+ - `ToastVariant` — Tom do alerta (também usado pelo toast).
3829
4240
 
3830
4241
  ```ts
3831
4242
  type AlertVariant = 'error' | 'warning' | 'info' | 'success';
3832
4243
  ```
3833
4244
 
3834
- - `ToastItem` — Um aviso na fila do canto da tela.
4245
+ - `ToastItem` — Um aviso na fila. `duration` 0 = só fecha quando alguém fecha (ou está pausado).
3835
4246
 
3836
4247
  ```ts
3837
4248
  interface ToastItem {
@@ -3863,7 +4274,7 @@ interface ToastState {
3863
4274
  }
3864
4275
  ```
3865
4276
 
3866
- - `ToastAction` — Ação de um aviso (ex.: "Desfazer"). `run` é chamado no clique e o aviso fecha em seguida.
4277
+ - `ToastAction` — Botão de ação do aviso ("Desfazer", "Ver detalhes").
3867
4278
 
3868
4279
  ```ts
3869
4280
  interface ToastAction {
@@ -3998,7 +4409,7 @@ interface WorkspaceStore {
3998
4409
  - `const DEFAULT_WORKSPACE_PERSISTENCE_CONFIG: WorkspacePersistenceConfig`
3999
4410
  - `function createWorkspaceStore(initialTabs: TabBarState): WorkspaceStore` — Cria a área de trabalho com um único painel, já com `initialTabs`. O id desse primeiro painel é gerado internamente (mesmo padrão de qualquer painel novo — quem consome nunca precisa inventar um id de painel).
4000
4411
  - `function cyclicPanelNeighbor(panelIds: readonly string[], panelId: string, step: 1 | -1): string | null` — Painel vizinho na ordem da árvore, cíclico (o último volta pro primeiro). `null` sem vizinho (um painel só, ou id desconhecido). Exportada pra a camada Angular usar a MESMA regra no item "mover para outro painel" do men…
4001
- - `function dropZone(rect: { readonly left: number; readonly top: number; readonly width: number; readonly height: number }, x: number, y: number): DropZone` — Borda do retângulo do painel mais perto do ponteiro — a faixa de borda é uma fração da dimensão do painel (`DROP_EDGE_FRACTION`), não um valor fixo, então um painel estreito não fica com uma borda maior que ele mesmo. A…
4412
+ - `function dropZone( rect: { readonly left: number; readonly top: number; readonly width: number; readonly height: number }, x: number, y: number, ): DropZone` — Região de um painel sob o ponteiro durante uma soltura. Cada borda tem uma faixa de `DROP_EDGE_FRACTION` da dimensão perpendicular a ela; fora de todas as faixas é o centro. Quando o ponto está em duas faixas (um canto)…
4002
4413
  - `function findPanelContainingTab(node: PanelNode, tabId: string): string | null` — Em qual painel (por id) mora a aba `tabId` — usado pra achar de onde uma aba arrastada saiu sem precisar de um segundo tipo de dado no `dataTransfer` (o `hm-tab-bar` não sabe o que é um "painel"; a árvore já sabe onde c…
4003
4414
  - `function findPanelTabs(node: PanelNode, panelId: string): TabBarState | null` — As abas do painel `panelId` (tabs + qual está ativa), ou `null` se o painel não existir mais na árvore — o que quem integra o workspace com um roteador de verdade precisa pra saber "qual é a aba ativa do painel focado a…
4004
4415
  - `function isValidPersistedWorkspace(value: unknown): value is PersistedWorkspace` — Nunca confia cegamente no que veio do storage — valida a forma inteira antes de aceitar (mesma regra de `readLanguage`/`readStoredTabs` já usadas nesta base).
@@ -4008,7 +4419,7 @@ interface WorkspaceStore {
4008
4419
  - `function saveWorkspace(state: WorkspaceState, config: WorkspacePersistenceConfig, storage: WorkspaceStorage | null): void` — Grava o estado atual. Try/catch mudo (cota estourada, modo privado, storage indisponível) — perder o arranjo salvo é aceitável, quebrar a aplicação por causa disso não é (mesmo padrão de `theme.ts`/`language.ts`). Debou…
4009
4420
  - `function toPersistedWorkspace(state: WorkspaceState): PersistedWorkspace` — `WorkspaceState` (com painéis/stores de verdade) → forma persistível.
4010
4421
  - `function workspaceKeyAction( event: Pick<KeyboardEvent, 'key' | 'ctrlKey' | 'altKey' | 'shiftKey'>, panelIds: readonly string[], focusedPanelId: string, ): WorkspaceKeyAction | null` — Atalhos do workspace com o foco num painel. Mover o foco (ou a aba) é cíclico na ordem da árvore (próximo/anterior) — suficiente pro MVP (no máximo poucos painéis, onde o vizinho "óbvio" já é cíclico). Navegação geométr…
4011
- - `CarouselSlide`
4422
+ - `CarouselSlide` — Um slide do `hm-carousel`. `image` vazio = slide só de texto; `alt` vazio = imagem decorativa.
4012
4423
 
4013
4424
  ```ts
4014
4425
  interface CarouselSlide {