@praxisui/dynamic-fields 8.0.0-beta.8 → 8.0.0-beta.81

package/docs/dynamic-fields-inline-filter-custom-component-guide.md

@@ -0,0 +1,241 @@
+---
+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

package/docs/dynamic-fields-inline-filter-inventory.md

@@ -0,0 +1,247 @@
+---
+title: "Dynamic Fields Inline Filter Inventory"
+slug: "dynamic-fields-inline-filter-inventory"
+description: "Inventario runtime-first dos componentes inline usados pela trilha de filtro dinamico, com controlType canonico, paths e shape de valor."
+doc_type: "reference"
+document_kind: "host-guide"
+component: "dynamic-fields"
+category: "components"
+audience:
+  - "frontend"
+  - "host"
+  - "architect"
+  - "platform-team"
+level: "advanced"
+status: "active"
+owner: "praxis-ui"
+tags:
+  - "dynamic-fields"
+  - "dynamic-filter"
+  - "inline"
+  - "inventory"
+  - "runtime"
+order: 41
+icon: "inventory_2"
+toc: true
+sidebar: true
+search_boost: 1.14
+reading_time: 18
+estimated_setup_time: 20
+version: "1.0"
+related_docs:
+  - "dynamic-fields-inline-components-guide"
+  - "dynamic-fields-inline-filter-catalog"
+  - "dynamic-fields-inline-filter-runtime-contract"
+  - "dynamic-inline-filter-catalog"
+  - "dynamic-filter-payload-contract"
+keywords:
+  - "inlineSelect"
+  - "INLINE_FILTER_CONTROL_TYPES"
+  - "ComponentRegistryService"
+  - "praxis-filter"
+source_of_truth:
+  - "projects/praxis-core/src/lib/utils/inline-filter-controls.util.ts"
+  - "projects/praxis-dynamic-fields/src/lib/services/component-registry/component-registry.service.ts"
+  - "projects/praxis-table/src/lib/components/praxis-filter/praxis-filter.component.ts"
+  - "projects/praxis-table/src/lib/filter-settings/filter-settings.component.ts"
+last_updated: "2026-03-23"
+---
+
+# Dynamic Fields Inline Filter Inventory
+
+## Objetivo
+
+Inventariar os inline filter components reais do runtime, sem misturar com o catalogo geral de fields do formulario.
+
+## Pre-requisitos
+
+- Leitura basica de `PraxisFilter` e `@praxisui/dynamic-fields`
+- Familiaridade com `controlType`, `ComponentRegistryService` e metadata de campo
+
+## Fonte de verdade usada
+
+Este inventario foi derivado de quatro camadas reais:
+
+1. `INLINE_FILTER_CONTROL_TYPES` no `@praxisui/core`
+2. registro explicito no `ComponentRegistryService`
+3. promocao de controls genericos para inline no `PraxisFilter`
+4. configuracao canonica publicada no editor de settings do filtro
+
+## Runtime inventory vs host consumption
+
+Este documento continua sendo a auditoria `runtime-first` da trilha inline.
+
+Para consumo por landing page, playground e outros hosts oficiais, a superficie publicada deve ser o catalogo exportado por `@praxisui/dynamic-fields`, que organiza os mesmos `controlType` em uma trilha `inline-filter` governada e pronta para descoberta.
+
+Nesse catalogo exportado, a trilha inline tambem publica:
+
+- `family`, para agrupar a natureza funcional do filtro;
+- `interactionPattern`, para resumir o padrao dominante de decisao ou captura;
+- `icon.key` + `icon.tone`, para identidade visual canonica em menus, vitrines e playgrounds;
+- `dataSourceKind`, para explicitar custo e natureza da integracao.
+
+Regra de uso:
+
+- `inventory`: comprova disponibilidade real e contratos de ativacao;
+- `catalog`: organiza descoberta, estados, `interactionPattern`, `icon` e snippets para hosts;
+- `docs`: explicam jornada e governanca, mas nao substituem o registry nem o catalogo exportado.
+
+Regra para hosts:
+
+- derive navegacao, cues e iconografia do catalogo exportado da lib;
+- nao use este inventario como tabela editorial para menu, cards ou vitrine.
+
+## Regras de leitura
+
+- `controlType canonico`: nome a ser salvo em contratos novos.
+- `promocao por flag`: quando o `praxis-filter` converte um `controlType` generico para inline.
+- `dependencia backend`: quando o componente depende de `resourcePath`, lookup remoto ou shape que precisa bater com `GenericFilterDTO`.
+
+## Resumo executivo
+
+Existem **24 controlTypes inline canonicamente publicados** no runtime:
+
+- 24 estao definidos em `INLINE_FILTER_CONTROL_TYPES`
+- 24 estao registrados em `ComponentRegistryService`
+- nem todos aparecem automaticamente na toolbar
+- parte deles so entra na jornada inline por `controlType` explicito
+- parte deles depende de feature flags do `praxis-filter`
+
+## Mapa de ativacao no runtime
+
+### Inline explicito por `controlType`
+
+Sempre entram inline quando o schema usa o `controlType` canonico:
+
+- `inlineEntityLookup`
+- `inlineTime`
+- `inlineTimeRange`
+- `inlineTreeSelect`
+- `inlineRating`
+- `inlineDistanceRadius`
+- `inlinePipelineStatus`
+- `inlineScorePriority`
+- `inlineRelativePeriod`
+- `inlineSentiment`
+- `inlineColorLabel`
+
+### Promocao de control generico para inline por flag do `praxis-filter`
+
+Dependem do schema/base control + flags da trilha de filtro:
+
+- `select` -> `inlineSelect`
+- `multiSelect` -> `inlineMultiSelect`
+- `input`/`searchInput` -> `inlineInput`
+- `numericTextBox` -> `inlineNumber`
+- `currency` -> `inlineCurrency`
+- `priceRange` -> `inlineCurrencyRange`
+- `toggle` -> `inlineToggle`
+- `rangeSlider` -> `inlineRange`
+- `date`/`dateInput`/`datepicker` -> `inlineDate`
+- `dateRange` -> `inlineDateRange`
+- `searchable-select` -> `inlineSearchableSelect`
+- `async-select` -> `inlineAsyncSelect`
+- `autocomplete` -> `inlineAutocomplete`
+
+## Familias
+
+As colunas de implementacao e metadata abaixo descrevem artefatos internos co-localizados ao `controlType`; caminhos fisicos e nomes historicos do workspace nao fazem parte do contrato recomendado.
+
+### Texto
+
+| ControlType canonico | implementacao Angular | Metadata | JSON API | Valor | Visual principal | Dependencia backend |
+| --- | --- | --- | --- | --- | --- | --- |
+| `inlineInput` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | `string` | pill compacta com busca/clear | opcional |
+
+### Selecao
+
+| ControlType canonico | implementacao Angular | Metadata | JSON API | Valor | Visual principal | Dependencia backend |
+| --- | --- | --- | --- | --- | --- | --- |
+| `inlineSelect` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | valor simples | pill + popover Material | opcional |
+| `inlineMultiSelect` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | `unknown[]` | tokens selecionados + overflow `+N` | opcional |
+| `inlineSearchableSelect` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | valor simples ou option object | pill + busca/paginacao no painel | frequente |
+| `inlineAsyncSelect` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | valor simples ou option object | carregamento remoto no painel | sim |
+
+### Remoto / lookup
+
+| ControlType canonico | implementacao Angular | Metadata | JSON API | Valor | Visual principal | Dependencia backend |
+| --- | --- | --- | --- | --- | --- | --- |
+| `inlineEntityLookup` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | objeto ou id conforme `optionValueKey` | lookup `id + descricao` com reset | sim |
+| `inlineAutocomplete` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | valor simples ou option object | busca incremental compacta | frequente |
+
+### Numero e moeda
+
+| ControlType canonico | implementacao Angular | Metadata | JSON API | Valor | Visual principal | Dependencia backend |
+| --- | --- | --- | --- | --- | --- | --- |
+| `inlineNumber` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | `number` | pill numerica compacta | nao |
+| `inlineCurrency` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | `number` | mascara monetaria inline | nao |
+
+### Range
+
+| ControlType canonico | implementacao Angular | Metadata | JSON API | Valor | Visual principal | Dependencia backend |
+| --- | --- | --- | --- | --- | --- | --- |
+| `inlineCurrencyRange` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | `{ minPrice?, maxPrice?, currency? }` | pill + slider/input monetario | sim |
+| `inlineRange` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | `number` em modo simples; `{ start?, end? }` em `mode: "range"` | slider simples ou duplo | sim para ranges |
+| `inlineRating` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | `{ start?, end? }` | rating semantico com bandas | sim para range/score |
+| `inlineDistanceRadius` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | `number` em modo simples; `{ start?, end? }` em `mode: "range"` | raio/distancia com anel visual | sim |
+| `inlineScorePriority` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | `number` em modo simples; `{ start?, end? }` em `mode: "range"` | faixa de score/prioridade | sim |
+
+### Data e tempo
+
+| ControlType canonico | implementacao Angular | Metadata | JSON API | Valor | Visual principal | Dependencia backend |
+| --- | --- | --- | --- | --- | --- | --- |
+| `inlineDate` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | `Date` no controle; host costuma serializar para data | datepicker compacto | sim na serializacao |
+| `inlineDateRange` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | `{ startDate?, endDate? }` | pill de periodo com shortcuts | sim |
+| `inlineTime` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | string `HH:mm` | seletor de horario compacto | sim |
+| `inlineTimeRange` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | `{ start?, end? }` com strings `HH:mm` | faixa horaria com dois inputs e slider | sim |
+
+### Arvore
+
+| ControlType canonico | implementacao Angular | Metadata | JSON API | Valor | Visual principal | Dependencia backend |
+| --- | --- | --- | --- | --- | --- | --- |
+| `inlineTreeSelect` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | valor simples do no selecionado | arvore compacta com busca | frequente |
+
+### Score / status / sentiment
+
+| ControlType canonico | implementacao Angular | Metadata | JSON API | Valor | Visual principal | Dependencia backend |
+| --- | --- | --- | --- | --- | --- | --- |
+| `inlinePipelineStatus` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | valor simples ou `unknown[]` quando multiplo | cards/segmentos de status | opcional |
+| `inlineRelativePeriod` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | `string` semantica (`today`, `last7` etc.) | presets de periodo relativo | sim |
+| `inlineSentiment` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | `string` | escolha semantica por sentimento | opcional |
+| `inlineColorLabel` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | valor simples ou `unknown[]` | badges coloridos | opcional |
+
+### Toggle
+
+| ControlType canonico | implementacao Angular | Metadata | JSON API | Valor | Visual principal | Dependencia backend |
+| --- | --- | --- | --- | --- | --- | --- |
+| `inlineToggle` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | `boolean | null` | toggle binario com estado neutro | nao |
+
+## Observacoes de contrato
+
+### Contrato publicado
+
+Salve e documente sempre o `controlType` canônico `inline*`.
+
+### Valor do componente nao e o payload HTTP final
+
+O valor do controle participa da pipeline:
+
+1. componente inline manipula um shape interno
+2. `praxis-filter` agrega o form value
+3. host envia o DTO
+4. backend normaliza ranges quando necessario
+
+Por isso:
+
+- `Date` no front nao significa que o backend recebera `Date`
+- ranges especializados precisam bater com a trilha descrita em `dynamic-filter-range-filters-guide.md`
+- para operacoes Java de range, `number` isolado nao e payload HTTP valido
+
+### Ligacao explicita com table
+
+Estes componentes pertencem a `dynamic-fields`, mas a feature de filtro continua sendo documentada em `praxis-table`.
+
+Regra editorial:
+
+- `table` documenta a jornada do filtro
+- `dynamic-fields` documenta os componentes inline que a jornada utiliza