@acropole/skills 1.2.0 → 1.3.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.
@@ -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 1.0.2, a cada `npm run sync` do @acropole/skills (junto com o `angular-api.md`).
4
4
 
5
5
  Tudo que cada `@trismegisto/angular/<ponto>` exporta: serviços (com os membros públicos), funções, constantes,
6
6
  tokens de injeção e tipos (com a declaração). Componentes, diretivas e pipes aparecem só pelo nome — inputs,
@@ -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';
@@ -400,7 +592,7 @@ interface DataGridFooterContext {
400
592
  }
401
593
  ```
402
594
 
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).
595
+ - `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
596
 
405
597
  ```ts
406
598
  type DataGridRowState = 'error' | 'warning';
@@ -412,7 +604,7 @@ type DataGridRowState = 'error' | 'warning';
412
604
  type DataGridRowDetail = 'enabled' | 'disabled' | 'hidden';
413
605
  ```
414
606
 
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…
607
+ - `DataGridColumn` _(de `@trismegisto/primitives`)_
416
608
 
417
609
  ```ts
418
610
  interface GridColumn<T> {
@@ -433,7 +625,7 @@ interface GridColumn<T> {
433
625
  }
434
626
  ```
435
627
 
436
- - `DataGridExportFormat` — `csv`: RFC 4180 (vírgula, sem BOM). `excel`: BOM UTF-8 e o separador do idioma (`;` em pt-BR/es).
628
+ - `DataGridExportFormat` — `csv` is plain RFC 4180; `excel` adds a BOM and the locale's list separator so spreadsheets open it right.
437
629
 
438
630
  ```ts
439
631
  type DataGridExportFormat = 'csv' | 'excel';
@@ -455,7 +647,7 @@ interface DataGridExportOptions {
455
647
  type DataGridPersistStorage = 'local' | 'session';
456
648
  ```
457
649
 
458
- - `DataGridSelectionMode` — `'single'` = rádio por linha (uma só); `'multiple'` = checkbox (o antigo `selectable`).
650
+ - `DataGridSelectionMode` — `'single'` = rádio por linha; `'multiple'` = caixa por linha e "selecionar todos" da página.
459
651
 
460
652
  ```ts
461
653
  type DataGridSelectionMode = 'none' | 'single' | 'multiple';
@@ -778,7 +970,7 @@ type DragListOrientation = 'vertical' | 'horizontal' | 'grid';
778
970
 
779
971
  ## `@trismegisto/angular/drawer`
780
972
 
781
- - `DrawerPosition` — Borda de onde o painel sai: fim da linha (direita em LTR), começo da linha ou de baixo.
973
+ - `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
974
 
783
975
  ```ts
784
976
  type DrawerPosition = 'end' | 'start' | 'bottom';
@@ -940,7 +1132,7 @@ type FieldType = 'text' | 'password';
940
1132
  type FileUploadSize = 'small' | 'medium' | 'large';
941
1133
  ```
942
1134
 
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 =…
1135
+ - `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
1136
 
945
1137
  ```ts
946
1138
  type FileUploader = (file: File, report: (progress: number) => void, signal: AbortSignal) => Promise<unknown>;
@@ -1167,7 +1359,10 @@ type IconFlip = 'horizontal' | 'vertical';
1167
1359
  - `const ICON_ANGLE_DOUBLE: RegisteredIcon`
1168
1360
  - `const ICON_ARROW: RegisteredIcon`
1169
1361
  - `const ICON_ARROWS_HORIZONTAL: RegisteredIcon`
1362
+ - `const ICON_BLOCK_QUOTE: RegisteredIcon`
1363
+ - `const ICON_BOLD: RegisteredIcon`
1170
1364
  - `const ICON_BOOKMARK: RegisteredIcon`
1365
+ - `const ICON_BULLET_LIST: RegisteredIcon`
1171
1366
  - `const ICON_CALENDAR: RegisteredIcon`
1172
1367
  - `const ICON_CHECK: RegisteredIcon`
1173
1368
  - `const ICON_CHECK_CIRCLE: RegisteredIcon`
@@ -1175,8 +1370,12 @@ type IconFlip = 'horizontal' | 'vertical';
1175
1370
  - `const ICON_CIRCLE: RegisteredIcon`
1176
1371
  - `const ICON_CLOCK: RegisteredIcon`
1177
1372
  - `const ICON_CLOUD_UP: RegisteredIcon`
1373
+ - `const ICON_CODE: RegisteredIcon`
1374
+ - `const ICON_CODE_BLOCK: RegisteredIcon`
1178
1375
  - `const ICON_COG: RegisteredIcon`
1179
1376
  - `const ICON_COPY: RegisteredIcon`
1377
+ - `const ICON_DETAIL_COLLAPSE: RegisteredIcon`
1378
+ - `const ICON_DETAIL_EXPAND: RegisteredIcon`
1180
1379
  - `const ICON_DOCUMENT_CSV: RegisteredIcon`
1181
1380
  - `const ICON_DOCUMENT_DOC: RegisteredIcon`
1182
1381
  - `const ICON_DOCUMENT_IMAGE: RegisteredIcon`
@@ -1186,6 +1385,7 @@ type IconFlip = 'horizontal' | 'vertical';
1186
1385
  - `const ICON_DRAG_HANDLE: RegisteredIcon`
1187
1386
  - `const ICON_ELLIPSIS_HORIZONTAL: RegisteredIcon`
1188
1387
  - `const ICON_ELLIPSIS_VERTICAL: RegisteredIcon`
1388
+ - `const ICON_ERASER: RegisteredIcon`
1189
1389
  - `const ICON_ERROR_STANDARD: RegisteredIcon`
1190
1390
  - `const ICON_EXCLAMATION_CIRCLE: RegisteredIcon`
1191
1391
  - `const ICON_EXCLAMATION_TRIANGLE: RegisteredIcon`
@@ -1197,36 +1397,48 @@ type IconFlip = 'horizontal' | 'vertical';
1197
1397
  - `const ICON_FILTER_GRID: RegisteredIcon`
1198
1398
  - `const ICON_FILTER_GRID_CIRCLE: RegisteredIcon`
1199
1399
  - `const ICON_GRID: RegisteredIcon`
1400
+ - `const ICON_IMAGE: RegisteredIcon`
1200
1401
  - `const ICON_INFO_CIRCLE: RegisteredIcon`
1402
+ - `const ICON_ITALIC: RegisteredIcon`
1201
1403
  - `const ICON_KEY: RegisteredIcon`
1202
1404
  - `const ICON_KEYBOARD: RegisteredIcon`
1405
+ - `const ICON_LINK: RegisteredIcon`
1203
1406
  - `const ICON_LIST: RegisteredIcon`
1204
1407
  - `const ICON_LOGIN: RegisteredIcon`
1205
1408
  - `const ICON_MENU: RegisteredIcon`
1206
1409
  - `const ICON_MINUS: RegisteredIcon`
