---
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-06-24"
publish_source_of_truth: false
last_updated: "2026-06-24"
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.

## AI assistant entrypoint

- `config.ai.assistant.enabled` controla a visibilidade e o acionamento do assistente de IA embarcado na tabela.
- Ausencia do campo equivale ao comportamento historico: o entrypoint continua disponivel quando o adapter de IA da tabela estiver carregado.
- Use `false` para surfaces em que o host precisa remover a acao de IA por contrato publico, sem CSS contra classes internas da tabela ou do Angular Material.
- Ao mudar para `false`, a tabela fecha o assistente e remove a sessao contextual da tabela no registry compartilhado de IA.

## Columns visibility dropdown

- `config.toolbar.columnsVisibility.enabled` controla a exibição do botão de visibilidade de colunas na barra de ferramentas.
- Por padrão, o botão de visibilidade rápida de colunas estará habilitado caso a toolbar esteja visível.
- **Guardrail de UX**: O último controle ativo no dropdown de colunas é automaticamente desabilitado quando apenas 1 coluna permanece visível, para impedir que o usuário oculte todas as colunas de dados da tabela.
- A desativação rápida de colunas reflete instantaneamente no layout visual (`displayedColumns`) e emite o evento `configChange`.

> [!WARNING]
> **Segurança Corporativa em Cenários Corporativos**: A visibilidade de colunas via dropdown da toolbar é um recurso estritamente visual (layout de apresentação do lado do cliente). A ocultação de colunas **não** protege o dado sensível da transmissão de rede nem de inspeção técnica. Se determinados campos (ex: salários, senhas ou tokens) forem confidenciais para o nível de permissão do usuário atual, a restrição de dados deve ser realizada obrigatoriamente no lado do servidor (através da filtragem de propriedades nas APIs de CRUD e consulta), e nunca por meio de ocultação puramente visual na tabela.

