@praxisui/table 9.0.0-beta.9 → 9.0.0-rc.1

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

@@ -37,9 +37,9 @@ source_of_truth:
   - "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-16"
+source_of_truth_last_verified: "2026-06-24"
 publish_source_of_truth: false
-last_updated: "2026-06-16"
+last_updated: "2026-06-24"
 toc: true
 sidebar: true
 tags:
@@ -92,6 +92,13 @@ Este documento e a referencia canonica da API JSON de praxis-table.
 - 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.
@@ -326,13 +333,25 @@ Este arquivo foi adaptado para o padrao canonico atual sem remover conteudo tecn
 | `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 variante, densidade, forma, divisores e tokens públicos da toolbar sem alterar a semântica das ações. |
+| `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
 
@@ -344,6 +363,7 @@ Renderer defaults:
 - 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`.
 
@@ -368,7 +388,7 @@ Renderer defaults:
 | `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. |
+| `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. |
@@ -416,13 +436,14 @@ degraded filter.
 | `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. |
+| `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. |
@@ -931,6 +952,7 @@ row selection through table affordances.
 | `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. |
@@ -947,28 +969,31 @@ row selection through table affordances.
 | `--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-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-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 |
@@ -984,6 +1009,10 @@ row selection through table affordances.
 | `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 |
@@ -1000,7 +1029,16 @@ A superficie usa `horizontalScroll` com classes:
 #### 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`.
+- 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
 
@@ -1193,8 +1231,10 @@ A superficie usa `horizontalScroll` com classes:
 
 ## Appendix: Events summary
 
-`selectionChange` emits `{ trigger, row?, selectedRows, selectedCount, tableId? }`
-for row selection changes initiated by the user.
+`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.
@@ -1217,6 +1257,7 @@ matching on row values must not decide primary intent.
 | `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