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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@praxisui/dynamic-fields",
-  "version": "9.0.0-beta.8",
+  "version": "9.0.0-beta.81",
   "description": "Angular Material-based dynamic form fields for Praxis UI with lazy loading and metadata-driven rendering.",
   "peerDependencies": {
     "@angular/common": "^21.0.0",
@@ -11,8 +11,8 @@
     "@angular/platform-browser": "^21.0.0",
     "@angular/router": "^21.0.0",
     "rxjs": "^7.8.0",
-    "@praxisui/core": "^9.0.0-beta.8",
-    "@praxisui/cron-builder": "^9.0.0-beta.8"
+    "@praxisui/core": "^9.0.0-beta.81",
+    "@praxisui/cron-builder": "^9.0.0-beta.81"
   },
   "dependencies": {
     "libphonenumber-js": "^1.12.41",
@@ -26,6 +26,7 @@
   "keywords": [
     "angular",
     "praxisui",
+    "praxis",
     "dynamic-fields",
     "material",
     "metadata-driven",
@@ -42,7 +43,10 @@
     ".": {
       "types": "./types/praxisui-dynamic-fields.d.ts",
       "default": "./fesm2022/praxisui-dynamic-fields.mjs"
+    },
+    "./ai/component-registry.json": {
+      "default": "./ai/component-registry.json"
     }
   },
   "type": "module"
-}
+}

package/src/lib/base/pdx-base-input-runtime-contract.json-api.md

@@ -349,6 +349,9 @@ Limites:
 | `metadata.validators.showInlineErrors` | `boolean` | Active | Forca/desliga exibicao inline de erros. |
 | `metadata.errorStateMatcher` | enum | Active | Estrategia de estado de erro usada pelo matcher utilitario. |
 | `metadata.hint` | `string` | Active | Exibe dica quando nao ha erro. |
+| `metadata.helpText` | `string` | Active | Texto de ajuda semantica publicado por DTO/schema; usado como fallback quando `hint` nao foi informado. |
+| `metadata.helpDisplay` | `'auto' \| 'inline' \| 'popover' \| 'hidden'` | Active | Politica efetiva de apresentacao de `hint`/`helpText`; normalmente materializada pelo host `praxis-dynamic-form` a partir de `FormConfig.helpPresentation`. |
+| `metadata.helpInlineMaxLength` | `number` | Active | Limite local usado quando `metadata.helpDisplay` e `auto`; textos acima do limite migram para affordance de ajuda. |
 | `metadata.hintAlign` | `'start' \| 'end'` | Active | Alinhamento da dica. |
 | `metadata.materialDesign.appearance` | `'fill' \| 'outline'` | Active | Aparencia do `mat-form-field`. |
 | `metadata.materialDesign.color` | `'primary' \| 'accent' \| 'warn'` | Active | Cor do `mat-form-field`. |
@@ -373,6 +376,19 @@ Limites:
 | `metadata.ariaDescribedby` | `string` | Active | `aria-describedby` no elemento nativo. |
 | `metadata.ariaLabelledby` | `string` | Active | `aria-labelledby` no elemento nativo. |
 
+#### Ajuda contextual em migracoes corporativas
+
+`metadata.helpText` pertence ao DTO/schema quando descreve semantica de negocio, impacto operacional ou criterio de decisao do campo. Ele nao deve ser gerado a partir de label, nome tecnico ou heuristica local.
+
+Use `metadata.helpDisplay` para excecoes por campo:
+
+- `inline`: texto curto que deve permanecer visivel para evitar erro operacional;
+- `popover`: texto longo, raro ou de apoio decisorio;
+- `hidden`: ajuda publicada mas inadequada para a superficie atual;
+- `auto`: delega a politica do host e ao limite `helpInlineMaxLength`.
+
+Em formularios densos, o host deve preferir uma politica global como `FormConfig.helpPresentation.display = "auto"` e mover textos longos para a affordance de ajuda. Mensagens de validacao continuam no canal de erro do campo e nao devem ser convertidas em `helpText`.
+
 #### Politica de label com prefixos e sufixos
 
 Quando um campo usa `metadata.prefixIcon`, `metadata.suffixIcon`, `clearButton`,

package/src/lib/components/field-shell/praxis-field-shell.json-api.md

@@ -22,8 +22,9 @@ source_of_truth:
   - "projects/praxis-dynamic-fields/src/lib/utils/field-state.util.ts"
   - "projects/praxis-dynamic-fields/src/lib/utils/format-display.util.ts"
   - "projects/praxis-core/src/lib/models/component-metadata.interface.ts"
-source_of_truth_last_verified: "2026-05-18"
-last_updated: "2026-05-18"
+  - "projects/praxis-core/src/lib/models/field-presentation.model.ts"
+source_of_truth_last_verified: "2026-06-25"
+last_updated: "2026-06-25"
 toc: true
 sidebar: true
 tags:
@@ -78,6 +79,7 @@ Este documento e a referencia canonica da API JSON de praxis-field-shell.
 | projects/praxis-dynamic-fields/src/lib/utils/field-state.util.ts | runtime-code | Arquivo presente no repositorio e usado como evidencia de contrato. |
 | projects/praxis-dynamic-fields/src/lib/utils/format-display.util.ts | runtime-code | Arquivo presente no repositorio e usado como evidencia de contrato. |
 | projects/praxis-core/src/lib/models/component-metadata.interface.ts | schema-types | Arquivo presente no repositorio e usado como evidencia de contrato. |
+| projects/praxis-core/src/lib/models/field-presentation.model.ts | schema-types/runtime-helper | Resolve `presentation` e `presentationRules` para presentationMode sem mutar valores. |
 
 ## Support legend
 