## 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`. |
| `toolbar.appearance` | object | No | Material 3 fallback | token-contract | Governa preset, variante, densidade, forma, divisores e tokens públicos da toolbar sem alterar a semântica das ações. |
| `actions.row.actions[].recordSurface` | object | No | none | `ResourceSurfaceCatalogItem` | Preserva a identidade canônica da superfície relacionada aberta por uma ação de linha, mantendo `actions.row.actions[].id` como identidade do botão. |
| `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. |

Quando `actions.row.discovery.enabled` esta ativo e o item publica
capabilities CRUD canonicas, `PraxisTable` pode sintetizar entradas
contextuais `view`, `edit` e `delete`. Quando o backend publica
explicitamente `operations["duplicate-draft"]`, a tabela tambem materializa
`duplicate-draft` como operacao estendida de item. Essas entradas continuam
sendo capabilities, nao workflow actions: o clique emite `rowAction` com
`actionConfig` apontando para a capability, para que um contexto CRUD ou
host composto materialize a operacao.

Renderer defaults:
- `columns[].renderer.type = "avatar"` aplica `columns[].align = "center"` quando a coluna não declara alinhamento explícito. Esse default governa header e célula para manter foto/avatar centralizados em colunas dedicadas, preservando `align`, `width` e demais overrides declarados pelo host.
- `columns[].renderer.type = "microVisualization"` renderiza a visualização compacta declarada em `renderer.microVisualization.visualization`. O caminho preferencial é metadata-driven: campos de schema com `presentation.presenter = "microVisualization"` e `presentation.visualization.surface = "table-cell"` são convertidos automaticamente para esse renderer quando o tipo é seguro para tabela. O contrato visual e a normalização pertencem a `@praxisui/core` (`PraxisPresentationVisualizationConfig`); a tabela apenas hospeda o HTML compacto em célula, compose item ou renderer condicional.

- Em tabela, campos `*Expr` da visualizacao, como `valueExpr`, `targetExpr`, `segmentsExpr`, `toneExpr` e `fallbackTextExpr`, sao resolvidos contra o contexto da linha antes de renderizar. Strings simples sao caminhos (`row.slaAtual`) e objetos seguem Json Logic. Para `kind = "comparison"`, use `points`/`pointsExpr`; `items` fica reservado para visualizacoes orientadas a itens/etapas.

### Toolbar contract

- Acoes globais de toolbar, row e bulk usam `effects[].kind = "global-action"` como envelope canonico de novo authoring.
  O campo `globalAction` plano continua aceito como fallback compatibilidade, mas nao e a superficie preferida.
- `payloadExpr` e escape avancado explicito de `GlobalActionRef`; visual authoring deve preferir `payload` estruturado e
  preservar `payloadExpr` existente apenas quando a mesma `actionId` for mantida.

- 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.
- Use `toolbar.appearance` para personalizar o chrome da toolbar por contrato governado. O runtime materializa `variant`, `density`, `shape`, `divider` e `tokens` como classes e CSS custom properties públicas; o host pode trocar aparência sem redefinir intenção, capability ou roteamento.
- Use `toolbar.appearance.preset = "table-integrated"` para compor toolbar e tabela como um unico bloco visual com tokens públicos estáveis, evitando CSS do host sobre classes internas como `praxis-toolbar-stack-top` ou `table-stack-top`.
- Tokens públicos suportados em `toolbar.appearance.tokens`: `bg`, `fg`, `borderColor`, `borderWidth`, `radius`, `shadow`, `paddingBlock`, `paddingInline`, `minHeight`, `gap`, `actionsGap`, `dividerColor`, `actionSize`, `actionRadius`, `actionBg`, `actionFg`, `actionHoverBg`, `actionActiveBg`, `actionFocusRing`, `aiAccentColor`, `statusFg`, `titleFg`, `subtitleFg`, `iconFg`, `titleFontSize`, `subtitleFontSize`, `titleFontWeight`, `identityGap`, `identityFilterGap`, `identityMinHeight`, `identityMarginBottom`, `identityIconSize` e `identityIconRadius`.
- 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. |
| `configPersistenceStrategy` | `'local-first' \| 'input-first' \| 'volatile'` | No | component-input | default `local-first` | Controla a hidratação de preferências persistidas. `volatile` renderiza apenas por inputs/runtime e não consulta nem grava `ASYNC_CONFIG_STORAGE`, útil para surfaces executivas efêmeras abertas por `surface.open`. |
| `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 | Entrada legada de compactação. Equivale a `appearance.density="compact"` apenas quando o contrato não informa `appearance.density`. |
| `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.

When the table assistant is opened, selected rows are projected into a governed
`table-row-selection` runtime digest with `selectedCount`, `idField`,
`selectedIds` and a limited sanitized `sampleRows` array. This digest grounds
LLM answers or requested actions about the selected records, but it does not
route the user's primary intent and it is not a second source of business rules.

The assistant can also materialize declared runtime operations through
`tableRuntimeOperations`. This is a reviewed, table-owned operation envelope,
not a free-form component patch. Supported operations are:

| Operation | Input | Effect |
| --- | --- | --- |
| `table.filter.apply` | `{ criteria }` | Applies advanced filter criteria through the same runtime path used by the filter UI. `criteria` is currently a simple conjunction over declared filter fields; boolean composition such as OR, `anyOf`, `oneOf` or `allOf` is not part of this runtime contract yet. |
| `table.export.run` | `{ format, scope? }` | Runs the canonical Collection Export pipeline. `scope` may override the configured export scope for this runtime action only. |

Compound filter semantics should evolve through the canonical
`PraxisDataQueryContext.filterExpression` proposal in
`projects/praxis-core/docs/rfc-query-context-filter-expression.md`, not through
implicit OR payloads in `criteria`.

When `/schemas/filtered` publishes `x-ui.resource.capabilities`, the table
assistant includes a resource capability digest in its authoring contract.
`capabilities.filter=true` only declares the flat `/filter` DTO/simple
conjunction surface. `capabilities.filterExpression=false` tells the assistant
to clarify or explain OR/nested boolean requests instead of silently applying a
degraded filter.

| 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`, renderer interativo ou CRUD capability sintetizada). `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. Para `view/edit/delete/duplicate-draft` vindos de capabilities, `actionConfig` carrega a operacao canonica e o host composto deve encaminhar ao contexto CRUD apropriado. | 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. A acao `create` de colecao pode ser materializada automaticamente a partir de `_links.create`, rel `capabilities`, surfaces e `CrudOperationResolutionService`; quando `surface.open` esta disponivel, o runtime abre a surface de criacao antes de emitir fallback. | Partial | Preservado da documentação anterior com materializacao CRUD de colecao. |
| `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. |
| `columnResize` | `{ action: 'columnResize', trigger: 'pointer' \| 'keyboard', tableId, field, header, previousWidth, currentWidth, persisted }` | Redimensionamento de coluna concluido pelo separador do header. | Partial | Usa `behavior.resizing.enabled`, respeita `columns[].resizable !== false` e persiste `columns[].width` em px quando `persistWidths !== false`. Em modo `px`, altera a largura da coluna e a largura interna do conteudo rolavel; o viewport/card externo permanece estavel. |
| `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. |
| `configChange` | `TableConfig` | Configuração materializada pelo runtime/editor/assistente. | Active | Permite que o host sincronize mudanças feitas por authoring em tempo de execução. |
| `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; não é acessado quando `configPersistenceStrategy='volatile'`. |
| `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` é uma superfície operacional para dados corporativos. Com uma
declaração pequena, a aplicação consegue exibir dados reais, paginação, colunas,
filtros, ações, mensagens e regras visuais sem reconstruir a tela a cada novo
cenário. A primeira renderização pode nascer do recurso publicado pelo backend;
os refinamentos podem vir da aplicação, do editor visual ou das preferências
persistidas.

