@praxisui/dynamic-fields 9.0.0-beta.4 → 9.0.0-beta.40

package/src/lib/components/inline-sentiment/pdx-inline-sentiment.json-api.md

@@ -7,7 +7,7 @@ document_kind: "json-api-canonical"
 reference_mode: "canonical"
 contract_format: "json"
 contract_source: "runtime-and-code"
-description: "Referencia canonica do contrato JSON do componente pdx-inline-sentiment."
+description: "Referência canônica do contrato JSON do componente pdx-inline-sentiment."
 category: "components"
 sub_category: "dynamic-fields"
 audience:
@@ -44,60 +44,60 @@ related_components:
 
 # pdx-inline-sentiment
 
-Este documento e a referencia canonica da API JSON de pdx-inline-sentiment.
+Este documento e a referência canônica da API JSON de pdx-inline-sentiment.
 
 ## Summary
 
-- Tipo documental: API reference canonica de contrato JSON.
+- Tipo documental: API reference canônica de contrato JSON.
 - Source of truth: runtime e codigo declarados no frontmatter.
-- Objetivo operacional: consulta rapida, auditavel e deterministica sob pressao.
+- Objetivo operacional: consulta rápida, auditável e determinística sob pressão.
 - Resumo funcional: Contrato JSON metadata-driven com comportamento definido por runtime e schema associado.
 
 ## Purpose and scope
 
-- O componente consome payload JSON metadata-driven e expoe comportamento runtime configuravel por contrato.
-- Esta referencia cobre contrato publico, classificacao de paths e semantica de cobertura (runtime/schema/editor).
-- Fora de escopo: quickstart, tutorial narrativo e notas arquiteturais que nao alteram contrato publico.
+- O componente consome payload JSON metadata-driven e expõe comportamento runtime configurável por contrato.
+- Esta referência cobre contrato público, classificação de paths e semântica de cobertura (runtime/schema/editor).
+- Fora de escopo: quickstart, tutorial narrativo e notas arquiteturais que não alteram contrato público.
 
-## Consulta rapida (obrigatorio)
+## Consulta rápida (obrigatorio)
 
 | Regra/tema | Observado | Canonico desejado | Status | Evidencia |
 | --- | --- | --- | --- | --- |
-| Component id | `pdx-inline-sentiment` | Manter ID canonico estavel e versionado por contrato | Active | frontmatter.component |
-| Primary contract source | `runtime-and-code` | Runtime, schema e docs devem permanecer rastreaveis | Partial | frontmatter.contract_source + source_of_truth |
-| Runtime coverage | `true` | Comportamentos runtime criticos devem ficar explicitamente verificados | Active | `projects/praxis-dynamic-fields/src/lib/components/inline-sentiment/inline-sentiment.component.ts`, `projects/praxis-dynamic-fields/src/lib/base/simple-base-select.component.ts` |
-| Schema/type coverage | `true` | Tipos e schema devem refletir paths publicos do contrato | Active | source_of_truth + Detailed API reference |
-| Editor/tooling coverage | `false` | Editor/tooling deve espelhar somente contrato publico suportado | Partial | `projects/praxis-core/src/lib/utils/inline-filter-controls.util.ts`, `projects/praxis-dynamic-fields/src/lib/services/component-registry/component-registry.service.ts` |
-| Path hygiene | `false` | Manter consistencia entre contrato canonico e caminhos documentados | Active | frontmatter.legacy_paths_present |
-| Known mismatches | `false` | Registrar observed vs desired de forma auditavel | Active | frontmatter.has_known_mismatches |
+| Component id | `pdx-inline-sentiment` | Manter ID canônico estável e versionado por contrato | Active | frontmatter.component |
+| Primary contract source | `runtime-and-code` | Runtime, schema e docs devem permanecer rastreáveis | Partial | frontmatter.contract_source + source_of_truth |
+| Runtime coverage | `true` | Comportamentos runtime críticos devem ficar explicitamente verificados | Active | `projects/praxis-dynamic-fields/src/lib/components/inline-sentiment/inline-sentiment.component.ts`, `projects/praxis-dynamic-fields/src/lib/base/simple-base-select.component.ts` |
+| Schema/type coverage | `true` | Tipos e schema devem refletir paths públicos do contrato | Active | source_of_truth + Detailed API reference |
+| Editor/tooling coverage | `false` | Editor/tooling deve espelhar somente contrato público suportado | Partial | `projects/praxis-core/src/lib/utils/inline-filter-controls.util.ts`, `projects/praxis-dynamic-fields/src/lib/services/component-registry/component-registry.service.ts` |
+| Path hygiene | `false` | Manter consistência entre contrato canônico e caminhos documentados | Active | frontmatter.legacy_paths_present |
+| Known mismatches | `false` | Registrar observed vs desired de forma auditável | Active | frontmatter.has_known_mismatches |
 
 ## Source of truth
 
 | Source | Kind | Notes |
 | --- | --- | --- |
-| projects/praxis-dynamic-fields/src/lib/components/inline-sentiment/inline-sentiment.component.ts | runtime-code | Arquivo presente no repositorio e usado como evidencia de contrato. |
-| projects/praxis-dynamic-fields/src/lib/base/simple-base-select.component.ts | runtime-code | Arquivo presente no repositorio e usado como evidencia de contrato. |
-| projects/praxis-core/src/lib/models/material-field-metadata.interface.ts | schema-types | Arquivo presente no repositorio e usado como evidencia de contrato. |
+| projects/praxis-dynamic-fields/src/lib/components/inline-sentiment/inline-sentiment.component.ts | runtime-code | Arquivo presente no repositorio e usado como evidência de contrato. |
+| projects/praxis-dynamic-fields/src/lib/base/simple-base-select.component.ts | runtime-code | Arquivo presente no repositorio e usado como evidência de contrato. |
+| projects/praxis-core/src/lib/models/material-field-metadata.interface.ts | schema-types | Arquivo presente no repositorio e usado como evidência de contrato. |
 
 ## Support legend
 
 - **Active**: suportado em runtime e liberado para uso externo.
