@praxisui/dynamic-fields 8.0.0-beta.9 → 8.0.0-beta.91

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

@@ -0,0 +1,518 @@
+---
+title: "Dynamic Fields Inline Filter Catalog"
+slug: "dynamic-fields-inline-filter-catalog"
+description: "Catalogo especializado dos inline filter components do dynamic-fields, com criterios de uso, shape de valor e notas de UX para a trilha de filtro em table."
+doc_type: "reference"
+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"
+  - "inline"
+  - "catalog"
+order: 42
+icon: "view_compact_alt"
+toc: true
+sidebar: true
+search_boost: 1.2
+reading_time: 24
+estimated_setup_time: 25
+version: "1.0"
+related_docs:
+  - "dynamic-fields-inline-filter-selection-guide"
+  - "dynamic-fields-inline-filter-runtime-contract"
+  - "dynamic-fields-inline-filter-custom-component-guide"
+  - "dynamic-inline-filter-catalog"
+  - "dynamic-filter-range-filters-guide"
+keywords:
+  - "inlineSelect"
+  - "inlinePhone"
+  - "inlineDateRange"
+  - "inlineTreeSelect"
+  - "inlineRelativePeriod"
+last_updated: "2026-05-26"
+---
+
+# Dynamic Fields Inline Filter Catalog
+
+## Objetivo
+
+Catalogar os inline components reais usados pela trilha de filtro em `praxis-table`, sem misturar com o catalogo geral de fields do formulario.
+
+## Superficie publicada para hosts
+
+Este documento continua sendo a referencia editorial da trilha inline.
+
+Para consumo operacional por hosts oficiais, landing page e playground, a superficie canonica e o catalogo exportado pela lib de dynamic-fields. Nele, os inline filters aparecem em `track: inline-filter`, separados dos fields de formulario comuns e validados contra o registry default.
+
+Nesse catalogo exportado, a trilha inline tambem publica:
+
+- `family`, para agrupar a natureza funcional do filtro;
+- `interactionPattern`, para resumir se o caso e `lookup`, `range`, `single-choice`, `multi-choice`, `visual` ou outro padrao dominante;
+- `icon.key` + `icon.tone`, para identidade visual canonica em menus, playgrounds e vitrines derivadas;
+- `dataSourceKind`, para explicitar o custo de integracao do filtro.
+
+## Pre-requisitos
+
+- Entendimento basico de toolbar compacta vs filtro avancado
+- Leitura recomendada do inventario runtime e do guia de payload do filtro
+
+## Como usar este catalogo
+
+Para cada item, leia em conjunto:
+
+- **quando usar**: cenarios em que a variante inline agrega produtividade
+- **quando evitar**: quando a compactacao piora a UX
+- **shape do valor**: valor do componente dentro do form do filtro
+- **UX note**: restricoes de densidade, acessibilidade e leitura na toolbar
+
+Para hosts oficiais:
+
+- a narrativa continua vindo deste markdown;
+- a navegacao, os cues e a iconografia devem ser derivados do catalogo exportado da lib;
+- nao mantenha uma tabela paralela de `interactionPattern` ou `icon` dentro do host.
+
+## Tiers editoriais
+
+- `core compact`: controles universais, previsiveis e de alta recorrencia
+- `advanced compact`: controles validos em toolbar, mas que exigem criterio adicional de densidade
+- `graphic specialized`: controles semanticos ou visuais que entram apenas por decisao explicita de produto
+
+## 1. Texto
+
+### <span id="inline-input"></span>`inlineInput`
+
+- Quando usar: busca textual curta, identificador, nome, codigo, termo livre
+- Quando evitar: texto longo, mascara pesada, validacao complexa que exija componente dedicado
+- Shape do valor: `string`
+- Mascara de display: quando houver semantica explicita em metadata (`mask`, `displayMask`,
+  `inputMask`, `format` com tokens de mascara) o campo renderiza o valor mascarado e preserva
+  o valor cru no form. Para compatibilidade com filtros metadata-driven, `inlineInput` tambem
+  reconhece sinais explicitos de CPF/CNPJ, telefone BR/E.164 e CEP; numeros sem essa semantica
+  permanecem texto cru.
+- Snippet:
+
+```json
+{ "name": "name", "controlType": "inlineInput", "label": "Nome" }
+```
+
+- UX note: mantenha placeholder curto e `clearButton` habilitado
+- Docs relacionadas: `dynamic-fields-inline-filter-runtime-contract`, `dynamic-filter-payload-contract`
+
+### <span id="inline-phone"></span>`inlinePhone`
+
+- Quando usar: busca compacta por telefone em listas de contatos, pessoas, clientes ou funcionarios
+- Quando evitar: edicao completa de telefone, seletor de pais, validacao internacional rica ou cadastro de multiplos telefones
+- Shape do valor: `string` com digitos preservados no form
+- Mascara de display: usa semantica telefonica do `inlineInput`, com `type="tel"` no input nativo e mascara visual quando `phoneFormat`, `mask`, `displayMask`, `inputMask` ou `format` indicarem telefone.
+- Snippet:
+
+```json
+{ "name": "telefone", "controlType": "inlinePhone", "label": "Telefone", "prefixIcon": "phone" }
+```
+
+- UX note: use placeholder curto e nao exponha texto de ajuda permanente na toolbar; detalhes de formato devem ficar em hint acessivel ou filtro avancado
+- Docs relacionadas: `dynamic-fields-inline-filter-runtime-contract`, `dynamic-filter-payload-contract`
+
+## 2. Selecao simples e multipla
+
+### <span id="inline-select"></span>`inlineSelect`
+
+- Quando usar: lista local pequena ou media
+- Quando evitar: catalogo remoto grande ou lookup rico
+- Shape do valor: valor simples
+- Snippet:
+
+```json
+{ "name": "status", "controlType": "inlineSelect", "options": [{ "label": "Ativo", "value": "ACTIVE" }] }
+```
+
+- UX note: o valor precisa continuar legivel dentro da pill
+- Docs relacionadas: `dynamic-fields-inline-filter-selection-guide`, `dynamic-inline-filter-catalog`
+
+### <span id="inline-multiselect"></span>`inlineMultiSelect`
+
+- Quando usar: poucas selecoes simultaneas que precisam permanecer visiveis como tokens compactos na pill
+- Quando evitar: selecao grande ou dependencia de leitura integral permanente fora do painel
+- Shape do valor: `unknown[]`
+- Snippet:
+
+```json
+{ "name": "status", "controlType": "inlineMultiSelect", "multiple": true }
+```
+
+- UX note: o trigger mostra tokens selecionados com overflow `+N`; o painel deve manter uma secao de selecionados para leitura e remocao rapida
+- Docs relacionadas: `dynamic-fields-inline-filter-selection-guide`
+
+### <span id="inline-searchable-select"></span>`inlineSearchableSelect`
+
+- Quando usar: lista media/grande com busca
+- Quando evitar: se `select` simples ja resolve
+- Shape do valor: valor simples ou option object, conforme metadata
+- Snippet:
+
+```json
+{ "name": "departmentId", "controlType": "inlineSearchableSelect", "resourcePath": "/departments/options" }
+```
+
+- UX note: so use quando a busca realmente reduz friccao
+- Docs relacionadas: `dynamic-fields-inline-filter-runtime-contract`, `dynamic-filter-backend-contract-cheatsheet`
+
+### <span id="inline-async-select"></span>`inlineAsyncSelect`
+
+- Quando usar: fonte remota com busca sob demanda ou paginacao
+- Quando evitar: se o custo cognitivo de abrir painel remoto na toolbar for alto
+- Shape do valor: valor simples ou option object
+- Snippet:
+
+```json
+{ "name": "ownerId", "controlType": "inlineAsyncSelect", "resourcePath": "/users/options" }
+```
+
+- UX note: valide loading, empty state e reset de termo na reabertura
+- Docs relacionadas: `dynamic-fields-inline-filter-troubleshooting`
+
+## 3. Lookup e autocomplete
+
+### <span id="inline-entity-lookup"></span>`inlineEntityLookup`
+
+- Quando usar: entidade com `id + descricao`, busca operacional, confirmacao de identidade
+- Quando evitar: simples select local
+- Shape do valor: objeto ou id final, conforme `optionValueKey`
+- Snippet:
+
+```json
+{ "name": "customerId", "controlType": "inlineEntityLookup", "resourcePath": "/customers/options" }
+```
+
+- UX note: sempre explicite `optionLabelKey` e `optionValueKey`
+- Docs relacionadas: `dynamic-fields-inline-filter-runtime-contract`, `dynamic-filter-payload-contract`
+
+### <span id="inline-autocomplete"></span>`inlineAutocomplete`
+
+- Quando usar: sugestao incremental com escolha unica
+- Quando evitar: lookup rico com mais de um identificador
+- Shape do valor: valor simples ou option object
+- Snippet:
+
+```json
+{ "name": "city", "controlType": "inlineAutocomplete", "resourcePath": "/cities/options" }
+```
+
+- UX note: autocomplete inline exige placeholder claro e feedback de carregamento
+- Docs relacionadas: `dynamic-fields-inline-filter-selection-guide`
+
+## 4. Numero e moeda
+
+### <span id="inline-number"></span>`inlineNumber`
+
+- Quando usar: valor numerico unico, score absoluto, quantidade
+- Quando evitar: quando o dominio e intervalo, nao valor pontual
+- Shape do valor: `number`
+- Snippet:
+
+```json
+{ "name": "attempts", "controlType": "inlineNumber", "min": 0, "max": 100 }
+```
+
+- UX note: use `suffix` ou `%` quando o numero isolado puder ser ambiguo
+- Docs relacionadas: `dynamic-fields-inline-filter-runtime-contract`
+
+### <span id="inline-currency"></span>`inlineCurrency`
+
+- Quando usar: valor monetario unico
+- Quando evitar: faixa monetaria
+- Shape do valor: `number`
+- Snippet:
+
+```json
+{ "name": "ticket", "controlType": "inlineCurrency", "currency": "BRL", "locale": "pt-BR" }
+```
+
+- UX note: compacte moeda, mas nao esconda contexto de locale
+- Docs relacionadas: `dynamic-filter-backend-contract-cheatsheet`
+
+## 5. Range
+
+### <span id="inline-currency-range"></span>`inlineCurrencyRange`
+
+- Quando usar: preco, budget, ticket medio, contrato
+- Quando evitar: valor pontual
+- Shape do valor: `{ minPrice?, maxPrice?, currency? }`
+- Snippet:
+
+```json
+{ "name": "salaryRange", "controlType": "inlineCurrencyRange", "currency": "BRL" }
+```
+
+- UX note: resumo na pill deve deixar claro lower/upper bound
+- Docs relacionadas: `dynamic-filter-range-filters-guide`
+
+### <span id="inline-range"></span>`inlineRange`
+
+- Quando usar: range numerico generico, slider simples ou duplo
+- Quando evitar: data, hora ou semantica monetaria
+- Shape do valor: `number` em modo simples; `{ start?, end? }` em `mode: "range"`
+- Snippet:
+
+```json
+{ "name": "scoreRange", "controlType": "inlineRange", "min": 0, "max": 10, "mode": "range" }
+```
+
+- UX note: use presets apenas quando houver ganho real de velocidade
+- Docs relacionadas: `dynamic-filter-range-filters-guide`
+
+### <span id="inline-rating"></span>`inlineRating`
+
+- Tier editorial: `graphic specialized`
+- Quando usar: score visual, rating, classificacao por estrelas
+- Quando evitar: se o backend so entende numero bruto sem ganho semantico ou se o usuario pensa em faixa numerica simples
+- Shape do valor: `{ start?, end? }`
+- Snippet:
+
+```json
+{ "name": "rating", "controlType": "inlineRating", "max": 5 }
+```
+
+- UX note: explicite se a leitura eh valor unico ou faixa e mantenha fallback textual claro na pill
+- Docs relacionadas: `dynamic-filter-range-filters-guide`
+
+### <span id="inline-distance-radius"></span>`inlineDistanceRadius`
+
+- Tier editorial: `graphic specialized`
+- Quando usar: raio de busca, distancia operacional, proximidade
+- Quando evitar: range numerico generico sem semantica espacial ou quando a unidade varia por contexto
+- Shape do valor: `number` em modo simples; `{ start?, end? }` em `mode: "range"`
+- Snippet:
+
+```json
+{ "name": "radius", "controlType": "inlineDistanceRadius", "unit": "km" }
+```
+
+- UX note: sempre mostre unidade e evite esse inline quando o usuario precisar comparar varios sistemas de medida
+- Docs relacionadas: `dynamic-filter-range-filters-guide`
+
+### <span id="inline-score-priority"></span>`inlineScorePriority`
+
+- Tier editorial: `graphic specialized`
+- Quando usar: score com bandas, prioridade, criticidade
+- Quando evitar: numero simples sem valor visual
+- Shape do valor: `number` em modo simples; `{ start?, end? }` em `mode: "range"`
+- Snippet:
+
+```json
+{ "name": "priority", "controlType": "inlineScorePriority", "min": 1, "max": 10 }
+```
+
+- UX note: a legenda visual precisa bater com a semantica do dominio; sem legenda confiavel, prefira `inlineRange`
+- Docs relacionadas: `dynamic-fields-inline-filter-selection-guide`
+
+## 6. Data e tempo
+
+### <span id="inline-date"></span>`inlineDate`
+
+- Quando usar: data unica
+- Quando evitar: periodo completo
+- Shape do valor: `Date`
+- Snippet:
+
+```json
+{ "name": "createdAt", "controlType": "inlineDate", "label": "Criado em" }
+```
+
+- UX note: o host precisa serializar e alinhar timezone com backend
+- Docs relacionadas: `dynamic-fields-inline-filter-runtime-contract`, `dynamic-filter-payload-contract`
+
+### <span id="inline-date-range"></span>`inlineDateRange`
+
+- Quando usar: janela temporal, periodo de analise, atalhos como hoje/7 dias
+- Quando evitar: quando a toolbar ja esta saturada
+- Shape do valor: `{ startDate?, endDate? }`
+- Snippet:
+
+```json
+{ "name": "period", "controlType": "inlineDateRange", "showShortcuts": true }
+```
+
+- UX note: shortcuts nao podem mascarar o shape final enviado ao backend
+- Docs relacionadas: `dynamic-filter-range-filters-guide`
+
+### <span id="inline-time"></span>`inlineTime`
+
+- Quando usar: horario unico
+- Quando evitar: se o usuario pensa em data ou periodo relativo
+- Shape do valor: string `HH:mm`
+- Snippet:
+
+```json
+{ "name": "hour", "controlType": "inlineTime" }
+```
+
+- UX note: sempre mantenha estado vazio claramente distinguivel
+- Docs relacionadas: `dynamic-fields-inline-filter-runtime-contract`
+
+### <span id="inline-time-range"></span>`inlineTimeRange`
+
+- Quando usar: turno, janela operacional, horario de atendimento
+- Quando evitar: quando o backend espera `LocalDateTime`
+- Shape do valor: `{ start?, end? }` com strings `HH:mm`
+- Snippet:
+
+```json
+{ "name": "workHour", "controlType": "inlineTimeRange" }
+```
+
+- UX note: valide bound invertido e fallback de clear
+- Docs relacionadas: `dynamic-filter-range-filters-guide`
+
+## 7. Arvore
+
+### <span id="inline-tree-select"></span>`inlineTreeSelect`
+
+- Tier editorial: `advanced compact`
+- Quando usar: taxonomia, estrutura hierarquica ou unidade organizacional com selecao de no unico e profundidade curta
+- Quando evitar: arvore profunda demais para toolbar, necessidade de expandir varios ramos ou revisao visual da estrutura completa
+- Shape do valor: valor simples do no
+- Snippet:
+
+```json
+{ "name": "orgUnit", "controlType": "inlineTreeSelect", "nodes": [] }
+```
+
+- UX note: preserve contraste, foco e navegacao por teclado no popover; se o usuario precisar "navegar a arvore para pensar", mova o caso para o filtro avancado
+- Docs relacionadas: `dynamic-fields-inline-filter-troubleshooting`
+
+## 8. Semanticos especializados
+
+### <span id="inline-pipeline-status"></span>`inlinePipelineStatus`
+
+- Tier editorial: `graphic specialized`
+- Quando usar: pipeline comercial, esteira, estado operacional
+- Quando evitar: status simples de enum
+- Shape do valor: valor simples ou `unknown[]`
+- Snippet:
+
+```json
+{ "name": "pipelineStatus", "controlType": "inlinePipelineStatus", "options": [] }
+```
+
+- UX note: nao use se o desenho visual nao agrega mais do que um select; esse componente precisa representar uma jornada operacional reconhecivel
+- Docs relacionadas: `dynamic-fields-inline-filter-selection-guide`
+
+### <span id="inline-relative-period"></span>`inlineRelativePeriod`
+
+- Tier editorial: `graphic specialized`
+- Quando usar: hoje, ontem, ultimos 7 dias, este mes
+- Quando evitar: quando a API nao usa a trilha canonica de filtros da plataforma, nao normaliza presets relativos ou quando o time precisa de rastreabilidade exata por data
+- Shape do valor: `string`
+- Snippet:
+
+```json
+{ "name": "periodPreset", "controlType": "inlineRelativePeriod" }
+```
+
+- UX note: com `praxis-metadata-starter`, presets suportados sao normalizados automaticamente para `onDate`, `lastDays` ou `between`; fora dessa trilha, documente a semantica HTTP equivalente e prefira `inlineDateRange`
+- Docs relacionadas: `dynamic-fields-inline-filter-runtime-contract`
+
+### <span id="inline-sentiment"></span>`inlineSentiment`
+
+- Tier editorial: `graphic specialized`
+- Quando usar: sentimento, humor, polaridade
+- Quando evitar: quando o backend ja usa enum simples sem ganho visual
+- Shape do valor: `string`
+- Snippet:
+
+```json
+{ "name": "sentiment", "controlType": "inlineSentiment" }
+```
+
+- UX note: contraste e rotulagem textual continuam obrigatorios; se a leitura final depender de cor ou emoji, o componente esta mal curado
+- Docs relacionadas: `dynamic-fields-inline-filter-troubleshooting`
+
+### <span id="inline-color-label"></span>`inlineColorLabel`
+
+- Tier editorial: `graphic specialized`
+- Quando usar: tags coloridas, labels semanticas, squads, categorias visuais
+- Quando evitar: quando a cor eh o unico canal de significado
+- Shape do valor: valor simples ou `unknown[]`
+- Snippet:
+
+```json
+{ "name": "labels", "controlType": "inlineColorLabel", "options": [] }
+```
+
+- UX note: siga WCAG AA e nao dependa apenas de cor; sem texto curto e consistente, prefira `inlineMultiSelect`
+- Docs relacionadas: `dynamic-fields-inline-filter-troubleshooting`
+
+## 9. Toggle
+
+### <span id="inline-toggle"></span>`inlineToggle`
+
+- Quando usar: booleano com estado neutro
+- Quando evitar: quando `false` e `null` significam coisas diferentes e nao estao documentadas
+- Shape do valor: `boolean | null`
+- Snippet:
+
+```json
+{ "name": "active", "controlType": "inlineToggle" }
+```
+
+- UX note: `clear` deve voltar para neutro, nao para `false`
+- Docs relacionadas: `dynamic-fields-inline-filter-runtime-contract`
+
+## Nota editorial importante
+
+`praxis-table/docs/dynamic-inline-filter-catalog.md` continua sendo a visao de feature e jornada.
+
+Este documento eh a visao de componente e implementacao.
+
+Regra de governanca:
+
+- `praxis-table`: documenta jornada, payload e operacao da feature de filtro;
+- `@praxisui/dynamic-fields`: documenta e publica os componentes inline reutilizaveis;
+- hosts oficiais devem consumir o catalogo exportado da lib, nao reconstruir uma lista inline paralela.
+
+Regra para ranges Java:
+
+- quando o backend usar operacoes `BETWEEN`, `BETWEEN_EXCLUSIVE`, `NOT_BETWEEN` ou `OUTSIDE_RANGE`, o valor simples `number` nao e payload HTTP valido; configure o inline em `mode: "range"` ou use um controle de range dedicado.
+
+## Comparativos rapidos de curadoria
+
+### Prefira `inlineSelect` em vez de `inlinePipelineStatus` quando
+
+- o valor final for um enum simples
+- nao houver jornada operacional clara por etapas
+- a pill precisar permanecer discreta na toolbar
+
+### Prefira `inlineDateRange` em vez de `inlineRelativePeriod` quando
+
+- o time precisa de rastreabilidade exata por data
+- o backend nao normaliza presets relativos de forma canonica
+- usuarios auditam o filtro pelo valor final, nao pelo atalho semantico
+
+### Prefira `inlineRange` em vez de `inlineRating` ou `inlineScorePriority` quando
+
+- a pessoa usuaria pensa em numero bruto
+- nao existe legenda de dominio forte
+- o valor precisa ser comparado com facilidade entre telas
+
+### Prefira `inlineMultiSelect` em vez de `inlineColorLabel` quando
+
+- a cor nao for semanticamente confiavel
+- o estado final precisar continuar claro em acessibilidade
+- o usuario reconhecer a categoria pelo texto, nao pelo badge
+
+### Prefira filtro avancado em vez de `inlineTreeSelect` quando
+
+- a arvore tiver muitos niveis
+- a decisao depender de explorar varios ramos
+- a pessoa usuaria precisar revisar a estrutura para confiar no filtro ativo