@praxisui/dynamic-fields 9.0.0-beta.20 → 9.0.0-beta.21

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/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/types/praxisui-dynamic-fields.d.ts

@@ -5994,6 +5994,7 @@ declare class MaterialCheckboxGroupComponent extends SimpleBaseSelectComponent i
     onCheckboxControlKeydown(event: KeyboardEvent): void;
     private syncDisabledModeControlState;
     setSelectMetadata(metadata: SimpleSelectMetadata<unknown>): void;
+    setExternalControl(control: AbstractControl): void;
     /** Disables options when maxSelections reached */
     isOptionDisabled(option: SelectOption<unknown>): boolean;
     protected getSpecificCssClasses(): string[];
@@ -6029,6 +6030,8 @@ declare class MaterialCheckboxGroupComponent extends SimpleBaseSelectComponent i
     private shouldToggleFromBooleanContent;
     private shouldToggleFromMultipleContent;
     private toggleBooleanCheckbox;
+    private normalizeBooleanControlValue;
+    private coerceBooleanControlValue;
     private syncBooleanOperationalEvents;
     private humanizeName;
     optionLabelId(option: SelectOption<unknown>): string;