-- **Partial**: suporte parcial, com restricoes, lacunas ou validacao incompleta.
-- **Declared-only**: declarado em tipos/schema sem evidencia operacional completa.
+- **Partial**: suporte parcial, com restricoes, lacunas ou validação incompleta.
+- **Declared-only**: declarado em tipos/schema sem evidência operacional completa.
 - **Schema-only**: presente em schema/tipos sem cobertura runtime confirmada.
 
 ## Contract status snapshot
 
 | Item | Value | Notes |
 | --- | --- | --- |
-| Reference mode | `canonical` | Deve permanecer canonico |
+| Reference mode | `canonical` | Deve permanecer canônico |
 | Contract format | `json` | Contrato metadata-driven |
 | Contract source | `runtime-and-code` | Alinhar com source_of_truth |
 | Runtime scope | `public` | Escopo publicado para consumidores |
-| Runtime verified | `true` | Revisar sempre com evidencia de runtime |
-| Schema verified | `true` | Revisar sempre com evidencia de tipos/schema |
-| Editor coverage verified | `false` | Revisar sempre com evidencia de editor/tooling |
-| Current path hygiene | `false` | Segregar consistencia do contrato canonico |
+| Runtime verified | `true` | Revisar sempre com evidência de runtime |
+| Schema verified | `true` | Revisar sempre com evidência de tipos/schema |
+| Editor coverage verified | `false` | Revisar sempre com evidência de editor/tooling |
+| Current path hygiene | `false` | Segregar consistência do contrato canônico |
 | Has known mismatches | `false` | Divergencias devem aparecer em secao dedicada |
 
 ## Contract classification (obrigatorio)
@@ -117,15 +117,15 @@ Este documento e a referencia canonica da API JSON de pdx-inline-sentiment.
 
 ### Path audit
 
-Nenhum desvio de caminho foi identificado nesta revisao.
+Nenhum desvio de caminho foi identificado nesta revisão.
 
 ### Internal-only paths
 
-Nao ha paths internal-only confirmados no contrato publico desta revisao.
+Não ha paths internal-only confirmados no contrato público desta revisão.
 
 ### Experimental paths
 
-Nao ha paths experimentais confirmados no contrato publico desta revisao.
+Não ha paths experimentais confirmados no contrato público desta revisão.
 
 ## Public contract surface (obrigatorio)
 
@@ -134,11 +134,11 @@ Nao ha paths experimentais confirmados no contrato publico desta revisao.
 | Block | Purpose | Required | Merge strategy | Notes |
 | --- | --- | --- | --- | --- |
 | `metadata` | Payload declarativo principal do componente | true | deep-merge | runtime linkage verified for core flows (component specs, 2026-03-16). |
-| `selectOptions` | Configuracao especifica de runtime | false | override | runtime linkage verified for core flows (component specs, 2026-03-16). |
+| `selectOptions` | Configuração especifica de runtime | false | override | runtime linkage verified for core flows (component specs, 2026-03-16). |
 | `readonlyMode` | Override de readonly no host/runtime | false | override | runtime linkage verified for core flows (component specs, 2026-03-16). |
 | `disabledMode` | Override de disabled no host/runtime | false | override | runtime linkage verified for core flows (component specs, 2026-03-16). |
 | `visible` | Override de visibilidade no host/runtime | false | override | runtime linkage verified for core flows (component specs, 2026-03-16). |
-| `presentationMode` | Renderizacao de apresentacao sem interacao | false | override | runtime linkage verified for core flows (component specs, 2026-03-16). |
+| `presentationMode` | Renderização de apresentação sem interação | false | override | runtime linkage verified for core flows (component specs, 2026-03-16). |
 
 ### Nested configuration blocks
 
@@ -203,15 +203,15 @@ Nao ha paths experimentais confirmados no contrato publico desta revisao.
 ### Runtime coverage boundaries
 
 - Ambientes suportados: browser/dev/prod; SSR/hydration appears to be component-dependent unless explicitly verified.
-- Pre-condicoes: payload JSON valido, bindings de host consistentes e dependencias descritas no source_of_truth.
-- Fora de cobertura confirmada: caminhos internos, experimentais ou aliases nao enumerados formalmente.
+- Pre-condicoes: payload JSON válido, bindings de host consistentes e dependencias descritas no source_of_truth.
+- Fora de cobertura confirmada: caminhos internos, experimentais ou aliases não enumerados formalmente.
 
 ### Editor and tooling notes
 
 - Evidencia de tooling: aliases `pdx-inline-*` resolvidos por `inline-filter-controls.util.ts` e consumidos no `ComponentRegistryService`; editor visual E2E permanece not-yet-verified.
-- O que esta exposto no editor visual depende da cobertura real do workspace e nao deve ser inferido como suporte runtime total.
-- Campos disponiveis apenas via JSON/manual devem continuar no contrato, com rotulo explicito de cobertura parcial.
-- Quando houver divergencia entre editor e runtime, manter mismatch rastreavel em secao dedicada.
+- O que esta exposto no editor visual depende da cobertura real do workspace e não deve ser inferido como suporte runtime total.
+- Campos disponíveis apenas via JSON/manual devem continuar no contrato, com rótulo explícito de cobertura parcial.
+- Quando houver divergencia entre editor e runtime, manter mismatch rastreável em secao dedicada.
 
 ## Resolution and precedence model (obrigatorio)
 