1207
1410
  - `const ICON_NODE: RegisteredIcon`
1411
+ - `const ICON_NUMBER_LIST: RegisteredIcon`
1208
1412
  - `const ICON_PAUSE: RegisteredIcon`
1209
1413
  - `const ICON_PENCIL: RegisteredIcon`
1210
1414
  - `const ICON_PIN: RegisteredIcon`
1211
1415
  - `const ICON_PLAY: RegisteredIcon`
1212
1416
  - `const ICON_PLUS: RegisteredIcon`
1417
+ - `const ICON_REDO: RegisteredIcon`
1213
1418
  - `const ICON_REFRESH: RegisteredIcon`
1419
+ - `const ICON_ROTATE_LEFT: RegisteredIcon`
1420
+ - `const ICON_ROTATE_RIGHT: RegisteredIcon`
1214
1421
  - `const ICON_SEARCH: RegisteredIcon`
1215
1422
  - `const ICON_STAR: RegisteredIcon`
1216
1423
  - `const ICON_STEP_FORWARD_2: RegisteredIcon`
1424
+ - `const ICON_STRIKETHROUGH: RegisteredIcon`
1217
1425
  - `const ICON_SUCCESS_STANDARD: RegisteredIcon`
1218
1426
  - `const ICON_TEXT: RegisteredIcon`
1219
1427
  - `const ICON_TIMES: RegisteredIcon`
1220
1428
  - `const ICON_TIMES_CIRCLE: RegisteredIcon`
1221
1429
  - `const ICON_TOOLS: RegisteredIcon`
1222
1430
  - `const ICON_TRASH: RegisteredIcon`
1431
+ - `const ICON_UNDERLINE: RegisteredIcon`
1223
1432
  - `const ICON_UNDO: RegisteredIcon`
1224
1433
  - `const ICON_UPLOAD: RegisteredIcon`
1225
1434
  - `const ICON_USER: RegisteredIcon`
1226
1435
  - `const ICON_VIEW_COLUMNS: RegisteredIcon`
1436
+ - `const ICON_VIEW_LIST: RegisteredIcon`
1227
1437
  - `const ICON_WINDOW_MAX: RegisteredIcon`
1228
1438
  - `const ICON_WINDOW_MIN: RegisteredIcon`
1229
1439
  - `const ICON_WINDOW_RESTORE: RegisteredIcon`
1440
+ - `const ICON_ZOOM_IN: RegisteredIcon`
1441
+ - `const ICON_ZOOM_OUT: RegisteredIcon`
1230
1442
  - `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
1443
  - `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
1444
  - `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 +1482,7 @@ type IconFlip = 'horizontal' | 'vertical';
1270
1482
 
1271
1483
  ## `@trismegisto/angular/illustration-shared`
1272
1484
 
1273
- - `IllustrationIdRef` — Um id interno do SVG e as formas de referenciá-lo.
1485
+ - `IllustrationIdRef` — Referência a um elemento definidor de SVG (`<clipPath>`, gradiente, máscara, filtro).
1274
1486
 
1275
1487
  ```ts