@@ -157,6 +159,9 @@ Nao ha paths experimentais confirmados no contrato publico desta revisao.
 | `field.controlType` | string | false | n/a | component-defined | Partial; verify per source_of_truth. |
 | `field.controlType='avatar'` | unknown | false | n/a | component-defined | Partial; verify per source_of_truth. |
 | `field.transformDisplayValue` | unknown | false | n/a | component-defined | Partial; verify per source_of_truth. |
+| `field.valuePresentation` | object | false | n/a | component-defined | Canonical value formatter for readonly/display surfaces. |
+| `field.presentation` | object | false | n/a | component-defined | Semantic readonly/display presentation state. |
+| `field.presentationRules` | array | false | n/a | component-defined | Ordered Json Logic rules that override semantic presentation state. |
 
 ### Input bindings (inbound data)
 
@@ -321,6 +326,8 @@ Resumo de composicao deste componente:
 ### 4. Mapeamento de Comportamento
 - Sempre cria o `insertionPoint` (`vc`) para o componente real do campo.
 - Em modo apresentacao sem excecao de tipo, esconde conteudo editavel e mostra bloco textual.
+- Em modo apresentacao, `field.valuePresentation` formata o valor e `field.presentation`/`field.presentationRules` ajustam presenter, tone, icon, label, badge, tooltip e appearance por semantica declarativa.
+- `presentationRules` sao avaliadas com Json Logic contra o contexto do campo. Regras invalidas falham fechadas e nao alteram o `FormControl`.
 - `readonlyMode` aplica overlay bloqueando interacao, mantendo controle habilitado.
 - `canvasMode` injeta semantica de evento para editores visuais.
 
@@ -346,7 +353,24 @@ Uso: shell padrao para um campo dinamico simples.
     "name": "approvalStatus",
     "label": "Aprovacao",
     "controlType": "select",
-    "readOnly": true
+    "readOnly": true,
+    "presentation": {
+      "presenter": "status",
+      "tone": "neutral",
+      "icon": "schedule",
+      "label": "Em analise"
+    },
+    "presentationRules": [
+      {
+        "when": { "===": [{ "var": "value" }, "BLOQUEADO"] },
+        "set": {
+          "tone": "danger",
+          "icon": "lock",
+          "label": "Bloqueado",
+          "appearance": "filled"
+        }
+      }
+    ]
   },
   "readonlyMode": false,
   "presentationMode": true,
@@ -374,6 +398,9 @@ Correcao: garantir `canvasMode=true`.
 5. Valor mostrado em apresentacao esta incorreto.
 Correcao: revisar `transformDisplayValue` e formato do valor no `control`.
 
+6. Regra de apresentacao nao muda o visual.
+Correcao: validar o Json Logic em `field.presentationRules[].when`; o contexto minimo expoe `value`, `rawValue`, `fieldName` e o nome do campo.
+
 ### 8. Cross-links
 - `projects/praxis-dynamic-fields/src/lib/utils/field-state.util.ts`
 - `projects/praxis-dynamic-fields/src/lib/utils/format-display.util.ts`
@@ -403,6 +430,9 @@ Correcao: revisar `transformDisplayValue` e formato do valor no `control`.
 | `field.controlType` | string | false | n/a | Partial | See Detailed API reference. |
 | `field.controlType='avatar'` | unknown | false | n/a | Partial | See Detailed API reference. |
 | `field.transformDisplayValue` | unknown | false | n/a | Partial | See Detailed API reference. |
+| `field.valuePresentation` | object | false | n/a | Active | Formats values in presentation mode. |
+| `field.presentation` | object | false | n/a | Active | Semantic state for presentation mode. |
+| `field.presentationRules` | array | false | n/a | Active | Json Logic conditional presentation state. |
 | `presentationMode` | boolean | false | n/a | Partial | See Detailed API reference. |
 | `readonlyMode` | boolean | false | n/a | Partial | See Detailed API reference. |
 | `disabledMode` | boolean | false | n/a | Partial | See Detailed API reference. |

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

@@ -311,7 +311,7 @@ Resumo de composicao deste componente:
 
 ### 4. Mapeamento de Comportamento
 - Trigger em pill + badge de quantidade quando multiplo.
-- Painel com busca em tempo real (termControl) e acoes `Carregar mais`/`Fim de lista`.
+- Painel com busca em tempo real (`termControl`) e rodape compartilhado: o rodape e materializado como irmao do `listbox` no overlay, nunca como opcao. `Carregar mais` e um botao real de largura total e alvo minimo de 44 px; durante a paginacao ele permanece visivel, ocupado e desabilitado. `Tab` transfere o foco da busca para a primeira acao habilitada; `Fim de lista` e um status, fora da semantica de opcoes.
 - Se `resourcePath` ausente, busca opera sobre snapshot local.
 
 ### 5. Exemplo Minimo (JSON + Uso)
@@ -416,7 +416,11 @@ Correcao: ajustar limites em `inlineAutoSize`.
 
 | Token/Class | Scope | Purpose | Notes |
 | --- | --- | --- | --- |
-| `not-yet-verified` | component | Styling contract not yet verified | Use Detailed API reference for component-specific styling notes. |
+| `--pdx-select-panel-actions-surface` / `--pdx-select-panel-actions-on-surface` / `--pdx-select-panel-actions-muted` | overlay footer | Superficie, texto principal e texto secundario | Definir na classe de tema que alcanca o CDK Overlay. Tokens inline e `--pdx-overlay-*` continuam como fallbacks compativeis. |
+| `--pdx-select-panel-actions-outline` / `--pdx-select-panel-actions-accent` | overlay footer | Separador, bordas e cor de acao/foco | Fallbacks Material: divider/outline e primary. |
+| `--pdx-select-panel-action-hover-surface` / `--pdx-select-panel-action-focus-ring` | overlay footer | Estados hover e foco visivel | O host deve preservar contraste AA em temas claro e escuro. |
+| `--pdx-select-panel-load-more-surface` / `--pdx-select-panel-load-more-outline` | overlay footer | Tratamento do botao `Carregar mais` | Permite distinguir a acao sem acoplamento a internals MDC. |
+| `--pdx-select-panel-actions-gap` / `--pdx-select-panel-actions-padding` / `--pdx-select-panel-action-min-height` / `--pdx-select-panel-action-padding` / `--pdx-select-panel-action-radius` / `--pdx-select-panel-action-disabled-opacity` | overlay footer | Densidade, geometria e estado desabilitado | Altura default de 44 px preserva alvo corporativo acessivel. |
 
 ## Examples (obrigatorio)
 

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