@@ -224,21 +224,21 @@ Nao ha paths experimentais confirmados no contrato publico desta revisao.
 
 ### Fallback order
 
-contrato explicito -> aliases historicos (quando suportados) -> defaults internos -> comportamento seguro
+contrato explicito -> aliases históricos (quando suportados) -> defaults internos -> comportamento seguro
 
 ### Override points
 
 - inputs publicos do componente
-- configuracao JSON de runtime
-- integracoes de host (servicos/tokens/adapters)
+- configuração JSON de runtime
+- integracoes de host (serviços/tokens/adapters)
 
 ### Runtime normalization
 
-Alias e defaults devem convergir para paths canonicos; onde nao houver evidencia, manter not-yet-verified de forma explicita.
+Alias e defaults devem convergir para paths canônicos; onde não houver evidência, manter not-yet-verified de forma explícita.
 
 ### Precedence rules
 
-Em conflito entre caminho historico e path canonico, priorizar path canonico e registrar janela de migracao do historico.
+Em conflito entre caminho histórico e path canônico, priorizar path canônico e registrar janela de migração do histórico.
 
 ## Validation and error semantics (obrigatorio)
 
@@ -246,7 +246,7 @@ Em conflito entre caminho historico e path canonico, priorizar path canonico e r
 
 | Path/Rule | Validation phase | Behavior on fail | Error code / warning | Notes |
 | --- | --- | --- | --- | --- |
-| canonical-paths | parse/runtime | component-defined (warn/reject/default) | not-yet-standardized | Semantica detalhada preservada na referencia tecnica por componente. |
+| canonical-paths | parse/runtime | component-defined (warn/reject/default) | not-yet-standardized | Semantica detalhada preservada na referência técnica por componente. |
 
 ### Invalid and unknown field handling
 
@@ -264,66 +264,66 @@ Em conflito entre caminho historico e path canonico, priorizar path canonico e r
 
 | Condition | Severity | Observability | Consumer action |
 | --- | --- | --- | --- |
-| partial-or-declared-only-coverage | warning | logs/eventos do componente | Confirmar ligacao runtime antes de uso critico. |
-| mismatch-confirmed | error-or-warning | componente/host observability | Planejar migracao e corrigir contrato/runtime. |
+| partial-or-declared-only-coverage | warning | logs/eventos do componente | Confirmar ligação runtime antes de uso crítico. |
+| mismatch-confirmed | error-or-warning | componente/host observability | Planejar migração e corrigir contrato/runtime. |
 
 ## Detailed API reference
 ### Preserved technical reference (normalized from previous revision)
 
-### 1. Visao Geral e Quando Usar
-`pdx-inline-sentiment` e um filtro inline de sentimento com emojis, barra de gradiente e cards selecionaveis.
+### 1. Visão Geral e Quando Usar
+`pdx-inline-sentiment` é um filtro inline de sentimento com emojis, barra de gradiente e cards selecionáveis.
 
 Use quando precisar:
 - classificar feedback por polaridade (negativo/neutro/positivo);
-- expor leitura visual rapida via emoji + cor;
-- permitir single ou multipla selecao com pills de resumo.
+- expor leitura visual rápida via emoji + cor;
+- permitir single ou múltipla seleção com pills de resumo.
 
 ### 2. API do Componente (Inputs/Outputs)
-| Propriedade | Tipo | Padrao | Obrigatorio | Comportamento |
+| Propriedade | Tipo | Padrão | Obrigatório | Comportamento |
 | --- | --- | --- | --- | --- |
 | `metadata` | `MaterialSelectMetadata` | - | Sim | Contrato principal de sentimento inline. |
-| `readonlyMode/disabledMode/visible/presentationMode` | `boolean` | `false/false/true/false` | Nao | Estados de host do campo inline. |
+| `readonlyMode/disabledMode/visible/presentationMode` | `boolean` | `false/false/true/false` | Não | Estados de host do campo inline. |
 | `selectionChange` | `T \| T[]` | - | Output herdado | Valor(es) de sentimento selecionado(s). |
-| `optionSelected` | `SelectOption` | - | Output herdado | Opcao escolhida no card de sentimento. |
+| `optionSelected` | `SelectOption` | - | Output herdado | Opção escolhida no card de sentimento. |
 
 ### 3. Matriz de Cobertura JSON (Completa)
-#### 3.1 Campos especificos do componente
+#### 3.1 Campos específicos do componente
 | Caminho JSON | Tipo | Status | Comportamento em runtime |
 | --- | --- | --- | --- |
 | `metadata.sentimentOptions` | `array \| string(JSON)` | Ativo | Fonte principal dos cards de sentimento. |
 | `metadata.sentimentMultiple` / `multiple` | `boolean` | Ativo | Define single/multiple selection. |
 | `metadata.sentimentShowBar` | `boolean` | Ativo | Exibe barra visual de sentimento. |
 | `metadata.sentimentShowSelectionPills` | `boolean` | Ativo | Exibe pills dos itens selecionados. |