1276
1488
  interface IllustrationIdRef {
@@ -1280,7 +1492,7 @@ interface IllustrationIdRef {
1280
1492
  }
1281
1493
  ```
1282
1494
 
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.
1495
+ - `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
1496
 
1285
1497
  ## `@trismegisto/angular/illustration-success`
1286
1498
 
@@ -1290,6 +1502,105 @@ interface IllustrationIdRef {
1290
1502
 
1291
1503
  - `IllustrationUnlockedComponent` — `hm-illustration-unlocked` (ver angular-api.md)
1292
1504
 
1505
+ ## `@trismegisto/angular/image-crop`
1506
+
1507
+ - `ImageCropComponent` — `hm-image-crop` (ver angular-api.md)
1508
+ - `ImageCropError` _(de `@trismegisto/primitives`)_ — Falha de carga ou de geração; `message` já vem do catálogo, pronta para a tela.
1509
+
1510
+ ```ts
1511
+ interface ImageCropError {
1512
+ readonly code: ImageCropErrorCode;
1513
+ readonly message: string;
1514
+ readonly cause?: unknown;
1515
+ }
1516
+ ```
1517
+
1518
+ - `ImageCropErrorCode` _(de `@trismegisto/primitives`)_
1519
+
1520
+ ```ts
1521
+ type ImageCropErrorCode = 'type' | 'size' | 'pixels' | 'url' | 'network' | 'decode' | 'empty' | 'encode';
1522
+ ```
1523
+
1524
+ - `ImageCropExportOptions` _(de `@trismegisto/primitives`)_ — Ajustes de uma geração (`exportImage`); o que faltar vem dos inputs do componente.
1525
+
1526
+ ```ts
1527
+ interface ImageCropExportOptions {
1528
+ readonly type?: ImageCropOutputType;
1529
+ readonly quality?: number;
1530
+ readonly maxWidth?: number;
1531
+ readonly maxHeight?: number;
1532
+ readonly fill?: string;
1533
+ readonly mask?: boolean;
1534
+ readonly as?: 'blob' | 'data-url';
1535
+ }
1536
+ ```
1537
+
1538
+ - `ImageCropInfo` _(de `@trismegisto/primitives`)_ — Imagem carregada: tamanho da imagem orientada (sem o giro do usuário), formato e bytes.
1539
+
1540
+ ```ts
1541
+ interface ImageCropInfo {
1542
+ readonly width: number;
1543
+ readonly height: number;
1544
+ readonly type: ImageCropType;
1545
+ readonly bytes: number;
1546
+ }
1547
+ ```
1548
+
1549
+ - `ImageCropOutputType` _(de `@trismegisto/primitives`)_ — Formatos de saída que o canvas codifica.
1550
+
1551
+ ```ts
1552
+ type ImageCropOutputType = 'image/png' | 'image/jpeg' | 'image/webp';
1553
+ ```
1554
+
1555
+ - `ImageCropRegion` _(de `@trismegisto/primitives`)_ — Área de recorte em pixels inteiros da imagem orientada e girada.
1556
+
1557
+ ```ts
1558
+ interface ImageCropRegion {
1559
+ readonly x: number;
1560
+ readonly y: number;
1561
+ readonly width: number;
1562
+ readonly height: number;
1563
+ }
1564
+ ```
1565
+
1566
+ - `ImageCropResult` _(de `@trismegisto/primitives`)_
1567
+
1568
+ ```ts
1569
+ interface ImageCropResult {
1570
+ readonly blob: Blob;
1571
+ readonly dataUrl?: string;
1572
+ readonly type: string;
1573
+ readonly width: number;
1574
+ readonly height: number;
1575
+ readonly region: ImageCropRegion;
1576
+ readonly rotation: ImageCropRotation;
1577
+ }
1578
+ ```
1579
+
1580
+ - `ImageCropRotation` _(de `@trismegisto/primitives`)_ — Giro no sentido horário, em quartos de volta.
1581
+
1582
+ ```ts
1583
+ type ImageCropRotation = 0 | 90 | 180 | 270;
1584
+ ```
1585
+
1586
+ - `ImageCropShape` _(de `@trismegisto/primitives`)_
1587
+
1588
+ ```ts
1589
+ type ImageCropShape = 'rect' | 'round';
1590
+ ```
1591
+
1592
+ - `ImageCropSource` _(de `@trismegisto/primitives`)_ — Imagem a recortar: arquivo/`Blob`, endereço `http(s)`/relativo, `blob:` ou `data:image/…`.
1593
+
1594
+ ```ts
1595
+ type ImageCropSource = Blob | string | null;
1596
+ ```
1597
+
1598
+ - `ImageCropType` _(de `@trismegisto/primitives`)_ — Formatos de ENTRADA reconhecidos (pelos bytes, nunca pelo tipo declarado).
1599
+
1600
+ ```ts
1601
+ type ImageCropType = 'image/png' | 'image/jpeg' | 'image/gif' | 'image/webp' | 'image/avif' | 'image/bmp';
1602
+ ```
1603
+
1293
1604
  ## `@trismegisto/angular/input`
1294
1605
 
1295
1606
  - `InputType`
@@ -1457,7 +1768,7 @@ type LegendOrientation = 'horizontal' | 'vertical';
1457
1768
  type LegendMarker = 'dot' | 'square' | 'line';
1458
1769
  ```
1459
1770
 
1460
- - `LegendItem` — Um item da legenda.
1771
+ - `LegendItem`
1461
1772
 
1462
1773
  ```ts
1463
1774
  interface LegendItem {
@@ -1563,7 +1874,7 @@ type MessageScrollerLive = 'polite' | 'off';
1563
1874
 
1564
1875
  ## `@trismegisto/angular/navigation-menu`
1565
1876
 
1566
- - **`HermesNavigationMenu`** (classe) — Contrato que `hm-navigation-menu` publica por injeção para os itens e links dentro dele.
1877
+ - **`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
1878
 
1568
1879
  ```ts
1569
1880
  abstract class HermesNavigationMenu {
@@ -1575,10 +1886,6 @@ abstract class HermesNavigationMenu {
1575
1886
  - `NavigationMenuItemComponent` — `hm-navigation-menu-item` (ver angular-api.md)
1576
1887
  - `NavigationMenuLinkComponent` — `hm-navigation-menu-link` (ver angular-api.md)
1577
1888
 
1578
- ## `@trismegisto/angular/opening-scene`
1579
-
1580
- - `OpeningSceneComponent` — `hm-opening-scene` (ver angular-api.md)
1581
-
1582
1889
  ## `@trismegisto/angular/page-header`
1583
1890
 
1584
1891
  - `PageHeaderLevel`
@@ -1591,7 +1898,7 @@ type PageHeaderLevel = 1 | 2 | 3 | 4 | 5 | 6;
1591
1898
 
1592
1899
  ## `@trismegisto/angular/paginator`
1593
1900
 
1594
- - `PaginatorVariant` — `full`: pontas, números e itens por página. `simple`: só anterior/próxima (+ "Página X").
1901
+ - `PaginatorVariant`
1595
1902
 
1596
1903
  ```ts
1597
1904
  type PaginatorVariant = 'full' | 'simple';
@@ -1729,13 +2036,13 @@ interface RadioOption {
1729
2036
  }
1730
2037
  ```
1731
2038
 
1732
- - `RadioAppearance` — Desenho do grupo: lista de rádios (padrão) ou cartões clicáveis (opção explicada, com ícone).
2039
+ - `RadioAppearance` — `list` (padrão): círculo ao lado do texto. `card`: cada opção vira um cartão clicável.
1733
2040
 
1734
2041
  ```ts
1735
2042
  type RadioAppearance = 'list' | 'card';
1736
2043
  ```
1737
2044
 
1738
- - `RadioLayout` — Disposição das opções: `'stacked'` (padrão, uma por linha) ou `'inline'` (lado a lado, quebrando linha sem espaço).
2045
+ - `RadioLayout` — `stacked` (padrão): uma opção por linha. `inline`: lado a lado, quebrando linha.
1739
2046
 
1740
2047
  ```ts
1741
2048
  type RadioLayout = 'stacked' | 'inline';
@@ -1791,6 +2098,11 @@ interface ReorderListItemContext {
1791
2098
 
1792
2099
  - `ReorderListComponent` — `hm-reorder-list` (ver angular-api.md)
1793
2100
 
2101
+ ## `@trismegisto/angular/rich-text`
2102
+
2103
+ - `RichTextComponent` — `hm-rich-text` (ver angular-api.md)
2104
+ - `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 `''`.
2105
+
1794
2106
  ## `@trismegisto/angular/search-field`
1795
2107
 
1796
2108
  - `SearchFieldSize`
@@ -1936,7 +2248,7 @@ class HermesShortcutService {
1936
2248
  ## `@trismegisto/angular/sidebar`
1937
2249
 
1938
2250
  - `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.
2251
+ - **`HermesSidebarGroup`** (classe) — O que um `hm-sidebar-group` oferece por injeção aos links e grupos dentro dele.
1940
2252
 
1941
2253
  ```ts
1942
2254
  abstract class HermesSidebarGroup {
@@ -1944,7 +2256,7 @@ abstract class HermesSidebarGroup {
1944
2256
  ```
1945
2257
 
1946
2258
  - `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.
2259
+ - `SidebarNode` — Um nó da árvore de navegação: folha vira link; nó com filhos visíveis vira grupo.
1948
2260
 
1949
2261
  ```ts
1950
2262
  interface SidebarNode {
@@ -1959,7 +2271,7 @@ interface SidebarNode {
1959
2271
 
1960
2272
  - `SidebarNodeComponent` — `hm-sidebar-node` (ver angular-api.md)
1961
2273
  - `SidebarComponent` — `hm-sidebar` (ver angular-api.md)
1962
- - `const HERMES_SIDEBAR_CONFIG = new InjectionToken<Pick<SidebarStoreOptions, 'storageKey' | 'defaultMode'>>`
2274
+ - `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
2275
  - **`HermesSidebarService`** (classe)
1964
2276
 
1965
2277
  ```ts
@@ -1970,19 +2282,19 @@ class HermesSidebarService {
1970
2282
  readonly overlaid = computed(…)
1971
2283
  readonly mobileOpen = computed(…)
1972
2284
  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(); }
2285
+ setMode(mode: SidebarMode): void
2286
+ peekPointer(inside: boolean): void
2287
+ peekFocus(inside: boolean): void
2288
+ toggleMobile(): void
2289
+ closeMobile(): void
2290
+ ensureExpanded(): void
1979
2291
  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; }
2292
+ setGroupOpen(id: string, open: boolean): void
2293
+ resetGroups(): void
2294
+ registerGroup(id: string): void
2295
+ unregisterGroup(id: string): void
2296
+ setAllGroups(open: boolean): void
2297
+ get doc(): Document
1986
2298
  }
1987
2299
  ```
1988
2300
 
@@ -2035,13 +2347,13 @@ type SpinnerSize = 'small' | 'medium' | 'large';
2035
2347
 
2036
2348
  ## `@trismegisto/angular/stat-card`
2037
2349
 
2038
- - `StatCardSize` — Escala de tamanho do cartão: muda o destaque do valor, o disco do ícone e o respiro.
2350
+ - `StatCardSize` — Escala do cartão: disco do ícone, corpo do valor e (em `large`) o respiro interno.
2039
2351
 
2040
2352
  ```ts
2041
2353
  type StatCardSize = 'small' | 'medium' | 'large';
2042
2354
  ```
2043
2355
 
2044
- - `StatCardDetail` — Um fragmento do detalhamento (`23 MPLS`, `19 Internet`), com um ponto colorido opcional.
2356
+ - `StatCardDetail` — Um pedaço do detalhamento do número (ex.: quantos de cada tipo), com marcador colorido opcional.
2045
2357
 
2046
2358
  ```ts
2047
2359
  interface StatCardDetail {
@@ -2050,13 +2362,13 @@ interface StatCardDetail {
2050
2362
  }
2051
2363
  ```
2052
2364
 
2053
- - `StatCardTrendDirection` — Direção da variação. A seta e o texto lido pelo leitor de tela vêm dela.
2365
+ - `StatCardTrendDirection`
2054
2366
 
2055
2367
  ```ts
2056
2368
  type StatCardTrendDirection = 'up' | 'down' | 'flat';
2057
2369
  ```
2058
2370
 
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`.
2371
+ - `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
2372
 
2061
2373
  ```ts
2062
2374
  interface StatCardTrend {
@@ -2071,7 +2383,7 @@ interface StatCardTrend {
2071
2383
 
2072
2384
  ## `@trismegisto/angular/stat-group`
2073
2385
 
2074
- - `StatGroupMetric` — Uma métrica do grupo: `{ label: 'Concluídos', value: '28', caption: 'hoje' }`.
2386
+ - `StatGroupMetric` — Um par rótulo/valor do grupo; `caption` é a legenda sob o valor e `intent` vence o tom do grupo.
2075
2387
 
2076
2388
  ```ts
2077
2389
  interface StatGroupMetric {
@@ -2127,7 +2439,7 @@ interface StatePagePreset extends StatePageVisual {
2127
2439
 
2128
2440
  ## `@trismegisto/angular/state-screen`
2129
2441
 
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.
2442
+ - `StateScreenSituation` — Situação mostrada; escolhe a ilustração padrão.
2131
2443
 
2132
2444
  ```ts
2133
2445
  type StateScreenSituation =
@@ -2147,13 +2459,20 @@ type StateScreenSituation =
2147
2459
 
2148
2460
  ## `@trismegisto/angular/stepper`
2149
2461
 
2150
- - `HermesStepGuard` — Pergunta assíncrona ou síncrona "a etapa pode avançar?", feita ao clicar em Avançar.
2462
+ - **`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.
2463
+
2464
+ ```ts
2465
+ abstract class HermesStepGroup {
2466
+ }
2467
+ ```
2468
+
2469
+ - `HermesStepGuard` — Guarda extra antes de sair adiante de uma etapa. `false`, exceção ou rejeição seguram a etapa.
2151
2470
 
2152
2471
  ```ts
2153
2472
  type HermesStepGuard = () => boolean | Promise<boolean>;
2154
2473
  ```
2155
2474
 
2156
- - `HermesStepSummaryEntry` — Um par termo/valor do resumo de uma etapa (o mesmo formato do `[items]` do `hm-description-list`).
2475
+ - `HermesStepSummaryEntry`
2157
2476
 
2158
2477
  ```ts
2159
2478
  interface HermesStepSummaryEntry {
@@ -2162,7 +2481,7 @@ interface HermesStepSummaryEntry {
2162
2481
  }
2163
2482
  ```
2164
2483
 
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…
2484
+ - `HermesStepSummary` — O que a etapa resume na página de revisão do `hm-wizard`: um template ou pares termo/valor.
2166
2485
 
2167
2486
  ```ts
2168
2487
  type HermesStepSummary = TemplateRef<unknown> | (() => readonly HermesStepSummaryEntry[]);
@@ -2176,16 +2495,10 @@ type StepperOrientation = 'horizontal' | 'vertical';
2176
2495
  ```
2177
2496
 
2178
2497
  - `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
2498
 
2186
2499
  ## `@trismegisto/angular/switch`
2187
2500
 
2188
- - `SwitchLabelPosition` — De que lado do controle o rótulo fica.
2501
+ - `SwitchLabelPosition`
2189
2502
 
2190
2503
  ```ts
2191
2504
  type SwitchLabelPosition = 'before' | 'after';
@@ -2195,7 +2508,7 @@ type SwitchLabelPosition = 'before' | 'after';
2195
2508
 
2196
2509
  ## `@trismegisto/angular/tab-bar`
2197
2510
 
2198
- - `TabDragData` — Dados de uma aba em arrasto (o `data()` do item no serviço de arrastar e soltar, tipo `TAB_DRAG_TYPE`).
2511
+ - `TabDragData` — Dados de uma aba em arrasto (o que uma zona de soltura enxerga em `item.data()`).
2199
2512
 
2200
2513
  ```ts
2201
2514
  interface TabDragData {
@@ -2205,7 +2518,7 @@ interface TabDragData {
2205
2518
  }
2206
2519
  ```
2207
2520
 
2208
- - `TabReceivedEvent` — Aba de outra fileira do mesmo `tabGroup` solta nesta (`tabReceived`).
2521
+ - `TabReceivedEvent` — Aba de outra fileira do mesmo grupo solta nesta.
2209
2522
 
2210
2523
  ```ts
2211
2524
  interface TabReceivedEvent {
@@ -2216,7 +2529,7 @@ interface TabReceivedEvent {
2216
2529
  ```
2217
2530
 
2218
2531
  - `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.
2532
+ - `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
2533
 
2221
2534
  ```ts
2222
2535
  interface TabItem {
@@ -2231,26 +2544,26 @@ interface TabItem {
2231
2544
 
2232
2545
  - `TabComponent` — `hm-tab` (ver angular-api.md)
2233
2546
  - `TabsComponent` — `hm-tabs` (ver angular-api.md)
2234
- - **`HermesTabGroup`** (classe) — Contrato que `hm-tabs` publica por injeção para os `hm-tab` dentro dele.
2547
+ - **`HermesTabGroup`** (classe) — O que o `hm-tabs` oferece por injeção aos `hm-tab` que ele contém.
2235
2548
 
2236
2549
  ```ts
2237
2550
  abstract class HermesTabGroup {
2238
2551
  }
2239
2552
  ```
2240
2553
 
2241
- - `HermesTabsMode` — `tabs`: tablist com painéis (padrão). `nav`: links de rota com `aria-current="page"`.
2554
+ - `HermesTabsMode` — `tabs`: lista de abas com painéis; `nav`: subnavegação por rotas, sem painel.
2242
2555
 
2243
2556
  ```ts
2244
2557
  type HermesTabsMode = 'tabs' | 'nav';
2245
2558
  ```
2246
2559
 
2247
- - `HermesTabsOrientation` — Direção da faixa de abas (WAI-ARIA APG: ←/→ no horizontal, ↑/↓ no vertical).
2560
+ - `HermesTabsOrientation`
2248
2561
 
2249
2562
  ```ts
2250
2563
  type HermesTabsOrientation = 'horizontal' | 'vertical';
2251
2564
  ```
2252
2565
 
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).
2566
+ - `HermesTabsOverflow` — O que fazer com as abas que não cabem na faixa horizontal: menu "Mais" ou quebrar em linhas.
2254
2567
 
2255
2568
  ```ts
2256
2569
  type HermesTabsOverflow = 'menu' | 'wrap';
@@ -2260,7 +2573,7 @@ type HermesTabsOverflow = 'menu' | 'wrap';
2260
2573
 
2261
2574
  ## `@trismegisto/angular/tag`
2262
2575
 
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…
2576
+ - `TagColor` — Cor da etiqueta. `error` é o nome antigo de `danger` (depreciado; continua funcionando).
2264
2577
 
2265
2578
  ```ts
2266
2579
  type TagColor = 'primary' | 'info' | 'success' | 'warning' | 'danger' | 'neutral' | 'error';
@@ -2587,7 +2900,7 @@ class HermesMenuItemHarness extends ComponentHarness {
2587
2900
  }
2588
2901
  ```
2589
2902
 
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…
2903
+ - **`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
2904
 
2592
2905
  ```ts
2593
2906
  class HermesMenuHarness extends ComponentHarness {
@@ -2749,14 +3062,14 @@ class HermesDataGridHarness extends ComponentHarness {
2749
3062
 
2750
3063
  ## `@trismegisto/angular/textarea`
2751
3064
 
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).
3065
+ - `TextareaSubmitKey` — Tecla que envia o texto (`submitted`): nunca, Ctrl/⌘+Enter, ou Enter (Shift+Enter quebra linha).
2753
3066
 
2754
3067
  ```ts
2755
3068
  type TextareaSubmitKey = 'none' | 'mod-enter' | 'enter';
2756
3069
  ```
2757
3070
 
2758
3071
  - `TextareaComponent` — `hm-textarea` (ver angular-api.md)
2759
- - `TextareaAddonSlot` — Onde o conteúdo projetado entra no `hm-textarea`.
3072
+ - `TextareaAddonSlot`
2760
3073
 
2761
3074
  ```ts
2762
3075
  type TextareaAddonSlot = 'prefix' | 'suffix' | 'actions' | 'actionsEnd';
@@ -2841,7 +3154,7 @@ class HermesToastService {
2841
3154
 
2842
3155
  ## `@trismegisto/angular/toggle-group`
2843
3156
 
2844
- - **`HermesToggleGroup`** (classe) — Contrato que `hm-toggle-group` publica por injeção para os `hm-toggle-group-item` dentro dele.
3157
+ - **`HermesToggleGroup`** (classe) — O que um `hm-toggle-group-item` enxerga do `hm-toggle-group` que o contém (fornecido por DI).
2845
3158
 
2846
3159
  ```ts
2847
3160
  abstract class HermesToggleGroup {
@@ -2877,7 +3190,7 @@ type ToggleGroupOrientation = 'horizontal' | 'vertical';
2877
3190
 
2878
3191
  ## `@trismegisto/angular/toggletip`
2879
3192
 
2880
- - `ToggletipSide` — Lado preferido de abertura do balão; ele vira sozinho quando não cabe.
3193
+ - `ToggletipSide`
2881
3194
 
2882
3195
  ```ts
2883
3196
  type ToggletipSide = 'bottom' | 'top';
@@ -2895,13 +3208,13 @@ type ToggletipSide = 'bottom' | 'top';
2895
3208
 
2896
3209
  ## `@trismegisto/angular/tree`
2897
3210
 
2898
- - `TreeCanDrop` — Pode soltar `node` em `position` de `target`? (`canDrop` do hm-tree).
3211
+ - `TreeCanDrop` — Decide se `node` pode ser solto em `position` relativo a `target`.
2899
3212
 
2900
3213
  ```ts
2901
3214
  type TreeCanDrop = (node: TreeNode, target: TreeNode, position: TreeDropPosition) => boolean;
2902
3215
  ```
2903
3216
 
2904
- - `TreeMoveEvent` — Nó solto em outro lugar (`moved`). O hm-tree não muda `nodes`: aplique com `moveTreeNode`.
3217
+ - `TreeMoveEvent` — Nó solto num lugar novo. `from`/`to` são as localizações antes e depois (índice já sem a origem).
2905
3218
 
2906
3219
  ```ts
2907
3220
  interface TreeMoveEvent {
@@ -2914,7 +3227,7 @@ interface TreeMoveEvent {
2914
3227
  }
2915
3228
  ```
2916
3229
 
2917
- - `TreeNodeActionEvent` — Ação escolhida no menu de contexto de um nó (`nodeAction`).
3230
+ - `TreeNodeActionEvent`
2918
3231
 
2919
3232
  ```ts
2920
3233
  interface TreeNodeActionEvent {
@@ -2923,13 +3236,13 @@ interface TreeNodeActionEvent {
2923
3236
  }
2924
3237
  ```
2925
3238
 
2926
- - `TreeNodeActions` — Itens do menu de contexto: os mesmos para todo nó, ou filtrados/calculados por nó.
3239
+ - `TreeNodeActions` — Itens do menu de contexto: a mesma lista para todos ou calculada por nó.
2927
3240
 
2928
3241
  ```ts
2929
3242
  type TreeNodeActions = readonly MenuItem[] | ((node: TreeNode) => readonly MenuItem[]);
2930
3243
  ```
2931
3244
 
2932
- - `TreeLoadContext` — Onde a carga está: quantos filhos do nó já chegaram e qual página é esta (0 = a primeira).
3245
+ - `TreeLoadContext` — Qual página pedir: `offset` = filhos já recebidos, `page` = páginas já recebidas.
2933
3246
 
2934
3247
  ```ts
2935
3248
  interface TreeLoadContext {
@@ -2938,7 +3251,7 @@ interface TreeLoadContext {
2938
3251
  }
2939
3252
  ```
2940
3253
 
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…
3254
+ - `TreeChildrenLoader`
2942
3255
 
2943
3256
  ```ts
2944
3257
  type TreeChildrenLoader = (
@@ -2947,7 +3260,7 @@ type TreeChildrenLoader = (
2947
3260
  ) => Promise<TreeChildrenResult> | Observable<TreeChildrenResult>;
2948
3261
  ```
2949
3262
 
2950
- - `TreeNodeTemplateContext` — Contexto do template customizado de nó (`<ng-template hmTreeNode let-node let-row="row">`).
3263
+ - `TreeNodeTemplateContext`
2951
3264
 
2952
3265
  ```ts
2953
3266
  interface TreeNodeTemplateContext {
@@ -2959,7 +3272,7 @@ interface TreeNodeTemplateContext {
2959
3272
 
2960
3273
  - `TreeNodeTemplateDirective` — `ng-template[hmTreeNode]` (ver angular-api.md)
2961
3274
  - `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").
3275
+ - `TreeChildrenPage` _(de `@trismegisto/primitives`)_
2963
3276
 
2964
3277
  ```ts
2965
3278
  interface TreeChildrenPage {
@@ -2968,19 +3281,19 @@ interface TreeChildrenPage {
2968
3281
  }
2969
3282
  ```
2970
3283
 
2971
- - `TreeChildrenResult` _(de `@trismegisto/primitives`)_ — O que um `loadChildren` pode devolver: a lista inteira (forma antiga) ou uma página.
3284
+ - `TreeChildrenResult` _(de `@trismegisto/primitives`)_
2972
3285
 
2973
3286
  ```ts
2974
3287
  type TreeChildrenResult = readonly TreeNode[] | TreeChildrenPage;
2975
3288
  ```
2976
3289
 
2977
- - `TreeDropPosition` _(de `@trismegisto/primitives`)_ — Onde soltar em relação ao nó-alvo: antes, dentro (último filho) ou depois.
3290
+ - `TreeDropPosition` _(de `@trismegisto/primitives`)_
2978
3291
 
2979
3292
  ```ts
2980
3293
  type TreeDropPosition = DropPosition;
2981
3294
  ```
2982
3295
 
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).
3296
+ - `TreeLocation` _(de `@trismegisto/primitives`)_
2984
3297
 
2985
3298
  ```ts
2986
3299
  interface TreeLocation {
@@ -3014,7 +3327,7 @@ interface TreeSelectionChange {
3014
3327
  }
3015
3328
  ```
3016
3329
 
3017
- - `TreeSelectionMode` _(de `@trismegisto/primitives`)_ — `none`: só ativa; `single`: um nó por vez; `multiple`: vários, com Ctrl/Shift e Ctrl+A.
3330
+ - `TreeSelectionMode` _(de `@trismegisto/primitives`)_
3018
3331
 
3019
3332
  ```ts
3020
3333
  type TreeSelectionMode = 'none' | 'single' | 'multiple';
@@ -3202,13 +3515,13 @@ enum HermesLoadingState {
3202
3515
  }
3203
3516
  ```
3204
3517
 
3205
- - `AlertVariant`
3518
+ - `AlertVariant` — Tom do alerta (também usado pelo toast).
3206
3519
 
3207
3520
  ```ts
3208
3521
  type AlertVariant = 'error' | 'warning' | 'info' | 'success';
3209
3522
  ```
3210
3523
 
3211
- - `ButtonEmphasis` — Montagem das classes CSS `hm-*` (definidas em @trismegisto/core) — igual em qualquer framework.
3524
+ - `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
3525
 
3213
3526
  ```ts
3214
3527
  type ButtonEmphasis = 'high' | 'medium' | 'minimal';
@@ -3232,7 +3545,7 @@ type ButtonSize = 'small' | 'medium' | 'large';
3232
3545
  type IconButtonEmphasis = 'filled' | 'outlined' | 'subtle';
3233
3546
  ```
3234
3547
 
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…
3548
+ - `ModalSize` — Tamanhos de diálogo (modal, drawer, wizard). Mora aqui por histórico do pacote.
3236
3549
 
3237
3550
  ```ts
3238
3551
  type ModalSize = 'small' | 'medium' | 'large' | 'xlarge' | 'full';
@@ -3240,7 +3553,7 @@ type ModalSize = 'small' | 'medium' | 'large' | 'xlarge' | 'full';
3240
3553
 
3241
3554
  - `HermesIcon`
3242
3555
  - `IconBadge`
3243
- - `MenuItem` — Pop-over e menu de contexto: posicionamento e teclado, sem DOM nem framework.
3556
+ - `MenuItem`
3244
3557
 
3245
3558
  ```ts
3246
3559
  interface MenuItem {
@@ -3284,7 +3597,7 @@ type MenuItemType = 'checkbox' | 'radio';
3284
3597
  type PopoverAlign = 'start' | 'center' | 'end';
3285
3598
  ```
3286
3599
 
3287
- - `PopoverAnchor` — Onde o menu abre, em coordenadas de viewport.
3600
+ - `PopoverAnchor` — De onde o cartão nasce, em px de viewport.
3288
3601
 
3289
3602
  ```ts
3290
3603
  interface PopoverAnchor {
@@ -3297,7 +3610,7 @@ interface PopoverAnchor {
3297
3610
  }
3298
3611
  ```
3299
3612
 
3300
- - `PopoverSide`
3613
+ - `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
3614
 
3302
3615
  ```ts
3303
3616
  type PopoverSide = 'top' | 'bottom' | 'left' | 'right';
@@ -3318,7 +3631,7 @@ interface TabBarState {
3318
3631
  }
3319
3632
  ```
3320
3633
 
3321
- - `TabReorder`
3634
+ - `TabReorder` — Pedido de mudança de posição: `index` é a posição final da aba.
3322
3635
 
3323
3636
  ```ts
3324
3637
  interface TabReorder {
@@ -3328,7 +3641,7 @@ interface TabReorder {
3328
3641
  ```
3329
3642
 
3330
3643
  - `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.
3644
+ - `AlertAppearance` — `inline` fica no fluxo do conteúdo; `banner` é a faixa de largura total do app.
3332
3645
 
3333
3646
  ```ts
3334
3647
  type AlertAppearance = 'inline' | 'banner';
@@ -3351,7 +3664,88 @@ interface FloatingRect {
3351
3664
  type FloatingWindowState = 'normal' | 'minimized' | 'maximized';
3352
3665
  ```
3353
3666
 
3354
- - `BulkCase` — Caixa aplicada a cada item depois do trim.
3667
+ - `RichTextTool` — Ferramentas da barra, na ordem; `'|'` separa grupos.
3668
+
3669
+ ```ts
3670
+ type RichTextTool =
3671
+ | 'bold'
3672
+ | 'italic'
3673
+ | 'underline'
3674
+ | 'strike'
3675
+ | 'code'
3676
+ | 'link'
3677
+ | 'blockType'
3678
+ | 'bulletList'
3679
+ | 'orderedList'
3680
+ | 'quote'
3681
+ | 'codeBlock'
3682
+ | 'undo'
3683
+ | 'redo'
3684
+ | 'clear'
3685
+ | '|';
3686
+ ```
3687
+
3688
+ - `RichTextFormatTool` — O que `apply()` executa: uma ferramenta (sem o separador e o menu de estilo) ou um tipo de bloco.
3689
+
3690
+ ```ts
3691
+ type RichTextFormatTool =
3692
+ | Exclude<RichTextTool, '|' | 'blockType'>
3693
+ | 'paragraph'
3694
+ | `heading${RichTextHeadingLevel}`;
3695
+ ```
3696
+
3697
+ - `RichTextHeadingLevel`
3698
+
3699
+ ```ts
3700
+ type RichTextHeadingLevel = 2 | 3 | 4;
3701
+ ```
3702
+
3703
+ - `RichTextPasteMode`
3704
+
3705
+ ```ts
3706
+ type RichTextPasteMode = 'formatted' | 'plain';
3707
+ ```
3708
+
3709
+ - `RichTextSchema`
3710
+
3711
+ ```ts
3712
+ interface RichTextSchema {
3713
+ readonly marks: number;
3714
+ readonly link: boolean;
3715
+ readonly headingLevels: readonly RichTextHeadingLevel[];
3716
+ readonly bulletList: boolean;
3717
+ readonly orderedList: boolean;
3718
+ readonly quote: boolean;
3719
+ readonly codeBlock: boolean;
3720
+ readonly protocols: readonly string[];
3721
+ readonly allowRelativeLinks: boolean;
3722
+ }
3723
+ ```
3724
+
3725
+ - `RichTextSchemaOptions`
3726
+
3727
+ ```ts
3728
+ interface RichTextSchemaOptions {
3729
+ readonly tools?: readonly RichTextTool[];
3730
+ readonly headingLevels?: readonly RichTextHeadingLevel[];
3731
+ readonly linkProtocols?: readonly string[];
3732
+ readonly allowRelativeLinks?: boolean;
3733
+ }
3734
+ ```
3735
+
3736
+ - `RichTextParser` — Adaptador de parser: `(html) => Document`. No navegador, o padrão é o `DOMParser`.
3737
+
3738
+ ```ts
3739
+ type RichTextParser = (html: string) => Document;
3740
+ ```
3741
+
3742
+ - `const RICH_TEXT_DEFAULT_TOOLS: readonly RichTextTool[]`
3743
+ - `function richTextSchema(options: RichTextSchemaOptions = {}): RichTextSchema` — Monta o esquema a partir das ferramentas, níveis de título e regras de link da instância.
3744
+ - `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 → `''`.
3745
+ - `function richTextPlainText(html: string): string` — Texto puro de um HTML (canônico): blocos por `\n`, `br` → `\n`, entidades decodificadas.
3746
+ - `function richTextLength(html: string): number` — Contagem de caracteres (grafemas, sem quebras de linha) de um HTML.
3747
+ - `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`…
3748
+ - `BulkCase`
3355
3749
 
3356
3750
  ```ts
3357
3751
  type BulkCase = 'preserve' | 'lower' | 'upper';
@@ -3367,7 +3761,7 @@ interface BulkInvalidItem {
3367
3761
  }
3368
3762
  ```
3369
3763
 
3370
- - `BulkInvalidReason` — `format`: reprovado pela validação sem texto próprio; `custom`: com o texto em `message`; `limit`: passou do máximo.
3764
+ - `BulkInvalidReason`
3371
3765
 
3372
3766
  ```ts
3373
3767
  type BulkInvalidReason = 'format' | 'custom' | 'limit';
@@ -3396,19 +3790,19 @@ interface BulkParseResult {
3396
3790
  }
3397
3791
  ```
3398
3792
 
3399
- - `BulkSeparator` — Separadores aceitos. `space` fica fora do padrão: nome de pessoa tem espaço.
3793
+ - `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
3794
 
3401
3795
  ```ts
3402
3796
  type BulkSeparator = 'newline' | 'comma' | 'semicolon' | 'space' | 'tab';
3403
3797
  ```
3404
3798
 
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).
3799
+ - `BulkValidator`
3406
3800
 
3407
3801
  ```ts
3408
3802
  type BulkValidator = RegExp | ((item: string) => boolean | string | null | undefined);
3409
3803
  ```
3410
3804
 
3411
- - `UploadFile` — Um arquivo na lista do `hm-file-upload`. Imutável: mudanças geram um objeto novo.
3805
+ - `UploadFile` — Um arquivo na lista do campo, com a situação do envio.
3412
3806
 
3413
3807
  ```ts
3414
3808
  interface UploadFile<F extends FileLike = File> {
@@ -3420,13 +3814,13 @@ interface UploadFile<F extends FileLike = File> {
3420
3814
  }
3421
3815
  ```
3422
3816
 
3423
- - `UploadFilePatch` — O que dá para mudar num item depois de criado.
3817
+ - `UploadFilePatch`
3424
3818
 
3425
3819
  ```ts
3426
3820
  type UploadFilePatch = Partial<Pick<UploadFile<FileLike>, 'status' | 'progress' | 'error'>>;
3427
3821
  ```
3428
3822
 
3429
- - `FileUploadStatus` — Situação de um arquivo na lista: na fila, enviando, enviado, falhou.
3823
+ - `FileUploadStatus`
3430
3824
 
3431
3825
  ```ts
3432
3826
  type FileUploadStatus = 'pending' | 'uploading' | 'done' | 'error';
@@ -3441,19 +3835,19 @@ interface FileRejection<F extends FileLike = File> {
3441
3835
  }
3442
3836
  ```
3443
3837
 
3444
- - `FileRejectionReason` — Por que um arquivo não entrou na lista.
3838
+ - `FileRejectionReason`
3445
3839
 
3446
3840
  ```ts
3447
3841
  type FileRejectionReason = 'type' | 'size' | 'totalSize' | 'count' | 'duplicate';
3448
3842
  ```
3449
3843
 
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.
3844
+ - `PageWindowItem`
3451
3845
 
3452
3846
  ```ts
3453
3847
  type PageWindowItem = number | 'gap';
3454
3848
  ```
3455
3849
 
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.
3850
+ - `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
3851
 
3458
3852
  ```ts
3459
3853
  interface PaginationState {
@@ -3498,7 +3892,7 @@ interface DisplayDatePattern {
3498
3892
  - `function displayDatePattern(locale: string): DisplayDatePattern`
3499
3893
  - `function formatDisplayDate(value: string | null | undefined, pattern: DisplayDatePattern = DEFAULT_DATE_PATTERN): string` — ISO → texto no padrão do idioma (vazio se inválido).
3500
3894
  - `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…
3895
+ - `GridColumn`
3502
3896
 
3503
3897
  ```ts
3504
3898
  interface GridColumn<T> {
@@ -3519,7 +3913,7 @@ interface GridColumn<T> {
3519
3913
  }
3520
3914
  ```
3521
3915
 
3522
- - `GridColumnState` — Preferência da pessoa sobre uma coluna — separada da definição, que é de quem desenvolve.
3916
+ - `GridColumnState`
3523
3917
 
3524
3918
  ```ts
3525
3919
  interface GridColumnState {
@@ -3529,19 +3923,19 @@ interface GridColumnState {
3529
3923
  }
3530
3924
  ```
3531
3925
 
3532
- - `GridColumnType`
3926
+ - `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
3927
 
3534
3928
  ```ts
3535
3929
  type GridColumnType = 'text' | 'number' | 'date' | 'boolean';
3536
3930
  ```
3537
3931
 
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…
3932
+ - `GridColumnFilterValue` — Texto livre (contém) ou lista de valores exibidos marcados.
3539
3933
 
3540
3934
  ```ts
3541
3935
  type GridColumnFilterValue = string | readonly string[];
3542
3936
  ```
3543
3937
 
3544
- - `GridFilterOption` — Um valor de opção, pro pop-over de filtro de uma coluna categórica.
3938
+ - `GridFilterOption`
3545
3939
 
3546
3940
  ```ts
3547
3941
  interface GridFilterOption {
@@ -3550,13 +3944,13 @@ interface GridFilterOption {
3550
3944
  }
3551
3945
  ```
3552
3946
 
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.
3947
+ - `GridSelection`
3554
3948
 
3555
3949
  ```ts
3556
3950
  type GridSelection = ReadonlySet<string>;
3557
3951
  ```
3558
3952
 
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).
3953
+ - `GridSort`
3560
3954
 
3561
3955
  ```ts
3562
3956
  interface GridSort {
@@ -3594,7 +3988,7 @@ type GridFilterOperator =
3594
3988
  type GridFilterConnector = 'and' | 'or';
3595
3989
  ```
3596
3990
 
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`.
3991
+ - `GridFilterCondition`
3598
3992
 
3599
3993
  ```ts
3600
3994
  interface GridFilterCondition {
@@ -3606,7 +4000,7 @@ interface GridFilterCondition {
3606
4000
  }
3607
4001
  ```
3608
4002
 
3609
- - `GridFilterQuery` — Condições combinadas por um conector (todas = E, qualquer uma = OU).
4003
+ - `GridFilterQuery`
3610
4004
 
3611
4005
  ```ts
3612
4006
  interface GridFilterQuery {
@@ -3633,7 +4027,7 @@ type GridAggregates = Readonly<Record<string, GridAggregateFn>>;
3633
4027
  type GridAggregateFormatter = (value: number, fn: GridAggregateFn, key: string) => string;
3634
4028
  ```
3635
4029
 
3636
- - `GridCsvSeparator` — Separador de campo: `,` (RFC 4180), `;` (o que o Excel espera onde a vírgula é decimal) ou tab.
4030
+ - `GridCsvSeparator`
3637
4031
 
3638
4032
  ```ts
3639
4033
  type GridCsvSeparator = ',' | ';' | '\t';
@@ -3645,22 +4039,22 @@ type GridCsvSeparator = ',' | ';' | '\t';
3645
4039
  - `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
4040
  - `const HOVER_OPEN_DELAY = 500` — Atraso padrão para abrir ao passar o mouse (ms): evita abrir em quem só cruza o gatilho.
3647
4041
  - `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.
4042
+ - `TimelineDateValue`
3649
4043
 
3650
4044
  ```ts
3651
4045
  type TimelineDateValue = Date | string | number | null | undefined;
3652
4046
  ```
3653
4047
 
3654
- - `TimelineOutcome` — Como o processo inteiro está: ainda correndo, concluído ou parado com falha.
4048
+ - `TimelineOutcome`
3655
4049
 
3656
4050
  ```ts
3657
4051
  type TimelineOutcome = 'running' | 'completed' | 'failed';
3658
4052
  ```
3659
4053
 
3660
- - `TimelineStatus` — Situação de um item: concluído, o atual, ainda não aconteceu, ou parou com erro.
4054
+ - `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
4055
 
3662
4056
  ```ts
3663
- type TimelineStatus = 'completed' | 'current' | 'pending' | 'error';
4057
+ type TimelineStatus = 'completed' | 'current' | 'processing' | 'pending' | 'error';
3664
4058
  ```
3665
4059
 
3666
4060
  - `DualListItem`
@@ -3722,6 +4116,12 @@ type ShortcutKeyName =
3722
4116
  type ShortcutPlatform = 'mac' | 'other';
3723
4117
  ```
3724
4118
 
4119
+ - `CodeDiffLayout`
4120
+
4121
+ ```ts
4122
+ type CodeDiffLayout = 'split' | 'unified';
4123
+ ```
4124
+
3725
4125
  - `CertificateAltName`
3726
4126
 
3727
4127
  ```ts
@@ -3825,13 +4225,13 @@ type CertificateValidityState = 'valid' | 'expiring' | 'expired' | 'not-yet-vali
3825
4225
  type SplitterOrientation = 'horizontal' | 'vertical';
3826
4226
  ```
3827
4227
 
3828
- - `ToastVariant`
4228
+ - `ToastVariant` — Tom do alerta (também usado pelo toast).
3829
4229
 
3830
4230
  ```ts
3831
4231
  type AlertVariant = 'error' | 'warning' | 'info' | 'success';
3832
4232
  ```
3833
4233
 
3834
- - `ToastItem` — Um aviso na fila do canto da tela.
4234
+ - `ToastItem` — Um aviso na fila. `duration` 0 = só fecha quando alguém fecha (ou está pausado).
3835
4235
 
3836
4236
  ```ts
3837
4237
  interface ToastItem {
@@ -3863,7 +4263,7 @@ interface ToastState {
3863
4263
  }
3864
4264
  ```
3865
4265
 
3866
- - `ToastAction` — Ação de um aviso (ex.: "Desfazer"). `run` é chamado no clique e o aviso fecha em seguida.
4266
+ - `ToastAction` — Botão de ação do aviso ("Desfazer", "Ver detalhes").
3867
4267
 
3868
4268
  ```ts
3869
4269
  interface ToastAction {
@@ -3998,7 +4398,7 @@ interface WorkspaceStore {
3998
4398
  - `const DEFAULT_WORKSPACE_PERSISTENCE_CONFIG: WorkspacePersistenceConfig`
3999
4399
  - `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
4400
  - `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…
4401
+ - `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
4402
  - `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
4403
  - `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
4404
  - `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 +4408,7 @@ interface WorkspaceStore {
4008
4408
  - `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
4409
  - `function toPersistedWorkspace(state: WorkspaceState): PersistedWorkspace` — `WorkspaceState` (com painéis/stores de verdade) → forma persistível.
4010
4410
  - `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`
4411
+ - `CarouselSlide` — Um slide do `hm-carousel`. `image` vazio = slide só de texto; `alt` vazio = imagem decorativa.
4012
4412
 
4013
4413
  ```ts
4014
4414
  interface CarouselSlide {