@praxisui/dynamic-form 3.0.0-beta.0 → 3.0.0-beta.10

package/README.md

@@ -133,6 +133,26 @@ export class FormDemoComponent {
 Tip: connect to a backend resource by setting `resourcePath`/`resourceId`. The component can fetch schemas and reconcile local layout with server metadata when `enableCustomization` is true.
 When a late `config` hydration rebuilds the surface, the runtime preserves the current form values already mounted in memory only when the logical context remains the same (`resourcePath`, `resourceId`, and mode). If the form was preloaded from `resourceId`, that entity hydration remains visible after the rebuild only for the same entity context; entity switches and create-mode transitions do not restore the previous record snapshot.
 
+Presentation/read-only note:
+- `praxis-dynamic-form` hospeda `FieldMetadata`, mas não é o resolvedor direto de `valuePresentation`.
+- quando campos entram em modo view/presentation, a semântica de apresentação vem do metadata do campo e é resolvida por `@praxisui/dynamic-fields`.
+
+## Canonical editorial resolution for field editors
+
+Para nome, descricao e icone do tipo de campo no configurador/layout editor e no titulo do metadata editor:
+
+- `@praxisui/dynamic-form` nao mantem mapa editorial local por `controlType`;
+- a resolucao canonica vem de `ComponentMetadataRegistry.resolveEditorial(..., { namespace: 'dynamicFields' })`;
+- aliases e normalizacao de `controlType` sao apenas ponte tecnica de lookup, nao fonte de copy;
+- quando nao existe descriptor canonico para aquele tipo, o fallback aceito e tecnico/neutro.
+
+Fronteira operacional:
+
+- package-owned fields de `@praxisui/dynamic-fields`: consomem descriptor editorial canonico da lib;
+- `ComponentDocMeta` desses fields e derivado, nao a origem semantica;
+- catalogo/showcase continua derivado;
+- custom types do host seguem suportados via `ComponentMetadataRegistry.register(ComponentDocMeta)`, sem exigir mapa local no form.
+
 ### Canonical DI contract for hosts
 
 `praxis-dynamic-form` does not register `GenericCrudService` internally.
@@ -383,6 +403,7 @@ See public exports: `projects/praxis-dynamic-form/src/public-api.ts`.
 
 - `FormSection.icon` continua suportado como identidade visual estática do header.
 - `FormSection.sectionHeader` amplia o contrato para permitir avatar resolvido a partir do `formData`, sem perder compatibilidade com `icon`.
+- `FormSection.headerActions` permite ações iconográficas no canto direito do header da seção, reutilizando o mesmo output `customAction` com `source: 'section-header'` e `sectionId`.
 - Modos suportados:
   - `icon`: usa o ícone estático da seção e, se ele estiver vazio, pode reutilizar `fallbackIcon` como identidade visual explícita do header.
   - `avatar-image`: tenta resolver uma imagem a partir de `sourceField`.
@@ -393,8 +414,16 @@ See public exports: `projects/praxis-dynamic-form/src/public-api.ts`.
   - `initialsSourceField`: field textual usado para derivar iniciais.
   - `altField`: field usado como texto acessível do avatar e fallback textual para iniciais.
   - `fallbackIcon`: ícone usado quando a fonte dinâmica estiver vazia ou inválida, e também como fallback explícito do modo `icon` quando `FormSection.icon` não estiver definido.
-  - `emptyState`: `fallback-icon`, `placeholder-avatar` ou `none`, útil sobretudo em fluxos `create`; o padrão efetivo é `placeholder-avatar`, neutro para qualquer domínio.
+  - `emptyState`: `fallback-icon`, `placeholder-avatar` ou `none`, útil sobretudo em fluxos `create`; o padrão efetivo é `placeholder-avatar`, neutro para qualquer domínio. Quando `fallback-icon` é usado, o ícone permanece dentro da moldura/avatar e continua obedecendo `size`.
+  - `size`: tamanho semântico do avatar (`sm`, `md` ou `lg`), materializado pelo runtime por meio dos tokens `--pfx-form-section-avatar-size*`.
   - `initialsMaxLength`: máximo de letras no avatar textual, normalizado para `1..4`.
+- Campos principais de `headerActions[]`:
+  - `id`, `label`, `icon`
+  - `action` (opcional; se vazio, usa `id`; quando informado, ele vira o nome lógico emitido e a base de rules/mensagens)
+  - `tooltip` (opcional; se vazio, usa `label`)
+  - `color`, `visible`, `disabled`, `loading`
+  - `className` (classe CSS opcional aplicada ao botão do header)
+  - `style` (objeto de estilo inline opcional; no editor é informado como JSON)
 - Formatos de imagem aceitos pelo runtime:
   - URL
   - data URL base64
@@ -417,13 +446,15 @@ Os paths micro são normalizados para `fieldMetadata[].<prop>` para garantir que
 
 ## Regras de formulário (novo contrato)
 
-- Formato: cada regra tem `targetType` (`field | section | action | row | column`), `targets: string[]` (IDs canônicos, sem prefixo), e `effect` com `condition` (DSL ou Specification), `properties` e `propertiesWhenFalse`.
-- Compatibilidade: regras antigas (`context/targetField`) são migradas para `properties/targets` automaticamente; prefixos `section:/action:/row:/column:` são removidos e `targetType` é inferido se não vier explicitado.
+- Formato: cada regra tem `targetType` (`field | section | action | row | column`), `targets: string[]` (IDs canônicos do alvo), e `effect` com `condition` (DSL ou Specification), `properties` e `propertiesWhenFalse`.
+- Compatibilidade: regras antigas (`context/targetField`) são migradas para `properties/targets` automaticamente; prefixes legados `section:/action:/row:/column:` continuam sendo normalizados quando representarem alvos tradicionais. Para header actions de seção, o ID canônico é preservado como `section:<sectionId>:header-action:<actionLogicalId>`.
 - Semântica de limpeza: valores `null` em `properties/propertiesWhenFalse` removem o override e retornam ao valor base do layout; ausência mantém o valor base.
 - Whitelist por tipo (somente propriedades a seguir são aplicadas; demais são descartadas e logadas em dev):
   - `field`: `visible`, `required`, `readonly`, `disabled`, `className`, `style`, `label`, `description`, `placeholder`, `hint`, `tooltip`, `prefixIcon`, `suffixIcon`, `prefixText`, `suffixText`, `defaultValue`, `options` (array `{label,value,disabled?}`), `appearance` (`fill|outline`), `color` (`primary|accent|warn`), `floatLabel` (`auto|always|never`), `hintPosition` (`start|end`), `validators` (primitivos por chave).
-  - `section`: `visible`, `title`, `description`, `icon`, `sectionHeader` (objeto rico) e tambem subpropriedades tipadas como `sectionHeader.mode`, `sectionHeader.sourceField`, `sectionHeader.initialsSourceField`, `sectionHeader.altField`, `sectionHeader.fallbackIcon`, `sectionHeader.emptyState`, `sectionHeader.initialsMaxLength`, `className`, `style`, `collapsible`, `collapsed`, `headerTooltip`, `headerAlign` (`start|center`), `appearance` (`card|plain|step`), `stepLabel`, gaps (`gapBottom`, `titleGapBottom`, `descriptionGapBottom`), cores/tipografia (`titleColor`, `descriptionColor`, `titleStyle`, `descriptionStyle`).
+  - `section`: `visible`, `title`, `description`, `icon`, `sectionHeader` (objeto rico), `headerActions` (ações contextuais do cabeçalho) e tambem subpropriedades tipadas como `sectionHeader.mode`, `sectionHeader.sourceField`, `sectionHeader.initialsSourceField`, `sectionHeader.altField`, `sectionHeader.fallbackIcon`, `sectionHeader.emptyState`, `sectionHeader.size`, `sectionHeader.initialsMaxLength`, `className`, `style`, `collapsible`, `collapsed`, `headerTooltip`, `headerAlign` (`start|center`), `appearance` (`card|plain|step`), `stepLabel`, gaps (`gapBottom`, `titleGapBottom`, `descriptionGapBottom`), cores/tipografia (`titleColor`, `descriptionColor`, `titleStyle`, `descriptionStyle`).
   - `action`: `visible`, `disabled`, `loading`, `label`, `icon`, `tooltip`, `color` (`primary|accent|warn|basic`), `variant` (`raised|stroked|flat|fab`), `size` (`small|medium|large`), `className`, `style`.
+- IDs canônicos de regras para actions do header de seção usam o formato `section:<sectionId>:header-action:<actionLogicalId>`, evitando colisão com botões globais e com ações repetidas em seções diferentes.
+- Se a seção ainda não tiver `id`, o runtime aceita o fallback `header-action:<actionLogicalId>` por compatibilidade; para contratos persistidos, prefira sempre materializar `section.id`.
   - `row`: `visible`, `gap`, `rowGap`, `className`, `style`.
   - `column`: `visible`, `span`, `offset`, `order`, `hidden`, `align` (`start|center|end|stretch`), `padding`, `className`, `style`.
 - Runtime (FormRulesService): filtra por whitelist, converte tipos (enum/number/boolean/string), saneia objetos (`options/validators/style`), aplica remoção de chaves com `null` e retorna mapas `fieldProps/sectionProps/actionProps/rowProps/columnProps`.
@@ -519,6 +550,13 @@ Dicas
 - Tokens M3: prefira `--md-sys-*` para cores/superfícies.
 - Mobile: ative `collapseToMenu` para colapsar botões extras em menu nas telas pequenas.
 - A classe de tema é decisão do host (`.dark-theme` ou `.theme-dark`/`.theme-light`); mantenha tokens e componentes no mesmo escopo.
+- Editor integrado:
+  - `Ações > Botões Customizados` permite editar `label`, `icon`, `color`, `variant`, `size`, `tooltip`, `shortcut`, `className`, `disabled`, `loading` e `style` (JSON).
+  - `Seção > Cabeçalho` permite editar `headerActions[]` sem JSON manual, incluindo adicionar, remover e reordenar ações do header.
+  - No campo `action`, o editor sugere o catálogo global canônico do core e mantém fallback para ação customizada livre; o valor salvo continua compatível com `action` textual legado.
+  - Ações globais no header seguem o mesmo princípio operacional do restante da plataforma: dependem de executor no app (`ActionResolver`) e validam parâmetro obrigatório quando o catálogo exigir.
+  - Para `surface.open`, o editor expõe o authoring especializado da surface em vez de reduzir tudo a texto cru.
+  - A mesma aba permite reordenar `actions.custom[]` pelos controles de mover para cima/baixo; a ordem salva é a mesma ordem renderizada no runtime, sempre depois de `submit/cancel/reset`.
 
 ### Tokens M3 obrigatórios (host)