-| `metadata.sentimentAnimatedEmoji` | `boolean` | Ativo | Ativa animacao de emoji em hover/select. |
-| `metadata.sentimentCloseOnSelect` | `boolean` | Ativo | Fecha painel apos selecao (single). |
-| `metadata.sentimentEmojiKey/optionEmojiKey` | `string` | Ativo | Chave do emoji por opcao. |
-| `metadata.sentimentColorKey/optionColorKey` | `string` | Ativo | Chave da cor por opcao. |
-| `metadata.sentimentPalette/palette` | `array \| string` | Ativo | Paleta fallback para opcoes sem cor. |
-| `metadata.sentimentGradientLowColor/midColor/highColor` | `string` | Ativo | Gradiente semantico fallback para barra e opcoes sem cor explicita. |
-| `metadata.sentimentTexts` / `inlineTexts` | `object \| string(JSON)` | Ativo | Textos de subtitulo, aria, labels de grupo/pills e empty state; templates canonicos devem usar `{{label}}` e `{{value}}` quando houver interpolacao. |
-| `metadata.inlineOverlay.applyMode` | `"auto" \| "explicit"` | Ativo | Define se cards de sentimento comitam imediatamente ou ficam em rascunho ate `Aplicar`. |
-| `metadata.inlineOverlay.actions.apply` | `object` | Ativo | Configura label, aria-label, icone, `appearance` e `colorRole` da acao de commit. |
-| `metadata.inlineOverlay.actions.cancel` | `object` | Ativo | Configura a acao que descarta rascunho e fecha o painel. |
-| `metadata.inlineOverlay.actions.clear` | `object` | Ativo | Configura a acao que remove a selecao aplicada/rascunho usando tokens do tema. |
-| `metadata.sentimentIcon` / `prefixIcon` | `string` | Ativo | Icone do trigger/painel. |
+| `metadata.sentimentAnimatedEmoji` | `boolean` | Ativo | Ativa animação de emoji em hover/select. |
+| `metadata.sentimentCloseOnSelect` | `boolean` | Ativo | Fecha painel após seleção (single). |
+| `metadata.sentimentEmojiKey/optionEmojiKey` | `string` | Ativo | Chave do emoji por opção. |
+| `metadata.sentimentColorKey/optionColorKey` | `string` | Ativo | Chave da cor por opção. |
+| `metadata.sentimentPalette/palette` | `array \| string` | Ativo | Paleta fallback para opções sem cor. |
+| `metadata.sentimentGradientLowColor/midColor/highColor` | `string` | Ativo | Gradiente semântico fallback para barra e opções sem cor explícita. |
+| `metadata.sentimentTexts` / `inlineTexts` | `object \| string(JSON)` | Ativo | Textos de subtítulo, aria, labels de grupo/pills e empty state; templates canônicos devem usar `{{label}}` e `{{value}}` quando houver interpolação. |
+| `metadata.inlineOverlay.applyMode` | `"auto" \| "explicit"` | Ativo | Define se cards de sentimento comitam imediatamente ou ficam em rascunho até `Aplicar`. |
+| `metadata.inlineOverlay.actions.apply` | `object` | Ativo | Configura label, aria-label, ícone, `appearance` e `colorRole` da ação de commit. |
+| `metadata.inlineOverlay.actions.cancel` | `object` | Ativo | Configura a ação que descarta rascunho e fecha o painel. |
+| `metadata.inlineOverlay.actions.clear` | `object` | Ativo | Configura a ação que remove a seleção aplicada/rascunho usando tokens do tema. |
+| `metadata.sentimentIcon` / `prefixIcon` | `string` | Ativo | Ícone do trigger/painel. |
 | `metadata.inlineAutoSize.*` | `object` | Ativo | Largura da pill e painel. |
 
 #### 3.2 Campos herdados compartilhados (exaustivo)
 - `projects/praxis-dynamic-fields/src/lib/components/material-select/pdx-material-select.json-api.md`
 - `projects/praxis-dynamic-fields/src/lib/base/pdx-base-select-runtime-contract.json-api.md`
 
-Resumo de composicao deste componente:
+Resumo de composição deste componente:
 - `Ativo`: cards de sentimento com emoji/cor, barra e pills de resumo.
-- `Extensao de runtime`: namespace `sentiment*` com fallback para chaves genericas.
+- `Extensão de runtime`: namespace `sentiment*` com fallback para chaves genéricas.
 
 ### 4. Mapeamento de Comportamento
-- Opcoes podem ser carregadas de `sentimentOptions`, `selectOptions` ou `options`.
+- Opções podem ser carregadas de `sentimentOptions`, `selectOptions` ou `options`.
 - Cor/emoji de cada item segue ordem de chaves custom -> payload -> paleta fallback.
-- Em multiplo, respeita `maxSelections` herdado.
+- Em múltiplo, respeita `maxSelections` herdado.
 - Aria labels, labels de grupo/pills e textos operacionais podem ser centralizados em `sentimentTexts`.
-- Quando `inlineOverlay.applyMode` e `"explicit"`, selecoes no painel alteram apenas o rascunho; `Aplicar` comita, `Cancelar`, `Esc` e clique externo descartam, e `Limpar` remove a selecao.
+- Quando `inlineOverlay.applyMode` e `"explicit"`, seleções no painel alteram apenas o rascunho; `Aplicar` comita, `Cancelar`, `Esc` e clique externo descartam, e `Limpar` remove a seleção.
 
-### 5. Exemplo Minimo (JSON + Uso)
+### 5. Exemplo Mínimo (JSON + Uso)
 ```json
 {
   "componentId": "pdx-inline-sentiment",
@@ -338,7 +338,7 @@ Resumo de composicao deste componente:
   }
 }
 ```
