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

package/docs/dynamic-fields-inline-filter-selection-guide.md

@@ -0,0 +1,419 @@
+---
+title: "Dynamic Fields Inline Filter Selection Guide"
+slug: "dynamic-fields-inline-filter-selection-guide"
+description: "Guia de decisao para escolher o inline correto na trilha de filtro, equilibrando densidade, semantica, payload e custo de integracao."
+doc_type: "guide"
+document_kind: "host-guide"
+component: "dynamic-fields"
+category: "components"
+audience:
+  - "frontend"
+  - "host"
+  - "designer"
+  - "architect"
+level: "advanced"
+status: "active"
+owner: "praxis-ui"
+tags:
+  - "dynamic-fields"
+  - "dynamic-filter"
+  - "selection"
+  - "ux"
+order: 43
+icon: "rule"
+toc: true
+sidebar: true
+search_boost: 1.16
+reading_time: 16
+estimated_setup_time: 15
+version: "1.0"
+related_docs:
+  - "dynamic-fields-inline-filter-catalog"
+  - "dynamic-fields-inline-filter-runtime-contract"
+  - "dynamic-inline-filter-catalog"
+  - "dynamic-filter-range-filters-guide"
+keywords:
+  - "quando usar inline"
+  - "single value vs range"
+  - "local vs remoto"
+  - "compact toolbar"
+last_updated: "2026-03-26"
+---
+
+# Dynamic Fields Inline Filter Selection Guide
+
+## Objetivo
+
+Ajudar times host a escolher o inline correto sem transformar a toolbar do filtro em um formulario comprimido e confuso.
+
+## Pre-requisitos
+
+- Conhecer a feature de filtro dinamico em `praxis-table`
+- Saber o tipo de dado e a expectativa de payload do backend
+
+## Fonte canonica para descoberta
+
+Para landing pages, playgrounds e outros hosts oficiais, a descoberta da trilha inline deve partir do catalogo exportado por `@praxisui/dynamic-fields`.
+
+Esse catalogo centraliza os mesmos `controlType` desta trilha com semantica pronta para descoberta:
+
+- `track`, para separar `inline-filter` de outras trilhas;
+- `family`, para agrupar a natureza funcional do filtro;
+- `interactionPattern`, para resumir se o caso dominante e `lookup`, `range`, `single-choice`, `multi-choice`, `visual` ou `trigger`;
+- `dataSourceKind`, para deixar claro se o caso e local, remoto, misto ou especializado;
+- `icon.key` e `icon.tone`, para projetar identidade visual canonica sem inventar outra taxonomia no host.
+
+Regra de uso:
+
+- este guia continua sendo a narrativa de decisao;
+- o inventario continua provando suporte runtime real;
+- cues de navegacao, mini-cards e vitrines devem ser derivados do catalogo exportado da lib.
+
+## Principio central
+
+Um inline filter component so vale a pena quando melhora a velocidade de decisao na barra compacta.
+
+Se ele exige muita exploracao, muita leitura ou muito backend roundtrip, prefira deixar a experiencia no filtro avancado.
+
+```mermaid
+flowchart TD
+  field["Filter field candidate"] --> freq{"High frequency?"}
+  freq -- no --> advanced["Keep in advanced filter"]
+  freq -- yes --> legible{"Readable active state?"}
+  legible -- no --> advanced
+  legible -- yes --> payload{"Payload fits backend DTO?"}
+  payload -- no --> advanced
+  payload -- yes --> density{"Compact enough for toolbar?"}
+  density -- yes --> inline["Promote to inline control"]
+  density -- no --> advanced
+```
+
+## Perguntas de decisao
+
+1. O usuario usa esse filtro com frequencia alta?
+2. O valor final continua legivel na pill?
+3. O shape do valor ja conversa bem com o DTO do backend?
+4. O filtro depende de lista remota pesada ou hierarquia profunda?
+5. O controle expressa uma semantica especifica do dominio ou eh so um field generico?
+
+Antes de transformar essas respostas em navegacao publicada, projete o resultado usando `interactionPattern`, `dataSourceKind` e `icon` vindos do catalogo exportado em vez de montar uma tabela paralela no host.
+
+## Simples vs multipla
+
+### Escolha simples
+
+Prefira:
+
+- `inlineSelect`
+- `inlineSearchableSelect`
+- `inlineAsyncSelect`
+- `inlineEntityLookup`
+- `inlineAutocomplete`
+
+Pergunta chave:
+
+- o usuario escolhe um item ou procura por uma entidade?
+
+Use `entity-lookup` quando a identidade do item importa.
+Use `select`/`searchable` quando o label por si so basta.
+
+### Escolha multipla
+
+Prefira:
+
+- `inlineMultiSelect`
+- `inlinePipelineStatus`
+- `inlineColorLabel`
+
+Evite inline multiplo quando:
+
+- a selecao tipica passa de 3 ou 4 itens;
+- a pill perde poder explicativo;
+- o usuario precisa revisar a lista completa para confiar no estado.
+
+## Local vs remoto
+
+### Local
+
+Use variantes locais quando:
+
+- o conjunto de opcoes eh estavel;
+- a lista cabe em memoria sem custo operacional;
+- a toolbar precisa abrir rapido.
+
+### Remoto
+
+Use variantes remotas quando:
+
+- o conjunto eh grande ou dependente de tenant;
+- ha busca paginada;
+- o filtro faz parte de operacao enterprise real.
+
+Prefira:
+
+- `inlineAsyncSelect`
+- `inlineEntityLookup`
+- `inlineAutocomplete`
+
+Risco:
+
+- backend lento degrada a UX da toolbar mais rapido do que degrada um modal de filtro avancado.
+
+## Single value vs range
+
+### Single value
+
+Prefira:
+
+- `inlineInput`
+- `inlineNumber`
+- `inlineCurrency`
+- `inlineDate`
+- `inlineTime`
+- `inlineToggle`
+
+### Range
+
+Prefira:
+
+- `inlineRange`
+- `inlineCurrencyRange`
+- `inlineDateRange`
+- `inlineTimeRange`
+- `inlineRating`
+- `inlineDistanceRadius`
+- `inlineScorePriority`
+
+Regra:
+
+- se o backend opera com lower/upper bound, documente o shape canonicamente como range
+- nao disfarce um range como numero simples apenas para caber na toolbar
+
+## Inline compacto vs advanced filter
+
+### Fica bem na toolbar
+
+- valor curto e recorrente
+- uma ou duas interacoes para definir
+- leitura rapida do estado ativo
+- clear facil
+
+### Melhor no painel avancado
+
+- lista profunda
+- arvore grande
+- validacao pesada
+- combinacao de muitos subcampos
+- dependencia forte de contexto adicional
+
+## Especializado semantico vs controle generico
+
+Use controles especializados quando a semantica visual reduz ambiguidade:
+
+- `inlineRating`
+- `inlineDistanceRadius`
+- `inlinePipelineStatus`
+- `inlineScorePriority`
+- `inlineRelativePeriod`
+- `inlineSentiment`
+- `inlineColorLabel`
+
+Evite especializados quando:
+
+- o backend e o usuario so precisam de um enum simples;
+- a visualizacao rica nao muda a decisao.
+
+Regra de produto obrigatoria:
+
+- componentes `graphic specialized` entram na toolbar somente por `controlType` explicito no schema
+- eles nao devem ser promovidos automaticamente a partir de um controle generico
+- se houver duvida entre `inlineSelect` e um especializado visual, prefira o controle generico
+
+Familia `graphic specialized`:
+
+- `inlinePipelineStatus`
+- `inlineRelativePeriod`
+- `inlineRating`
+- `inlineDistanceRadius`
+- `inlineScorePriority`
+- `inlineSentiment`
+- `inlineColorLabel`
+
+## Tiers de densidade
+
+### Core compact
+
+Use como primeira opcao na toolbar:
+
+- `inlineInput`
+- `inlineSelect`
+- `inlineSearchableSelect`
+- `inlineAsyncSelect`
+- `inlineEntityLookup`
+- `inlineAutocomplete`
+- `inlineNumber`
+- `inlineCurrency`
+- `inlineRange`
+- `inlineCurrencyRange`
+- `inlineDate`
+- `inlineDateRange`
+- `inlineTime`
+- `inlineTimeRange`
+- `inlineToggle`
+- `inlinePeriodRange`
+
+Heuristica:
+
+- uma interacao principal
+- estado preenchido facil de ler
+- baixo custo de explicacao para usuario novo
+
+### Advanced compact
+
+Use quando houver ganho claro e frequente:
+
+- `inlineMultiSelect`
+- `inlineTreeSelect`
+
+Regra:
+
+- `inlineTreeSelect` so vale a pena para hierarquias rasas, com rotulo final curto e selecao de no unico
+- se a arvore exigir exploracao profunda, varios niveis expandidos ou revisao estrutural para confiar no estado, prefira filtro avancado ou desative a promocao inline
+
+### Graphic specialized
+
+Use apenas por opt-in explicito:
+
+- `inlinePipelineStatus`
+- `inlineRelativePeriod`
+- `inlineRating`
+- `inlineDistanceRadius`
+- `inlineScorePriority`
+- `inlineSentiment`
+- `inlineColorLabel`
+
+Regra:
+
+- esses componentes nunca devem ser o primeiro default editorial quando um controle generico resolve
+- so use quando a linguagem visual reduz ambiguidade ou acelera decisao de forma mensuravel
+- se a principal vantagem for "ficar mais bonito", nao use na toolbar compacta
+
+## Anti-padroes comuns
+
+- promover `inlineTreeSelect` para qualquer taxonomia so porque existe arvore no backend
+- usar `inlineRelativePeriod` quando a API nao normaliza presets relativos de forma canonica
+- usar `inlinePipelineStatus` para enum simples de status administrativo
+- usar `inlineColorLabel` quando a cor eh o unico canal sem texto de apoio
+- usar `inlineRating` ou `inlineScorePriority` quando o usuario pensa em numero bruto, nao em banda visual
+
+## Matriz de decisao
+
+| Pergunta | Melhor opcao |
+| --- | --- |
+| Lista pequena, selecao unica | `inlineSelect` |
+| Lista grande com busca | `inlineSearchableSelect` |
+| Lista remota paginada | `inlineAsyncSelect` |
+| Entidade com id + descricao | `inlineEntityLookup` |
+| Sugestao incremental | `inlineAutocomplete` |
+| Texto curto | `inlineInput` |
+| Numero unico | `inlineNumber` |
+| Valor monetario unico | `inlineCurrency` |
+| Faixa monetaria | `inlineCurrencyRange` |
+| Range numerico generico | `inlineRange` |
+| Data unica | `inlineDate` |
+| Periodo | `inlineDateRange` |
+| Horario unico | `inlineTime` |
+| Faixa horaria | `inlineTimeRange` |
+| Hierarquia rasa, no unico e leitura curta | `inlineTreeSelect` |
+| Booleano com neutro | `inlineToggle` |
+| Score visual com ganho semantico real | `inlineRating` |
+| Distancia / raio com unidade explicita | `inlineDistanceRadius` |
+| Status visual de pipeline com semantica operacional | `inlinePipelineStatus` |
+| Score / prioridade por banda com legenda clara | `inlineScorePriority` |
+| Preset temporal em API com normalizacao canonica | `inlineRelativePeriod` |
+| Polaridade / sentimento com leitura textual clara | `inlineSentiment` |
+| Tags com cor e rotulo textual forte | `inlineColorLabel` |
+
+## Recipes comparativos
+
+### Use isto / evite isto
+
+#### Enum simples de status administrativo
+
+Use isto:
+
+- `inlineSelect`
+
+Evite isto:
+
+- `inlinePipelineStatus`
+
+Motivo:
+
+- se o usuario so precisa escolher `Ativo`, `Inativo` ou `Pendente`, a metafora de pipeline adiciona peso visual sem acelerar decisao
+
+#### Periodo analitico com rastreabilidade
+
+Use isto:
+
+- `inlineDateRange`
+- `inlinePeriodRange`
+
+Evite isto:
+
+- `inlineRelativePeriod` quando o backend nao normaliza presets
+
+Motivo:
+
+- filtros analiticos precisam deixar claro o recorte final enviado ao backend; se a plataforma nao fecha essa traducao canonicamente, o preset relativo cria opacidade
+
+#### Hierarquia organizacional
+
+Use isto:
+
+- `inlineTreeSelect` para arvore rasa, selecao unica e rotulo final curto
+
+Evite isto:
+
+- `inlineTreeSelect` para navegacao exploratoria ou estruturas profundas
+
+Motivo:
+
+- quando a pessoa precisa abrir muitos ramos para decidir, a toolbar vira um mini navegador de arvore e perde sua funcao compacta
+
+#### Faixa numerica sem semantica visual forte
+
+Use isto:
+
+- `inlineRange`
+
+Evite isto:
+
+- `inlineRating`
+- `inlineScorePriority`
+
+Motivo:
+
+- se o dominio pensa em numero ou intervalo bruto, o componente especializado so troca clareza por ornamento
+
+#### Tags ou categorias
+
+Use isto:
+
+- `inlineMultiSelect`
+
+Evite isto:
+
+- `inlineColorLabel` quando a cor for o principal canal
+
+Motivo:
+
+- cor pode ajudar, mas nao pode carregar sozinha a semantica de um filtro enterprise
+
+## Recomendacoes enterprise
+
+- use `controlType` canonico `inline*`
+- valide sempre o shape do valor com o DTO da tabela
+- nao promova um controle para inline so porque existe componente pronto
+- trate `inlineTreeSelect` como excecao operacional, nao como default para qualquer hierarquia
+- trate a familia `graphic specialized` como opt-in de produto, nunca como decoracao padrao

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

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