@praxisui/dynamic-fields 6.0.0-beta.0 → 8.0.0-beta.0

package/fesm2022/praxisui-dynamic-fields.mjs

@@ -39,6 +39,7 @@ import * as i2$1 from '@angular/material/slide-toggle';
 import { MatSlideToggleModule } from '@angular/material/slide-toggle';
 import * as i4$2 from '@angular/cdk/text-field';
 import { TextFieldModule } from '@angular/cdk/text-field';
+import { parsePhoneNumberFromString, AsYouType } from 'libphonenumber-js';
 import { PraxisDialog } from '@praxisui/dialog';
 import { HttpClient, HttpHeaders, provideHttpClient, withInterceptorsFromDi } from '@angular/common/http';
 import * as i7 from '@angular/material/menu';
@@ -281,6 +282,8 @@ const PRAXIS_DYNAMIC_FIELDS_EN_US = {
     'praxis.dynamicFields.checkboxGroup.optionUnavailableDescription': 'Option unavailable.',
     'praxis.dynamicFields.editorial.textInput.friendlyName': 'Text input',
     'praxis.dynamicFields.editorial.textInput.description': 'Simple text field with validation and icon/placeholder support.',
+    'praxis.dynamicFields.editorial.phoneInput.friendlyName': 'Phone input',
+    'praxis.dynamicFields.editorial.phoneInput.description': 'Country-aware phone field with progressive masking and semantic validation.',
     'praxis.dynamicFields.editorial.numericTextBox.friendlyName': 'Numeric input',
     'praxis.dynamicFields.editorial.numericTextBox.description': 'Numeric field with validation (min, max, pattern).',
     'praxis.dynamicFields.editorial.select.friendlyName': 'Select (Material)',
@@ -492,6 +495,8 @@ const PRAXIS_DYNAMIC_FIELDS_PT_BR = {
     'praxis.dynamicFields.checkboxGroup.optionUnavailableDescription': 'Opção indisponível.',
     'praxis.dynamicFields.editorial.textInput.friendlyName': 'Entrada de texto',
     'praxis.dynamicFields.editorial.textInput.description': 'Campo de texto simples com validação e suporte a ícones/placeholder.',
+    'praxis.dynamicFields.editorial.phoneInput.friendlyName': 'Entrada de telefone',
+    'praxis.dynamicFields.editorial.phoneInput.description': 'Campo telefônico com máscara progressiva por país e validação semântica.',
     'praxis.dynamicFields.editorial.numericTextBox.friendlyName': 'Entrada numérica',
     'praxis.dynamicFields.editorial.numericTextBox.description': 'Campo numérico com validação (mín, máx, padrão).',
     'praxis.dynamicFields.editorial.select.friendlyName': 'Seleção (Material)',
@@ -2614,6 +2619,7 @@ class SimpleBaseSelectComponent extends SimpleBaseInputComponent {
     global = inject(GlobalConfigService);
     // Dependency cascade support (Phase 1)
     dependencySub = null;
+    remoteSelectionHydrationSub = null;
     hasLoadedOnce = false;
     /** Options filtered according to the current `searchTerm` */
     filteredOptions = computed(() => {
@@ -3145,18 +3151,24 @@ class SimpleBaseSelectComponent extends SimpleBaseInputComponent {
         if (searchTerm && !this.optionSource()) {
             filter[this.optionLabelKey()] = searchTerm;
         }
+        const includeIds = page === 0 ? this.currentIncludeIds() : undefined;
         this.loading.set(true);
         const request$ = this.optionSource()
             ? this.crudService.filterOptionSourceOptions(this.optionSource().key, filter, { pageNumber: page, pageSize: this.pageSize() }, {
                 search: searchTerm || undefined,
                 includeIds: this.optionSource().includeIds
-                    ? this.currentIncludeIds()
+                    ? includeIds
                     : undefined,
             })
-            : this.crudService.filter(filter, {
-                pageNumber: page,
-                pageSize: this.pageSize(),
-            });
+            : includeIds?.length
+                ? this.crudService.filter(filter, {
+                    pageNumber: page,
+                    pageSize: this.pageSize(),
+                }, { includeIds })
+                : this.crudService.filter(filter, {
+                    pageNumber: page,
+                    pageSize: this.pageSize(),
+                });
         request$
             .pipe(takeUntilDestroyed(this.destroyRef), take(1))
             .subscribe({
@@ -3240,6 +3252,45 @@ class SimpleBaseSelectComponent extends SimpleBaseInputComponent {
         // Recreate subscriptions when the bound control instance changes
         queueMicrotask(() => this.setupDependencies());
     }, ...(ngDevMode ? [{ debugName: "_depEffect" }] : []));
+    /** Rebind hydration for remote selected values when FormControl changes */
+    _remoteSelectionEffect = effect(() => {
+        const _ctrl = this.formControl();
+        const _path = this.resourcePath();
+        queueMicrotask(() => this.setupRemoteSelectionHydration());
+    }, ...(ngDevMode ? [{ debugName: "_remoteSelectionEffect" }] : []));
+    setupRemoteSelectionHydration() {
+        if (this.remoteSelectionHydrationSub) {
+            try {
+                this.remoteSelectionHydrationSub.unsubscribe();
+            }
+            catch { }
+            this.remoteSelectionHydrationSub = null;
+        }
+        if (!this.resourcePath()) {
+            return;
+        }
+        const control = this.control();
+        this.remoteSelectionHydrationSub = control.valueChanges
+            .pipe(startWith(control.value), takeUntilDestroyed(this.destroyRef))
+            .subscribe(() => {
+            this.ensureCurrentValueLoaded();
+        });
+    }
+    ensureCurrentValueLoaded() {
+        if (!this.resourcePath() || this.loading()) {
+            return;
+        }
+        const selected = this.currentIncludeIds();
+        if (!selected.length) {
+            return;
+        }
+        const hasAllSelectedOptions = selected.every((value) => this.options().some((candidate) => this.areSelectValuesEqual(candidate.value, value)));
+        if (hasAllSelectedOptions) {
+            return;
+        }
+        this.pageIndex.set(0);
+        this.loadOptions(0, this.searchTerm(), this.filterCriteria());
+    }
     /** (Re)configure dependency observers based on metadata and current FormGroup */
     setupDependencies() {
         // Teardown previous subscriptions if any
@@ -4388,7 +4439,7 @@ class MaterialCheckboxGroupComponent extends SimpleBaseSelectComponent {
                 : !!mappedOptions?.length;
         super.setSelectMetadata({
             ...matMetadata,
-            options: mappedOptions,
+            options: mappedOptions ?? [],
             multiple,
             searchable: matMetadata.searchable,
             selectAll: matMetadata.selectAll,
@@ -7558,168 +7609,234 @@ function createNumberInputComponentMetadata(locale = 'en-US') {
     return createWave1ComponentDocMeta(PDX_NUMBER_INPUT_EDITORIAL_DESCRIPTOR, locale);
 }
 
-// =============================================================================
-// INTERFACES ESPECÍFICAS DO TEXT-INPUT (herda BaseValidationConfig)
-// =============================================================================
-class TextInputComponent extends SimpleBaseInputComponent {
-    // =============================================================================
-    // OUTPUTS ESPECÍFICOS
-    // =============================================================================
+/**
+ * Specialized input component for telephone numbers.
+ *
+ * Renders a `<mat-form-field>` wrapping an `<input type="tel">` element with
+ * Material styling. Built on top of `SimpleBaseInputComponent` to leverage
+ * reactive forms integration, hint/error messaging and validation hooks.
+ */
+class PhoneInputComponent extends SimpleBaseInputComponent {
+    /** Emits whenever validation state changes. */
     validationChange = output();
     // Praxis Field States
     readonlyMode = false;
     disabledMode = false;
     visible = true;
     presentationMode = false;
-    isReadonlyEffective() {
-        const st = computeEffectiveState(this.metadataAsField(), {
-            readonlyMode: this.readonlyMode,
-            presentationMode: this.presentationMode,
-        });
-        return st.readonly;
-    }
-    // =============================================================================
-    // COMPUTED PROPERTIES (validação e classes herdadas da base)
-    // =============================================================================
-    // Todas as computed properties (CSS classes, validação, Material Design) estão na base class
-    // =============================================================================
-    // LIFECYCLE
-    // =============================================================================
+    allowedCharactersValidator = Validators.pattern(/^[0-9()+\-\s]*$/);
+    semanticPhoneValidator = (control) => this.validatePhoneControl(control);
     ngOnInit() {
-        super.ngOnInit(); // Chama a inicialização da classe base (já inclui setupValidators)
-        try {
-            this.log('debug', 'TextInput initialized');
+        super.ngOnInit();
+        this.syncPhoneValidators();
+        queueMicrotask(() => this.applyPhoneDisplayValue());
+    }
+    writeValue(value) {
+        super.writeValue(value);
+        queueMicrotask(() => this.applyPhoneDisplayValue());
+    }
+    registerInputElement(el) {
+        super.registerInputElement(el);
+        this.applyPhoneDisplayValue();
+    }
+    handleInput(event) {
+        if (!this.isPhoneRuntimeEnabled()) {
+            super.handleInput(event);
+            return;
         }
-        catch (error) {
-            this.log('error', 'TextInput initialization failed', { error });
+        const input = event.target;
+        const rawValue = input?.value ?? '';
+        const displayValue = this.formatPhoneDisplayValue(rawValue, {
+            allowPartial: true,
+        });
+        const modelValue = this.resolveModelValue(displayValue);
+        if (input && input.value !== displayValue) {
+            input.value = displayValue;
         }
-    }
-    onComponentInit() {
-        // Inicialização específica do text-input
-        const meta = this.metadata();
-        if (meta) {
-            // Inicializar valor padrão se definido
-            if (meta.defaultValue !== undefined && this.control().value == null) {
-                this.control().setValue(meta.defaultValue, { emitEvent: false });
-            }
+        this.setValue(modelValue, { emitEvent: true });
+        if (input && input.value !== displayValue) {
+            input.value = displayValue;
         }
     }
-    /**
-     * Adiciona classes CSS específicas do text-input
-     */
-    getSpecificCssClasses() {
-        return ['pdx-text-input'];
-    }
-    // =============================================================================
-    // EVENT HANDLERS (inherited from base, pode ser customizado se necessário)
-    // =============================================================================
-    // =============================================================================
-    // MÉTODOS PÚBLICOS ESPECÍFICOS
-    // =============================================================================
-    /**
-     * Reset do campo
-     */
-    resetField() {
-        const meta = this.metadata();
-        const defaultValue = meta?.defaultValue ?? null;
-        this.setValue(defaultValue, { emitEvent: false });
-        // Reset estados via base class
-        this.componentState.update((state) => ({
-            ...state,
-            touched: false,
-            dirty: false,
-        }));
-        this.fieldState.update((state) => ({
-            ...state,
-            value: defaultValue,
-            valid: true,
-            errors: null,
-        }));
-        const control = this.control();
-        control.markAsPristine();
-        control.markAsUntouched();
+    handleBlur() {
+        super.handleBlur();
+        if (!this.isPhoneRuntimeEnabled()) {
+            return;
+        }
+        const displayValue = this.formatPhoneDisplayValue(this.control().value, {
+            allowPartial: false,
+        });
+        const modelValue = this.resolveModelValue(displayValue);
+        if (modelValue !== this.control().value) {
+            this.setValue(modelValue, { emitEvent: true });
+        }
+        else {
+            this.control().updateValueAndValidity();
+        }
+        this.setNativeDisplayValue(displayValue);
     }
-    /**
-     * Força validação do campo (override para emitir evento)
-     */
     async validateField() {
         const errors = await super.validateField();
         this.validationChange.emit(errors);
         return errors;
     }
-    /**
-     * Define metadata e aplica configurações
-     */
-    setInputMetadata(metadata) {
-        this.setMetadata(metadata); // Base class já reaplica validators
-        // Reaplicar defaultValue dinamicamente sem recriar componente
-        const ctrl = this.control();
-        if (ctrl && ctrl.pristine && (ctrl.value == null || ctrl.value === '') &&
-            metadata.defaultValue !== undefined) {
-            ctrl.setValue(metadata.defaultValue, { emitEvent: false });
-        }
-    }
-    showClear() {
-        const cfg = this.clearButtonConfig();
-        if (cfg === undefined || cfg === null)
-            return false;
-        const enabled = typeof cfg === 'boolean' ? cfg : cfg.enabled === true;
-        if (!enabled)
-            return false;
-        if (this.disabledMode || this.isReadonlyEffective() || this.presentationMode)
-            return false;
-        if (cfg && typeof cfg === 'object' && cfg.showOnlyWhenFilled) {
-            const v = this.control().value;
-            return v !== null && v !== undefined && String(v) !== '';
-        }
-        return true;
+    getSpecificCssClasses() {
+        return ['pdx-phone-input'];
     }
-    onClearClick() {
-        // Prefer empty string for text input
-        this.setValue('', { emitEvent: true });
-        const control = this.control();
-        control.markAsDirty();
-        control.markAsTouched();
+    /** Applies strongly typed metadata to the component. */
+    setInputMetadata(metadata) {
+        this.setMetadata(metadata);
+        this.syncPhoneValidators();
+        this.applyPhoneDisplayValue();
     }
-    // Material error state matcher derived from metadata configuration
     errorStateMatcher() {
         return getErrorStateMatcherForField(this.metadata());
     }
-    clearButtonConfig() {
-        const raw = this.metadataRecord()?.['clearButton'];
-        if (typeof raw === 'boolean') {
-            return raw;
-        }
-        if (raw && typeof raw === 'object') {
-            return raw;
+    isReadonlyEffective() {
+        const st = computeEffectiveState(this.metadataAsField(), {
+            readonlyMode: this.readonlyMode,
+            presentationMode: this.presentationMode,
+        });
+        return st.readonly;
+    }
+    metadataAsField() {
+        const metadata = this.metadata();
+        if (!metadata || typeof metadata !== 'object') {
+            return null;
         }
-        return null;
+        return metadata;
     }
-    metadataRecord() {
+    phoneMetadata() {
         const metadata = this.metadata();
         return metadata && typeof metadata === 'object'
             ? metadata
-            : null;
+            : {};
     }
-    metadataAsField() {
-        const metadata = this.metadata();
-        if (!metadata || typeof metadata !== 'object') {
+    syncPhoneValidators() {
+        const control = this.control();
+        control.removeValidators([
+            this.allowedCharactersValidator,
+            this.semanticPhoneValidator,
+        ]);
+        control.addValidators(this.allowedCharactersValidator);
+        if (this.phoneMetadata().validatePhoneNumber === true) {
+            control.addValidators(this.semanticPhoneValidator);
+        }
+        control.updateValueAndValidity({ emitEvent: false });
+    }
+    validatePhoneControl(control) {
+        const value = String(control.value ?? '').trim();
+        if (!value) {
             return null;
         }
-        return metadata;
+        const metadata = this.phoneMetadata();
+        const phone = parsePhoneNumberFromString(value, this.resolveDefaultCountry());
+        if (!phone?.isValid()) {
+            return {
+                phoneNumber: {
+                    message: 'Telefone invalido',
+                    defaultCountry: metadata.defaultCountry ?? null,
+                },
+            };
+        }
+        const allowedCountries = this.resolveAllowedCountries();
+        if (allowedCountries.length) {
+            const actualCountry = phone.country;
+            if (!actualCountry || !allowedCountries.includes(actualCountry)) {
+                return {
+                    phoneCountry: {
+                        message: 'Pais do telefone nao permitido',
+                        allowedCountries,
+                        actualCountry: actualCountry ?? null,
+                    },
+                };
+            }
+        }
+        return null;
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.17", ngImport: i0, type: TextInputComponent, deps: null, target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "20.3.17", type: TextInputComponent, isStandalone: true, selector: "pdx-text-input", inputs: { readonlyMode: "readonlyMode", disabledMode: "disabledMode", visible: "visible", presentationMode: "presentationMode" }, outputs: { validationChange: "validationChange" }, host: { properties: { "class": "componentCssClasses()", "class.praxis-disabled": "disabledMode", "style.display": "visible ? \"block\" : \"none\"", "attr.aria-hidden": "visible ? null : \"true\"", "style.width": "\"100%\"", "attr.data-field-type": "\"input\"", "attr.data-field-name": "metadata()?.name", "attr.data-component-id": "componentId()" } }, providers: [
+    isPhoneRuntimeEnabled() {
+        const metadata = this.phoneMetadata();
+        return (metadata.autoFormat === true ||
+            metadata.validatePhoneNumber === true ||
+            !!metadata.phoneFormat);
+    }
+    resolveDefaultCountry() {
+        const country = String(this.phoneMetadata().defaultCountry ?? '')
+            .trim()
+            .toUpperCase();
+        return /^[A-Z]{2}$/.test(country) ? country : undefined;
+    }
+    resolveAllowedCountries() {
+        return (this.phoneMetadata().allowedCountries ?? [])
+            .map((country) => String(country ?? '').trim().toUpperCase())
+            .filter((country) => /^[A-Z]{2}$/.test(country));
+    }
+    resolvePhoneFormat() {
+        return this.phoneMetadata().phoneFormat ?? 'national';
+    }
+    resolveModelValue(displayValue) {
+        const value = String(displayValue ?? '').trim();
+        if (!value) {
+            return '';
+        }
+        const metadata = this.phoneMetadata();
+        const phone = parsePhoneNumberFromString(value, this.resolveDefaultCountry());
+        if (phone?.isValid() &&
+            (metadata.validatePhoneNumber === true || metadata.phoneFormat === 'e164')) {
+            return phone.number;
+        }
+        return displayValue;
+    }
+    formatPhoneDisplayValue(value, options) {
+        const rawValue = String(value ?? '').trim();
+        if (!rawValue) {
+            return '';
+        }
+        const country = this.resolveDefaultCountry();
+        const phone = parsePhoneNumberFromString(rawValue, country);
+        const shouldFormatValidNumber = this.phoneMetadata().autoFormat === true || !!this.phoneMetadata().phoneFormat;
+        if (phone?.isValid() && shouldFormatValidNumber) {
+            switch (this.resolvePhoneFormat()) {
+                case 'e164':
+                    return phone.number;
+                case 'international':
+                    return phone.formatInternational();
+                case 'national':
+                default:
+                    return phone.formatNational();
+            }
+        }
+        if (options.allowPartial && this.phoneMetadata().autoFormat === true) {
+            return new AsYouType(country).input(rawValue);
+        }
+        return rawValue;
+    }
+    applyPhoneDisplayValue() {
+        if (!this.isPhoneRuntimeEnabled()) {
+            return;
+        }
+        const displayValue = this.formatPhoneDisplayValue(this.control().value, {
+            allowPartial: false,
+        });
+        this.setNativeDisplayValue(displayValue);
+    }
+    setNativeDisplayValue(displayValue) {
+        const input = this.nativeElement;
+        if (input && input.value !== displayValue) {
+            input.value = displayValue;
+        }
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.17", ngImport: i0, type: PhoneInputComponent, deps: null, target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "20.3.17", type: PhoneInputComponent, isStandalone: true, selector: "pdx-phone-input", inputs: { readonlyMode: "readonlyMode", disabledMode: "disabledMode", visible: "visible", presentationMode: "presentationMode" }, outputs: { validationChange: "validationChange" }, host: { properties: { "class": "componentCssClasses()", "class.praxis-disabled": "disabledMode", "style.display": "visible ? null : \"none\"", "attr.aria-hidden": "visible ? null : \"true\"", "attr.data-field-type": "\"phone\"", "attr.data-field-name": "metadata()?.name", "attr.data-component-id": "componentId()" } }, providers: [
             {
                 provide: NG_VALUE_ACCESSOR,
-                useExisting: forwardRef(() => TextInputComponent),
+                useExisting: forwardRef(() => PhoneInputComponent),
                 multi: true,
             },
         ], usesInheritance: true, ngImport: i0, template: `
     <mat-form-field
       [appearance]="materialAppearance()"
       [color]="materialColor()"
-      floatLabel="auto"
       [class]="componentCssClasses()"
       [floatLabel]="floatLabelBehavior()"
       [subscriptSizing]="metadata()?.materialDesign?.subscriptSizing || 'fixed'"
@@ -7739,16 +7856,12 @@ class TextInputComponent extends SimpleBaseInputComponent {
           shouldShowPlaceholder && placeholder ? placeholder : null
         "
         [required]="metadata()?.required || false"
-        [type]="inputType()"
-        [autocomplete]="metadata()?.autocomplete || 'off'"
-        [spellcheck]="metadata()?.spellcheck ?? true"
         [readonly]="isReadonlyEffective()"
-        [attr.aria-disabled]="disabledMode ? 'true' : null"
-        [maxlength]="metadata()?.maxLength || null"
-        [minlength]="metadata()?.minLength || null"
+        [autocomplete]="metadata()?.autocomplete || 'tel'"
+        [type]="inputType()"
         [attr.aria-label]="!label && placeholder ? placeholder : null"
+        [attr.aria-disabled]="disabledMode ? 'true' : null"
         [attr.aria-required]="metadata()?.required ? 'true' : 'false'"
-        [attr.aria-invalid]="ariaInvalidAttribute()"
         [matTooltip]="tooltipEnabled() ? errorMessage() : null"
         [matTooltipDisabled]="!(tooltipEnabled() && !!errorMessage())"
         [matTooltipPosition]="tooltipPosition()"
@@ -7759,12 +7872,13 @@ class TextInputComponent extends SimpleBaseInputComponent {
           matSuffix
           [color]="iconPalette(metadata()?.suffixIconColor)"
           [style.color]="iconCustomColor(metadata()?.suffixIconColor)"
+          [praxisIcon]="metadata()!.suffixIcon"
           [matTooltip]="metadata()?.suffixIconTooltip || null"
           [attr.aria-label]="metadata()?.suffixIconAriaLabel || null"
-          [praxisIcon]="metadata()!.suffixIcon"
         ></mat-icon>
       }
 
+      
       @if (showClear()) {
         <button
           mat-icon-button
@@ -7792,26 +7906,18 @@ class TextInputComponent extends SimpleBaseInputComponent {
           metadata()!.hint
         }}</mat-hint>
       }
-
-      @if (metadata()?.showCharacterCount && metadata()?.maxLength) {
-        <mat-hint align="end">
-          {{ (control().value || '').length }} /
-          {{ metadata()!.maxLength }}
-        </mat-hint>
-      }
     </mat-form-field>
-  `, isInline: true, dependencies: [{ kind: "ngmodule", type: CommonModule }, { kind: "ngmodule", type: MatInputModule }, { kind: "directive", type: i3$1.MatInput, selector: "input[matInput], textarea[matInput], select[matNativeControl],      input[matNativeControl], textarea[matNativeControl]", inputs: ["disabled", "id", "placeholder", "name", "required", "type", "errorStateMatcher", "aria-describedby", "value", "readonly", "disabledInteractive"], exportAs: ["matInput"] }, { kind: "component", type: i2.MatFormField, selector: "mat-form-field", inputs: ["hideRequiredMarker", "color", "floatLabel", "appearance", "subscriptSizing", "hintLabel"], exportAs: ["matFormField"] }, { kind: "directive", type: i2.MatLabel, selector: "mat-label" }, { kind: "directive", type: i2.MatHint, selector: "mat-hint", inputs: ["align", "id"] }, { kind: "directive", type: i2.MatError, selector: "mat-error, [matError]", inputs: ["id"] }, { kind: "directive", type: i2.MatPrefix, selector: "[matPrefix], [matIconPrefix], [matTextPrefix]", inputs: ["matTextPrefix"] }, { kind: "directive", type: i2.MatSuffix, selector: "[matSuffix], [matIconSuffix], [matTextSuffix]", inputs: ["matTextSuffix"] }, { kind: "ngmodule", type: MatFormFieldModule }, { kind: "ngmodule", type: MatIconModule }, { kind: "component", type: i4.MatIcon, selector: "mat-icon", inputs: ["color", "inline", "svgIcon", "fontSet", "fontIcon"], exportAs: ["matIcon"] }, { kind: "ngmodule", type: MatTooltipModule }, { kind: "directive", type: i5.MatTooltip, selector: "[matTooltip]", inputs: ["matTooltipPosition", "matTooltipPositionAtOrigin", "matTooltipDisabled", "matTooltipShowDelay", "matTooltipHideDelay", "matTooltipTouchGestures", "matTooltip", "matTooltipClass"], exportAs: ["matTooltip"] }, { kind: "ngmodule", type: MatButtonModule }, { kind: "component", type: i1$2.MatIconButton, selector: "button[mat-icon-button], a[mat-icon-button], button[matIconButton], a[matIconButton]", exportAs: ["matButton", "matAnchor"] }, { kind: "directive", type: PraxisIconDirective, selector: "mat-icon[praxisIcon]", inputs: ["praxisIcon"] }, { kind: "ngmodule", type: ReactiveFormsModule }, { kind: "directive", type: i1$1.DefaultValueAccessor, selector: "input:not([type=checkbox])[formControlName],textarea[formControlName],input:not([type=checkbox])[formControl],textarea[formControl],input:not([type=checkbox])[ngModel],textarea[ngModel],[ngDefaultControl]" }, { kind: "directive", type: i1$1.NgControlStatus, selector: "[formControlName],[ngModel],[formControl]" }, { kind: "directive", type: i1$1.RequiredValidator, selector: ":not([type=checkbox])[required][formControlName],:not([type=checkbox])[required][formControl],:not([type=checkbox])[required][ngModel]", inputs: ["required"] }, { kind: "directive", type: i1$1.MinLengthValidator, selector: "[minlength][formControlName],[minlength][formControl],[minlength][ngModel]", inputs: ["minlength"] }, { kind: "directive", type: i1$1.MaxLengthValidator, selector: "[maxlength][formControlName],[maxlength][formControl],[maxlength][ngModel]", inputs: ["maxlength"] }, { kind: "directive", type: i1$1.FormControlDirective, selector: "[formControl]", inputs: ["formControl", "disabled", "ngModel"], outputs: ["ngModelChange"], exportAs: ["ngForm"] }] });
+  `, isInline: true, dependencies: [{ kind: "ngmodule", type: MatButtonModule }, { kind: "component", type: i1$2.MatIconButton, selector: "button[mat-icon-button], a[mat-icon-button], button[matIconButton], a[matIconButton]", exportAs: ["matButton", "matAnchor"] }, { kind: "ngmodule", type: CommonModule }, { kind: "ngmodule", type: MatFormFieldModule }, { kind: "component", type: i2.MatFormField, selector: "mat-form-field", inputs: ["hideRequiredMarker", "color", "floatLabel", "appearance", "subscriptSizing", "hintLabel"], exportAs: ["matFormField"] }, { kind: "directive", type: i2.MatLabel, selector: "mat-label" }, { kind: "directive", type: i2.MatHint, selector: "mat-hint", inputs: ["align", "id"] }, { kind: "directive", type: i2.MatError, selector: "mat-error, [matError]", inputs: ["id"] }, { kind: "directive", type: i2.MatPrefix, selector: "[matPrefix], [matIconPrefix], [matTextPrefix]", inputs: ["matTextPrefix"] }, { kind: "directive", type: i2.MatSuffix, selector: "[matSuffix], [matIconSuffix], [matTextSuffix]", inputs: ["matTextSuffix"] }, { kind: "ngmodule", type: MatInputModule }, { kind: "directive", type: i3$1.MatInput, selector: "input[matInput], textarea[matInput], select[matNativeControl],      input[matNativeControl], textarea[matNativeControl]", inputs: ["disabled", "id", "placeholder", "name", "required", "type", "errorStateMatcher", "aria-describedby", "value", "readonly", "disabledInteractive"], exportAs: ["matInput"] }, { kind: "ngmodule", type: MatIconModule }, { kind: "component", type: i4.MatIcon, selector: "mat-icon", inputs: ["color", "inline", "svgIcon", "fontSet", "fontIcon"], exportAs: ["matIcon"] }, { kind: "ngmodule", type: MatTooltipModule }, { kind: "directive", type: i5.MatTooltip, selector: "[matTooltip]", inputs: ["matTooltipPosition", "matTooltipPositionAtOrigin", "matTooltipDisabled", "matTooltipShowDelay", "matTooltipHideDelay", "matTooltipTouchGestures", "matTooltip", "matTooltipClass"], exportAs: ["matTooltip"] }, { kind: "directive", type: PraxisIconDirective, selector: "mat-icon[praxisIcon]", inputs: ["praxisIcon"] }, { kind: "ngmodule", type: ReactiveFormsModule }, { kind: "directive", type: i1$1.DefaultValueAccessor, selector: "input:not([type=checkbox])[formControlName],textarea[formControlName],input:not([type=checkbox])[formControl],textarea[formControl],input:not([type=checkbox])[ngModel],textarea[ngModel],[ngDefaultControl]" }, { kind: "directive", type: i1$1.NgControlStatus, selector: "[formControlName],[ngModel],[formControl]" }, { kind: "directive", type: i1$1.RequiredValidator, selector: ":not([type=checkbox])[required][formControlName],:not([type=checkbox])[required][formControl],:not([type=checkbox])[required][ngModel]", inputs: ["required"] }, { kind: "directive", type: i1$1.FormControlDirective, selector: "[formControl]", inputs: ["formControl", "disabled", "ngModel"], outputs: ["ngModelChange"], exportAs: ["ngForm"] }] });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.17", ngImport: i0, type: TextInputComponent, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.17", ngImport: i0, type: PhoneInputComponent, decorators: [{
             type: Component,
             args: [{
-                    selector: 'pdx-text-input',
+                    selector: 'pdx-phone-input',
                     standalone: true,
                     template: `
     <mat-form-field
       [appearance]="materialAppearance()"
       [color]="materialColor()"
-      floatLabel="auto"
       [class]="componentCssClasses()"
       [floatLabel]="floatLabelBehavior()"
       [subscriptSizing]="metadata()?.materialDesign?.subscriptSizing || 'fixed'"
@@ -7831,16 +7937,12 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.17", ngImpo
           shouldShowPlaceholder && placeholder ? placeholder : null
         "
         [required]="metadata()?.required || false"
-        [type]="inputType()"
-        [autocomplete]="metadata()?.autocomplete || 'off'"
-        [spellcheck]="metadata()?.spellcheck ?? true"
         [readonly]="isReadonlyEffective()"
-        [attr.aria-disabled]="disabledMode ? 'true' : null"
-        [maxlength]="metadata()?.maxLength || null"
-        [minlength]="metadata()?.minLength || null"
+        [autocomplete]="metadata()?.autocomplete || 'tel'"
+        [type]="inputType()"
         [attr.aria-label]="!label && placeholder ? placeholder : null"
+        [attr.aria-disabled]="disabledMode ? 'true' : null"
         [attr.aria-required]="metadata()?.required ? 'true' : 'false'"
-        [attr.aria-invalid]="ariaInvalidAttribute()"
         [matTooltip]="tooltipEnabled() ? errorMessage() : null"
         [matTooltipDisabled]="!(tooltipEnabled() && !!errorMessage())"
         [matTooltipPosition]="tooltipPosition()"
@@ -7851,9 +7953,395 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.17", ngImpo
           matSuffix
           [color]="iconPalette(metadata()?.suffixIconColor)"
           [style.color]="iconCustomColor(metadata()?.suffixIconColor)"
+          [praxisIcon]="metadata()!.suffixIcon"
           [matTooltip]="metadata()?.suffixIconTooltip || null"
           [attr.aria-label]="metadata()?.suffixIconAriaLabel || null"
-          [praxisIcon]="metadata()!.suffixIcon"
+        ></mat-icon>
+      }
+
+      
+      @if (showClear()) {
+        <button
+          mat-icon-button
+          matSuffix
+          type="button"
+          (click)="onClearClick()"
+          [disabled]="disabledMode || isReadonlyEffective() || presentationMode"
+          [matTooltip]="clearActionTooltip()"
+          [attr.aria-label]="clearActionAriaLabel()"
+        >
+          <mat-icon
+            [color]="iconPalette(metadata()?.clearButton?.iconColor)"
+            [style.color]="iconCustomColor(metadata()?.clearButton?.iconColor)"
+            [praxisIcon]="metadata()?.clearButton?.icon || 'mi:clear'"
+          ></mat-icon>
+        </button>
+      }
+
+      @if (hasValidationError()) {
+        <mat-error>{{ errorMessage() }}</mat-error>
+      }
+
+      @if (metadata()?.hint && !hasValidationError()) {
+        <mat-hint [align]="metadata()?.hintAlign || 'start'">{{
+          metadata()!.hint
+        }}</mat-hint>
+      }
+    </mat-form-field>
+  `,
+                    imports: [
+                        MatButtonModule,
+                        CommonModule,
+                        MatFormFieldModule,
+                        MatInputModule,
+                        MatIconModule,
+                        MatTooltipModule,
+                        PraxisIconDirective,
+                        ReactiveFormsModule,
+                    ],
+                    providers: [
+                        {
+                            provide: NG_VALUE_ACCESSOR,
+                            useExisting: forwardRef(() => PhoneInputComponent),
+                            multi: true,
+                        },
+                    ],
+                    host: {
+                        '[class]': 'componentCssClasses()',
+                        '[class.praxis-disabled]': 'disabledMode',
+                        '[style.display]': 'visible ? null : "none"',
+                        '[attr.aria-hidden]': 'visible ? null : "true"',
+                        '[attr.data-field-type]': '"phone"',
+                        '[attr.data-field-name]': 'metadata()?.name',
+                        '[attr.data-component-id]': 'componentId()',
+                    },
+                }]
+        }], propDecorators: { validationChange: [{ type: i0.Output, args: ["validationChange"] }], readonlyMode: [{
+                type: Input
+            }], disabledMode: [{
+                type: Input
+            }], visible: [{
+                type: Input
+            }], presentationMode: [{
+                type: Input
+            }] } });
+
+const PDX_PHONE_INPUT_EDITORIAL_DESCRIPTOR = {
+    controlType: FieldControlType.PHONE,
+    componentMetaId: 'pdx-phone-input',
+    selector: 'pdx-phone-input',
+    component: PhoneInputComponent,
+    friendlyName: wave1Message('praxis.dynamicFields.editorial.phoneInput.friendlyName'),
+    description: wave1Message('praxis.dynamicFields.editorial.phoneInput.description'),
+    tooltip: wave1Message('praxis.dynamicFields.editorial.phoneInput.description'),
+    icon: 'call',
+    family: 'text',
+    track: 'material',
+    tags: ['widget', 'field', 'input', 'phone', 'mask', 'validation', 'material'],
+    inputs: createWave1StandardInputs('MaterialPhoneMetadata', 'praxis.dynamicFields.editorial.common.inputs.metadata.description'),
+    outputs: createWave1StandardOutputs(),
+    lib: '@praxisui/dynamic-fields',
+};
+function createPhoneInputComponentMetadata(locale = 'en-US') {
+    return createWave1ComponentDocMeta(PDX_PHONE_INPUT_EDITORIAL_DESCRIPTOR, locale);
+}
+
+// =============================================================================
+// INTERFACES ESPECÍFICAS DO TEXT-INPUT (herda BaseValidationConfig)
+// =============================================================================
+class TextInputComponent extends SimpleBaseInputComponent {
+    // =============================================================================
+    // OUTPUTS ESPECÍFICOS
+    // =============================================================================
+    validationChange = output();
+    // Praxis Field States
+    readonlyMode = false;
+    disabledMode = false;
+    visible = true;
+    presentationMode = false;
+    isReadonlyEffective() {
+        const st = computeEffectiveState(this.metadataAsField(), {
+            readonlyMode: this.readonlyMode,
+            presentationMode: this.presentationMode,
+        });
+        return st.readonly;
+    }
+    // =============================================================================
+    // COMPUTED PROPERTIES (validação e classes herdadas da base)
+    // =============================================================================
+    // Todas as computed properties (CSS classes, validação, Material Design) estão na base class
+    // =============================================================================
+    // LIFECYCLE
+    // =============================================================================
+    ngOnInit() {
+        super.ngOnInit(); // Chama a inicialização da classe base (já inclui setupValidators)
+        try {
+            this.log('debug', 'TextInput initialized');
+        }
+        catch (error) {
+            this.log('error', 'TextInput initialization failed', { error });
+        }
+    }
+    onComponentInit() {
+        // Inicialização específica do text-input
+        const meta = this.metadata();
+        if (meta) {
+            // Inicializar valor padrão se definido
+            if (meta.defaultValue !== undefined && this.control().value == null) {
+                this.control().setValue(meta.defaultValue, { emitEvent: false });
+            }
+        }
+    }
+    /**
+     * Adiciona classes CSS específicas do text-input
+     */
+    getSpecificCssClasses() {
+        return ['pdx-text-input'];
+    }
+    // =============================================================================
+    // EVENT HANDLERS (inherited from base, pode ser customizado se necessário)
+    // =============================================================================
+    // =============================================================================
+    // MÉTODOS PÚBLICOS ESPECÍFICOS
+    // =============================================================================
+    /**
+     * Reset do campo
+     */
+    resetField() {
+        const meta = this.metadata();
+        const defaultValue = meta?.defaultValue ?? null;
+        this.setValue(defaultValue, { emitEvent: false });
+        // Reset estados via base class
+        this.componentState.update((state) => ({
+            ...state,
+            touched: false,
+            dirty: false,
+        }));
+        this.fieldState.update((state) => ({
+            ...state,
+            value: defaultValue,
+            valid: true,
+            errors: null,
+        }));
+        const control = this.control();
+        control.markAsPristine();
+        control.markAsUntouched();
+    }
+    /**
+     * Força validação do campo (override para emitir evento)
+     */
+    async validateField() {
+        const errors = await super.validateField();
+        this.validationChange.emit(errors);
+        return errors;
+    }
+    /**
+     * Define metadata e aplica configurações
+     */
+    setInputMetadata(metadata) {
+        this.setMetadata(metadata); // Base class já reaplica validators
+        // Reaplicar defaultValue dinamicamente sem recriar componente
+        const ctrl = this.control();
+        if (ctrl && ctrl.pristine && (ctrl.value == null || ctrl.value === '') &&
+            metadata.defaultValue !== undefined) {
+            ctrl.setValue(metadata.defaultValue, { emitEvent: false });
+        }
+    }
+    showClear() {
+        const cfg = this.clearButtonConfig();
+        if (cfg === undefined || cfg === null)
+            return false;
+        const enabled = typeof cfg === 'boolean' ? cfg : cfg.enabled === true;
+        if (!enabled)
+            return false;
+        if (this.disabledMode || this.isReadonlyEffective() || this.presentationMode)
+            return false;
+        if (cfg && typeof cfg === 'object' && cfg.showOnlyWhenFilled) {
+            const v = this.control().value;
+            return v !== null && v !== undefined && String(v) !== '';
+        }
+        return true;
+    }
+    onClearClick() {
+        // Prefer empty string for text input
+        this.setValue('', { emitEvent: true });
+        const control = this.control();
+        control.markAsDirty();
+        control.markAsTouched();
+    }
+    // Material error state matcher derived from metadata configuration
+    errorStateMatcher() {
+        return getErrorStateMatcherForField(this.metadata());
+    }
+    clearButtonConfig() {
+        const raw = this.metadataRecord()?.['clearButton'];
+        if (typeof raw === 'boolean') {
+            return raw;
+        }
+        if (raw && typeof raw === 'object') {
+            return raw;
+        }
+        return null;
+    }
+    metadataRecord() {
+        const metadata = this.metadata();
+        return metadata && typeof metadata === 'object'
+            ? metadata
+            : null;
+    }
+    metadataAsField() {
+        const metadata = this.metadata();
+        if (!metadata || typeof metadata !== 'object') {
+            return null;
+        }
+        return metadata;
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.17", ngImport: i0, type: TextInputComponent, deps: null, target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "20.3.17", type: TextInputComponent, isStandalone: true, selector: "pdx-text-input", inputs: { readonlyMode: "readonlyMode", disabledMode: "disabledMode", visible: "visible", presentationMode: "presentationMode" }, outputs: { validationChange: "validationChange" }, host: { properties: { "class": "componentCssClasses()", "class.praxis-disabled": "disabledMode", "style.display": "visible ? \"block\" : \"none\"", "attr.aria-hidden": "visible ? null : \"true\"", "style.width": "\"100%\"", "attr.data-field-type": "\"input\"", "attr.data-field-name": "metadata()?.name", "attr.data-component-id": "componentId()" } }, providers: [
+            {
+                provide: NG_VALUE_ACCESSOR,
+                useExisting: forwardRef(() => TextInputComponent),
+                multi: true,
+            },
+        ], usesInheritance: true, ngImport: i0, template: `
+    <mat-form-field
+      [appearance]="materialAppearance()"
+      [color]="materialColor()"
+      floatLabel="auto"
+      [class]="componentCssClasses()"
+      [floatLabel]="floatLabelBehavior()"
+      [subscriptSizing]="metadata()?.materialDesign?.subscriptSizing || 'fixed'"
+      [hideRequiredMarker]="metadata()?.materialDesign?.hideRequiredMarker || false"
+    >
+      <mat-label>{{ label }}</mat-label>
+
+      @if (metadata()?.prefixIcon) {
+        <mat-icon matPrefix [color]="iconPalette(metadata()?.prefixIconColor)" [style.color]="iconCustomColor(metadata()?.prefixIconColor)" [praxisIcon]="metadata()!.prefixIcon"></mat-icon>
+      }
+
+      <input
+        matInput
+        [formControl]="control()"
+        [errorStateMatcher]="errorStateMatcher()"
+        [attr.placeholder]="
+          shouldShowPlaceholder && placeholder ? placeholder : null
+        "
+        [required]="metadata()?.required || false"
+        [type]="inputType()"
+        [autocomplete]="metadata()?.autocomplete || 'off'"
+        [spellcheck]="metadata()?.spellcheck ?? true"
+        [readonly]="isReadonlyEffective()"
+        [attr.aria-disabled]="disabledMode ? 'true' : null"
+        [maxlength]="metadata()?.maxLength || null"
+        [minlength]="metadata()?.minLength || null"
+        [attr.aria-label]="!label && placeholder ? placeholder : null"
+        [attr.aria-required]="metadata()?.required ? 'true' : 'false'"
+        [attr.aria-invalid]="ariaInvalidAttribute()"
+        [matTooltip]="tooltipEnabled() ? errorMessage() : null"
+        [matTooltipDisabled]="!(tooltipEnabled() && !!errorMessage())"
+        [matTooltipPosition]="tooltipPosition()"
+      />
+
+      @if (metadata()?.suffixIcon) {
+        <mat-icon
+          matSuffix
+          [color]="iconPalette(metadata()?.suffixIconColor)"
+          [style.color]="iconCustomColor(metadata()?.suffixIconColor)"
+          [matTooltip]="metadata()?.suffixIconTooltip || null"
+          [attr.aria-label]="metadata()?.suffixIconAriaLabel || null"
+          [praxisIcon]="metadata()!.suffixIcon"
+        ></mat-icon>
+      }
+
+      @if (showClear()) {
+        <button
+          mat-icon-button
+          matSuffix
+          type="button"
+          (click)="onClearClick()"
+          [disabled]="disabledMode || isReadonlyEffective() || presentationMode"
+          [matTooltip]="clearActionTooltip()"
+          [attr.aria-label]="clearActionAriaLabel()"
+        >
+          <mat-icon
+            [color]="iconPalette(metadata()?.clearButton?.iconColor)"
+            [style.color]="iconCustomColor(metadata()?.clearButton?.iconColor)"
+            [praxisIcon]="metadata()?.clearButton?.icon || 'mi:clear'"
+          ></mat-icon>
+        </button>
+      }
+
+      @if (hasValidationError()) {
+        <mat-error>{{ errorMessage() }}</mat-error>
+      }
+
+      @if (metadata()?.hint && !hasValidationError()) {
+        <mat-hint [align]="metadata()?.hintAlign || 'start'">{{
+          metadata()!.hint
+        }}</mat-hint>
+      }
+
+      @if (metadata()?.showCharacterCount && metadata()?.maxLength) {
+        <mat-hint align="end">
+          {{ (control().value || '').length }} /
+          {{ metadata()!.maxLength }}
+        </mat-hint>
+      }
+    </mat-form-field>
+  `, isInline: true, dependencies: [{ kind: "ngmodule", type: CommonModule }, { kind: "ngmodule", type: MatInputModule }, { kind: "directive", type: i3$1.MatInput, selector: "input[matInput], textarea[matInput], select[matNativeControl],      input[matNativeControl], textarea[matNativeControl]", inputs: ["disabled", "id", "placeholder", "name", "required", "type", "errorStateMatcher", "aria-describedby", "value", "readonly", "disabledInteractive"], exportAs: ["matInput"] }, { kind: "component", type: i2.MatFormField, selector: "mat-form-field", inputs: ["hideRequiredMarker", "color", "floatLabel", "appearance", "subscriptSizing", "hintLabel"], exportAs: ["matFormField"] }, { kind: "directive", type: i2.MatLabel, selector: "mat-label" }, { kind: "directive", type: i2.MatHint, selector: "mat-hint", inputs: ["align", "id"] }, { kind: "directive", type: i2.MatError, selector: "mat-error, [matError]", inputs: ["id"] }, { kind: "directive", type: i2.MatPrefix, selector: "[matPrefix], [matIconPrefix], [matTextPrefix]", inputs: ["matTextPrefix"] }, { kind: "directive", type: i2.MatSuffix, selector: "[matSuffix], [matIconSuffix], [matTextSuffix]", inputs: ["matTextSuffix"] }, { kind: "ngmodule", type: MatFormFieldModule }, { kind: "ngmodule", type: MatIconModule }, { kind: "component", type: i4.MatIcon, selector: "mat-icon", inputs: ["color", "inline", "svgIcon", "fontSet", "fontIcon"], exportAs: ["matIcon"] }, { kind: "ngmodule", type: MatTooltipModule }, { kind: "directive", type: i5.MatTooltip, selector: "[matTooltip]", inputs: ["matTooltipPosition", "matTooltipPositionAtOrigin", "matTooltipDisabled", "matTooltipShowDelay", "matTooltipHideDelay", "matTooltipTouchGestures", "matTooltip", "matTooltipClass"], exportAs: ["matTooltip"] }, { kind: "ngmodule", type: MatButtonModule }, { kind: "component", type: i1$2.MatIconButton, selector: "button[mat-icon-button], a[mat-icon-button], button[matIconButton], a[matIconButton]", exportAs: ["matButton", "matAnchor"] }, { kind: "directive", type: PraxisIconDirective, selector: "mat-icon[praxisIcon]", inputs: ["praxisIcon"] }, { kind: "ngmodule", type: ReactiveFormsModule }, { kind: "directive", type: i1$1.DefaultValueAccessor, selector: "input:not([type=checkbox])[formControlName],textarea[formControlName],input:not([type=checkbox])[formControl],textarea[formControl],input:not([type=checkbox])[ngModel],textarea[ngModel],[ngDefaultControl]" }, { kind: "directive", type: i1$1.NgControlStatus, selector: "[formControlName],[ngModel],[formControl]" }, { kind: "directive", type: i1$1.RequiredValidator, selector: ":not([type=checkbox])[required][formControlName],:not([type=checkbox])[required][formControl],:not([type=checkbox])[required][ngModel]", inputs: ["required"] }, { kind: "directive", type: i1$1.MinLengthValidator, selector: "[minlength][formControlName],[minlength][formControl],[minlength][ngModel]", inputs: ["minlength"] }, { kind: "directive", type: i1$1.MaxLengthValidator, selector: "[maxlength][formControlName],[maxlength][formControl],[maxlength][ngModel]", inputs: ["maxlength"] }, { kind: "directive", type: i1$1.FormControlDirective, selector: "[formControl]", inputs: ["formControl", "disabled", "ngModel"], outputs: ["ngModelChange"], exportAs: ["ngForm"] }] });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.17", ngImport: i0, type: TextInputComponent, decorators: [{
+            type: Component,
+            args: [{
+                    selector: 'pdx-text-input',
+                    standalone: true,
+                    template: `
+    <mat-form-field
+      [appearance]="materialAppearance()"
+      [color]="materialColor()"
+      floatLabel="auto"
+      [class]="componentCssClasses()"
+      [floatLabel]="floatLabelBehavior()"
+      [subscriptSizing]="metadata()?.materialDesign?.subscriptSizing || 'fixed'"
+      [hideRequiredMarker]="metadata()?.materialDesign?.hideRequiredMarker || false"
+    >
+      <mat-label>{{ label }}</mat-label>
+
+      @if (metadata()?.prefixIcon) {
+        <mat-icon matPrefix [color]="iconPalette(metadata()?.prefixIconColor)" [style.color]="iconCustomColor(metadata()?.prefixIconColor)" [praxisIcon]="metadata()!.prefixIcon"></mat-icon>
+      }
+
+      <input
+        matInput
+        [formControl]="control()"
+        [errorStateMatcher]="errorStateMatcher()"
+        [attr.placeholder]="
+          shouldShowPlaceholder && placeholder ? placeholder : null
+        "
+        [required]="metadata()?.required || false"
+        [type]="inputType()"
+        [autocomplete]="metadata()?.autocomplete || 'off'"
+        [spellcheck]="metadata()?.spellcheck ?? true"
+        [readonly]="isReadonlyEffective()"
+        [attr.aria-disabled]="disabledMode ? 'true' : null"
+        [maxlength]="metadata()?.maxLength || null"
+        [minlength]="metadata()?.minLength || null"
+        [attr.aria-label]="!label && placeholder ? placeholder : null"
+        [attr.aria-required]="metadata()?.required ? 'true' : 'false'"
+        [attr.aria-invalid]="ariaInvalidAttribute()"
+        [matTooltip]="tooltipEnabled() ? errorMessage() : null"
+        [matTooltipDisabled]="!(tooltipEnabled() && !!errorMessage())"
+        [matTooltipPosition]="tooltipPosition()"
+      />
+
+      @if (metadata()?.suffixIcon) {
+        <mat-icon
+          matSuffix
+          [color]="iconPalette(metadata()?.suffixIconColor)"
+          [style.color]="iconCustomColor(metadata()?.suffixIconColor)"
+          [matTooltip]="metadata()?.suffixIconTooltip || null"
+          [attr.aria-label]="metadata()?.suffixIconAriaLabel || null"
+          [praxisIcon]="metadata()!.suffixIcon"
         ></mat-icon>
       }
 
@@ -7953,6 +8441,7 @@ function createTextInputComponentMetadata(locale = 'en-US') {
 
 const PRAXIS_DYNAMIC_FIELDS_WAVE_1_COMPONENT_METADATA = [
     createTextInputComponentMetadata(),
+    createPhoneInputComponentMetadata(),
     createNumberInputComponentMetadata(),
     createMaterialSelectComponentMetadata(),
     createMaterialTextareaComponentMetadata(),
@@ -7966,6 +8455,7 @@ const PRAXIS_DYNAMIC_FIELDS_WAVE_1_COMPONENT_METADATA = [
 ];
 const PRAXIS_DYNAMIC_FIELDS_EDITORIAL_WAVE_1 = [
     PDX_TEXT_INPUT_EDITORIAL_DESCRIPTOR,
+    PDX_PHONE_INPUT_EDITORIAL_DESCRIPTOR,
     PDX_NUMBER_INPUT_EDITORIAL_DESCRIPTOR,
     PDX_MATERIAL_SELECT_EDITORIAL_DESCRIPTOR,
     PDX_MATERIAL_TEXTAREA_EDITORIAL_DESCRIPTOR,
@@ -10701,19 +11191,10 @@ class DynamicFieldLoaderDirective {
      */
     applyGlobalStates() {
         this.shellRefs.forEach((shellRef) => {
-            if (this.readonlyMode !== null) {
-                shellRef.instance.readonlyMode = this.readonlyMode === true;
-            }
-            if (this.disabledMode !== null) {
-                shellRef.instance.disabledMode = this.disabledMode === true;
-            }
-            if (this.presentationMode !== null) {
-                shellRef.instance.presentationMode = this.presentationMode === true;
-            }
-            if (this.visible !== null) {
-                // visível por padrão; apenas aplicar quando definido
-                shellRef.instance.visible = this.visible !== false ? true : false;
-            }
+            shellRef.instance.readonlyMode = this.readonlyMode === true;
+            shellRef.instance.disabledMode = this.disabledMode === true;
+            shellRef.instance.presentationMode = this.presentationMode === true;
+            shellRef.instance.visible = this.visible !== false ? true : false;
             shellRef.changeDetectorRef.detectChanges();
             const compRef = this.componentRefs.get(shellRef.instance.field?.name);
             if (compRef) {
@@ -43816,254 +44297,6 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.17", ngImpo
                 type: Input
             }] } });
 
-/**
- * Specialized input component for telephone numbers.
- *
- * Renders a `<mat-form-field>` wrapping an `<input type="tel">` element with
- * Material styling. Built on top of `SimpleBaseInputComponent` to leverage
- * reactive forms integration, hint/error messaging and validation hooks.
- */
-class PhoneInputComponent extends SimpleBaseInputComponent {
-    /** Emits whenever validation state changes. */
-    validationChange = output();
-    // Praxis Field States
-    readonlyMode = false;
-    disabledMode = false;
-    visible = true;
-    presentationMode = false;
-    ngOnInit() {
-        super.ngOnInit();
-        this.control().addValidators(Validators.pattern(/^[0-9()+\-\s]*$/));
-    }
-    async validateField() {
-        const errors = await super.validateField();
-        this.validationChange.emit(errors);
-        return errors;
-    }
-    getSpecificCssClasses() {
-        return ['pdx-phone-input'];
-    }
-    /** Applies strongly typed metadata to the component. */
-    setInputMetadata(metadata) {
-        this.setMetadata(metadata);
-    }
-    errorStateMatcher() {
-        return getErrorStateMatcherForField(this.metadata());
-    }
-    isReadonlyEffective() {
-        const st = computeEffectiveState(this.metadataAsField(), {
-            readonlyMode: this.readonlyMode,
-            presentationMode: this.presentationMode,
-        });
-        return st.readonly;
-    }
-    metadataAsField() {
-        const metadata = this.metadata();
-        if (!metadata || typeof metadata !== 'object') {
-            return null;
-        }
-        return metadata;
-    }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.17", ngImport: i0, type: PhoneInputComponent, deps: null, target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "20.3.17", type: PhoneInputComponent, isStandalone: true, selector: "pdx-phone-input", inputs: { readonlyMode: "readonlyMode", disabledMode: "disabledMode", visible: "visible", presentationMode: "presentationMode" }, outputs: { validationChange: "validationChange" }, host: { properties: { "class": "componentCssClasses()", "class.praxis-disabled": "disabledMode", "style.display": "visible ? null : \"none\"", "attr.aria-hidden": "visible ? null : \"true\"", "attr.data-field-type": "\"phone\"", "attr.data-field-name": "metadata()?.name", "attr.data-component-id": "componentId()" } }, providers: [
-            {
-                provide: NG_VALUE_ACCESSOR,
-                useExisting: forwardRef(() => PhoneInputComponent),
-                multi: true,
-            },
-        ], usesInheritance: true, ngImport: i0, template: `
-    <mat-form-field
-      [appearance]="materialAppearance()"
-      [color]="materialColor()"
-      [class]="componentCssClasses()"
-      [floatLabel]="floatLabelBehavior()"
-      [subscriptSizing]="metadata()?.materialDesign?.subscriptSizing || 'fixed'"
-      [hideRequiredMarker]="metadata()?.materialDesign?.hideRequiredMarker || false"
-    >
-      <mat-label>{{ label }}</mat-label>
-
-      @if (metadata()?.prefixIcon) {
-        <mat-icon matPrefix [color]="iconPalette(metadata()?.prefixIconColor)" [style.color]="iconCustomColor(metadata()?.prefixIconColor)" [praxisIcon]="metadata()!.prefixIcon"></mat-icon>
-      }
-
-      <input
-        matInput
-        [formControl]="control()"
-        [errorStateMatcher]="errorStateMatcher()"
-        [attr.placeholder]="
-          shouldShowPlaceholder && placeholder ? placeholder : null
-        "
-        [required]="metadata()?.required || false"
-        [readonly]="isReadonlyEffective()"
-        [autocomplete]="metadata()?.autocomplete || 'tel'"
-        [type]="inputType()"
-        [attr.aria-label]="!label && placeholder ? placeholder : null"
-        [attr.aria-disabled]="disabledMode ? 'true' : null"
-        [attr.aria-required]="metadata()?.required ? 'true' : 'false'"
-        [matTooltip]="tooltipEnabled() ? errorMessage() : null"
-        [matTooltipDisabled]="!(tooltipEnabled() && !!errorMessage())"
-        [matTooltipPosition]="tooltipPosition()"
-      />
-
-      @if (metadata()?.suffixIcon) {
-        <mat-icon
-          matSuffix
-          [color]="iconPalette(metadata()?.suffixIconColor)"
-          [style.color]="iconCustomColor(metadata()?.suffixIconColor)"
-          [praxisIcon]="metadata()!.suffixIcon"
-          [matTooltip]="metadata()?.suffixIconTooltip || null"
-          [attr.aria-label]="metadata()?.suffixIconAriaLabel || null"
-        ></mat-icon>
-      }
-
-      
-      @if (showClear()) {
-        <button
-          mat-icon-button
-          matSuffix
-          type="button"
-          (click)="onClearClick()"
-          [disabled]="disabledMode || isReadonlyEffective() || presentationMode"
-          [matTooltip]="clearActionTooltip()"
-          [attr.aria-label]="clearActionAriaLabel()"
-        >
-          <mat-icon
-            [color]="iconPalette(metadata()?.clearButton?.iconColor)"
-            [style.color]="iconCustomColor(metadata()?.clearButton?.iconColor)"
-            [praxisIcon]="metadata()?.clearButton?.icon || 'mi:clear'"
-          ></mat-icon>
-        </button>
-      }
-
-      @if (hasValidationError()) {
-        <mat-error>{{ errorMessage() }}</mat-error>
-      }
-
-      @if (metadata()?.hint && !hasValidationError()) {
-        <mat-hint [align]="metadata()?.hintAlign || 'start'">{{
-          metadata()!.hint
-        }}</mat-hint>
-      }
-    </mat-form-field>
-  `, isInline: true, dependencies: [{ kind: "ngmodule", type: MatButtonModule }, { kind: "component", type: i1$2.MatIconButton, selector: "button[mat-icon-button], a[mat-icon-button], button[matIconButton], a[matIconButton]", exportAs: ["matButton", "matAnchor"] }, { kind: "ngmodule", type: CommonModule }, { kind: "ngmodule", type: MatFormFieldModule }, { kind: "component", type: i2.MatFormField, selector: "mat-form-field", inputs: ["hideRequiredMarker", "color", "floatLabel", "appearance", "subscriptSizing", "hintLabel"], exportAs: ["matFormField"] }, { kind: "directive", type: i2.MatLabel, selector: "mat-label" }, { kind: "directive", type: i2.MatHint, selector: "mat-hint", inputs: ["align", "id"] }, { kind: "directive", type: i2.MatError, selector: "mat-error, [matError]", inputs: ["id"] }, { kind: "directive", type: i2.MatPrefix, selector: "[matPrefix], [matIconPrefix], [matTextPrefix]", inputs: ["matTextPrefix"] }, { kind: "directive", type: i2.MatSuffix, selector: "[matSuffix], [matIconSuffix], [matTextSuffix]", inputs: ["matTextSuffix"] }, { kind: "ngmodule", type: MatInputModule }, { kind: "directive", type: i3$1.MatInput, selector: "input[matInput], textarea[matInput], select[matNativeControl],      input[matNativeControl], textarea[matNativeControl]", inputs: ["disabled", "id", "placeholder", "name", "required", "type", "errorStateMatcher", "aria-describedby", "value", "readonly", "disabledInteractive"], exportAs: ["matInput"] }, { kind: "ngmodule", type: MatIconModule }, { kind: "component", type: i4.MatIcon, selector: "mat-icon", inputs: ["color", "inline", "svgIcon", "fontSet", "fontIcon"], exportAs: ["matIcon"] }, { kind: "ngmodule", type: MatTooltipModule }, { kind: "directive", type: i5.MatTooltip, selector: "[matTooltip]", inputs: ["matTooltipPosition", "matTooltipPositionAtOrigin", "matTooltipDisabled", "matTooltipShowDelay", "matTooltipHideDelay", "matTooltipTouchGestures", "matTooltip", "matTooltipClass"], exportAs: ["matTooltip"] }, { kind: "directive", type: PraxisIconDirective, selector: "mat-icon[praxisIcon]", inputs: ["praxisIcon"] }, { kind: "ngmodule", type: ReactiveFormsModule }, { kind: "directive", type: i1$1.DefaultValueAccessor, selector: "input:not([type=checkbox])[formControlName],textarea[formControlName],input:not([type=checkbox])[formControl],textarea[formControl],input:not([type=checkbox])[ngModel],textarea[ngModel],[ngDefaultControl]" }, { kind: "directive", type: i1$1.NgControlStatus, selector: "[formControlName],[ngModel],[formControl]" }, { kind: "directive", type: i1$1.RequiredValidator, selector: ":not([type=checkbox])[required][formControlName],:not([type=checkbox])[required][formControl],:not([type=checkbox])[required][ngModel]", inputs: ["required"] }, { kind: "directive", type: i1$1.FormControlDirective, selector: "[formControl]", inputs: ["formControl", "disabled", "ngModel"], outputs: ["ngModelChange"], exportAs: ["ngForm"] }] });
-}
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.17", ngImport: i0, type: PhoneInputComponent, decorators: [{
-            type: Component,
-            args: [{
-                    selector: 'pdx-phone-input',
-                    standalone: true,
-                    template: `
-    <mat-form-field
-      [appearance]="materialAppearance()"
-      [color]="materialColor()"
-      [class]="componentCssClasses()"
-      [floatLabel]="floatLabelBehavior()"
-      [subscriptSizing]="metadata()?.materialDesign?.subscriptSizing || 'fixed'"
-      [hideRequiredMarker]="metadata()?.materialDesign?.hideRequiredMarker || false"
-    >
-      <mat-label>{{ label }}</mat-label>
-
-      @if (metadata()?.prefixIcon) {
-        <mat-icon matPrefix [color]="iconPalette(metadata()?.prefixIconColor)" [style.color]="iconCustomColor(metadata()?.prefixIconColor)" [praxisIcon]="metadata()!.prefixIcon"></mat-icon>
-      }
-
-      <input
-        matInput
-        [formControl]="control()"
-        [errorStateMatcher]="errorStateMatcher()"
-        [attr.placeholder]="
-          shouldShowPlaceholder && placeholder ? placeholder : null
-        "
-        [required]="metadata()?.required || false"
-        [readonly]="isReadonlyEffective()"
-        [autocomplete]="metadata()?.autocomplete || 'tel'"
-        [type]="inputType()"
-        [attr.aria-label]="!label && placeholder ? placeholder : null"
-        [attr.aria-disabled]="disabledMode ? 'true' : null"
-        [attr.aria-required]="metadata()?.required ? 'true' : 'false'"
-        [matTooltip]="tooltipEnabled() ? errorMessage() : null"
-        [matTooltipDisabled]="!(tooltipEnabled() && !!errorMessage())"
-        [matTooltipPosition]="tooltipPosition()"
-      />
-
-      @if (metadata()?.suffixIcon) {
-        <mat-icon
-          matSuffix
-          [color]="iconPalette(metadata()?.suffixIconColor)"
-          [style.color]="iconCustomColor(metadata()?.suffixIconColor)"
-          [praxisIcon]="metadata()!.suffixIcon"
-          [matTooltip]="metadata()?.suffixIconTooltip || null"
-          [attr.aria-label]="metadata()?.suffixIconAriaLabel || null"
-        ></mat-icon>
-      }
-
-      
-      @if (showClear()) {
-        <button
-          mat-icon-button
-          matSuffix
-          type="button"
-          (click)="onClearClick()"
-          [disabled]="disabledMode || isReadonlyEffective() || presentationMode"
-          [matTooltip]="clearActionTooltip()"
-          [attr.aria-label]="clearActionAriaLabel()"
-        >
-          <mat-icon
-            [color]="iconPalette(metadata()?.clearButton?.iconColor)"
-            [style.color]="iconCustomColor(metadata()?.clearButton?.iconColor)"
-            [praxisIcon]="metadata()?.clearButton?.icon || 'mi:clear'"
-          ></mat-icon>
-        </button>
-      }
-
-      @if (hasValidationError()) {
-        <mat-error>{{ errorMessage() }}</mat-error>
-      }
-
-      @if (metadata()?.hint && !hasValidationError()) {
-        <mat-hint [align]="metadata()?.hintAlign || 'start'">{{
-          metadata()!.hint
-        }}</mat-hint>
-      }
-    </mat-form-field>
-  `,
-                    imports: [
-                        MatButtonModule,
-                        CommonModule,
-                        MatFormFieldModule,
-                        MatInputModule,
-                        MatIconModule,
-                        MatTooltipModule,
-                        PraxisIconDirective,
-                        ReactiveFormsModule,
-                    ],
-                    providers: [
-                        {
-                            provide: NG_VALUE_ACCESSOR,
-                            useExisting: forwardRef(() => PhoneInputComponent),
-                            multi: true,
-                        },
-                    ],
-                    host: {
-                        '[class]': 'componentCssClasses()',
-                        '[class.praxis-disabled]': 'disabledMode',
-                        '[style.display]': 'visible ? null : "none"',
-                        '[attr.aria-hidden]': 'visible ? null : "true"',
-                        '[attr.data-field-type]': '"phone"',
-                        '[attr.data-field-name]': 'metadata()?.name',
-                        '[attr.data-component-id]': 'componentId()',
-                    },
-                }]
-        }], propDecorators: { validationChange: [{ type: i0.Output, args: ["validationChange"] }], readonlyMode: [{
-                type: Input
-            }], disabledMode: [{
-                type: Input
-            }], visible: [{
-                type: Input
-            }], presentationMode: [{
-                type: Input
-            }] } });
-
 /**
  * Specialized input component for HTML time inputs.
  *
@@ -48808,26 +49041,7 @@ const PDX_PASSWORD_INPUT_COMPONENT_METADATA = {
     lib: '@praxisui/dynamic-fields',
 };
 
-const PDX_PHONE_INPUT_COMPONENT_METADATA = {
-    id: 'pdx-phone-input',
-    selector: 'pdx-phone-input',
-    component: PhoneInputComponent,
-    friendlyName: 'Telefone (input)',
-    description: 'Campo de telefone com máscara e validação.',
-    icon: 'call',
-    inputs: [
-        { name: 'metadata', type: 'MaterialPhoneMetadata', description: 'Configuração do campo' },
-        { name: 'readonlyMode', type: 'boolean', default: false, description: 'Somente leitura' },
-        { name: 'disabledMode', type: 'boolean', default: false, description: 'Desabilitado' },
-        { name: 'visible', type: 'boolean', default: true, description: 'Visibilidade' },
-        { name: 'presentationMode', type: 'boolean', default: false, description: 'Modo apresentação' },
-    ],
-    outputs: [
-        { name: 'validationChange', type: 'ValidationErrors | null', description: 'Emite ao validar' },
-    ],
-    tags: ['widget', 'field', 'input', 'material', 'phone'],
-    lib: '@praxisui/dynamic-fields',
-};
+const PDX_PHONE_INPUT_COMPONENT_METADATA = createPhoneInputComponentMetadata();
 
 const PDX_PRELOAD_STATUS_COMPONENT_METADATA = {
     id: 'pdx-preload-status',
@@ -49724,7 +49938,7 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'text',
         friendlyName: 'Phone input',
-        description: 'Specialized phone field.',
+        description: 'Specialized phone field with country-aware masking and validation.',
         tags: ['text', 'phone', 'formatted'],
         valueShape: 'string',
         recommendedWhen: ['phone', 'contact'],
@@ -49732,6 +49946,51 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         dataSourceKind: 'local',
         status: 'partial-docs',
         apiPath: jsonApiPath('phone-input/pdx-phone-input.json-api.md'),
+        metadata: {
+            defaultCountry: 'BR',
+            phoneFormat: 'national',
+            autoFormat: true,
+            validatePhoneNumber: true,
+        },
+        previewPresets: [
+            {
+                id: 'br-national',
+                label: 'BR national',
+                description: 'Formats Brazilian mobile numbers with DDD and stores the canonical E.164 value.',
+                metadataPatch: {
+                    defaultCountry: 'BR',
+                    phoneFormat: 'national',
+                    autoFormat: true,
+                    validatePhoneNumber: true,
+                },
+                initialValue: '+5511987654321',
+            },
+            {
+                id: 'br-e164',
+                label: 'BR E.164',
+                description: 'Keeps Brazilian numbers in the canonical E.164 presentation.',
+                metadataPatch: {
+                    defaultCountry: 'BR',
+                    phoneFormat: 'e164',
+                    autoFormat: true,
+                    validatePhoneNumber: true,
+                },
+                initialValue: '+5511987654321',
+            },
+            {
+                id: 'us-international',
+                label: 'US international',
+                description: 'Restricts semantic validation to US numbers and renders international formatting.',
+                metadataPatch: {
+                    defaultCountry: 'US',
+                    allowedCountries: ['US'],
+                    phoneFormat: 'international',
+                    autoFormat: true,
+                    validatePhoneNumber: true,
+                },
+                initialValue: '+14155552671',
+            },
+        ],
     }),
     createEntry({
         id: 'url-input',
@@ -49762,6 +50021,38 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         dataSourceKind: 'local',
         status: 'partial-docs',
         apiPath: jsonApiPath('material-cpf-cnpj-input/pdx-material-cpf-cnpj-input.json-api.md'),
+        previewPresets: [
+            {
+                id: 'cpf',
+                label: 'CPF',
+                description: 'Forces numeric CPF masking and check-digit validation.',
+                metadataPatch: {
+                    documentType: 'cpf',
+                    version: 'legacy',
+                },
+                initialValue: '529.982.247-25',
+            },
+            {
+                id: 'cnpj',
+                label: 'CNPJ',
+                description: 'Forces numeric CNPJ masking and legacy check-digit validation.',
+                metadataPatch: {
+                    documentType: 'cnpj',
+                    version: 'legacy',
+                },
+                initialValue: '11.444.777/0001-61',
+            },
+            {
+                id: 'cnpj-alpha',
+                label: 'CNPJ alpha',
+                description: 'Forces alphanumeric CNPJ masking and alphanumeric check-digit validation.',
+                metadataPatch: {
+                    documentType: 'cnpj',
+                    version: 'alpha',
+                },
+                initialValue: '12.ABC.345/01DE-35',
+            },
+        ],
     }),
     createWave1Entry({
         id: 'number-input',
@@ -49794,6 +50085,57 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         stateRecipes: [
             createDefaultSeedRecipe(18450.75, 'Seeded default preview to expose formatted monetary rendering at first glance.'),
         ],
+        previewPresets: [
+            {
+                id: 'brl',
+                label: 'BRL',
+                description: 'Uses Brazilian Portuguese grouping, decimal separators, and BRL symbol placement.',
+                metadataPatch: {
+                    currency: 'BRL',
+                    locale: 'pt-BR',
+                    decimalPlaces: 2,
+                    currencyPosition: 'before',
+                },
+                initialValue: 18450.75,
+            },
+            {
+                id: 'usd',
+                label: 'USD',
+                description: 'Uses US English grouping and decimal separators with two decimal places.',
+                metadataPatch: {
+                    currency: 'USD',
+                    locale: 'en-US',
+                    decimalPlaces: 2,
+                    currencyPosition: 'before',
+                },
+                initialValue: 9876.5,
+            },
+            {
+                id: 'jpy',
+                label: 'JPY',
+                description: 'Uses Japanese yen formatting with zero decimal places.',
+                metadataPatch: {
+                    currency: 'JPY',
+                    locale: 'ja-JP',
+                    currencyPosition: 'after',
+                },
+                initialValue: 123456,
+            },
+            {
+                id: 'brl-range',
+                label: 'BRL range',
+                description: 'Applies BRL masking with numeric min and max validation.',
+                metadataPatch: {
+                    currency: 'BRL',
+                    locale: 'pt-BR',
+                    decimalPlaces: 2,
+                    currencyPosition: 'before',
+                    min: 0,
+                    max: 1000,
+                },
+                initialValue: 250.75,
+            },
+        ],
     }),
     createEntry({
         id: 'slider',
@@ -49833,7 +50175,7 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         friendlyName: 'Price range',
         description: 'Currency range with dedicated semantics.',
         tags: ['number', 'currency', 'range'],
-        valueShape: '{ min, max }',
+        valueShape: '{ minPrice, maxPrice }',
         recommendedWhen: ['price range', 'salary band', 'minimum and maximum budget'],
         avoidWhen: ['single monetary value'],
         dataSourceKind: 'local',
@@ -49841,6 +50183,54 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         status: 'partial-docs',
         apiPath: jsonApiPath('material-price-range/pdx-material-price-range.json-api.md'),
         metadata: { currency: 'BRL', locale: 'pt-BR' },
+        stateRecipes: [
+            createDefaultSeedRecipe({ minPrice: 1200.5, maxPrice: 5800.75 }, 'Seeded default preview to expose the canonical monetary range payload immediately.'),
+            createFilledSeedRecipe({ minPrice: 3500, maxPrice: 7500 }, 'Filled preview keeps the runtime value aligned with the price range contract.'),
+        ],
+        previewPresets: [
+            {
+                id: 'brl-band',
+                label: 'BRL band',
+                description: 'Uses BRL masking in both range endpoints with Brazilian separators.',
+                metadataPatch: {
+                    currency: 'BRL',
+                    locale: 'pt-BR',
+                    decimalPlaces: 2,
+                    currencyPosition: 'before',
+                    startLabel: 'Minimum price',
+                    endLabel: 'Maximum price',
+                },
+                initialValue: { minPrice: 1200.5, maxPrice: 5800.75 },
+            },
+            {
+                id: 'usd-band',
+                label: 'USD band',
+                description: 'Uses USD masking in both range endpoints with US separators.',
+                metadataPatch: {
+                    currency: 'USD',
+                    locale: 'en-US',
+                    decimalPlaces: 2,
+                    currencyPosition: 'before',
+                    startLabel: 'Minimum price',
+                    endLabel: 'Maximum price',
+                },
+                initialValue: { minPrice: 2500, maxPrice: 12500.5 },
+            },
+            {
+                id: 'brl-limited',
+                label: 'BRL limited',
+                description: 'Adds min and max validation while preserving BRL masking.',
+                metadataPatch: {
+                    currency: 'BRL',
+                    locale: 'pt-BR',
+                    decimalPlaces: 2,
+                    currencyPosition: 'before',
+                    min: 0,
+                    max: 10000,
+                },
+                initialValue: { minPrice: 3500, maxPrice: 7500 },
+            },
+        ],
     }),
     createEntry({
         id: 'rating',
@@ -49899,6 +50289,7 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         apiPath: jsonApiPath('material-date-range/pdx-material-date-range.json-api.md'),
         stateRecipes: [
             createDefaultSeedRecipe({ startDate: '2026-03-01', endDate: '2026-03-23' }, 'Seeded default preview to demonstrate a complete temporal range without switching states.'),
+            createFilledSeedRecipe({ startDate: '2026-04-01', endDate: '2026-04-30' }, 'Filled preview keeps the runtime value aligned with the published date-range payload.'),
         ],
     }),
     createEntry({