@praxisui/dynamic-fields 9.0.0-beta.8 → 9.0.0-beta.80

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,11 +324,11 @@ 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`
 
-`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`
+`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, inlineQuickPresets.position, 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`
 
@@ -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.
@@ -435,6 +451,8 @@ Convenções importantes para contrato corporativo:
 - `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.
+- `shortcuts` aceita ids built-in, presets TypeScript com `calculateRange()` e `StaticDateRangePreset` serializável com `startDate`/`endDate` resolvidos pelo domínio. O runtime nunca executa regra de negócio recebida por JSON.
+- `inlineQuickPresets.position` aceita `auto`, `footer`, `start` e `end`; `start`/`end` são posições lógicas e voltam para `footer` em viewport estreito ou `touchUi`.
 - 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:
@@ -575,6 +593,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-catalog.md

@@ -340,10 +340,27 @@ Para hosts oficiais:
 - Snippet:
 
 ```json
-{ "name": "period", "controlType": "inlineDateRange", "showShortcuts": true }
+{
+  "name": "period",
+  "controlType": "inlineDateRange",
+  "showShortcuts": true,
+  "shortcuts": [
+    "today",
+    {
+      "id": "periodo-votacao-2026",
+      "label": "Periodo de votacao 2026",
+      "startDate": "2026-07-06",
+      "endDate": "2026-10-04",
+      "timeZone": "America/Sao_Paulo",
+      "tone": "info"
+    }
+  ],
+  "inlineQuickPresets": { "enabled": true, "maxVisible": 4, "position": "auto" }
+}
 ```
 
 - UX note: shortcuts nao podem mascarar o shape final enviado ao backend
+- Domain note: periodos corporativos chegam resolvidos por metadata; o frontend nao calcula regras eleitorais, fiscais, juridicas, feriados ou dias contaveis.
 - Docs relacionadas: `dynamic-filter-range-filters-guide`
 
 ### <span id="inline-time"></span>`inlineTime`

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`