@praxisui/table 1.0.0-beta.8 → 3.0.0-beta.0

package/README.md

@@ -1,11 +1,99 @@
+---
+title: "Table"
+slug: "table-overview"
+description: "Visao geral do @praxisui/table com TableConfig unificada, filtros, renderers, performance e integracao enterprise."
+doc_type: "reference"
+document_kind: "component-overview"
+component: "table"
+category: "components"
+audience:
+  - "frontend"
+  - "host"
+  - "architect"
+level: "intermediate"
+status: "active"
+owner: "praxis-ui"
+tags:
+  - "table"
+  - "tableconfig"
+  - "filters"
+  - "renderers"
+  - "enterprise"
+order: 25
+icon: "table_chart"
+toc: true
+sidebar: true
+search_boost: 1.0
+reading_time: 14
+estimated_setup_time: 25
+version: "1.0"
+related_docs:
+  - "dynamic-filter-architecture-overview"
+  - "dynamic-filter-host-integration-guide"
+  - "dynamic-filter-payload-contract"
+  - "dynamic-filter-range-filters-guide"
+  - "dynamic-filter-editor-settings-guide"
+  - "dynamic-inline-filter-catalog"
+  - "dynamic-filter-troubleshooting-guide"
+  - "dynamic-filter-backend-contract-cheatsheet"
+  - "adr-dynamic-filter-cross-lib-coupling-2026-03"
+  - "host-integration-guide"
+  - "consumer-integration-quickstart"
+keywords:
+  - "TableConfig"
+  - "filters"
+  - "renderers"
+  - "performance"
+  - "dynamic filter"
+last_updated: "2026-03-07"
+---
+
 # @praxisui/table
 
+## Documentation
+
+- Documentação oficial: https://praxisui.dev
+- Aplicação de referência: https://github.com/codexrodrigues/praxis-ui-quickstart
+- Indicado para: data grids enterprise com filtros, edicao, virtualizacao, renderers e governanca de configuracao
+
+## When to use
+
+- Exibir grandes volumes de dados com filtros e operacoes ricas
+- Governar configuracao de colunas, toolbar e comportamento em runtime
+- Integrar tabelas a fluxos CRUD, IA e editores visuais do ecossistema Praxis UI
+
 > Componente de tabela empresarial avançado com arquitetura unificada
 
+## Customization Mode Contract
+
+- `enableCustomization` is the canonical public input for runtime customization mode.
+- The default is `false`; hosts opt in when they want settings, authoring affordances and schema-drift UX.
+- Customization mode does not change the table data mode. It only gates configuration/editorial surfaces.
+
+## Migration Note
+
+- This release treats `enableCustomization=false` as the canonical default.
+- Hosts that relied on the previous implicit authoring behavior must now declare `[enableCustomization]="true"` explicitly.
+- This is an intentional breaking change for enterprise governance: authoring is opt-in, not ambient.
+
 ## 🌟 Visão Geral
 
 A biblioteca `@praxisui/table` fornece um componente de tabela robusto e altamente configurável para aplicações Angular empresariais. Com a nova arquitetura unificada, oferece uma experiência de desenvolvimento simplificada mantendo todos os recursos avançados.
 
+## 🎨 Tema M3 (tokens mínimos)
+
+Para garantir que a tabela, filtros e editores reflitam o tema do app host:
+
+- Superfícies: `--md-sys-color-surface`, `--md-sys-color-surface-variant`, `--md-sys-color-surface-container-*`
+- Texto/contorno: `--md-sys-color-on-surface`, `--md-sys-color-on-surface-variant`, `--md-sys-color-on-primary`, `--md-sys-color-outline`, `--md-sys-color-outline-variant`
+- Semânticos: `--md-sys-color-primary`, `--md-sys-color-secondary`, `--md-sys-color-tertiary`, `--md-sys-color-error`
+- Containers: `--md-sys-color-primary-container`, `--md-sys-color-secondary-container`, `--md-sys-color-tertiary-container`, `--md-sys-color-error-container`
+- Overlay: `--md-sys-color-scrim`
+- Elevação: `--md-sys-elevation-level1`–`--md-sys-elevation-level3`
+
+Observação: tokens `--md-sys-*` e `--mdc-theme-*` continuam aceitos quando presentes.
+Nota: a classe de tema é decisão do host (`.dark-theme` ou `.theme-dark`/`.theme-light`); mantenha tokens e componentes no mesmo escopo.
+
 ## ✨ Características Principais
 
 ### 🏗️ Arquitetura Unificada
@@ -27,6 +115,15 @@ A biblioteca `@praxisui/table` fornece um componente de tabela robusto e altamen
 - **Acessibilidade**: WCAG 2.1 AA compliant
 - **Verificação de Schema**: ETag/If-None-Match com notificações (somente em customização)
 
