---
title: "Dynamic Filter Host Integration Guide"
slug: "dynamic-filter-host-integration-guide"
description: "Guia operacional para integrar o filtro dinamico em hosts Praxis, cobrindo bindings da tabela, persistencia, eventos, settings e envio do DTO ao backend."
doc_type: "guide"
document_kind: "host-guide"
component: "table"
category: "integration"
audience:
  - "host"
  - "frontend"
  - "architect"
level: "advanced"
status: "active"
owner: "praxis-ui"
tags:
  - "dynamic-filter"
  - "host"
  - "praxis-table"
  - "integration"
  - "settings"
order: 29
icon: "integration_instructions"
toc: true
sidebar: true
search_boost: 1.15
reading_time: 18
estimated_setup_time: 45
version: "1.0"
related_docs:
  - "praxis-table-json-api"
  - "dynamic-filter-architecture-overview"
  - "dynamic-filter-payload-contract"
  - "dynamic-filter-editor-settings-guide"
  - "dynamic-inline-filter-catalog"
keywords:
  - "alwaysVisibleFields"
  - "selectedFieldIds"
  - "allowSaveTags"
  - "changeDebounceMs"
source_of_truth:
  - "projects/praxis-table/src/lib/praxis-table.html"
  - "projects/praxis-table/src/lib/components/praxis-filter/praxis-filter.component.ts"
  - "projects/praxis-table/src/lib/services/filter-config.service.ts"
last_updated: "2026-03-07"
---

# Dynamic Filter Host Integration Guide

## Objetivo

Mostrar como um host integra o filtro dinâmico no contexto real da `table`, incluindo bindings de configuração, eventos emitidos, persistência local e envio do payload ao backend.

## Pré-requisitos

- Conhecimento básico de `TableConfig` e `@praxisui/table`.
- Backend já expondo schema e endpoint de filtro.
- Entendimento prévio do contrato de payload e de ranges.

## Quando usar

Use este guia para:

- plugar o filtro em uma tabela nova;
- padronizar configuração de `advancedFilters.settings`;
- decidir quais campos ficam sempre visíveis;
- alinhar debounce, tags e comportamento do painel avançado.

## Integração mínima

No runtime da tabela, o `praxis-filter` já é montado pela própria `praxis-table`.

O host normalmente atua via `config.behavior.filtering.advancedFilters.settings`, alimentando bindings como:

- `alwaysVisibleFields`
- `alwaysVisibleFieldMetadataOverrides`
- `selectedFieldIds`
- `allowSaveTags`
- `changeDebounceMs`
- `showFilterSettings`

O template da tabela também encaminha:

- `resourcePath`
- `filterId`
- `formId`
- `persistenceKey`
- `fieldMetadata`
- `enableCustomization` (opt-in; default canônico `false`)

O host deve pensar a integração na ordem abaixo.

```mermaid
flowchart TD
  config["Load TableConfig"] --> bindings["Resolve bindings and effective data mode"]
  bindings --> render["praxis-table mounts praxis-filter when advanced filtering is enabled"]
  render --> schema["PraxisFilter uses provided fieldMetadata or resolves schema via /schemas/filtered"]
  schema --> settings["Apply advancedFilters.settings and persisted filter state"]
  settings --> events["Observe submit/change/clear/tags/meta events"]
  events --> backend["Send DTO to /filter or /filter/cursor"]
```

## Fluxo de integração recomendado

### 1. Definir o DTO e o schema do filtro

O host precisa garantir que a fonte de metadata do filtro e o backend estejam alinhados.

Sem isso, o runtime até renderiza o formulário, mas o payload não será previsível.

### 2. Configurar `advancedFilters.settings`

Essas chaves são as mais importantes na prática:

- `alwaysVisibleFields`: fixa campos prioritários na barra do filtro;
- `alwaysVisibleFieldMetadataOverrides`: permite ajustar label, `controlType`, clear button e outros detalhes para campos sempre visíveis;
- `selectedFieldIds`: controla os extras escolhidos pelo usuário;
- `allowSaveTags`: habilita tags persistidas/visíveis;
- `changeDebounceMs`: regula a cadência de emissão de `change` e `submit`.

