---
title: "Dynamic Filter Editor Settings Guide"
slug: "dynamic-filter-editor-settings-guide"
description: "Guia detalhado do editor de configuracoes do filtro dinamico, cobrindo campos always visible, metadata overrides, variantes inline, painel avancado e governanca operacional."
doc_type: "reference"
document_kind: "host-guide"
component: "table"
category: "components"
audience:
  - "host"
  - "frontend"
  - "architect"
level: "advanced"
status: "active"
owner: "praxis-ui"
tags:
  - "dynamic-filter"
  - "filter-settings"
  - "always-visible"
  - "metadata-overrides"
  - "editor"
order: 30
icon: "settings_suggest"
toc: true
sidebar: true
search_boost: 1.15
reading_time: 22
estimated_setup_time: 40
version: "1.0"
related_docs:
  - "dynamic-filter-host-integration-guide"
  - "dynamic-inline-filter-catalog"
  - "dynamic-fields-inline-components-guide"
  - "table-overview"
keywords:
  - "advancedOpenMode"
  - "advancedClearButtonsEnabled"
  - "alwaysVisibleFieldMetadataOverrides"
  - "useInlineDateRangeVariant"
source_of_truth:
  - "projects/praxis-table/src/lib/filter-settings/filter-settings.component.ts"
  - "projects/praxis-table/src/lib/services/filter-config.service.ts"
  - "projects/praxis-table/src/lib/components/praxis-filter/praxis-filter.component.ts"
last_updated: "2026-03-07"
---

# Dynamic Filter Editor Settings Guide

## Objetivo

Documentar o papel do editor/configurador do filtro dinâmico como camada de governança da feature, e não apenas como tela auxiliar.

## Pré-requisitos

- Conhecimento de `advancedFilters.settings`.
- Entendimento básico de `controlType` inline e toolbar compacta.
- Familiaridade com a diferença entre metadata original e overrides do host.

## Quando usar

Use este guia para:

- padronizar o editor do filtro em ambientes enterprise;
- explicar como o host altera a UX sem alterar o DTO original;
- decidir quais flags inline ativar;
- documentar a política de always visible fields.

## Papel do editor

O `filter-settings` não é cosmético. Ele governa:

- quais campos ficam sempre visíveis;
- quais campos podem ser escolhidos pelo usuário;
- quais variantes inline são permitidas;
- como o painel avançado abre;
- como clear buttons e métricas operam.

Em termos arquiteturais, ele é o ponto onde a experiência do filtro deixa de ser “schema puro” e passa a ser “schema + política do produto”.

## Grupos principais de configuração

### Always visible

Campos centrais:

- `alwaysVisibleFields`
- `alwaysVisibleFieldMetadataOverrides`
- `selectedFieldIds`

Use esse grupo para controlar a barra compacta principal.

### Operação

Campos centrais:

- `changeDebounceMs`
- `allowSaveTags`
- `showAdvanced`
- `mode`

Esse grupo controla como o filtro reage, não só como ele parece.

### Variantes inline

Flags principais:

- `useInlineSearchableSelectVariant`
- `useInlineRangeVariant`
- `useInlineDateVariant`
- `useInlineDateRangeVariant`
- `useInlineTimeVariant`
- `useInlineTimeRangeVariant`
- `useInlineTreeSelectVariant`

Essas flags são decisivas para a documentação porque vários `controlType` agora migram para a experiência compacta por padrão, e o host usa essas chaves como opt-out explícito quando precisa preservar o renderer tradicional.

### Painel avançado

Campos centrais:

- `overlayVariant`
- `overlayBackdrop`
- `advancedOpenMode`
- `advancedClearButtonsEnabled`

Esse grupo define a experiência do formulário avançado e precisa ser documentado junto com a jornada de uso.

## Always visible fields em profundidade

### O que são

São os campos “pinned” do filtro, exibidos antes da grade ampliada e antes dos campos opcionais escolhidos pelo usuário.

### Quando usar

Escolha campos que tenham:

- alta frequência de uso;
- leitura rápida;
- valor decisório forte;
- compatibilidade com layout compacto.

### Quando evitar

Evite promover para always visible campos que:

- tenham interação longa e pouco frequente;
- dependam de catálogos remotos lentos;
- exijam overlay complexo para valor baixo de uso;
- prejudiquem a leitura do conjunto da barra.

## Metadata overrides

`alwaysVisibleFieldMetadataOverrides` existe para ajustes controlados sobre campos fixados.

Use quando o campo precisar:

- label mais curta;
- outro `controlType`;
- clear button diferente;
- largura e auto-size específicos;
- hints e aria labels adequados ao modo compacto.

Não use para:

- reinventar o contrato do DTO;
- alterar o significado semântico do campo;
- criar divergência editorial entre barra compacta e formulário avançado sem documentação.

## Política de variantes inline

### Regra recomendada

Inline é o padrão do `praxis-filter` quando existe equivalente dedicado para a barra compacta.

Sugestão prática:

- mantenha `useInlineRangeVariant` e `useInlineDateVariant` no padrão inline;
- mantenha `useInlineDateRangeVariant` no padrão inline e faça opt-out apenas quando o host precisar do renderer dedicado por densidade ou fluxo operacional;
- mantenha `useInlineTimeVariant` e `useInlineTimeRangeVariant` no padrão inline, validando densidade e clareza de rótulo no host real;
- mantenha `useInlineSearchableSelectVariant` no padrão inline, mas faça opt-out se o endpoint, paginação ou volume remoto exigirem o renderer dedicado;
- mantenha `useInlineTreeSelectVariant` no padrão inline para seleção hierárquica compacta e faça opt-out quando o fluxo depender da leitura expandida do componente dedicado.

## Advanced open mode

`advancedOpenMode` define se o filtro avançado abre em:

- `modal`
- `drawer`

Regra recomendada:

- `modal` quando o contexto exige foco e baixa simultaneidade;
- `drawer` quando a tabela precisa continuar visível e comparável durante o refinamento do filtro.

## Clear buttons avançados

`advancedClearButtonsEnabled` não é detalhe cosmético. Ele interfere na velocidade de limpeza do formulário e na previsibilidade da UX.

Recomendação:

- mantenha `true` por padrão em ambientes enterprise;
- desabilite apenas quando houver conflito com um design de formulário altamente controlado.

## Sinais operacionais importantes

O editor também conversa com preocupações de operação:

- `logLevel`
- `enablePerformanceMetrics`

Esses campos ajudam a transformar o filtro em feature observável em vez de caixa-preta.

## Erros editoriais comuns

1. Ativar todas as variantes inline ao mesmo tempo.
2. Tratar `alwaysVisibleFieldMetadataOverrides` como escape hatch permanente.
3. Criar toolbar compacta mais complexa que o formulário avançado.
4. Não documentar por que certos campos foram fixados e outros não.
5. Ignorar diferenças de layout entre desktop, tablet e mobile.

## Recomendação de governança

Para documentação extensa e sustentável:

1. registre a política de always visible por produto;
2. documente quais flags inline estão aprovadas;
3. trate overrides como exceção auditável;
4. mantenha catálogo visual e settings guide sincronizados.