-Uso: classificacao simples de sentimento.
+Uso: classificação simples de sentimento.
 
 ### 6. Exemplo Corporativo (JSON + Uso)
 ```json
@@ -378,34 +378,34 @@ Uso: classificacao simples de sentimento.
   }
 }
 ```
-Uso: analise de CX com semantica visual direta e confirmacao explicita antes de aplicar.
+Uso: análise de CX com semântica visual direta e confirmação explícita antes de aplicar.
 
 ### 7. Troubleshooting e Armadilhas Comuns
-1. Emoji nao renderiza.
-Correcao: ajustar `sentimentEmojiKey` ou o campo de payload.
+1. Emoji não renderiza.
+Correção: ajustar `sentimentEmojiKey` ou o campo de payload.
 
 2. Cores repetidas sem intencao.
-Correcao: revisar `sentimentColorKey` e `sentimentPalette`.
+Correção: revisar `sentimentColorKey` e `sentimentPalette`.
 
-3. Painel nao fecha no single.
-Correcao: habilitar `sentimentCloseOnSelect=true`.
+3. Painel não fecha no single.
+Correção: habilitar `sentimentCloseOnSelect=true`.
 
-4. Pills nao aparecem no multiplo.
-Correcao: verificar `sentimentShowSelectionPills`.
+4. Pills não aparecem no múltiplo.
+Correção: verificar `sentimentShowSelectionPills`.
 
-5. Animacao de emoji nao ocorre.
-Correcao: validar `sentimentAnimatedEmoji`.
+5. Animação de emoji não ocorre.
+Correção: validar `sentimentAnimatedEmoji`.
 
 ### 8. Cross-links
 - `projects/praxis-dynamic-fields/src/lib/components/material-select/pdx-material-select.json-api.md`
 - `projects/praxis-dynamic-fields/src/lib/base/pdx-base-select-runtime-contract.json-api.md`
 
-### 9. Relatorio de Validacao Estrutural
-- Visao geral: PASS
+### 9. Relatório de Validação Estrutural
+- Visão geral: PASS
 - API (inputs/outputs): PASS
 - Cobertura JSON completa (especifico + herdado): PASS
 - Mapeamento de comportamento: PASS
-- Exemplo minimo: PASS
+- Exemplo mínimo: PASS
 - Exemplo corporativo: PASS
 - Troubleshooting: PASS
 
@@ -668,7 +668,7 @@ Correcao: validar `sentimentAnimatedEmoji`.
 
 | Path/Behavior | Observed behavior (runtime) | Desired behavior | Impact | Tracking issue | Target fix |
 | --- | --- | --- | --- | --- | --- |
-| Canonical contract parity | Runtime e exemplos desta referencia foram atualizados em 2026-03-16 para refletir a migracao do componente para o catalogo shared de i18n e o uso de templates `{{...}}` | Manter exemplos e host overrides no formato canonico `{{...}}` | Low | n/a | Monitor in periodic audit |
+| Canonical contract parity | Runtime e exemplos desta referência foram atualizados em 2026-03-16 para refletir a migração do componente para o catálogo shared de i18n e o uso de templates `{{...}}` | Manter exemplos e host overrides no formato canônico `{{...}}` | Low | n/a | Monitor in periodic audit |
 
 ## Source references (obrigatorio)
 

package/src/lib/components/inline-time-range/pdx-inline-time-range.json-api.md

@@ -299,7 +299,7 @@ Use quando precisar:
 | `metadata.validators.rangeMessage` | `string` | Ativo | Mensagem para erro de ordem do intervalo. |
 | `metadata.validators.minDistanceMessage` | `string` | Ativo | Mensagem para distancia minima. |
 | `metadata.validators.maxDistanceMessage` | `string` | Ativo | Mensagem para distancia maxima. |
-| `metadata.inlineOverlay.applyMode` | `"auto" \| "explicit" \| "confirm"` | Ativo | Quando `explicit`/`confirm`, slider, inputs e presets ficam em rascunho ate `Aplicar`. |
+| `metadata.inlineOverlay.applyMode` | `"auto" \| "explicit"` | Ativo | Quando `explicit`, slider, inputs e presets ficam em rascunho ate `Aplicar`. |
 | `metadata.inlineOverlay.actions.apply.*` | `object` | Ativo | Label, aria, icon, appearance e colorRole do commit. |
 | `metadata.inlineOverlay.actions.cancel.*` | `object` | Ativo | Label, aria, icon, appearance e colorRole do descarte. |
 | `metadata.inlineOverlay.actions.clear.*` | `object` | Ativo | Label, aria, icon, appearance, colorRole e visibilidade da limpeza explicita. |
@@ -318,7 +318,7 @@ Resumo de composicao deste componente:
 - `quickPresets` podem ser declarados ou gerados por defaults internos.
 - Slider e inputs textuais permanecem sincronizados (`timeRangeForm` + `sliderRangeForm`).
 - `timeInputStepSeconds()` deriva de `stepMinute` para entrada `type=time`.