+### 📄 Contrato Inline do Filtro
+
+- Referencia canonica: `projects/praxis-dynamic-fields/docs/dynamic-fields-inline-components-guide.md` (slug publicado: `dynamic-fields-inline-components-guide`)
+- No contexto da tabela, use este contrato para definir `controlType` inline e politica de compatibilidade (canonica vs legado).
+
+### 🧭 Decisoes de Arquitetura (ADR)
+
+- Bundle/adapters: `projects/praxis-table/docs/adr/2026-03-filter-drawer-adapter-light-entrypoint.md`
+
 ### 🎨 Editores Visuais
 
 - **Behavior Editor**: Configuração de comportamentos
@@ -34,12 +131,211 @@ A biblioteca `@praxisui/table` fornece um componente de tabela robusto e altamen
 - **Toolbar Editor**: Personalização de ações
 - **Messages Editor**: Textos e localização
 
+Nota (Regras)
+- A antiga aba visual genérica foi removida deste pacote. O editor especializado de regras da Tabela já está disponível no painel de configuração.
+
+### 🧩 Editor de Regras (column-first)
+
+O novo editor é "column-first" e usa uma tipagem compartilhada com o Editor de Colunas. Principais pontos:
+
+- Escopo: aplique regras na linha inteira (rowConditionalStyles) ou em uma coluna específica (columns[].conditionalStyles).
+- Operadores por tipo: o conjunto de operadores é filtrado por tipo (string/number/date/boolean/enum).
+- Editores de valor dinâmicos: inputs numéricos, listas (CSV/múltipla seleção), datepickers.
+- Grupos lógicos: construa condições com AND/OR/NOT e reordene via arrastar-e-soltar (CDK DragDrop).
+- Preview: execute “Testar” para ver quantas linhas seriam afetadas pelas regras ativas.
+- Import/Export: exporta JSON sem o campo `enabled`; importa com validação de DSL e sanitização de estilos (allowlist).
+
+Exemplos de DSL:
+
+```text
+contains(status, 'Ativo')
+not (status in ['A', 'I'])
+(price >= 10 and price <= 20)
+(createdAt >= '2024-10-01' and createdAt <= '2024-10-31')
+(name == null or name == '')
+active == true
+```
+
+Notas sobre enum/CSV:
+- Para campos enumerados, as opções são inferidas de `valueMapping` da coluna ou de `fields?.options`.
+- Para `in/not in` em números/strings, use CSV (ex.: `10, 20, 30` ou `Alice, Bob`).
+
+#### Extensões de DSL (runtime nativo + custom)
+
+O runtime da tabela já inclui helpers de JSON/tempo/listas/texto sem configuração extra:
+
+- JSON: `jsonGet`, `hasJsonKey`, `jsonPathMatches`, `jsonEq`, `jsonIn`, `jsonType`
+- Texto/valor: `isBlank`, `eqIgnoreCase`, `coalesce`
+- Faixas: `between`, `dateBetween`
+- Coleções: `containsAny`, `containsAll`, `len`, `lenEq`, `lenGt`, `lenLt`, `lenAtLeast`
+- Tempo: `today`, `now`, `dateAdd`, `dateFormat`, `isToday`, `inLast`, `isPast`, `isPastOrNow`, `isFuture`, `isFutureOrNow`, `weekdayIn`
+
+Exemplos de DSL (canônica):
+- `jsonEq(payload, '$.user.name', 'Alice')`
+- `jsonIn(customer, '$.id', [10, 20])`
+- `eqIgnoreCase(status, 'ATIVO')`
+- `between(amount, 10, 20)`
+- `dateBetween(createdAt, '2025-01-01', '2025-12-31')`
+- `containsAll(tags, ['vip', 'gold'])`
+
+Observação de gramática:
+- comparações diretas sobre retorno de função (`fn(...) == 'x'`) não são suportadas pela gramática atual; prefira funções predicativas (booleanas) na `condition`.
+
+Guia completo: `projects/praxis-table/docs/DSL-Extensions-Guide.md`
+
+#### 🎨 Efeitos (Conteúdo C)
+
+O bloco de Efeitos permite aplicar estilo e visuais quando a condição é verdadeira:
+
+- Toolbar de texto com ícones (negrito, itálico, sublinhado) e presets rápidos (tachado, maiúsculas/minúsculas/capitalizar, tamanho +/- e reset).
+- Presets de feedback com ícones (sucesso, aviso, erro, info) — mantêm o rótulo via tooltip e `aria-label`.
+- “Posição do valor” como grupo de alternância (antes / entre-1 / entre-2 / depois / oculto).
+- “Ordem dos visuais” com seletor compacto (3 mais comuns) e menu para opções extras.
+- Layout do compose: espaçamento, alinhamento, quebra de linha e reticências.
+
+Dicas
+- Use “Resetar texto” para reverter efeitos de texto sem perder cor de fundo/borda.
+- Para acessibilidade, os grupos possuem `role="toolbar"`, tooltips e navegação por teclado consistente.
+
+Como reverter efeitos
+- “Reset Text” remove apenas propriedades de tipografia e transformação de texto.
+- “Limpar efeitos” apaga classe e estilo livres do bloco rápido.
+
+Observação: capturas de tela “antes/depois” podem ser adicionadas no PR conforme necessário.
+
+#### Relacionais (lookup)
+
+Campos relacionais (FK/objetos) podem ser editados no Rules Editor com busca assíncrona (typeahead) e seleção single/multiple.
+
+Boas práticas
+- Informe `resourcePath` (ou `endpoint`) no `FieldDefinition` para habilitar o lookup via `GenericCrudService` do host.
+- Defina `valueField` (chave estável, tipicamente `id`) e `displayField` (label amigável, como `name`).
+
+## 🔎 Filtro: Atalhos para Período (DateRange)
+
+Habilite atalhos de período no filtro dinâmico sem alterar o contrato do `praxis-filter` — apenas via metadata do campo:
+
+```ts
+// Em FilterConfig (ou na metadata de campos do filtro)
+{
+  name: 'period',
+  label: 'Período',
+  controlType: 'dateRange',
+  showShortcuts: true,
+  shortcuts: ['thisMonth','lastMonth','thisYear'],
+  // Opcional:
+  // i18nShortcuts: { thisMonth: 'Este mês', lastMonth: 'Mês passado' },
+  // applyOnShortcutClick: true
+}
+```
+- Para múltipla seleção, use `multiple: true` no `FieldDefinition` quando aplicável.
+- No runtime da tabela não é necessário registrar funções JSON/data manualmente; os helpers já são embutidos.
+- APIs com busca: suporte a um parâmetro livre de texto (por ex. `search`) facilita a experiência do autocomplete.
+
+Exemplo de FieldDefinition (lookup)
+```ts
+import type { FieldDefinition } from '@praxisui/core';
+
+const fields: FieldDefinition[] = [
+  {
+    name: 'customer',
+    type: 'object',
+    // Habilita o lookup via GenericCrudService
+    resourcePath: 'customers',
+    // Mapeia o id/label que virão do backend
+    valueField: 'id',
+    displayField: 'name',
+    // Se quiser multiseleção em todo o app
+    // multiple: true,
+  },
+];
+```
+
+Operadores e DSL gerada (relacional)
+- `id ==` → `jsonEq(customer, '$.id', 10)`
+- `id in` → `jsonIn(customer, '$.id', [10, 20])`
+- `has property` → `hasJsonKey(customer, '$.meta.etag')`
+- Condições por caminho (join simples): use `key ==` (JSON Path + valor)
+
+UI (no editor)
+- `id ==` (single): autocomplete + chip “label [id]” com ação “Limpar”.
+- `id in` (multi): autocomplete + chips removíveis por item.
+- `has property`: input do caminho (ex.: `$.meta.etag`).
+
+Formato esperado do payload (relacional)
+
+Para que o editor/preview e o runtime avaliem corretamente as regras relacionais, o valor do campo deve ser um objeto (ou compatível com JSON) contendo ao menos o identificador e, opcionalmente, propriedades exibidas:
+
+```ts
+// Exemplo de linha (row) com campo relacional "customer"
+const row = {
+  id: 123,
+  customer: {
+    id: 10,          // ← usado em id == / id in via jsonEq/jsonIn
+    name: 'ACME',    // ← usado para exibir label no autocomplete/chip
+    meta: { etag: 'v1' },
+  },
+};
+
+// Regras DSL comuns
+// id ==
+//   jsonEq(customer, '$.id', 10)
+// id in
+//   jsonIn(customer, '$.id', [10, 20])
+// has property
+//   hasJsonKey(customer, '$.meta.etag')
+// caminho/valor (join simples)
+//   jsonEq(customer, '$.name', 'ACME')
+```
+
+Notas
+- O editor usa `displayField` (ex.: `name`) para compor o rótulo, e `valueField` (ex.: `id`) para gerar a DSL.
+- Se o backend devolver o relacionamento já "normalizado" (ex.: `customerId` e `customerName` na mesma linha), você ainda pode expressar condições com operadores padrão (`==`, `in`) no campo numérico/literal — a abordagem relacional é útil quando o payload contém o objeto.
+
+Onde é consumido (preview e runtime)
+
+- Preview/validação no Editor de Regras (usa `DslParser` interno):
+  - Validação da expressão (parse): projects/praxis-table/src/lib/rules-editor/table-rules-editor.component.ts:536
+  - Preview “Testar” (parse + evaluate): projects/praxis-table/src/lib/rules-editor/table-rules-editor.component.ts:909
+- Runtime na Tabela (aplica `rowConditionalStyles`/`conditionalStyles`):
+  - Parser interno do componente: projects/praxis-table/src/lib/praxis-table.ts:282
+
+Observação
+- O runtime da tabela já injeta o registry DSL padrão para validação/parse/execução.
+- Para funções realmente custom, injete via input `[dslFunctionRegistry]` no componente.
+
+Exemplo de Provider (recomendado)
+
+```ts
+import { Injectable } from '@angular/core';
+import { FunctionRegistry } from '@praxisui/specification';
+
+@Injectable({ providedIn: 'root' })
+export class TableDslRegistryFactory {
+  private readonly registry = FunctionRegistry.getInstance<any>('orders-table-rules');
+
+  constructor() {
+    this.registry.clear();
+    this.registry.register('isStatus', (_row: any, value: any, expected: any) =>
+      String(value ?? '').toLowerCase() === String(expected ?? '').toLowerCase(),
+    );
+  }
+
+  get(): FunctionRegistry<any> {
+    return this.registry;
+  }
+}
+
+// Uso no host:
+// <praxis-table [dslFunctionRegistry]="tableDslRegistryFactory.get()" ... />
+```
+
 ### ⚙️ Painel de Configurações
 
 Para abrir o painel de configurações, habilite o modo de edição na tabela:
 
 ```html
-<praxis-table [editModeEnabled]="true"></praxis-table>
+<praxis-table [enableCustomization]="true"></praxis-table>
 ```
 
 Um botão de engrenagem será exibido no canto superior direito. Ao clicar nele, o `SettingsPanel` é aberto permitindo ajustar:
