@praxisui/dynamic-fields 3.0.0-beta.6 → 3.0.0-beta.8

package/README.md

@@ -64,6 +64,18 @@ last_updated: "2026-03-07"
 - Headless UI and design systems
 - Data-driven forms
 
+## Value Presentation
+
+Em estados read-only/display, `dynamic-fields` prefere o contrato canônico `valuePresentation` quando ele existir no metadata do campo.
+
+Regras práticas:
+- use `valuePresentation` para valores escalares de display, como `currency`, `number`, `date`, `datetime`, `time`, `percentage` e `boolean`
+- mantenha `format`, `numericFormat`, `currency`, `numberFormat` e `locale` apenas como bridge legado quando necessário
+- `valuePresentation` não é o contrato certo para ranges, selections e IDs semânticos
+- precedência prática: `field.valuePresentation` -> hints legados mapeáveis -> `localization` da superfície/campo -> `LOCALE_ID`
+- `controlType` ajuda o runtime a inferir fallback quando o metadata antigo ainda é usado, mas não substitui a semântica de apresentação
+- em `presentationMode` puro, o runtime renderiza o valor formatado no shell e evita instanciar o componente interativo escondido, reduzindo side effects e deriva de valor
+
 Biblioteca de campos dinâmicos para aplicações Angular (v20+) com Material Design. Renderiza campos a partir de metadados, com carregamento lazy e integração com Reactive Forms.
 
 ## Instalação
@@ -152,6 +164,23 @@ const isRegistered = registry.isRegistered(FieldControlType.INPUT);
 - `projects/praxis-dynamic-fields/docs/dynamic-fields-inline-components-guide.md` (slug: `dynamic-fields-inline-components-guide`)
 - `projects/praxis-dynamic-fields/docs/generic-crud-service.md`
 
+## Editorial governance
+
+Para fields mantidos pela propria lib, a semantica editorial canonica nasce em `src/lib/editorial/**`.
+
+Fronteira oficial:
+
+- `ComponentMetadataEditorialDescriptor`: fonte canonica de `friendlyName`, `description`, `tooltip`, `icon`, bindings e i18n para familias governadas.
+- `ComponentDocMeta`: artefato derivado para builders, discovery e compatibilidade de runtime; nao deve redefinir copy editorial da mesma familia governada.
+- `dynamic-fields-playground.catalog.ts`: camada derivada para showcase/discovery; pode adicionar `recommendedWhen`, `avoidWhen`, estados e snippets, mas nao deve reinventar copy canonica.
+- `@praxisui/dynamic-form`: consumidor; resolve nome/icone/descricao via `ComponentMetadataRegistry.resolveEditorial(..., { namespace: 'dynamicFields' })`.
+
+Estado atual da trilha:
+
+- a governanca editorial canonica cobre a wave 1 registrada em `dynamic-fields-wave-1.registry.ts`;
+- familias fora da wave 1 ainda podem expor `ComponentDocMeta` proprio, mas isso nao as transforma em nova fonte canonica;
+- ao promover uma nova familia para a trilha canonica, a ordem correta e: descriptor editorial -> metadata derivado -> catalogo derivado -> consumo no `dynamic-form`.
+
 ### Componentes Suportados
 
 A fonte de verdade do suporte default e o `ComponentRegistryService`.