@@ -154,7 +154,7 @@ Nao ha paths experimentais confirmados no contrato publico desta revisao.
 | `metadata.touchUi` | boolean | false | n/a | component-defined | Partial; verify per source_of_truth. |
 | `metadata.clearButton` | object | false | n/a | component-defined | Partial; verify per source_of_truth. |
 | `metadata.inlineAutoSize.*` | object | false | n/a | component-defined | Partial; verify per source_of_truth. |
-| `metadata.inlineOverlay.applyMode` | string | false | `auto` | `auto`, `explicit`, `confirm` | Shared inline overlay commit mode; `confirm` is accepted as explicit compatibility. |
+| `metadata.inlineOverlay.applyMode` | string | false | `auto` | `auto`, `explicit` | Shared inline overlay commit mode. |
 | `metadata.inlineOverlay.actions.apply` | object | false | n/a | component-defined | Theme-aware Apply action metadata. |
 | `metadata.inlineOverlay.actions.cancel` | object | false | n/a | component-defined | Theme-aware Cancel action metadata. |
 | `metadata.ariaLabel` | string | false | n/a | component-defined | Partial; verify per source_of_truth. |

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

@@ -40,6 +40,8 @@ related_components:
   - "praxis-table"
   - "pdx-material-date-range"
   - "pdx-base-input-runtime-contract"
+related_docs:
+  - "date-range-rust-host-integration"
 ---
 
 # pdx-inline-date-range
@@ -296,7 +298,8 @@ Use quando precisar:
 | `metadata.inlineAutoSize.*` | `object` | Ativo | Autoajuste de largura da pill. |
 | `metadata.inlineChipDisplay` | `"value" \| "label-value"` | Ativo | Exibicao compacta do chip preenchido: somente valor ou label + valor. |
 | `metadata.clearButton` | `boolean \| object` | Ativo | Botao de limpeza rapida no trigger. |
-| `metadata.inlineQuickPresets*` | `object/array` | Ativo | Presets/acoes especificos do date-range. `inlineQuickPresetsApplyMode` permanece como compatibilidade quando `inlineOverlay.applyMode` nao e declarado. |
+| `metadata.inlineQuickPresets` | `boolean \| { enabled?: boolean; maxVisible?: number; position?: "auto" \| "footer" \| "start" \| "end" }` | Ativo | Controla atalhos inline. `position` usa posicoes logicas, com fallback para `footer` em viewport estreito/touch. |
+| `metadata.shortcuts` | `Array<string \| DateRangePreset \| StaticDateRangePreset>` | Ativo | Mesmo catalogo do `pdx-material-date-range`: built-ins, presets TypeScript e periodos corporativos estaticos serializaveis publicados pelo backend/dominio. |
 | `metadata.inlineOverlay.applyMode` | `"auto" \| "explicit"` | Ativo | Contrato compartilhado de commit do overlay: automatico ou rascunho ate Aplicar. |
 | `metadata.inlineOverlay.actions.apply.*` | `object` | Ativo | Label, aria, appearance e colorRole canonicos do botao Aplicar. |
 | `metadata.inlineOverlay.actions.cancel.*` | `object` | Ativo | Label, aria, appearance e colorRole canonicos do botao Cancelar. |
@@ -316,12 +319,16 @@ Resumo de composicao deste componente:
 - Trigger em pill mostra estado vazio, parcial ou completo do intervalo.
 - Clicar em qualquer area acionavel da pill, incluindo os inputs internos de inicio/fim, abre o calendario; apenas o botao de limpeza rapida fica isolado para limpar sem abrir o overlay.
 - Overlay de calendario inclui presets e botoes de aplicar/cancelar.
+- `inlineQuickPresets.position: "footer"` renderiza atalhos acima das acoes; `"start"` e `"end"` materializam uma rail logica ao lado do calendario quando ha espaco; `"auto"` escolhe rail em desktop e cai para rodape quando necessario.
+- Em modo explicito/confirmacao, selecionar um preset mostra um resumo antes de `Aplicar` com label, descricao quando publicada, inicio, fim e intervalo resolvido. Esse resumo e apenas confirmacao visual/acessivel do rascunho; nao altera o payload canonico.
 - Entrada manual em ambos os campos sincroniza com o valor consolidado do range.
 - Em `inlineOverlay.applyMode: "auto"`, selecao manual no calendario aplica pendencias imediatamente para manter o valor do chip inline sincronizado.
 - Em `inlineOverlay.applyMode: "explicit"`, o chip inline mostra o intervalo em rascunho enquanto o overlay esta aberto; o commit de negocio continua ocorrendo apenas em `Aplicar`, enquanto `Cancelar`, `Esc` ou fechamento externo restauram o valor confirmado.
 - O rodape `Aplicar`/`Cancelar` e materializado pelo contrato `inlineOverlay` mesmo quando nao ha `inlineQuickPresets`, para que confirmacao explicita nao dependa de atalhos rapidos.
 - `inlineQuickPresetsApplyMode: "auto" | "confirm"` continua suportado como fallback legado especifico do `inlineDateRange`.
 - Labels, aria, `appearance` e `colorRole` dos botoes do rodape devem ser authorados em `inlineOverlay.actions.apply` e `inlineOverlay.actions.cancel`; os campos `inlineQuickPresets*Label` sao fallback legado.
