@praxisui/table 8.0.0-beta.2 → 8.0.0-beta.20

package/src/lib/praxis-table.json-api.md

@@ -0,0 +1,1315 @@
+---
+title: "praxis-table JSON API (Canonical)"
+slug: "praxis-table-json-api"
+doc_type: "api-reference"
+component: "praxis-table"
+document_kind: "json-api-canonical"
+reference_mode: "canonical"
+contract_format: "json"
+contract_source: "runtime-and-code"
+description: "Referencia canonica do contrato JSON do praxis-table com cobertura de runtime, precedencia, defaults e compatibilidade."
+category: "components"
+sub_category: "table"
+audience:
+  - "frontend"
+  - "architect"
+  - "platform-team"
+level: "advanced"
+status: "active"
+owner: "praxis-ui"
+source_of_truth:
+  - "projects/praxis-table/src/lib/praxis-table.ts"
+  - "projects/praxis-table/src/lib/praxis-table.html"
+  - "projects/praxis-table/src/lib/praxis-table.scss"
+  - "projects/praxis-table/src/lib/praxis-table-toolbar.ts"
+  - "projects/praxis-table/src/lib/praxis-table-config-editor.ts"
+  - "projects/praxis-table/src/lib/behavior-config-editor/behavior-config-editor.component.ts"
+  - "projects/praxis-table/src/lib/header-appearance-editor/header-appearance-editor.component.ts"
+  - "projects/praxis-table/src/lib/columns-config-editor/columns-config-editor.component.ts"
+  - "projects/praxis-table/src/lib/rules-editor/table-rules-editor.component.ts"
+  - "projects/praxis-table/src/lib/toolbar-actions-editor/toolbar-actions-editor.component.ts"
+  - "projects/praxis-table/src/lib/filter-settings/filter-settings.component.ts"
+  - "projects/praxis-table/src/lib/messages-localization-editor/messages-localization-editor.component.ts"
+  - "projects/praxis-table/src/lib/dialogs/confirm-dialog-appearance-editor.component.ts"
+  - "projects/praxis-table/src/lib/crud-integration-editor/crud-integration-editor.component.ts"
+  - "projects/praxis-core/src/lib/models/table-config-v2.model.ts"
+  - "projects/praxis-table/src/lib/utils/action-utils.ts"
+  - "projects/praxis-core/src/lib/tokens/global-action.catalog.ts"
+  - "projects/praxis-core/src/lib/models/global-action.model.ts"
+  - "projects/praxis-core/src/lib/actions/global-action-ui.ts"
+source_of_truth_last_verified: "2026-03-05"
+publish_source_of_truth: false
+last_updated: "2026-03-05"
+toc: true
+sidebar: true
+tags:
+  - "json-api"
+  - "canonical-contract"
+  - "praxis-table"
+api_stability: "canonical"
+schema_verified: true
+runtime_verified: true
+editor_coverage_verified: false
+runtime_scope: "public"
+legacy_paths_present: false
+has_known_mismatches: true
+related_components: []
+---
+
+# praxis-table
+
+Este documento e a referencia canonica da API JSON de praxis-table.
+
+## Summary
+
+- Tipo documental: API reference canonica de contrato JSON.
+- Evidencia canonica permanece governada no frontmatter para auditoria interna, sem expor paths na publicacao.
+- Objetivo operacional: consulta rapida, auditavel e deterministica sob pressao.
+- Resumo funcional herdado: Referencia canonica da API JSON do `praxis-table`.
+
+## Authoring contract
+
+- O contrato primario de autoria do `praxis-table` e `TableAuthoringDocument` (`kind: "praxis.table.editor"`).
+- `TableAuthoringDocument` encapsula `config` + `bindings` e e o formato correto para editor visual, editor JSON, playground e fluxos de IA.
+- `TableConfig` continua sendo a projeção canonica de runtime consumida pela tabela apos normalizacao e apply plan.
+- `meta.schemaId` e `meta.serverHash` devem ser tratados como snapshot persistido de reconciliacao, nao como fonte primaria do runtime.
+- Em contexto de `praxis-crud`, o authoring canonico de `CrudMetadata` pertence a `@praxisui/crud`, mesmo que o ponto visual de entrada continue sendo o icone da tabela.
+- A superficie `crud-integration-editor` da tabela existe apenas para overrides operacionais de runtime e nao deve ser tratada como editor canonico do documento CRUD.
+
+## Scope and positioning
+
+- Escopo: contrato JSON publico e limites de comportamento observavel.
+- Fora de escopo: tutorial de adocao e walkthrough operacional detalhado.
+- Posicionamento: referencia canonicamente governada para consumidores, arquitetos e mantenedores.
+
+## Collection export actions
+
+- `config.export.enabled` habilita o pipeline nativo de exportacao da tabela e deve declarar os formatos permitidos em `config.export.formats`.
+- O menu nativo de exportacao dispara `exportAction` e baixa o artefato retornado por `PraxisCollectionExportService`.
+- Acoes em massa podem acionar o mesmo pipeline quando usam uma chave claramente de exportacao, como `bulk-export` ou `export-selected`, ou quando declaram `exportFormat`.
+- Quando `exportFormat` e declarado, o formato precisa estar habilitado em `config.export.formats`; a tabela nao deve substituir silenciosamente por outro formato.
+- Acoes genericas de download, como `download-contract`, permanecem no output `bulkAction` enquanto nao declararem `exportFormat`; isso evita capturar workflows corporativos que nao sejam exportacao tabular.
+- Para exportar apenas a selecao, combine `behavior.selection.enabled`, `config.export.general.scope: "selected"` e uma bulk action visivel apenas quando `selectedCount > 0`.
+- Quando `config.export.general.scope` e `"selected"`, a exportacao sem linhas selecionadas e bloqueada com feedback de usuario em vez de gerar um arquivo vazio.
+
+## Rich content convergence
+
+- `mapTableRendererToRichContentP0(...)` e a ponte publica e restrita entre a taxonomia atual de cell renderers do `praxis-table` e o vocabulario compartilhado `1.0` de rich content em `@praxisui/core`.
+- O subconjunto promovido nesta fase e intencionalmente pequeno: `icon`, `image`, `badge`, `chip -> badge`, `avatar`, `progress` e `compose`.
+- Renderers interativos como `button`, `toggle`, `menu`, `link`, `html` e `rating`, alem do shell de detail/expansion, continuam table-owned e fora do contrato compartilhado `1.0` ate promocao semantica explicita.
+
+## Detail rich surfaces
+- `actionBar` entra na mesma fronteira canônica de detail row para agrupar ações contextuais host-mediated.
+- `actionBar` é host-mediated:
+  - o host resolve visibilidade, disabled e dispatch
+  - o conteúdo visual de cada botão continua em `PraxisRichContent`
+- `timeline` entra na mesma fronteira canônica de detail row ao lado de `detailList` e `cardGrid`.
+- `timeline` e host-mediated:
+  - a colecao vem de `field` ou `items`
+  - cada entrada usa `itemSchema` para mapear `title`, `subtitle`, `meta`, `icon` e `badge`
+  - o host resolve dados e fallback, mas o rendering cronologico final fica no `PraxisRichContent`
+
+- `behavior.expansion.detail.schemaContract.allowedNodes` inclui `detailList` e `cardGrid` como surfaces canônicas de detail row.
+- `list` continua sendo lista simples e nao aceita subtree declarativa por item.
+- `mediaBlock` tambem faz parte da fronteira canonica do detail row, como primitive compartilhada para avatar/imagem, headline, subtitle, meta e trailing leve.
+- `detailList` e host-mediated:
+  - a colecao vem de `field` ou `items`
+  - cada item usa `itemSchema.nodes` com `RichBlockNode[]`
+  - o contexto do item expõe `detailItem` e `detailIndex`, com aliases opcionais via `itemContext`
+  - `itemActions` permanecem no host, mas o conteudo visual do botao usa `PraxisRichContent`
+- `cardGrid` tambem e host-mediated:
+  - o host resolve o shell do grid
+  - cada card e convertido para `RichCardNode` e renderizado por `PraxisRichContent`
+  - o conteudo dos cards e limitado a `RichPresenterNode | RichComposeNode`
+- `mediaBlock` e primitive compartilhada:
+  - a tabela nao cria renderer proprio; ela delega diretamente para `PraxisRichContent`
+  - o shape e voltado a avatar/imagem, headline, subtitle, meta e trailing leve
+- O contrato alvo do primeiro corte de colecao rica e:
+
+```ts
+type DetailListNode = {
+  type: 'detailList';
+  title?: string;
+  field?: string;
+  items?: unknown[];
+  emptyText?: string;
+  itemKeyField?: string;
+  itemSchema: {
+    layout?: 'stack' | 'row' | 'card-list';
+    nodes: RichBlockNode[];
+  };
+  itemContext?: {
+    itemAlias?: string;
+    indexAlias?: string;
+  };
+  itemActions?: Array<{
+    actionId: string;
+    label: string;
+    icon?: string;
+    payloadExpr?: string;
+    visibleWhen?: JsonLogicExpression | null;
+    disabledWhen?: JsonLogicExpression | null;
+  }>;
+};
+```
+
+- O contrato alvo do segundo corte de cards densos e:
+
+```ts
+type CardGridNode = {
+  type: 'cardGrid';
+  title?: string;
+  subtitle?: string;
+  columns?: 1 | 2 | 3 | 4 | 'auto';
+  minCardWidth?: number;
+  cards: Array<{
+    id?: string;
+    title?: string;
+    subtitle?: string;
+    content: Array<RichPresenterNode | RichComposeNode>;
+  }>;
+};
+```
+
+- O contrato alvo do terceiro corte de topo rico e:
+
+```ts
+type MediaBlockNode = {
+  type: 'mediaBlock';
+  avatar?: RichAvatarNode;
+  title?: RichTextNode;
+  subtitle?: RichTextNode;
+  meta?: RichComposeNode;
+  trailing?: RichBlockNode[];
+};
+```
+
+- O contrato alvo do quarto corte cronologico e:
+
+```ts
+type TimelineNode = {
+  type: 'timeline';
+  title?: string;
+  field?: string;
+  items?: unknown[];
+  emptyText?: string;
+  itemSchema?: {
+    titleField?: string;
+    subtitleField?: string;
+    metaField?: string;
+    iconField?: string;
+    badgeField?: string;
+  };
+};
+```
+
+```ts
+type ActionBarNode = {
+  type: 'actionBar';
+  title?: string;
+  emptyText?: string;
+  actions: Array<{
+    actionId: string;
+    label: string;
+    icon?: string;
+    payloadExpr?: string;
+    visibleWhen?: JsonLogicExpression | null;
+    disabledWhen?: JsonLogicExpression | null;
+  }>;
+};
+```
+
+## Support legend
+
+- Active: suportado e observado no runtime atual.
+- Partial: suporte parcial, com restricoes conhecidas.
+- Declared-only: declarado em tipos/schema sem ligacao runtime confirmada.
+- Schema-only: presente em schema/modelo sem confirmacao de execucao.
+- Deprecated: mantido por compatibilidade legada com migracao prevista.
+
+## Contract classification
+
+### Canonical runtime paths (public contract)
+
+| Path | Type | Required | Default | Status | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `meta` | object | No | `{}` | Active | Metadados de versao/hash/contexto da configuracao. |
+| `columns[]` | array | Yes | `[]` | Active | Definicao estrutural principal da tabela. |
+| `behavior` | object | No | component-defaults | Active | Regras de paginação, sort, filter, selection, expansion, loading. |
+| `appearance` | object | No | component-defaults | Active | Densidade, responsividade, tokens e comportamento visual. |
+| `toolbar` | object | No | component-defaults | Active | Ações globais, busca e controles de topo. |
+| `actions` | object | No | component-defaults | Active | Ações por linha/lote e integrações de comando. |
+| `messages` | object | No | component-defaults | Active | Textos de UX e feedbacks operacionais. |
+| `data` | object | No | component-defaults | Partial | Configuração de integração de dados server/client. |
+| `localization` | object | No | component-defaults | Partial | i18n/localização em campos e mensagens. |
+| `accessibility` | object | No | component-defaults | Partial | A11y semântica e atalhos de interação. |
+| `rowConditionalStyles[]` | array | No | `[]` | Partial | Estilos condicionais por linha. |
+| `_rowStyleRulesState` | any | No | `undefined` | Partial | Estado serializado do editor (round-trip). |
+
+### Supported legacy paths
+
+Nenhum path legado suportado foi identificado nesta revisão baseada em evidência textual preservada.
+
+### Canonical authoring envelope
+
+```ts
+type TableAuthoringDocument = {
+  kind: 'praxis.table.editor';
+  version: 1;
+  config: TableConfig;
+  bindings?: {
+    resourcePath?: string | null;
+    horizontalScroll?: 'auto' | 'wrap' | 'none';
+  };
+};
+```
+
+### Internal-only paths
+
+| Path | Internal consumer | Runtime presence | Public support | Notes |
+| --- | --- | --- | --- | --- |
+| `__forceRemoteMode__` | reconciliacao de modo de dados | Yes | No | Flag interna para forcar modo remoto em cenarios de editor/runtime. |
+
+### Experimental paths
+
+| Path | Enablement (flag/guard) | Stability | Rollout notes | Notes |
+| --- | --- | --- | --- | --- |
+| `behavior.expansion.detail.source.resourcePath` | `resourceAllowList` + `schemaContract` + renderer contract | Partial | Guard rails ativos; requer evidência de host para produção | Fluxo com fail-closed quando contrato/allowlist falha. |
+| `behavior.expansion.detail.source.hypermedia` | `_links.capabilities` + `schemaContract` + renderer contract | Partial | Usa discovery canônico do backend; fail-closed sem `rel="capabilities"` | Primeiro corte gera detail schema leve a partir do snapshot agregado. |
+
+### Hypermedia detail semantics
+
+- `behavior.expansion.detail.source.mode = "hypermedia"` começa sempre em `_links.capabilities`.
+- `surfaces`, `actions` e `canonicalOperations` são lidos do `ResourceCapabilitySnapshot` retornado pelo backend.
+- O primeiro corte monta um detail schema leve de resumo contextual; ele não embute execução inline de `surface.open` nem de workflow.
+- O runtime faz prefetch por linha apenas quando `actions.row.enabled=true`. Em cenários com expansion `hypermedia` sem row actions, o discovery contextual é resolvido sob demanda na expansão da linha.
+- `actions.row.discovery.enabled=false` desliga somente o enriquecimento automático de ações por linha. Use este modo para telas corporativas curadas, nas quais o host quer expor apenas `actions.row.actions[]` e evitar overflow/actions descobertas por HATEOAS/capabilities. O default permanece habilitado quando o campo é omitido.
+
+## Overview
+
+Este arquivo foi adaptado para o padrao canonico atual sem remover conteudo tecnico existente. O conteudo detalhado anterior foi preservado para manter rastreabilidade historica e reduzir perda de contexto.
+
+## Public contract surface
+
+### Top-level configuration blocks
+
+| Block | Purpose | Required | Merge strategy | Notes |
+| --- | --- | --- | --- | --- |
+| `meta` | Identidade/versionamento da configuração | No | shallow-merge | Pode carregar `schemaId` e `serverHash` como snapshot persistido de reconciliação; o runtime usa estado transitório para verificação ativa de schema. |
+| `columns[]` | Estrutura de colunas e renderers | Yes | replace-array | Nucleo funcional do runtime de tabela. |
+| `behavior` | Regras operacionais (sort/filter/paginação/expansion) | No | deep-merge | Defaults internos aplicados por `ensureConfigDefaults()`. |
+| `appearance` | Densidade, responsividade e tema | No | deep-merge | Inclui normalização de `horizontalScroll` e breakpoints. |
+| `toolbar` | Ações e UX de topo | No | deep-merge | Integrado com editor e quick actions. |
+| `actions` | Ações de linha/lote | No | deep-merge | Roteia para eventos `rowAction`, `bulkAction` e flows de delete. |
+| `messages` | Mensagens de feedback/runtime | No | deep-merge | Fallback para mensagens padrão quando ausente. |
+| `data` | Estratégia de integração de dados | No | deep-merge | Convivência de modo remoto e local com `data` input. |
+
+### Nested configuration blocks
+
+| Path | Type | Required | Default | Constraints | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `behavior.pagination` | object | No | component-defaults | component-defined | Estratégia client/server e tamanho de página. |
+| `behavior.filtering` | object | No | component-defaults | component-defined | Filtros simples/avançados e debounce. |
+| `behavior.selection` | object | No | component-defaults | component-defined | Single/multiple, persistência e UX visual. |
+| `behavior.expansion` | object | No | component-defaults | contract-version-aware | Contrato de detail row e políticas fail-closed/fallback. |
+| `behavior.expansion.interaction.toggleIcon` | object | No | runtime-defaults | icon-name strings | Customiza ícones recolhido/expandido e `ariaLabelCollapsed`/`ariaLabelExpanded` do toggle sem alterar a lógica de expansão; usa o pipeline `[praxisIcon]` do host e preserva fallback legado para `ariaLabel`. |
+| `behavior.expansion.interaction.motion` | object | No | runtime-defaults | preset-driven | Presets controlados (`none`, `subtle-slide`, `accordion`, `fade-scale`) com respeito a `prefers-reduced-motion`; `durationMs` aceita `0` para desabilitar motion temporal. |
+| `appearance.responsive` | object | No | component-defaults | numeric-breakpoint | Breakpoint móvel inválido é normalizado para `768`. |
+| `toolbar.actions[]` | array | No | `[]` | action-contract | Ações de toolbar com roteamento para `toolbarAction`/`bulkAction`. |
+| `actions.row.discovery.enabled` | boolean | No | `true` | row-action-discovery | Controla se row actions podem ser enriquecidas por HATEOAS/capabilities. Configure `false` para manter somente ações declaradas em `actions.row.actions[]`. |
+| `columns[].renderer` | object | No | field-type-driven | renderer-contract | Renderers condicionais, payload expr e ações interativas. |
+
+### Toolbar contract
+
+- O bloco `toolbar` continua parte do contrato público principal.
+- Use `toolbar.actions[]` para quick actions e `toolbar.search` para busca quando o host não injeta shell própria.
+- Para localizar paths específicos de toolbar, complemente a leitura com o `Appendix: JSON path index`.
+
+### Messages contract
+
+- O bloco `messages` governa copy operacional, affordances de confirmação, labels de toolbar e feedbacks corporativos.
+- Prefira `messages` para texto/public contract; reserve providers globais para políticas de tenant.
+- Para busca rápida de paths e defaults parciais, complemente a leitura com o `Appendix: JSON path index`.
+
+### Input bindings
+
+| Binding/Path | Type | Required | Source | Runtime normalization | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `config` | `TableConfig` | Yes (logical) | component-input | `ensureConfigDefaults` + guards | Contrato JSON principal da tabela. |
+| `resourcePath` | `string` | Conditional | component-input | `crudService.configure(resourcePath)` | Fonte remota de dados/schema quando em modo remoto. |
+| `data` | `any[] \| null` | No | component-input | `dataSource.data = data` | Ativa caminho de dados locais. |
+| `tableId` | `string` | Yes | component-input | trim + component key builder | Necessário para persistência/configuração por instância. |
+| `componentInstanceId` | `string \| undefined` | No | component-input | component key scoping | Isola preferências por instância em mesma rota. |
+| `title` | `string` | No | component-input | host-surface passthrough | Título opcional consumido por superfícies auxiliares, quick connect e contextos host. |
+| `subtitle` | `string` | No | component-input | host-surface passthrough | Subtítulo opcional para contexto operacional do host. |
+| `icon` | `string` | No | component-input | host-surface passthrough | Ícone opcional usado em affordances auxiliares do runtime. |
+| `autoDelete` | `boolean` | No | component-input | boolean coercion | Ativa deleção automática quando o host delega esse fluxo ao runtime. |
+| `enableCustomization` | `boolean` | No | component-input | boolean coercion | Controla entrada em editor/configuração; default canônico `false`. |
+| `dense` | `boolean` | No | component-input | boolean coercion | Força modo compacto quando o host precisa sobrepor densidade do contrato. |
+| `notifyIfOutdated` | `'inline' \| 'snackbar' \| 'both' \| 'none'` | No | component-input | enum validation + prefs fallback | Política de aviso de drift de schema; o host escolhe banner inline, snackbar, ambos ou silêncio explícito. |
+| `snoozeMs` | `number` | No | component-input | numeric fallback + prefs fallback | Janela de snooze para avisos de drift; default do input é `86400000` (24h) e políticas globais podem complementar. |
+| `autoOpenSettingsOnOutdated` | `boolean` | No | component-input | schema-prefs resolution | Abre automaticamente o settings panel quando drift de schema é detectado. |
+| `crudContext` | `any` | No | component-input | host-context passthrough | Contexto opcional usado por flows compostos e integrações host/CRUD. |
+
+Migration note:
+- `enableCustomization=false` is now the canonical default.
+- Hosts that need runtime authoring/settings must pass `enableCustomization=true` explicitly.
+
+### Output events
+
+`selectionChange` is an active output for Dynamic Page composition. It emits
+`{ trigger, row?, selectedRows, selectedCount, tableId? }` when the user changes
+row selection through table affordances.
+
+| Event | Payload | Trigger | Stability | Notes |
+| --- | --- | --- | --- | --- |
+| `rowClick` | `{ row, index }` | Clique em linha. | Partial | Preservado da documentação anterior. |
+| `rowDoubleClick` | `{ action, row }` | Duplo clique quando habilitado. | Partial | Preservado da documentação anterior. |
+| `rowExpansionChange` | `RowExpansionChangeEvent` | Evento canônico para expand/collapse de detail row no runtime P0A (caminho não virtualizado), com payload discriminado por política de exposição (`allowRawExposure` + `eventExposureDefault`). | Partial | Preservado da documentação anterior. |
+| `rowAction` | `{ action, row, payload?, actionConfig?, localMode?, preventedHttp? }` | Acao de linha (coluna `_actions` ou renderer interativo). `payload` e emitido quando houver `payloadExpr` em renderer interativo. Quando `actionConfig.globalAction` aponta para `navigation.openRoute`, o runtime resolve templates como `${row.id}` antes de executar a navegação interna. Para actions como `surface.open`, `payload.*` continua sendo o envelope canônico do evento entregue ao destino. | Partial | Preservado da documentação anterior. |
+| `toolbarAction` | `{ action, actionConfig? }` | Acao clicada em `toolbar.actions[]` que nao foi roteada para fluxo bulk; `actionConfig` carrega o objeto da acao quando disponivel. | Partial | Preservado da documentação anterior. |
+| `exportAction` | `{ format, request?, result?, error?, tableId? }` | Acao de exportacao acionada pelo menu `export.formats[]`; `request` segue `PraxisCollectionExportRequest`. | Active | Usa o contrato canonico de Collection Export em `@praxisui/core`. |
+| `exportAction` | `{ format, request?, result?, error?, tableId? }` | Acao de exportacao acionada pelo menu `export.formats[]`; `request` segue `PraxisCollectionExportRequest`. | Active | Usa o contrato canonico de Collection Export em `@praxisui/core`. |
+| `bulkAction` | `{ action, rows, actionConfig? }` | Acao em lote; `actionConfig` carrega a configuracao da acao quando disponivel. | Partial | Preservado da documentação anterior. |
+| `columnReorder` | `ColumnReorderEvent` | Reordenação de coluna concluída (drag/keyboard). | Partial | Inclui metadados de origem, destino e operação. |
+| `columnReorderAttempt` | `ColumnReorderAttemptEvent` | Tentativa bloqueada por política de drop-zone. | Partial | Evento diagnóstico para observabilidade e auditoria. |
+| `beforeDelete` | `row` | Antes de delete de linha. | Partial | Preservado da documentação anterior. |
+| `afterDelete` | `row` | Depois de delete com sucesso. | Partial | Preservado da documentação anterior. |
+| `deleteError` | `{ row, error }` | Erro no delete de linha. | Partial | Preservado da documentação anterior. |
+| `beforeBulkDelete` | `rows[]` | Antes de bulk delete. | Partial | Preservado da documentação anterior. |
+| `afterBulkDelete` | `rows[]` | Depois de bulk delete com sucesso. | Partial | Preservado da documentação anterior. |
+| `bulkDeleteError` | `{ rows, error }` | Erro em operação de delete em lote. | Partial | Preservado da documentação anterior. |
+| `schemaStatusChange` | `{ outdated, serverHash?, lastVerifiedAt?, trigger?, tableId? }` | Verificação de versão de schema concluída. | Partial | Usado para notificação de drift entre runtime e servidor. |
+| `metadataChange` | `{ trigger, meta, tableId? }` | Metadados operacionais atualizados pelo runtime/editor. | Partial | Emite contexto de trigger e a carga corrente de `config.meta`. |
+| `loadingStateChange` | `LoadingState` | Mudança de estado (`config/schema/data/render`). | Active | Emitido por `emitLoadingState()`. |
+
+### External side channels
+
+| Channel | Direction | Contract | Failure mode | Notes |
+| --- | --- | --- | --- | --- |
+| `ASYNC_CONFIG_STORAGE` | bidirectional | `loadConfig/saveConfig/clearConfig` | fail-open | Persistência de config e inputs por `tableId`/instância. |
+| `CONNECTION_STORAGE` | bidirectional | `loadConnection/saveConnection` | fail-open | Persistência de `resourcePath` para quick-connect. |
+| `SettingsPanelService` | bidirectional | `open(...).applied$/saved$` | fail-open | Canal de edição em runtime (quick connect/editor). |
+| `Global resolver: PAX_EXPANSION_DETAIL_RESOURCE_RESOLVER` | outbound call | function contract | fail-closed | Resolução externa de detail schema por `resource`. |
+
+### Host/runtime dependencies
+
+| Dependency | Required | Environment | Purpose | Notes |
+| --- | --- | --- | --- | --- |
+| `GenericCrudService` | Yes | browser/dev/prod | data + schema I/O | Configura endpoint e executa `filter/getSchema`. |
+| `TableDefaultsProvider` | Yes | browser/dev/prod/ssr | defaults canônicos | Base para merge inicial e fallback de configuração. |
+| `SettingsPanelService` | Yes | browser/dev/prod | edição runtime | Abre editor e quick setup/quick connect. |
+| `ASYNC_CONFIG_STORAGE` | Yes | browser/dev/prod | persistência | Guarda configurações por escopo de componente. |
+| `CONNECTION_STORAGE` | Yes | browser/dev/prod | persistência de conexão | Mantém vínculo `tableId -> resourcePath`. |
+| `LoadingOrchestrator` | Yes | browser/dev/prod/ssr | estado de loading | Coordena bloqueio/feedback por fase. |
+| `PRAXIS_LOADING_RENDERER` | Optional | browser/dev/prod/ssr | render de loading custom | Quando ausente, fluxo segue sem renderizador dedicado. |
+
+## Coverage matrix
+
+| Surface | Verified | Coverage status | Evidence | Notes |
+| --- | --- | --- | --- | --- |
+| Runtime | true | Active | source_of_truth + conteudo preservado | Revisao estrutural concluida; validacao comportamental fina pode exigir follow-up. |
+| Schema/Types | true | Partial | interfaces/modelos citados | Mapeamento formal de todos os campos ainda pode requerer refinamento. |
+| Editor/Tooling | false | Partial | secoes de editor quando presentes | Cobertura de editor/tooling nem sempre confirmada por evidencia direta. |
+
+## Runtime coverage boundaries
+
+- Cobertura consolidada com base em documentacao existente e source of truth declarado.
+- Comportamentos fora de evidencia direta foram marcados como not-yet-verified ou Partial.
+- Compatibilidade legada, quando detectada, foi separada em classificacao explicita.
+
+## Resolution model
+
+### Merge order
+
+1. defaults base (`createDefaultTableConfig` + `TableDefaultsProvider`)
+2. contrato recebido em `@Input() config`
+3. hidratação opcional de config persistida (`table-config:*`) e inputs persistidos (`table-inputs:*`)
+4. ajustes de runtime (`ensureConfigDefaults`, guards de recursos não suportados, reconciliação de modo de dados)
+5. alterações vindas de editor/settings panel (`applied$`/`saved$`)
+
+### Fallback order
+
+`resourcePath` explícito -> conexão persistida (`CONNECTION_STORAGE`) -> `data` local -> tabela sem fetch remoto.
+
+### Override points
+
+- `@Input() config`, `@Input() resourcePath`, `@Input() data`
+- edição via `SettingsPanelService` (config editor, quick connect, quick setup)
+- persistência de host (`ASYNC_CONFIG_STORAGE` e `CONNECTION_STORAGE`)
+
+### Runtime normalization
+
+- `ensureConfigDefaults()` preenche blocos ausentes sem sobrescrever intenção explícita do contrato.
+- `parseLegacyOrTableDocument()` absorve payloads legados do editor e converte para o envelope canônico de autoria antes do apply plan.
+- `sanitizeExpansionDetailSchema()` aplica contrato de nós permitidos e política de fallback.
+
+### Precedence rules
+
+- input explícito de runtime tem precedência sobre persistência local.
+- paths canônicos têm precedência sobre aliases internos remanescentes (`__forceRemoteMode__`).
+- em `behavior.expansion.detail`, contrato inválido aplica fail-closed para detail row.
+- `behavior.expansion.detail.source.mode = "hypermedia"` usa `_links.capabilities` como ponto único de entrada e não executa `surface.open` inline no primeiro corte.
+
+Observação adicional:
+- no primeiro corte, `behavior.expansion.detail.source.mode = "hypermedia"` usa `_links.capabilities` como ponto único de entrada, consome `surfaces/actions/canonicalOperations` do snapshot agregado e não executa `surface.open` inline.
+
+## Validation and error semantics
+
+### Validation model
+
+| Path/Rule | Validation phase | Behavior on fail | Error code / warning | Notes |
+| --- | --- | --- | --- | --- |
+| `tableId` para persistência | init/runtime | warn + disable persistence | `praxis-table:missing-table-id` | Tabela segue funcional sem persistir preferências. |
+| `appearance.responsive.breakpoints.mobile` | runtime normalization | fallback para `768` | `praxis-table:responsive-breakpoint-mobile-invalid` | Comportamento fail-open com warning deduplicado. |
+| `behavior.expansion.detail.schemaContract.kind/version` | runtime validation | fail-closed (sem render de detail) | `praxis-table:expansion:detail:schema-contract-kind-version-invalid` | Bloqueia detail schema inválido. |
+| `behavior.expansion.detail.source.resourcePath` allowlist | runtime validation | fail-closed | `praxis-table:expansion:detail:resource-path-not-allowlisted` | Bloqueia path fora de allowlist/URL absoluta. |
+| `behavior.expansion.detail.source.hypermedia` sem `_links.capabilities` | runtime validation | fail-closed | `praxis-table:expansion:detail:hypermedia-links-missing` | Bloqueia detail hypermedia quando o item não expõe affordance canônica. |
+| `detail rendering contract` | runtime validation | fail-closed | `praxis-table:expansion:detail:rendering-invalid` | Exige estratégia/registry consistentes. |
+
+### Error semantics
+
+Warnings cobrem preferências inválidas e ausência de `tableId` para persistência. Falhas de contratos de detail schema aplicam bloqueio local (detail row) sem derrubar renderização base da tabela.
+
+### Fail-open / fail-closed behavior
+
+| Condition | Mode | Runtime behavior | Consumer impact |
+| --- | --- | --- | --- |
+| Configuração persistida indisponível | fail-open | ignora storage e usa defaults/inputs | componente continua operacional |
+| `resourcePath` inválido para detail schema | fail-closed (escopo detail) | não expande detail row e registra warning/error | linha segue visível sem detalhe |
+| Contrato `schemaContract` inválido | fail-closed (escopo detail) | bloqueia render de detail | evita execução de contrato não confiável |
+| Campos opcionais desconhecidos no JSON | fail-open | ignorados ou mantidos sem efeito | baixo impacto, requer revisão de contrato |
+
+### Invalid or unknown field handling
+
+- Campos desconhecidos: comportamento depende da estrategia do componente (ignore, warn ou reject).
+- Campos invalidos: podem gerar fallback, warning ou falha conforme implementacao.
+- Registrar divergencias observadas em Known limitations and mismatches.
+
+### Runtime warnings vs hard failures
+
+| Condition | Severity | Observability | Consumer action |
+| --- | --- | --- | --- |
+| partial-or-declared-only-coverage | warning | logs/eventos do componente | confirmar ligacao runtime antes de uso critico |
+
+## Detailed API
+
+### Preserved technical reference (normalized from previous revision)
+
+### Summary
+
+Referencia canonica da API JSON do `praxis-table`.
+- O componente consome `TableConfig` + inputs externos (`resourcePath`, `data`, `tableId`) e side-channels de integracao.
+- Este documento cobre contrato, cobertura de runtime, precedencia, defaults, eventos e exemplos copiaveis.
+- Fora de escopo: implementacao detalhada do host app, backend e UI de editores alem dos contratos que afetam runtime.
+
+### Support legend
+
+- **Active**
+- **Partial**
+- **Declared-only**
+- **Schema-only**
+- **Deprecated**
+
+### Overview
+`praxis-table` nao e apenas um grid ou uma tabela convencional. Ele funciona
+como um motor de renderizacao dinamico orientado a contrato (`TableConfig`).
+Em vez de criar um template para cada tela de listagem, voce entrega a planta
+(JSON) e o runtime monta a obra em tempo de execucao.
+
+Em arquiteturas tradicionais, cada variacao de colunas, acoes e filtros costuma
+virar nova camada de HTML + estado + condicionais. Aqui, a estrategia e inverter
+o custo: a mudanca fica na configuracao. Quando o requisito muda, o contrato muda
+e a interface se adapta sem reescrever o componente.
+
+Em linguagem simples: o JSON e a planta; a tabela e a obra. Troque a planta e o
+resultado muda sem retrabalho de template.
+
+Conceitos-chave:
+
+- UI declarativa / schema-driven: um contrato JSON define estrutura, dados e UX.
+- Self-describing APIs: backend pode publicar OpenAPI + `x-ui` para derivar UI.
+- Separacao de dados e apresentacao: `columns` descreve dado; `appearance` e
+  `behavior` definem como apresentar/interagir.
+- Motor de regras condicional: JSON Logic como contrato canonico para estilos, visibilidade e renderizacao sem
+  ifs espalhados no template.
+- Pipeline de dados: fluxo remoto/local com estrategias de pagina, ordenacao e filtro.
+
+#### Porque este componente e diferente
+`praxis-table` nao e apenas um grid. E um runtime configuravel que interpreta um
+contrato JSON extenso e coordena varias superficies ao mesmo tempo. Em tabelas
+convencionais, cada mudanca de coluna, filtro, acao ou visual pede codigo e
+template; aqui, essas mudancas entram no JSON e o runtime responde na hora:
+
+- Configuracao declarativa profunda (TableConfig) que governa UI, dados e regras.
+- Dois modos de dados (remoto/local) com pipelines diferentes e impactos no UX.
+- Editor e runtime convivendo (settings panel, reconciliacao e marcadores).
+- JSON Logic para regras de estilos, renderizacao e comportamento condicional.
+- Persistencia e identidade atraves de `tableId` + `componentInstanceId`.
+
+O resultado e um componente "plataforma": cada bloco do contrato vira um modulo
+do runtime, e as interacoes entre esses modulos tornam o comportamento realmente
+disruptivo.
+
+#### Pitch de 30 segundos (valor)
+Uma tabela que vira plataforma. `praxis-table` transforma configuracao em
+experiencia: colunas, acoes, filtros, mensagens e regras vivem no mesmo contrato
+JSON, pronto para dados remotos ou locais, sem retrabalho de template.
+
+- **Entrega rapida**: ajuste comportamento e visual por JSON.
+- **Padrao de UX**: regras, acoes e mensagens consistentes entre telas.
+- **Escalavel**: JSON Logic e actions permitem crescer a complexidade sem fork do runtime.
+
+#### O fim do boilerplate
+Uma tabela que vira plataforma. Em vez de programar features de grade do zero,
+voce ativa capacidades nativas via contrato:
+
+- **Zero-code iteration**: adicionar botoes, trocar densidade, ajustar colunas,
+  filtros e dialogs apenas alterando JSON.
+- **Logica desacoplada (rules engine)**: destaque de linha, visibilidade de acao
+  e variacao de renderer ficam em expressoes condicionais canonicas, nao em `*ngIf` espalhado.
+- **Ecossistema embutido**: paginacao remota, virtual scroll, reorder de colunas,
+  exportacao e `praxis-filter` avancado como capacidades prontas.
+- **Eventos estruturados**: `rowAction`, `bulkAction`, `toolbarAction`, `exportAction`,
+  `columnReorder` e eventos de delete padronizam a integracao com o host.
+- **Governanca de estado**: `tableId` + `componentInstanceId` organizam
+  persistencia, reconciliacao e isolamento de instancia.
+
+#### Receitas de impacto para o overview (live-first)
+Para o overview no estilo Angular Material (`demo vivo + view code` na mesma
+card), a melhor estrategia e mostrar poucos cenarios com alta densidade de
+valor. Sugestao de ordem para a primeira dobra:
+
+1. **Dashboard financeiro**: prova `computed` + densidade + regra visual.
+2. **Micro-layout compose (CRM)**: prova poder de layout sem componente custom.
+3. **Backoffice seguro**: prova bulk com travas de negocio e confirmacao.
+4. **Rastreador de SLA**: prova de regra temporal em JSON Logic + alerta visual declarativo.
+
+Snippets curtos (prontos para cards de overview):
+
+**Receita 1 - Dashboard Financeiro**
+```json
+{
+  "appearance": { "density": "compact" },
+  "columns": [
+    { "field": "asset", "header": "Ativo" },
+    { "field": "costPrice", "header": "Custo", "type": "currency", "format": "BRL|symbol|2" },
+    { "field": "salePrice", "header": "Venda", "type": "currency", "format": "BRL|symbol|2" },
+    {
+      "field": "margin",
+      "header": "Margem",
+      "type": "currency",
+      "format": "BRL|symbol|2",
+      "computed": { "expression": { "-": [{ "var": "salePrice" }, { "var": "costPrice" }] }, "outputType": "number" }
+    }
+  ],
+  "rowConditionalStyles": [
+    { "condition": { "<": [{ "var": "computed.margin" }, 0] }, "cssClass": "row--danger" }
+  ]
+}
+```
+
+**Receita 2 - Micro-layout sem scroll (compose)**
+```json
+{
+  "columns": [
+    {
+      "field": "contact",
+      "header": "Cliente",
+      "renderer": {
+        "type": "compose",
+        "compose": {
+          "layout": { "direction": "row", "gap": 8, "align": "center" },
+          "items": [
+            { "type": "avatar", "avatar": { "srcField": "photoUrl", "initialsField": "name" } },
+            { "type": "value", "field": "name" },
+            { "type": "badge", "badge": { "textField": "status", "variant": "soft" } }
+          ]
+        }
+      }
+    }
+  ]
+}
+```
+
+**Receita 3 - Backoffice Seguro (acoes em lote)**
+```json
+{
+  "actions": {
+    "row": {
+      "enabled": true,
+      "actions": [
+        {
+          "id": "approve",
+          "label": "Aprovar",
+          "action": "approve",
+          "visibleWhen": { "===": [{ "var": "status" }, "PENDENTE"] }
+        }
+      ]
+    },
+    "bulk": {
+      "enabled": true,
+      "position": "toolbar",
+      "actions": [
+        {
+          "id": "delete",
+          "label": "Excluir selecionados",
+          "action": "delete",
+          "minSelections": 1,
+          "requiresConfirmation": true
+        }
+      ]
+    }
+  },
+  "messages": {
+    "actions": {
+      "confirmations": {
+        "deleteMultiple": "Tem certeza que deseja excluir os itens selecionados?"
+      }
+    }
+  }
+}
+```
+
+### Internal route global action
+
+```json
+{
+  "actions": {
+    "row": {
+      "enabled": true,
+      "actions": [
+        {
+          "id": "open-details",
+          "label": "Abrir detalhe",
+          "icon": "open_in_new",
+          "globalAction": {
+            "actionId": "navigation.openRoute",
+            "payload": {
+              "path": "/funcionarios/detalhe",
+              "query": { "id": "${row.id}" },
+              "state": { "source": "table", "selectedId": "${row.id}" }
+            }
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+**Receita 4 - Rastreador de SLA (tempo + alerta visual)**
+```json
+{
+  "columns": [
+    {
+      "field": "ageDays",
+      "header": "Dias em aberto",
+      "computed": { "expression": { "daysSince": [{ "var": "createdAt" }] }, "outputType": "number" }
+    }
+  ],
+  "rowConditionalStyles": [
+    {
+      "condition": {
+        "and": [
+          { ">": [{ "var": "computed.ageDays" }, 5] },
+          { "!==": [{ "var": "status" }, "RESOLVIDO"] }
+        ]
+      },
+      "cssClass": "row--danger text-bold"
+    }
+  ],
+  "rowConditionalRenderers": [
+    {
+      "condition": {
+        "and": [
+          { ">": [{ "var": "computed.ageDays" }, 5] },
+          { "!==": [{ "var": "status" }, "RESOLVIDO"] }
+        ]
+      },
+      "tooltip": { "text": "SLA violado: acao imediata necessaria", "position": "top" },
+      "animation": { "preset": "warning-attention", "repeat": 3 }
+    }
+  ]
+}
+```
+
+Para manter o overview leve, publique somente essas 4 receitas na landing da
+doc. Os demais casos (filtros avancados, logs massivos, overrides CRUD, etc.)
+ficam na aba de exemplos completos.
+
+#### Dominando a cauda longa das interfaces
+Em sistemas corporativos e aplicacoes complexas, o esforco de engenharia
+raramente esta nos fluxos principais. O custo aparece na cauda longa dos
+requisitos de UI: variacoes de regras condicionais, formatacoes especificas,
+tooltips baseados em estado e permissoes de acao que mudam por linha ou usuario.
+
+`praxis-table` foi desenhado para reduzir drasticamente esse custo de
+manutencao. Em vez de espalhar condicionais `*ngIf` no codigo, o componente
+move o poder de decisao para uma API de regras em JSON Logic e renderizadores
+condicionais/compostos. Quem define o contrato ganha controle fino da
+experiencia, com mais autonomia para produto e menos acoplamento no frontend.
+
+Impacto pratico:
+
+- Menos ramificacao de codigo no front.
+- Mais autonomia para evoluir UX por configuracao.
+- Menor risco de regressao ao escalar regras condicionais.
+
+#### Mapa de contrato e superficies
+O contrato governa 6 superficies principais:
+
+| Superficie | O que governa no JSON/API | Impacto no runtime |
+| --- | --- | --- |
+| Declarativa (UI e UX) | `columns`, `appearance`, `behavior`, `messages`, `localization` | Define estrutura visual, densidade, textos, ordenacao e comportamento base da tabela. |
+| Dados e operacao | `resourcePath`, `data[]`, `behavior.pagination.*`, `behavior.filtering.*`, `behavior.localDataMode.*` | Resolve modo (`remote/local/empty`), estrategia de pagina/filtro/sort e pipeline de dados. |
+| Regras condicionais | `rules`, `conditionalStyles`, `rowConditionalStyles`, `conditionalRenderers` | Avalia JSON Logic por linha/celula para estilo, visibilidade e renderer dinamico. |
+| Acoes e jornada | `actions`, `toolbar`, `dialogs`, `export` | Materializa acoes de linha/lote/toolbar e fluxos de confirmacao/export. |
+| Integracao externa | `tableId`, `componentInstanceId`, overrides CRUD, marcadores de painel | Conecta persistencia, reconciliacao e extensoes de host sem quebrar o contrato base. |
+| Eventos de saida | `rowAction`, `bulkAction`, `toolbarAction`, `exportAction`, `columnReorder`, `schemaStatusChange` | Entrega intencoes do usuario como eventos padronizados para o app hospedeiro reagir. |
+
+A API detalha cada superficie e explicita onde o runtime realmente consome
+(Active/Partial/Declared-only/Schema-only).
+
+#### Arquitetura orientada a contrato (como funciona)
+O componente separa estritamente dados, apresentacao e interacao, operando em
+dois eixos principais: motor interno da tabela e integracoes externas.
+
+Fluxo simplificado de execucao:
+
+1. **Interpretacao do contrato**: le `TableConfig` e resolve o modo de operacao
+   (`remote` via API, `local` via array, ou `empty`).
+2. **Montagem da superficie**: renderiza colunas, toolbar, filtros e
+   comportamentos visuais definidos em `appearance` e `behavior`.
+3. **Pipeline de dados + motor de regras**:
+   - remoto: integra `crudService` + estrategia de pagina/sort/filtro;
+   - local: aplica `computeLocalViewPipeline()` + filtros avancados;
+   - regras: executa JSON Logic para estilos condicionais, visibilidade de acoes e
+     renderizadores dinamicos por linha.
+4. **Ciclo de eventos**: emite acoes estruturadas (`rowAction`, `bulkAction`,
+   `toolbarAction`, etc.) para que a aplicacao hospedeira reaja as intencoes do usuario.
+
+#### Integracao com ecossistema Praxis (frontend e backend)
+`praxis-table` compoe o ecossistema Praxis de ponta a ponta. O mapa de
+integracao cobre frontend, contratos e backend.
+
+Frontend (UI):
+
+| Componente | Papel na experiencia | Como se conecta |
+| --- | --- | --- |
+| `praxis-table-toolbar` | Barra superior/inferior com acoes, bulk e export | `toolbar`, `actions`, `export`, `behavior.filtering.*` |
+| `praxis-filter` | Filtro avancado acoplado a toolbar | `behavior.filtering.advancedFilters.*`, `behavior.filtering.debounceTime`, `resourcePath` |
+| `praxis-empty-state-card` | Estado inicial quando nao ha conexao remota | exibido quando nao ha `resourcePath` valido |
+| `praxis-ai-assistant` | Assistente opcional nos slots de toolbar | habilitado pelo runtime (nao exposto no JSON) |
+| Angular Material + CDK | Base de tabela, menus, selecao e virtual scroll | `behavior.pagination.*`, `behavior.selection.*`, `behavior.virtualization.*`, `appearance.spacing.*` |
+
+Backend e contratos:
+
+| Componente | Papel na experiencia | Como se conecta |
+| --- | --- | --- |
+| `praxis-metadata-starter` | Publica OpenAPI + `x-ui` e o endpoint `GET /schemas/filtered` | A tabela deriva colunas, filtros e validacoes a partir do contrato |
+| `praxis-api-quickstart` | Exemplo pronto com recursos, filtros e CRUD padronizados | Demonstra o fluxo completo com `resourcePath` apontando para a API |
+
+No modo de edicao (quando `enableCustomization` esta ativo), a tabela exibe o painel
+de configuracao para ajustar colunas, behavior, appearance e regras sem editar
+codigo. Esse painel usa editores internos (`praxis-table-config-editor`,
+`behavior-config-editor`, `columns-config-editor`, `toolbar-actions-editor`,
+`messages-localization-editor`, etc.) para compor o JSON com consistencia e evitar
+divergencia entre UI e contrato.
+
+#### Checklist de integracao (pre-flight)
+Antes de plugar a tabela em um host, valide estes pontos:
+
+- `tableId` esta definido e estavel (persiste e evita colisao de storage).
+- Modo de dados decidido: `resourcePath` (remoto) ou `data[]` + flag local.
+- `columns[]` descreve o dataset real e define renderers coerentes.
+- Acoes e toolbar estao alinhadas com o roteamento `bulkAction` vs `toolbarAction`.
+- Regras condicionais: JSON Logic é o contrato canônico.
+- UX e mensagens: configure `appearance`, `messages` e `localization` para evitar
+  inconsistencias entre defaults e o comportamento esperado.
+
+### Top-level contract
+
+O contrato principal e `TableConfig` (alias de `TableConfigV2`) com extensoes de runtime aceitas no JSON:
+- Base tipada: `meta`, `columns`, `behavior`, `appearance`, `toolbar`, `actions`, `export`, `messages`, `localization`.
+- Extensoes fora do tipo estrito: `dialogs.confirm.delete`, `rowConditionalRenderers[]`, aliases legados de `behavior.virtualScroll.*` e chaves legadas de header em `actions.row.*`.
+- Artefatos auxiliares fora do `TableConfig`: `crud-overrides:<componentKeyId>` e o envelope autorado `TableAuthoringDocument`, que carrega `bindings.resourcePath` e `bindings.horizontalScroll`. A chave operacional da linha pertence ao `TableConfig` em `config.meta.idField`.
+
+### Coverage matrix
+
+Resumo de cobertura por bloco:
+
+| Bloco | Leitura executiva | Referencia detalhada |
+| --- | --- | --- |
+| `TableConfig + extensoes` | Contrato canônico consumido pelo runtime | `### JSON coverage matrix (TableConfig + extras)` |
+| Inputs/outputs do componente | API pública para host Angular | `### Component inputs` e `### Component outputs` |
+| Caminhos JSON completos | Índice detalhado para escrita manual e validação | `## JSON path index` |
+
+### Preserved source snapshot
+
+| Source | Kind | Notes |
+| --- | --- | --- |
+| `projects/praxis-table/src/lib/praxis-table.ts` | local-file | referencia preservada da versao anterior |
+| `projects/praxis-table/src/lib/praxis-table.html` | local-file | referencia preservada da versao anterior |
+| `projects/praxis-table/src/lib/praxis-table.scss` | local-file | referencia preservada da versao anterior |
+| `projects/praxis-table/src/lib/praxis-table-toolbar.ts` | local-file | referencia preservada da versao anterior |
+| `projects/praxis-table/src/lib/praxis-table-config-editor.ts` | local-file | referencia preservada da versao anterior |
+| `projects/praxis-table/src/lib/behavior-config-editor/behavior-config-editor.component.ts` | local-file | referencia preservada da versao anterior |
+| `projects/praxis-table/src/lib/header-appearance-editor/header-appearance-editor.component.ts` | local-file | referencia preservada da versao anterior |
+| `projects/praxis-table/src/lib/columns-config-editor/columns-config-editor.component.ts` | local-file | referencia preservada da versao anterior |
+| `projects/praxis-table/src/lib/rules-editor/table-rules-editor.component.ts` | local-file | referencia preservada da versao anterior |
+| `projects/praxis-table/src/lib/toolbar-actions-editor/toolbar-actions-editor.component.ts` | local-file | referencia preservada da versao anterior |
+| `projects/praxis-table/src/lib/filter-settings/filter-settings.component.ts` | local-file | referencia preservada da versao anterior |
+| `projects/praxis-table/src/lib/messages-localization-editor/messages-localization-editor.component.ts` | local-file | referencia preservada da versao anterior |
+| `projects/praxis-table/src/lib/dialogs/confirm-dialog-appearance-editor.component.ts` | local-file | referencia preservada da versao anterior |
+
+## Events
+
+`selectionChange` is an active output for Dynamic Page composition. It emits
+`{ trigger, row?, selectedRows, selectedCount, tableId? }` when the user changes
+row selection through table affordances.
+
+| Event | Payload | Trigger | Stability | Notes |
+| --- | --- | --- | --- | --- |
+| `rowClick` | `{ row, index }` | Clique em linha. | Partial | Preservado da documentação anterior. |
+| `rowDoubleClick` | `{ action, row }` | Duplo clique quando habilitado. | Partial | Preservado da documentação anterior. |
+| `rowExpansionChange` | `RowExpansionChangeEvent` | Evento canônico para expand/collapse de detail row no runtime P0A (caminho não virtualizado), com payload discriminado por política de exposição (`allowRawExposure` + `eventExposureDefault`). | Partial | Preservado da documentação anterior. |
+| `rowAction` | `{ action, row, payload?, actionConfig?, localMode?, preventedHttp? }` | Acao de linha (coluna `_actions` ou renderer interativo). `payload` e emitido quando houver `payloadExpr` em renderer interativo. | Partial | Preservado da documentação anterior. |
+| `toolbarAction` | `{ action, actionConfig? }` | Acao clicada em `toolbar.actions[]` que nao foi roteada para fluxo bulk; `actionConfig` carrega o objeto da acao quando disponivel. | Partial | Preservado da documentação anterior. |
+| `bulkAction` | `{ action, rows, actionConfig? }` | Acao em lote; `actionConfig` carrega a configuracao da acao quando disponivel. | Partial | Preservado da documentação anterior. |
+| `columnReorder` | `{ action, trigger: 'drag' \ | 'keyboard' \ | Partial | Preservado da documentação anterior. |
+| `columnReorderAttempt` | `{ action: 'columnReorderAttempt', trigger: 'drag' \ | 'keyboard', operationId, tableId, sourceField, targetField, previousIndex, currentIndex, sourceZone, targetZone, result: 'blocked', reasonCode: 'drop-zone-policy-blocked', configuredColumnDropZones[] }` | Partial | Preservado da documentação anterior. |
+| `beforeDelete` | `row` | Antes de delete de linha. | Partial | Preservado da documentação anterior. |
+| `afterDelete` | `row` | Depois de delete com sucesso. | Partial | Preservado da documentação anterior. |
+| `deleteError` | `{ row, error }` | Erro no delete de linha. | Partial | Preservado da documentação anterior. |
+| `beforeBulkDelete` | `rows[]` | Antes de bulk delete. | Partial | Preservado da documentação anterior. |
+
+## Styling API
+
+#### CSS vars principais
+| CSS var | Efeito |
+| --- | --- |
+| `--p-table-header-bg` | fundo do header |
+| `--p-table-header-fg` | cor de texto/icone do header |
+| `--p-table-border-color` | cor de borda da tabela |
+| `--p-table-row-even-bg` | zebra row |
+| `--p-table-row-hover-bg` | hover row |
+| `--p-table-row-selected-bg` | row selecionada |
+| `--p-header-padding` | padding do header |
+| `--p-header-font-size` | fonte do header |
+| `--p-header-font-weight` | peso do header |
+| `--p-header-letter-spacing` | tracking do header |
+| `--p-header-text-transform` | caixa do texto do header |
+| `--p-table-drag-handle-size` | tamanho do handle de drag (preset padrao do runtime) |
+| `--p-table-drag-handle-color` | cor do handle de drag |
+| `--p-table-drag-handle-base-opacity` | opacidade base do handle em repouso |
+| `--p-table-drag-handle-idle-bg` | fundo base do handle em repouso |
+| `--p-table-drag-handle-idle-border` | borda base do handle em repouso |
+| `--p-table-drag-handle-hover-bg` | fundo do handle em hover/focus |
+| `--p-table-drag-handle-hover-border` | borda do handle em hover/focus |
+| `--p-table-drag-handle-active-bg` | fundo do handle em estado ativo |
+| `--p-table-drag-handle-active-border` | borda do handle em estado ativo |
+| `--p-table-drag-handle-focus-ring` | cor do anel de foco do handle |
+| `--p-table-drag-handle-transition-duration` | duracao das transicoes do handle |
+| `--p-table-reorder-transition-duration` | duracao da animacao de reorder das colunas |
+| `--p-table-drag-preview-scale` | escala visual do preview durante drag |
+| `--p-table-drag-preview-shadow` | sombra do preview durante drag |
+| `--p-table-drag-status-enter-duration` | duracao da entrada da mensagem visual de reorder |
+| `--p-actions-btn-size` | tamanho de botoes de acao |
+| `--p-actions-icon-size` | tamanho de icones de acao |
+| `--p-table-state-success-*` | tokens de estado success |
+| `--p-table-state-warning-*` | tokens de estado warning |
+| `--p-table-state-danger-*` | tokens de estado danger |
+| `--p-table-state-highlight-*` | tokens de estado highlight |
+
+#### Host classes
+| Classe no host | Efeito |
+| --- | --- |
+| `density-compact` | densidade compacta |
+| `density-comfortable` | densidade padrao |
+| `density-spacious` | densidade espacada |
+| `row-borders` | bordas horizontais entre linhas |
+| `col-borders` | bordas verticais entre colunas |
+| `pfx-column-drag-enabled` | habilita layout base de DnD de colunas |
+| `pfx-column-drag-indicator` | habilita indicador visual de drag |
+
+#### DnD classes (globais)
+| Classe CSS | Escopo | Efeito |
+| --- | --- | --- |
+| `pfx-column-drag-preview` | preview gerado pelo CDK (inserido globalmente) | card visual do header durante drag (gradiente, borda, sombra e escala leve) |
+
+#### Horizontal scroll classes
+A superficie usa `horizontalScroll` com classes:
+
+- `scroll-auto`
+- `scroll-wrap`
+- `scroll-none`
+
+#### Row/cell conditional styling
+- `rowConditionalStyles` aplica classes/estilo por linha.
+- `columns[].conditionalStyles` aplica por celula.
+- Presets uteis no SCSS: `row--success`, `row--warning`, `row--danger`, `row--highlight`, `row--muted`.
+
+### Examples
+
+### Minimal valid
+
+```json
+{
+  "appearance": { "density": "compact" },
+  "columns": [
+    { "field": "asset", "header": "Ativo" },
+    { "field": "costPrice", "header": "Custo", "type": "currency", "format": "BRL|symbol|2" },
+    { "field": "salePrice", "header": "Venda", "type": "currency", "format": "BRL|symbol|2" },
+    {
+      "field": "margin",
+      "header": "Margem",
+      "type": "currency",
+      "format": "BRL|symbol|2",
+      "computed": { "expression": { "-": [{ "var": "salePrice" }, { "var": "costPrice" }] }, "outputType": "number" }
+    }
+  ],
+  "rowConditionalStyles": [
+    { "condition": { "<": [{ "var": "computed.margin" }, 0] }, "cssClass": "row--danger" }
+  ]
+}
+```
+
+### Typical/common
+
+```json
+{
+  "columns": [
+    {
+      "field": "contact",
+      "header": "Cliente",
+      "renderer": {
+        "type": "compose",
+        "compose": {
+          "layout": { "direction": "row", "gap": 8, "align": "center" },
+          "items": [
+            { "type": "avatar", "avatar": { "srcField": "photoUrl", "initialsField": "name" } },
+            { "type": "value", "field": "name" },
+            { "type": "badge", "badge": { "textField": "status", "variant": "soft" } }
+          ]
+        }
+      }
+    }
+  ]
+}
+```
+
+### Advanced
+
+```json
+{
+  "actions": {
+    "row": {
+      "enabled": true,
+      "actions": [
+        {
+          "id": "approve",
+          "label": "Aprovar",
+          "action": "approve",
+          "visibleWhen": { "===": [{ "var": "status" }, "PENDENTE"] }
+        }
+      ]
+    },
+    "bulk": {
+      "enabled": true,
+      "position": "toolbar",
+      "actions": [
+        {
+          "id": "delete",
+          "label": "Excluir selecionados",
+          "action": "delete",
+          "minSelections": 1,
+          "requiresConfirmation": true
+        }
+      ]
+    }
+  },
+  "messages": {
+    "actions": {
+      "confirmations": {
+        "deleteMultiple": "Tem certeza que deseja excluir os itens selecionados?"
+      }
+    }
+  }
+}
+```
+
+### Enterprise scenario
+
+```json
+{
+  "columns": [
+    {
+      "field": "ageDays",
+      "header": "Dias em aberto",
+      "computed": { "expression": { "daysSince": [{ "var": "createdAt" }] }, "outputType": "number" }
+    }
+  ],
+  "rowConditionalStyles": [
+    {
+      "condition": {
+        "and": [
+          { ">": [{ "var": "computed.ageDays" }, 5] },
+          { "!==": [{ "var": "status" }, "RESOLVIDO"] }
+        ]
+      },
+      "cssClass": "row--danger text-bold"
+    }
+  ],
+  "rowConditionalRenderers": [
+    {
+      "condition": {
+        "and": [
+          { ">": [{ "var": "computed.ageDays" }, 5] },
+          { "!==": [{ "var": "status" }, "RESOLVIDO"] }
+        ]
+      },
+      "tooltip": { "text": "SLA violado: acao imediata necessaria", "position": "top" },
+      "animation": { "preset": "warning-attention", "repeat": 3 }
+    }
+  ]
+}
+```
+
+## Known limitations and mismatches
+
+| Path/Behavior | Observed behavior (runtime) | Desired behavior | Impact | Tracking issue | Target fix |
+| --- | --- | --- | --- | --- | --- |
+| coverage/mapping | Evidência textual preservada indica itens Partial/Declared-only. | Cobertura confirmada por evidência runtime + schema + editor. | Pode gerar uso de paths não totalmente ligados. | to-be-linked | next-doc-cycle |
+
+## Compatibility and migration notes
+
+- Paths e aliases legados continuam aceitos para compatibilidade (`behavior.virtualScroll.*`, chaves legadas de header em `actions.row.*`), mas novos contratos devem usar caminhos canonicos atuais.
+- O side-channel de overrides CRUD (`crud-overrides:<componentKeyId>`) nao faz parte do `TableConfig`; mantenha migracao/backup dessa chave separado do payload principal.
+- Para regex em regras, a forma canonica persistida e infixa (`field matches value`); `matches(field, value)` permanece como legado suportado.
+- O editor manual de regras da tabela autora apenas JSON Logic.
+- Se houver comportamento divergente entre schema e runtime, priorize as indicacoes desta pagina em `Known limitations and mismatches` e mantenha `has_known_mismatches=true` no frontmatter enquanto a lacuna existir.
+
+### Source references
+- `projects/praxis-table/src/lib/praxis-table.ts`
+- `projects/praxis-table/src/lib/praxis-table.html`
+- `projects/praxis-table/src/lib/praxis-table.scss`
+- `projects/praxis-table/src/lib/praxis-table-toolbar.ts`
+- `projects/praxis-table/src/lib/praxis-table-config-editor.ts`
+- `projects/praxis-table/src/lib/behavior-config-editor/behavior-config-editor.component.ts`
+- `projects/praxis-table/src/lib/header-appearance-editor/header-appearance-editor.component.ts`
+- `projects/praxis-table/src/lib/columns-config-editor/columns-config-editor.component.ts`
+- `projects/praxis-table/src/lib/rules-editor/table-rules-editor.component.ts`
+- `projects/praxis-table/src/lib/toolbar-actions-editor/toolbar-actions-editor.component.ts`
+- `projects/praxis-table/src/lib/filter-settings/filter-settings.component.ts`
+- `projects/praxis-table/src/lib/messages-localization-editor/messages-localization-editor.component.ts`
+- `projects/praxis-table/src/lib/dialogs/confirm-dialog-appearance-editor.component.ts`
+- `projects/praxis-table/src/lib/crud-integration-editor/crud-integration-editor.component.ts`
+- `projects/praxis-core/src/lib/models/table-config-v2.model.ts`
+- `projects/praxis-table/src/lib/utils/action-utils.ts`
+- `projects/praxis-core/src/lib/tokens/global-action.catalog.ts`
+- `projects/praxis-core/src/lib/models/global-action.model.ts`
+- `projects/praxis-core/src/lib/actions/global-action-ui.ts`
+
+## Appendix: JSON path index
+
+| Path | Type | Required | Default | Status | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `columns[]` | `TableColumnConfig[]` | Yes | `[]` | Active | Definicao de colunas, renderers e regras de exibicao. |
+| `behavior` | `TableBehaviorConfig` | No | defaults do runtime | Partial | Inclui paginacao, filtro, selecao e expansao por blocos. |
+| `toolbar.actions[]` | `ToolbarActionConfig[]` | No | `[]` | Partial | Acoes de toolbar com roteamento para `toolbarAction` e `bulkAction`. |
+| `messages` | `TableMessagesConfig` | No | defaults internos | Partial | Overrides de i18n e mensagens operacionais. |
+| `data` | `TableDataConfig` | No | modo local/remoto autodetectado | Partial | Integra origem local ou remota conforme `resourcePath`/inputs. |
+
+## Appendix: Events summary
+
+`selectionChange` emits `{ trigger, row?, selectedRows, selectedCount, tableId? }`
+for row selection changes initiated by the user.
+
+| Event | Payload | Trigger | Stability |
+| --- | --- | --- | --- |
+| `rowClick` | `{ row, index }` | clique de linha no corpo da tabela | Partial |
+| `rowAction` | `{ action, row, payload?, actionConfig? }` | acao interativa de linha (`_actions`/renderer); `navigation.openRoute` resolve templates de linha antes da execucao e `surface.open` preserva `payload.*` como envelope canonico do evento | Partial |
+| `toolbarAction` | `{ action, actionConfig? }` | acao de toolbar fora de fluxo bulk | Partial |
+| `exportAction` | `{ format, request?, result?, error?, tableId? }` | exportacao por `PraxisCollectionExportRequest` | Active |
+| `bulkAction` | `{ action, rows, actionConfig? }` | acao em lote sobre linhas selecionadas | Partial |
+| `loadingStateChange` | `LoadingState` | mudanca de estado (`config/schema/data/render`) | Active |
+
+## Appendix: Styling API summary
+
+| Token/Class | Scope | Purpose | Notes |
+| --- | --- | --- | --- |
+| `--p-table-header-bg` / `--p-table-header-fg` | css vars | aparencia de cabecalho e contraste | Tokens principais de tema para header. |
+| `--p-table-row-*` | css vars | zebra, hover e estado selecionado de linha | Aplicados no runtime de render da tabela. |
+| `density-compact` / `density-comfortable` / `density-spacious` | host classes | controle de densidade visual | Derivadas de `appearance.density`. |
+| `.pfx-column-drag-enabled` | host class | habilita feedback visual de reordenacao | Ativada quando contrato de reorder esta habilitado. |
+| `.pfx-column-drag-indicator` | host class | indicador visual durante drag/drop | Integrada ao runtime de `columnReorder`. |
+
+### Fallback global de aparencia
+
+Quando o host salva `GlobalConfig.table.appearance`, a tabela usa esses valores como fallback corporativo para:
+
+- `appearance.density`
+- `appearance.spacing.cellPadding`
+- `appearance.spacing.headerPadding`
+- `appearance.typography.fontSize`
+- `appearance.typography.headerFontSize`
+
+Precedencia efetiva:
+
+1. `TableConfig` local informado pelo host
+2. `GlobalConfig.table.appearance`
+3. defaults hardcoded de `createDefaultTableConfig()`
+
+Campos fora de `table.appearance` mantem a semantica anterior de fallback do provider.
+
+## Editor and tooling notes
+
+- Cobertura de editor/tooling foi separada da cobertura de runtime para evitar confusao de suporte.
+- Quando nao houver evidencia direta no codigo, o status deve permanecer not yet verified.
+
+## Appendix: Examples summary
+
+### Appendix minimal valid
+
+```json
+{
+  "columns": []
+}
+```
+
+### Appendix typical/common
+
+```json
+{
+  "columns": [
+    {
+      "field": "name",
+      "header": "Nome"
+    }
+  ],
+  "behavior": {
+    "pagination": {
+      "enabled": true,
+      "pageSize": 25
+    }
+  }
+}
+```
+
+### Appendix advanced
+
+```json
+{
+  "columns": [
+    {
+      "field": "status",
+      "header": "Status",
+      "renderer": {
+        "type": "badge"
+      }
+    }
+  ],
+  "toolbar": {
+    "actions": [
+      {
+        "id": "refresh",
+        "label": "Atualizar"
+      }
+    ]
+  },
+  "behavior": {
+    "selection": {
+      "mode": "multiple"
+    }
+  }
+}
+```
+
+### Appendix enterprise scenario
+
+```json
+{
+  "columns": [],
+  "messages": {
+    "emptyState": "Nenhum registro encontrado."
+  },
+  "behavior": {
+    "expansion": {
+      "enabled": true
+    }
+  },
+  "data": {
+    "mode": "remote",
+    "resourcePath": "customers/table"
+  }
+}
+```
+
+Nota: exemplos especificos do componente foram preservados na secao detalhada para evitar perda de cobertura durante esta migracao canonicamente orientada.
+
+## Known limitations and mismatches
+
+| Path/Behavior | Observed behavior (runtime) | Desired behavior | Impact | Tracking issue | Target fix |
+| --- | --- | --- | --- | --- | --- |
+| coverage/mapping | Documento anterior indica cobertura parcial ou declared-only. | Cobertura totalmente rastreada por superficie. | Pode haver diferenca entre schema e runtime/editor. | to-be-linked | next-doc-cycle |
+
+## Compatibility and migration notes
+
+| Concern | Affected versions | Migration action | Deadline | Notes |
+| --- | --- | --- | --- | --- |
+| legacy aliases and mixed status vocabulary | pre-canonical docs | unificar para taxonomia canonica (Active/Partial/Declared-only/...) | next-doc-cycle | manter backward compatibility documentada |
+
+## Governed embeds
+
+- `behavior.expansion.detail.schemaContract.allowedNodes` agora tambem pode incluir `formRef`, `tableRef`, `chartRef`, `templateRef` e `diagramEmbed`.
+- Esses nodes continuam host-mediated:
+  - o host resolve discovery, registry, abertura e policy
+  - a tabela padroniza o shell, os metadados e a CTA do embed
+  - o miolo visual continua delegado para `PraxisRichContent`
+- `diagramEmbed` adiciona `provider`, `source` ou `sourceField` para preview governado de diagrama, sem abrir uma segunda DSL de detail row.
+
+```ts
+type DetailEmbedNode = {
+  type: 'formRef' | 'tableRef' | 'chartRef' | 'templateRef';
+  title?: string;
+  subtitle?: string;
+  description?: string;
+  caption?: string;
+  emptyText?: string;
+  schemaId?: string;
+  templateId?: string;
+  inputs?: Record<string, unknown>;
+  presetRef?: CorePresetRef;
+  action?: {
+    actionId: string;
+    label: string;
+    icon?: string;
+    payloadExpr?: string;
+    visibleWhen?: JsonLogicExpression | null;
+    disabledWhen?: JsonLogicExpression | null;
+  };
+};
+
+type DiagramEmbedNode = {
+  type: 'diagramEmbed';
+  title?: string;
+  subtitle?: string;
+  description?: string;
+  caption?: string;
+  emptyText?: string;
+  provider: 'mermaid' | 'bpmn' | 'custom';
+  source?: string;
+  sourceField?: string;
+  inputs?: Record<string, unknown>;
+  presetRef?: CorePresetRef;
+  action?: {
+    actionId: string;
+    label: string;
+    icon?: string;
+    payloadExpr?: string;
+    visibleWhen?: JsonLogicExpression | null;
+    disabledWhen?: JsonLogicExpression | null;
+  };
+};
+```