@praxisui/dynamic-fields 8.0.0-beta.20 → 8.0.0-beta.22

package/index.d.ts

@@ -974,6 +974,7 @@ declare abstract class SimpleBaseSelectComponent<T = any> extends SimpleBaseInpu
     /** Holds error message when option loading fails */
     readonly error: _angular_core.WritableSignal<string | null>;
     private readonly matSelectInitEffect;
+    private readonly multipleControlNormalizationEffect;
     /** CRUD service for remote option loading (optional) */
     protected readonly crudService: GenericCrudService<any> | null;
     /** Emits whenever the selected value(s) change */
@@ -1011,6 +1012,8 @@ declare abstract class SimpleBaseSelectComponent<T = any> extends SimpleBaseInpu
     protected defaultPanelClass(): string | string[] | undefined;
     selectPanelClass(): string[];
     protected isInteractionDisabled(): boolean;
+    protected normalizeMultipleControlValue(): void;
+    setExternalControl(control: AbstractControl): void;
     /** Whether to show the clear button (if enabled in metadata) */
     showClear(): boolean;
     /** Clears the selection according to single/multiple mode */
@@ -1103,6 +1106,8 @@ declare abstract class SimpleBaseSelectComponent<T = any> extends SimpleBaseInpu
     selectOption(option: SelectOption<T>): void;
     /** Checks if the provided value is currently selected */
     isSelected(value: T): boolean;
+    isOptionDisabled(option: SelectOption<T>): boolean;
+    protected areOptionValuesEqual(left: unknown, right: unknown): boolean;
     /**
      * Toggles selection of all options when `selectAll` is enabled in multiple
      * selection mode.
@@ -1555,6 +1560,8 @@ declare class DynamicFieldLoaderDirective implements OnInit, OnDestroy, OnChange
     /**
      * Reatribui apenas os FormControls existentes aos componentes/shells sem refazer a renderização.
      */
+    private hasSameRenderShape;
+    private updateExistingFieldMetadata;
     private rebindControlsOnly;
     /** Destroi todos os componentes e limpa o container */
     private destroyComponents;
