--- 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"`, mas é reduzido ao pill compacto quando renderizado dentro de `praxis-filter` compacto para preservar densidade, ritmo e legibilidade da barra. - `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, resumo `min-max`, ticks/marks semânticos compactos, bands opcionais, histograma/distribuição, readout adaptativo para evitar colisão de valores longos e confirmação explícita por `Aplicar`/`Cancelar`. - `inlineMultiSelect`: listas múltiplas compactas em pill + popover, exibindo tokens selecionados com overflow `+N`, seção de selecionados no painel e confirmação explícita por `inlineOverlay` quando necessário. - `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, placeholder inline e confirmação explícita opcional via `inlineOverlay`. - `inlineDateRange`: intervalo de datas compacto em pill, com largura adaptativa por conteúdo. Em barras corporativas densas, toda a área acionável do chip deve abrir o calendário, inclusive o texto de início/fim; o `clearButton` é a única ação isolada para limpar sem abrir o overlay. - `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`; campos `multiple=true` continuam emitindo arrays e permanecem compactos na toolbar. - `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 + `inlineOverlay` opcional | `registrado por default no runtime inline` | | `inlineDateRange` | `date-range.config.ts` | — | presets + `inlineOverlay.applyMode` | `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, inlineOverlay.applyMode, inlineOverlay.actions.apply.label, inlineOverlay.actions.apply.ariaLabel, inlineOverlay.actions.apply.appearance, inlineOverlay.actions.apply.colorRole, inlineOverlay.actions.cancel.label, inlineOverlay.actions.cancel.ariaLabel, inlineOverlay.actions.cancel.appearance, inlineOverlay.actions.cancel.colorRole, 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, inlineOverlay.applyMode, inlineOverlay.actions.apply.label, inlineOverlay.actions.apply.ariaLabel, inlineOverlay.actions.apply.appearance, inlineOverlay.actions.apply.colorRole, inlineOverlay.actions.cancel.label, inlineOverlay.actions.cancel.ariaLabel, inlineOverlay.actions.cancel.appearance, inlineOverlay.actions.cancel.colorRole, inlineOverlay.actions.clear.label, inlineOverlay.actions.clear.ariaLabel, inlineOverlay.actions.clear.appearance, inlineOverlay.actions.clear.colorRole, 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, marks, semanticBands, currency, currencyPosition, decimalPlaces, locale, thousandsSeparator, decimalSeparator, allowNegative, clearButton.enabled, clearButton.icon, clearButton.iconColor, clearButton.tooltip, clearButton.ariaLabel, clearButton.showOnlyWhenFilled, inlineOverlay.applyMode, inlineOverlay.actions.apply.label, inlineOverlay.actions.apply.ariaLabel, inlineOverlay.actions.apply.appearance, inlineOverlay.actions.apply.colorRole, inlineOverlay.actions.cancel.label, inlineOverlay.actions.cancel.ariaLabel, inlineOverlay.actions.cancel.appearance, inlineOverlay.actions.cancel.colorRole, inlineOverlay.actions.clear.label, inlineOverlay.actions.clear.ariaLabel, inlineOverlay.actions.clear.appearance, inlineOverlay.actions.clear.colorRole, 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, inlineOverlay.applyMode, inlineOverlay.actions.apply.label, inlineOverlay.actions.cancel.label, inlineOverlay.actions.clear.label, materialDesign.density` - `inlineDistanceRadius`: `distanceIcon, distanceSubtitle, distanceUnit, distanceBaseUnit, distanceAllowUnitToggle, distanceUnits, distanceUnitLabels.km, distanceUnitLabels.mi, distanceDisplayDecimals, distancePresets, distanceRadialRings, distanceAccentColor, distanceRingColor, distanceTrackColor, distanceGlowColor, inlineOverlay.applyMode, inlineOverlay.actions.apply.label, inlineOverlay.actions.cancel.label, inlineOverlay.actions.clear.label, inlineOverlay.actions.clear.appearance, inlineOverlay.actions.clear.colorRole, materialDesign.density` - `inlinePipelineStatus`: `pipelineSubtitle, pipelineOptions, pipelineSearchable, pipelineSearchPlaceholder, pipelineOptionSubtitleKey, pipelineOptionWeightKey, pipelineOptionColorKey, pipelineShowBar, pipelineShowSelectionPills, pipelineShowSelectAll, pipelineSelectAllText, pipelineShowClearAction, pipelineClearActionText, inlineOverlay.applyMode, inlineOverlay.actions.apply.label, inlineOverlay.actions.cancel.label, inlineOverlay.actions.clear.label, inlineOverlay.actions.clear.appearance, inlineOverlay.actions.clear.colorRole, 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, inlineOverlay.applyMode, inlineOverlay.actions.apply.label, inlineOverlay.actions.cancel.label, inlineOverlay.actions.clear.label, inlineOverlay.actions.clear.appearance, inlineOverlay.actions.clear.colorRole, materialDesign.density` - `inlineRelativePeriod`: `relativePeriodSubtitle, relativePeriodOptions, relativePeriodPresets, relativePeriodShowProgress, relativePeriodColumns, relativePeriodCloseOnSelect, relativePeriodMultiple, relativePeriodSearchable, relativePeriodIcon, relativePeriodIconKey, relativePeriodSubtitleKey, relativePeriodOptionsAriaLabel, relativePeriodProgressEmptyLabel, relativePeriodEmptyStateText, relativePeriodTexts, inlineOverlay.applyMode, inlineOverlay.actions.apply.label, inlineOverlay.actions.apply.ariaLabel, inlineOverlay.actions.apply.appearance, inlineOverlay.actions.apply.colorRole, inlineOverlay.actions.cancel.label, inlineOverlay.actions.cancel.ariaLabel, inlineOverlay.actions.cancel.appearance, inlineOverlay.actions.cancel.colorRole, inlineOverlay.actions.clear.label, inlineOverlay.actions.clear.ariaLabel, inlineOverlay.actions.clear.appearance, inlineOverlay.actions.clear.colorRole, inlineAutoSize.panelMinWidth, inlineAutoSize.panelMaxWidth, inlineAutoSize.panelMinWidthMobile, inlineAutoSize.panelMaxWidthMobile` - `inlineSentiment`: `sentimentSubtitle, sentimentOptions, sentimentPalette, sentimentShowBar, sentimentAnimatedEmoji, sentimentCloseOnSelect, sentimentMultiple, sentimentShowSelectionPills, sentimentIcon, sentimentColorKey, sentimentEmojiKey, sentimentOptionsAriaLabel, sentimentSelectionPillsAriaLabel, sentimentEmptyStateText, sentimentTexts, inlineOverlay.applyMode, inlineOverlay.actions.apply.label, inlineOverlay.actions.cancel.label, inlineOverlay.actions.clear.label, inlineOverlay.actions.clear.appearance, inlineOverlay.actions.clear.colorRole, 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, inlineOverlay.applyMode, inlineOverlay.actions.apply.label, inlineOverlay.actions.cancel.label, inlineOverlay.actions.clear.label, inlineOverlay.actions.clear.appearance, inlineOverlay.actions.clear.colorRole, 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 } } ``` ### Política canônica de commit para overlays inline `inlineOverlay` é o contrato canônico para painéis inline editáveis. Ele não deve ser substituído por contratos locais como `confirm`, `commitPolicy` ou labels isolados por componente. | Classe de interação | Componentes típicos | Modo recomendado | Regra UX | | --- | --- | --- | --- | | Campo direto sem painel composto | `inlineInput`, `inlineNumber`, `inlineCurrency`, `inlineToggle` | Sem `inlineOverlay` | Alteração aplica imediatamente; `Cancelar`/`Aplicar` adicionaria fricção sem reduzir erro. | | Seleção simples conclusiva | `inlineSelect`, `inlineSearchableSelect`, `inlineAsyncSelect`, `inlineAutocomplete`, `inlineTreeSelect`, `inlineTime` | `auto` ou sem `inlineOverlay` | Escolher uma opção aplica o filtro; `Esc` e clique externo apenas fecham o painel. | | Seleção múltipla, range, presets ou painel exploratório | `inlineMultiSelect`, `inlineRange`, `inlineCurrencyRange`, `inlineRating`, `inlineDistanceRadius`, `inlineScorePriority`, `inlinePipelineStatus`, `inlineRelativePeriod`, `inlineSentiment`, `inlineColorLabel`, `inlineDate`, `inlineDateRange`, `inlineTimeRange` | `explicit` quando houver rascunho real; `auto` quando a interação for filtro rápido | Em `explicit`, alterações ficam em rascunho; `Aplicar` comita; `Cancelar`, `Esc` e fechamento externo restauram o valor confirmado anterior. | | Lookup com dialog real | `inlineEntityLookup` | Semântica de dialog | `Cancelar` fecha sem alterar a seleção confirmada; a ação primária do dialog comita e o foco retorna ao trigger. | O vocabulário público de `inlineOverlay.applyMode` é `auto | explicit`. Componentes podem tolerar aliases legados em runtime para compatibilidade, mas documentação, exemplos e authoring visual devem emitir `explicit` para fluxos com `Aplicar`/`Cancelar`. `Limpar` não é sinônimo de `Cancelar`: no trigger/pill, limpa diretamente o valor aplicado; dentro de um painel `explicit`, deve limpar o rascunho e só virar valor final quando o usuário acionar `Aplicar`, salvo contrato específico documentado pelo componente. `inlineSelect` usa o mesmo envelope de min/max por densidade/viewport (pill vazio e preenchido), mantendo largura por conteúdo para o texto selecionado. `inlineMultiSelect` também usa o envelope adaptativo e, com `inlineOverlay.applyMode: "explicit"`, mantém seleção, remoção e limpeza do painel em rascunho até `Aplicar`; `Cancelar`, `Esc` ou fechamento externo restauram a seleção confirmada anterior. Labels, aria, `appearance` e `colorRole` das ações do rodapé devem vir de `inlineOverlay.actions.*`. O `inlineSelect` single ainda comita no clique por herdar o comportamento nativo do `mat-select`; confirmação explícita ali exige uma superfície de painel própria para não fechar ao selecionar. `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. No painel, o resumo completo é a leitura principal da faixa selecionada; os valores junto ao slider são usados apenas como orientação quando não duplicam a seleção ativa. `marks` materializa até três labels compactos e ativa ticks; `semanticBands` projeta faixas de significado no trilho; `distribution/rangeDistribution/histogram` continua sendo a camada para comparação com população real. Por padrão, alterações feitas no painel ficam em rascunho até `Aplicar`; `Cancelar`, `Esc` ou fechamento externo descartam o rascunho, e `Limpar` remove o filtro explicitamente. Labels, aria, `appearance`, `colorRole` e ícones dessas ações devem vir de `inlineOverlay.actions.*` e materializar tokens do tema. Quando `inlineOverlay.applyMode: "auto"` for explicitado, o slider comita durante a interação e a ação de cancelar deixa de ser exibida. `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. Por padrao, altera em modo `auto` para preservar filtros rápidos; com `inlineOverlay.applyMode: "explicit"`, slider, inputs e presets ficam em rascunho até `Aplicar`, enquanto `Cancelar`, `Esc` ou fechamento externo descartam o rascunho. Labels, aria, `appearance` e `colorRole` dos botoes devem vir de `inlineOverlay.actions.*` e materializar tokens do tema, nao CSS ad hoc. `inlineRating` usa o mesmo contrato `inlineOverlay` para fluxos em que explorar estrelas, inputs ou presets nao deve alterar o filtro aplicado imediatamente. Em `applyMode: "explicit"`, o painel exibe `Aplicar`, `Cancelar` e `Limpar`; a escala visual acompanha o rascunho e o valor final so muda no commit. `inlineDistanceRadius` usa o mesmo contrato `inlineOverlay` quando a decisao de UX exigir confirmacao: em `applyMode: "explicit"`, slider radial e presets ficam em rascunho ate `Aplicar`; `Cancelar`, `Esc` e fechamento externo descartam a alteracao. O modo default continua imediato para preservar filtros de raio rapidos. `inlinePipelineStatus` usa `inlineOverlay` quando mudanças de etapa/status precisam ser revisadas antes de afetar o filtro aplicado. Em `applyMode: "explicit"`, cards, selecionar todos e limpar seleção alteram apenas o rascunho do painel; `Aplicar` comita, enquanto `Cancelar`, `Esc` e fechamento externo restauram a seleção anterior. Labels, aria, `appearance`, `colorRole` e ícones das ações finais devem vir de `inlineOverlay.actions.*`. `inlineRelativePeriod` usa `inlineOverlay` quando presets temporais precisam ser explorados sem alterar imediatamente o filtro aplicado. Em `applyMode: "explicit"`, cards de período e progresso visual acompanham apenas o rascunho; `Aplicar` comita o preset, enquanto `Cancelar`, `Esc` e fechamento externo restauram a seleção anterior. Labels, aria, `appearance`, `colorRole` e ícones devem ser authorados em `inlineOverlay.actions.*`. `inlineScorePriority` usa `inlineOverlay` para cenarios em que score, prioridade ou bandas de risco nao devem comitar durante a exploracao. Em `applyMode: "explicit"`, slider e chips de bandas ficam em rascunho ate `Aplicar`; `Cancelar`, `Esc` e fechamento externo restauram a selecao anterior. Os botoes devem ser authorados em `inlineOverlay.actions.*` para respeitar labels, aria, `appearance`, `colorRole` e tokens do tema. `inlineColorLabel` usa `inlineOverlay` quando a seleção de etiquetas precisa ser revisada antes de alterar o filtro aplicado. Em `applyMode: "explicit"`, cards e badges alteram apenas o rascunho; `Aplicar` comita a seleção, enquanto `Cancelar`, `Esc` ou fechamento externo descartam a exploração. `inlineSentiment` usa `inlineOverlay` quando a escolha visual de humor, polaridade ou satisfação precisa ser revisada antes de afetar o filtro aplicado. Em `applyMode: "explicit"`, cards e barra visual acompanham o rascunho; `Aplicar` comita e `Cancelar`, `Esc` ou fechamento externo descartam. `inlineDate` também usa envelope adaptativo (`inlineAutoSize`) e calcula a largura pelo valor exibido ou label do campo quando vazio. Com `inlineOverlay.applyMode: "explicit"`, o calendário nativo exibe `Aplicar` e `Cancelar`; a data escolhida fica em rascunho até o commit, e labels/aria/`appearance`/`colorRole` vêm de `inlineOverlay.actions.*`. `inlineDateRange` segue o mesmo princípio (`inlineAutoSize`) e usa o resumo do período para calcular largura. Em `inlineOverlay.applyMode: "explicit"`, o rodapé de `Aplicar` e `Cancelar` deve aparecer mesmo sem atalhos rápidos, para que a confirmação explícita não dependa da presença de presets. `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`. Com `inlineOverlay.applyMode: "explicit"`, slider, inputs manuais e presets ficam em rascunho até `Aplicar`; `Cancelar`, `Esc` e fechamento externo restauram o valor confirmado anterior. Labels, aria, `appearance`, `colorRole` e ícones das ações finais devem vir de `inlineOverlay.actions.*`. `inlineTreeSelect` usa envelope adaptativo (`inlineAutoSize`) com faixa maior para rótulos hierárquicos. Para `inlineDateRange`, o contrato compartilhado é `inlineOverlay.applyMode`: - `auto`: preset ou calendário aplica imediatamente e fecha overlay quando a interação for conclusiva. - `explicit`: preset ou calendário fica em rascunho no overlay; só `Aplicar` comita no valor final e `Cancelar` descarta. - `inlineQuickPresetsApplyMode` continua como compatibilidade específica do date-range e é interpretado depois de `inlineOverlay.applyMode`. - Labels, aria, `appearance` e `colorRole` dos botões `Aplicar` e `Cancelar` devem vir de `inlineOverlay.actions.*`; os campos `inlineQuickPresets*Label` são fallback legado. - O trigger preenchido deve permanecer previsível em uso corporativo: clique no ícone, no texto ou no espaço interno da pill abre o calendário; clique no clear remove o valor e não abre o calendário. 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. - Customização visual: - `clearButton.iconColor` deve ser respeitado mesmo quando o inline estiver dentro do host compacto do `praxis-filter`. - Componentes inline que renderizam clear/close devem propagar a cor resolvida para `--pdx-inline-clear-icon-color` no próprio botão de limpeza. - Hosts compactos podem estilizar tamanho, fundo e hover dos clear buttons, mas devem manter `color: var(--pdx-inline-clear-icon-color, currentColor)` para não descartar a customização feita no metadata editor. - `inlineCurrency` deve manter formatação localizada após `Salvar & Fechar` no metadata editor, incluindo o caso de round-trip com `decimalPlaces` vazio. 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`.