Em arquiteturas tradicionais, cada variação de colunas, ações e filtros costuma
virar uma nova camada de HTML, estado e condicionais. Aqui, a estratégia é
inverter esse custo: a mudança entra em uma configuração governada. Quando o
requisito muda, a experiência evolui sem transformar cada ajuste em uma nova
implementação de tabela.

Conceitos-chave:

- Uma declaração publicada define estrutura, dados e experiência.
- O backend pode descrever o recurso para que a tabela derive a primeira leitura.
- Dados, apresentação e interação ficam separados, mas evoluem no mesmo contrato.
- Regras condicionais governam estilos, visibilidade e renderização sem espalhar decisões pelo template.
- Fluxos remotos ou locais preservam paginação, ordenação e filtros de forma previsível.

#### Por que este componente é diferente
O valor da Table aparece quando a tela deixa de ser um template isolado e passa
a ser uma superfície governada por contrato. Em tabelas convencionais, cada
mudança de coluna, filtro, ação ou visual pede código e template; aqui, essas
mudanças entram em uma configuração declarativa e o componente responde de forma consistente:

- A configuração da tabela governa visual, dados e regras sem espalhar decisões pelo template.
- Dados remotos e dados locais têm estratégias próprias, com impacto claro na experiência.
- O editor visual convive com a tabela renderizada para permitir autoria governada.
- Regras condicionais cobrem destaque visual, renderização e comportamento sem duplicar tela.
- Identidade estável permite persistir preferências e reconciliar instâncias com segurança.

O resultado é um componente "plataforma": cada bloco do contrato vira um módulo
do componente, e as interações entre esses módulos permitem evoluir experiências
corporativas sem transformar cada nova regra em uma nova implementação de tela.

#### Valor em uma leitura rápida
Uma tabela que vira plataforma. `praxis-table` transforma decisões declarativas
em experiência: colunas, ações, filtros, mensagens e regras vivem no mesmo
contrato operacional, pronto para dados remotos ou locais, sem retrabalho de
template.

- **Entrega rápida**: ajuste comportamento e visual por configuração governada.
- **Padrão de UX**: regras, ações e mensagens consistentes entre telas.
- **Escalável**: regras e comandos estruturados permitem crescer a complexidade sem criar forks de tela.