@@ -77,14 +373,14 @@ Quando `resourcePath` é fornecido, a tabela se torna "inteligente":
 
 ```html
 <!-- Exemplo no template do seu componente -->
-<praxis-table resourcePath="human-resources/departamentos" [editModeEnabled]="true"> </praxis-table>
+<praxis-table resourcePath="human-resources/departamentos" [enableCustomization]="true"> </praxis-table>
 ```
 
 Neste exemplo:
 
 - `resourcePath="human-resources/departamentos"` instrui a tabela a se comunicar com o endpoint `/api/human-resources/departamentos`.
 - A tabela fará requisições como `POST /api/human-resources/departamentos/filter` para obter os dados e `GET /api/human-resources/departamentos/schemas` para obter a configuração das colunas.
-- `[editModeEnabled]="true"` permite a edição visual da configuração da tabela em tempo real.
+- `enableCustomization` controla explicitamente o gate de edição visual. O default canônico agora é `false`; declare `[enableCustomization]="true"` quando o host quiser expor customização e surfaces editoriais.
 
 ### Empty State + Quick Connect (sem `resourcePath`)
 
@@ -233,14 +529,18 @@ Quando `behavior.virtualization.enabled` estiver ativo, as linhas da tabela são
 
 ### Concept Usage
 
-- [Schema‑driven UI](../../../../docs/concepts/schema-driven-ui.md)
-- [Self‑describing APIs](../../../../docs/concepts/self-describing-apis.md)
-- [Rules Engines & Specifications](../../../../docs/concepts/rules-engines-and-specifications.md)
-- [Configuration‑driven development](../../../../docs/concepts/configuration-driven-development.md)
+- Schema-driven UI
+- Self-describing APIs
+- Rules engines and specifications
+- Configuration-driven development
 
 - `behavior.pagination.position`: `top` | `bottom` | `both`.
 - `behavior.pagination.style`: `default` | `compact` (aplica classe de estilo no paginator).
 
