@praxisui/list 9.0.7 → 9.0.9

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 (7) hide show
  1. package/README.md +14 -23
  2. package/ai/component-registry.json +2 -2
  3. package/docs/2026-08-collection-toolbar-runtime-note.md +22 -0
  4. package/fesm2022/praxisui-list.mjs +189 -67
  5. package/package.json +6 -6
  6. package/src/lib/praxis-list.json-api.md +241 -237
  7. package/types/praxisui-list.d.ts +31 -1
package/src/lib/praxis-list.json-api.md CHANGED
@@ -178,22 +178,22 @@ Este arquivo foi adaptado para o padrao canonico atual sem remover conteudo tecn
178
178
 
179
179
  ### Output events
180
180
 
181
- | Event | Payload | Trigger | Stability | Notes |
182
- | ----------------- | -------------------- | --------------------------------------------------- | --------- | ------------------------------------ |
183
- | `itemClick` | `ListItemEvent` | clique (mouse/teclado) em item | Partial | Preservado da documentação anterior. |
181
+ | Event | Payload | Trigger | Stability | Notes |
182
+ | ----------------- | -------------------- | ----------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------- |
183
+ | `itemClick` | `ListItemEvent` | clique (mouse/teclado) em item | Partial | Preservado da documentação anterior. |
184
184
  | `actionClick` | `ListActionEvent` | acao local de item, global com `emitLocal=true` ou acao de `rich-content` hospedado | Partial | `rich-content` inclui `payload?` e `source='rich-content'`. |
185
- | `selectionChange` | `ListSelectionEvent` | alteracao de selecao em `mat-selection-list` | Partial | Preservado da documentação anterior. |
186
- | `exportAction` | `any` | resultado ou erro de exportacao de colecao | Active | Usa `PraxisCollectionExportService`. |
185
+ | `selectionChange` | `ListSelectionEvent` | alteracao de selecao em `mat-selection-list` | Partial | Preservado da documentação anterior. |
186
+ | `exportAction` | `any` | resultado ou erro de exportacao de colecao | Active | Usa `PraxisCollectionExportService`. |
187
187
 
188
188
  ### External side channels
189
189
 
190
- | Channel | Direction | Contract | Failure mode | Notes |
191
- | ----------------------- | ---------------- | ------------------------------------- | ------------ | ------------------------------------------------------ |
192
- | `ASYNC_CONFIG_STORAGE` | bidirectional | `loadConfig/saveConfig` | fail-open | Persistência de configuração por `listId`/instância. |
193
- | `SettingsPanelService` | bidirectional | `open(...).applied$/saved$` | fail-open | Canal de edição runtime para `PraxisListConfigEditor`. |
194
- | `GlobalActionService` | outbound action | `executeRef(globalAction, context)` | fail-soft | Opcional; ausência gera warning e segue fluxo local. |
195
- | `GLOBAL_DIALOG_SERVICE` | bidirectional | confirmação de ação | fail-open | Opcional; sem serviço, ação segue sem modal central. |
196
- | `PRAXIS_COLLECTION_EXPORT_PROVIDER` | outbound export | `exportCollection(request)` | fail-fast | Necessário para escopos remotos `filtered/all` e formatos avançados. |
190
+ | Channel | Direction | Contract | Failure mode | Notes |
191
+ | ----------------------------------- | --------------- | ----------------------------------- | ------------ | -------------------------------------------------------------------- |
192
+ | `ASYNC_CONFIG_STORAGE` | bidirectional | `loadConfig/saveConfig` | fail-open | Persistência de configuração por `listId`/instância. |
193
+ | `SettingsPanelService` | bidirectional | `open(...).applied$/saved$` | fail-open | Canal de edição runtime para `PraxisListConfigEditor`. |
194
+ | `GlobalActionService` | outbound action | `executeRef(globalAction, context)` | fail-soft | Opcional; ausência gera warning e segue fluxo local. |
195
+ | `GLOBAL_DIALOG_SERVICE` | bidirectional | confirmação de ação | fail-open | Opcional; sem serviço, ação segue sem modal central. |
196
+ | `PRAXIS_COLLECTION_EXPORT_PROVIDER` | outbound export | `exportCollection(request)` | fail-fast | Necessário para escopos remotos `filtered/all` e formatos avançados. |
197
197
 
198
198
  ### Host/runtime dependencies
199
199
 
@@ -257,12 +257,12 @@ config explícita -> config persistida por chave -> config corrente em memória
257
257
 
258
258
  ### Validation model
259
259
 
260
- | Path/Rule | Validation phase | Behavior on fail | Error code / warning | Notes |
261
- | ---------------------------------- | ----------------------- | ----------------------------- | ---------------------------------------- | ------------------------------------------------ |
262
- | `listId` para persistência | init/runtime | disable persistence silently | n/a | Lista continua funcional sem restore/save. |
260
+ | Path/Rule | Validation phase | Behavior on fail | Error code / warning | Notes |
261
+ | ---------------------------------- | ----------------------- | ----------------------------- | ---------------------------------------- | ----------------------------------------------- |
262
+ | `listId` para persistência | init/runtime | disable persistence silently | n/a | Lista continua funcional sem restore/save. |
263
263
  | Json Logic `showIf` inválido | runtime evaluate | warning + fallback false | `praxis-list:invalid-show-if` | Evita render incorreto por condição malformada. |
