@praxisui/table 9.0.0-beta.4 → 9.0.0-beta.41

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-03-05"
+source_of_truth_last_verified: "2026-06-24"
 publish_source_of_truth: false
-last_updated: "2026-03-05"
+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,11 +333,26 @@ 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
 
 - Acoes globais de toolbar, row e bulk usam `effects[].kind = "global-action"` como envelope canonico de novo authoring.
@@ -341,6 +363,7 @@ Este arquivo foi adaptado para o padrao canonico atual sem remover conteudo tecn
 - 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`.
 
@@ -365,7 +388,7 @@ Este arquivo foi adaptado para o padrao canonico atual sem remover conteudo tecn
 | `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. |
@@ -413,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. |
@@ -928,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. |
@@ -944,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-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 |
@@ -981,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 |
@@ -1214,6 +1246,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