@praxisui/dynamic-form 9.0.0-beta.22 → 9.0.0-beta.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@praxisui/dynamic-form",
-  "version": "9.0.0-beta.22",
+  "version": "9.0.0-beta.26",
   "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.0-beta.22",
-    "@praxisui/dynamic-fields": "^9.0.0-beta.22",
-    "@praxisui/metadata-editor": "^9.0.0-beta.22",
-    "@praxisui/rich-content": "^9.0.0-beta.22",
-    "@praxisui/settings-panel": "^9.0.0-beta.22",
-    "@praxisui/visual-builder": "^9.0.0-beta.22",
-    "@praxisui/core": "^9.0.0-beta.22",
+    "@praxisui/ai": "^9.0.0-beta.26",
+    "@praxisui/dynamic-fields": "^9.0.0-beta.26",
+    "@praxisui/metadata-editor": "^9.0.0-beta.26",
+    "@praxisui/rich-content": "^9.0.0-beta.26",
+    "@praxisui/settings-panel": "^9.0.0-beta.26",
+    "@praxisui/visual-builder": "^9.0.0-beta.26",
+    "@praxisui/core": "^9.0.0-beta.26",
     "rxjs": "^7.8.0"
   },
   "dependencies": {

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

@@ -132,6 +132,7 @@ Essa fronteira preserva a premissa de plataforma: o formulario materializa e exp
 | `formRulesState` | not-specified | not-specified | n/a | Active | Persistido para round-trip do builder visual. |
 | `hooks` | not-specified | not-specified | n/a | Active | Integracao de ciclo (before/after) via runtime de hooks. |
 | `hints` | not-specified | not-specified | n/a | Declared-only | Mantido no contrato/editor; sem render dedicado no template principal. |
+| `helpPresentation` | `FormHelpPresentationConfig` | No | `{ display: "inline" }` | Active | Politica visual para exibir `hint`/`helpText` dos campos sem alterar semantica dos DTOs; erros de validacao continuam inline. |
 | `fieldMetadata[].array` | `FieldArrayConfig` | No | n/a | Active | Contrato de Editable Collection apenas quando `fieldMetadata[].controlType === "array"` ou quando `x-ui.array` foi publicado explicitamente. |
 
 Nota editorial:
@@ -577,6 +578,7 @@ No ecossistema Praxis, ele funciona tanto como runtime final quanto como superfi
 | `componentInstanceId` | `string \| undefined` | `undefined` | Active | Isola instancias com mesmo `formId`. |
 | `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; campos sem width permanecem full-width. `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. |
@@ -589,8 +591,28 @@ No ecossistema Praxis, ele funciona tanto como runtime final quanto como superfi
 | `readonlyModeGlobal` | `boolean \| null` | `null` | Active | Estado global de leitura propagado para loader. |
 | `disabledModeGlobal` | `boolean \| null` | `null` | Active | Estado global de desabilitado propagado para loader. |
 | `presentationModeGlobal` | `boolean \| null` | `null` | Active | Modo apresentacao global (efetivo em `view`). |
+| `fieldIconPolicy` | `'all' \| 'presentation-only' \| 'none'` | `'all'` | Active | Controla icones `prefixIcon`/`suffixIcon` vindos da metadata dos campos. `all` preserva o comportamento atual; `presentation-only` mantem icones decorativos no modo apresentacao e oculta os slots de icone em controles input/read-only tradicionais; `none` oculta esses slots em todos os modos. |
 | `visibleGlobal` | `boolean \| null` | `null` | Active | Visibilidade global propagada para loader. |
 
+#### Migration baseline for ErgonX-style screens
+
+For enterprise migrations that must become templates for many screens, `layoutPolicy`,
+`helpPresentation` and `fieldIconPolicy` should be selected as part of the DTO/schema
+handoff, not patched locally after visual review.
+
+Recommended baseline:
+
+| Surface | Inputs | Contract gate |
+| --- | --- | --- |
+| Detail/read-only | `layoutPolicy.source='schema'`, `intent='detail'`, `preset='compactPresentation'`, `persistence='transient'`, `schemaType='response'` | Response DTO publishes business grouping, order, labels, value presentation and safe widths. |
+| Create/edit | `layoutPolicy.source='schema'`, `intent='command'`, `preset='groupedCommand'`, `persistence='transient'`, `schemaType='request'` | Request DTO/write contract publishes only editable fields, validators, options and help text required for the command. |
+| Dense command drawer | `config.helpPresentation.display='auto'` with `preferPopoverForControls` for select, checkbox, toggle, date/datepickers and numeric controls | DTO help text is semantic and not a substitute for validation messages. |
+| Input-heavy operational form | `fieldIconPolicy='presentation-only'` | Icons remain useful in read-only presentation but do not crowd editable controls. |
+
+If a field requires a local label, local help text, local option mapping or local code/description
+composition to look correct, the schema is not ready for scalable migration. Fix the backend DTO,
+OpenAPI `x-ui` metadata or option/value-presentation contract first.
+
 #### Regras compartilhadas materializadas
 
 `domainRules` separa regra corporativa compartilhavel de regra materializada no `FormConfig`. Quando habilitado, o componente consulta o backend de configuracao via `DomainRuleFormRulesService`, transforma cada materializacao em `FormLayoutRule` e aplica a lista combinada:

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

@@ -7,7 +7,7 @@ import { MatDialog } from '@angular/material/dialog';
 import { MatSnackBar } from '@angular/material/snack-bar';
 import { CdkDragStart, CdkDragMove, CdkDragEnd, CdkDragDrop } from '@angular/cdk/drag-drop';
 import * as _praxisui_core from '@praxisui/core';
-import { AsyncConfigStorage, FormLayout, FieldMetadata, FormLayoutRule, FormRuleTargetType as FormRuleTargetType$1, PraxisJsonLogicService, FormSection, FormRow, FormColumn, FormConfig, FormLayoutItem, FormActionButton, AiCapability, BackConfig, RichBlockHostCapabilities, ApiEndpoint, ApiUrlEntry, FormHooksLayout, EndpointConfig, FormSubmitEvent, FormReadyEvent, FormValueChangeEvent, SyncResult, FormInitializationError, LoadingState, FormCustomActionEvent, FormActionConfirmationEvent, RichContentDocument, JsonLogicRecord, GenericCrudService, ConnectionStorage, DynamicFormService, ErrorMessageService, SchemaNormalizerService, ComponentMetadataRegistry, GlobalConfigService, ComponentKeyService, LoadingOrchestrator, ApiUrlConfig, PraxisLoadingRenderer, FormHooksRegistry, FormHookPreset, LoggerService, FormSectionHeaderAction, FormSectionHeaderConfig, FormConfigState, JsonLogicExpression, GlobalActionCatalogEntry, PraxisRuntimeConditionalEffectRule, PraxisRuntimeGlobalActionEffect, SurfaceOpenPayload, GlobalActionField, PraxisEffectPolicy, FieldDefinition, ComponentDocMeta, Breakpoint, DomainRuleRequestOptions, DomainRuleService, DomainRuleMaterialization, IconPickerService, GlobalActionRef, AiCapabilityCategory, AiCapabilityCatalog, AiValueKind, ComponentAuthoringManifest } from '@praxisui/core';
+import { AsyncConfigStorage, FormLayout, FieldMetadata, FormLayoutRule, FormRuleTargetType as FormRuleTargetType$1, PraxisJsonLogicService, FormSection, FormRow, FormColumn, FormConfig, FormLayoutItem, FormActionButton, AiCapability, BackConfig, RichBlockHostCapabilities, ApiEndpoint, ApiUrlEntry, DynamicFormLayoutPolicy, FormHooksLayout, EndpointConfig, FormSubmitEvent, FormReadyEvent, FormValueChangeEvent, SyncResult, FormInitializationError, LoadingState, FormCustomActionEvent, FormActionConfirmationEvent, RichContentDocument, JsonLogicRecord, GenericCrudService, ConnectionStorage, DynamicFormService, ErrorMessageService, SchemaNormalizerService, ComponentMetadataRegistry, GlobalConfigService, ComponentKeyService, LoadingOrchestrator, ApiUrlConfig, PraxisLoadingRenderer, FormHooksRegistry, FormHookPreset, LoggerService, FormSectionHeaderAction, FormSectionHeaderConfig, FormConfigState, JsonLogicExpression, FormHelpPresentationConfig, GlobalActionCatalogEntry, PraxisRuntimeConditionalEffectRule, PraxisRuntimeGlobalActionEffect, SurfaceOpenPayload, GlobalActionField, PraxisEffectPolicy, FieldDefinition, ComponentDocMeta, Breakpoint, DomainRuleRequestOptions, DomainRuleService, DomainRuleMaterialization, TableConfig, IconPickerService, GlobalActionRef, AiCapabilityCategory, AiCapabilityCatalog, AiValueKind, ComponentAuthoringManifest } from '@praxisui/core';
 import * as rxjs from 'rxjs';
 import { Observable, BehaviorSubject } from 'rxjs';
 import { SettingsPanelService, SettingsValueProvider } from '@praxisui/settings-panel';
@@ -206,6 +206,7 @@ interface GenerateFormConfigFromMetadataOptions {
     fieldsPerRow?: number;
     defaultSectionTitle?: string;
     layoutPreset?: DynamicFormGeneratedLayoutPreset;
+    presentationRoleMap?: Record<string, string>;
 }
 declare class DynamicFormLayoutService {
     private readonly changesSubject;
@@ -227,6 +228,10 @@ declare class DynamicFormLayoutService {
     private inferCompactPresentationSpan;
     private clampGridSpan;
     private resolveGroupOrder;
+    private withCompactPresentationFieldDefaults;
+    private resolveFieldPresentationRole;
+    private resolvePresentationRole;
+    private normalizePresentationRole;
     private genId;
     private capitalizeFirstLetter;
     private assertIndex;
@@ -768,6 +773,8 @@ declare class PraxisDynamicForm implements OnInit, OnChanges, OnDestroy {
     layout?: FormLayout;
     /** Metadata-driven layout preset used only when creating an initial config from schema. */
     generatedLayoutPreset: DynamicFormGeneratedLayoutPreset;
+    /** Opt-in policy for schema-driven transient layout materialization. */
+    layoutPolicy?: DynamicFormLayoutPolicy | null;
     /** Optional navigation back config (from CRUD host) */
     backConfig?: BackConfig;
     /** Optional direct hooks declaration for testing/demo (overrides config.hooks) */
@@ -788,6 +795,7 @@ declare class PraxisDynamicForm implements OnInit, OnChanges, OnDestroy {
     disabledModeGlobal: boolean | null;
     presentationModeGlobal: boolean | null;
     visibleGlobal: boolean | null;
+    fieldIconPolicy: 'all' | 'presentation-only' | 'none';
     /** Opt-in loader for shared domain rule materializations persisted outside FormConfig. */
     domainRules: PraxisDynamicFormDomainRulesOptions | boolean | null;
     get effectivePresentation(): boolean;
@@ -797,6 +805,12 @@ declare class PraxisDynamicForm implements OnInit, OnChanges, OnDestroy {
     get invalidRequiredFieldLabels(): string[];
     /** Value propagated to DynamicFieldLoader; null allows per-field metadata */
     get presentationForLoader(): boolean | null;
+    getRenderableFieldsForLoader(fields: FieldMetadata[]): FieldMetadata[];
+    private materializeFieldPresentationPolicy;
+    private materializeFieldHelpPolicy;
+    private shouldSuppressFieldIcons;
+    private resolveFieldHelpDisplay;
+    private normalizeFieldHelpControlToken;
     /** Custom endpoints for CRUD operations */
     private _customEndpoints;
     get customEndpoints(): EndpointConfig;
@@ -992,6 +1006,10 @@ declare class PraxisDynamicForm implements OnInit, OnChanges, OnDestroy {
     private persistFormConfig;
     private createDefaultConfig;
     private createConfigFromHostConfig;
+    private shouldUseSchemaLayoutPolicy;
+    private layoutPolicyRequestsPresentation;
+    private shouldPersistGeneratedConfig;
+    private createSchemaMaterializedConfig;
     private reconcileLoadedConfigWithServerSchema;
     private hostConfigHasAuthoredLocalFieldsNotInLocalConfig;
     private syncWithServer;
@@ -1147,6 +1165,7 @@ declare class PraxisDynamicForm implements OnInit, OnChanges, OnDestroy {
     private _showConfirmationDialog;
     onFormAction(event: PraxisFormActionEvent): void;
     private dispatchRichContentAction;
+    private emitRichContentCustomAction;
     private isRichContentActionAvailable;
     private hasRichContentCapability;
     private buildRichContentActionContext;
@@ -1349,7 +1368,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; }]>;
-    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; }; "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; }; "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; }; "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 {
@@ -1547,6 +1566,12 @@ declare class PraxisDynamicFormConfigEditor implements SettingsValueProvider, On
     };
     /** Ensure hints object exists (normalized upstream) */
     private ensureHints;
+    get helpPresentationDraft(): Required<FormHelpPresentationConfig>;
+    onHelpPresentationDisplayChange(display: FormHelpPresentationConfig['display']): void;
+    onHelpPresentationInlineMaxLengthChange(inlineMaxLength: number | string | null): void;
+    private updateHelpPresentation;
+    getHelpPreferPopoverControlsText(): string;
+    onHelpPreferPopoverControlsChange(value: string): void;
     schemaPrefs: {
         notifyIfOutdated: 'inline' | 'snackbar' | 'both' | 'none';
         snoozeMs: number;
@@ -2172,6 +2197,7 @@ interface Ergadm00034CompactPresentationExample {
     readonly resourcePath: string;
     readonly layoutPreset: 'compactPresentation';
     readonly rows: readonly Ergadm00034LegacyFrequencyRow[];
+    readonly tableConfig: TableConfig;
     readonly metadata: readonly FieldMetadata[];
     readonly initialValue: Record<string, unknown>;
 }