-- Com `inlineOverlay.applyMode: "explicit"` ou `"confirm"`, alteracoes no painel nao emitem valor externo ate `Aplicar`; `Cancelar`, `Esc`, detach ou clique externo restauram o valor confirmado anterior.
+- Com `inlineOverlay.applyMode: "explicit"`, alteracoes no painel nao emitem valor externo ate `Aplicar`; `Cancelar`, `Esc`, detach ou clique externo restauram o valor confirmado anterior.
 
 ### 5. Exemplo Minimo (JSON + Uso)
 ```json

package/src/lib/components/material-async-select/pdx-material-async-select.json-api.md

@@ -393,7 +393,8 @@ Precedencia de comportamento:
 
 Notas de runtime:
 
-- em remoto, `loadOptions` usa filtro com include de selecionados na pagina 0.
+- em remoto generico, `loadOptions` pode usar `includeIds` na pagina 0.
+- em `optionSource`, o filtro envia `includeIds` somente quando `optionSource.includeIds=true`; quando ausente ou `false`, valores selecionados sao reidratados por `/option-sources/{sourceKey}/options/by-ids`.
 - `onSearch` limpa estado local e reinicia pagina para novo termo.
 
 Contrato compartilhado completo:
@@ -417,7 +418,7 @@ Correcao: revise `loadOn`, `resourcePath` e permissao de endpoint.
 Correcao: alinhe `optionLabelKey` e `optionValueKey` ao payload real.
 
 4. Item selecionado some apos nova busca.
-Correcao: backend deve suportar include de ids selecionados na pagina inicial.
+Correcao: para `optionSource.includeIds=false`, backend deve suportar reidratacao por `/by-ids`; para remoto generico ou `optionSource.includeIds=true`, pode suportar include de ids selecionados na pagina inicial.
 
 5. Cascata nao atualiza automaticamente.
 Correcao: use `dependencyLoadOnChange='immediate'` ou dispare recarga no host.

package/src/lib/components/material-checkbox-group/pdx-material-checkbox-group.json-api.md

@@ -22,8 +22,8 @@ source_of_truth:
   - "projects/praxis-dynamic-fields/src/lib/components/material-checkbox-group/material-checkbox-group.component.ts"
   - "projects/praxis-dynamic-fields/src/lib/base/simple-base-select.component.ts"
   - "projects/praxis-core/src/lib/models/material-field-metadata.interface.ts"
-source_of_truth_last_verified: "2026-04-27"
-last_updated: "2026-04-27"
+source_of_truth_last_verified: "2026-06-25"
+last_updated: "2026-06-25"
 toc: true
 sidebar: true
 tags:
@@ -133,6 +133,7 @@ Este documento e a referencia canonica da API JSON de pdx-material-checkbox-grou
 | --- | --- | --- | --- | --- |
 | `metadata.options` | `metadata.checkboxOptions` | not-yet-defined | accepted for backward compatibility | Alias legado para opcoes do grupo. |
 | ausencia de `metadata.selectionMode` | `metadata.selectionMode` explicito | not-yet-defined | runtime infere `boolean` sem opcoes e `multiple` com opcoes | Fallback legado preservado para migracao. |
+| valores booleanos legados `S`/`N`, `1`/`0`, `true`/`false` no `FormControl` | `boolean` real | not-yet-defined | em `selectionMode: 'boolean'`, o runtime normaliza antes de renderizar e emitir eventos | Compatibilidade para telas migradas que recebem flags legadas do backend. |
 
 ### Internal-only paths
 
@@ -197,6 +198,7 @@ Nao ha paths experimentais confirmados no contrato publico desta revisao.
 ### Runtime semantics addendum
 
 - `selectionMode` explicito governa a semantica interna de selecao; heuristica por presenca de opcoes so vale quando `selectionMode` nao e informado.
+- Em `selectionMode: 'boolean'`, o valor de entrada aceita `boolean` real e flags legadas textuais/numéricas (`S`/`N`, `T`/`F`, `1`/`0`, `true`/`false`, `sim`/`não`) e normaliza para `boolean` antes da interação.
 - `required`/`requiredChecked` propagam sinalizacao acessivel (`aria-required`) para o checkbox renderizado.
 - No modo boolean, cliques no shell de conteudo tambem emitem `selectionChange` e `optionSelected` para alinhamento operacional com o runtime base de selecao.
 - Estados governados (`disabledMode`, `readonlyMode`, `presentationMode`, `metadata.readonly` e `FormControl.disabled`) bloqueiam mutacoes em modo boolean, option e select-all.
@@ -224,7 +226,7 @@ Nao ha paths experimentais confirmados no contrato publico desta revisao.
 
 | Surface | Verified | Coverage status | Evidence | Notes |
 | --- | --- | --- | --- | --- |
-| Runtime | `true` | Active | `projects/praxis-dynamic-fields/src/lib/components/material-checkbox-group/material-checkbox-group.metadata.ts`, `projects/praxis-dynamic-fields/src/lib/components/material-checkbox-group/material-checkbox-group.component.ts` | Core runtime flows and governed states verified via focused component specs on 2026-04-27; editor/tooling coverage remains independent. |
+| Runtime | `true` | Active | `projects/praxis-dynamic-fields/src/lib/components/material-checkbox-group/material-checkbox-group.metadata.ts`, `projects/praxis-dynamic-fields/src/lib/components/material-checkbox-group/material-checkbox-group.component.ts` | Core runtime flows, governed states and legacy boolean value normalization verified via focused component specs on 2026-06-25; editor/tooling coverage remains independent. |
 | Schema/Types | `true` | Active | source_of_truth + Detailed API reference | Reconcile schema/types with canonical paths during follow-up when needed. |
 | Editor/Tooling | `false` | Partial | `projects/praxis-core/src/lib/metadata/field-selector-control-type.constants.ts`, `projects/praxis-dynamic-fields/src/lib/services/component-registry/component-registry.service.ts` | Selector/control-type tooling linkage verified via default selector map and registry seeding; visual editor end-to-end coverage remains not-yet-verified. |
 

package/src/lib/components/material-file-upload/pdx-material-file-upload.json-api.md

@@ -21,8 +21,8 @@ source_of_truth:
   - "projects/praxis-dynamic-fields/src/lib/components/material-file-upload/material-file-upload.metadata.ts"
   - "projects/praxis-dynamic-fields/src/lib/components/material-file-upload/material-file-upload.component.ts"
   - "projects/praxis-dynamic-fields/src/lib/base/simple-base-input.component.ts"
-source_of_truth_last_verified: "2026-03-06"
-last_updated: "2026-03-06"
+source_of_truth_last_verified: "2026-06-24"
+last_updated: "2026-06-24"
 toc: true
 sidebar: true
 tags:
@@ -149,10 +149,14 @@ Nao ha paths experimentais confirmados no contrato publico desta revisao.
 | `metadata.hint` | string | false | n/a | component-defined | Partial; verify per source_of_truth. |
 | `metadata.placeholder` | string | false | n/a | component-defined | Partial; verify per source_of_truth. |
 | `metadata.validators.*` | object | false | n/a | component-defined | Partial; verify per source_of_truth. |
-| `metadata.accept` | string | false | n/a | component-defined | Partial; verify per source_of_truth. |
-| `metadata.multiple` | boolean | false | n/a | component-defined | Partial; verify per source_of_truth. |
-| `metadata.maxFileSize` | number | false | n/a | component-defined | Partial; verify per source_of_truth. |
+| `metadata.accept` | string | false | n/a | comma-separated extensions or MIME patterns | Active; applied to native input and local file validation. |
+| `metadata.multiple` | boolean | false | `false` | boolean | Active; selected value is `File[]` when true and `File | null` otherwise. |
+| `metadata.maxFileSize` | number | false | n/a | positive byte count | Active; rejects selected files above the configured limit. |
+| `metadata.maxFiles` | number | false | n/a | positive integer | Active; rejects selections above the configured number of files. |
 | `metadata.allowedTypes` | string[] | false | n/a | component-defined | Partial; verify per source_of_truth. |
+| `metadata.imagePreview` | boolean | false | `false` | boolean | Active; renders local image preview for selected image files. |
+| `metadata.preview` | string | false | n/a | `image` | Active; `image` is an alias for local image preview. |
+| `metadata.previewAlt` | string | false | localized fallback | component-defined | Active; accessible alt text for the local preview image. |
 
 ### Input bindings (inbound data)
 
@@ -268,12 +272,13 @@ Em conflito entre alias legado e path canonico, priorizar path canonico e regist
 ### Preserved technical reference (normalized from previous revision)
 
 ### 1. Visao Geral e Quando Usar
-`pdx-material-file-upload` e um upload basico (placeholder funcional) com `<input type="file">` simples e integracao CVA.
+`pdx-material-file-upload` e um upload basico de campo com `<input type="file">`, integracao CVA, validacao local de tipo/tamanho e preview local de imagem.
 
 Use quando precisar:
 - prototipar upload rapido no form;
-- capturar um unico arquivo selecionado;
-- evoluir depois para fluxo corporativo completo (preview/chunk/validacoes avancadas).
+- capturar um arquivo selecionado ou uma lista curta de arquivos;
+- mostrar preview local para fluxos de foto/avatar antes da persistencia;
+- delegar persistencia, presign, progresso, conflito e storage governado para a camada canonica de upload.
 
 ### 2. API do Componente (Inputs/Outputs)
 | Propriedade | Tipo | Padrao | Obrigatorio | Comportamento |
@@ -283,7 +288,7 @@ Use quando precisar:
 | `disabledMode` | `boolean` | `false` | Nao | Sobrescreve disabled no host. |
 | `visible` | `boolean` | `true` | Nao | Controla exibicao no host. |
 | `presentationMode` | `boolean` | `false` | Nao | Modo apresentacao sem edicao. |
-| `valueChange` | `File \| null` | - | Output base input | Arquivo selecionado no input. |
+| `valueChange` | `File \| File[] \| null` | - | Output base input | Arquivo selecionado no input; quando `multiple=true`, emite array. |
 
 ### 3. Matriz de Cobertura JSON (Completa)
 #### 3.1 Campos especificos do componente
@@ -294,25 +299,29 @@ Use quando precisar:
 | `metadata.hint` | `string` | Ativo | Mensagem de apoio quando sem erro. |
 | `metadata.placeholder` | `string` | Parcial | `setFileUploadMetadata` remove placeholder do estado efetivo. |
 | `metadata.validators.*` | `object` | Parcial | Validacoes basicas do `SimpleBaseInput` podem atuar no control, sem parser de arquivo dedicado. |
-| `metadata.accept` | `string` | Declared-only | Nao aplicado ao atributo `accept` no input atual. |
-| `metadata.multiple` | `boolean` | Declared-only | Input atual usa apenas o primeiro arquivo selecionado. |
-| `metadata.maxFileSize` | `number` | Declared-only | Nao ha validacao de tamanho especifica no componente. |
+| `metadata.accept` | `string` | Ativo | Aplicado ao atributo `accept` e validado localmente por extensao/MIME antes de atualizar o control. |
+| `metadata.multiple` | `boolean` | Ativo | Permite selecionar varios arquivos e atualiza o valor como `File[]`. |
+| `metadata.maxFileSize` | `number` | Ativo | Rejeita arquivos acima do limite em bytes antes de atualizar o control. |
+| `metadata.maxFiles` | `number` | Ativo | Rejeita selecoes acima da quantidade maxima configurada. |
 | `metadata.allowedTypes` | `string[]` | Declared-only | Nao ha filtro dedicado por tipo no componente atual. |
+| `metadata.imagePreview` | `boolean` | Ativo | Mostra preview local para o primeiro arquivo de imagem selecionado. |
+| `metadata.preview` | `'image'` | Ativo | Alias declarativo para habilitar preview local de imagem. |
+| `metadata.previewAlt` | `string` | Ativo | Texto alternativo do preview local. |
 
 #### 3.2 Campos herdados compartilhados (exaustivo)
 Contrato compartilhado de input base:
 - [pdx-base-input-runtime-contract.json-api.md](projects/praxis-dynamic-fields/src/lib/base/pdx-base-input-runtime-contract.json-api.md)
 
 Resumo de composicao deste componente:
-- `Ativo`: fluxo basico de selecao de um arquivo e bind no control.
+- `Ativo`: fluxo basico de selecao, bind no control, preview local de imagem e validacao local de tipo/tamanho/quantidade.
 - `Parcial`: placeholder e validacoes genericas do base.
-- `Declared-only`: capacidade avancada de upload ainda nao implementada.
+- `Declared-only`: politica avancada por `allowedTypes`.
 
 ### 4. Mapeamento de Comportamento
-- Selecao: ao `change`, pega `files[0]` e grava no control.
-- Valor: tipo `File | null`.
-- Renderizacao: label + input file + erro/hint.
-- Estado corporativo: componente se declara "placeholder" no proprio codigo.
+- Selecao: ao `change`, valida arquivos e grava `File` ou `File[]` no control.
+- Valor: `File | null` quando `multiple` esta ausente/falso; `File[]` quando `multiple=true`.
+- Renderizacao: label, input file, resumo da selecao, preview local de imagem, erro/hint e acao de limpar.
+- Persistencia corporativa: fora deste componente. Use `@praxisui/files-upload` para presign, progresso, conflito, retry e storage governado.
 
 ### 5. Exemplo Minimo (JSON + Uso)
 ```json
