---
title: "ADR - Dynamic Filter as Cross-Library Feature"
slug: "adr-dynamic-filter-cross-lib-coupling-2026-03"
description: "Decisao de arquitetura para tratar o filtro dinamico como feature transversal entre table, dynamic-fields e metadata-starter, com documentacao e contrato coordenados."
doc_type: "adr"
document_kind: "adr-record"
category: "architecture"
audience:
  - "frontend"
  - "backend"
  - "architect"
  - "platform-team"
level: "advanced"
status: "implemented"
owner: "praxis-ui"
tags:
  - "dynamic-filter"
  - "table"
  - "dynamic-fields"
  - "metadata-starter"
  - "architecture"
toc: true
sidebar: true
related_docs:
  - "dynamic-filter-architecture-overview"
  - "dynamic-filter-payload-contract"
  - "dynamic-filter-range-filters-guide"
  - "dynamic-filter-host-integration-guide"
  - "dynamic-filter-troubleshooting-guide"
last_updated: "2026-03-07"
---

# ADR: Dynamic Filter as Cross-Library Feature

## Status

`implemented`

## Context

Historicamente, o filtro dinâmico podia ser lido de forma fragmentada:

- `table` como componente “dono” da experiência;
- `dynamic-fields` como catálogo de controles;
- `metadata-starter` como detalhe backend separado.

Esse modelo é insuficiente para documentação e governança porque os problemas reais atravessam as três camadas.

Exemplos concretos:

- o `PraxisFilter` decide variantes inline e persistência local;
- os campos `filter-*-inline` definem UX, acessibilidade e envelopes de interação;
- o backend normaliza ranges e rejeita payload inválido com `FILTER_PAYLOAD_INVALID`.

Se a documentação tratar essas partes como silos, o resultado é incompleto.

## Decision

Adotar oficialmente o filtro dinâmico como feature transversal do ecossistema Praxis.

Isso implica:

- a entrada principal de uso público continua em `@praxisui/table`;
- contratos visuais e metadata dos inline continuam canônicos em `@praxisui/dynamic-fields`;
- contrato HTTP, normalização e semântica operacional do payload devem citar explicitamente `praxis-metadata-starter`;
- a documentação da feature deve ser pensada como trilha, e não como README solto por biblioteca.

## Consequences

### Positivas

- documentação mais didática e completa;
- troubleshooting mais rápido;
- menos divergência entre frontend e backend;
- maior clareza sobre onde documentar payload, range e settings.

### Custos

- manutenção documental coordenada entre bibliotecas;
- necessidade de `related_docs` e slugs estáveis;
- revisão mais cuidadosa quando a feature evoluir.

## Non-goals

- fundir fisicamente as bibliotecas;
- mover os componentes inline para dentro de `table`;
- duplicar documentação canônica entre libs.

## Implementation Outline

1. Manter `table` como ponto de entrada da jornada.
2. Referenciar `dynamic-fields` como fonte de verdade para catálogo inline e metadata.
3. Referenciar `metadata-starter` como fonte de verdade para payload backend e normalização.
4. Publicar a trilha documental completa sob `projects/praxis-table/docs`.

## Acceptance Criteria

- trilha documental cobrindo arquitetura, integração host, payload, range, catálogo inline e troubleshooting;
- referências explícitas ao `metadata-starter` nos documentos de contrato;
- navegação consistente entre docs relacionados.

## Source References

- `projects/praxis-table/src/lib/components/praxis-filter/praxis-filter.component.ts`
- `projects/praxis-dynamic-fields/docs/dynamic-fields-inline-components-guide.md` (slug publicado: `dynamic-fields-inline-components-guide`)
- `../praxis-metadata-starter/src/main/java/org/praxisplatform/uischema/filter/web/FilterRequestBodyAdvice.java`
- `../praxis-metadata-starter/src/main/java/org/praxisplatform/uischema/filter/range/RangePayloadNormalizer.java`