---
title: "Dynamic Fields Inline Filter Troubleshooting"
slug: "dynamic-fields-inline-filter-troubleshooting"
description: "Runbook de troubleshooting para inline filters, cobrindo renderizacao, payload, range, clear button e problemas de densidade na toolbar."
doc_type: "reference"
document_kind: "host-guide"
component: "dynamic-fields"
category: "integration"
audience:
  - "frontend"
  - "host"
  - "platform-team"
level: "advanced"
status: "active"
owner: "praxis-ui"
tags:
  - "dynamic-fields"
  - "dynamic-filter"
  - "troubleshooting"
  - "inline"
order: 46
icon: "build_circle"
toc: true
sidebar: true
search_boost: 1.12
reading_time: 16
estimated_setup_time: 15
version: "1.0"
related_docs:
  - "dynamic-fields-inline-filter-runtime-contract"
  - "dynamic-fields-inline-filter-custom-component-guide"
  - "dynamic-filter-troubleshooting-guide"
  - "dynamic-filter-backend-contract-cheatsheet"
keywords:
  - "inline nao renderiza"
  - "payload invalido"
  - "controlType errado"
  - "toolbar overflow"
last_updated: "2026-03-07"
---

# Dynamic Fields Inline Filter Troubleshooting

## Objetivo

Resolver as falhas mais comuns na trilha de inline filters entre `dynamic-fields`, `table` e backend.

```mermaid
flowchart TD
  issue["Inline filter issue"] --> render["Check controlType and registry"]
  render --> mapping["Confirm resolved component"]
  mapping --> payload["Inspect emitted form value"]
  payload --> range["Validate range shape"]
  range --> toolbar["Review toolbar density and accessibility"]
  toolbar --> backend["Compare with backend DTO and filter contract"]
```

## Pre-requisitos

- Saber qual `controlType` o schema esta enviando
- Conseguir inspecionar o valor emitido pelo formulario
- Ter o contrato do backend ou `GenericFilterDTO` em maos

## 1. Inline nao renderiza

Checklist:

- o `controlType` existe em `INLINE_FILTER_CONTROL_TYPES` ou foi registrado no host?
- o `ComponentRegistryService` conhece esse tipo?
- o `praxis-filter` realmente promoveu o campo para a variante inline esperada?

Causas comuns:

- `controlType` inventado
- flag `useInline*Variant` desligada
- componente custom registrado fora do root injector

## 2. `controlType` resolve para componente errado

Checklist:

- verifique `inline-filter-controls.util.ts`
- verifique `normalizeControlType` do `ComponentRegistryService`
- verifique `normalizeInlineControlType` no `filter-settings`

Causas comuns:

- schema usando `controlType` inexistente
- host assumindo um componente que nao esta registrado
- divergencia entre o `controlType` salvo e o `controlType` esperado pelo runtime

## 3. Payload nao bate com backend

Checklist:

- confirme o valor emitido pelo form
- confirme o DTO esperado pelo backend
- confirme o shape de range
- confirme serializacao de data/hora

Causas comuns:

- enviar metadata de UI junto do DTO
- assumir que option object sera aceito pelo backend
- tratar preset relativo como se o backend entendesse automaticamente

## 4. Range sai em shape invalido

Checklist:

- `inlineRange`: `number` em modo simples; `{ start?, end? }` em `mode: "range"`
- `inlineCurrencyRange`: `{ minPrice?, maxPrice?, currency? }`
- `inlineDateRange`: `{ startDate?, endDate? }`
- `inlineTimeRange`: `{ start?, end? }`

Causas comuns:

- range vazio indo para submit
- bound invertido sem tratamento
- payload escalar enviado para operacao Java de range

## 5. Funciona no form, mas nao no filtro inline

Isso e esperado em varios casos.

O fato de um field existir no catalogo geral nao significa que ele cabe na shell compacta do filtro.

Valide:

- densidade
- clear rapido
- leitura do valor na pill
- overlay/popover

## 6. Clear button / readonly / disabled nao respeitados

Checklist:

- metadata chega ao componente?
- o componente custom consome `clearButton`, `readonly` e `disabled`?
- o shell esta bloqueando interacao por `readonlyMode` ou `disabledMode`?
- o `FormControl` esta desabilitado quando o componente realmente precisa refletir `aria-disabled` no DOM?
- `clear` volta para estado neutro ou para valor arbitrario?

Risco:

- toolbar enterprise fica inconsistente e gera criterio fantasma

Regra canonica:

- `disabledMode` bloqueia interacao no `FieldShell`
- `FormControl.disabled` controla o estado nativo do controle
- em selects Material, nao reintroduzir `[disabled]` local so para espelhar `disabledMode`

## 7. Overflow, densidade e acessibilidade ruins na toolbar

Checklist:

- o valor cabe na pill?
- o overlay abre com largura controlada?
- foco visivel?
- contraste suficiente?
- navegacao por teclado mantida?
- overrides globais do host em `.mat-mdc-form-field`, `.mat-mdc-select-panel` ou
  `.mat-mdc-option` estao preservando os tokens package-owned
  `--pdx-inline-field-*` e `--pdx-inline-panel-*`?

Regra:

- se a leitura do estado ativo fica ruim, o componente deveria estar no filtro avancado, nao na toolbar

## 8. Componente remoto parece vazio ao reabrir

Checklist:

- termo de busca temporario esta sendo resetado?
- selecionados sao preloadados?
- `resourcePath` responde?

Especialmente relevante para:

- `inlineSearchableSelect`
- `inlineAsyncSelect`
- `inlineEntityLookup`
- `inlineAutocomplete`

## 9. Componente custom do host nao aparece

Checklist:

- `ComponentRegistryService.register(...)`
- `ComponentMetadataRegistry.register(...)`
- bootstrap em `ENVIRONMENT_INITIALIZER`
- mesmo `controlType` no runtime e na metadata

## 10. Duplicacao confusa entre docs de table e dynamic-fields

Regra de diagnostico:

- se a duvida eh sobre jornada do filtro, procure `table`
- se a duvida eh sobre componente inline, procure `dynamic-fields`