@@ -345,12 +354,30 @@ Uso: captura um arquivo unico para envio posterior.
 ```
 Uso: etapa inicial de upload, deixando validacoes profundas para API backend.
 
+### 6.1 Exemplo para troca de avatar (JSON + Uso)
+```json
+{
+  "componentId": "pdx-material-file-upload",
+  "metadata": {
+    "name": "profileImageFile",
+    "label": "Foto de perfil",
+    "controlType": "upload",
+    "accept": "image/*",
+    "maxFileSize": 4194304,
+    "maxFiles": 1,
+    "imagePreview": true,
+    "hint": "Escolha uma imagem para revisar antes de salvar a foto do perfil."
+  }
+}
+```
+Uso: combine este campo com `pdx-material-avatar` para preview/display e com a capability canonica de persistencia de arquivo para publicar a URL final consumida pelo avatar.
+
 ### 7. Troubleshooting e Armadilhas Comuns
-1. Esperar upload multiplo.
-Correcao: componente atual captura somente o primeiro arquivo.
+1. Esperar persistencia automatica.
+Correcao: este componente escolhe e valida localmente; persistencia pertence ao host ou a `@praxisui/files-upload`.
 
-2. Esperar filtro automatico por tipo/tamanho.
-Correcao: nao ha `accept`/validacao dedicada implementada nesta versao.
+2. Esperar crop/zoom.
+Correcao: preview local nao e editor de imagem. Crop deve nascer em contrato proprio de avatar/image authoring.
 
 3. Placeholder nao aparece.
 Correcao: `setFileUploadMetadata` remove placeholder explicitamente.
@@ -358,8 +385,8 @@ Correcao: `setFileUploadMetadata` remove placeholder explicitamente.
 4. Arquivo nao persiste no payload final.
 Correcao: verificar serializacao de `File` no host e estrategia de envio multipart.
 
-5. Necessidade de preview/progresso/chunk.
-Correcao: esse renderer e baseline; implementar camada avancada para cenarios enterprise.
+5. Necessidade de progresso/chunk/presign.
+Correcao: usar `@praxisui/files-upload`, que e a fronteira canonica de upload operacional.
 
 ### 8. Cross-links
 - `projects/praxis-dynamic-fields/src/lib/base/pdx-base-input-runtime-contract.json-api.md`
@@ -388,10 +415,14 @@ Correcao: esse renderer e baseline; implementar camada avancada para cenarios en
 | `metadata.hint` | string | false | n/a | Partial | See Detailed API reference. |
 | `metadata.placeholder` | string | false | n/a | Partial | See Detailed API reference. |
 | `metadata.validators.*` | object | false | n/a | Partial | See Detailed API reference. |
-| `metadata.accept` | string | false | n/a | Partial | See Detailed API reference. |
-| `metadata.multiple` | boolean | false | n/a | Partial | See Detailed API reference. |
-| `metadata.maxFileSize` | number | false | n/a | Partial | See Detailed API reference. |
+| `metadata.accept` | string | false | n/a | Active | Applied to native input and local type validation. |
+| `metadata.multiple` | boolean | false | `false` | Active | Emits `File[]` when true. |
+| `metadata.maxFileSize` | number | false | n/a | Active | Rejects files above the byte limit. |
+| `metadata.maxFiles` | number | false | n/a | Active | Rejects selections above the configured number of files. |
 | `metadata.allowedTypes` | string[] | false | n/a | Partial | See Detailed API reference. |
+| `metadata.imagePreview` | boolean | false | `false` | Active | Enables local image preview. |
+| `metadata.preview` | string | false | n/a | Active | `image` enables local image preview. |
+| `metadata.previewAlt` | string | false | localized fallback | Active | Accessible alt text for preview image. |
 
 ## Events reference (obrigatorio)