`selectedFieldIds` é a parte gerenciável da toolbar de filtros. O seletor de
campos deve permitir adicionar e remover esses filtros exibidos; ao remover um
campo com valor ativo, o runtime limpa também o critério correspondente no DTO
e emite o novo payload para evitar filtro invisível. Use `alwaysVisibleFields`
apenas para campos realmente fixos, porque eles não entram nessa remoção rápida
do usuário.

#### Preservar a hierarquia da consulta na toolbar

O host declara a semântica, mas não posiciona controles com CSS próprio. O
`praxis-filter` organiza a consulta em duas regiões internas:

- **critérios**: campos sempre visíveis e campos adicionados por
  `selectedFieldIds`;
- **auxiliar**: atalhos salvos/tags e comandos de gerenciamento, como adicionar
  filtros, limpar critérios e abrir o formulário avançado.

Em containers largos, as duas regiões podem compartilhar a mesma faixa. Quando
o espaço diminui, a região auxiliar desce como um bloco completo; atalhos e
comandos não devem se espalhar por linhas diferentes nem comprimir campos de
data, intervalo ou lookup abaixo da largura utilizável. Em containers estreitos,
os critérios passam para uma coluna e o cluster auxiliar pode quebrar
internamente, preservando a ordem de leitura e de teclado.

Essa adaptação usa a largura do container da tabela, não apenas a viewport. Por
isso, o mesmo contrato continua válido dentro de páginas, cards, drawers e split
panes. Não crie breakpoints no host nem projete atalhos dentro da região de
campos: use os inputs e slots públicos, e deixe o runtime materializar a
geometria. Valide pelo menos os estados sem valor, preenchido, foco, erro e
disabled em tema claro/escuro, zoom de 200% e labels localizados longos.

Atalhos declarados em `tags` devem usar exatamente as chaves e os shapes do DTO
de filtro descoberto. Um atalho de faixa salarial, por exemplo, deve escrever o
mesmo campo de intervalo materializado pelo controle inline; criar um alias
apenas no host produz critério invisível. Tags predefinidas são somente leitura
quanto a renomear e excluir, mas continuam acionáveis e removíveis pelo operador.
O host deve observar `submit` quando atalhos precisam disparar consulta imediata;
`change` permanece a cadência de edição dos campos.

Controles projetados no slot `[toolbar]` recebem orçamento limitado e podem
quebrar dentro do cluster de consulta. Eles devem aceitar redução de largura e
não podem impor `min-width` maior que o slot. Se a operação precisar manter
largura intrínseca rígida, materialize-a como ação governada/overflow em vez de
forçar geometria local.

#### Padronizar `materialDesign` dos campos de filtro

O `praxis-filter` normaliza a metadata efetiva de filtros com uma politica
visual consistente para toolbar compacta e formulario avancado. Quando o host
fornece metadata propria ou overrides em `alwaysVisibleFieldMetadataOverrides`,
ele deve preservar essa politica para campos com icones, prefixos, sufixos,
datepicker toggle, simbolo de moeda, seletor de cor ou clear button.

Configuracao recomendada:

```ts
const filterFieldMaterialDesign = {
  floatLabel: 'always',
  subscriptSizing: 'dynamic',
} as const;
```

Exemplo de override:

```ts
advancedFilters: {
  settings: {
    alwaysVisibleFieldMetadataOverrides: {
      cpf: {
        prefixIcon: 'fingerprint',
        materialDesign: filterFieldMaterialDesign,
      },
      dataNascimento: {
        materialDesign: filterFieldMaterialDesign,
      },
    },
  },
}
```

Nao trate isso como ajuste cosmetico local. O Angular Material recomenda
`floatLabel="always"` para campos `fill`/`outline` com prefixos/sufixos porque o
label em repouso nao compartilha o mesmo alinhamento do valor do input. A regra
de plataforma e aplicar essa politica na metadata efetiva de filtro antes de
recorrer a CSS; o runtime ja faz essa normalizacao para a barra compacta e para
o formulario avancado.

