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

package/README.md

@@ -1,11 +1,32 @@
 # @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
@@ -34,6 +55,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:
@@ -178,6 +398,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 +461,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.
@@ -262,6 +526,8 @@ Observação: quando informado, o defaultSort é aplicado na carga inicial se n
 
 ## 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
@@ -347,8 +613,11 @@ sequenceDiagram
   - `notifyIfOutdated: 'inline' | 'snackbar' | 'both' | 'none' = 'both'`
   - `snoozeMs: number = 86400000` (24h)
   - `autoOpenSettingsOnOutdated: boolean = false`
-- Output:
+- Outputs:
   - `schemaStatusChange: { outdated: boolean; serverHash?: string; lastVerifiedAt?: string; resourcePath?: string }`
+    - Emitido tanto na verificação leve (304/200) quanto no bootstrap do schema (primeira carga via `loadSchema()`).
+  - `metadataChange: { meta: any; reason: 'bootstrap'|'verification'|'applied' }`
+    - 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 +672,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.
@@ -488,7 +757,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 +779,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 +799,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
@@ -1006,7 +1280,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 +1292,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,9 +1312,32 @@ 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: “Guia de Integração — Hosts (filtro em gaveta)” em `docs/host-crud-integration.md` para detalhes do contrato do Adapter.
 
 ### Novos Inputs/Outputs (PraxisFilter)
 
