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

package/docs/dynamic-fields-field-catalog.md

@@ -27,7 +27,6 @@ reading_time: 24
 estimated_setup_time: 30
 version: "1.0"
 related_docs:
-  - "dynamic-fields-overview"
   - "dynamic-fields-inventory"
   - "dynamic-fields-field-selection-guide"
   - "dynamic-fields-host-custom-field-guide"
@@ -180,7 +179,7 @@ Use `stateInitialValues` apenas quando o valor do preset precisa continuar coere
 
 | Field         | controlType                                   | Quando usar                                                                                           | Quando evitar                                    | Valor esperado                | Snippet                                                                         | Detail doc                                |
 | ------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------ | ----------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------- |
-| Checkbox      | <span id="checkbox"></span>`checkbox`         | booleano simples com `selectionMode: 'boolean'` ou multiplas escolhas com `selectionMode: 'multiple'` | contrato novo sem `selectionMode`; escolha unica | `boolean \| unknown[]`        | `{ name: 'privacyConsent', controlType: 'checkbox', selectionMode: 'boolean' }` | `pdx-material-checkbox-group.json-api.md` |
+| Checkbox      | <span id="checkbox"></span>`checkbox`         | booleano simples com `selectionMode: 'boolean'` ou múltiplas escolhas com `selectionMode: 'multiple'`; em migrações, flags `S`/`N` e `1`/`0` são normalizadas no modo booleano | contrato novo sem `selectionMode`; escolha única | `boolean \| unknown[]`        | `{ name: 'privacyConsent', controlType: 'checkbox', selectionMode: 'boolean' }` | `pdx-material-checkbox-group.json-api.md` |
 | Radio group   | <span id="radio"></span>`radio`               | escolha unica explicita com `selectionMode: 'single'`                                                 | muitas opcoes/espaco restrito                    | `string \| number \| boolean` | `{ name: 'priority', controlType: 'radio', selectionMode: 'single' }`           | `pdx-material-radio-group.json-api.md`    |
 | Toggle        | <span id="toggle"></span>`toggle`             | booleano binario                                                                                      | multiplos estados                                | `boolean`                     | `{ name: 'active', controlType: 'toggle' }`                                     | `pdx-material-slide-toggle.json-api.md`   |
 | Button toggle | <span id="buttontoggle"></span>`buttonToggle` | escolha segmentada curta                                                                              | listas longas                                    | `string \| number`            | `{ name: 'mode', controlType: 'buttonToggle' }`                                 | `pdx-material-button-toggle.json-api.md`  |
@@ -189,7 +188,7 @@ Use `stateInitialValues` apenas quando o valor do preset precisa continuar coere
 
 | Field       | controlType                       | Quando usar         | Quando evitar                    | Valor esperado               | Snippet                                         | Detail doc                             |
 | ----------- | --------------------------------- | ------------------- | -------------------------------- | ---------------------------- | ----------------------------------------------- | -------------------------------------- |
-| File upload | <span id="upload"></span>`upload` | anexos e documentos | quando o fluxo nao exige arquivo | `File \| File[] \| metadata` | `{ name: 'attachment', controlType: 'upload' }` | `pdx-material-file-upload.json-api.md` |
+| File upload | <span id="upload"></span>`upload` | anexos, documentos e escolha local de imagem com preview | quando o fluxo nao exige arquivo ou exige persistencia operacional completa sem `@praxisui/files-upload` | `File \| File[] \| metadata` | `{ name: 'attachment', controlType: 'upload', accept: 'image/*', imagePreview: true }` | `pdx-material-file-upload.json-api.md` |
 
 ## Cor
 

package/docs/dynamic-fields-field-selection-guide.md

@@ -37,7 +37,7 @@ keywords:
   - "select vs autocomplete"
   - "custom host field"
   - "inline filter"
-last_updated: "2026-06-01"
+last_updated: "2026-06-25"
 ---
 
 # Dynamic Fields Field Selection Guide
@@ -187,7 +187,29 @@ Se o caso e filtro corporativo compacto, consulte:
 - [Dynamic Fields Inline Filter Catalog](./dynamic-fields-inline-filter-catalog.md)
 - [Dynamic Fields Inline Components Guide](./dynamic-fields-inline-components-guide.md)
 
-## 6. Decision table
+## 6. Presentation mode vs chart widget
+
+`presentation.presenter = 'microVisualization'` nao e um `controlType`. Use esse presenter quando o campo ja tem valor no `FormControl`, mas a surface readonly precisa mostrar um indicador compacto e escaneavel.
+
+Use `microVisualization` quando:
+
+- a surface e `form-presentation`, `table-cell`, `list-item`, `object-header` ou `card-summary`;
+- a leitura precisa caber em celula, linha, drawer ou detalhe compacto;
+- o indicador e pequeno, como `comparison`, `stackedBar`, `bullet` ou `delta`;
+- a mesma semantica deve ser dirigida por `presentationRules` e Json Logic sem mutar o valor do campo.
+
+Use `@praxisui/charts` quando:
+
+- o usuario precisa interagir com grafico, legenda, tooltip analitico ou drilldown;
+- o grafico ocupa card, dashboard, cockpit ou modal dedicado;
+- a visualizacao depende de series maiores, eixos, zoom ou agregacoes vindas de endpoint analitico.
+
+Use `rich-content` quando:
+
+- o bloco mistura timeline, record summary, property sheet, progresso, badges e textos;
+- a surface de detalhe precisa composicao editorial, nao apenas um valor de campo.
+
+## 7. Decision table
 
 | Question | Prefer |
 | --- | --- |
