@praxisui/dynamic-form 9.0.4-rc.2 → 9.0.4-rc.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@praxisui/dynamic-form",
-  "version": "9.0.4-rc.2",
+  "version": "9.0.4-rc.21",
   "description": "Angular dynamic form engine for Praxis UI: metadata-driven forms, hooks, and services integrating @praxisui/* packages.",
   "peerDependencies": {
     "@angular/common": "^21.0.0",
@@ -9,13 +9,13 @@
     "@angular/forms": "^21.0.0",
     "@angular/material": "^21.0.0",
     "@angular/router": "^21.0.0",
-    "@praxisui/ai": "^9.0.4-rc.2",
-    "@praxisui/dynamic-fields": "^9.0.4-rc.2",
-    "@praxisui/metadata-editor": "^9.0.4-rc.2",
-    "@praxisui/rich-content": "^9.0.4-rc.2",
-    "@praxisui/settings-panel": "^9.0.4-rc.2",
-    "@praxisui/visual-builder": "^9.0.4-rc.2",
-    "@praxisui/core": "^9.0.4-rc.2",
+    "@praxisui/ai": "^9.0.4-rc.21",
+    "@praxisui/dynamic-fields": "^9.0.4-rc.21",
+    "@praxisui/metadata-editor": "^9.0.4-rc.21",
+    "@praxisui/rich-content": "^9.0.4-rc.21",
+    "@praxisui/settings-panel": "^9.0.4-rc.21",
+    "@praxisui/visual-builder": "^9.0.4-rc.21",
+    "@praxisui/core": "^9.0.4-rc.21",
     "rxjs": "^7.8.0"
   },
   "dependencies": {

package/src/lib/praxis-dynamic-form.json-api.md

@@ -232,20 +232,25 @@ O host deve persistir `formSubmit.formData` para fluxos normais. `formSubmit.raw
 ### Input bindings
 
 `initialValue` is an active component input for host-authored or complementary
-field values. The runtime applies it as local initial state without redefining
-the canonical remote entity loaded through `resourcePath` and `resourceId`.
+field values. In `edit/view`, the runtime applies it without redefining the
+canonical remote entity loaded through `resourcePath` and `resourceId`. In
+`create`, including item-scoped command forms, it is the only supported source
+of initial values: a contextual `resourceId` never triggers entity hydration.
 
 | Binding/Path | Type | Required | Source | Runtime normalization | Notes |
 | --- | --- | --- | --- | --- | --- |
 | `config` | `FormConfig` | Conditional | component-input | `normalizeFormConfig(config)` | Contrato principal quando fornecido diretamente pelo host. |
 | `resourcePath` | `string \| undefined` | Conditional | component-input | `crud.configure(resourcePath)` | Endpoint base para schema e dados remotos. Alternativa canônica: `schemaUrl` explícito. |
-| `resourceId` | `string \| number \| undefined` | No | component-input | update `pendingEntityId` + `loadEntity()` | Carrega entidade em modo `edit/view`. |
+| `resourceId` | `string \| number \| undefined` | No | component-input | update `pendingEntityId`; hydrate only in `edit/view` | Carrega entidade em modo `edit/view`. Em `create`, pode identificar o item dono de um comando sem iniciar leitura nem bloquear os campos. |
 | `mode` | `'create' \| 'edit' \| 'view'` | No | component-input/storage | persistido em `formInputsKey` | Preferência de modo pode ser hidratada do storage. |
 | `schemaSource` | `'resource' \| 'filter'` | No | component-input | runtime branch | Seleciona caminho de obtenção de schema quando `schemaUrl` não é informado. |
 | `schemaUrl` | `string \| null \| undefined` | Conditional | component-input | parsed as `/schemas/filtered` contract | Fonte canônica explícita para inicialização schema-backed sem depender de `resourcePath`. |
 | `readUrl` | `string \| null \| undefined` | No | component-input | resolved via API origin and `{id}` placeholders | URL concreta de leitura publicada por surface `VIEW`/`READ_PROJECTION`; quando presente, substitui `crud.getById` na hidratação da entidade. |
 | `submitUrl` | `string \| null \| undefined` | Conditional | component-input | resolved via API origin | URL concreta de submit publicada por surface/action; exige `submitMethod` quando usada para envio HTTP. |
 | `submitMethod` | `'post' \| 'put' \| 'patch' \| null \| undefined` | Conditional | component-input | normalized lowercase | Método HTTP concreto de submit publicado por surface/action; exige `submitUrl` quando usado para envio HTTP. |
+| `submitIdempotencyKey` | `string \| null \| undefined` | No | action execution contract | `Idempotency-Key` | Identidade estável da tentativa; deve ser reutilizada em retries da mesma execução. |
+| `submitCorrelationId` | `string \| null \| undefined` | No | action execution contract | `X-Correlation-Id` | Correlação de observabilidade do comando entre host e backend. |
+| `submitResourceVersion` | `string \| number \| null \| undefined` | Conditional | action execution contract | quoted `If-Match` | Versão esperada do item; obrigatória quando `execution.preconditions.resourceVersionTransport` é `IF_MATCH`. |
 | `responseSchemaUrl` | `string \| null \| undefined` | No | component-input | diagnostic only | Schema de resposta para diagnóstico e follow-up; não compõe campos editáveis nem o payload do comando. |
 | `enableCustomization` | `boolean` | No | component-input | boolean coercion | Alterna UX de edição visual/configuração. |
 | `formId` | `string \| undefined` | Yes (corporate flow) | component-input | component key scoping | Obrigatório para ciclo corporativo com persistência e sync. |
@@ -566,7 +571,7 @@ No ecossistema Praxis, ele funciona tanto como runtime final quanto como superfi
 | --- | --- | --- | --- | --- |
 | `config` | `FormConfig` | `{ sections: [] }` | Active | Contrato principal consumido no ciclo inteiro. `sections` é opcional somente para forms schema-driven com grounding explícito (`metadata.source='schema'`, schema metadata ou fonte runtime como `schemaUrl`/`resourcePath`); ausência de layout manual é normalizada internamente como array vazio e permite que `layoutPolicy`/schema materializem agrupamentos. |
 | `resourcePath` | `string \| undefined` | `undefined` | Active | Habilita carga de schema/dados remotos. Opcional quando `schemaUrl` explícito é fornecido. |
-| `resourceId` | `string \| number \| undefined` | `undefined` | Active | Carrega entidade no modo `edit/view`. |
+| `resourceId` | `string \| number \| undefined` | `undefined` | Active | Carrega entidade no modo `edit/view`; em `create`, funciona apenas como contexto do item e não dispara hidratação. |
 | `mode` | `'create' \| 'edit' \| 'view'` | `'create'` | Active | Governa submit, leitura e apresentacao. |
 | `schemaSource` | `'resource' \| 'filter'` | `'resource'` | Active | Seleciona origem do schema remoto. |
 | `schemaUrl` | `string \| undefined` | `undefined` | Active | Permite usar schema canonico publicado pelo backend sem heuristica local de path e pode iniciar o fluxo corporativo sem `resourcePath`. |
@@ -576,13 +581,17 @@ No ecossistema Praxis, ele funciona tanto como runtime final quanto como superfi
 | `domainRules` | `PraxisDynamicFormDomainRulesOptions \| boolean \| null` | `null` | Active | Opt-in para carregar materializacoes de regras compartilhadas em `/api/praxis/config/domain-rules/materializations` e combina-las com `config.formRules`. |
 | `submitUrl` | `string \| undefined` | `undefined` | Active | Executa submit canonico publicado por `surface` ou `action`, sem inferencia local de CRUD. |
 | `submitMethod` | `'post' \| 'put' \| 'patch' \| undefined` | `undefined` | Active | Metodo HTTP do submit canonico; deve acompanhar `submitUrl`. |
+| `submitIdempotencyKey` | `string \| undefined` | `undefined` | Active | Envia `Idempotency-Key` e preserva a identidade entre retries da mesma tentativa. |
+| `submitCorrelationId` | `string \| undefined` | `undefined` | Active | Envia `X-Correlation-Id` para rastreabilidade corporativa ponta a ponta. |
+| `submitResourceVersion` | `string \| number \| undefined` | `undefined` | Active | Envia a versão esperada como `If-Match`, sem inferir concorrência a partir do formulário. |
 | `responseSchemaUrl` | `string \| undefined` | `undefined` | Active | Porta diagnóstica/read-only; não deve ser usada para mesclar propriedades do schema de resposta no formulário de comando. |
 | `enableCustomization` | `boolean` | `false` | Active | Habilita UX de customizacao do layout. |
 | `formId` | `string \| undefined` | `undefined` | Active | Chave de persistencia e identidade logica. |
 | `componentInstanceId` | `string \| undefined` | `undefined` | Active | Isola instancias com mesmo `formId`. |
+| `configPersistenceStrategy` | `'local-first' \| 'input-first'` | `'local-first'` | Active | Em `input-first`, os inputs fornecidos pelo host, inclusive `mode`, permanecem autoritativos sobre preferencias persistidas da mesma instancia. Combine com `layoutPolicy.persistence='transient'` em commands efemeros para nao carregar nem gravar layout local. |
 | `layout` | `FormLayout \| undefined` | `undefined` | Partial | Funciona como override estrutural em parte dos fluxos de layout/editor. |
 | `generatedLayoutPreset` | `'default' \| 'compactPresentation'` | `'default'` | Active | Usado apenas ao criar a configuracao inicial a partir de schema/metadata; nao reprocessa layouts persistidos ou authorados. |
-| `layoutPolicy` | `DynamicFormLayoutPolicy \| null` | `null` | Active | Politica opt-in para materializar layout a partir do schema atual. Use `source: 'schema'` com `persistence: 'transient'` para detalhe/read-only e command forms schema-driven sem persistir `sections` geradas nem reabrir configuracao local salva; politicas de host em `config`, como `helpPresentation`, continuam sendo aplicadas ao layout materializado. Em `mode='view'`, `intent: 'detail'` ou `preset: 'compactPresentation'` ativa apresentacao quando `presentationModeGlobal` nao foi informado; use `[presentationModeGlobal]=false` para controles read-only tradicionais. No preset `compactPresentation`, `x-ui.width` explicito empacota campos em linhas de 12 colunas e tem precedencia sobre `detailSummary.columns` por default; campos sem width permanecem full-width, a menos que `detailSummary.columns`/`responsiveColumns` declare a densidade do resumo. Use `detailSummary.widthPrecedence='summary'` quando a densidade do resumo read-only deve sobrescrever `x-ui.width` apenas nessa surface compacta. No preset `groupedCommand`, `groupedCommand.orphanFieldExpansion` controla linhas com um unico campo: `medium-and-wide` (default) expande spans 6/8, `preserve` mantem o width publicado e `all` tambem expande campos compactos. Use `responsiveColumns`, por exemplo `{ lg: 3, md: 2, sm: 1 }`, para drawers, side sheets e painéis corporativos estreitos sem copiar `FormConfig.sections` locais. `schemaType` e `schemaOperation` sao validados contra `schemaUrl` quando a URL declara esses parametros. |
+| `layoutPolicy` | `DynamicFormLayoutPolicy \| null` | `null` | Active | Politica opt-in para materializar layout a partir do schema atual. Use `source: 'schema'` com `persistence: 'transient'` para detalhe/read-only e command forms schema-driven sem persistir `sections` geradas nem reabrir configuracao local salva; politicas de host em `config`, como `helpPresentation`, continuam sendo aplicadas ao layout materializado. Em `mode='view'`, `intent: 'detail'` ou `preset: 'compactPresentation'` ativa apresentacao quando `presentationModeGlobal` nao foi informado; use `[presentationModeGlobal]=false` para controles read-only tradicionais. No preset `compactPresentation`, `x-ui.width` explicito empacota campos em linhas de 12 colunas e tem precedencia sobre `detailSummary.columns` por default; campos sem width permanecem full-width, a menos que `detailSummary.columns`/`responsiveColumns` declare a densidade do resumo. Use `detailSummary.widthPrecedence='summary'` quando a densidade do resumo read-only deve sobrescrever `x-ui.width` apenas nessa surface compacta. No preset `groupedCommand`, `groupedCommand.orphanFieldExpansion` controla linhas com um unico campo: `medium-and-wide` (default) expande spans 6/8, `preserve` mantem o width publicado e `all` tambem expande campos compactos. `groupedCommand.contextFields` identifica campos schema-backed já hidratados pela surface: eles permanecem no `FormGroup` e no payload, mas não renderizam controles redundantes. Use `responsiveColumns`, por exemplo `{ lg: 3, md: 2, sm: 1 }`, para drawers, side sheets e painéis corporativos estreitos sem copiar `FormConfig.sections` locais. `schemaType` e `schemaOperation` sao validados contra `schemaUrl` quando a URL declara esses parametros. |
 | `backConfig` | `BackConfig \| undefined` | `undefined` | Active | Integra retorno/navegacao no painel de configuracao; `confirmOnDirty` tem precedencia sobre `behavior.confirmOnUnsavedChanges` no cancel. |
 | `hooks` | `FormHooksLayout \| undefined` | `undefined` | Active | Override direto de hooks sobre `config.hooks`. |
 | `customEndpoints` | `EndpointConfig` | `{}` | Active | Override de endpoints no CRUD service interno. |
@@ -697,7 +706,7 @@ Validado em 2026-04-23 contra `praxis-api-quickstart` publicado no Render com
 
 #### Data mode e fluxo
 
-- `mode='create'`: cria registro, carga de entidade opcional.
+- `mode='create'`: cria registro ou materializa um comando; nunca carrega a entidade por `resourceId`, e valores iniciais devem vir de `initialValue`.
 - `mode='edit'`: carrega entidade por `resourceId` quando disponivel.
 - `mode='view'`: foco em leitura/apresentacao; actions de edicao podem ser suprimidas.
 

package/types/praxisui-dynamic-form.d.ts

@@ -735,6 +735,12 @@ declare class PraxisDynamicForm implements OnInit, OnChanges, OnDestroy {
     submitUrl?: string | null;
     /** Canonical submit method published by the backend surface catalog. */
     submitMethod?: string | null;
+    /** Stable key reused by retries of the same materialized business command. */
+    submitIdempotencyKey?: string | null;
+    /** Correlation identifier propagated to the backend command boundary. */
+    submitCorrelationId?: string | null;
+    /** Current persisted resource version sent through If-Match when governed by the action. */
+    submitResourceVersion?: string | number | null;
     /** Canonical response schema URL exposed for runtime diagnostics/follow-up. */
     responseSchemaUrl?: string | null;
     /** API endpoint entry used to resolve relative canonical URLs in detached hosts. */
@@ -973,6 +979,7 @@ declare class PraxisDynamicForm implements OnInit, OnChanges, OnDestroy {
     private resolveSubmitOperation;
     private buildSubmitRequest;
     private normalizeSubmitMethod;
+    private formatResourceVersion;
     private resolveSubmitHref;
     private resolveReadHref;
     private resolveEntityAwareHref;
@@ -1386,7 +1393,7 @@ declare class PraxisDynamicForm implements OnInit, OnChanges, OnDestroy {
     private applyPresentationVars;
     private applyPresentationConfig;
     static ɵfac: i0.ɵɵFactoryDeclaration<PraxisDynamicForm, [null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, { optional: true; }, { optional: true; }, { optional: true; }, { optional: true; }, { optional: true; }, { optional: true; }, { optional: true; }]>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<PraxisDynamicForm, "praxis-dynamic-form", never, { "resourcePath": { "alias": "resourcePath"; "required": false; }; "resourceId": { "alias": "resourceId"; "required": false; }; "initialValue": { "alias": "initialValue"; "required": false; }; "editorialContext": { "alias": "editorialContext"; "required": false; }; "mode": { "alias": "mode"; "required": false; }; "config": { "alias": "config"; "required": false; }; "actions": { "alias": "actions"; "required": false; }; "schemaSource": { "alias": "schemaSource"; "required": false; }; "schemaUrl": { "alias": "schemaUrl"; "required": false; }; "readUrl": { "alias": "readUrl"; "required": false; }; "submitUrl": { "alias": "submitUrl"; "required": false; }; "submitMethod": { "alias": "submitMethod"; "required": false; }; "responseSchemaUrl": { "alias": "responseSchemaUrl"; "required": false; }; "apiEndpointKey": { "alias": "apiEndpointKey"; "required": false; }; "apiUrlEntry": { "alias": "apiUrlEntry"; "required": false; }; "enableCustomization": { "alias": "enableCustomization"; "required": false; }; "showAiAssistant": { "alias": "showAiAssistant"; "required": false; }; "formId": { "alias": "formId"; "required": false; }; "componentInstanceId": { "alias": "componentInstanceId"; "required": false; }; "configPersistenceStrategy": { "alias": "configPersistenceStrategy"; "required": false; }; "layout": { "alias": "layout"; "required": false; }; "generatedLayoutPreset": { "alias": "generatedLayoutPreset"; "required": false; }; "layoutPolicy": { "alias": "layoutPolicy"; "required": false; }; "backConfig": { "alias": "backConfig"; "required": false; }; "hooks": { "alias": "hooks"; "required": false; }; "removeEmptyContainersOnSave": { "alias": "removeEmptyContainersOnSave"; "required": false; }; "reactiveValidation": { "alias": "reactiveValidation"; "required": false; }; "reactiveValidationDebounceMs": { "alias": "reactiveValidationDebounceMs"; "required": false; }; "notifyIfOutdated": { "alias": "notifyIfOutdated"; "required": false; }; "snoozeMs": { "alias": "snoozeMs"; "required": false; }; "autoOpenSettingsOnOutdated": { "alias": "autoOpenSettingsOnOutdated"; "required": false; }; "readonlyModeGlobal": { "alias": "readonlyModeGlobal"; "required": false; }; "disabledModeGlobal": { "alias": "disabledModeGlobal"; "required": false; }; "presentationModeGlobal": { "alias": "presentationModeGlobal"; "required": false; }; "visibleGlobal": { "alias": "visibleGlobal"; "required": false; }; "fieldIconPolicy": { "alias": "fieldIconPolicy"; "required": false; }; "domainRules": { "alias": "domainRules"; "required": false; }; "customEndpoints": { "alias": "customEndpoints"; "required": false; }; }, { "formSubmit": "formSubmit"; "formCancel": "formCancel"; "formReset": "formReset"; "configChange": "configChange"; "configPatchChange": "configPatchChange"; "formReady": "formReady"; "valueChange": "valueChange"; "syncCompleted": "syncCompleted"; "initializationError": "initializationError"; "loadingStateChange": "loadingStateChange"; "enableCustomizationChange": "enableCustomizationChange"; "customAction": "customAction"; "actionConfirmation": "actionConfirmation"; "schemaStatusChange": "schemaStatusChange"; "fieldRenderError": "fieldRenderError"; "ruleDiagnosticsChange": "ruleDiagnosticsChange"; }, never, never, true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<PraxisDynamicForm, "praxis-dynamic-form", never, { "resourcePath": { "alias": "resourcePath"; "required": false; }; "resourceId": { "alias": "resourceId"; "required": false; }; "initialValue": { "alias": "initialValue"; "required": false; }; "editorialContext": { "alias": "editorialContext"; "required": false; }; "mode": { "alias": "mode"; "required": false; }; "config": { "alias": "config"; "required": false; }; "actions": { "alias": "actions"; "required": false; }; "schemaSource": { "alias": "schemaSource"; "required": false; }; "schemaUrl": { "alias": "schemaUrl"; "required": false; }; "readUrl": { "alias": "readUrl"; "required": false; }; "submitUrl": { "alias": "submitUrl"; "required": false; }; "submitMethod": { "alias": "submitMethod"; "required": false; }; "submitIdempotencyKey": { "alias": "submitIdempotencyKey"; "required": false; }; "submitCorrelationId": { "alias": "submitCorrelationId"; "required": false; }; "submitResourceVersion": { "alias": "submitResourceVersion"; "required": false; }; "responseSchemaUrl": { "alias": "responseSchemaUrl"; "required": false; }; "apiEndpointKey": { "alias": "apiEndpointKey"; "required": false; }; "apiUrlEntry": { "alias": "apiUrlEntry"; "required": false; }; "enableCustomization": { "alias": "enableCustomization"; "required": false; }; "showAiAssistant": { "alias": "showAiAssistant"; "required": false; }; "formId": { "alias": "formId"; "required": false; }; "componentInstanceId": { "alias": "componentInstanceId"; "required": false; }; "configPersistenceStrategy": { "alias": "configPersistenceStrategy"; "required": false; }; "layout": { "alias": "layout"; "required": false; }; "generatedLayoutPreset": { "alias": "generatedLayoutPreset"; "required": false; }; "layoutPolicy": { "alias": "layoutPolicy"; "required": false; }; "backConfig": { "alias": "backConfig"; "required": false; }; "hooks": { "alias": "hooks"; "required": false; }; "removeEmptyContainersOnSave": { "alias": "removeEmptyContainersOnSave"; "required": false; }; "reactiveValidation": { "alias": "reactiveValidation"; "required": false; }; "reactiveValidationDebounceMs": { "alias": "reactiveValidationDebounceMs"; "required": false; }; "notifyIfOutdated": { "alias": "notifyIfOutdated"; "required": false; }; "snoozeMs": { "alias": "snoozeMs"; "required": false; }; "autoOpenSettingsOnOutdated": { "alias": "autoOpenSettingsOnOutdated"; "required": false; }; "readonlyModeGlobal": { "alias": "readonlyModeGlobal"; "required": false; }; "disabledModeGlobal": { "alias": "disabledModeGlobal"; "required": false; }; "presentationModeGlobal": { "alias": "presentationModeGlobal"; "required": false; }; "visibleGlobal": { "alias": "visibleGlobal"; "required": false; }; "fieldIconPolicy": { "alias": "fieldIconPolicy"; "required": false; }; "domainRules": { "alias": "domainRules"; "required": false; }; "customEndpoints": { "alias": "customEndpoints"; "required": false; }; }, { "formSubmit": "formSubmit"; "formCancel": "formCancel"; "formReset": "formReset"; "configChange": "configChange"; "configPatchChange": "configPatchChange"; "formReady": "formReady"; "valueChange": "valueChange"; "syncCompleted": "syncCompleted"; "initializationError": "initializationError"; "loadingStateChange": "loadingStateChange"; "enableCustomizationChange": "enableCustomizationChange"; "customAction": "customAction"; "actionConfirmation": "actionConfirmation"; "schemaStatusChange": "schemaStatusChange"; "fieldRenderError": "fieldRenderError"; "ruleDiagnosticsChange": "ruleDiagnosticsChange"; }, never, never, true, never>;
 }
 
 declare class FormConfigService {
@@ -1755,6 +1762,8 @@ declare class PraxisFilterForm implements OnChanges, OnDestroy {
     form: FormGroup<Record<string, any>>;
     private valueChangesSub?;
     private statusChangesSub?;
+    private columnFieldsCache;
+    private singleFieldCache;
     constructor(dynamicForm: DynamicFormService);
     ngOnChanges(changes: SimpleChanges): void;
     ngOnDestroy(): void;
@@ -1763,6 +1772,7 @@ declare class PraxisFilterForm implements OnChanges, OnDestroy {
     private hasExplicitDefaultValue;
     onFormSubmit(): void;
     getColumnFields(column: FormColumn): FieldMetadata[];
+    getSingleField(field: FieldMetadata): FieldMetadata[];
     getColumnClasses(column: FormColumn): string | null;
     get fieldMetadata(): FieldMetadata[];
     get hasLayout(): boolean;
@@ -2766,7 +2776,7 @@ declare function buildDynamicFormRuleAuthoringContext(config: Pick<FormConfig, '
  * Manifesto de authoring canônico para o componente praxis-dynamic-form.
  * Este arquivo define as operações permitidas pela IA para editar formulários.
  *
- * @version 1.5.0
+ * @version 1.5.1
  * @status COMPLIANT - Alinhado com contrato v2, gate de aceitação e semântica local/schema-backed.
  */
 declare const PRAXIS_DYNAMIC_FORM_AUTHORING_MANIFEST: ComponentAuthoringManifest;