@@ -1064,6 +1361,51 @@ 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`
+
 ## 📊 Roadmap
 
 ### Próximas Versões

package/fesm2022/praxisui-table-filter-form-dialog-host.component-CLF05-__.mjs

@@ -0,0 +1,166 @@
+import * as i0 from '@angular/core';
+import { Inject, Component } from '@angular/core';
+import * as i1$1 from '@angular/common';
+import { CommonModule } from '@angular/common';
+import * as i1 from '@angular/material/dialog';
+import { MAT_DIALOG_DATA, MatDialogModule } from '@angular/material/dialog';
+import * as i3 from '@angular/material/button';
+import { MatButtonModule } from '@angular/material/button';
+import * as i15 from '@angular/material/progress-bar';
+import { MatProgressBarModule } from '@angular/material/progress-bar';
+import * as i5 from '@angular/material/icon';
+import { MatIconModule } from '@angular/material/icon';
+import { PraxisFilterForm } from '@praxisui/dynamic-form';
+
+class FilterFormDialogHostComponent {
+    data;
+    ref;
+    valid = true;
+    lastValue = {};
+    formGroup = null;
+    canSave = false;
+    constructor(data, ref) {
+        this.data = data;
+        this.ref = ref;
+    }
+    onReady(ev) {
+        try {
+            this.formGroup = ev?.formGroup || null;
+            const dto = this.data?.initialDto || {};
+            if (ev?.formGroup && dto && Object.keys(dto).length) {
+                ev.formGroup.patchValue(dto, { emitEvent: false });
+            }
+            this.lastValue = this.formGroup?.getRawValue?.() ?? this.lastValue;
+            this.updateCanSave();
+        }
+        catch { }
+    }
+    onChange(ev) {
+        this.lastValue = ev?.formData ?? {};
+        this.updateCanSave();
+    }
+    onValidity(v) {
+        this.valid = v;
+        this.updateCanSave();
+    }
+    apply() {
+        const formData = this.formGroup?.getRawValue?.() ??
+            this.lastValue ??
+            this.data?.initialDto ??
+            {};
+        this.ref.close({ formData });
+    }
+    close() { this.ref.close(); }
+    clean(obj) {
+        const out = {};
+        Object.keys(obj || {}).forEach((k) => {
+            const v = obj[k];
+            if (v !== '' && v !== null && v !== undefined)
+                out[k] = v;
+        });
+        return out;
+    }
+    buildDtoForSave() {
+        const base = this.data?.initialDto || {};
+        const merged = { ...base, ...(this.lastValue || {}) };
+        return this.clean(merged);
+    }
+    updateCanSave() {
+        this.canSave = Object.keys(this.buildDtoForSave() || {}).length > 0;
+    }
+    saveShortcut() {
+        try {
+            const dto = this.buildDtoForSave();
+            if (!Object.keys(dto).length)
+                return;
+            this.data?.onSaveShortcut?.(dto);
+        }
+        catch { }
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.1.4", ngImport: i0, type: FilterFormDialogHostComponent, deps: [{ token: MAT_DIALOG_DATA }, { token: i1.MatDialogRef }], target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "20.1.4", type: FilterFormDialogHostComponent, isStandalone: true, selector: "praxis-filter-form-dialog-host", ngImport: i0, template: `
+    <div mat-dialog-title class="pfx-dialog-title" id="filterDialogTitle">
+      <div class="pfx-dialog-title-text">
+        <mat-icon>tune</mat-icon>
+        <span>{{ data.title || 'Filtro avançado' }}</span>
+      </div>
+      <button mat-icon-button type="button" class="pfx-dialog-close" (click)="close()"
+        [attr.aria-label]="data.i18n?.cancel || 'Fechar'">
+        <mat-icon>close</mat-icon>
+      </button>
+    </div>
+    <mat-dialog-content class="pfx-filter-dialog-content" aria-labelledby="filterDialogTitle">
+      <mat-progress-bar *ngIf="data?.schemaLoading" mode="indeterminate"></mat-progress-bar>
+      <praxis-filter-form
+        *ngIf="data?.config"
+        [formId]="data.formId"
+        [resourcePath]="data.resourcePath"
+        [mode]="'edit'"
+        [config]="data.config"
+        (formReady)="onReady($event)"
+        (valueChange)="onChange($event)"
+        (validityChange)="onValidity($event)"
+      ></praxis-filter-form>
+      <p *ngIf="!data?.config && !data?.schemaLoading" class="pfx-empty-state">{{ data.i18n?.noData || 'Nenhum dado' }}</p>
+    </mat-dialog-content>
+    <mat-dialog-actions align="end" class="pfx-dialog-actions">
+      <button mat-button type="button"
+              *ngIf="data?.allowSaveTags"
+              [disabled]="!canSave"
+              (click)="saveShortcut()">
+        {{ data.i18n?.saveAsShortcut || 'Salvar como atalho' }}
+      </button>
+      <button mat-stroked-button type="button" (click)="close()">{{ data.i18n?.cancel || 'Cancelar' }}</button>
+      <button mat-flat-button color="primary" (click)="apply()" [disabled]="!valid">
+        {{ data.i18n?.apply || 'Aplicar' }}
+      </button>
+    </mat-dialog-actions>
+  `, isInline: true, styles: [".pfx-dialog-title{display:flex;align-items:center;justify-content:space-between;gap:12px;padding-right:8px}.pfx-dialog-title-text{display:inline-flex;align-items:center;gap:8px;font-weight:600;color:var(--md-sys-color-on-surface)}.pfx-dialog-close{margin-left:auto}.pfx-filter-dialog-content{display:flex;flex-direction:column;gap:12px;padding-top:8px}.pfx-empty-state{margin:8px 0 0;color:var(--md-sys-color-on-surface-variant)}.pfx-dialog-actions{padding:var(--pdx-dialog-actions-padding, 12px 24px 16px);border-top:1px solid var(--md-sys-color-outline-variant);background:transparent;display:flex;align-items:center;gap:8px}\n"], dependencies: [{ kind: "ngmodule", type: CommonModule }, { kind: "directive", type: i1$1.NgIf, selector: "[ngIf]", inputs: ["ngIf", "ngIfThen", "ngIfElse"] }, { kind: "ngmodule", type: MatDialogModule }, { kind: "directive", type: i1.MatDialogTitle, selector: "[mat-dialog-title], [matDialogTitle]", inputs: ["id"], exportAs: ["matDialogTitle"] }, { kind: "directive", type: i1.MatDialogActions, selector: "[mat-dialog-actions], mat-dialog-actions, [matDialogActions]", inputs: ["align"] }, { kind: "directive", type: i1.MatDialogContent, selector: "[mat-dialog-content], mat-dialog-content, [matDialogContent]" }, { kind: "ngmodule", type: MatButtonModule }, { kind: "component", type: i3.MatButton, selector: "    button[matButton], a[matButton], button[mat-button], button[mat-raised-button],    button[mat-flat-button], button[mat-stroked-button], a[mat-button], a[mat-raised-button],    a[mat-flat-button], a[mat-stroked-button]  ", inputs: ["matButton"], exportAs: ["matButton", "matAnchor"] }, { kind: "component", type: i3.MatIconButton, selector: "button[mat-icon-button], a[mat-icon-button], button[matIconButton], a[matIconButton]", exportAs: ["matButton", "matAnchor"] }, { kind: "ngmodule", type: MatProgressBarModule }, { kind: "component", type: i15.MatProgressBar, selector: "mat-progress-bar", inputs: ["color", "value", "bufferValue", "mode"], outputs: ["animationEnd"], exportAs: ["matProgressBar"] }, { kind: "ngmodule", type: MatIconModule }, { kind: "component", type: i5.MatIcon, selector: "mat-icon", inputs: ["color", "inline", "svgIcon", "fontSet", "fontIcon"], exportAs: ["matIcon"] }, { kind: "component", type: PraxisFilterForm, selector: "praxis-filter-form", inputs: ["config", "formId", "resourcePath", "mode"], outputs: ["formReady", "valueChange", "submit", "validityChange"] }] });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.1.4", ngImport: i0, type: FilterFormDialogHostComponent, decorators: [{
+            type: Component,
+            args: [{ selector: 'praxis-filter-form-dialog-host', standalone: true, imports: [CommonModule, MatDialogModule, MatButtonModule, MatProgressBarModule, MatIconModule, PraxisFilterForm], template: `
+    <div mat-dialog-title class="pfx-dialog-title" id="filterDialogTitle">
+      <div class="pfx-dialog-title-text">
+        <mat-icon>tune</mat-icon>
+        <span>{{ data.title || 'Filtro avançado' }}</span>
+      </div>
+      <button mat-icon-button type="button" class="pfx-dialog-close" (click)="close()"
+        [attr.aria-label]="data.i18n?.cancel || 'Fechar'">
+        <mat-icon>close</mat-icon>
+      </button>
+    </div>
+    <mat-dialog-content class="pfx-filter-dialog-content" aria-labelledby="filterDialogTitle">
+      <mat-progress-bar *ngIf="data?.schemaLoading" mode="indeterminate"></mat-progress-bar>
+      <praxis-filter-form
+        *ngIf="data?.config"
+        [formId]="data.formId"
+        [resourcePath]="data.resourcePath"
+        [mode]="'edit'"
+        [config]="data.config"
+        (formReady)="onReady($event)"
+        (valueChange)="onChange($event)"
+        (validityChange)="onValidity($event)"
+      ></praxis-filter-form>
+      <p *ngIf="!data?.config && !data?.schemaLoading" class="pfx-empty-state">{{ data.i18n?.noData || 'Nenhum dado' }}</p>
+    </mat-dialog-content>
+    <mat-dialog-actions align="end" class="pfx-dialog-actions">
+      <button mat-button type="button"
+              *ngIf="data?.allowSaveTags"
+              [disabled]="!canSave"
+              (click)="saveShortcut()">
+        {{ data.i18n?.saveAsShortcut || 'Salvar como atalho' }}
+      </button>
+      <button mat-stroked-button type="button" (click)="close()">{{ data.i18n?.cancel || 'Cancelar' }}</button>
+      <button mat-flat-button color="primary" (click)="apply()" [disabled]="!valid">
+        {{ data.i18n?.apply || 'Aplicar' }}
+      </button>
+    </mat-dialog-actions>
+  `, styles: [".pfx-dialog-title{display:flex;align-items:center;justify-content:space-between;gap:12px;padding-right:8px}.pfx-dialog-title-text{display:inline-flex;align-items:center;gap:8px;font-weight:600;color:var(--md-sys-color-on-surface)}.pfx-dialog-close{margin-left:auto}.pfx-filter-dialog-content{display:flex;flex-direction:column;gap:12px;padding-top:8px}.pfx-empty-state{margin:8px 0 0;color:var(--md-sys-color-on-surface-variant)}.pfx-dialog-actions{padding:var(--pdx-dialog-actions-padding, 12px 24px 16px);border-top:1px solid var(--md-sys-color-outline-variant);background:transparent;display:flex;align-items:center;gap:8px}\n"] }]
+        }], ctorParameters: () => [{ type: undefined, decorators: [{
+                    type: Inject,
+                    args: [MAT_DIALOG_DATA]
+                }] }, { type: i1.MatDialogRef }] });
+
+export { FilterFormDialogHostComponent };
+//# sourceMappingURL=praxisui-table-filter-form-dialog-host.component-CLF05-__.mjs.map