---
title: "Dynamic Fields Inline Filter Custom Component Guide"
slug: "dynamic-fields-inline-filter-custom-component-guide"
description: "Guia enterprise para criar novos inline filter components em hosts ou contribuicoes da lib, com naming, runtime registry, metadata registry e checklist de UX compacta."
doc_type: "guide"
document_kind: "host-guide"
component: "dynamic-fields"
category: "components"
audience:
  - "host"
  - "frontend"
  - "architect"
level: "advanced"
status: "active"
owner: "praxis-ui"
tags:
  - "dynamic-fields"
  - "inline filter"
  - "custom component"
  - "host extension"
order: 45
icon: "extension"
toc: true
sidebar: true
search_boost: 1.12
reading_time: 20
estimated_setup_time: 35
version: "1.0"
related_docs:
  - "dynamic-fields-host-custom-field-guide"
  - "dynamic-fields-inline-filter-runtime-contract"
  - "dynamic-fields-inline-filter-troubleshooting"
  - "dynamic-inline-filter-catalog"
keywords:
  - "ComponentRegistryService.register"
  - "ENVIRONMENT_INITIALIZER"
  - "inline*"
  - "host custom inline"
last_updated: "2026-03-07"
---

# Dynamic Fields Inline Filter Custom Component Guide

## Objetivo

Ensinar quando e como criar um novo inline component para a trilha de filtro, sem quebrar:

- a shell compacta do `praxis-filter`
- o contrato de payload
- a governanca do host

## Pre-requisitos

- Host Angular com `@praxisui/dynamic-fields` e `praxis-filter` integrados
- Conhecimento basico de `ComponentRegistryService`, `ComponentMetadataRegistry` e `ENVIRONMENT_INITIALIZER`
- Contrato do backend e payload do filtro ja definidos

## Quando vale criar um inline novo

Crie um inline novo somente quando:

- um controle especializado reduz ambiguidade real da feature
- o catalogo existente nao cobre a semantica
- o valor final continua legivel na toolbar
- o backend suporta um shape estavel

Nao crie um inline novo apenas para trocar cosmetica de um select.

## Naming canonico

Para novos inline filters, siga:

- `inline<Domain>`

Exemplos bons:

- `inlineSlaWindow`
- `inlineRiskBand`

Evite:

- `custom-filter`
- `inline-sla`
- nomes sem vinculo explicito com filtro

## Caminho 1. Extensao em host

Para hosts, o fluxo real e:

1. criar componente Angular standalone
2. registrar no `ComponentRegistryService`
3. registrar metadata editorial no `ComponentMetadataRegistry`
4. opcionalmente registrar selector aliases se o host usar fluxo config-first

### Exemplo de registro no bootstrap

```ts
import { ENVIRONMENT_INITIALIZER, inject } from '@angular/core';
import { ComponentRegistryService } from '@praxisui/dynamic-fields';
import { ComponentMetadataRegistry, type ComponentDocMeta, type FieldControlType } from '@praxisui/core';

const hostInlineMeta: ComponentDocMeta = {
  id: 'inlineSlaWindow',
  title: 'SLA Window Inline',
  icon: 'schedule',
  category: 'host-filters',
  description: 'Filtro inline para janela de SLA.',
};

{
  provide: ENVIRONMENT_INITIALIZER,
  multi: true,
  useValue: () => {
    const registry = inject(ComponentRegistryService);
    registry.register('inlineSlaWindow' as FieldControlType, () =>
      import('./filters/inline-sla-window.component').then((m) => m.InlineSlaWindowComponent),
    );
  },
},
{
  provide: ENVIRONMENT_INITIALIZER,
  multi: true,
  useValue: () => {
    inject(ComponentMetadataRegistry).register(hostInlineMeta);
  },
}
```

## Caminho 2. Contribuicao na lib

Se a extensao precisa virar componente oficial da lib:

1. criar pasta em `src/lib/components/inline-<dominio>`
2. adicionar `.component.ts`
3. adicionar `.metadata.ts`
4. adicionar `pdx-*.json-api.md`
5. exportar no `public-api.ts`
6. registrar no `ComponentRegistryService`
7. decidir aliases no `inline-filter-controls.util.ts`
8. decidir como a metadata editorial sera registrada no `ComponentMetadataRegistry`

### Ponto de cuidado: runtime registry != metadata registry

Registrar no `ComponentRegistryService` faz o componente renderizar.

Isso **nao garante**, por si so, que editores ou palettes descubram o componente via `ComponentMetadataRegistry`.

Hoje existem dois padroes reais na workspace:

- metadata apenas exportada como constante `ComponentDocMeta`
- metadata com provider opcional usando `ENVIRONMENT_INITIALIZER`, como em `provideMaterialAvatarMetadata()`

Se o inline novo precisa aparecer de forma discoverable em ferramentas editoriais, a contribuicao oficial deve incluir um mecanismo de registro da metadata, nao apenas o arquivo `.metadata.ts`.

## Compatibilidade com a shell do filtro

Seu componente precisa funcionar em densidade compacta:

- largura controlada
- valor resumido na pill
- abertura/fechamento previsivel
- clear rapido
- estados `readonly`, `disabled` e `presentation mode`

## Requisitos minimos de implementacao

### Forms

O componente deve:

- implementar `ControlValueAccessor`, ou
- integrar corretamente com `[formControl]`

### Metadata

O componente deve consumir metadata suficiente para:

- label
- placeholder
- `clearButton`
- `inlineAutoSize`
- `readonly`
- `disabled`

### Valor

O shape do valor precisa ser:

- simples de entender
- estavel
- compativel com o DTO do filtro

Nao invente um objeto complexo se um range canonicamente conhecido ja resolve.

## Clear button

Se o componente representa filtro rapido, trate `clear` como parte do contrato.

Regras:

- respeitar `metadata.clearButton`
- limpar para estado neutro
- nao confundir limpar com `false`, `0` ou string vazia sem decisao explicita

## Readonly / disabled / presentation mode

Minimo esperado:

- `readonly`: valor visivel, sem mutacao
- `disabled`: fora da interacao, mas com contraste coerente
- `presentation mode`: nao quebrar layout da toolbar

## Compatibilidade backend

Antes de publicar um novo inline:

1. defina o shape do valor
2. valide o DTO backend
3. confirme serializacao de data/hora/range
4. confirme como `clear` vira ausencia de criterio

## Checklist de UX compacta

- placeholder curto
- label inteligivel
- foco visivel
- area de clique suficiente
- clear visivel quando preenchido
- overlay sem overflow estranho
- sem dependencia exclusiva de cor
- leitura do valor na pill ainda faz sentido

## Checklist de engenharia

- registro no `ComponentRegistryService`
- metadata criada em `.metadata.ts`
- metadata registrada quando a contribuicao exigir discoverability em `ComponentMetadataRegistry`
- aliases somente se houver migracao
- spec cobrindo `writeValue`, `clear`, `disabled`
- doc `json-api` criada
- relacionamento com `table` documentado