@praxisui/table 1.0.0-beta.5 → 1.0.0-beta.52

package/README.md

@@ -1,11 +1,82 @@
+---
+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-filter-inline-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
 
+## 🔰 Exemplos / Quickstart
+
+Para ver esta biblioteca em funcionamento em uma aplicação completa, utilize o projeto de exemplo (Quickstart):
+
+- Repositório: https://github.com/codexrodrigues/praxis-ui-quickstart
+- O Quickstart demonstra a integração das bibliotecas `@praxisui/*` em um app Angular, incluindo instalação, configuração e uso em telas reais.
+
 > Componente de tabela empresarial avançado com arquitetura unificada
 
 ## 🌟 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 +98,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/filter-inline-components-guide.md` (slug publicado: `dynamic-fields-filter-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,6 +114,205 @@ 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:
@@ -84,7 +363,7 @@ 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.
+- `editModeEnabled` controla explicitamente o gate de edição visual. No runtime atual o default já é `true`; declare `[editModeEnabled]="false"` quando o host precisar publicar a tabela em modo estritamente read-only.
 
 ### Empty State + Quick Connect (sem `resourcePath`)
 
@@ -178,6 +457,46 @@ sequenceDiagram
 - Virtualização: habilite em Comportamento → Virtualização para listas grandes (requer altura de linha previsível).
 - Densidade e linhas de grade: ajuste em Comportamento → Aparência rápida (compacta/confortável/espaçosa; bordas horizontais/verticais).
 
+## Rolagem Horizontal (owner do scroll)
+
+Por padrão, a `<praxis-table>` agora assume a responsabilidade pela rolagem horizontal quando o conteúdo excede a largura do container. Isso evita cortes de conteúdo e comportamentos inconsistentes entre projetos.
+
+### Input: `horizontalScroll`
+
+```
+@Input() horizontalScroll: 'auto' | 'wrap' | 'none' = 'auto';
+```
+
+- `auto` (padrão): a tabela cria um viewport com `overflow-x: auto` e permite que a tabela interna cresça com `width: max-content`. Quando a soma das colunas > container, aparece a barra de rolagem horizontal neste viewport.
+- `wrap`: permite quebra de linha nas células (libera `white-space: normal`), reduzindo a largura necessária; ideal quando você prefere minimizar a rolagem horizontal.
+- `none`: desabilita o comportamento interno; o host (página) deve fornecer o container com `overflow-x: auto` e as regras de largura necessárias.
+
+Exemplo:
+
+```html
+<!-- Comportamento padrão (auto) -->
+<praxis-table resourcePath="employees"></praxis-table>
+
+<!-- Reduz rolagem: permite quebra de linha nas células -->
+<praxis-table resourcePath="employees" horizontalScroll="wrap"></praxis-table>
+
+<!-- Host controla o scroll horizontal -->
+<div class="table-shell" style="overflow-x:auto">
+  <praxis-table resourcePath="employees" horizontalScroll="none"></praxis-table>
+  <!-- host pode usar width: max-content na tabela interna conforme seu design system -->
+</div>
+```
+
+### Editor de Configuração (Settings Panel)
+
+Na aba “Visão Geral & Comportamento”, há um seletor “Scroll Horizontal” com as opções `Auto`, `Wrap` e `Host` (none). As alterações podem ser aplicadas (Aplicar) ou salvas (Salvar & Fechar). O valor é persistido junto com outras preferências da tabela.
+
+### Notas
+
+- O caminho virtual (CDK Virtual Scroll) permanece sendo o owner da rolagem vertical; o viewport horizontal é um contêiner externo que não interfere no scroll vertical.
+- Cabeçalho sticky continua funcional. Teste combinações com colunas sticky/virt para seu caso.
+- Para grids alternativos (ex.: Kendo), as mesmas regras de `max-content`/`min-width: 100%` se aplicam ao elemento de tabela interno.
+
 ## Virtualização (CDK)
 
 Quando `behavior.virtualization.enabled` estiver ativo, as linhas da tabela são renderizadas com `cdk-virtual-scroll-viewport` (cabeçalho permanece igual).
@@ -201,6 +520,10 @@ Quando `behavior.virtualization.enabled` estiver ativo, as linhas da tabela são
 - `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.
@@ -234,6 +557,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:
 
@@ -259,9 +583,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
@@ -345,10 +678,14 @@ sequenceDiagram
 
 - Inputs (efetivos apenas quando `editModeEnabled = 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)
 
@@ -403,7 +740,7 @@ onSchemaStatus(ev: { outdated: boolean; serverHash?: string; lastVerifiedAt?: st
 ### 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.
@@ -431,7 +768,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)
 
@@ -488,7 +825,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";
@@ -508,12 +847,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" },
@@ -527,6 +867,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
@@ -598,7 +940,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. No runtime atual, o editor já nasce habilitado por padrão; use `[editModeEnabled]="false"` quando o host precisar bloquear customização e manter a tabela em modo estritamente operacional.
 
 A seguir, veja os principais recursos que você pode configurar visualmente:
 
@@ -831,7 +1173,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');
   }
 }
@@ -1006,7 +1349,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
@@ -1018,15 +1361,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
@@ -1038,19 +1381,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.
+  - `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)
 
@@ -1064,6 +1431,80 @@ 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`
+
+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

package/fesm2022/praxisui-table-filter-drawer-adapter.mjs

@@ -0,0 +1,18 @@
+import { InjectionToken } from '@angular/core';
+
+function getFilterDrawerAdapterToken() {
+    const registryKey = '__PAX_FILTER_DRAWER_ADAPTER_TOKEN__';
+    const globalRegistry = globalThis;
+    if (!globalRegistry[registryKey]) {
+        globalRegistry[registryKey] = new InjectionToken('FILTER_DRAWER_ADAPTER');
+    }
+    return globalRegistry[registryKey];
+}
+const FILTER_DRAWER_ADAPTER = getFilterDrawerAdapterToken();
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { FILTER_DRAWER_ADAPTER };
+//# sourceMappingURL=praxisui-table-filter-drawer-adapter.mjs.map