@praxisui/table 8.0.0-beta.99 → 9.0.0-beta.0

package/fesm2022/{praxisui-table-table-ai.adapter-C96CotWq.mjs → praxisui-table-table-ai.adapter-BvaMq2CS.mjs}

@@ -1,7 +1,7 @@
 import { firstValueFrom } from 'rxjs';
-import { BaseAiAdapter, createComponentAuthoringContext } from '@praxisui/ai';
+import { BaseAiAdapter, sanitizePraxisAssistantText, createComponentAuthoringContext } from '@praxisui/ai';
 import { PRAXIS_GLOBAL_ACTION_CATALOG, deepMerge } from '@praxisui/core';
-import { G as TABLE_COMPONENT_EDIT_PLAN_OPERATION_IDS, k as PRAXIS_TABLE_AUTHORING_MANIFEST, T as TABLE_AI_CAPABILITIES, W as coerceTableComponentEditPlans, Y as compileTableComponentEditPlans, I as TASK_PRESETS, a1 as getTableComponentEditPlanCapabilities, y as TABLE_COMPONENT_EDIT_PLAN_EXPECTED_PATHS, w as TABLE_COMPONENT_EDIT_PLAN_ALLOWED_CHANGE_KINDS, z as TABLE_COMPONENT_EDIT_PLAN_JSON_SCHEMA, H as TABLE_COMPONENT_EDIT_PLAN_VERSION, x as TABLE_COMPONENT_EDIT_PLAN_BATCH_KIND, E as TABLE_COMPONENT_EDIT_PLAN_KIND } from './praxisui-table-praxisui-table-rz7xSDwL.mjs';
+import { G as TABLE_COMPONENT_EDIT_PLAN_OPERATION_IDS, k as PRAXIS_TABLE_AUTHORING_MANIFEST, T as TABLE_AI_CAPABILITIES, W as coerceTableComponentEditPlans, Y as compileTableComponentEditPlans, I as TASK_PRESETS, a1 as getTableComponentEditPlanCapabilities, y as TABLE_COMPONENT_EDIT_PLAN_EXPECTED_PATHS, w as TABLE_COMPONENT_EDIT_PLAN_ALLOWED_CHANGE_KINDS, z as TABLE_COMPONENT_EDIT_PLAN_JSON_SCHEMA, H as TABLE_COMPONENT_EDIT_PLAN_VERSION, x as TABLE_COMPONENT_EDIT_PLAN_BATCH_KIND, E as TABLE_COMPONENT_EDIT_PLAN_KIND } from './praxisui-table-praxisui-table-CunEk0vb.mjs';
 
 const TABLE_COMPONENT_CONTEXT_PACK = {
     version: 'v1',
@@ -1991,6 +1991,46 @@ class TableAiAdapter extends BaseAiAdapter {
             isLoading: false // TODO: expose real loading flag
         };
     }
