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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@praxisui/dynamic-fields",
-  "version": "9.0.0-beta.22",
+  "version": "9.0.0-beta.26",
   "description": "Angular Material-based dynamic form fields for Praxis UI with lazy loading and metadata-driven rendering.",
   "peerDependencies": {
     "@angular/common": "^21.0.0",
@@ -11,8 +11,8 @@
     "@angular/platform-browser": "^21.0.0",
     "@angular/router": "^21.0.0",
     "rxjs": "^7.8.0",
-    "@praxisui/core": "^9.0.0-beta.22",
-    "@praxisui/cron-builder": "^9.0.0-beta.22"
+    "@praxisui/core": "^9.0.0-beta.26",
+    "@praxisui/cron-builder": "^9.0.0-beta.26"
   },
   "dependencies": {
     "libphonenumber-js": "^1.12.41",

package/src/lib/base/pdx-base-input-runtime-contract.json-api.md

@@ -349,6 +349,9 @@ Limites:
 | `metadata.validators.showInlineErrors` | `boolean` | Active | Forca/desliga exibicao inline de erros. |
 | `metadata.errorStateMatcher` | enum | Active | Estrategia de estado de erro usada pelo matcher utilitario. |
 | `metadata.hint` | `string` | Active | Exibe dica quando nao ha erro. |
+| `metadata.helpText` | `string` | Active | Texto de ajuda semantica publicado por DTO/schema; usado como fallback quando `hint` nao foi informado. |
+| `metadata.helpDisplay` | `'auto' \| 'inline' \| 'popover' \| 'hidden'` | Active | Politica efetiva de apresentacao de `hint`/`helpText`; normalmente materializada pelo host `praxis-dynamic-form` a partir de `FormConfig.helpPresentation`. |
+| `metadata.helpInlineMaxLength` | `number` | Active | Limite local usado quando `metadata.helpDisplay` e `auto`; textos acima do limite migram para affordance de ajuda. |
 | `metadata.hintAlign` | `'start' \| 'end'` | Active | Alinhamento da dica. |
 | `metadata.materialDesign.appearance` | `'fill' \| 'outline'` | Active | Aparencia do `mat-form-field`. |
 | `metadata.materialDesign.color` | `'primary' \| 'accent' \| 'warn'` | Active | Cor do `mat-form-field`. |
@@ -373,6 +376,19 @@ Limites:
 | `metadata.ariaDescribedby` | `string` | Active | `aria-describedby` no elemento nativo. |
 | `metadata.ariaLabelledby` | `string` | Active | `aria-labelledby` no elemento nativo. |
 
+#### Ajuda contextual em migracoes corporativas
+
+`metadata.helpText` pertence ao DTO/schema quando descreve semantica de negocio, impacto operacional ou criterio de decisao do campo. Ele nao deve ser gerado a partir de label, nome tecnico ou heuristica local.
+
+Use `metadata.helpDisplay` para excecoes por campo:
+
+- `inline`: texto curto que deve permanecer visivel para evitar erro operacional;
+- `popover`: texto longo, raro ou de apoio decisorio;
+- `hidden`: ajuda publicada mas inadequada para a superficie atual;
+- `auto`: delega a politica do host e ao limite `helpInlineMaxLength`.
+
+Em formularios densos, o host deve preferir uma politica global como `FormConfig.helpPresentation.display = "auto"` e mover textos longos para a affordance de ajuda. Mensagens de validacao continuam no canal de erro do campo e nao devem ser convertidas em `helpText`.
+
 #### Politica de label com prefixos e sufixos
 
 Quando um campo usa `metadata.prefixIcon`, `metadata.suffixIcon`, `clearButton`,

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

@@ -3,7 +3,7 @@ import { WritableSignal, InjectionToken, Provider, OnInit, OnDestroy, AfterViewI
 import { AbstractControl, ControlValueAccessor, NgControl, ValidationErrors, FormControl, FormGroup, FormArray, FormGroupDirective, NgForm } from '@angular/forms';
 import { Observable, BehaviorSubject, Subscription } from 'rxjs';
 import * as _praxisui_core from '@praxisui/core';
-import { ComponentMetadata, PraxisTextValue, PraxisI18nDictionary, PraxisI18nConfig, PraxisI18nMessageDescriptor, PraxisI18nService, GlobalActionService, GlobalActionRef, OptionSourceMetadata, GenericCrudService, GlobalConfigService, OptionDTO, ComponentMetadataEditorialDescriptor, ComponentDocMeta, ComponentMetadataRegistry, FieldMetadata, MaterialButtonMetadata, FieldArrayConfig, MaterialInputMetadata, MaterialColorInputMetadata, MaterialDateInputMetadata, MaterialDatepickerMetadata, MaterialDateRangeMetadata, DateRangePreset, DateRangeValue, MaterialDatetimeLocalInputMetadata, MaterialEmailInputMetadata, MaterialTextareaMetadata, MaterialNumericMetadata, MaterialCurrencyMetadata, MaterialCpfCnpjMetadata, MaterialPriceRangeMetadata, MaterialMonthInputMetadata, MaterialPasswordMetadata, MaterialSearchInputMetadata, MaterialSelectMetadata, LookupFilterRequest, LookupFilteringMetadata, LookupSortOptionMetadata, LookupFilterDefinitionMetadata, MaterialEntityLookupMetadata, LookupStatusTone, EntityLookupResultState, EntityLookupResult, LookupDialogMetadata, LookupFilterOperator, LookupFilterFieldType, LookupResultColumnMetadata, MaterialAutocompleteMetadata, RangeSliderMark, RangeSliderSemanticTone, MaterialToggleMetadata, MaterialRangeSliderMetadata, RangeSliderValue, InlinePeriodRangeMetadata, FieldControlType, MaterialTimepickerMetadata, MaterialTimeRangeMetadata, MaterialTreeNode, MaterialTreeSelectMetadata, MaterialMultiSelectTreeMetadata, MaterialChipsMetadata, RangeSliderSemanticBand, MaterialSliderMetadata, MaterialPhoneMetadata, MaterialTimeInputMetadata, MaterialUrlInputMetadata, MaterialWeekInputMetadata, MaterialColorPickerMetadata, MaterialYearInputMetadata, CapabilityCatalog, ComponentAuthoringManifest, ManifestControlProfile } from '@praxisui/core';
+import { ComponentMetadata, PraxisTextValue, PraxisI18nDictionary, PraxisI18nConfig, PraxisI18nMessageDescriptor, PraxisI18nService, FormFieldHelpDisplay, GlobalActionService, GlobalActionRef, OptionSourceMetadata, GenericCrudService, GlobalConfigService, OptionDTO, ComponentMetadataEditorialDescriptor, ComponentDocMeta, ComponentMetadataRegistry, FieldMetadata, MaterialButtonMetadata, FieldArrayConfig, MaterialInputMetadata, MaterialColorInputMetadata, MaterialDateInputMetadata, MaterialDatepickerMetadata, MaterialDateRangeMetadata, DateRangePreset, DateRangeValue, MaterialDatetimeLocalInputMetadata, MaterialEmailInputMetadata, MaterialTextareaMetadata, MaterialNumericMetadata, MaterialCurrencyMetadata, MaterialCpfCnpjMetadata, MaterialPriceRangeMetadata, MaterialMonthInputMetadata, MaterialPasswordMetadata, MaterialSearchInputMetadata, MaterialSelectMetadata, LookupFilterRequest, LookupFilteringMetadata, LookupSortOptionMetadata, LookupFilterDefinitionMetadata, MaterialEntityLookupMetadata, LookupStatusTone, EntityLookupResultState, EntityLookupResult, LookupDialogMetadata, LookupFilterOperator, LookupFilterFieldType, LookupResultColumnMetadata, MaterialAutocompleteMetadata, RangeSliderMark, RangeSliderSemanticTone, MaterialToggleMetadata, MaterialRangeSliderMetadata, RangeSliderValue, InlinePeriodRangeMetadata, FieldControlType, MaterialTimepickerMetadata, MaterialTimeRangeMetadata, MaterialTreeNode, MaterialTreeSelectMetadata, MaterialMultiSelectTreeMetadata, MaterialChipsMetadata, RangeSliderSemanticBand, MaterialSliderMetadata, MaterialPhoneMetadata, MaterialTimeInputMetadata, MaterialUrlInputMetadata, MaterialWeekInputMetadata, MaterialColorPickerMetadata, MaterialYearInputMetadata, CapabilityCatalog, ComponentAuthoringManifest, ManifestControlProfile } from '@praxisui/core';
 import { Router } from '@angular/router';
 import { MatDialog, MatDialogRef } from '@angular/material/dialog';
 import { MatSelect } from '@angular/material/select';
@@ -660,6 +660,13 @@ declare abstract class SimpleBaseInputComponent implements ControlValueAccessor,
     protected isInlineContextTooltipEnabled(): boolean;
     protected resolveInlineContextTooltipValue(): string;
     protected resolveInlineHelpTooltipText(): string;
+    fieldHelpText(): string;
+    fieldHelpDisplay(): FormFieldHelpDisplay;
+    hasInlineFieldHelp(): boolean;
+    fieldHelpInlineText(): string;
+    fieldHelpPopoverText(): string;
+    fieldHelpPopoverDisabled(): boolean;
+    fieldHelpAriaLabel(): string;
     protected isInteractionBlockedByState(options?: {
         readonly includeReadonly?: boolean;
         readonly includePresentation?: boolean;