264
- | `GlobalActionService` indisponível | runtime action dispatch | warning + skip comando global | `praxis-list:global-command-unavailable` | Não interrompe ações locais/emissão de eventos. |
265
- | inferência de schema falha | startup/runtime | ignore error | n/a | Mantém configuração original sem inferência. |
264
+ | `GlobalActionService` indisponível | runtime action dispatch | warning + skip comando global | `praxis-list:global-command-unavailable` | Não interrompe ações locais/emissão de eventos. |
265
+ | inferência de schema falha | startup/runtime | ignore error | n/a | Mantém configuração original sem inferência. |
266
266
 
267
267
  ### Error semantics
268
268
 
@@ -270,12 +270,12 @@ A maior parte das falhas opera em modo fail-open (persistência, inferência, co
270
270
 
271
271
  ### Fail-open / fail-closed behavior
272
272
 
273
- | Condition | Mode | Runtime behavior | Consumer impact |
274
- | --------------------------------- | --------- | ------------------------------------------------ | ---------------------------------- |
275
- | Falha em `loadConfig/saveConfig` | fail-open | ignora persistência e mantém config ativa | sem perda de renderização |
273
+ | Condition | Mode | Runtime behavior | Consumer impact |
274
+ | --------------------------------- | ----------- | ------------------------------------------------ | ---------------------------------- |
275
+ | Falha em `loadConfig/saveConfig` | fail-open | ignora persistência e mantém config ativa | sem perda de renderização |
276
276
  | `showIf` invalido | fail-closed | item/acao e ocultado com warning | evita renderizacao indevida |
277
- | comando global não disponível | fail-open | ação global não executa; fluxo local continua | comportamento parcial, sem crash |
278
- | contrato de seleção inconsistente | fail-soft | adapter normaliza payload para formato suportado | pode reduzir fidelidade do payload |
277
+ | comando global não disponível | fail-open | ação global não executa; fluxo local continua | comportamento parcial, sem crash |
278
+ | contrato de seleção inconsistente | fail-soft | adapter normaliza payload para formato suportado | pode reduzir fidelidade do payload |
279
279
 
280
280
  ### Invalid or unknown field handling
281
281
 
@@ -382,19 +382,19 @@ Quatro superficies governam o componente:
382
382
 
383
383
  #### Integracao com ecossistema Praxis
384
384
 
385
- | Componente/Servico | Papel | Como se conecta |
386
- | ---------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------ |
387
- | `ListDataService` | pipeline de dados local/remoto | `dataSource.data/resourcePath/query/sort` |
388
- | `ListSkinService` | classes e CSS dinamico | `skin.*` + `layout.density/itemSpacing/model/lines` |
389
- | `SettingsPanelService` | edicao runtime | `openConfigEditor()` com `PraxisListConfigEditor` retornando `ListAuthoringDocument` |
390
- | `PraxisListConfigEditor` | autoria visual do documento | tabs visuais + aba JSON canônica |
391
- | `GlobalActionService` | acoes globais estruturadas | `actions[].globalAction` |
392
- | `GLOBAL_DIALOG_SERVICE` | confirmacao de acao | `actions[].confirmation` |
393
- | `ASYNC_CONFIG_STORAGE` | persistencia de config | `praxis-list-config-${componentKeyId}` |
394
- | `ComponentKeyService` | identidade de instancia | `listId + componentInstanceId + route` |
395
- | `PraxisCollectionExportService` | exportação de coleção | CSV/JSON local; provider para export remoto/formatos avançados |
396
- | `PraxisAiAssistantShellComponent` + `ListAgenticAuthoringTurnFlow` + `ListAiAdapter` | copiloto semantico governado | ativo com `enableCustomization=true`; rejeita patch JSON livre e exige `componentEditPlan` manifest-backed antes de apply local |
397
- | `GenericCrudService` | dados remotos e inferencia de schema | `/filter` + fallback `getAll` + `getSchema` |
385
+ | Componente/Servico | Papel | Como se conecta |
386
+ | ------------------------------------------------------------------------------------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
387
+ | `ListDataService` | pipeline de dados local/remoto | `dataSource.data/resourcePath/query/sort` |
388
+ | `ListSkinService` | classes e CSS dinamico | `skin.*` + `layout.density/itemSpacing/model/lines` |
389
+ | `SettingsPanelService` | edicao runtime | `openConfigEditor()` com `PraxisListConfigEditor` retornando `ListAuthoringDocument` |
390
+ | `PraxisListConfigEditor` | autoria visual do documento | tabs visuais + aba JSON canônica |
391
+ | `GlobalActionService` | acoes globais estruturadas | `actions[].globalAction` |
392
+ | `GLOBAL_DIALOG_SERVICE` | confirmacao de acao | `actions[].confirmation` |
393
+ | `ASYNC_CONFIG_STORAGE` | persistencia de config | `praxis-list-config-${componentKeyId}` |
394
+ | `ComponentKeyService` | identidade de instancia | `listId + componentInstanceId + route` |
395
+ | `PraxisCollectionExportService` | exportação de coleção | CSV/JSON local; provider para export remoto/formatos avançados |
396
+ | `PraxisAiAssistantShellComponent` + `ListAgenticAuthoringTurnFlow` + `ListAiAdapter` | copiloto semantico governado | ativo com `enableCustomization=true`; rejeita patch JSON livre e exige `componentEditPlan` manifest-backed antes de apply local |
397
+ | `GenericCrudService` | dados remotos e inferencia de schema | `/filter` + fallback `getAll` apenas sem critérios ativos + `getSchema` |
398
398
 
399
399
  #### Checklist corporativo pre-flight
400
400
 
@@ -402,7 +402,7 @@ Antes de liberar para producao:
402
402
 
403
403
  - Defina `listId` estavel por tela.
404
404
  - Em multi-instancia, defina `componentInstanceId`.
405
- - Se remoto: valide `resourcePath` e politica de fallback (`/filter` -> `getAll`).
405
+ - Se remoto: valide `resourcePath`; o fallback `/filter` -> `getAll` existe apenas para consulta sem critérios ativos.
406
406
  - Em `actions[].globalAction`, aplique governanca de acoes globais no host.
407
407
  - Para `type='html'`, mantenha origem confiavel do conteudo.
408
408
  - Nao trate `showIf` como autorizacao; backend continua soberano.
@@ -411,13 +411,14 @@ Antes de liberar para producao:
411
411
 
412
412
  #### Component inputs
413
413
 
414
- | Input | Tipo | Required | Default | O que controla | Runtime |
415
- | --------------------- | -------------------------------- | ------------ | ------------------ | -------------------------- | ------- |
416
- | `config` | `PraxisListConfig` | Yes (logico) | sem default seguro | Contrato principal | Active |
417
- | `listId` | `string` | Yes | sem default | identidade de persistencia | Active |
418
- | `componentInstanceId` | `string \| undefined` | No | `undefined` | isolamento de instancias | Active |
419
- | `form` | `FormGroup \| null \| undefined` | No | `undefined` | binding de selecao externa | Active |
420
- | `enableCustomization` | `boolean` | No | `false` | editor + AI assistant | Active |
414
+ | Input | Tipo | Required | Default | O que controla | Runtime |
415
+ | --------------------- | -------------------------------- | ------------ | ------------------ | --------------------------- | ------- |
416
+ | `config` | `PraxisListConfig` | Yes (logico) | sem default seguro | Contrato principal | Active |
417
+ | `listId` | `string` | Yes | sem default | identidade de persistencia | Active |
418
+ | `componentInstanceId` | `string \| undefined` | No | `undefined` | isolamento de instancias | Active |
419
+ | `queryContext` | `PraxisDataQueryContext \| null` | No | `undefined` | filtros/sort/página runtime | Active |
420
+ | `form` | `FormGroup \| null \| undefined` | No | `undefined` | binding de selecao externa | Active |
421
+ | `enableCustomization` | `boolean` | No | `false` | editor + AI assistant | Active |
421
422
 
422
423
  #### Component outputs
423
424
 
@@ -440,18 +441,21 @@ Regras operacionais:
440
441
 
441
442
  - Local tem precedencia sobre remoto quando ambos estao presentes.
442
443
  - Remoto usa `filter(query, pageable)`.
443
- - Em erro no `/filter`, faz fallback para `getAll()` com warning deduplicado.
444
+ - Em erro no `/filter` sem critérios ativos, faz fallback de compatibilidade para `getAll()` com warning deduplicado.
445
+ - Em erro no `/filter` com critérios ativos, falha fechado: mantém o contexto de filtro, zera o resultado, publica `ListRemoteLoadError` em `ListDataService.error$` e oferece nova tentativa. Dados sem filtro nunca substituem silenciosamente a consulta solicitada.
444
446
  - Busca (`ui.showSearch`) aplica debounce de `300ms` e exige `ui.searchField`.
445
- - Controles de pagina/sort/search no template aparecem apenas quando `dataSource.resourcePath` esta definido.
447
+ - Busca, ordenação e exportação compartilham a toolbar superior da coleção; paginação permanece no footer. Busca, ordenação e paginação remotas aparecem apenas quando o modo resolvido é `remote`, nunca quando `data` local tem precedência sobre `resourcePath`.
448
+ - Atualizações síncronas de query, ordenação e página materializadas pelo mesmo `queryContext` são coalescidas antes do acesso HTTP; o backend recebe somente o estado final consistente.
449
+ - `ListDataService.error$` é um `Observable<ListRemoteLoadError | null>` somente leitura; consumidores podem reagir e solicitar `refresh()`, mas não publicar estados de erro no serviço.
446
450
  - Quando nao ha `dataSource.data` nem `dataSource.resourcePath`, o runtime renderiza um empty state operacional orientando a conexao da lista a um recurso.
447
451
 
448
452
  Matriz de decisao (runtime atual):
449
453
 
450
- | `dataSource.data` | `dataSource.resourcePath` | Modo resolvido | Superficie principal | Pipeline efetivo |
451
- | ----------------- | ------------------------- | -------------- | ------------------------------------- | ------------------------------------------------- |
452
- | `array` | qualquer valor | `local` | lista/cards/tiles | local (`data` em memoria) |
453
- | `null/undefined` | preenchido | `remote` | lista/cards/tiles + controles remotos | `filter(query, pageable)` com fallback `getAll()` |
454
- | `null/undefined` | vazio/ausente | `empty` | empty state | sem pipeline de dados |
454
+ | `dataSource.data` | `dataSource.resourcePath` | Modo resolvido | Superficie principal | Pipeline efetivo |
455
+ | ----------------- | ------------------------- | -------------- | --------------------------------------- | --------------------------------------------------------------------------- |
456
+ | `array` | qualquer valor | `local` | lista/cards/tiles | local (`data` em memoria) |
457
+ | `null/undefined` | preenchido | `remote` | lista/cards/tiles + toolbar e paginação | `filter(query, pageable)`; fallback `getAll()` somente sem critérios ativos |
458
+ | `null/undefined` | vazio/ausente | `empty` | empty state | sem pipeline de dados |
455
459
 
456
460
  Regra critica de autoria:
457
461
 
@@ -511,7 +515,7 @@ interface PraxisListConfig {
511
515
  | `actions` | Partial | quase completo; `emitPayload` sem consumo no runtime |
512
516
  | `i18n` | Active | locale/currency para `date/currency` |
513
517
  | `ui` | Active | busca/sort/range |
514
- | `export` | Active | exportação via contrato compartilhado de coleções |
518
+ | `export` | Active | exportação via contrato compartilhado de coleções |
515
519
  | `a11y` | Partial | aria ativos; `highContrast/reduceMotion` sem efeito |
516
520
  | `events` | Declared-only | mapeamentos declarados sem roteamento runtime |
517
521
 
@@ -571,16 +575,16 @@ Notas de seguranca:
571
575
 
572
576
  #### Export API
573
577
 
574
- | Caminho | Status | Observacao |
575
- | ---------------------------------- | ------ | ---------- |
576
- | `export.enabled` | Active | Renderiza menu de exportação da lista. |
577
- | `export.formats` | Active | `csv/json/excel/pdf/print`; CSV/JSON têm fallback local. |
578
- | `export.general.scope` | Active | `auto/selected/filtered/currentPage/all`; `auto` prioriza seleção. |
579
- | `export.general.includeHeaders` | Active | Controla cabeçalho em exportações tabulares. |
580
- | `export.general.maxRows` | Active | Limita linhas no fallback local. |
581
- | `export.general.defaultFileName` | Active | Nome base do arquivo gerado. |
582
- | `export.general.includeFields` | Active | Lista de paths exportáveis ou `all` para inferência por chaves. |
583
- | `export.general.applyFormatting` | Active | Mantido para paridade com o contrato compartilhado. |
578
+ | Caminho | Status | Observacao |
579
+ | -------------------------------- | ------ | ------------------------------------------------------------------ |
580
+ | `export.enabled` | Active | Renderiza menu de exportação da lista. |
581
+ | `export.formats` | Active | `csv/json/excel/pdf/print`; CSV/JSON têm fallback local. |
582
+ | `export.general.scope` | Active | `auto/selected/filtered/currentPage/all`; `auto` prioriza seleção. |
583
+ | `export.general.includeHeaders` | Active | Controla cabeçalho em exportações tabulares. |
584
+ | `export.general.maxRows` | Active | Limita linhas no fallback local. |
585
+ | `export.general.defaultFileName` | Active | Nome base do arquivo gerado. |
586
+ | `export.general.includeFields` | Active | Lista de paths exportáveis ou `all` para inferência por chaves. |
587
+ | `export.general.applyFormatting` | Active | Mantido para paridade com o contrato compartilhado. |
584
588
 
585
589
  Escopos remotos `filtered`/`all` e formatos `excel/pdf/print` exigem provider em `@praxisui/core`.
586
590
 
@@ -653,16 +657,16 @@ Tipo declarado sem renderer dedicado:
653
657
 
654
658
  #### Expansion API
655
659
 
656
- | Caminho | Status | Observacao |
657
- | --------------------------------- | ------ | ---------------------------------------- |
658
- | `expansion.sections` | Active | array de secoes da detail row |
659
- | `expansion.sections[].id` | Active | identidade da secao |
660
- | `expansion.sections[].title` | Active | titulo visivel da secao |
661
- | `expansion.sections[].type` | Active | `info-list/chip-list/timeline/key-value/metadata/component/rich-content` |
662
- | `expansion.sections[].itemsExpr` | Active | expr de colecao/objeto por item |
663
- | `expansion.sections[].document` | Active | `RichContentDocument` canonico para secoes `rich-content` |
664
- | `expansion.sections[].documentExpr` | Active | expr que resolve um `RichContentDocument` por item |
665
- | `expansion.sections[].emptyLabel` | Active | mensagem vazia por secao |
660
+ | Caminho | Status | Observacao |
661
+ | ----------------------------------- | ------ | ------------------------------------------------------------------------ |
662
+ | `expansion.sections` | Active | array de secoes da detail row |
663
+ | `expansion.sections[].id` | Active | identidade da secao |
664
+ | `expansion.sections[].title` | Active | titulo visivel da secao |
665
+ | `expansion.sections[].type` | Active | `info-list/chip-list/timeline/key-value/metadata/component/rich-content` |
666
+ | `expansion.sections[].itemsExpr` | Active | expr de colecao/objeto por item |
667
+ | `expansion.sections[].document` | Active | `RichContentDocument` canonico para secoes `rich-content` |
668
+ | `expansion.sections[].documentExpr` | Active | expr que resolve um `RichContentDocument` por item |
669
+ | `expansion.sections[].emptyLabel` | Active | mensagem vazia por secao |
666
670
 
667
671
  Notas de UX/WCAG:
668
672
 
@@ -677,27 +681,27 @@ Notas de UX/WCAG:
677
681
 
678
682
  #### Actions API
679
683
 
680
- | Caminho | Status | Observacao |
681
- | -------------------------------- | ------------- | ----------------------------------------------------------- |
682
- | `actions[].id` | Active | identificador da acao |
683
- | `actions[].icon` | Active | icone |
684
- | `actions[].label` | Active | label/aria-label |
685
- | `actions[].color` | Active | tema/cor custom |
686
- | `actions[].kind` | Active | `icon` ou `button` |
687
- | `actions[].buttonVariant` | Active | `stroked/raised/flat` |
688
- | `actions[].showIf` | Active | condição Json Logic avaliada no contexto `row` |
689
- | `actions[].emitPayload` | Declared-only | sem uso no payload de ações nativas; ações `rich-content` hospedadas podem emitir `payload?` próprio |
690
- | `actions[].action` | Active | `surface.open` identifica a execução contextual governada quando acompanhada de `recordOpen` |
691
- | `actions[].recordOpen` | Active | referência mínima `{ sourceIdentityField, target: { resourceKey, surfaceId } }`; o runtime reconsulta catálogo, item e `_links.surfaces` antes de materializar |
692
- | `actions[].globalAction` | Active | integra com `GlobalActionService.executeRef`; suporta `navigation.openRoute` para navegação interna canônica |
693
- | `actions[].globalAction.actionId` | Active | identificador canonico da acao global |
694
- | `actions[].globalAction.payload` | Active | template/JSON resolvido recursivamente, inclusive `item.id` em rotas internas |
695
- | `actions[].globalAction.payloadExpr` | Active | escape avancado de `GlobalActionRef`; quando nao ha `payload`, o runtime nao injeta payload sintetico |
696
- | `actions[].emitLocal` | Active | emite `actionClick` mesmo com acao global |
697
- | `actions[].showLoading` | Active | spinner + disable durante execucao |
698
- | `actions[].confirmation.title` | Active | dialogo de confirmacao |
699
- | `actions[].confirmation.message` | Active | dialogo de confirmacao |
700
- | `actions[].confirmation.type` | Active | `danger/warning/info` |
684
+ | Caminho | Status | Observacao |
685
+ | ------------------------------------ | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
686
+ | `actions[].id` | Active | identificador da acao |
687
+ | `actions[].icon` | Active | icone |
688
+ | `actions[].label` | Active | label/aria-label |
689
+ | `actions[].color` | Active | tema/cor custom |
690
+ | `actions[].kind` | Active | `icon` ou `button` |
691
+ | `actions[].buttonVariant` | Active | `stroked/raised/flat` |
692
+ | `actions[].showIf` | Active | condição Json Logic avaliada no contexto `row` |
693
+ | `actions[].emitPayload` | Declared-only | sem uso no payload de ações nativas; ações `rich-content` hospedadas podem emitir `payload?` próprio |
694
+ | `actions[].action` | Active | `surface.open` identifica a execução contextual governada quando acompanhada de `recordOpen` |
695
+ | `actions[].recordOpen` | Active | referência mínima `{ sourceIdentityField, target: { resourceKey, surfaceId } }`; o runtime reconsulta catálogo, item e `_links.surfaces` antes de materializar |
696
+ | `actions[].globalAction` | Active | integra com `GlobalActionService.executeRef`; suporta `navigation.openRoute` para navegação interna canônica |
697
+ | `actions[].globalAction.actionId` | Active | identificador canonico da acao global |
698
+ | `actions[].globalAction.payload` | Active | template/JSON resolvido recursivamente, inclusive `item.id` em rotas internas |
699
+ | `actions[].globalAction.payloadExpr` | Active | escape avancado de `GlobalActionRef`; quando nao ha `payload`, o runtime nao injeta payload sintetico |
700
+ | `actions[].emitLocal` | Active | emite `actionClick` mesmo com acao global |
701
+ | `actions[].showLoading` | Active | spinner + disable durante execucao |
702
+ | `actions[].confirmation.title` | Active | dialogo de confirmacao |
703
+ | `actions[].confirmation.message` | Active | dialogo de confirmacao |
704
+ | `actions[].confirmation.type` | Active | `danger/warning/info` |
701
705
 
702
706
  Semantica de execucao:
703
707
 
@@ -711,25 +715,25 @@ Semantica de execucao:
711
715
 
712
716
  #### UI, i18n, a11y e events
713
717
 
714
- | Caminho | Status | Observacao |
715
- | ------------------------ | ------------- | --------------------------------------- |
716
- | `ui.showSearch` | Active | input de busca (somente quando remoto) |
717
- | `ui.searchField` | Active | campo da query de busca |
718
- | `ui.searchPlaceholder` | Active | label do input |
719
- | `ui.showSort` | Active | seletor de sort (somente quando remoto) |
720
- | `ui.sortOptions` | Active | `string` ou `{label,value}` |
721
- | `ui.showRange` | Active | range `X-Y de total` |
722
- | `i18n.locale` | Active | formatacao date/number |
723
- | `i18n.currency` | Active | formatacao currency |
724
- | `a11y.ariaLabel` | Active | `aria-label` do root |
725
- | `a11y.ariaLabelledBy` | Active | `aria-labelledby` do root |
726
- | `a11y.highContrast` | Declared-only | sem binding funcional |
727
- | `a11y.reduceMotion` | Declared-only | sem binding funcional |
728
- | `events.itemClick` | Declared-only | sem roteamento dinamico |
729
- | `events.actionClick` | Declared-only | sem roteamento dinamico |
730
- | `events.selectionChange` | Declared-only | sem roteamento dinamico |
731
- | `events.exportAction` | Declared-only | sem roteamento dinamico |
732
- | `events.loaded` | Declared-only | sem roteamento dinamico |
718
+ | Caminho | Status | Observacao |
719
+ | ------------------------ | ------------- | ---------------------------------------------- |
720
+ | `ui.showSearch` | Active | busca na toolbar superior (somente remoto) |
721
+ | `ui.searchField` | Active | campo da query de busca |
722
+ | `ui.searchPlaceholder` | Active | label do input |
723
+ | `ui.showSort` | Active | ordenação na toolbar superior (somente remoto) |
724
+ | `ui.sortOptions` | Active | `string` ou `{label,value}` |
725
+ | `ui.showRange` | Active | range `X-Y de total` |
726
+ | `i18n.locale` | Active | formatacao date/number |
727
+ | `i18n.currency` | Active | formatacao currency |
728
+ | `a11y.ariaLabel` | Active | `aria-label` do root |
729
+ | `a11y.ariaLabelledBy` | Active | `aria-labelledby` do root |
730
+ | `a11y.highContrast` | Declared-only | sem binding funcional |
731
+ | `a11y.reduceMotion` | Declared-only | sem binding funcional |
732
+ | `events.itemClick` | Declared-only | sem roteamento dinamico |
733
+ | `events.actionClick` | Declared-only | sem roteamento dinamico |
734
+ | `events.selectionChange` | Declared-only | sem roteamento dinamico |
735
+ | `events.exportAction` | Declared-only | sem roteamento dinamico |
736
+ | `events.loaded` | Declared-only | sem roteamento dinamico |
733
737
 
734
738
  #### Superfícies de expressão (`expr` e `showIf`)
735
739
 
@@ -778,133 +782,133 @@ AI:
778
782
 
779
783
  #### Complete JSON path index (cobertura total)
780
784
 
781
- | JSON path | Status | Observacao |
782
- | -------------------------------------- | ------------- | -------------------------------------- |
783
- | `id` | Declared-only | sem binding direto |
784
- | `dataSource` | Active | bloco de dados |
785
- | `dataSource.data` | Active | local mode |
786
- | `dataSource.resourcePath` | Active | remote mode |
787
- | `dataSource.query` | Active | query remota |
788
- | `dataSource.sort` | Active | sort remoto |
789
- | `layout` | Partial | bloco visual/estrutura |
790
- | `layout.variant` | Active | list/cards/tiles |
791
- | `layout.density` | Active | classe host |
792
- | `layout.itemSpacing` | Active | gap vertical entre itens + classe host |
793
- | `layout.lines` | Active | linhas + classe |
794
- | `layout.dividers` | Active | divisor no list |
795
- | `layout.model` | Active | classe host |
796
- | `layout.groupBy` | Active | agrupamento |
797
- | `layout.stickySectionHeader` | Declared-only | sem sticky runtime |
798
- | `layout.virtualScroll` | Declared-only | sem virtual runtime |
799
- | `layout.pageSize` | Active | pagina remota |
800
- | `skin` | Active | bloco de skin |
801
- | `skin.type` | Active | classe skin |
802
- | `skin.gradient` | Active | vars gradiente |
803
- | `skin.gradient.from` | Active | var |
804
- | `skin.gradient.to` | Active | var |
805
- | `skin.gradient.angle` | Active | var |
806
- | `skin.radius` | Active | var |
807
- | `skin.shadow` | Active | var |
808
- | `skin.border` | Active | var |
809
- | `skin.backdropBlur` | Active | var |
810
- | `skin.class` | Active | classe extra |
811
- | `skin.inlineStyle` | Active | css inline sanitizado |
812
- | `selection` | Active | bloco de selecao |
813
- | `selection.mode` | Active | none/single/multiple |
814
- | `selection.formControlName` | Active | binding form |
815
- | `selection.formControlPath` | Active | binding form |
816
- | `selection.compareBy` | Active | ids/trackBy |
817
- | `selection.return` | Active | value/item/id |
818
- | `interaction` | Partial | bloco de expansao inline V1 |
819
- | `interaction.expandable` | Active | toggle da expansao |
820
- | `interaction.expandTrigger` | Partial | coerced para `icon` quando ha selecao |
821
- | `interaction.expandMode` | Active | single/multiple |
822
- | `templating` | Partial | bloco de slots |
823
- | `templating.leading` | Active | slot |
824
- | `templating.primary` | Active | slot |
825
- | `templating.secondary` | Active | slot |
826
- | `templating.meta` | Active | slot |
827
- | `templating.trailing` | Active | slot |
828
- | `templating.sectionHeader` | Active | slot |
829
- | `templating.emptyState` | Active | slot |
830
- | `templating.<slot>.type` | Partial | `slot` sem renderer |
831
- | `templating.<slot>.expr` | Active | avaliador |
832
- | `templating.<slot>.class` | Active | estilo |
833
- | `templating.<slot>.style` | Active | estilo |
834
- | `templating.<slot>.color` | Active | chip/icon/rating |
835
- | `templating.<slot>.variant` | Active | chip variant |
836
- | `templating.<slot>.props.rating.max` | Active | rating |
837
- | `templating.<slot>.props.rating.size` | Active | rating |
838
- | `templating.<slot>.props.rating.color` | Active | rating |
839
- | `templating.<slot>.imageAlt` | Active | alt imagem |
840
- | `templating.<slot>.badge.expr` | Active | badge |
841
- | `templating.<slot>.badge.color` | Active | badge |
842
- | `templating.<slot>.badge.variant` | Active | badge |
843
- | `templating.metaPlacement` | Active | side/line |
844
- | `templating.metaPrefixIcon` | Active | prefix icon |
845
- | `templating.statusPosition` | Active | inline/top-right |
846
- | `templating.chipColorMap` | Active | map cor |
847
- | `templating.chipLabelMap` | Active | map label |
848
- | `templating.iconColorMap` | Active | map cor icon |
849
- | `templating.features` | Active | features row |
850
- | `templating.features[].icon` | Active | feature icon |
851
- | `templating.features[].expr` | Active | feature expr |
852
- | `templating.features[].class` | Active | feature class |
853
- | `templating.features[].style` | Active | feature style |
854
- | `templating.featuresVisible` | Active | toggle features |
855
- | `templating.featuresMode` | Active | icons+labels/icons-only/labels-only |
856
- | `templating.skeleton` | Active | skeleton bloco |
857
- | `templating.skeleton.count` | Active | skeleton count |
858
- | `expansion` | Partial | detail row governada |
859
- | `expansion.sections` | Active | secoes do detail row |
860
- | `expansion.sections[].id` | Active | id |
861
- | `expansion.sections[].title` | Active | title |
785
+ | JSON path | Status | Observacao |
786
+ | -------------------------------------- | ------------- | ---------------------------------------------------------------------- |
787
+ | `id` | Declared-only | sem binding direto |
788
+ | `dataSource` | Active | bloco de dados |
789
+ | `dataSource.data` | Active | local mode |
790
+ | `dataSource.resourcePath` | Active | remote mode |
791
+ | `dataSource.query` | Active | query remota |
792
+ | `dataSource.sort` | Active | sort remoto |
793
+ | `layout` | Partial | bloco visual/estrutura |
794
+ | `layout.variant` | Active | list/cards/tiles |
795
+ | `layout.density` | Active | classe host |
796
+ | `layout.itemSpacing` | Active | gap vertical entre itens + classe host |
797
+ | `layout.lines` | Active | linhas + classe |
798
+ | `layout.dividers` | Active | divisor no list |
799
+ | `layout.model` | Active | classe host |
800
+ | `layout.groupBy` | Active | agrupamento |
801
+ | `layout.stickySectionHeader` | Declared-only | sem sticky runtime |
802
+ | `layout.virtualScroll` | Declared-only | sem virtual runtime |
803
+ | `layout.pageSize` | Active | pagina remota |
804
+ | `skin` | Active | bloco de skin |
805
+ | `skin.type` | Active | classe skin |
806
+ | `skin.gradient` | Active | vars gradiente |
807
+ | `skin.gradient.from` | Active | var |
808
+ | `skin.gradient.to` | Active | var |
809
+ | `skin.gradient.angle` | Active | var |
810
+ | `skin.radius` | Active | var |
811
+ | `skin.shadow` | Active | var |
812
+ | `skin.border` | Active | var |
813
+ | `skin.backdropBlur` | Active | var |
814
+ | `skin.class` | Active | classe extra |
815
+ | `skin.inlineStyle` | Active | css inline sanitizado |
816
+ | `selection` | Active | bloco de selecao |
817
+ | `selection.mode` | Active | none/single/multiple |
818
+ | `selection.formControlName` | Active | binding form |
819
+ | `selection.formControlPath` | Active | binding form |
820
+ | `selection.compareBy` | Active | ids/trackBy |
821
+ | `selection.return` | Active | value/item/id |
822
+ | `interaction` | Partial | bloco de expansao inline V1 |
823
+ | `interaction.expandable` | Active | toggle da expansao |
824
+ | `interaction.expandTrigger` | Partial | coerced para `icon` quando ha selecao |
825
+ | `interaction.expandMode` | Active | single/multiple |
826
+ | `templating` | Partial | bloco de slots |
827
+ | `templating.leading` | Active | slot |
828
+ | `templating.primary` | Active | slot |
829
+ | `templating.secondary` | Active | slot |
830
+ | `templating.meta` | Active | slot |
831
+ | `templating.trailing` | Active | slot |
832
+ | `templating.sectionHeader` | Active | slot |
833
+ | `templating.emptyState` | Active | slot |
834
+ | `templating.<slot>.type` | Partial | `slot` sem renderer |
835
+ | `templating.<slot>.expr` | Active | avaliador |
836
+ | `templating.<slot>.class` | Active | estilo |
837
+ | `templating.<slot>.style` | Active | estilo |
838
+ | `templating.<slot>.color` | Active | chip/icon/rating |
839
+ | `templating.<slot>.variant` | Active | chip variant |
840
+ | `templating.<slot>.props.rating.max` | Active | rating |
841
+ | `templating.<slot>.props.rating.size` | Active | rating |
842
+ | `templating.<slot>.props.rating.color` | Active | rating |
843
+ | `templating.<slot>.imageAlt` | Active | alt imagem |
844
+ | `templating.<slot>.badge.expr` | Active | badge |
845
+ | `templating.<slot>.badge.color` | Active | badge |
846
+ | `templating.<slot>.badge.variant` | Active | badge |
847
+ | `templating.metaPlacement` | Active | side/line |
848
+ | `templating.metaPrefixIcon` | Active | prefix icon |
849
+ | `templating.statusPosition` | Active | inline/top-right |
850
+ | `templating.chipColorMap` | Active | map cor |
851
+ | `templating.chipLabelMap` | Active | map label |
852
+ | `templating.iconColorMap` | Active | map cor icon |
853
+ | `templating.features` | Active | features row |
854
+ | `templating.features[].icon` | Active | feature icon |
855
+ | `templating.features[].expr` | Active | feature expr |
856
+ | `templating.features[].class` | Active | feature class |
857
+ | `templating.features[].style` | Active | feature style |
858
+ | `templating.featuresVisible` | Active | toggle features |
859
+ | `templating.featuresMode` | Active | icons+labels/icons-only/labels-only |
860
+ | `templating.skeleton` | Active | skeleton bloco |
861
+ | `templating.skeleton.count` | Active | skeleton count |
862
+ | `expansion` | Partial | detail row governada |
863
+ | `expansion.sections` | Active | secoes do detail row |
864
+ | `expansion.sections[].id` | Active | id |
865
+ | `expansion.sections[].title` | Active | title |
862
866
  | `expansion.sections[].type` | Active | info-list/chip-list/timeline/key-value/metadata/component/rich-content |
863
- | `expansion.sections[].itemsExpr` | Active | expr |
864
- | `expansion.sections[].document` | Active | `RichContentDocument` para `rich-content` |
865
- | `expansion.sections[].documentExpr` | Active | expr que resolve `RichContentDocument` |
866
- | `expansion.sections[].emptyLabel` | Active | empty state da secao |
867
- | `actions` | Partial | bloco de acoes |
868
- | `actions[].id` | Active | id |
869
- | `actions[].icon` | Active | icon |
870
- | `actions[].label` | Active | label |
871
- | `actions[].color` | Active | color |
872
- | `actions[].kind` | Active | icon/button |
873
- | `actions[].buttonVariant` | Active | raised/flat/stroked |
874
- | `actions[].showIf` | Active | visibilidade |
875
- | `actions[].emitPayload` | Declared-only | sem efeito runtime |
876
- | `actions[].action` | Active | `surface.open` contextual governado |
877
- | `actions[].recordOpen` | Active | identidade mínima resolvida por catálogo e HATEOAS |
878
- | `actions[].globalAction` | Active | acao global estruturada |
879
- | `actions[].globalAction.actionId` | Active | identificador canonico da acao global |
880
- | `actions[].globalAction.payload` | Active | payload template/json |
881
- | `actions[].emitLocal` | Active | emissao local |
882
- | `actions[].showLoading` | Active | spinner/desabilita |
883
- | `actions[].confirmation` | Active | confirmacao |
884
- | `actions[].confirmation.title` | Active | confirmacao |
885
- | `actions[].confirmation.message` | Active | confirmacao |
886
- | `actions[].confirmation.type` | Active | danger/warning/info |
887
- | `i18n` | Active | bloco i18n |
888
- | `i18n.locale` | Active | locale |
889
- | `i18n.currency` | Active | currency |
890
- | `ui` | Active | bloco ui |
891
- | `ui.showSearch` | Active | input busca |
892
- | `ui.searchField` | Active | query field |
893
- | `ui.searchPlaceholder` | Active | label busca |
894
- | `ui.showSort` | Active | select sort |
895
- | `ui.sortOptions` | Active | opcoes sort |
896
- | `ui.showRange` | Active | range/total |
897
- | `a11y` | Partial | acessibilidade |
898
- | `a11y.ariaLabel` | Active | aria-label |
899
- | `a11y.ariaLabelledBy` | Active | aria-labelledby |
900
- | `a11y.highContrast` | Declared-only | sem binding |
901
- | `a11y.reduceMotion` | Declared-only | sem binding |
902
- | `events` | Declared-only | declarativo |
903
- | `events.itemClick` | Declared-only | sem roteamento runtime |
904
- | `events.actionClick` | Declared-only | sem roteamento runtime |
905
- | `events.selectionChange` | Declared-only | sem roteamento runtime |
906
- | `events.exportAction` | Declared-only | sem roteamento runtime |
907
- | `events.loaded` | Declared-only | sem roteamento runtime |
867
+ | `expansion.sections[].itemsExpr` | Active | expr |
868
+ | `expansion.sections[].document` | Active | `RichContentDocument` para `rich-content` |
869
+ | `expansion.sections[].documentExpr` | Active | expr que resolve `RichContentDocument` |
870
+ | `expansion.sections[].emptyLabel` | Active | empty state da secao |
871
+ | `actions` | Partial | bloco de acoes |
872
+ | `actions[].id` | Active | id |
873
+ | `actions[].icon` | Active | icon |
874
+ | `actions[].label` | Active | label |
875
+ | `actions[].color` | Active | color |
876
+ | `actions[].kind` | Active | icon/button |
877
+ | `actions[].buttonVariant` | Active | raised/flat/stroked |
878
+ | `actions[].showIf` | Active | visibilidade |
879
+ | `actions[].emitPayload` | Declared-only | sem efeito runtime |
880
+ | `actions[].action` | Active | `surface.open` contextual governado |
881
+ | `actions[].recordOpen` | Active | identidade mínima resolvida por catálogo e HATEOAS |
882
+ | `actions[].globalAction` | Active | acao global estruturada |
883
+ | `actions[].globalAction.actionId` | Active | identificador canonico da acao global |
884
+ | `actions[].globalAction.payload` | Active | payload template/json |
885
+ | `actions[].emitLocal` | Active | emissao local |
886
+ | `actions[].showLoading` | Active | spinner/desabilita |
887
+ | `actions[].confirmation` | Active | confirmacao |
888
+ | `actions[].confirmation.title` | Active | confirmacao |
889
+ | `actions[].confirmation.message` | Active | confirmacao |
890
+ | `actions[].confirmation.type` | Active | danger/warning/info |
891
+ | `i18n` | Active | bloco i18n |
892
+ | `i18n.locale` | Active | locale |
893
+ | `i18n.currency` | Active | currency |
894
+ | `ui` | Active | bloco ui |
895
+ | `ui.showSearch` | Active | input busca |
896
+ | `ui.searchField` | Active | query field |
897
+ | `ui.searchPlaceholder` | Active | label busca |
898
+ | `ui.showSort` | Active | select sort |
899
+ | `ui.sortOptions` | Active | opcoes sort |
900
+ | `ui.showRange` | Active | range/total |
901
+ | `a11y` | Partial | acessibilidade |
902
+ | `a11y.ariaLabel` | Active | aria-label |
903
+ | `a11y.ariaLabelledBy` | Active | aria-labelledby |
904
+ | `a11y.highContrast` | Declared-only | sem binding |
905
+ | `a11y.reduceMotion` | Declared-only | sem binding |
906
+ | `events` | Declared-only | declarativo |
907
+ | `events.itemClick` | Declared-only | sem roteamento runtime |
908
+ | `events.actionClick` | Declared-only | sem roteamento runtime |
909
+ | `events.selectionChange` | Declared-only | sem roteamento runtime |
910
+ | `events.exportAction` | Declared-only | sem roteamento runtime |
911
+ | `events.loaded` | Declared-only | sem roteamento runtime |
908
912
 
909
913
  ### Styling
910
914