@praxisui/dynamic-fields 9.0.0-beta.0 → 9.0.0-beta.10

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.
@@ -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.
@@ -575,6 +590,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`