@praxisui/dynamic-fields 8.0.0-beta.6 → 8.0.0-beta.60

package/docs/dynamic-fields-inline-components-guide.md

@@ -0,0 +1,582 @@
+---
+title: "Dynamic Fields Inline Components Guide"
+slug: "dynamic-fields-inline-components-guide"
+description: "Hub tecnico da trilha especializada de inline filter components, conectando catalogo, selecao, contrato runtime, extensao de host e troubleshooting."
+doc_type: "reference"
+document_kind: "host-guide"
+category: "components"
+audience:
+  - "host"
+  - "frontend"
+level: "advanced"
+status: "active"
+owner: "praxis-ui"
+tags:
+  - "filter"
+  - "inline"
+  - "praxis-table"
+  - "dynamic-fields"
+  - "a11y"
+order: 40
+icon: "tune"
+toc: true
+sidebar: true
+search_boost: 1.05
+reading_time: 20
+estimated_setup_time: 30
+version: "1.1"
+deprecated_paths:
+  - "filter-inline-components-guide.md"
+deprecated_slugs:
+  - "dynamic-fields-filter-inline-components-guide"
+related_docs:
+  - "dynamic-fields-inline-filter-inventory"
+  - "dynamic-fields-inline-filter-catalog"
+  - "dynamic-fields-inline-filter-selection-guide"
+  - "dynamic-fields-inline-filter-runtime-contract"
+  - "dynamic-fields-inline-filter-custom-component-guide"
+  - "dynamic-fields-inline-filter-troubleshooting"
+  - "dynamic-filter-payload-contract"
+  - "dynamic-filter-range-filters-guide"
+  - "dynamic-inline-filter-catalog"
+keywords:
+  - "controlType"
+  - "inline*"
+  - "alwaysVisibleFields"
+  - "clearButton"
+last_updated: "2026-03-07"
+---
+
+# Dynamic Fields Inline Components Guide
+
+## Objetivo
+
+Padronizar componentes compactos do filtro dinâmico para uso corporativo, com alta legibilidade, acessibilidade e previsibilidade de comportamento.
+
+Este documento agora funciona como **hub tecnico** da trilha especializada de inline filters.
+
+Use a suite abaixo para a leitura canonica:
+
+- inventario runtime: `dynamic-fields-inline-filter-inventory.md`
+- catalogo especializado: `dynamic-fields-inline-filter-catalog.md`
+- guia de selecao: `dynamic-fields-inline-filter-selection-guide.md`
+- runtime contract: `dynamic-fields-inline-filter-runtime-contract.md`
+- custom component guide: `dynamic-fields-inline-filter-custom-component-guide.md`
+- troubleshooting: `dynamic-fields-inline-filter-troubleshooting.md`
+
+Regra editorial:
+
+- `praxis-table` documenta a **feature de filtro**
+- `praxis-dynamic-fields` documenta os **componentes inline** que a feature consome
+
+As secoes detalhadas abaixo continuam como referencia de UX/metadata, mas a trilha governada passa a ser a suite acima.
+
+## Pré-requisitos
+
+- Host Angular com `praxis-filter` e `@praxisui/dynamic-fields` integrados.
+- Conhecimento basico de `controlType`, metadata de campos e requisitos de acessibilidade.
+
+## Padrões obrigatórios
+
+1. Estados visuais consistentes:
+   - `empty`: label do campo exibido no próprio pill (nunca texto cru).
+   - `filled`: valor exibido com hierarquia visual clara.
+   - `focus`: foco acompanha o shape do pill.
+   - `disabled/readonly`: contraste e interação coerentes.
+
+2. Layout:
+   - Campos compactos (`inline*`, formato canônico) ficam na faixa `compact-fields` (flex).
+   - Campos não compactos seguem na `fields-grid`.
+   - Evitar largura fixa em componentes compactos; usar `min/max` responsivos.
+
+3. Overlay/Popover:
+   - Arredondamento superior e inferior preservado.
+   - `overflow: hidden` no painel e no `overlay-pane` quando necessário.
+   - Largura controlada por `min/max` para não ficar “full-width”.
+   - Ao fechar, limpar termo de busca temporário do popover para evitar “lista vazia” na reabertura.
+
+   - Controles inline package-owned devem preservar contraste via tokens internos
+     `--pdx-inline-field-*` e `--pdx-inline-panel-*`, evitando depender de overrides
+     globais de `.mat-mdc-form-field` ou `.mat-mdc-select-panel` do host.
+
+4. Fonte de label:
+   - Prioridade: `label` -> `metadata.label` -> `placeholder` -> `metadata.placeholder` -> `name` humanizado -> fallback.
+
+5. Acessibilidade:
+   - `aria-label` sempre disponível.
+   - Placeholder visual custom deve ser `aria-hidden`.
+   - Botões de limpar com `aria-label`.
+   - Foco visual visível em dark/light theme.
+
+6. Regra de clear button (corporativo):
+   - Controles inline respeitam `metadata.clearButton` (`enabled`, `showOnlyWhenFilled`).
+   - Para manter UX de pill compacta sem configuração manual em cada schema, o `praxis-filter` aplica default `clearButton={ enabled: true, showOnlyWhenFilled: true }` para:
+     `inlineSelect`, `inlineSearchableSelect`, `inlineAsyncSelect`, `inlineEntityLookup`,
+     `inlineAutocomplete`, `inlineMultiSelect`, `inlineInput`, `inlineNumber`,
+     `inlineCurrency`, `inlineCurrencyRange`, `inlineToggle`, `inlineRange`,
+     `inlinePeriodRange`, `inlineYearRange`, `inlineMonthRange`,
+     `inlineDate`, `inlineDateRange`, `inlineTime`, `inlineTimeRange`,
+     `inlineTreeSelect`, `inlineRating`, `inlineDistanceRadius`,
+     `inlinePipelineStatus`, `inlineScorePriority`.
+   - Para `inlineRelativePeriod`, `inlineSentiment` e `inlineColorLabel`, defina
+     `metadata.clearButton` explicitamente quando quiser quick clear.
+   - Fora da lista acima, o default corporativo de quick clear não é aplicado automaticamente.
+
+Exemplo mínimo (quick clear explícito para os 3 inline especiais):
+
+```json
+{
+  "controlType": "inlineRelativePeriod",
+  "clearButton": {
+    "enabled": true,
+    "showOnlyWhenFilled": true
+  }
+}
+```
+
+7. Tooltip contextual (corporativo):
+   - Quando `validators.errorPosition = "tooltip"` e existe erro, o tooltip mostra a mensagem de validação.
+   - Sem erro, campos inline preenchidos exibem contexto no formato `Campo: valor`.
+   - É possível desabilitar por campo com `inlineContextTooltip: false` (ou `{ "enabled": false }`).
+
+## Mapa atual
+
+- `inlineSelect`: listas compactas em pill + popover.
+- `inlineSearchableSelect`: variante inline dedicada para `searchable-select`, mantendo preload de selecionados, busca remota e paginação.
+- `inlineAsyncSelect`: variante inline dedicada para `async-select`, com busca remota, cursor/paginação e placeholder em pill quando vazio.
+  - Quando a fonte remota vier de `x-ui.optionSource.type = CATEGORICAL_BUCKET`, o runtime passa a assumir `loadOn = "init"` e esconde a busca por padrão, mantendo opt-in explícito via `metadata.searchable = true` quando o host realmente precisar de pesquisa textual.
+- `inlineEntityLookup`: variante inline corporativa para lookup de entidades (`id + descrição`), com busca por id/descrição e atalho de reset no popover.
+- `inlineAutocomplete`: autocomplete compacto em pill, com busca incremental e lista em popover arredondado.
+- `inlineNumber`: número compacto em pill, com validação `min/max`, clear e largura adaptativa. Em `numericFormat/format = percent`, renderiza sufixo `%` e defaults corporativos (`min=0`, `max=100`, `step=0.01`) quando não informados. O visual gráfico enriquecido fica sob opt-in explícito com `inlineVisualStyle = "graphic"`, preservando o modo compacto como padrão corporativo.
+- `inlineCurrency`: moeda compacta em pill, com máscara, locale/moeda configuráveis e clear.
+- `inlineCurrencyRange`: faixa monetária compacta em pill, com slider duplo em popover e resumo `min-max`.
+- `inlineMultiSelect`: listas múltiplas compactas em pill + popover, exibindo tokens selecionados com overflow `+N` e seção de selecionados no painel.
+- `inlineInput`: texto compacto com ícone de busca, clear, largura adaptativa e mascara de
+  display para campos textuais semanticamente conhecidos (CPF/CNPJ, telefone BR/E.164 e CEP),
+  preservando o valor cru enviado ao filtro.
+- `inlineToggle`: toggle booleano compacto em pill, com `clear` para voltar a estado neutro (`null`).
+- `inlineRange`: chip compacto + popover com slider, suportando `rangeSlider` em modo `single` e `range`, inputs numéricos opcionais (`showInputs`), labels/marks declarativos, value labels, histograma/distribuição e presets rápidos (`quickPresets` / `quickPresetsAuto`).
+- `inlinePeriodRange`: faixa temporal compacta por granularidade, cobrindo `month`, `quarter`, `year` e `fiscal-year` com chip e presets específicos por período.
+- `inlineYearRange`: alias compatível para `inlinePeriodRange` com `granularity: 'year'`.
+- `inlineMonthRange`: alias compatível para `inlinePeriodRange` com `granularity: 'month'`.
+- `inlineDate`: datepicker compacto em pill, com largura automática por conteúdo e placeholder inline.
+- `inlineDateRange`: intervalo de datas compacto em pill, com largura adaptativa por conteúdo.
+- `inlineTime`: timepicker compacto em pill, com largura adaptativa por conteúdo e modos `list|columns|auto`.
+- `inlineTimeRange`: intervalo de horário compacto em pill, com validações de faixa reutilizando o componente base.
+- `inlineTreeSelect`: tree select compacto em pill, com busca no popover e seleção hierárquica de nó único.
+- `inlineRating`: rating inline (explícito por `controlType`) com escala e tons configuráveis.
+- `inlineDistanceRadius`: distância/raio inline (explícito por `controlType`) com unidade e anéis.
+- `inlinePipelineStatus`: status de pipeline inline (explícito por `controlType`) com cards e barra segmentada.
+- `inlineScorePriority`: score/prioridade inline (explícito por `controlType`) com bandas e escala.
+- `inlineRelativePeriod`: período relativo inline (explícito por `controlType`) com presets e progresso.
+- `inlineSentiment`: sentimento inline (explícito por `controlType`) com paleta e seleção rápida.
+- `inlineColorLabel`: etiquetas por cor inline (explícito por `controlType`) com badges e seleção.
+
+Compatibilidade de mapeamento no `praxis-filter`:
+
+- Para novos schemas, use `controlType` no formato canônico `inline*`.
+- `select` -> `inlineSelect`.
+- `searchable-select` -> `inlineSearchableSelect` por padrão (desative via `useInlineSearchableSelectVariant=false` quando o host precisar do renderer dedicado).
+- `async-select` -> `inlineAsyncSelect` por padrão com a mesma regra de opt-out: `useInlineSearchableSelectVariant=false`.
+- `entityLookup` -> `inlineEntityLookup` por configuração explícita no `controlType`.
+- `autoComplete` / `autocomplete` -> `inlineAutocomplete` por padrão com a mesma regra de opt-out: `useInlineSearchableSelectVariant=false`.
+- `numericTextBox` -> `inlineNumber`.
+- `currency` -> `inlineCurrency`.
+- `priceRange` -> `inlineCurrencyRange`.
+- `year + mode=range` -> `inlinePeriodRange` com `granularity: 'year'` por padrão quando a toolbar compacta estiver ativa.
+- `month + mode=range` -> `inlinePeriodRange` com `granularity: 'month'` por padrão quando a toolbar compacta estiver ativa.
+- `multiSelect` -> `inlineMultiSelect`.
+- `date/dateInput/datepicker` -> `inlineDate` por padrão (desative via `useInlineDateVariant=false`).
+- `dateRange/daterange` -> `inlineDateRange` por padrão (desative via `useInlineDateRangeVariant=false`).
+- `time/timeInput/timePicker` -> `inlineTime` por padrão (desative via `useInlineTimeVariant=false`).
+- `timeRange` -> `inlineTimeRange` por padrão (desative via `useInlineTimeRangeVariant=false`).
+- `treeSelect` -> `inlineTreeSelect` por padrão (desative via `useInlineTreeSelectVariant=false`).
+- `inlineRating`, `inlineDistanceRadius`, `inlinePipelineStatus`, `inlineScorePriority`,
+  `inlineRelativePeriod`, `inlineSentiment`, `inlineColorLabel` ficam inline por `controlType` explícito.
+- `multiSelectTree` permanece no componente dedicado para preservar semântica de seleção múltipla.
+
+Observação técnica importante:
+
+- No `mat-select`, o `mat-select-trigger` customizado não é renderizado quando o campo está vazio.
+- Por isso, o estado `empty` do `inlineSelect` e do `inlineSearchableSelect` deve ser estilizado no branch de placeholder do Material (`.mat-mdc-select-placeholder`) para manter o visual de badge/pill.
+
+Regra de curadoria enterprise:
+
+- componentes da familia `graphic specialized` sao `opt-in` explicito por schema
+- eles nunca devem virar default implicito por promocao automatica do `praxis-filter`
+- a promocao automatica deve ficar restrita a controles universais e previsiveis, como select, input, date e range
+
+Critério visual e acessível para `graphic specialized`:
+
+- A metáfora gráfica só deve ser usada quando reduz esforço de decisão: fluxo operacional real, severidade, prioridade, distribuição, tendência ou faixa com significado de negócio.
+- Se a visualização apenas deixa um enum mais decorativo, use `inlineSelect`, `inlineMultiSelect`, `inlineRange` ou `inlineCurrencyRange`.
+- O chip preenchido deve mostrar texto suficiente para leitura sem abrir o popover. O padrão esperado é `label + value`, por exemplo `Pipeline Qualified +1` ou `Risco Critical +1`.
+- Cor, ícone, estrela, emoji, barra ou banda nunca podem ser o único canal de significado. Toda opção precisa de label textual, `aria-label` coerente e contraste AA.
+- O painel deve oferecer modo compacto legível: quantidade controlada de opções, wrap previsível, foco visível e seleção identificável sem depender apenas de cor.
+- Em `inlinePipelineStatus`, a barra segmentada precisa representar etapas reais do processo. Quando o usuário precisa comparar apenas rótulos, use o modo text-first (`pipelineShowBar=false`).
+- Em `inlineColorLabel`, `inlineSentiment`, `inlineScorePriority` e `inlineRating`, mantenha texto visível no resumo e nas opções; use paleta apenas como reforço semântico.
+- Para dashboards corporativos com muitas colunas ou toolbar densa, documente um preset ou metadata de fallback: `density`, `inlineAutoSize`, `colorLabelColumns`, `pipelineChipMaxVisible`, `pipelineShowBar=false` ou clear button explícito.
+
+Tiers de densidade recomendados:
+
+- `core compact`: `inlineInput`, `inlineSelect`, `inlineSearchableSelect`, `inlineAsyncSelect`, `inlineEntityLookup`, `inlineAutocomplete`, `inlineNumber`, `inlineCurrency`, `inlineRange`, `inlineCurrencyRange`, `inlineDate`, `inlineDateRange`, `inlineTime`, `inlineTimeRange`, `inlineToggle`, `inlinePeriodRange`
+- `advanced compact`: `inlineMultiSelect`, `inlineTreeSelect`
+- `graphic specialized`: `inlinePipelineStatus`, `inlineRelativePeriod`, `inlineRating`, `inlineDistanceRadius`, `inlineScorePriority`, `inlineSentiment`, `inlineColorLabel`
+
+Heuristicas de curadoria:
+
+- `inlineTreeSelect` continua suportado como promocao inline, mas deve ser usado apenas para arvores rasas, selecao de no unico e leitura final curta
+- quando o usuario precisa explorar varios ramos para descobrir o valor correto, a experiencia apropriada deixa de ser a toolbar compacta
+- `inlineRelativePeriod` so deve ser escolhido quando a API e a trilha metadata-driven normalizam presets relativos de forma canonica; caso contrario, prefira `inlineDateRange`
+- a familia `graphic specialized` deve entrar por decisao consciente de produto, nao por entusiasmo visual ou disponibilidade do componente
+
+## Matriz de contrato inline (enterprise)
+
+Esta seção formaliza o contrato único de metadata para todos os inline do `praxis-filter`:
+
+- `campo`: nome da propriedade de metadata.
+- `tipo`: `editorType` definido no metadata editor (`text`, `number`, `checkbox`, `select`, `textarea`, `color`).
+- `default`: valor aplicado em runtime quando o campo não vem no payload.
+- `runtime support`: componentes que efetivamente consomem o campo.
+
+### Guia de uso da matriz
+
+1. Escolha o `controlType` inline.
+2. Use a coluna `Matriz base` para os campos compartilhados.
+3. Aplique os campos da coluna `Extensões específicas` quando o inline for especializado.
+4. Para ícones de painel/opção, use os campos de `Ícones` da matriz correspondente (todos metadata-driven).
+5. Para novos contratos, prefira sempre `controlType` canônico (`inline*`).
+
+### Matriz por inline (base + extensão)
+
+| Inline / ControlType     | Matriz base              | Extensões específicas                      | Default runtime                                                                          | Runtime support                                            |
+| ------------------------ | ------------------------ | ------------------------------------------ | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| `inlineSelect`           | `select.config.ts`       | —                                          | label/placeholder com fallback para `name`; busca opcional; clear respeita `clearButton` | `registrado por default no runtime inline`                 |
+| `inlineSearchableSelect` | `select.config.ts`       | —                                          | busca local/remota e paginação                                                           | `registrado por default no runtime inline`                 |
+| `inlineAsyncSelect`      | `select.config.ts`       | —                                          | busca remota sob demanda + paginação                                                     | `registrado por default no runtime inline`                 |
+| `inlineEntityLookup`     | `select.config.ts`       | —                                          | modo lookup com reset no painel                                                          | `registrado por default no runtime inline`                 |
+| `inlineAutocomplete`     | `select.config.ts`       | —                                          | comportamento de select-like inline                                                      | `registrado por default no runtime inline`                 |
+| `inlineMultiSelect`      | `select.config.ts`       | —                                          | seleção múltipla com tokens compactos, overflow `+N` e selecionados no painel            | `registrado por default no runtime inline`                 |
+| `inlineInput`            | `input.config.ts`        | —                                          | auto width por conteúdo                                                                  | `registrado por default no runtime inline`                 |
+| `inlineNumber`           | `number.config.ts`       | —                                          | formatação numérica e `%` quando configurado                                             | `registrado por default no runtime inline`                 |
+| `inlineCurrency`         | `currency.config.ts`     | —                                          | máscara monetária por locale                                                             | `registrado por default no runtime inline`                 |
+| `inlineCurrencyRange`    | `price-range.config.ts`  | —                                          | slider + inputs + resumo monetário                                                       | `registrado por default no runtime inline`                 |
+| `inlineToggle`           | `toggle.config.ts`       | —                                          | estado neutro com clear opcional                                                         | `registrado por default no runtime inline`                 |
+| `inlineRange`            | `range-slider.config.ts` | —                                          | single/range com presets                                                                 | `registrado por default no runtime inline`                 |
+| `inlinePeriodRange`      | `range-slider.config.ts` | `extensão temporal genérica co-localizada` | granularidades `month`, `quarter`, `year`, `fiscal-year`                                 | `registrado por default no runtime inline`                 |
+| `inlineYearRange`        | `range-slider.config.ts` | `alias compatível de inlinePeriodRange`    | converte para `granularity: 'year'`                                                      | `compatível; prefira inlinePeriodRange em contratos novos` |
+| `inlineMonthRange`       | `range-slider.config.ts` | `alias compatível de inlinePeriodRange`    | converte para `granularity: 'month'`                                                     | `compatível; prefira inlinePeriodRange em contratos novos` |
+| `inlineDate`             | `date.config.ts`         | —                                          | datepicker inline com auto width                                                         | `registrado por default no runtime inline`                 |
+| `inlineDateRange`        | `date-range.config.ts`   | —                                          | presets + modo `auto/confirm`                                                            | `registrado por default no runtime inline`                 |
+| `inlineTime`             | `time-picker.config.ts`  | —                                          | modo `auto/list/columns`; toggle e selected icon metadata-driven                         | `registrado por default no runtime inline`                 |
+| `inlineTimeRange`        | `time-range.config.ts`   | —                                          | faixa de horário com validações                                                          | `registrado por default no runtime inline`                 |
+| `inlineTreeSelect`       | `tree-select.config.ts`  | —                                          | busca em árvore + seleção de nó                                                          | `registrado por default no runtime inline`                 |
+| `inlineRating`           | `range-slider.config.ts` | `extensão especializada co-localizada`     | rating por faixa com tons e ícones de badge/estrelas metadata-driven                     | `registrado por default no runtime inline`                 |
+| `inlineDistanceRadius`   | `range-slider.config.ts` | `extensão especializada co-localizada`     | distância com unidade e anéis                                                            | `registrado por default no runtime inline`                 |
+| `inlinePipelineStatus`   | `select.config.ts`       | `extensão especializada co-localizada`     | cards + barra segmentada + busca                                                         | `registrado por default no runtime inline`                 |
+| `inlineScorePriority`    | `range-slider.config.ts` | `extensão especializada co-localizada`     | score bands e escala                                                                     | `registrado por default no runtime inline`                 |
+| `inlineRelativePeriod`   | `select.config.ts`       | `extensão especializada co-localizada`     | presets de período com progresso                                                         | `registrado por default no runtime inline`                 |
+| `inlineSentiment`        | `select.config.ts`       | `extensão especializada co-localizada`     | opções de sentimento com palette                                                         | `registrado por default no runtime inline`                 |
+| `inlineColorLabel`       | `select.config.ts`       | `extensão especializada co-localizada`     | etiquetas por cor com badges                                                             | `registrado por default no runtime inline`                 |
+
+### Campos completos por matriz (todos os campos inline)
+
+Fonte de verdade: `projects/praxis-metadata-editor/src/lib/config/*.config.ts`.
+
+### Matriz de ícones inline (campo, tipo, default, aliases reconhecidos, runtime support)
+
+| Campo                             | Tipo    | Default runtime                  | Aliases reconhecidos                                               | Runtime support                                                                                                              |
+| --------------------------------- | ------- | -------------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
+| `panelSearchIcon`                 | `text`  | `search`                         | `searchIcon`, `inlineSearchIcon`                                   | `inlineSelect`, `inlineSearchableSelect`, `inlineAsyncSelect`, `inlineMultiSelect`, `inlineEntityLookup`, `inlineTreeSelect` |
+| `panelSearchIconColor`            | `color` | `undefined`                      | `searchIconColor`, `inlineSearchIconColor`                         | mesmos componentes acima                                                                                                     |
+| `panelResetIcon`                  | `text`  | `restart_alt`                    | `resetIcon`, `inlineResetIcon`                                     | `inlineEntityLookup`                                                                                                         |
+| `panelResetIconColor`             | `color` | `undefined`                      | `resetIconColor`, `inlineResetIconColor`                           | `inlineEntityLookup`                                                                                                         |
+| `optionSelectedIcon`              | `text`  | `done` (`check` no `inlineTime`) | `selectedIcon`, `checkIcon`                                        | `inlineTime`, `inlineColorLabel`, `inlineRelativePeriod`                                                                     |
+| `optionSelectedIconColor`         | `color` | `undefined`                      | `selectedIconColor`, `checkIconColor`                              | `inlineTime`, `inlineColorLabel`, `inlineRelativePeriod`                                                                     |
+| `panelToggleOpenIcon`             | `text`  | `expand_less`                    | `toggleOpenIcon`                                                   | `inlineTime`, `inlineTreeSelect`                                                                                             |
+| `panelToggleCloseIcon`            | `text`  | `expand_more`                    | `panelToggleClosedIcon`, `toggleCloseIcon`                         | `inlineTime`, `inlineTreeSelect`                                                                                             |
+| `panelToggleIconColor`            | `color` | `undefined`                      | `toggleIconColor`                                                  | `inlineTime`, `inlineTreeSelect`                                                                                             |
+| `treeNodeExpandedIcon`            | `text`  | `expand_more`                    | `nodeExpandedIcon`                                                 | `inlineTreeSelect`                                                                                                           |
+| `treeNodeCollapsedIcon`           | `text`  | `chevron_right`                  | `nodeCollapsedIcon`                                                | `inlineTreeSelect`                                                                                                           |
+| `treeNodeIconColor`               | `color` | `undefined`                      | `nodeToggleIconColor`                                              | `inlineTreeSelect`                                                                                                           |
+| `pipelineSearchIcon`              | `text`  | `search`                         | `panelSearchIcon`, `searchIcon`, `inlineSearchIcon`                | `inlinePipelineStatus`                                                                                                       |
+| `pipelineSearchIconColor`         | `color` | `undefined`                      | `panelSearchIconColor`, `searchIconColor`, `inlineSearchIconColor` | `inlinePipelineStatus`                                                                                                       |
+| `colorLabelSelectedIcon`          | `text`  | `done`                           | `optionSelectedIcon`, `selectedIcon`, `checkIcon`                  | `inlineColorLabel`                                                                                                           |
+| `colorLabelSelectedIconColor`     | `color` | `undefined`                      | `optionSelectedIconColor`, `selectedIconColor`, `checkIconColor`   | `inlineColorLabel`                                                                                                           |
+| `relativePeriodSelectedIcon`      | `text`  | `done`                           | `optionSelectedIcon`, `selectedIcon`, `checkIcon`                  | `inlineRelativePeriod`                                                                                                       |
+| `relativePeriodSelectedIconColor` | `color` | `undefined`                      | `optionSelectedIconColor`, `selectedIconColor`, `checkIconColor`   | `inlineRelativePeriod`                                                                                                       |
+
+#### `select.config.ts`
+
+`label, defaultValue, placeholder, hint, prefix, suffix, prefixIcon, prefixIconColor, suffixIcon, suffixIconColor, panelSearchIcon, panelSearchIconColor, panelResetIcon, panelResetIconColor, optionSelectedIcon, optionSelectedIconColor, options, emptyOptionText, multiple, optionLabelKey, optionValueKey, lookupIdKey, lookupLabelKey, lookupSubtitleKey, resourcePath, loadOn, filterCriteria, dependencyFields, resetOnDependentChange, enableDependencyCascade, dependencyFilterMap, dependencyValuePath, dependencyMergeStrategy, dependencyDebounceMs, dependencyLoadOnChange, selectAll, searchable, searchPlaceholder, maxSelections, required, validators.requiredMessage, clearButton.enabled, clearButton.icon, clearButton.iconColor, clearButton.tooltip, clearButton.ariaLabel, clearButton.showOnlyWhenFilled, materialDesign.appearance, materialDesign.color, materialDesign.floatLabel, materialDesign.subscriptSizing, inlineAutoSize.minWidth, inlineAutoSize.maxWidth, inlineAutoSize.minWidthMobile, inlineAutoSize.maxWidthMobile, materialDesign.hideRequiredMarker, errorStateMatcher, ariaLabel, ariaDescribedby, ariaLabelledby, tabIndex, dataAttributes`
+
+#### `input.config.ts`
+
+`label, placeholder, hint, prefixIcon, prefixIconColor, suffixIcon, suffixIconColor, prefix, suffix, showCharacterCount, required, minLength, maxLength, pattern, validators.requiredMessage, validators.minLengthMessage, validators.maxLengthMessage, validators.patternMessage, mask, textTransform, textTransformApply, autocomplete, spellcheck, disabled, readonly, inputMode, autoFocus, inputType, validators.validationTrigger, validators.validationDebounce, validators.showInlineErrors, validators.errorPosition, materialDesign.appearance, materialDesign.color, materialDesign.floatLabel, materialDesign.subscriptSizing, inlineAutoSize.minWidth, inlineAutoSize.maxWidth, inlineAutoSize.minWidthMobile, inlineAutoSize.maxWidthMobile, materialDesign.hideRequiredMarker, errorStateMatcher, disabledInteractive, clearButton.enabled, clearButton.icon, clearButton.iconColor, clearButton.tooltip, clearButton.ariaLabel, clearButton.showOnlyWhenFilled, ariaLabel, ariaDescribedby, ariaLabelledby, tabIndex, dataAttributes, defaultValue`
+
+#### `number.config.ts`
+
+`label, placeholder, defaultValue, hint, prefix, suffix, prefixIcon, prefixIconColor, suffixIcon, suffixIconColor, step, numberFormat.decimalPlaces, showGrouping, inputMode, autocomplete, spellcheck, readonly, disabled, autoFocus, validators.validationTrigger, validators.validationDebounce, validators.showInlineErrors, validators.errorPosition, required, min, max, validators.requiredMessage, validators.minMessage, validators.maxMessage, clearButton.enabled, clearButton.icon, clearButton.iconColor, clearButton.tooltip, clearButton.ariaLabel, clearButton.showOnlyWhenFilled, materialDesign.appearance, materialDesign.color, materialDesign.floatLabel, materialDesign.subscriptSizing, inlineAutoSize.minWidth, inlineAutoSize.maxWidth, inlineAutoSize.minWidthMobile, inlineAutoSize.maxWidthMobile, materialDesign.hideRequiredMarker, errorStateMatcher, ariaLabel, ariaDescribedby, ariaLabelledby, tabIndex, dataAttributes`
+
+#### `currency.config.ts`
+
+`label, defaultValue, placeholder, hint, prefix, suffix, prefixIcon, prefixIconColor, suffixIcon, suffixIconColor, currency, currencyPosition, decimalPlaces, locale, allowNegative, thousandsSeparator, decimalSeparator, readonly, disabled, autoFocus, required, min, max, validators.requiredMessage, validators.minMessage, validators.maxMessage, materialDesign.appearance, materialDesign.color, inlineAutoSize.minWidth, inlineAutoSize.maxWidth, inlineAutoSize.minWidthMobile, inlineAutoSize.maxWidthMobile, ariaLabel, ariaDescribedby, ariaLabelledby, clearButton.enabled, clearButton.icon, clearButton.iconColor, clearButton.tooltip, clearButton.ariaLabel, clearButton.showOnlyWhenFilled`
+
+#### `date.config.ts`
+
+`label, defaultValue, placeholder, hint, prefixIcon, prefixIconColor, suffixIcon, suffixIconColor, prefix, suffix, required, minDate, maxDate, validators.requiredMessage, validators.minMessage, validators.maxMessage, startView, startAt, touchUi, closeOnSelect, materialDesign.appearance, materialDesign.color, materialDesign.floatLabel, materialDesign.subscriptSizing, inlineAutoSize.minWidth, inlineAutoSize.maxWidth, inlineAutoSize.minWidthMobile, inlineAutoSize.maxWidthMobile, materialDesign.hideRequiredMarker, errorStateMatcher, ariaLabel, ariaDescribedby, ariaLabelledby, tabIndex, dataAttributes, clearButton.enabled, clearButton.icon, clearButton.iconColor, clearButton.tooltip, clearButton.ariaLabel, clearButton.showOnlyWhenFilled`
+
+#### `date-range.config.ts`
+
+`label, hint, startPlaceholder, endPlaceholder, defaultValue.startDate, defaultValue.endDate, prefixIcon, prefixIconColor, suffixIconColor, suffixIcon, startView, startAt, touchUi, required, minDate, maxDate, validators.requiredMessage, materialDesign.appearance, materialDesign.color, materialDesign.floatLabel, materialDesign.subscriptSizing, inlineAutoSize.minWidth, inlineAutoSize.maxWidth, inlineAutoSize.minWidthMobile, inlineAutoSize.maxWidthMobile, materialDesign.hideRequiredMarker, errorStateMatcher, startAriaLabel, endAriaLabel, tabIndex, dataAttributes, showShortcuts, shortcutsPosition, applyOnShortcutClick, shortcuts, inlineQuickPresets.enabled, inlineQuickPresets.maxVisible, inlineQuickPresetsAriaLabel, inlineQuickPresetsApplyMode, inlineQuickPresetsCancelLabel, inlineQuickPresetsCancelAriaLabel, inlineQuickPresetsApplyLabel, inlineQuickPresetsApplyAriaLabel, clearButton.enabled, clearButton.icon, clearButton.iconColor, clearButton.tooltip, clearButton.ariaLabel, clearButton.showOnlyWhenFilled`
+
+#### `time-picker.config.ts`
+
+`label, defaultValue, hint, prefixIcon, prefixIconColor, suffixIcon, suffixIconColor, panelToggleCloseIcon, panelToggleOpenIcon, panelToggleIconColor, optionSelectedIcon, optionSelectedIconColor, timeOptions, interval, inlineTimeMode, inlineListMaxOptions, openOnClick, touchUi, format, showSeconds, stepMinute, stepSecond, timeFilter, inlineTexts.hourLabel, inlineTexts.minuteLabel, inlineTexts.secondLabel, inlineTexts.emptyStateLabel, inlineTexts.openPanelAriaLabel, inlineTexts.closePanelAriaLabel, required, min, max, validators.requiredMessage, materialDesign.appearance, materialDesign.color, materialDesign.density, inlineAutoSize.minWidth, inlineAutoSize.maxWidth, inlineAutoSize.minWidthMobile, inlineAutoSize.maxWidthMobile, ariaLabel, ariaDescribedby, ariaLabelledby, clearButton.enabled, clearButton.icon, clearButton.iconColor, clearButton.tooltip, clearButton.ariaLabel, clearButton.showOnlyWhenFilled`
+
+#### `time-range.config.ts`
+
+`label, inlinePanelTitle, startLabel, endLabel, defaultValue.start, defaultValue.end, hint, prefixIcon, prefixIconColor, suffixIcon, suffixIconColor, step, stepMinute, minTime, maxTime, showTicks, inlineTimeQuickPresets, inlineTimeTrackShifts, touchUi, readonly, disabled, autoFocus, required, min, max, validators.requiredMessage, materialDesign.appearance, materialDesign.color, inlineAutoSize.minWidth, inlineAutoSize.maxWidth, inlineAutoSize.minWidthMobile, inlineAutoSize.maxWidthMobile, ariaLabel, ariaDescribedby, ariaLabelledby, clearButton.enabled, clearButton.icon, clearButton.iconColor, clearButton.tooltip, clearButton.ariaLabel, clearButton.showOnlyWhenFilled`
+
+#### `tree-select.config.ts`
+
+`label, hint, prefixIcon, prefixIconColor, panelSearchIcon, panelSearchIconColor, panelToggleCloseIcon, panelToggleOpenIcon, panelToggleIconColor, treeNodeExpandedIcon, treeNodeCollapsedIcon, treeNodeIconColor, options, searchable, searchPlaceholder, emptyStateText, leafOnly, autoExpandOnSearch, returnPath, returnObject, required, validators.requiredMessage, clearButton.enabled, clearButton.icon, clearButton.iconColor, clearButton.tooltip, clearButton.ariaLabel, clearButton.showOnlyWhenFilled, inlineAutoSize.minWidth, inlineAutoSize.maxWidth, inlineAutoSize.minWidthMobile, inlineAutoSize.maxWidthMobile, ariaLabel, ariaDescribedby, ariaLabelledby, tabIndex, dataAttributes`
+
+#### `toggle.config.ts`
+
+`label, defaultValue, hint, labelPosition, inlineLabelVisible, hideIcon, disableRipple, readonly, disabled, autoFocus, clearButton.enabled, clearButton.icon, clearButton.iconColor, clearButton.tooltip, clearButton.ariaLabel, clearButton.showOnlyWhenFilled, requiredTrue, validators.requiredTrueMessage, color, ariaLabel, ariaDescribedby, ariaLabelledby`
+
+#### `range-slider.config.ts`
+
+`label, hint, prefixIcon, prefixIconColor, suffixIcon, suffixIconColor, mode, step, thumbLabel, showTicks, discrete, vertical, invert, displayWith, showInputs, quickPresets, quickPresetsAuto, quickPresetsLabels, inlineTexts, min, max, minDistance, maxDistance, validators.minMessage, validators.maxMessage, validators.rangeMessage, validators.distanceMessage, required, validators.requiredMessage, clearButton.enabled, clearButton.icon, clearButton.iconColor, clearButton.tooltip, clearButton.ariaLabel, clearButton.showOnlyWhenFilled, color, inlineAutoSize.minWidth, inlineAutoSize.maxWidth, inlineAutoSize.minWidthMobile, inlineAutoSize.maxWidthMobile, inlineAutoSize.panelMinWidth, inlineAutoSize.panelMaxWidth, inlineAutoSize.panelMinWidthMobile, inlineAutoSize.panelMaxWidthMobile, ariaLabel, ariaDescribedby, ariaLabelledby, tabIndex`
+
+#### `price-range.config.ts`
+
+`label, hint, tooltip, inlinePanelTitle, startLabel, endLabel, prefixIcon, prefixIconColor, suffixIcon, suffixIconColor, startPlaceholder, endPlaceholder, defaultValue.minPrice, defaultValue.maxPrice, hideSubLabels, layout, gap, clearButtonPlacement, required, readonly, disabled, hidden, min, max, startMin, startMax, startMinMessage, startMaxMessage, endMin, endMax, endMinMessage, endMaxMessage, endMinOffset, endMinOffsetMessage, startMaxOffset, startMaxOffsetMessage, step, showTicks, currency, currencyPosition, decimalPlaces, locale, thousandsSeparator, decimalSeparator, allowNegative, clearButton.enabled, clearButton.icon, clearButton.iconColor, clearButton.tooltip, clearButton.ariaLabel, clearButton.showOnlyWhenFilled, materialDesign.appearance, materialDesign.color, inlineAutoSize.minWidth, inlineAutoSize.maxWidth, inlineAutoSize.minWidthMobile, inlineAutoSize.maxWidthMobile, inlineAutoSize.panelMinWidth, inlineAutoSize.panelMaxWidth, ariaLabel, ariaDescribedby, ariaLabelledby`
+
+#### Matrizes especializadas (incrementais)
+
+- `inlineRating`:
+  `ratingIcon, allowHalf, ratingAllowHalf, ratingPrecision, precision, ratingToneLowColor, ratingToneMidColor, ratingToneHighColor, ratingBadgeColor, ratingBadgeIcon, ratingBadgeIconColor, ratingActiveIcon, ratingInactiveIcon, ratingToneColors, ratingColors, starColors, ratingLowColor, ratingMidColor, ratingHighColor, ratingIndicatorColor, ratingMin, ratingMax, itemsCount, ratingStep, materialDesign.density`
+- `inlineDistanceRadius`:
+  `distanceIcon, distanceSubtitle, distanceUnit, distanceBaseUnit, distanceAllowUnitToggle, distanceUnits, distanceUnitLabels.km, distanceUnitLabels.mi, distanceDisplayDecimals, distancePresets, distanceRadialRings, distanceAccentColor, distanceRingColor, distanceTrackColor, distanceGlowColor, materialDesign.density`
+- `inlinePipelineStatus`:
+  `pipelineSubtitle, pipelineOptions, pipelineSearchable, pipelineSearchPlaceholder, pipelineOptionSubtitleKey, pipelineOptionWeightKey, pipelineOptionColorKey, pipelineShowBar, pipelineShowSelectionPills, pipelineShowSelectAll, pipelineSelectAllText, pipelineShowClearAction, pipelineClearActionText, pipelineChipMaxVisible, pipelineColors, pipelineEmptyStateText, pipelineSelectionActionsAriaLabel, pipelineOptionsGroupAriaLabelMultiple, pipelineOptionsGroupAriaLabelSingle, pipelineSelectionPillsAriaLabel, pipelineBarAriaLabelEmpty, pipelineBarAriaLabelSelected, pipelineTexts, pipelineIcon, pipelineSearchIcon, pipelineSearchIconColor, inlineAutoSize.panelMinWidth, inlineAutoSize.panelMaxWidth, inlineAutoSize.panelMinWidthMobile, inlineAutoSize.panelMaxWidthMobile`
+- `inlineScorePriority`:
+  `scoreSubtitle, scoreBands, scoreUnit, scoreDisplayDecimals, scoreShowScaleLabels, scoreShowBandChips, scoreRangeSeparator, scorePalette, scoreValueFallbackColor, scoreEmptyGradient, scoreIcon, scoreBandsAriaLabel, scoreBandAriaLabelTemplate, scoreTexts, scoreMin, scoreMax, scoreStep, priorityBands, severityBands, materialDesign.density`
+- `inlineRelativePeriod`:
+  `relativePeriodSubtitle, relativePeriodOptions, relativePeriodPresets, relativePeriodShowProgress, relativePeriodColumns, relativePeriodCloseOnSelect, relativePeriodMultiple, relativePeriodSearchable, relativePeriodIcon, relativePeriodIconKey, relativePeriodSubtitleKey, relativePeriodOptionsAriaLabel, relativePeriodProgressEmptyLabel, relativePeriodEmptyStateText, relativePeriodTexts, inlineAutoSize.panelMinWidth, inlineAutoSize.panelMaxWidth, inlineAutoSize.panelMinWidthMobile, inlineAutoSize.panelMaxWidthMobile`
+- `inlineSentiment`:
+  `sentimentSubtitle, sentimentOptions, sentimentPalette, sentimentShowBar, sentimentAnimatedEmoji, sentimentCloseOnSelect, sentimentMultiple, sentimentShowSelectionPills, sentimentIcon, sentimentColorKey, sentimentEmojiKey, sentimentOptionsAriaLabel, sentimentSelectionPillsAriaLabel, sentimentEmptyStateText, sentimentTexts, inlineAutoSize.panelMinWidth, inlineAutoSize.panelMaxWidth, inlineAutoSize.panelMinWidthMobile, inlineAutoSize.panelMaxWidthMobile`
+- `inlineColorLabel`:
+  `colorLabelSubtitle, colorLabelOptions, colorLabelPalette, colorLabelMultiple, colorLabelColumns, colorLabelShowSelectedBadges, colorLabelCloseOnSelect, colorLabelSelectionTitle, colorLabelIcon, colorLabelBadgeRemoveIcon, colorLabelBadgeRemoveIconColor, colorLabelColorKey, colorLabelOptionsAriaLabel, colorLabelSelectionBadgesAriaLabel, colorLabelRemoveSelectionAriaLabel, colorLabelEmptyStateText, colorLabelTexts, inlineAutoSize.panelMinWidth, inlineAutoSize.panelMaxWidth, inlineAutoSize.panelMinWidthMobile, inlineAutoSize.panelMaxWidthMobile`
+
+## Auto Width (input inline)
+
+`inlineInput` agora redimensiona por conteúdo (valor atual ou label quando vazio), com limites por densidade:
+
+- `compact`: menor largura mínima, foco em economia de espaço.
+- `comfortable`: padrão mais amplo.
+- `dense`: ainda mais compacto para cenários de alta densidade.
+
+Override opcional por metadata:
+
+```json
+{
+  "controlType": "inlineInput",
+  "density": "compact",
+  "inlineAutoSize": {
+    "minWidth": 112,
+    "maxWidth": 300,
+    "minWidthMobile": 104,
+    "maxWidthMobile": 236
+  }
+}
+```
+
+`inlineSelect` usa o mesmo envelope de min/max por densidade/viewport (pill vazio e preenchido), mantendo largura por conteúdo para o texto selecionado.
+`inlineAsyncSelect` segue o mesmo envelope adaptativo de largura e mantém label como placeholder visual quando vazio.
+`inlineAutocomplete` também usa auto-width por conteúdo (valor/label), mantendo foco no shape pill e clear alinhado.
+`inlineNumber` segue o mesmo envelope adaptativo de largura, usando valor numérico atual ou label como fallback quando vazio.
+No modo percentual (`numericFormat` ou `format` com valor `percent`), mantém o mesmo layout inline e exibe sufixo `%`, preservando overrides explícitos de `min/max/step`.
+`inlineCurrency` segue envelope adaptativo (`inlineAutoSize`) com máscara de moeda e símbolo antes/depois conforme metadata (`currencyPosition`).
+`inlineCurrencyRange` segue envelope adaptativo (`inlineAutoSize`) no chip e popover, com escala e resumo monetário formatados.
+`inlineEntityLookup` usa envelope adaptativo (`inlineAutoSize`) com faixa padrão maior para comportar `id + descrição`.
+`inlineRange` usa envelope adaptativo de largura (`inlineAutoSize`) no chip e no popover para evitar bloco fixo largo quando usado na barra compacta.
+`inlineDate` também usa envelope adaptativo (`inlineAutoSize`) e calcula a largura pelo valor exibido ou label do campo quando vazio.
+`inlineDateRange` segue o mesmo princípio (`inlineAutoSize`) e usa o resumo do período para calcular largura.
+`inlineTime` usa envelope adaptativo (`inlineAutoSize`) e calcula a largura com base no horário exibido.
+No modo `inlineTimeMode: "auto"`:
+
+- usa `list` quando o conjunto de horários é pequeno (ou `timeOptions` explícitas);
+- usa `columns` para cenários de alta densidade/precisão (ex.: segundos).
+
+Convenções importantes para contrato corporativo:
+
+- `interval` numérico é tratado em **segundos**.
+- para minutos/horas, prefira string com unidade (`"15m"`, `"1h"`).
+- Exemplo rápido de equivalência:
+  - `{ "controlType": "inlineTime", "interval": 900 }` -> 900s (15 minutos)
+  - `{ "controlType": "inlineTime", "interval": "15m" }` -> equivalente (recomendado por legibilidade)
+- para i18n do inline, use `inlineTexts.*` (`hourLabel`, `minuteLabel`, `secondLabel`, `emptyStateLabel`, labels aria).
+  `inlineTimeRange` usa envelope adaptativo (`inlineAutoSize`) e calcula a largura pelo resumo `inicio - fim`.
+  `inlineTreeSelect` usa envelope adaptativo (`inlineAutoSize`) com faixa maior para rótulos hierárquicos.
+  Para `inlineDateRange`, `inlineQuickPresetsApplyMode` define o contrato:
+- `auto`: preset aplica imediatamente e fecha overlay.
+- `confirm`: preset fica em rascunho no overlay; só `Aplicar` comita no valor final e `Cancelar` descarta.
+
+Exemplo rápido para `inlineRange` com presets automáticos:
+
+```json
+{
+  "controlType": "inlineRange",
+  "mode": "range",
+  "min": 0,
+  "max": 15000,
+  "step": 500,
+  "showInputs": true,
+  "quickPresetsAuto": true,
+  "quickPresetsLabels": {
+    "uptoMid": "Faixa baixa",
+    "fromMid": "Faixa alta",
+    "full": "Faixa completa"
+  },
+  "inlineTexts": {
+    "minLabel": "De",
+    "maxLabel": "Até",
+    "quickPresetsLabel": "Sugestões"
+  }
+}
+```
+
+## Diretriz corporativa (catálogos remotos)
+
+- Catálogo pequeno/médio: pode usar `inlineSelect` com busca local.
+- Catálogo grande/remoto: prefira `searchable-select` dedicado (load sob demanda, paginação, preload de selecionados).
+- Catálogo grande/remoto com UX de toolbar compacta: `inlineAsyncSelect` agora é o padrão; faça opt-out via `useInlineSearchableSelectVariant=false` se o host precisar preservar o renderer dedicado após validação de performance.
+- Em cenários corporativos com paginação remota, latência alta ou busca pesada, trate `useInlineSearchableSelectVariant=false` como escape hatch suportado, não como exceção ad hoc.
+- Quando habilitado, o componente inline dedicado limpa o termo de busca ao fechar o popover e reabre com estado consistente.
+
+## Backlog enterprise recomendado
+
+Prioridade alta (próximo ciclo):
+
+- Hardening de teclado/a11y no `inlineTreeSelect` para fluxos avançados.
+- Monitorar via testes a consistência dos recipes AI inline e do catálogo canônico (`INLINE_FILTER_CONTROL_TYPES`).
+
+## Checklist de design review
+
+Antes de aprovar um inline novo na toolbar, confirme:
+
+- o estado vazio usa label semantico do campo, nao copy generica
+- o estado preenchido continua inteligivel sem abrir o popover
+- a escolha do componente reduz interacoes, nao apenas enriquece o visual
+- o DTO final do backend continua obvio para frontend, QA e observabilidade
+- existe plano de fallback para filtro avancado quando a densidade real da interacao crescer
+
+Checklist especifico para `advanced compact` e `graphic specialized`:
+
+- `inlineTreeSelect`: a arvore e rasa, a selecao e unica e o rotulo final cabe na toolbar
+- `inlineRelativePeriod`: a trilha metadata-driven normaliza presets relativos para payload canonicamente auditavel
+- `inlinePipelineStatus`: a metafora de pipeline representa um fluxo operacional real, nao um enum ornamental
+- `inlineColorLabel`, `inlineSentiment`, `inlineRating`, `inlineScorePriority`: a leitura final nao depende apenas de cor, icone ou estilo grafico
+
+## Overrides de metadata para `alwaysVisibleFields`
+
+Para cenários corporativos em que o mesmo campo precisa de comportamento diferente no modo inline (sempre visível), use:
+
+- `advancedFilters.settings.alwaysVisibleFieldMetadataOverrides`
+- Chave: `name` do campo no DTO de filtro
+- Valor: patch parcial de metadata aplicado **após** os defaults inline do `praxis-filter`
+
+Exemplo:
+
+```json
+{
+  "behavior": {
+    "filtering": {
+      "advancedFilters": {
+        "enabled": true,
+        "settings": {
+          "alwaysVisibleFields": ["status", "recompensa"],
+          "alwaysVisibleFieldMetadataOverrides": {
+            "status": {
+              "label": "Situação",
+              "clearButton": { "enabled": false }
+            },
+            "recompensa": {
+              "controlType": "inlineRange",
+              "inlineAutoSize": { "minWidth": 188, "maxWidth": 280 },
+              "min": 0,
+              "max": 5000,
+              "step": 50
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Precedência efetiva:
+
+- DTO de filtro (backend) -> defaults inline do `praxis-filter` -> `alwaysVisibleFieldMetadataOverrides`
+
+Fallback corporativo para DTO sem `controlType`:
+
+- O `praxis-filter` agora infere tipo mínimo para renderização de always-visible:
+  - `options` -> `select`/`multiSelect`
+  - `dataType=boolean` -> `toggle`
+  - demais casos -> `input`
+- Isso evita perda de renderização quando o backend envia schema com `type`, mas sem `x-ui.controlType`.
+
+UX no editor de tabela:
+
+- Na aba `Filtros -> Sempre Visíveis`, há um editor visual por campo sempre visível (abrindo o `FieldMetadataEditor` da plataforma).
+- Cada card exibe tipo de controle efetivo, status de override e resumo das propriedades customizadas.
+- O modo JSON continua disponível para ajustes em lote e propriedades avançadas.
+- As ações de JSON são locais ao editor (`Validar e carregar no editor` / `Carregar JSON no formulário`) e não persistem sozinhas.
+- Persistência final acontece no rodapé do painel (`Salvar & Fechar`).
+- A ordenação de campos sempre visíveis usa um **layout composer** com 3 faixas alinhadas ao runtime:
+  - `Faixa de ações` (toggles quando `placeBooleansInActions=true`)
+  - `Barra inline` (pills compactas com wrap)
+  - `Grid de campos` (controles não compactos)
+- O composer inclui simulação de viewport (`Desktop`, `Tablet`, `Mobile`) para prever quebras reais de linha no toolbar.
+- Reordenação ocorre por faixa com drag-and-drop e fallback de teclado (`Alt/Ctrl + setas`), sem mistura entre faixas.
+- Navegação rápida (`Ordem`, `Metadados`, `JSON`) destaca automaticamente a seção ativa durante rolagem/foco e usa `aria-current="location"` para leitores de tela.
+- As seções possuem `scroll-margin-top` para não ficarem ocultas atrás do bloco sticky de contexto.
+- Motion segue WCAG/Nielsen: entrada suave por seção em ambiente padrão e fallback sem animação para `prefers-reduced-motion`.
+
+## Contrato do Showcase Inline (filtro + tabela local)
+
+No exemplo `Showcase inline com metadados estáticos` (`/filter-demo`), o contrato de filtro local foi consolidado para uso enterprise:
+
+- Salário:
+  - `salarioMinimo` filtra pelo campo `row.salarioMinimo` (limite inferior).
+  - `salarioPretendido` filtra pelo campo `row.salarioPretendido` (limite superior).
+- Janela de atendimento:
+  - `janelaAtendimento` usa sobreposição de intervalo (`[start,end]` do filtro vs `[start,end]` da linha), não igualdade com `horarioEntrada`.
+- Datas:
+  - strings `YYYY-MM-DD` são parseadas em calendário local para evitar deslocamento de dia por timezone.
+- A11y/WCAG:
+  - contador visual de linhas/filtros não usa `role=status` contínuo.
+  - live region dedicada (sr-only, `aria-live="polite"`) anuncia resultado somente após submissão.
+  - conflito temporal (`periodoRelativo` combinado com data/período absoluto) exibe aviso explícito.
+
+Para E2E visual em CI, a configuração Playwright do filtro suporta servidor gerenciado:
+
+- `PLAYWRIGHT_USE_WEB_SERVER=1` habilita `webServer` no config.
+- `PLAYWRIGHT_WEB_SERVER_COMMAND` permite sobrescrever o comando de subida.
+- `PLAYWRIGHT_BASE_URL` define URL alvo do teste.
+
+## Definition of Done (DoD)
+
+- Typecheck sem erros.
+- Estado vazio mostra label no pill.
+- Foco segue o shape do componente.
+- Popover mantém bordas arredondadas top/bottom.
+- Componente não cria gaps horizontais excessivos na barra.
+- Teste de registro no `ComponentRegistryService`.
+- Campos com `hidden/formHidden` não podem reservar espaço no layout (host colapsado).
+- `Aplicar` no filtro avançado deve usar o estado atual do `FormGroup`, mesmo sem evento `valueChange`.