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

package/docs/dynamic-fields-field-catalog.md

@@ -179,7 +179,7 @@ Use `stateInitialValues` apenas quando o valor do preset precisa continuar coere
 
 | Field         | controlType                                   | Quando usar                                                                                           | Quando evitar                                    | Valor esperado                | Snippet                                                                         | Detail doc                                |
 | ------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------ | ----------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------- |
-| Checkbox      | <span id="checkbox"></span>`checkbox`         | booleano simples com `selectionMode: 'boolean'` ou multiplas escolhas com `selectionMode: 'multiple'` | contrato novo sem `selectionMode`; escolha unica | `boolean \| unknown[]`        | `{ name: 'privacyConsent', controlType: 'checkbox', selectionMode: 'boolean' }` | `pdx-material-checkbox-group.json-api.md` |
+| Checkbox      | <span id="checkbox"></span>`checkbox`         | booleano simples com `selectionMode: 'boolean'` ou múltiplas escolhas com `selectionMode: 'multiple'`; em migrações, flags `S`/`N` e `1`/`0` são normalizadas no modo booleano | contrato novo sem `selectionMode`; escolha única | `boolean \| unknown[]`        | `{ name: 'privacyConsent', controlType: 'checkbox', selectionMode: 'boolean' }` | `pdx-material-checkbox-group.json-api.md` |
 | Radio group   | <span id="radio"></span>`radio`               | escolha unica explicita com `selectionMode: 'single'`                                                 | muitas opcoes/espaco restrito                    | `string \| number \| boolean` | `{ name: 'priority', controlType: 'radio', selectionMode: 'single' }`           | `pdx-material-radio-group.json-api.md`    |
 | Toggle        | <span id="toggle"></span>`toggle`             | booleano binario                                                                                      | multiplos estados                                | `boolean`                     | `{ name: 'active', controlType: 'toggle' }`                                     | `pdx-material-slide-toggle.json-api.md`   |
 | Button toggle | <span id="buttontoggle"></span>`buttonToggle` | escolha segmentada curta                                                                              | listas longas                                    | `string \| number`            | `{ name: 'mode', controlType: 'buttonToggle' }`                                 | `pdx-material-button-toggle.json-api.md`  |

package/docs/dynamic-fields-field-selection-guide.md

@@ -37,7 +37,7 @@ keywords:
   - "select vs autocomplete"
   - "custom host field"
   - "inline filter"
-last_updated: "2026-06-01"
+last_updated: "2026-06-25"
 ---
 
 # Dynamic Fields Field Selection Guide
@@ -187,7 +187,29 @@ Se o caso e filtro corporativo compacto, consulte:
 - [Dynamic Fields Inline Filter Catalog](./dynamic-fields-inline-filter-catalog.md)
 - [Dynamic Fields Inline Components Guide](./dynamic-fields-inline-components-guide.md)
 
-## 6. Decision table
+## 6. Presentation mode vs chart widget
+
+`presentation.presenter = 'microVisualization'` nao e um `controlType`. Use esse presenter quando o campo ja tem valor no `FormControl`, mas a surface readonly precisa mostrar um indicador compacto e escaneavel.
+
+Use `microVisualization` quando:
+
+- a surface e `form-presentation`, `table-cell`, `list-item`, `object-header` ou `card-summary`;
+- a leitura precisa caber em celula, linha, drawer ou detalhe compacto;
+- o indicador e pequeno, como `comparison`, `stackedBar`, `bullet` ou `delta`;
+- a mesma semantica deve ser dirigida por `presentationRules` e Json Logic sem mutar o valor do campo.
+
+Use `@praxisui/charts` quando:
+
+- o usuario precisa interagir com grafico, legenda, tooltip analitico ou drilldown;
+- o grafico ocupa card, dashboard, cockpit ou modal dedicado;
+- a visualizacao depende de series maiores, eixos, zoom ou agregacoes vindas de endpoint analitico.
+
+Use `rich-content` quando:
+
+- o bloco mistura timeline, record summary, property sheet, progresso, badges e textos;
+- a surface de detalhe precisa composicao editorial, nao apenas um valor de campo.
+
+## 7. Decision table
 
 | Question | Prefer |
 | --- | --- |
@@ -211,12 +233,14 @@ Se o caso e filtro corporativo compacto, consulte:
 | ha uma colecao repetivel de objetos? | `array` |
 | ha anexos? | `upload` |
 | o controle e acao, nao dado? | `button` |
+| o valor readonly precisa de indicador compacto em celula/lista/formulario? | `presentation.presenter = "microVisualization"` |
 | nada do catalogo resolve sem gambiarra? | field custom do host |
 
-## 7. Enterprise recommendations
+## 8. Enterprise recommendations
 
 - prefira nomes canonicos de `controlType`; deixe aliases apenas para compatibilidade;
 - nao use inline filter controls em formularios normais para “economizar espaco”;
+- nao crie `controlType` local para indicadores readonly; use `presentation.presenter` e `presentation.visualization` quando a semantica for de apresentacao;
 - para campos remotos, explicite origem de dados e comportamento de busca;
 - para entidades de negocio, use `entityLookup` com `optionSource.type = RESOURCE_ENTITY`, `byIds`, `dependsOn`, `dependencyFilterMap` e `selectionPolicy` quando a selecao depender de status, permissao ou contexto;
 - para colecoes repetiveis, use `array` com `array.itemSchema.fields` em vez de criar campos numerados como `item1`, `item2`, `item3`;