@@ -211,12 +233,14 @@ Se o caso e filtro corporativo compacto, consulte:
 | ha uma colecao repetivel de objetos? | `array` |
 | ha anexos? | `upload` |
 | o controle e acao, nao dado? | `button` |
+| o valor readonly precisa de indicador compacto em celula/lista/formulario? | `presentation.presenter = "microVisualization"` |
 | nada do catalogo resolve sem gambiarra? | field custom do host |
 
-## 7. Enterprise recommendations
+## 8. Enterprise recommendations
 
 - prefira nomes canonicos de `controlType`; deixe aliases apenas para compatibilidade;
 - nao use inline filter controls em formularios normais para “economizar espaco”;
+- nao crie `controlType` local para indicadores readonly; use `presentation.presenter` e `presentation.visualization` quando a semantica for de apresentacao;
 - para campos remotos, explicite origem de dados e comportamento de busca;
 - para entidades de negocio, use `entityLookup` com `optionSource.type = RESOURCE_ENTITY`, `byIds`, `dependsOn`, `dependencyFilterMap` e `selectionPolicy` quando a selecao depender de status, permissao ou contexto;
 - para colecoes repetiveis, use `array` com `array.itemSchema.fields` em vez de criar campos numerados como `item1`, `item2`, `item3`;

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

@@ -147,7 +147,7 @@ Exemplo mínimo (quick clear explícito para os 3 inline especiais):
   - 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.
+- `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.
@@ -308,15 +308,15 @@ Fonte de verdade: `projects/praxis-metadata-editor/src/lib/config/*.config.ts`.
 
 #### `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`
+`label, defaultValue, placeholder, hint, helpText, helpDisplay, helpInlineMaxLength, 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`
+`label, placeholder, hint, helpText, helpDisplay, helpInlineMaxLength, 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`
+`label, placeholder, defaultValue, hint, helpText, helpDisplay, helpInlineMaxLength, 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`
 
@@ -324,7 +324,7 @@ Fonte de verdade: `projects/praxis-metadata-editor/src/lib/config/*.config.ts`.
 
 #### `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`
+`label, defaultValue, placeholder, hint, helpText, helpDisplay, helpInlineMaxLength, 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`
 
@@ -344,7 +344,7 @@ Fonte de verdade: `projects/praxis-metadata-editor/src/lib/config/*.config.ts`.
 
 #### `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`
+`label, defaultValue, hint, helpText, helpDisplay, helpInlineMaxLength, 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`
 
@@ -394,6 +394,21 @@ Override opcional por metadata:
 }
 ```
 
+### 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.
@@ -403,6 +418,7 @@ No modo percentual (`numericFormat` ou `format` com valor `percent`), mantém o
 `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`.
+Em shells corporativos autenticados, como seletores globais de empresa, tenant ou órgão, `pdx-inline-entity-lookup` pode ser usado fora de `PraxisDynamicForm` com um `FormControl` externo e `initialMetadata` estático. Para fontes locais, informe `options`, `optionValueKey`, `optionLabelKey` e `loadOn: "open"`; o valor inicial do `FormControl` deve ser preservado sem disparar recarga remota nem reprocessamento contínuo de metadata. Hosts devem preferir uma referência estável de metadata, mas o runtime tolera recriação semântica equivalente para evitar loops de change detection em topbars.
 `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.
@@ -575,6 +591,11 @@ No exemplo `Showcase inline com metadados estáticos` (`/filter-demo`), o contra
   - 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:
 

package/docs/dynamic-fields-inline-filter-runtime-contract.md

@@ -129,6 +129,17 @@ Conclusao importante:
 
 ## Camada 4. shape do valor no front
 
+### 4.1. commit de overlay inline
+
+`inlineOverlay` é o contrato compartilhado para painéis inline que precisam separar rascunho visual de valor aplicado. O vocabulário público de `inlineOverlay.applyMode` é:
+
+- `auto`: cada interação conclusiva aplica imediatamente o valor no `FormGroup`; `Esc` e clique externo apenas fecham o painel.
+- `explicit`: alterações ficam em rascunho no painel; `Aplicar` comita o valor; `Cancelar`, `Esc` e fechamento externo restauram o valor confirmado anterior.
+
+Não criar contratos locais como `confirm`, `commitPolicy` ou botões hardcoded por componente. Labels, `ariaLabel`, `appearance`, `colorRole`, ícones e visibilidade de ações pertencem a `inlineOverlay.actions.apply`, `inlineOverlay.actions.cancel` e `inlineOverlay.actions.clear`.
+
+`Limpar` não é `Cancelar`: no trigger/pill é uma ação direta de remover o valor aplicado; dentro de um overlay `explicit`, deve limpar o rascunho e aguardar `Aplicar`, salvo contrato específico documentado pelo componente.
+
 ### Valores simples
 
 - texto: `string`