@praxisui/dynamic-fields 8.0.0-beta.21 → 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.
@@ -1899,17 +1904,23 @@ 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;
@@ -2571,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>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@praxisui/dynamic-fields",
-  "version": "8.0.0-beta.21",
+  "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.21",
-    "@praxisui/cron-builder": "^8.0.0-beta.21"
+    "@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)
 
@@ -319,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. |
@@ -622,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-05-04"
-last_updated: "2026-05-04"
+  - "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
 
@@ -158,6 +160,14 @@ Nao ha paths experimentais confirmados no contrato publico desta revisao.
 | `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)
 
 | Binding/Path | Type | Required | Source | Runtime normalization | Notes |
@@ -192,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)
 
@@ -537,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;