#### Menos código de tela, mais contrato
Uma tabela que vira plataforma. Em vez de programar cada capacidade de tabela
do zero, você ativa recursos nativos via contrato:

- **Iteração sem código de tela**: adicionar botões, trocar densidade, ajustar
  colunas, filtros e diálogos por configuração governada.
- **Lógica desacoplada**: destaque de linha, visibilidade de ação
  e variação visual ficam em regras condicionais, não em `*ngIf` espalhado.
- **Ecossistema embutido**: paginação remota, virtual scroll, reorder de colunas,
  exportação e `praxis-filter` avançado como capacidades prontas.
- **Eventos estruturados**: ações de linha, lote, toolbar, exportação e reordenação
  entregam intenções claras para a aplicação.
- **Governança de estado**: identidade estável organiza persistência,
  reconciliação e isolamento de instância.

#### Receitas de impacto
As receitas abaixo mostram capacidades que normalmente exigiriam código de tela,
mas que a Table materializa a partir do contrato. Elas funcionam como portas de
entrada para o leitor entender o valor antes de mergulhar na matriz completa da
API.

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 negócio e confirmação.
4. **Rastreador de SLA**: prova de regra temporal em JSON Logic + alerta visual declarativo.

**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 (ações 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

Configurações novas devem persistir a integração em `effects[].globalAction`. O runtime e os validadores também
leem `globalAction` plano para documentos existentes, mas editores e AI manifest devem tratar esse campo como
compatibilidade. O adapter da Table preserva `payload`/`payloadExpr` ao reabrir e re-selecionar a mesma `actionId`,
e limpa payloads ao trocar de global action para evitar semântica cruzada.

```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: ação imediata necessária", "position": "top" },
      "animation": { "preset": "warning-attention", "repeat": 3 }
    }
  ]
}
```

Essas quatro receitas cobrem o primeiro impacto. Cenários mais longos, como
filtros avançados, logs massivos e overrides CRUD, pertencem à trilha de exemplos
completos para não diluir a tese principal do runtime.

#### Dominando a cauda longa das interfaces
Em sistemas corporativos e aplicações complexas, o esforço de engenharia
raramente está nos fluxos principais. O custo aparece na cauda longa dos
requisitos de UI: variações de regras condicionais, formatações específicas,
mensagens baseadas em estado e permissões de ação que mudam por linha, perfil
ou contexto operacional.

`praxis-table` foi desenhado para reduzir drasticamente esse custo de
manutenção. Em vez de espalhar condicionais pelo código da tela, o componente
move essas decisões para uma configuração governada. Quem define a experiência
ganha controle fino sobre leitura visual, ações, filtros e mensagens, com mais
autonomia para produto e menos acoplamento no frontend.

Impacto prático:

- Menos ramificação de código no frontend.
- Mais autonomia para evoluir UX por configuração.
- Menor risco de regressão ao escalar regras condicionais.

#### Mapa de contrato e superfícies
O contrato governa 6 áreas principais:

| Área | O que governa | Impacto na experiência |
| --- | --- | --- |
| Estrutura e leitura | Colunas, aparência, comportamento, mensagens e localização | Define densidade, textos, ordenação e comportamento base da tabela. |
| Dados e operação | Recurso remoto, dados locais, paginação, filtros e ordenação | Decide como a tabela busca, pagina, filtra e apresenta os registros. |
| Regras condicionais | Regras de destaque, visibilidade e variação visual | Transforma estado operacional em sinais visuais consistentes. |
| Ações e jornada | Toolbar, ações de linha, ações em lote, diálogos e exportação | Materializa comandos e confirmações sem duplicar fluxo em cada tela. |
| Integração externa | Identidade da instância, preferências e reconciliação | Preserva persistência e isolamento entre telas, usuários e contextos. |
| Eventos de saída | Intenções estruturadas do usuário | Entrega comandos claros para a aplicação executar navegação, auditoria e regra de negócio. |

A API detalha cada área e explicita onde o comportamento está ativo, parcial,
declarado ou dependente de schema.

#### Arquitetura orientada a contrato (como funciona)
O componente separa estritamente dados, apresentação e interação, operando em
dois eixos principais: motor interno da tabela e integrações externas.

Fluxo simplificado de execução:

1. **Interpretação da configuração**: resolve se a tabela usará dados remotos,
   dados locais ou estado vazio.
2. **Montagem da superfície**: renderiza colunas, toolbar, filtros e
   comportamentos visuais definidos pela configuração.
3. **Pipeline de dados + motor de regras**:
   - remoto: consulta a operação publicada pelo backend;
   - local: aplica paginação, ordenação e filtros no conjunto recebido;
   - regras: avalia destaque visual, visibilidade de ações e variações por linha.
4. **Ciclo de eventos**: emite ações estruturadas para que a aplicação reaja às
   intenções do usuário.

#### Integração com ecossistema Praxis (frontend e backend)
`praxis-table` compõe o ecossistema Praxis de ponta a ponta. O mapa de
integração cobre frontend, contratos e backend.

Frontend (UI):

| Componente | Papel na experiência | Como se conecta |
| --- | --- | --- |
| `praxis-table-toolbar` | Barra superior/inferior com ações, bulk e export | `toolbar`, `actions`, `export`, `behavior.filtering.*` |
| `praxis-filter` | Filtro avançado acoplado à toolbar | `behavior.filtering.advancedFilters.*`, `behavior.filtering.debounceTime`, `resourcePath` |
| `praxis-empty-state-card` | Estado inicial quando não há conexão remota | exibido quando não há `resourcePath` válido |
| `PraxisAiAssistantShellComponent` | Copiloto semântico opcional nos slots de toolbar | habilitado pelo runtime com turn orchestration e contexto seguro; ao minimizar, a sessão fica no registry com `presence: "origin-anchor"` e o affordance volta ao gatilho da tabela (não exposto no JSON) |
| Angular Material + CDK | Base de tabela, menus, seleção e virtual scroll | `behavior.pagination.*`, `behavior.selection.*`, `behavior.virtualization.*`, `appearance.spacing.*` |

Backend e contratos:

| Componente | Papel na experiência | Como se conecta |
| --- | --- | --- |
| `praxis-metadata-starter` | Publica OpenAPI + `x-ui` e o endpoint `GET /schemas/filtered` | A tabela deriva colunas, filtros e validações 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 edição, quando a aplicação habilita customização, a tabela exibe o
editor visual para ajustar colunas, comportamento, aparência e regras sem editar
código de tela. Esse editor compõe a configuração com consistência e evita
divergência entre o que o usuário authora e o que a tabela renderiza.

#### Checklist de integração (pre-flight)
Antes de plugar a tabela em uma aplicação, valide estes pontos:

- A instância tem identidade estável para persistir preferências sem colisão.
- O modo de dados está decidido: recurso remoto ou conjunto local informado pela aplicação.
- As colunas descrevem o conjunto de dados real e usam apresentação coerente.
- Ações de linha, lote e toolbar estão alinhadas com os comandos da aplicação.
- Regras condicionais têm fonte clara e não ficam espalhadas pelo template.
- Aparência, mensagens e localização foram revisadas para evitar inconsistências
  entre padrões globais e 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. |
| `columnResize` | `{ action: 'columnResize', trigger: 'pointer' \| 'keyboard', tableId, field, header, previousWidth, currentWidth, persisted }` | Separador de resize no header. | Partial | Mutacao visual/runtime de largura; nao redefine schema nem dados. Em modo `px`, nao redistribui colunas vizinhas; o conteudo interno pode ficar maior que o viewport e usar scroll horizontal. |
| `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-table-row-height` | altura da linha; sobrescreve o default do preset de densidade |
| `--p-table-header-height` | altura do header; sobrescreve o default do preset de densidade |
| `--p-table-column-resize-hit-area` | area clicavel do separador de resize |
| `--p-table-column-resize-separator-color` | cor base da divisoria de resize |
| `--p-table-column-resize-separator-hover-color` | cor da divisoria em hover/focus |
| `--p-table-column-resize-active-color` | cor da divisoria durante resize |
| `--p-header-padding` | padding do header |
| `--p-cell-padding` | padding das células; sobrescreve o default do preset de densidade |
| `--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-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 da superfície visível dos botões de ação; o alvo interativo permanece em 44px |
| `--p-actions-icon-size` | tamanho dos ícones de ação dentro da superfície canônica |
| `--p-table-paginator-container-min-height` | altura minima do paginator |
| `--p-table-paginator-container-padding` | padding do paginator |
| `--p-table-paginator-container-gap` | espaçamento entre controles do paginator |
| `--p-table-paginator-action-size` | tamanho dos botoes de navegacao do paginator |
| `--p-table-paginator-select-width` | largura do seletor de tamanho de pagina |
| `--p-table-paginator-select-height` | altura do seletor de tamanho de pagina |
| `--p-table-paginator-select-padding-inline` | padding horizontal do seletor de tamanho de pagina |
| `--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 |
| `pfx-column-resize-enabled` | habilita separadores de resize no header |
| `pfx-column-resizing` | estado ativo enquanto uma coluna esta sendo redimensionada |

`appearance.density` seleciona apenas o preset de defaults. `appearance.spacing.*` e defaults globais também alimentam tokens `*-default`. Hosts podem redefinir livremente os tokens finais sem depender de seletores internos, por exemplo `--p-table-row-height`, `--p-table-header-height`, `--p-cell-padding`, `--p-actions-btn-size` e `--p-table-paginator-select-height`. Em virtualização sem `itemHeight` explícito, o runtime deriva a altura da densidade efetiva.

#### 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.
- Para intenções semânticas cobertas pelo catálogo oficial, use `surfacePresetRef`, por exemplo `{ "id": "warning", "catalogVersion": "0.2.0" }`. A versão `0.2.0` oferece `success`, `warning`, `danger` e `highlight` nos escopos de linha e célula.
- Fundo sólido determinístico sem `color` usa foreground acessível derivado no runtime; a cor derivada não é persistida no `TableConfig`.
- `color` explícito continua sendo intenção autorada e deve atingir contraste WCAG AA (`4.5:1`) contra o fundo sólido efetivo.
- O authoring bloqueia pares explícitos abaixo de AA. Para configuração legada ou manual que bypassou esse gate, o runtime substitui apenas o foreground renderizado por um fallback acessível e preserva o documento original para diagnóstico/correção governada.
- Hover e zebra não apagam uma superfície condicional. Seleção possui precedência explícita com seu próprio par `--p-table-row-selected-bg`/`--p-table-row-selected-fg`.
- Alpha, `var(...)`, `cssClass` externa, gradiente e shorthand não determinístico exigem preview contextual e não devem ser declarados acessíveis apenas por validação estrutural. O fundo contextual fica adiado no HTML inicial. Após o render, o runtime aplica fundo e foreground no mesmo frame e emite evidência DOM `derived-contextual` somente quando uma transparência ou variável CSS puder ser composta até uma base opaca e reduzida a uma única cor sólida. Gradientes, imagens e composições sem base opaca permanecem `unresolved-suppressed`, sem pintar o fundo inseguro.
- Em CSP estrito, estilos condicionais inline são desativados e o runtime não faz reparos via CSSOM. Apenas um `surfacePresetRef` válido é convertido na classe privada correspondente; `cssClass` arbitrária falha fechado. Os nomes dessas classes são detalhe interno e não fazem parte do contrato de authoring.
- A observação runtime publica `affordances.visualMaterialization.inlineStyle`, `governedClass` e `surfacePresetCatalog` (ID, versão, tema, modo, escopos e presets instalados), sem expor nonce ou a política CSP bruta. O backend usa essa evidência somente para restringir o preview: estilos inline exigem `inlineStyle=supported`; presets exigem instalação compatível comprovada. Capability ausente, `unknown`, versão/escopo/preset divergente ou modo de tema ainda não certificado falham fechado.
- `muted` não integra o catálogo acessível: opacidade aplicada à linha pode compor com descendentes e invalidar o contraste. O modo `high-contrast` é observado pelo runtime, mas permanece não aplicável pelo authoring até ter evidência visual certificada; o catálogo `0.2.0` está certificado para `light` e `dark`.
- Quando a cor comunicar estado ou classificação de negócio, materialize também uma pista visível independente de cor, como marcador lateral, ícone ou label.

### 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`. |
| `toolbar.title` | `string` | No | `undefined` | Active | Titulo renderizado na regiao de identidade da toolbar principal, antes de filtros e acoes. |
| `toolbar.subtitle` | `string` | No | `undefined` | Active | Texto auxiliar renderizado abaixo do titulo quando houver espaco. |
| `toolbar.icon` | `string` | No | `undefined` | Active | Icone semantico renderizado junto ao titulo da toolbar via `PraxisIconDirective`. |
| `toolbar.textAlign` | `'start' \| 'center' \| 'end'` | No | `'start'` | Active | Alinhamento textual do bloco de identidade da toolbar. |
| `toolbar.appearance` | `TableToolbarAppearanceConfig` | No | fallback M3 | Active | Chrome visual governado da toolbar; tokens viram `--p-table-toolbar-*` no runtime. |
| `toolbar.appearance.tokens.titleFg` | `string` | No | fallback M3 | Active | Cor do titulo na identidade da toolbar; use tokens semanticos do host para suportar tema claro/escuro. |
| `toolbar.appearance.tokens.subtitleFg` | `string` | No | fallback M3 | Active | Cor do subtitulo na identidade da toolbar. |
| `toolbar.appearance.tokens.iconFg` | `string` | No | fallback M3 | Active | Cor do icone da identidade; o fundo tonal e derivado dessa cor para manter contraste suave. |
| `toolbar.appearance.tokens.titleFontSize` | `string` | No | `14px` | Active | Tamanho tipografico do titulo da identidade. |
| `toolbar.appearance.tokens.subtitleFontSize` | `string` | No | `11.5px` | Active | Tamanho tipografico do subtitulo da identidade. |
| `toolbar.appearance.tokens.titleFontWeight` | `string` | No | `700` | Active | Peso tipografico do titulo da identidade. |
| `toolbar.appearance.tokens.identityGap` | `string` | No | `8px` | Active | Espaco entre icone e copy da identidade da toolbar. |
| `toolbar.appearance.tokens.identityFilterGap` | `string` | No | `8px` | Active | Respiro vertical entre identidade e filtros/controles quando a identidade ocupa linha propria. |
| `toolbar.appearance.tokens.identityMinHeight` | `string` | No | `30px` | Active | Altura minima do bloco de identidade da toolbar. |
| `toolbar.appearance.tokens.identityMarginBottom` | `string` | No | `2px` | Active | Espacamento inferior complementar da identidade da toolbar. |
| `toolbar.appearance.tokens.identityIconSize` | `string` | No | `28px` | Active | Tamanho do container do icone da identidade. |
| `toolbar.appearance.tokens.identityIconRadius` | `string` | No | `8px` | Active | Raio do container do icone da identidade. |
| `toolbar.columnsVisibility` | `object` | No | habilitado se a toolbar estiver ativa | Active | Controle rápido de visibilidade de colunas no toolbar (dropdown). |
| `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?, resourceIdentity? }`
for row selection changes initiated by the user and with `trigger: "data-reconcile"`
when a data update removes identities from the effective selection. Rehydrating the
same identities does not emit a new selection event.

Assistant turns can also receive the selected-row digest as context; textual
matching on row values must not decide primary intent.

| 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`. |
| `.praxis-header-sort-trigger` | internal header zone | zona dedicada de sort no header | Recebe `mat-sort-header`; reorder por drag continua implicito no header cell. |

### 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;
  };
};
```