+- Atalhos corporativos estaticos nunca executam codigo vindo de JSON; regras fiscais, legais, eleitorais, feriados e dias contaveis permanecem responsabilidade do backend/dominio.
+- Hosts Rust que publicam metadata devem seguir o guia `date-range-rust-host-integration` para DTOs `serde`, validacao de timezone, seguranca e testes de consumidor.
 
 ### 5. Exemplo Minimo (JSON + Uso)
 ```json
@@ -350,10 +357,21 @@ Uso: filtro inline de intervalo de datas.
     "endAriaLabel": "Data final do periodo",
     "inlinePanelTitle": "Selecionar periodo",
     "inlineAutoSize": { "minWidth": 180, "maxWidth": 420 },
-    "inlineQuickPresets": [
-      { "id": "today", "label": "Hoje", "start": "today", "end": "today" },
-      { "id": "last7", "label": "Ultimos 7 dias", "start": "-7d", "end": "today" }
+    "shortcuts": [
+      "today",
+      "thisMonth",
+      {
+        "id": "competencia-fiscal-marco",
+        "label": "Competencia fiscal de marco",
+        "description": "Periodo resolvido pelo dominio fiscal para a competencia de marco.",
+        "startDate": "2026-03-01",
+        "endDate": "2026-03-31",
+        "timeZone": "America/Sao_Paulo",
+        "icon": "account_balance",
+        "tone": "success"
+      }
     ],
+    "inlineQuickPresets": { "enabled": true, "maxVisible": 4, "position": "start" },
     "inlineOverlay": {
       "applyMode": "explicit",
       "actions": {
@@ -377,19 +395,22 @@ Correcao: revisar preenchimento de `startDate/endDate` e parse de input manual.
 3. Selecao manual nao reflete no chip em modo `auto`.
 Correcao: garantir que o componente esteja usando a sincronizacao de pendencias do Datepicker (`_applyPendingSelection`) ao clicar em celulas do calendario no overlay.
 
-4. Botao limpar indisponivel.
+4. Preset corporativo nao explica o intervalo antes de aplicar.
+Correcao: publicar `description` nos presets estaticos quando o nome nao for autoexplicativo e usar `inlineOverlay.applyMode: "explicit"` para permitir revisao antes do commit. O runtime exibe label, descricao, inicio/fim e intervalo do rascunho no resumo pre-Aplicar.
+
+5. Botao limpar indisponivel.
 Correcao: verificar `clearButton` e estado readonly/disabled.
 
-5. Calendario nao abre ao clicar no texto da pill preenchida.
+6. Calendario nao abre ao clicar no texto da pill preenchida.
 Correcao: garantir que o clique nos inputs internos de inicio/fim encaminha para `openPicker`; esses inputs ocupam a maior parte da area visual do chip em cenarios densos de toolbar.
 
-6. Largura do chip estoura em mobile.
+7. Largura do chip estoura em mobile.
 Correcao: ajustar limites no bloco `inlineAutoSize`.
 
-7. ARIA de inicio/fim nao refletida.
+8. ARIA de inicio/fim nao refletida.
 Correcao: preencher `startAriaLabel/endAriaLabel` explicitamente.
 
-8. Layout muda entre apps com densidade diferente.
+9. Layout muda entre apps com densidade diferente.
 Correcao: usar `metadata.materialDesign.density` (`dense` ou `default`) e validar no overlay se `gap/padding` foram aplicados no bloco `.mat-datepicker-actions` com classe de densidade `pdx-inline-date-range-overlay-actions-container--*`.
 
 ### 8. Cross-links

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

@@ -324,7 +324,7 @@ Use quando precisar:
 | `metadata.optionSource.detail.surfaceId` | `string` | Ativo | Id da surface item-level preferida para o detalhe. Quando ausente, o runtime escolhe `detail`, `view` ou a primeira surface item-level de leitura disponivel. |
 | `metadata.optionSource.detail.presentation` | `"drawer" | "modal"` | Ativo | Apresentacao desejada para `surface.open`. Default vem do preset/host de surface. |
 | `metadata.optionSource.detail.preferredWidget` / `metadata.optionSource.detail.mode` | `string` | Documental | Hints semanticos para autoria/discovery. A materializacao final vem da surface descoberta e do `ResourceSurfaceOpenAdapterService`. |
-| `metadata.optionSource.detail.hrefTemplate` / `metadata.optionSource.detail.routeTemplate` | `string` | Legado | Fallback para abrir detalhe por link quando nao houver contrato de surface ou servico global disponivel. Nao deve ser a fonte primaria em novos lookups de plataforma. |
+| `metadata.optionSource.detail.hrefTemplate` / `metadata.optionSource.detail.routeTemplate` | `string` | Legado | Fallback quando nao houver surface governada. Quando ambos existem, `routeTemplate` tem precedencia por representar a rota navegavel do host. `hrefTemplate` que aponta para `/api/**` e tratado como evidencia de recurso, nao como destino de UX, e nao habilita a acao Detalhe isoladamente. |
 | `metadata.optionSource.display.preset` | `"compact" | "rich" | "directory" | "status" | "reference" | "hierarchical"` | Ativo | Define a intencao visual canonica. `directory` e recomendado para pessoas/equipes; `reference` para codigo + descricao; `status` para entidades com estado operacional forte. |
 | `metadata.optionSource.display.usage` | `"form" | "filter" | "table-cell" | "dashboard" | "wizard" | "review"` | Ativo | Indica onde a option-source costuma aparecer. O runtime pode ajustar densidade e acoes sem duplicar regra por host. |
 | `metadata.optionSource.display.density` | `"compact" | "comfortable" | "rich"` | Ativo | Densidade preferencial. Campos de formulario usam `comfortable`; filtros inline e celulas de tabela tendem a `compact`; revisoes podem usar `rich`. |
@@ -341,11 +341,11 @@ Use quando precisar:
 | `metadata.showAvatar` | `boolean` | Ativo | Controla exibicao de avatar por iniciais. Default: `true`. |
 | `metadata.showBadges` | `boolean` | Ativo | Controla exibicao de badges auxiliares vindos de `badges`, `tags`, `riskLevel`, `homologationStatus` ou `badgeKeys`. Default: `true`. |
 | `metadata.showDisabledReason` | `boolean` | Ativo | Controla exibicao do motivo de bloqueio quando `selectable=false`. Default: `true`. |
-| `metadata.showResultCount` | `boolean` | Ativo | Controla contador de resultados no painel de busca. Quando o backend pagina com `totalElements`, mostra o total remoto; em fontes locais/cursor, mostra o total carregado. Default: `true`. |
+| `metadata.showResultCount` | `boolean` | Ativo | Controla contador de resultados no painel de busca. Quando `totalElements` remoto for maior que os itens carregados, mostra `carregados de total` para deixar claro que a lista visivel ainda e uma pagina parcial; em fontes locais/cursor, mostra o total carregado. Default: `true`. |
 | `metadata.statusToneMap` | `Record<string, "success" | "warning" | "danger" | "neutral">` | Ativo | Permite mapear status de dominio para tom visual governado. |
 | `metadata.badgeKeys` | `string[]` | Ativo | Chaves adicionais lidas do valor de entidade para compor badges auxiliares. |
 | `metadata.maxVisibleBadges` | `number` | Ativo | Limita quantidade de badges auxiliares exibidos. Default: `3`. |
-| `metadata.actions.showDetail` | `boolean` | Ativo | Controla acao de detalhe quando houver surface canonica ou fallback `detailHref`/`detailRoute`. Default: `true`. |
+| `metadata.actions.showDetail` | `boolean` | Ativo | Controla acao de detalhe quando houver surface canonica, `detailRoute` navegavel ou `detailHref` nao-API. `detailHref` de API nao abre nova aba para evitar link morto em hosts corporativos. Default: `true`. |
 | `metadata.actions.showChange` | `boolean` | Ativo | Controla acao de troca no cartao selecionado. Default: `true`. |
 | `metadata.actions.showCopyCode` | `boolean` | Ativo | Controla acao de copiar codigo/id. Default: `true`. |
 | `metadata.actions.showClear` | `boolean` | Ativo | Controla acao de limpar em conjunto com `clearButton`/clearable herdado. |
@@ -366,8 +366,11 @@ Resumo de composicao deste componente:
 - `metadata.optionSource.display` e a fonte preferencial de UX para a entidade; campos top-level como `selectedLayout`, `density`, `showAvatar` e `showStatus` funcionam como override local de host.
 - Opcoes podem mostrar linha secundaria (`subtitle`) para desambiguacao; em `entityLookup`, a linha rica tambem mostra avatar, campos ricos com icones/chips/datas, status visual, badges e motivo de bloqueio.
 - Com `metadata.optionSource.resourcePath`, busca emite termo no pipeline remoto de option-source; sem endpoint, filtra local.
+- Em uso standalone de shell/topbar autenticado, o componente aceita `FormControl` externo com `initialMetadata` estático e `options` locais. Um valor inicial já selecionado no controle deve materializar o texto da opção local sem bloquear a montagem da rota nem realimentar change detection quando a metadata recebida for semanticamente equivalente.
 - `metadata.resourcePath` continua aceito como configuracao operacional herdada, mas nao substitui a semantica canonica de entidade publicada em `metadata.optionSource`.
-- Opcao de reset limpa filtro sem fechar contexto de trabalho.
+- As acoes de painel ficam em um rodape materializado como irmao do `listbox` no overlay: `Limpar selecao` e uma acao secundaria alinhada ao inicio; `Carregar mais` e uma acao de largura total, com alvo minimo de 44 px, estado ocupado e foco visivel. `Tab` transfere o foco da busca para a primeira acao habilitada. Nenhuma delas participa da navegacao semantica de opcoes.
+- A reidratacao por IDs preserva o valor selecionado, mas nao conta como carga da pagina zero. No primeiro `open`, o runtime consulta a pagina zero antes de habilitar `Carregar mais`; o contador remoto e a lista visivel permanecem coerentes.
+- Durante busca digitada, a lista visivel mostra apenas resultados retornados pela pagina remota filtrada. O selecionado reidratado por ID nao e injetado como falso resultado, embora continue preservado para display fechado e reabertura sem termo.
 - `OptionDTO.extra.selectable === false` desabilita a opcao e permite exibir `disabledReason` sem remover a entidade da lista ou da reidratacao.
 
 ### 5. Exemplo Minimo (JSON + Uso)
@@ -377,7 +380,7 @@ Resumo de composicao deste componente:
   "metadata": {
     "name": "employee",
     "label": "Funcionario",
-    "controlType": "select",
+    "controlType": "inlineEntityLookup",
     "lookupIdKey": "employeeId",
     "lookupLabelKey": "fullName",
     "selectOptions": [
@@ -408,7 +411,7 @@ Uso: lookup simples em lista local.
       "statusPropertyPath": "status",
       "detail": {
         "kind": "surface",
-        "surfaceId": "view",
+        "surfaceId": "detail",
         "presentation": "drawer",
         "preferredWidget": "praxis-dynamic-form",
         "mode": "view"
@@ -506,7 +509,22 @@ Correcao: ajustar `inlineAutoSize.minWidth/maxWidth`.
 
 | Token/Class | Scope | Purpose | Notes |
 | --- | --- | --- | --- |
-| `not-yet-verified` | component | Styling contract not yet verified | Use Detailed API reference for component-specific styling notes. |
+| `.pdx-entity-lookup-rich` | trigger | Ativa a geometria de campo corporativo | Preserva label Material, subscript e zona de seta com altura integral. |
+| `.pdx-select-panel-actions` | overlay footer | Agrupa acoes auxiliares fora da lista de opcoes | Primitiva interna compartilhada pela familia de selects; nao deve ser transformada em `mat-option`. |
+| `.pdx-select-panel-action.is-clear` | overlay footer | Limpa a selecao atual | Acao secundaria alinhada ao inicio, alvo minimo de 44 px e foco visivel. |
+| `.pdx-select-panel-action.is-load-more` | overlay footer | Solicita a proxima pagina | Acao de largura total com estados normal, hover, focus e loading/disabled. |
+| `.pdx-select-panel-end` | overlay footer | Comunica fim da paginacao | Estado informativo com `role="status"`; nao e interativo. |
+| `--pdx-inline-panel-surface` / `--pdx-inline-panel-surface-raised` | overlay | Superficie base e superficie de estado/selecionado | Definir globalmente no escopo de tema do host, pois o painel vive no CDK Overlay. Fallbacks: `--md-sys-color-surface-container-highest/high`. |
+| `--pdx-inline-panel-on-surface` / `--pdx-inline-panel-on-surface-muted` | overlay | Texto principal e texto auxiliar | Devem manter contraste nos temas claro e escuro. Fallbacks: `--md-sys-color-on-surface/-variant`. |
+| `--pdx-inline-panel-outline` | overlay | Borda e separadores do painel | Fallback: `--md-sys-color-outline-variant`. |
+| `--pdx-entity-lookup-avatar-size` / `--pdx-entity-lookup-avatar-large-size` / `--pdx-entity-lookup-avatar-compact-size` / `--pdx-entity-lookup-avatar-radius` | trigger/panel | Geometria dos avatares por iniciais | Permite ajustar densidade corporativa sem colar icone/texto ou quebrar alinhamento vertical do select. |
+| `--pdx-entity-lookup-avatar-surface` / `--pdx-entity-lookup-avatar-text` | trigger/panel | Cor de avatar por iniciais | Fallbacks usam primary Material com `color-mix`; hosts podem calibrar claro/escuro por tema. |
+| `--pdx-entity-lookup-selected-compact-padding` / `--pdx-entity-lookup-selected-compact-inline-start` | trigger | Respiro do valor selecionado compacto | Deve manter o avatar afastado da borda esquerda, preservar a zona de seta alinhada ao select Material e respeitar o `inline-size` do container em drawers estreitos. |
+| `--pdx-entity-lookup-success-surface` / `--pdx-entity-lookup-success-text` / `--pdx-entity-lookup-warning-surface` / `--pdx-entity-lookup-warning-text` / `--pdx-entity-lookup-warning-outline` / `--pdx-entity-lookup-danger-surface` / `--pdx-entity-lookup-danger-text` / `--pdx-entity-lookup-danger-outline` | trigger/panel | Tons de status, badges e notas de bloqueio/legado | Fallbacks derivam de tokens Material (`primary`, `tertiary`, `error`) para funcionar em temas claro e escuro; hosts regulados podem substituir todos os tons. |
+| `--pdx-select-panel-actions-surface` / `--pdx-select-panel-actions-on-surface` / `--pdx-select-panel-actions-muted` | overlay footer | Superficie, texto principal e texto secundario do rodape | Contrato canonico; os tokens inline acima sao preservados como fallback e transferidos quando definidos no painel. |
+| `--pdx-select-panel-actions-outline` / `--pdx-select-panel-actions-accent` | overlay footer | Separador, bordas e cor de acao/foco | Fallbacks Material: divider/outline e primary. |
+| `--pdx-select-panel-action-hover-surface` / `--pdx-select-panel-action-focus-ring` / `--pdx-select-panel-load-more-surface` / `--pdx-select-panel-load-more-outline` | overlay footer | Estados interativos de limpar/carregar mais | Customizar na classe de tema que alcanca o CDK Overlay e validar contraste claro/escuro. |
+| `--pdx-select-panel-actions-gap` / `--pdx-select-panel-actions-padding` / `--pdx-select-panel-action-min-height` / `--pdx-select-panel-action-padding` / `--pdx-select-panel-action-radius` / `--pdx-select-panel-action-disabled-opacity` | overlay footer | Densidade, geometria e estado desabilitado | Altura default de 44 px preserva alvo corporativo acessivel. |
 
 ## Examples (obrigatorio)
 
@@ -525,7 +543,7 @@ Correcao: ajustar `inlineAutoSize.minWidth/maxWidth`.
   "metadata": {
     "name": "employee",
     "label": "Funcionario",
-    "controlType": "select",
+    "controlType": "inlineEntityLookup",
     "lookupIdKey": "employeeId",
     "lookupLabelKey": "fullName",
     "selectOptions": [
@@ -548,7 +566,7 @@ Correcao: ajustar `inlineAutoSize.minWidth/maxWidth`.
   "metadata": {
     "name": "costCenterOwner",
     "label": "Responsavel",
-    "controlType": "select",
+    "controlType": "inlineEntityLookup",
     "resourcePath": "employees/options",
     "lookupIdKey": "matricula",
     "lookupLabelKey": "nome",

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

@@ -301,6 +301,7 @@ Resumo de composicao deste componente:
 
 ### 4. Mapeamento de Comportamento
 - Modo percentual ajusta semantica visual e valores default de faixa/passo.
+- `metadata.inlineVisualStyle = "graphic"` materializa leitura percentual enriquecida, mas o componente suprime gauge/rail decorativos quando esta dentro de `praxis-filter` compacto para manter a barra densa e escaneavel.
 - Campo recalcula largura com base no conteudo/placeholder e limites configurados.
 - Validadores `min/max` sao aplicados no control conforme metadata.
 

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

@@ -305,6 +305,8 @@ Use quando precisar:
 | `metadata.inlineOverlay.actions.apply/cancel/clear` | `object` | Ativo | Labels, aria, icones, `appearance` e `colorRole` das acoes do painel, materializados por tokens do tema. |
 | `metadata.quickPresets` | `array` | Ativo | Presets herdados do range inline para faixa de rating. |
 
+Quando `allowHalf`/`ratingAllowHalf` ou a precisao de `0.5` estiver ativa, as estrelas do painel tambem aceitam selecao direta: clique na metade esquerda para selecionar o meio ponto anterior e na metade direita para o ponto inteiro. A selecao por estrela cria uma faixa pontual (`start = end`); use o slider para abrir uma faixa. Em `inlineOverlay.applyMode: "explicit"`, a selecao direta permanece em rascunho ate `Aplicar`.
+
 #### 3.2 Campos herdados compartilhados (exaustivo)
 - `projects/praxis-dynamic-fields/src/lib/components/inlineRange/pdx-inline-range-slider.json-api.md`
 - `projects/praxis-dynamic-fields/src/lib/components/material-range-slider/pdx-material-range-slider.json-api.md`

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

@@ -300,7 +300,7 @@ Use quando precisar:
 | `metadata.relativePeriodIconKey/optionIconKey` | `string` | Ativo | Chave do ícone por opção. |
 | `metadata.relativePeriodSubtitleKey/optionSubtitleKey` | `string` | Ativo | Chave de subtítulo por opção. |
 | `metadata.relativePeriodTexts` / `inlineTexts` | `object \| string(JSON)` | Ativo | Textos de labels, empty state e aria; templates canônicos devem usar `{{label}}` e `{{percent}}` quando houver interpolação, com compatibilidade legada para `{...}` em metadata. |
-| `metadata.inlineOverlay.applyMode` | `"auto" \| "explicit" \| "confirm"` | Ativo | Quando `explicit`/`confirm`, seleções ficam em rascunho até `Aplicar`. |
+| `metadata.inlineOverlay.applyMode` | `"auto" \| "explicit"` | Ativo | Quando `explicit`, seleções ficam em rascunho até `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 explícita. |
@@ -319,7 +319,7 @@ Resumo de composição deste componente:
 - Em single mode, pode fechar automaticamente por `relativePeriodCloseOnSelect`.
 - Barra de progresso calcula posição da opção selecionada no conjunto.
 - Busca filtra opções por label/subtítulo antes da seleção.
-- Com `inlineOverlay.applyMode: "explicit"` ou `"confirm"`, clique em card altera apenas o rascunho do painel; `Aplicar` comita, enquanto `Cancelar`, `Esc`, detach ou clique externo descartam.
+- Com `inlineOverlay.applyMode: "explicit"`, clique em card altera apenas o rascunho do painel; `Aplicar` comita, enquanto `Cancelar`, `Esc`, detach ou clique externo descartam.
 
 ### 5. Exemplo Mínimo (JSON + Uso)
 ```json

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

@@ -308,6 +308,7 @@ Resumo de composicao deste componente:
 - `Extensao de runtime`: `searchPlaceholder` e `inlineAutoSize.*`.
 
 ### 4. Mapeamento de Comportamento
+- A paginacao usa o rodape compartilhado da familia de selects, materializado como irmao do `listbox` no overlay: botao `Carregar mais` com alvo minimo de 44 px, estado ocupado sem salto de layout e acesso por `Tab` a partir da busca. A acao nao participa da semantica de opcoes.
 - Trigger exibe label e, em modo multiplo, badge de quantidade.
 - Painel contem input de busca e estados de loading/fim de lista.
 - Quando sem `resourcePath`, usa filtragem local da lista estatica.
@@ -418,7 +419,11 @@ Correcao: quick-clear respeita estados readonly/disabled/presentation.
 
 | Token/Class | Scope | Purpose | Notes |
 | --- | --- | --- | --- |
-| `not-yet-verified` | component | Styling contract not yet verified | Use Detailed API reference for component-specific styling notes. |
+| `--pdx-select-panel-actions-surface` / `--pdx-select-panel-actions-on-surface` / `--pdx-select-panel-actions-muted` | overlay footer | Superficie, texto principal e texto secundario | Definir na classe de tema que alcanca o CDK Overlay. Tokens inline e `--pdx-overlay-*` continuam como fallbacks compativeis. |
+| `--pdx-select-panel-actions-outline` / `--pdx-select-panel-actions-accent` | overlay footer | Separador, bordas e cor de acao/foco | Fallbacks Material: divider/outline e primary. |
+| `--pdx-select-panel-action-hover-surface` / `--pdx-select-panel-action-focus-ring` | overlay footer | Estados hover e foco visivel | O host deve preservar contraste AA em temas claro e escuro. |
+| `--pdx-select-panel-load-more-surface` / `--pdx-select-panel-load-more-outline` | overlay footer | Tratamento do botao `Carregar mais` | Permite distinguir a acao sem acoplamento a internals MDC. |
+| `--pdx-select-panel-actions-gap` / `--pdx-select-panel-actions-padding` / `--pdx-select-panel-action-min-height` / `--pdx-select-panel-action-padding` / `--pdx-select-panel-action-radius` / `--pdx-select-panel-action-disabled-opacity` | overlay footer | Densidade, geometria e estado desabilitado | Altura default de 44 px preserva alvo corporativo acessivel. |
 
 ## Examples (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

@@ -22,8 +22,8 @@ source_of_truth:
   - "projects/praxis-dynamic-fields/src/lib/components/material-async-select/material-async-select.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-03-06"
-last_updated: "2026-03-06"
+source_of_truth_last_verified: "2026-07-06"
+last_updated: "2026-07-06"
 toc: true
 sidebar: true
 tags:
@@ -318,7 +318,12 @@ Garantias:
 
 - input de busca e carga incremental estao habilitados no painel.
 - `loadOn` controla a primeira carga (`open`, `init`, `none`).
+- Uma falha na carga inicial nao marca o campo como carregado: com `loadOn='open'`, reabrir o painel tenta novamente; somente uma resposta processada com sucesso conclui a carga inicial.
 - `useCursor` pode trocar estrategia de pagina quando backend suporta cursor.
+- Com `resourcePath` e `loadOn='open'`, o painel abre mesmo antes da primeira pagina remota para disparar a carga inicial; a opcao sentinela usada para isso e interna, invisivel e nao compoe contrato visual publico.
+- `Carregar mais` so aparece depois de uma primeira pagina remota carregada com sucesso e com proxima pagina disponivel; durante a paginacao permanece visivel, ocupado e desabilitado para evitar requisicoes duplicadas e salto de layout. A acao usa o rodape compartilhado, materializado como irmao do `listbox` no overlay, tem alvo minimo de 44 px, recebe foco por `Tab` a partir da busca e nao participa da semantica de opcoes.
+- fontes locais (`selectOptions`/`options`) e `loadOn='none'` antes da primeira carga nao exibem acao de paginacao.
+- em paginacao numerada, o fim usa `totalPages`/`totalElements` quando fornecidos pelo backend; se ausentes, usa `content.length < pageSize` como fallback.
 
 Limites:
 
@@ -351,6 +356,7 @@ Precedencia de comportamento:
 #### Checklist corporativo
 
 - alinhe backend para pesquisa por termo e include de selecionados.
+- retorne `totalPages` e `totalElements` consistentes para evitar chamadas extras de paginacao.
 - padronize `optionLabelKey`/`optionValueKey` entre dominios.
 - defina `dependencyLoadOnChange` conforme UX esperada em cascata.
 - use `maxSelections` quando multi-select exigir limite de negocio.
@@ -393,8 +399,13 @@ 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` e nao ha termo de busca ativo; quando ausente, `false` ou durante busca digitada, valores selecionados sao reidratados por `/option-sources/{sourceKey}/options/by-ids`.
+- durante busca digitada, a lista visivel usa apenas os itens da pagina remota filtrada. Opcoes reidratadas por ID preservam o display fechado, mas nao podem substituir ou inflar o resultado da busca.
+- em `optionSource`, dependencias declaradas por `dependsOn` e `dependencyFilterMap` sao materializadas como filtros estruturados `equals` no envelope canonico de opcoes.
 - `onSearch` limpa estado local e reinicia pagina para novo termo.
+- `loadMore` nao inicia a primeira carga remota; a primeira pagina respeita `loadOn`, abertura do painel, reload explicito ou mudanca de dependencia.
+- `loadMore` incrementa pagina somente quando ja existe pagina remota carregada e `endReached=false`.
 
 Contrato compartilhado completo:
 
@@ -416,8 +427,8 @@ Correcao: revise `loadOn`, `resourcePath` e permissao de endpoint.
 3. Filtro remoto usa campo errado.
 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.
+4. Item selecionado aparece como unico resultado de uma busca que deveria retornar outro item.
+Correcao: durante busca, nao envie `includeIds` nem force `ensureVisible` do selecionado; a lista deve refletir a pagina remota filtrada. O selecionado continua preservado pela reidratacao `/by-ids` para display fechado e reabertura sem termo.
 
 5. Cascata nao atualiza automaticamente.
 Correcao: use `dependencyLoadOnChange='immediate'` ou dispare recarga no host.
@@ -459,7 +470,11 @@ Correcao: use `dependencyLoadOnChange='immediate'` ou dispare recarga no host.
 
 | Token/Class | Scope | Purpose | Notes |
 | --- | --- | --- | --- |
-| `not-yet-verified` | component | Styling contract not yet verified | Use Detailed API reference for component-specific styling notes. |
+| `--pdx-select-panel-actions-surface` / `--pdx-select-panel-actions-on-surface` / `--pdx-select-panel-actions-muted` | overlay footer | Superficie, texto principal e texto secundario | Definir na classe de tema que alcanca o CDK Overlay. Tokens `--pdx-overlay-*` e inline continuam como fallbacks compativeis. |
+| `--pdx-select-panel-actions-outline` / `--pdx-select-panel-actions-accent` | overlay footer | Separador, bordas e cor de acao/foco | Fallbacks Material: divider/outline e primary. |
+| `--pdx-select-panel-action-hover-surface` / `--pdx-select-panel-action-focus-ring` | overlay footer | Estados hover e foco visivel | O host deve preservar contraste AA em temas claro e escuro. |
+| `--pdx-select-panel-load-more-surface` / `--pdx-select-panel-load-more-outline` | overlay footer | Tratamento do botao `Carregar mais` | Permite distinguir a acao sem acoplamento a internals MDC. |
+| `--pdx-select-panel-actions-gap` / `--pdx-select-panel-actions-padding` / `--pdx-select-panel-action-min-height` / `--pdx-select-panel-action-padding` / `--pdx-select-panel-action-radius` / `--pdx-select-panel-action-disabled-opacity` | overlay footer | Densidade, geometria e estado desabilitado | Altura default de 44 px preserva alvo corporativo acessivel. |
 
 ## Examples (obrigatorio)
 

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. |