+    getFieldValueSamples(field, maxValues = 12) {
+        const normalizedField = typeof field === 'string' ? field.trim() : '';
+        if (!normalizedField || this.isSensitiveFieldForAiAssistantSamples(normalizedField))
+            return [];
+        const column = (this.getCurrentConfig().columns || [])
+            .find((candidate) => candidate?.field === normalizedField);
+        if (!column)
+            return [];
+        const values = new Set();
+        const rows = Array.isArray(this.table.dataSource?.data) ? this.table.dataSource.data : [];
+        for (const row of rows) {
+            if (!row || typeof row !== 'object')
+                continue;
+            const displayValue = this.table.getCellValue(row, column);
+            const text = this.safeAiAssistantValueText(displayValue);
+            if (text)
+                values.add(text);
+            if (values.size >= maxValues)
+                break;
+        }
+        return [...values];
+    }
+    safeAiAssistantValueText(value) {
+        if (value === null || value === undefined)
+            return '';
+        if (value instanceof Date)
+            return sanitizePraxisAssistantText(value.toISOString(), 120);
+        if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+            return sanitizePraxisAssistantText(value, 120);
+        }
+        try {
+            return sanitizePraxisAssistantText(JSON.stringify(value), 120);
+        }
+        catch {
+            return sanitizePraxisAssistantText(String(value), 120);
+        }
+    }
+    isSensitiveFieldForAiAssistantSamples(field) {
+        return /(?:password|senha|token|secret|api[_-]?key|authorization|bearer|blob|bytes|base64|file|payload)/i.test(field);
+    }
     getAuthoringContext() {
         const filterFieldCatalog = this.buildFilterFieldCatalog();
         const selectedRowsContext = this.getSelectedRowsAuthoringContext();

package/fesm2022/praxisui-table.mjs

@@ -1 +1 @@
-export { A as AnalyticsTableConfigAdapterService, a as AnalyticsTableContractService, b as AnalyticsTableStatsApiService, B as BOOLEAN_PRESETS, c as BehaviorConfigEditorComponent, C as CURRENCY_PRESETS, d as ColumnsConfigEditorComponent, D as DATE_PRESETS, e as DataFormatterComponent, f as DataFormattingService, F as FORMULA_TEMPLATES, g as FilterConfigService, h as FilterSettingsComponent, i as FormulaGeneratorService, J as JsonConfigEditorComponent, M as MessagesLocalizationEditorComponent, N as NUMBER_PRESETS, P as PERCENTAGE_PRESETS, j as PRAXIS_FILTER_COMPONENT_METADATA, k as PRAXIS_TABLE_AUTHORING_MANIFEST, l as PRAXIS_TABLE_COMPONENT_METADATA, m as PRAXIS_TABLE_TOOLBAR_DEFAULT_APPEARANCE, n as PRAXIS_TABLE_TOOLBAR_TOKEN_PRESETS, o as PraxisFilter, p as PraxisFilterWidgetConfigEditor, q as PraxisTable, r as PraxisTableConfigEditor, s as PraxisTableInlineAuthoringEditorComponent, t as PraxisTableToolbar, u as PraxisTableWidgetConfigEditor, S as STRING_PRESETS, T as TABLE_AI_CAPABILITIES, v as TABLE_COMPONENT_AI_CAPABILITIES, w as TABLE_COMPONENT_EDIT_PLAN_ALLOWED_CHANGE_KINDS, x as TABLE_COMPONENT_EDIT_PLAN_BATCH_KIND, y as TABLE_COMPONENT_EDIT_PLAN_EXPECTED_PATHS, z as TABLE_COMPONENT_EDIT_PLAN_JSON_SCHEMA, E as TABLE_COMPONENT_EDIT_PLAN_KIND, H as TABLE_COMPONENT_EDIT_PLAN_VERSION, I as TASK_PRESETS, K as TableDefaultsProvider, L as TableRulesEditorComponent, O as ToolbarActionsEditorComponent, V as ValueMappingEditorComponent, Q as VisualFormulaBuilderComponent, R as buildTableApplyPlan, U as coerceTableComponentEditPlan, W as coerceTableComponentEditPlans, X as compileTableComponentEditPlan, Y as compileTableComponentEditPlans, Z as createTableAuthoringDocument, _ as getActionId, $ as getEnum, a0 as getTableCapabilities, a1 as getTableComponentEditPlanCapabilities, a2 as isTableRendererSupportedByRichContentP0, a3 as mapTableRendererToRichContentP0, a4 as normalizeTableAuthoringDocument, a5 as parseLegacyOrTableDocument, a6 as providePraxisFilterMetadata, a7 as providePraxisTableMetadata, a8 as providePraxisTableToolbarAppearance, a9 as serializeTableAuthoringDocument, aa as toCanonicalTableConfig, ab as validateTableAuthoringDocument } from './praxisui-table-praxisui-table-rz7xSDwL.mjs';
+export { A as AnalyticsTableConfigAdapterService, a as AnalyticsTableContractService, b as AnalyticsTableStatsApiService, B as BOOLEAN_PRESETS, c as BehaviorConfigEditorComponent, C as CURRENCY_PRESETS, d as ColumnsConfigEditorComponent, D as DATE_PRESETS, e as DataFormatterComponent, f as DataFormattingService, F as FORMULA_TEMPLATES, g as FilterConfigService, h as FilterSettingsComponent, i as FormulaGeneratorService, J as JsonConfigEditorComponent, M as MessagesLocalizationEditorComponent, N as NUMBER_PRESETS, P as PERCENTAGE_PRESETS, j as PRAXIS_FILTER_COMPONENT_METADATA, k as PRAXIS_TABLE_AUTHORING_MANIFEST, l as PRAXIS_TABLE_COMPONENT_METADATA, m as PRAXIS_TABLE_TOOLBAR_DEFAULT_APPEARANCE, n as PRAXIS_TABLE_TOOLBAR_TOKEN_PRESETS, o as PraxisFilter, p as PraxisFilterWidgetConfigEditor, q as PraxisTable, r as PraxisTableConfigEditor, s as PraxisTableInlineAuthoringEditorComponent, t as PraxisTableToolbar, u as PraxisTableWidgetConfigEditor, S as STRING_PRESETS, T as TABLE_AI_CAPABILITIES, v as TABLE_COMPONENT_AI_CAPABILITIES, w as TABLE_COMPONENT_EDIT_PLAN_ALLOWED_CHANGE_KINDS, x as TABLE_COMPONENT_EDIT_PLAN_BATCH_KIND, y as TABLE_COMPONENT_EDIT_PLAN_EXPECTED_PATHS, z as TABLE_COMPONENT_EDIT_PLAN_JSON_SCHEMA, E as TABLE_COMPONENT_EDIT_PLAN_KIND, H as TABLE_COMPONENT_EDIT_PLAN_VERSION, I as TASK_PRESETS, K as TableDefaultsProvider, L as TableRulesEditorComponent, O as ToolbarActionsEditorComponent, V as ValueMappingEditorComponent, Q as VisualFormulaBuilderComponent, R as buildTableApplyPlan, U as coerceTableComponentEditPlan, W as coerceTableComponentEditPlans, X as compileTableComponentEditPlan, Y as compileTableComponentEditPlans, Z as createTableAuthoringDocument, _ as getActionId, $ as getEnum, a0 as getTableCapabilities, a1 as getTableComponentEditPlanCapabilities, a2 as isTableRendererSupportedByRichContentP0, a3 as mapTableRendererToRichContentP0, a4 as normalizeTableAuthoringDocument, a5 as parseLegacyOrTableDocument, a6 as providePraxisFilterMetadata, a7 as providePraxisTableMetadata, a8 as providePraxisTableToolbarAppearance, a9 as serializeTableAuthoringDocument, aa as toCanonicalTableConfig, ab as validateTableAuthoringDocument } from './praxisui-table-praxisui-table-CunEk0vb.mjs';

package/package.json

@@ -1,23 +1,23 @@
 {
   "name": "@praxisui/table",
-  "version": "8.0.0-beta.99",
+  "version": "9.0.0-beta.0",
   "description": "Advanced data table for Angular (Praxis UI) with editing, filtering, sorting, virtualization, and settings panel integration.",
   "peerDependencies": {
     "@angular/common": "^21.0.0",
     "@angular/core": "^21.0.0",
-    "@praxisui/ai": "^8.0.0-beta.99",
-    "@praxisui/core": "^8.0.0-beta.99",
-    "@praxisui/dynamic-fields": "^8.0.0-beta.99",
-    "@praxisui/dynamic-form": "^8.0.0-beta.99",
-    "@praxisui/metadata-editor": "^8.0.0-beta.99",
-    "@praxisui/rich-content": "^8.0.0-beta.99",
-    "@praxisui/settings-panel": "^8.0.0-beta.99",
-    "@praxisui/table-rule-builder": "^8.0.0-beta.99",
+    "@praxisui/ai": "^9.0.0-beta.0",
+    "@praxisui/core": "^9.0.0-beta.0",
+    "@praxisui/dynamic-fields": "^9.0.0-beta.0",
+    "@praxisui/dynamic-form": "^9.0.0-beta.0",
+    "@praxisui/metadata-editor": "^9.0.0-beta.0",
+    "@praxisui/rich-content": "^9.0.0-beta.0",
+    "@praxisui/settings-panel": "^9.0.0-beta.0",
+    "@praxisui/table-rule-builder": "^9.0.0-beta.0",
     "@angular/cdk": "^21.0.0",
     "@angular/forms": "^21.0.0",
     "@angular/material": "^21.0.0",
     "@angular/router": "^21.0.0",
-    "@praxisui/dialog": "^8.0.0-beta.99",
+    "@praxisui/dialog": "^9.0.0-beta.0",
     "rxjs": "~7.8.0"
   },
   "dependencies": {

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

@@ -92,6 +92,16 @@ 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.
 
+## 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`.
@@ -331,7 +341,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.
-- 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` e `statusFg`.
+- 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
@@ -349,6 +359,7 @@ Este arquivo foi adaptado para o padrao canonico atual sem remover conteudo tecn
 | `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. |
@@ -424,7 +435,7 @@ degraded filter.
 
 | 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. |
+| `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`. |
@@ -549,81 +560,79 @@ Referencia canonica da API JSON do `praxis-table`.
 - **Deprecated**
 
 ### Overview
-`praxis-table` nao e apenas um grid ou uma tabela convencional. Ele funciona
-como um motor de renderizacao dinamico orientado a contrato (`TableConfig`).
-Em vez de criar um template para cada tela de listagem, voce entrega a planta
-(JSON) e o runtime monta a obra em tempo de execucao.
-
-Em arquiteturas tradicionais, cada variacao de colunas, acoes e filtros costuma
-virar nova camada de HTML + estado + condicionais. Aqui, a estrategia e inverter
-o custo: a mudanca fica na configuracao. Quando o requisito muda, o contrato muda
-e a interface se adapta sem reescrever o componente.
-
-Em linguagem simples: o JSON e a planta; a tabela e a obra. Troque a planta e o
-resultado muda sem retrabalho de template.
+`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:
 
-- UI declarativa / schema-driven: um contrato JSON define estrutura, dados e UX.
-- Self-describing APIs: backend pode publicar OpenAPI + `x-ui` para derivar UI.
-- Separacao de dados e apresentacao: `columns` descreve dado; `appearance` e
-  `behavior` definem como apresentar/interagir.
-- Motor de regras condicional: JSON Logic como contrato canonico para estilos, visibilidade e renderizacao sem
-  ifs espalhados no template.
-- Pipeline de dados: fluxo remoto/local com estrategias de pagina, ordenacao e filtro.
-
-#### Porque este componente e diferente
-`praxis-table` nao e apenas um grid. E um runtime configuravel que interpreta um
-contrato JSON extenso e coordena varias superficies ao mesmo tempo. Em tabelas
-convencionais, cada mudanca de coluna, filtro, acao ou visual pede codigo e
-template; aqui, essas mudancas entram no JSON e o runtime responde na hora:
-
-- Configuracao declarativa profunda (TableConfig) que governa UI, dados e regras.
-- Dois modos de dados (remoto/local) com pipelines diferentes e impactos no UX.
-- Editor e runtime convivendo (settings panel, reconciliacao e marcadores).
-- JSON Logic para regras de estilos, renderizacao e comportamento condicional.
-- Persistencia e identidade atraves de `tableId` + `componentInstanceId`.
-
-O resultado e um componente "plataforma": cada bloco do contrato vira um modulo
-do runtime, e as interacoes entre esses modulos tornam o comportamento realmente
-disruptivo.
-
-#### Pitch de 30 segundos (valor)
-Uma tabela que vira plataforma. `praxis-table` transforma configuracao em
-experiencia: colunas, acoes, filtros, mensagens e regras vivem no mesmo contrato
-JSON, pronto para dados remotos ou locais, sem retrabalho de template.
-
-- **Entrega rapida**: ajuste comportamento e visual por JSON.
-- **Padrao de UX**: regras, acoes e mensagens consistentes entre telas.
-- **Escalavel**: JSON Logic e actions permitem crescer a complexidade sem fork do runtime.
-
-#### O fim do boilerplate
-Uma tabela que vira plataforma. Em vez de programar features de grade do zero,
-voce ativa capacidades nativas via contrato:
-
-- **Zero-code iteration**: adicionar botoes, trocar densidade, ajustar colunas,
-  filtros e dialogs apenas alterando JSON.
-- **Logica desacoplada (rules engine)**: destaque de linha, visibilidade de acao
-  e variacao de renderer ficam em expressoes condicionais canonicas, nao em `*ngIf` espalhado.
-- **Ecossistema embutido**: paginacao remota, virtual scroll, reorder de colunas,
-  exportacao e `praxis-filter` avancado como capacidades prontas.
-- **Eventos estruturados**: `rowAction`, `bulkAction`, `toolbarAction`, `exportAction`,
-  `columnReorder` e eventos de delete padronizam a integracao com o host.
-- **Governanca de estado**: `tableId` + `componentInstanceId` organizam
-  persistencia, reconciliacao e isolamento de instancia.
-
-#### Receitas de impacto para o overview (live-first)
-Para o overview no estilo Angular Material (`demo vivo + view code` na mesma
-card), a melhor estrategia e mostrar poucos cenarios com alta densidade de
-valor. Sugestao de ordem para a primeira dobra:
+- 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 negocio e confirmacao.
+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.
 
-Snippets curtos (prontos para cards de overview):
-
 **Receita 1 - Dashboard Financeiro**
 ```json
 {
@@ -669,7 +678,7 @@ Snippets curtos (prontos para cards de overview):
 }
 ```
 
-**Receita 3 - Backoffice Seguro (acoes em lote)**
+**Receita 3 - Backoffice Seguro (ações em lote)**
 ```json
 {
   "actions": {
@@ -710,10 +719,10 @@ Snippets curtos (prontos para cards de overview):
 
 ### Internal route global action
 
-Configuracoes novas devem persistir a integracao em `effects[].globalAction`. O runtime e os validadores tambem
+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 semantica cruzada.
+e limpa payloads ao trocar de global action para evitar semântica cruzada.
 
 ```json
 {
@@ -769,106 +778,104 @@ e limpa payloads ao trocar de global action para evitar semantica cruzada.
           { "!==": [{ "var": "status" }, "RESOLVIDO"] }
         ]
       },
-      "tooltip": { "text": "SLA violado: acao imediata necessaria", "position": "top" },
+      "tooltip": { "text": "SLA violado: ação imediata necessária", "position": "top" },
       "animation": { "preset": "warning-attention", "repeat": 3 }
     }
   ]
 }
 ```
 
-Para manter o overview leve, publique somente essas 4 receitas na landing da
-doc. Os demais casos (filtros avancados, logs massivos, overrides CRUD, etc.)
-ficam na aba de exemplos completos.
+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 aplicacoes complexas, o esforco de engenharia
-raramente esta nos fluxos principais. O custo aparece na cauda longa dos
-requisitos de UI: variacoes de regras condicionais, formatacoes especificas,
-tooltips baseados em estado e permissoes de acao que mudam por linha ou usuario.
+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
-manutencao. Em vez de espalhar condicionais `*ngIf` no codigo, o componente
-move o poder de decisao para uma API de regras em JSON Logic e renderizadores
-condicionais/compostos. Quem define o contrato ganha controle fino da
-experiencia, com mais autonomia para produto e menos acoplamento no frontend.
+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 pratico:
+Impacto prático:
 
-- Menos ramificacao de codigo no front.
-- Mais autonomia para evoluir UX por configuracao.
-- Menor risco de regressao ao escalar regras condicionais.
+- 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 superficies
-O contrato governa 6 superficies principais:
+#### Mapa de contrato e superfícies
+O contrato governa 6 áreas principais:
 
-| Superficie | O que governa no JSON/API | Impacto no runtime |
+| Área | O que governa | Impacto na experiência |
 | --- | --- | --- |
-| Declarativa (UI e UX) | `columns`, `appearance`, `behavior`, `messages`, `localization` | Define estrutura visual, densidade, textos, ordenacao e comportamento base da tabela. |
-| Dados e operacao | `resourcePath`, `data[]`, `behavior.pagination.*`, `behavior.filtering.*`, `behavior.localDataMode.*` | Resolve modo (`remote/local/empty`), estrategia de pagina/filtro/sort e pipeline de dados. |
-| Regras condicionais | `rules`, `conditionalStyles`, `rowConditionalStyles`, `conditionalRenderers` | Avalia JSON Logic por linha/celula para estilo, visibilidade e renderer dinamico. |
-| Acoes e jornada | `actions`, `toolbar`, `dialogs`, `export` | Materializa acoes de linha/lote/toolbar e fluxos de confirmacao/export. |
-| Integracao externa | `tableId`, `componentInstanceId`, overrides CRUD, marcadores de painel | Conecta persistencia, reconciliacao e extensoes de host sem quebrar o contrato base. |
-| Eventos de saida | `rowAction`, `bulkAction`, `toolbarAction`, `exportAction`, `columnReorder`, `schemaStatusChange` | Entrega intencoes do usuario como eventos padronizados para o app hospedeiro reagir. |
+| 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 superficie e explicita onde o runtime realmente consome
-(Active/Partial/Declared-only/Schema-only).
+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, apresentacao e interacao, operando em
-dois eixos principais: motor interno da tabela e integracoes externas.
+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 execucao:
+Fluxo simplificado de execução:
 
-1. **Interpretacao do contrato**: le `TableConfig` e resolve o modo de operacao
-   (`remote` via API, `local` via array, ou `empty`).
-2. **Montagem da superficie**: renderiza colunas, toolbar, filtros e
-   comportamentos visuais definidos em `appearance` e `behavior`.
+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: integra `crudService` + estrategia de pagina/sort/filtro;
-   - local: aplica `computeLocalViewPipeline()` + filtros avancados;
-   - regras: executa JSON Logic para estilos condicionais, visibilidade de acoes e
-     renderizadores dinamicos por linha.
-4. **Ciclo de eventos**: emite acoes estruturadas (`rowAction`, `bulkAction`,
-   `toolbarAction`, etc.) para que a aplicacao hospedeira reaja as intencoes do usuario.
+   - 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.
 
-#### Integracao com ecossistema Praxis (frontend e backend)
-`praxis-table` compoe o ecossistema Praxis de ponta a ponta. O mapa de
-integracao cobre frontend, contratos e backend.
+#### 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 experiencia | Como se conecta |
+| Componente | Papel na experiência | Como se conecta |
 | --- | --- | --- |
-| `praxis-table-toolbar` | Barra superior/inferior com acoes, bulk e export | `toolbar`, `actions`, `export`, `behavior.filtering.*` |
-| `praxis-filter` | Filtro avancado acoplado a toolbar | `behavior.filtering.advancedFilters.*`, `behavior.filtering.debounceTime`, `resourcePath` |
-| `praxis-empty-state-card` | Estado inicial quando nao ha conexao remota | exibido quando nao ha `resourcePath` valido |
-| `PraxisAiAssistantShellComponent` | Copiloto semântico opcional nos slots de toolbar | habilitado pelo runtime com turn orchestration e contexto seguro; ao minimizar, a sessao fica no registry com `presence: "origin-anchor"` e o affordance volta ao gatilho da tabela (nao exposto no JSON) |
-| Angular Material + CDK | Base de tabela, menus, selecao e virtual scroll | `behavior.pagination.*`, `behavior.selection.*`, `behavior.virtualization.*`, `appearance.spacing.*` |
+| `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 experiencia | Como se conecta |
+| 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 validacoes a partir do contrato |
+| `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 edicao (quando `enableCustomization` esta ativo), a tabela exibe o painel
-de configuracao para ajustar colunas, behavior, appearance e regras sem editar
-codigo. Esse painel usa editores internos (`praxis-table-config-editor`,
-`behavior-config-editor`, `columns-config-editor`, `toolbar-actions-editor`,
-`messages-localization-editor`, etc.) para compor o JSON com consistencia e evitar
-divergencia entre UI e contrato.
+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 integracao (pre-flight)
-Antes de plugar a tabela em um host, valide estes pontos:
+#### Checklist de integração (pre-flight)
+Antes de plugar a tabela em uma aplicação, valide estes pontos:
 
-- `tableId` esta definido e estavel (persiste e evita colisao de storage).
-- Modo de dados decidido: `resourcePath` (remoto) ou `data[]` + flag local.
-- `columns[]` descreve o dataset real e define renderers coerentes.
-- Acoes e toolbar estao alinhadas com o roteamento `bulkAction` vs `toolbarAction`.
-- Regras condicionais: JSON Logic é o contrato canônico.
-- UX e mensagens: configure `appearance`, `messages` e `localization` para evitar
-  inconsistencias entre defaults e o comportamento esperado.
+- 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
 
@@ -1160,7 +1167,24 @@ A superficie usa `horizontalScroll` com classes:
 | `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. |