@@ -1761,6 +1768,7 @@ declare class ColorInputComponent extends SimpleBaseInputComponent {
     ngOnInit(): void;
     validateField(): Promise<ValidationErrors | null>;
     protected getSpecificCssClasses(): string[];
+    effectiveFloatLabelBehavior(): 'always';
     /** Applies component metadata with strong typing. */
     setInputMetadata(metadata: MaterialColorInputMetadata): void;
     /** Programmatically opens the native color picker if supported. */
@@ -1852,6 +1860,7 @@ declare class MaterialDatepickerComponent extends SimpleBaseInputComponent {
     /** Applies component metadata with strong typing. */
     setDatepickerMetadata(metadata: MaterialDatepickerMetadata): void;
     isReadonlyEffective(): boolean;
+    isInputReadonly(): boolean;
     errorStateMatcher(): _angular_material_error_options_d_CGdTZUYk.E;
     showClear(): boolean;
     onClearClick(): void;
@@ -1895,16 +1904,26 @@ declare class MaterialDateRangeComponent extends SimpleBaseInputComponent implem
     readonly maxDate: _angular_core.Signal<any>;
     readonly startAt: _angular_core.Signal<any>;
     overlayOpen: boolean;
+    readonly shortcutOverlayViewportMargin = 12;
+    private pickerOpen;
     private readonly dateAdapter;
     picker: MatDateRangePicker<Date>;
+    private endDateInput?;
     readonly shouldShowShortcuts: () => boolean;
     readonly overlayPositions: () => ConnectedPosition[];
+    private shortcutOverlayBelowPositions;
+    private shortcutOverlayLeftPositions;
+    private shortcutOverlayRightPositions;
     readonly resolvedPresets: _angular_core.Signal<Record<string, DateRangePreset>>;
     readonly shortcutItems: _angular_core.Signal<DateRangeShortcutItem[]>;
     readonly activePresetId: () => string | null;
     writeValue(value: unknown): void;
     ngOnInit(): void;
     protected shouldPropagateRangeGroupChanges(): boolean;
+    protected focusEndDateInput(event: Event): void;
+    private propagateRangeValue;
+    private isEmptyRangeValue;
+    private areDatesEqual;
     validateField(): Promise<ValidationErrors | null>;
     protected getSpecificCssClasses(): string[];
     /** Applies component metadata with strong typing. */
@@ -2563,7 +2582,7 @@ declare class MaterialAsyncSelectComponent extends SimpleBaseSelectComponent {
     protected mapRemoteOption(option: AsyncOption): AsyncRenderedOption;
     protected resolveRemoteOptionValue(option: AsyncOption): unknown;
     protected resolveRemoteOptionDisabled(option: AsyncOption): boolean;
-    private areRemoteOptionValuesEqual;
+    protected areOptionValuesEqual(left: unknown, right: unknown): boolean;
     private normalizeRemoteOptionValue;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<MaterialAsyncSelectComponent, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<MaterialAsyncSelectComponent, "pdx-material-async-select", never, { "readonlyMode": { "alias": "readonlyMode"; "required": false; }; "disabledMode": { "alias": "disabledMode"; "required": false; }; "visible": { "alias": "visible"; "required": false; }; "presentationMode": { "alias": "presentationMode"; "required": false; }; }, {}, never, never, true, never>;
@@ -2794,6 +2813,9 @@ declare class InlineEntityLookupComponent extends MaterialAsyncSelectComponent {
     dialogFilterOperatorHintText(operator: LookupFilterOperator): string;
     dialogApplyFiltersActionText(): string;
     dialogClearFiltersActionText(): string;
+    dialogFilterSelectEmptyText(label: string): string;
+    dialogFilterStartAriaLabelText(label: string): string;
+    dialogFilterEndAriaLabelText(label: string): string;
     dialogPreviewSelectionStateLabelText(): string;
     dialogPreviewSelectionStateText(state: EntityLookupResultState): string;
     dialogSearchAriaLabelText(): string;
@@ -2877,6 +2899,7 @@ declare class EntityLookupDialogComponent implements AfterViewInit {
     readonly dialogSearchControl: FormControl<string | null>;
     readonly filterPanelOpen: FormControl<boolean>;
     private readonly dialogFilterControls;
+    private readonly dialogFilterSecondaryControls;
     private previewIdentity;
     private activeResultIndex;
     ngAfterViewInit(): void;
@@ -2902,9 +2925,22 @@ declare class EntityLookupDialogComponent implements AfterViewInit {
     toggleFilterPanel(): void;
     dialogFilterDefinitions(): LookupFilterDefinitionMetadata[];
     filterPanelToggleText(): string;
-    filterControl(field: string): FormControl<string>;
+    filterControl(field: string): FormControl<unknown>;
+    filterSecondaryControl(field: string): FormControl<unknown>;
     dialogFilterLabel(definition: LookupFilterDefinitionMetadata): string;
     dialogFilterPlaceholder(definition: LookupFilterDefinitionMetadata): string;
+    dialogFilterRangeEndPlaceholder(definition: LookupFilterDefinitionMetadata): string;
+    dialogFilterStartAriaLabel(definition: LookupFilterDefinitionMetadata): string;
+    dialogFilterEndAriaLabel(definition: LookupFilterDefinitionMetadata): string;
+    dialogFilterInputType(definition: LookupFilterDefinitionMetadata): 'text' | 'date' | 'number';
+    useDialogEnumSelect(definition: LookupFilterDefinitionMetadata): boolean;
+    useDialogMultiSelect(definition: LookupFilterDefinitionMetadata): boolean;
+    useDialogRangeInputs(definition: LookupFilterDefinitionMetadata): boolean;
+    dialogFilterSelectEmptyText(definition: LookupFilterDefinitionMetadata): string;
+    dialogEnumOptions(definition: LookupFilterDefinitionMetadata): Array<{
+        value: string;
+        label: string;
+    }>;
     dialogOperatorHint(definition: LookupFilterDefinitionMetadata): string;
     applyDialogFiltersText(): string;
     clearDialogFiltersText(): string;
@@ -2950,10 +2986,14 @@ declare class EntityLookupDialogComponent implements AfterViewInit {
     previewSelectionStateLabel(): string;
     previewSelectionStateText(item: EntityLookupViewModel): string;
     private initializeDialogFilters;
-    private serializeDialogFilterValue;
+    private dialogFilterEmptyValue;
+    private serializeDialogFilterSingleValue;
+    private serializeDialogFilterScalarValue;
     private buildDialogFilterRequest;
-    private parseDialogFilterValue;
-    private parseDialogFilterPrimitive;
+    private normalizeDialogFilterControlValue;
+    private normalizeDialogFilterScalarValue;
+    private resolveDialogFilterFieldValue;
+    private pushDialogEnumOption;
     private syncPreviewIdentity;
     private focusResultRow;
     private normalizeOptionValue;
@@ -5723,6 +5763,7 @@ declare class MaterialColorPickerComponent extends SimpleBaseInputComponent {
     /** Handles color selection from the native input. */
     onNativeColorChange(event: Event): void;
     protected getSpecificCssClasses(): string[];
+    effectiveFloatLabelBehavior(): 'always';
     errorStateMatcher(): _angular_material_error_options_d_CGdTZUYk.E;
     isReadonlyEffective(): boolean;
     previewColor(): string;
@@ -5920,6 +5961,7 @@ declare class PdxColorPickerComponent extends SimpleBaseInputComponent implement
     readonlyEffective(): boolean;
     errorStateMatcher(): _angular_material_error_options_d_CGdTZUYk.E;
     protected getSpecificCssClasses(): string[];
+    effectiveFloatLabelBehavior(): 'always';
     setInputMetadata(meta: ComponentMetadata | null): void;
     private currentMetadataRecord;
     private asRecord;

package/package.json

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

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

@@ -373,6 +373,33 @@ Limites:
 | `metadata.ariaDescribedby` | `string` | Active | `aria-describedby` no elemento nativo. |
 | `metadata.ariaLabelledby` | `string` | Active | `aria-labelledby` no elemento nativo. |
 
+#### Politica de label com prefixos e sufixos
+
+Quando um campo usa `metadata.prefixIcon`, `metadata.suffixIcon`, `clearButton`,
+datepicker toggle, seletor de cor, simbolo de moeda ou qualquer outro conteudo
+renderizado via `matPrefix`/`matSuffix`, a politica recomendada para
+`materialDesign.appearance = 'fill'` ou `'outline'` e:
+
+```json
+{
+  "materialDesign": {
+    "appearance": "outline",
+    "floatLabel": "always",
+    "subscriptSizing": "dynamic"
+  }
+}
+```
+
+Essa regra segue a limitacao documentada pelo Angular Material para campos
+`fill`/`outline`: label em repouso e valor do input nao compartilham o mesmo
+alinhamento, entao prefixos/sufixos podem conflitar visualmente com o label
+quando `floatLabel = 'auto'`.
+
+Para superficies geradas, como filtros avancados, preferir aplicar essa politica
+na camada global que materializa a metadata dos campos. Evite corrigir com CSS
+local movendo label, icone ou notch do `mat-form-field`; esses detalhes sao
+internos do Angular Material e podem mudar entre versoes.
+
 #### Saidas runtime compartilhadas
 
 | Output | Tipo | Quando ocorre |
@@ -387,7 +414,8 @@ Limites:
 1. Tratar `metadata.validators.*` como contrato de UX, sem substituir validacao de dominio no backend.
 2. Manter consistencia entre `required`, `visible` e regras de negocio para evitar bloqueio de submit com campo oculto.
 3. Padronizar `materialDesign` por design system (aparencia, cor e floatLabel) para reduzir variacao visual entre equipes.
-4. Usar `clearButton` com `ariaLabel` para conformidade de acessibilidade.
+4. Usar `floatLabel: 'always'` em campos `fill`/`outline` com prefixos, sufixos ou icones Material.
+5. Usar `clearButton` com `ariaLabel` para conformidade de acessibilidade.
 
 #### Cross-links
 
@@ -400,6 +428,7 @@ Limites:
 
 - Acessibilidade em Angular: https://angular.dev/best-practices/a11y
 - Criacao e manutencao de libraries: https://angular.dev/tools/libraries/creating-libraries
+- Angular Material `mat-form-field`: https://material.angular.io/components/form-field/overview
 
 ## JSON path index
 

package/src/lib/components/material-date-range/pdx-material-date-range.json-api.md

@@ -24,8 +24,9 @@ source_of_truth:
   - "projects/praxis-core/src/lib/models/component-metadata.interface.ts"
   - "projects/praxis-core/src/lib/utils/date-range-presets.util.ts"
   - "projects/praxis-dynamic-fields/src/lib/base/simple-base-input.component.ts"
-source_of_truth_last_verified: "2026-03-06"
-last_updated: "2026-03-06"
+  - "projects/praxis-dynamic-fields/src/lib/utils/praxis-native-date-adapter.ts"
+source_of_truth_last_verified: "2026-05-06"
+last_updated: "2026-05-06"
 toc: true
 sidebar: true
 tags:
@@ -84,6 +85,7 @@ Este documento e a referencia canonica da API JSON de pdx-material-date-range.
 | projects/praxis-core/src/lib/models/component-metadata.interface.ts | schema-types | Arquivo presente no repositorio e usado como evidencia de contrato. |
 | projects/praxis-core/src/lib/utils/date-range-presets.util.ts | runtime-code | Arquivo presente no repositorio e usado como evidencia de contrato. |
 | projects/praxis-dynamic-fields/src/lib/base/simple-base-input.component.ts | runtime-code | Arquivo presente no repositorio e usado como evidencia de contrato. |
+| projects/praxis-dynamic-fields/src/lib/utils/praxis-native-date-adapter.ts | runtime-code | Adapter canonico de parsing manual de datas usado pelos controles Material de data. |
 
 ## Support legend
 
@@ -163,6 +165,14 @@ Nao ha paths experimentais confirmados no contrato publico desta revisao.
 | `metadata.endPlaceholder` | string | false | n/a | component-defined | Partial; verify per source_of_truth. |
 | `metadata.startAriaLabel` | string | false | n/a | component-defined | Partial; verify per source_of_truth. |
 
+### Manual date parsing
+
+- Digitacao manual usa `PraxisNativeDateAdapter` e respeita o `LOCALE_ID` do host.
+- Em locales nao ingleses, como `pt-BR`, datas numericas sao interpretadas como `dd/MM/yyyy`.
+- Em locales ingleses, datas numericas sao interpretadas como `MM/dd/yyyy`.
+- Strings ISO date-only (`YYYY-MM-DD`) sao tratadas como data local, sem deslocamento por timezone.
+- Valores enviados ao backend por ranges devem preservar a semantica date-only quando o campo representa uma data civil.
+
 ### Input bindings (inbound data)
 
 | Binding/Path | Type | Required | Source | Runtime normalization | Notes |
@@ -199,6 +209,7 @@ Nao ha paths experimentais confirmados no contrato publico desta revisao.
 | `component-metadata.interface.ts` | true | browser/dev/prod/ssr | contract resolution | Refer to `projects/praxis-core/src/lib/models/component-metadata.interface.ts`. |
 | `date-range-presets.util.ts` | true | browser/dev/prod/ssr | contract resolution | Refer to `projects/praxis-core/src/lib/utils/date-range-presets.util.ts`. |
 | `simple-base-input.component.ts` | true | browser/dev/prod/ssr | contract resolution | Refer to `projects/praxis-dynamic-fields/src/lib/base/simple-base-input.component.ts`. |
+| `praxis-native-date-adapter.ts` | true | browser/dev/prod/ssr | locale-aware date parsing | Refer to `projects/praxis-dynamic-fields/src/lib/utils/praxis-native-date-adapter.ts`. |
 
 ## Coverage by surface (obrigatorio)
 
@@ -300,6 +311,7 @@ Use quando precisar:
 
 Observacao:
 - valor do campo segue `DateRangeValue` com `startDate` e `endDate` (e opcionalmente `preset`, `label`, `timezone`).
+- Durante a selecao pelo `mat-date-range-picker`, o componente nao propaga um range parcial enquanto o overlay esta aberto; `valueChange` e write-back externo sao emitidos quando inicio e fim estao preenchidos ou quando o picker fecha.
 
 ### 3. Matriz de Cobertura JSON (Completa)
 #### 3.1 Campos especificos do componente
@@ -318,7 +330,7 @@ Observacao:
 | `metadata.endAriaLabel` | `string` | Ativo | ARIA label do input de fim. |
 | `metadata.showShortcuts` | `boolean` | Ativo | Exibe overlay de atalhos ao abrir picker. |
 | `metadata.shortcuts` | `Array<string \| DateRangePreset>` | Ativo | Define atalhos builtin e customizados. |
-| `metadata.shortcutsPosition` | `'left' \| 'right'` | Ativo | Posicao do overlay de atalhos. |
+| `metadata.shortcutsPosition` | `'auto' \| 'below' \| 'left' \| 'right'` | Ativo | Posicao preferencial do overlay de atalhos. O default `auto` prioriza posicionamento abaixo do campo, com fallback lateral e protecao contra recorte no viewport. |
 | `metadata.applyOnShortcutClick` | `boolean` | Ativo | Aplica e fecha automaticamente ao clicar no atalho. |
 | `metadata.i18nShortcuts` | `Partial<Record<...>>` | Ativo | Sobrescreve labels de atalhos builtin. |
 | `metadata.timezone` | `string` | Ativo | Contexto de timezone para calculo de presets builtin. |
@@ -349,7 +361,7 @@ Resumo de composicao deste componente:
 - Paginacao: nao se aplica.
 - Ordenacao: nao se aplica.
 - Selecao: objeto `DateRangeValue` (`startDate`, `endDate`, opcional `preset`).
-- Eventos: `validationChange` + outputs herdados (`valueChange`, `focusChange`, `nativeBlur`, `nativeChange`).
+- Eventos: `validationChange` + outputs herdados (`valueChange`, `focusChange`, `nativeBlur`, `nativeChange`). `valueChange` evita range parcial durante a selecao aberta para preservar o fluxo de escolha de inicio e fim.
 - Renderizacao: `mat-date-range-input` + `mat-date-range-picker` + overlay opcional de atalhos.
 
 ### 5. Exemplo Minimo (JSON + Uso)
@@ -455,7 +467,7 @@ Correcao: verificar `applyOnShortcutClick`; com `false`, o fluxo exige acao manu
 | Event | Payload | Trigger | Stability | Notes |
 | --- | --- | --- | --- | --- |
 | `validationChange` | unknown | runtime-event | Experimental | Check component/runtime implementation. |
-| `valueChange` | unknown | runtime-event | Experimental | Check component/runtime implementation. |
+| `valueChange` | unknown | runtime-event | Experimental | Durante seleção pelo picker, o valor é publicado apenas após o fechamento do calendário; digitação manual fora do picker continua propagando pelas regras normais do CVA. |
 | `focusChange` | unknown | runtime-event | Experimental | Check component/runtime implementation. |
 | `nativeBlur` | unknown | runtime-event | Experimental | Check component/runtime implementation. |
 | `nativeChange` | unknown | runtime-event | Experimental | Check component/runtime implementation. |
@@ -621,3 +633,4 @@ Correcao: verificar `applyOnShortcutClick`; com `false`, o fluxo exige acao manu
 | schema-types | projects/praxis-core/src/lib/models/component-metadata.interface.ts | Primary source of truth for contract and behavior. | 2026-03-06 | verified-path |
 | runtime-code | projects/praxis-core/src/lib/utils/date-range-presets.util.ts | Primary source of truth for contract and behavior. | 2026-03-06 | verified-path |
 | runtime-code | projects/praxis-dynamic-fields/src/lib/base/simple-base-input.component.ts | Primary source of truth for contract and behavior. | 2026-03-06 | verified-path |
+| runtime-code | projects/praxis-dynamic-fields/src/lib/utils/praxis-native-date-adapter.ts | Source of truth for locale-aware manual date parsing. | 2026-05-06 | verified-path |

package/src/lib/components/material-datepicker/pdx-material-datepicker.json-api.md

@@ -22,8 +22,9 @@ source_of_truth:
   - "projects/praxis-dynamic-fields/src/lib/components/material-datepicker/material-datepicker.component.ts"
   - "projects/praxis-core/src/lib/models/material-field-metadata.interface.ts"
   - "projects/praxis-dynamic-fields/src/lib/base/simple-base-input.component.ts"
-source_of_truth_last_verified: "2026-03-06"
-last_updated: "2026-03-06"
+  - "projects/praxis-dynamic-fields/src/lib/utils/praxis-native-date-adapter.ts"
+source_of_truth_last_verified: "2026-05-06"
+last_updated: "2026-05-06"
 toc: true
 sidebar: true
 tags:
@@ -81,6 +82,7 @@ Este documento e a referencia canonica da API JSON de pdx-material-datepicker.
 | projects/praxis-dynamic-fields/src/lib/components/material-datepicker/material-datepicker.component.ts | runtime-code | Arquivo presente no repositorio e usado como evidencia de contrato. |
 | projects/praxis-core/src/lib/models/material-field-metadata.interface.ts | schema-types | Arquivo presente no repositorio e usado como evidencia de contrato. |
 | projects/praxis-dynamic-fields/src/lib/base/simple-base-input.component.ts | runtime-code | Arquivo presente no repositorio e usado como evidencia de contrato. |
+| projects/praxis-dynamic-fields/src/lib/utils/praxis-native-date-adapter.ts | runtime-code | Adapter canonico de parsing manual de datas usado pelos controles Material de data. |
 
 ## Support legend
 
@@ -118,6 +120,7 @@ Este documento e a referencia canonica da API JSON de pdx-material-datepicker.
 | `metadata.controlType` | string | false | n/a | Partial | See Detailed API reference for runtime semantics. |
 | `metadata.minDate` | string | false | n/a | Partial | See Detailed API reference for runtime semantics. |
 | `metadata.maxDate` | string | false | n/a | Partial | See Detailed API reference for runtime semantics. |
+| `metadata.manualInput` | boolean | false | `true` | Active | `false` keeps calendar selection enabled while making the text input readonly. |
 
 ### Supported legacy paths
 
@@ -155,6 +158,15 @@ Nao ha paths experimentais confirmados no contrato publico desta revisao.
 | `metadata.touchUi` | boolean | false | n/a | component-defined | Partial; verify per source_of_truth. |
 | `metadata.dateFilter` | string | false | n/a | component-defined | Partial; verify per source_of_truth. |
 | `metadata.dateFormat` | string | false | n/a | component-defined | Partial; verify per source_of_truth. |
+| `metadata.manualInput` | boolean | false | `true` | `false` blocks manual typing without activating readonly field semantics. | Use for locale-sensitive dates where typed strings would be ambiguous. |
+
+### Manual date parsing
+
+- Digitacao manual usa `PraxisNativeDateAdapter` e respeita o `LOCALE_ID` do host.
+- Em locales nao ingleses, como `pt-BR`, datas numericas sao interpretadas como `dd/MM/yyyy`.
+- Em locales ingleses, datas numericas sao interpretadas como `MM/dd/yyyy`.
+- Strings ISO date-only (`YYYY-MM-DD`) sao tratadas como data local, sem deslocamento por timezone.
+- Use `metadata.manualInput: false` quando o host quiser bloquear digitacao manual e manter apenas selecao pelo calendario.
 
 ### Input bindings (inbound data)
 
@@ -190,6 +202,7 @@ Nao ha paths experimentais confirmados no contrato publico desta revisao.
 | `material-datepicker.component.ts` | true | browser/dev/prod/ssr | contract resolution | Refer to `projects/praxis-dynamic-fields/src/lib/components/material-datepicker/material-datepicker.component.ts`. |
 | `material-field-metadata.interface.ts` | true | browser/dev/prod/ssr | contract resolution | Refer to `projects/praxis-core/src/lib/models/material-field-metadata.interface.ts`. |
 | `simple-base-input.component.ts` | true | browser/dev/prod/ssr | contract resolution | Refer to `projects/praxis-dynamic-fields/src/lib/base/simple-base-input.component.ts`. |
+| `praxis-native-date-adapter.ts` | true | browser/dev/prod/ssr | locale-aware date parsing | Refer to `projects/praxis-dynamic-fields/src/lib/utils/praxis-native-date-adapter.ts`. |
 
 ## Coverage by surface (obrigatorio)
 
@@ -535,3 +548,4 @@ Correcao: validar `validators`/matcher e estado touched/dirty do controle no hos
 | runtime-code | projects/praxis-dynamic-fields/src/lib/components/material-datepicker/material-datepicker.component.ts | Primary source of truth for contract and behavior. | 2026-03-06 | verified-path |
 | schema-types | projects/praxis-core/src/lib/models/material-field-metadata.interface.ts | Primary source of truth for contract and behavior. | 2026-03-06 | verified-path |
 | runtime-code | projects/praxis-dynamic-fields/src/lib/base/simple-base-input.component.ts | Primary source of truth for contract and behavior. | 2026-03-06 | verified-path |
+| runtime-code | projects/praxis-dynamic-fields/src/lib/utils/praxis-native-date-adapter.ts | Source of truth for locale-aware manual date parsing. | 2026-05-06 | verified-path |

package/src/lib/components/material-price-range/pdx-material-price-range.json-api.md

@@ -277,6 +277,9 @@ Em conflito entre alias legado e path canonico, priorizar path canonico e regist
 
 ### 1. Visao Geral e Quando Usar
 `pdx-material-price-range` compoe dois `pdx-material-currency` para modelar faixa monetaria (`minPrice`/`maxPrice`).
+O label do grupo identifica a faixa completa, enquanto `startLabel` e
+`endLabel` identificam as entradas internas. `hint` e renderizado como helper
+text abaixo do grupo, com a mesma hierarquia visual dos hints de `mat-form-field`.
 
 Use quando precisar:
 - capturar intervalo financeiro com mascara de moeda;