+Nota sobre estratégia (client vs server)
+- Se `behavior.pagination.strategy` não estiver definido, a tabela assume `server` automaticamente quando há `resourcePath` (dados remotos). Caso contrário, usa `client`.
+- O mesmo vale para `behavior.sorting.strategy`.
+
 ## Duplo clique na linha
 
 Ative em Comportamento → Interação.
@@ -274,6 +574,7 @@ onRowDoubleClick(evt: { action: string; row: any }) {
 
 - Configure em `behavior.sorting.defaultSort`.
 - Aceita objeto único (coluna/direção) ou array para multi‑sort.
+- Status runtime atual: `behavior.sorting.multiSort` está **schema-only** (apenas 1 critério efetivo em runtime).
 
 Exemplos:
 
@@ -299,9 +600,18 @@ sorting: {
 ```
 
 Observação: quando informado, o defaultSort é aplicado na carga inicial se não houver estado de ordenação ativo.
+Observação enterprise: para evitar ambiguidade de contrato, mantenha `multiSort: false` no runtime atual. Se um array for informado em `defaultSort`, trate como payload de compatibilidade/roadmap e valide no host como single-sort efetivo.
+
+### Roadmap / migração de multiSort
+
+- Curto prazo: `multiSort` segue schema-only no runtime.
+- Recomendação de migração: desenhar integrações com fallback para ordenação única (`column` + `direction`).
+- Planejamento: quando multi-sort runtime for implementado, publicar release note com guia de ativação gradual (feature-flag + validação de payload legado).
 
 ## Coluna de ações (sticky)
 
+Nota: por padrão a coluna de ações vem desabilitada. Habilite explicitamente em `actions.row.enabled` e defina as ações desejadas.
+
 - Fixe a coluna de ações no início/fim configurando `actions.row.sticky`:
 
 ```ts
@@ -340,7 +650,7 @@ Onde configurar no Editor Visual:
 
 ## 🔒 Verificação de Schema (ETag) e Notificações (somente em customização)
 
-Quando já existe uma configuração salva (colunas presentes), a tabela não baixa o schema bruto do servidor para montar as colunas. Em vez disso, valida se há uma nova versão do schema usando ETag/If-None-Match. Notificações são exibidas somente quando o modo de customização está ativo (`editModeEnabled = true`).
+Quando já existe uma configuração salva (colunas presentes), a tabela não baixa o schema bruto do servidor para montar as colunas. Em vez disso, valida se há uma nova versão do schema usando ETag/If-None-Match. Notificações são exibidas somente quando o modo de customização está ativo (`enableCustomization = true`).
 
 ### Comportamento
 
@@ -383,12 +693,16 @@ sequenceDiagram
 
 ### Inputs/Outputs
 
-- Inputs (efetivos apenas quando `editModeEnabled = true`):
+- Inputs (efetivos apenas quando `enableCustomization = true`):
   - `notifyIfOutdated: 'inline' | 'snackbar' | 'both' | 'none' = 'both'`
-  - `snoozeMs: number = 86400000` (24h)
+  - `snoozeMs: number = 86400000`
   - `autoOpenSettingsOnOutdated: boolean = false`
-- Output:
-  - `schemaStatusChange: { outdated: boolean; serverHash?: string; lastVerifiedAt?: string; resourcePath?: string }`
+  - `dslFunctionRegistry: FunctionRegistry<any> | null = null`
+- Outputs:
+  - `schemaStatusChange: { outdated: boolean; serverHash?: string; lastVerifiedAt?: string; trigger?: string; tableId?: string }`
+    - Emitido tanto na verificação leve (304/200) quanto no bootstrap do schema (primeira carga via `loadSchema()`).
+  - `metadataChange: { trigger: string; meta: any; tableId?: string }`
+    - Emitido quando `config.meta` é atualizado (ex.: após bootstrap ou verificação ETag). Útil para sincronizar sidebars/bridges de metadados.
 
 ### Fallback Global (opcional)
 
@@ -415,7 +729,7 @@ sequenceDiagram
 
 ```html
 <praxis-table
-  [editModeEnabled]="true"
+  [enableCustomization]="true"
   [notifyIfOutdated]="'both'"
   [snoozeMs]="12 * 60 * 60 * 1000"
   [autoOpenSettingsOnOutdated]="false"
@@ -436,14 +750,14 @@ onSchemaStatus(ev: { outdated: boolean; serverHash?: string; lastVerifiedAt?: st
 ### Notas
 
 - A verificação leve não grava nem usa o schema bruto quando `config.columns` já existe.
-- Em ambientes sem customização (`editModeEnabled=false`), não há notificações visuais; ainda assim `schemaStatusChange` é emitido e `config.meta.lastVerifiedAt` atualizado.
+- Em ambientes sem customização (`enableCustomization=false`), não há notificações visuais; ainda assim `schemaStatusChange` é emitido e `config.meta.lastVerifiedAt` atualizado.
 
 ## Filtro Avançado (PraxisFilter)
 
 ### Boas práticas para estabilidade
 
 - Evite literais em bindings para o carregador dinâmico:
-  - Não use `[fields]="[quickFieldMeta]"`; prefira um array estável como `quickFieldMetaArray` atualizado apenas quando o metadata mudar.
+  - Não use `[fields]="[pinnedFieldMeta]"`; prefira um array estável como `pinnedFieldMetaArray` atualizado apenas quando o metadata mudar.
 - Reutilize `FormGroup` quando possível. Se precisar trocar o `FormGroup` sem mudar os campos, deixe o `DynamicFieldLoader` reatribuir os controles (rebind-only) em vez de recriar componentes.
 - Evite recriar arrays/objetos desnecessariamente em `ngOnChanges`/`ngAfterViewInit`. Prefira atualizar valores (`setValue`, `patchValue`) e manter referências estáveis.
 - Observers (Resize/Mutation): atualize `overlayOrigin` e largura apenas quando houver mudanças reais; isso evita loops de CD.
@@ -471,7 +785,7 @@ onSchemaStatus(ev: { outdated: boolean; serverHash?: string; lastVerifiedAt?: st
 - O `PraxisFilter` busca schema do DTO de filtro via `/schemas/filtered` com ETag/If-None-Match
   e emite `metaChanged` com `{ schemaId, serverHash, context }`.
 - O schema é normalizado e `advancedConfig.metadata` é preenchido para auditoria/telemetria.
-- Detalhes: `docs/schemas/fluxo-schema.md` (cliente/caching, 200/304, reconciliadores Form/Filter).
+- Detalhes: `projects/praxis-core/docs/schema-flow.md` (canônico) e `docs/schemas/fluxo-schema.md` (resumo operacional) para cliente/caching, 200/304 e reconciliadores Form/Filter.
 
 ### Resolução da chave primária (idField)
 
@@ -528,7 +842,9 @@ sequenceDiagram
 
 ### Uso com Dados Locais (Client-Side)
 
-Se você precisar fornecer os dados manualmente (por exemplo, de uma fonte que não é uma API Praxis), pode usar o input `[data]` e omitir o `resourcePath`. Neste modo, todas as operações (paginação, ordenação, filtro) são realizadas no lado do cliente.
+Se você precisar fornecer os dados manualmente (por exemplo, de uma fonte que não é uma API Praxis), pode usar o input `[data]` e omitir o `resourcePath`.
+Importante: o modo local está protegido por feature flag e exige `behavior.localDataMode.enabled = true` (default é `false`).
+Quando a flag está ativa, as operações de paginação, ordenação e filtro são executadas no lado do cliente.
 
 ```typescript
 import { PraxisTable } from "@praxisui/table";
@@ -548,12 +864,13 @@ export class ExampleComponent {
       { field: "name", header: "Nome", type: "string" },
       { field: "email", header: "Email", type: "string" },
     ],
-    behavior: {
-      pagination: { enabled: true, pageSize: 10 },
-      sorting: { enabled: true },
-      filtering: { enabled: true },
-    },
-  };
+	    behavior: {
+	      pagination: { enabled: true, pageSize: 10 },
+	      sorting: { enabled: true },
+	      filtering: { enabled: true },
+	      localDataMode: { enabled: true }, // obrigatório para fluxo local oficial
+	    },
+	  };
 
   employees = [
     { id: 1, name: "João Silva", email: "joao@empresa.com" },
@@ -567,6 +884,8 @@ export class ExampleComponent {
 
 Quando a `<praxis-table>` é conectada a um `resourcePath`, as operações de paginação, ordenação e filtro são delegadas ao backend. Isso garante alta performance, pois apenas os dados visíveis na tela são trafegados pela rede.
 
+Importante: se você não configurar explicitamente as estratégias de paginação/ordenação no `TableConfig`, a tabela resolve automaticamente como `server` quando há `resourcePath`. Se preferir operar no cliente, defina `behavior.pagination.strategy = 'client'` e/ou `behavior.sorting.strategy = 'client'` conscientemente.
+
 O diagrama abaixo detalha a sequência de eventos, desde a interação do usuário na UI até a construção da consulta JPA no servidor.
 
 ```mermaid
@@ -638,7 +957,7 @@ sequenceDiagram
 
 ## 🎨 Edição Visual da Tabela: O Poder do Low-Code
 
-A `<praxis-table>` vem com um poderoso editor de configuração visual que permite personalizar quase todos os aspectos da sua tabela em tempo real, sem escrever uma única linha de código. Ative o editor passando a propriedade `[editModeEnabled]="true"` para o componente.
+A `<praxis-table>` vem com um poderoso editor de configuração visual que permite personalizar quase todos os aspectos da sua tabela em tempo real, sem escrever uma única linha de código. O runtime expõe esse editor somente quando o host ativa `[enableCustomization]="true"`.
 
 A seguir, veja os principais recursos que você pode configurar visualmente:
 
@@ -871,7 +1190,8 @@ export class MyComponent {
     this.configService.setConfig(this.tableConfig);
 
     // Verificar recursos disponíveis
-    const hasMultiSort = this.configService.isFeatureEnabled('multiSort');
+    // No runtime atual, multiSort permanece schema-only.
+    const hasMultiSort = false;
     const hasBulkActions = this.configService.isFeatureEnabled('bulkActions');
   }
 }
@@ -1022,7 +1342,7 @@ Configurações de comportamento (paginação, ordenação, etc.).
 
 Configurações de aparência visual.
 
-Para documentação completa da API, consulte a [documentação da @praxisui/core](../praxis-core/README.md).
+Para documentação completa da API, consulte `projects/praxis-core/README.md`.
 
 ## 🤝 Contribuição
 
@@ -1046,7 +1366,7 @@ Para documentação completa da API, consulte a [documentação da @praxisui/cor
 O `PraxisFilter` pode ser acoplado à barra de ferramentas da tabela. O exemplo abaixo mostra a busca de pessoas por CPF e status.
 
 ```html
-<praxis-filter [resourcePath]="'pessoas'" [formId]="'pessoas-filter'" [persistenceKey]="'pessoas-filter-v1'" [quickField]="'cpf'" [alwaysVisibleFields]="['status']" (submit)="onFilter($event)"></praxis-filter> <praxis-table [data]="tableData"></praxis-table>
+<praxis-filter [resourcePath]="'pessoas'" [formId]="'pessoas-filter'" [persistenceKey]="'pessoas-filter-v1'" [alwaysVisibleFields]="['status']" (submit)="onFilter($event)"></praxis-filter> <praxis-table [data]="tableData"></praxis-table>
 ```
 
 ```ts
@@ -1058,15 +1378,15 @@ onFilter(dto: any) {
 }
 ```
 
-### ⚙️ Painel de Configurações do Filtro
+### ⚙️ Configuração do Filtro
 
-O `PraxisFilter` possui um painel de configurações acessível pelo ícone de
-engrenagem na barra do filtro ou programaticamente através do método
+O `PraxisFilter` pode ser configurado por inputs/JSON de configuração. O atalho
+visual por ícone de engrenagem não é exposto por padrão na tabela/demo.
+Quando necessário, também é possível abrir o painel programaticamente via
 `openSettings()`. Nesse painel é possível ajustar:
 
-- **quickField** – campo utilizado para a busca rápida
 - **alwaysVisibleFields** – campos que permanecem sempre visíveis
-- **placeholder** – texto exibido no campo de busca
+- **alwaysVisibleFieldMetadataOverrides** – patch de metadata por campo sempre visível (controle, clearButton, inlineAutoSize etc.)
 - **showAdvanced** – define se a seção avançada inicia aberta
 
 ```ts
@@ -1078,19 +1398,43 @@ abrirConfiguracoes() {
 ```
 
 Ao aplicar ou salvar, as escolhas são validadas contra os metadados
-disponíveis. O componente exibe uma barra de progresso durante o processo
-de persistência e mensagens de sucesso ou erro via _snack bar_, garantindo
-uma experiência consistente.
+do **DTO de filtro** (schema de `POST /{resource}/filter`). Campos ausentes
+no DTO não são aplicados em `alwaysVisibleFields`.
+O componente exibe uma barra de progresso durante o processo de persistência e
+mensagens de sucesso ou erro via _snack bar_, garantindo uma experiência
+consistente.
+
+### 🔖 Mini‑guia: Atalhos do Filtro (tags)
+
+Atalhos são “chips” que guardam um conjunto de filtros (DTO) para reuso rápido.
+
+- Criar/Salvar
+  - Modal (padrão): o host do diálogo exibe o botão quando `allowSaveTags === true`.
+  - Gaveta (Drawer): o Adapter recebe `allowSaveTags?`, `i18nSaveAsShortcut?` e `onSaveShortcut?` (opcionais). O host deve exibir o botão e chamar `onSaveShortcut(clean({ ...initialDto, ...lastValue }))`.
+  - O DTO é limpo antes de persistir (remove `'' | null | undefined`).
+- Aplicar
+  - Clique/Enter no chip aplica imediatamente `tag.patch` (substitui o estado atual), emite `submit` e persiste.
+  - O chip ativo é destacado (cor/borda + ícone de “check”) quando o DTO atual é igual ao patch do atalho.
+- Editar/Renomear
+  - Apenas atalhos do usuário exibem ícone de lápis. Predefinidos mostram ícone de “cadeado” (somente leitura).
+- Excluir (com Undo)
+  - Exclusão remove imediatamente o atalho do usuário e exibe snackbar “Atalho removido” com ação “Desfazer” quando `confirmTagDelete === true`.
+  - Ao clicar em “Desfazer”, o atalho é restaurado na mesma posição e os eventos são reemitidos.
+- i18n
+  - Chaves úteis: `saveAsShortcut`, `renameShortcut`, `removeShortcut`, `shortcutSaved`, `shortcutRemoved`, `undo`, `readonlyShortcut`.
+
+Veja também: `docs/host-crud-integration.md` (guia operacional host) e `projects/praxis-crud/docs/host-crud-runtime-and-openmode.md` (contrato técnico canônico) para detalhes do contrato do Adapter.
 
 ### Novos Inputs/Outputs (PraxisFilter)
 
-- Inputs (efetivos apenas quando `editModeEnabled = true`):
-  - `editModeEnabled: boolean` — habilita o gate de customização para notificações de schema.
-  - `notifyIfOutdated: 'inline' | 'snackbar' | 'both' | 'none' = 'both'` — canal de notificação quando o schema muda.
+- Inputs (efetivos apenas quando `enableCustomization = true`):
+  - `enableCustomization: boolean` — habilita o gate de customização para notificações de schema.
+  - `notifyIfOutdated: 'inline' | 'snackbar' | 'both' | 'none' = 'both'` — seleciona como o runtime publica avisos de drift quando a política operacional estiver habilitada.
   - `snoozeMs: number = 86400000` — tempo de soneca para avisos (ms).
   - `autoOpenSettingsOnOutdated: boolean = false` — abre Configurações ao detectar schema desatualizado.
+  - `dslFunctionRegistry: FunctionRegistry<any> | null = null` — adiciona funções DSL custom sem substituir o registry nativo.
 - Output:
-  - `schemaStatusChange: { outdated: boolean; serverHash?: string; lastVerifiedAt?: string; formId?: string }` — emitido após verificação leve (304/200).
+  - `schemaStatusChange: { outdated: boolean; serverHash?: string; lastVerifiedAt?: string; tableId?: string }` — emitido após verificação leve (304/200).
 
 #### Fallback Global (opcional)
 
@@ -1104,6 +1448,88 @@ Notas rápidas (Flow ETag no Filter):
 - 200: atualiza `serverHash/lastVerifiedAt`; marca `outdated=true` apenas quando em customização; não aplica o schema automaticamente.
 - O corpo do schema é baixado apenas quando necessário para renderização (ex.: `alwaysVisibleFields` ou ao abrir o painel Avançado).
 
+## Formatação de Colunas (format)
+
+Cada coluna pode declarar `type` e uma string de formatação `format` consumida pelo `DataFormattingService`. Os tipos suportados são: `string`, `number`, `currency`, `percentage`, `date`, `boolean`, `custom`.
+
+Regra geral: a formatação só é aplicada quando há `format` não vazio e `type !== 'custom'`.
+
+Tipos e padrões de `format`:
+- number (DecimalPipe)
+  - Padrões: `minInt.minFrac-maxFrac`
+  - Exemplos: `1.0-0`, `1.2-2`, `1.0-3|nosep` (remove separador de milhar)
+- currency (CurrencyPipe)
+  - Sintaxe: `CURRENCY|DISPLAY|DECIMALS[|nosep]`
+  - Exemplos: `BRL|symbol|2`, `USD|code|0`, `EUR|symbol|2|nosep`
+- percentage (PercentPipe/DecimalPipe)
+  - Sem multiplicador: `1.0-0` (PercentPipe)
+  - Multiplicar por 100: `1.1-1|x100` (DecimalPipe×100 + `%`)
+- date (DatePipe)
+  - Tokens Angular: `shortDate`, `mediumDate`, `longDate`, `fullDate`, `short`, `shortTime`
+  - Padrões customizados: `dd/MM/yyyy`, `yyyy-MM-dd`, `dd/MM/yyyy HH:mm`
+- string (transformações + truncamento)
+  - Transform: `uppercase` | `lowercase` | `titlecase` | `capitalize` | `none`
+  - Transform + truncar: `<transform>|truncate|<max>|<suffix>`
+  - Exemplos: `uppercase|truncate|50|...`, `titlecase`
+- boolean (pré-definidos ou custom)
+  - Presets: `true-false` | `yes-no` | `active-inactive` | `on-off` | `enabled-disabled`
+  - Custom: `custom|Verdadeiro|Falso`
+
+Exemplos de ColumnDefinition:
+```ts
+{ field: 'salario', type: 'currency', format: 'BRL|symbol|2', header: 'Salário' }
+{ field: 'desconto', type: 'percentage', format: '1.1-1|x100', header: 'Desconto' }
+{ field: 'criadoEm', type: 'date', format: 'dd/MM/yyyy', header: 'Criado em' }
+{ field: 'nome', type: 'string', format: 'titlecase|truncate|32|…', header: 'Nome' }
+{ field: 'ativo', type: 'boolean', format: 'yes-no', header: 'Ativo' }
+```
+
+Observações:
+- `|nosep` remove separadores de milhar da saída formatada.
+- Para datas inválidas ou valores não numéricos, o serviço retorna o valor original (com aviso no console).
+- Colunas com renderizador `custom` não passam por formatação automática.
+
+Exemplos práticos no workspace (rotas):
+- Regras Visuais (Simples): `/table-rules-simple`
+- Regras Visuais (Complexas): `/table-rules-complex`
+
+## Auto-render de Avatar (strict mode)
+
+No bootstrap de schema (quando `config.columns` esta vazio), a tabela detecta automaticamente colunas de avatar e aplica `renderer.type = 'avatar'`.
+
+Deteccao:
+- somente quando `FieldDefinition.controlType === 'avatar'`
+
+Renderer aplicado:
+- `renderer: { type: 'avatar', avatar: { srcField, initialsExpr, shape: 'circle', size: 28 } }`
+- alinhamento central e largura compacta (~56px)
+- `initialsExpr` com fallback para `nomeCompleto|nome|fullName|name|title`
+
+Avatar explicito:
+- `renderer: { type: 'avatar', avatar: { srcField, initialsExpr, initialsField, shape: 'circle', size: 28 } }`
+- `initialsField` deriva automaticamente as iniciais de um campo textual quando `srcField` nao resolve imagem e `initialsExpr` nao foi informado
+- `initialsExpr` deve retornar as iniciais prontas; ele nao transforma automaticamente um campo bruto em iniciais
+- quando quiser derivar iniciais a partir de um campo textual, prefira `initialsField`
+- exemplo recomendado: `avatar: { srcField: 'photoUrl', initialsField: 'name' }`
+- exemplo de `initialsExpr` explicito: `avatar: { initialsExpr: \"= (row.name || '').trim().split(/\\s+/).slice(0,2).map(p => p[0] || '').join('').toUpperCase()\" }`
+
+Comportamento importante:
+- a autodeteccao ocorre apenas no bootstrap (nao sobrescreve configuracoes de colunas persistidas)
+- se quiser desabilitar, defina renderer explicito na coluna (`image` ou `text`)
+- para cenarios sem `x-ui`, exponha renderer no config ou ajuste backend para enviar `x-ui.controlType`
+
+Ajustes comuns:
+- `renderer.avatar.shape`: `'square' | 'rounded' | 'circle'`
+- `renderer.avatar.size`: numero em px
+- `renderer.avatar.alt` / `altField`
+- use `conditionalRenderers` para variar renderer por linha
+
+A11y, seguranca e performance:
+- `alt`/`altField` sao respeitados
+- fallback para iniciais quando imagem falha/nao existe
+- URL da imagem sanitizada (bloqueia esquemas perigosos)
+- imagem com `loading=\"lazy\"`
+
 ## 📊 Roadmap
 
 ### Próximas Versões
@@ -1115,7 +1541,7 @@ Notas rápidas (Flow ETag no Filter):
 
 ## 📄 Licença
 
-Apache-2.0 — consulte [LICENSE](../../LICENSE) para detalhes.
+Apache-2.0 — consulte `LICENSE` na raiz do workspace para detalhes.
 
 ---