Campos compostos de faixa (`priceRange`, `dateRange`, `dateTimeRange` e
`timeRange`) devem ocupar uma linha completa no formulario avancado. Eles
materializam mais de um controle interno e, quando competem lado a lado com um
campo simples, perdem alinhamento vertical e tornam o hint ambíguo. O
`praxis-filter` aplica essa classe de layout automaticamente ao montar o
`FormConfig` avancado.

### 3. Definir política do painel avançado

Os principais knobs são:

- `advancedOpenMode`: `modal` ou `drawer`;
- `advancedClearButtonsEnabled`: liga ou desliga clear buttons nos campos do formulário avançado;
- `showFilterSettings`: normalmente atrelado a `enableCustomization` quando o host opta por expor customização runtime.

### 4. Observar os eventos corretos

Os eventos principais para integração são:

- `submit`: use para busca explícita;
- `change`: use para filtros reativos com debounce;
- `clear`: reseta o estado do filtro;
- `tagsChange`: sincroniza chips persistidos/salvos;
- `selectedFieldIdsChange`: acompanha customização de campos visíveis;
- `metaChanged` e `schemaStatusChange`: importantes para observabilidade e reconciliação de schema.

## Exemplo mental de integração

O fluxo típico é:

1. host carrega `TableConfig`;
2. `praxis-table` resolve o metadata do filtro;
3. `praxis-filter` renderiza toolbar compacta e/ou formulário avançado;
4. usuário altera valores;
5. host observa `submit` ou `change`;
6. host envia DTO para `/filter` ou `/filter/cursor`.

Quando a página também precisa explicar o recorte ao usuário, observe
`contextChange` separadamente. O payload mantém o DTO em `filter` e acrescenta os
rótulos resolvidos em `labels`; ele serve a Rich Content, badges e surfaces. Não o
reutilize como corpo de `/filter` e não refaça option lookups no host.

## Persistência local

O runtime já persiste dois grupos de informação:

- estado operacional do filtro em `filter-dto:<key>`;
- preferências/configuração em `filter-config:<key>`.

Isso tem duas implicações:

1. a doc do host precisa deixar claro o papel do `persistenceKey`;
2. o reset de preferências precisa considerar DTO e config, não só um deles.

## Estratégia de UX recomendada

### Campos sempre visíveis

Use `alwaysVisibleFields` apenas para filtros de alta frequência e leitura rápida:

- status;
- período principal;
- faixa monetária;
- texto livre;
- owner/departamento em operações recorrentes.

### Metadata overrides

Use `alwaysVisibleFieldMetadataOverrides` quando o mesmo campo precisar:

- de label mais curta;
- de `controlType` inline canônico;
- de `clearButton` diferente;
- de `inlineAutoSize` próprio.

### Debounce

Regra prática:

- `300ms` é o default saudável;
- cenários com backend pesado ou selects remotos podem pedir números maiores;
- evite debounce muito baixo em filtros que disparam chamadas remotas frequentes.

## Tags salvas

`allowSaveTags` muda a experiência do filtro, não só a UI dos chips.

Quando habilitar:

- defina claramente se as tags são só visuais ou se representam presets reais;
- documente como elas afetam a recuperação do estado na próxima sessão;
- valide se faz sentido no contexto da sua tabela, porque nem todo filtro enterprise deve permitir salvar seleções ad hoc.

## Erros comuns de integração

1. Configurar `alwaysVisibleFields` com nomes que não existem no schema.
2. Misturar nomes de `controlType` fora do contrato publicado com nomes canônicos.
3. Persistir estado com `persistenceKey` instável.
4. Escutar só `change` e esquecer estratégia de envio ao backend.
5. Ativar demasiados campos sempre visíveis e destruir a legibilidade da toolbar.

## Recomendação de rollout

Para uma nova tabela enterprise:

1. comece com poucos `alwaysVisibleFields`;
2. use overrides só onde a barra compacta realmente precisa;
3. valide payload com backend antes de abrir opções avançadas;
4. só então ligue tags, settings editor e variantes inline mais complexas.