@praxisui/dynamic-fields 3.0.0-beta.5 → 3.0.0-beta.7

package/fesm2022/praxisui-dynamic-fields.mjs

@@ -1,9 +1,9 @@
 import * as i1$3 from '@angular/forms';
 import { NgControl, FormControl, Validators, ReactiveFormsModule, NG_VALUE_ACCESSOR, FormGroup, FormsModule } from '@angular/forms';
 import * as i0 from '@angular/core';
-import { InjectionToken, inject, DestroyRef, ElementRef, ChangeDetectorRef, Injector, signal, output, computed, Input, Directive, viewChild, effect, Injectable, EventEmitter, ViewContainerRef, ViewChild, HostListener, HostBinding, Output, ViewEncapsulation, ChangeDetectionStrategy, Component, Inject, forwardRef, LOCALE_ID, ViewChildren, TemplateRef, ContentChild, ENVIRONMENT_INITIALIZER, APP_INITIALIZER, Optional } from '@angular/core';
+import { InjectionToken, inject, DestroyRef, ElementRef, ChangeDetectorRef, Injector, signal, output, computed, Input, Directive, viewChild, effect, Injectable, LOCALE_ID, EventEmitter, ViewContainerRef, ViewChild, HostListener, HostBinding, Output, ViewEncapsulation, ChangeDetectionStrategy, Component, Inject, forwardRef, ViewChildren, TemplateRef, ContentChild, ENVIRONMENT_INITIALIZER, APP_INITIALIZER, Optional } from '@angular/core';
 import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
-import { providePraxisI18n, PraxisI18nService, isCssTextTransform, getTextTransformer, GenericCrudService, GlobalConfigService, INLINE_FILTER_CONTROL_TYPES, FieldControlType, FieldSelectorRegistry, FIELD_SELECTOR_REGISTRY_BASE, FIELD_SELECTOR_REGISTRY_DISABLE_DEFAULTS, LoggerService, resolveInlineFilterControlType, DEFAULT_FIELD_SELECTOR_CONTROL_TYPE_MAP, PraxisIconDirective, resolveBuiltinPresets, createCpfCnpjValidator, NumericFormat, interpolatePraxisTranslation, ComponentMetadataRegistry, FIELD_METADATA_CAPABILITIES } from '@praxisui/core';
+import { providePraxisI18n, PraxisI18nService, isCssTextTransform, getTextTransformer, GenericCrudService, GlobalConfigService, INLINE_FILTER_CONTROL_TYPES, FieldControlType, FieldSelectorRegistry, FIELD_SELECTOR_REGISTRY_BASE, FIELD_SELECTOR_REGISTRY_DISABLE_DEFAULTS, LoggerService, resolveInlineFilterControlType, DEFAULT_FIELD_SELECTOR_CONTROL_TYPE_MAP, resolveValuePresentation, FieldDataType, PraxisIconDirective, resolveBuiltinPresets, createCpfCnpjValidator, NumericFormat, interpolatePraxisTranslation, ComponentMetadataRegistry, FIELD_METADATA_CAPABILITIES } from '@praxisui/core';
 import { BehaviorSubject, combineLatest, Subscription, firstValueFrom, fromEvent, take as take$1, of, EMPTY } from 'rxjs';
 import { Router } from '@angular/router';
 import * as i1$2 from '@angular/material/dialog';
@@ -12,7 +12,7 @@ import { take, startWith, debounceTime, filter, distinctUntilChanged, switchMap,
 import * as i4$2 from '@angular/material/select';
 import { MatSelect, MatSelectModule } from '@angular/material/select';
 import * as i1 from '@angular/common';
-import { CommonModule, registerLocaleData, CurrencyPipe } from '@angular/common';
+import { formatDate, CommonModule, registerLocaleData, CurrencyPipe } from '@angular/common';
 import * as i1$1 from '@angular/material/button';
 import { MatButtonModule } from '@angular/material/button';
 import * as i3 from '@angular/material/icon';
@@ -4147,47 +4147,33 @@ const LoggerPresets = {
     }
 };
 
+const EMPTY_DISPLAY = '-- Nao informado';
 function isISODate(v) {
     return /^\d{4}-\d{2}-\d{2}$/.test(v);
 }
 function isISODateTimeLocal(v) {
     return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2})?$/.test(v);
 }
-function tryFormatDate(v) {
-    try {
-        const d = new Date(v);
-        if (!isNaN(d.getTime()))
-            return d.toLocaleDateString();
-    }
-    catch { }
-    return v;
-}
-function tryFormatDateTime(v) {
-    try {
-        const d = new Date(v.replace('T', ' '));
-        if (!isNaN(d.getTime()))
-            return d.toLocaleString();
-    }
-    catch { }
-    return v.replace('T', ' ');
-}
-function formatDisplayValue(field, value) {
+function formatDisplayValue(field, value, options) {
     if (value == null)
-        return '— Não informado';
-    if (typeof value === 'boolean') {
-        return value ? 'Sim' : 'Não';
-    }
-    // Arrays → join labels or values
+        return EMPTY_DISPLAY;
     if (Array.isArray(value)) {
         const parts = value.map((item) => {
             if (item && typeof item === 'object') {
-                return item.label ?? item.name ?? String(item.id ?? '');
+                return (item.label ??
+                    item.name ??
+                    String(item.id ?? ''));
             }
             return String(item);
         });
         return parts.filter(Boolean).join(', ');
     }
-    // Option-like objects
+    if (value instanceof Date) {
+        const explicit = resolveFieldPresentation(field, value, options);
+        return explicit
+            ? formatTypedValue(field, value, explicit)
+            : formatHeuristicDateTime(value, options);
+    }
     if (value && typeof value === 'object') {
         const obj = value;
         if (obj.label)
@@ -4205,29 +4191,30 @@ function formatDisplayValue(field, value) {
             return String(obj);
         }
     }
+    const presentation = resolveFieldPresentation(field, value, options);
     if (typeof value === 'string') {
         const trimmed = value.trim();
         if (!trimmed)
-            return '— Não informado';
+            return EMPTY_DISPLAY;
+        if (presentation) {
+            return formatTypedValue(field, trimmed, presentation);
+        }
         if (isISODate(trimmed))
-            return tryFormatDate(trimmed);
-        if (isISODateTimeLocal(trimmed))
-            return tryFormatDateTime(trimmed);
+            return formatHeuristicDate(trimmed, options);
+        if (isISODateTimeLocal(trimmed)) {
+            return formatHeuristicDateTime(trimmed, options);
+        }
         return trimmed;
     }
     if (typeof value === 'number') {
-        const ct = String(field?.controlType || '').toLowerCase();
-        if (ct.includes('currency')) {
-            try {
-                const currency = field?.currency || 'BRL';
-                return new Intl.NumberFormat(undefined, {
-                    style: 'currency',
-                    currency,
-                }).format(value);
-            }
-            catch {
-                return String(value);
-            }
+        if (presentation) {
+            return formatTypedValue(field, value, presentation);
+        }
+        return String(value);
+    }
+    if (typeof value === 'boolean') {
+        if (presentation) {
+            return formatTypedValue(field, value, presentation);
         }
         return String(value);
     }
@@ -4237,22 +4224,437 @@ function formatDisplayValue(field, value) {
  * Formats a value for presentation and linkifies emails/URLs.
  * Rely on Angular's built-in sanitization when binding via [innerHTML].
  */
-function formatDisplayHtml(field, value) {
-    const text = formatDisplayValue(field, value);
-    // Email
+function formatDisplayHtml(field, value, options) {
+    const text = formatDisplayValue(field, value, options);
     const emailRe = /^([A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,})$/i;
     if (emailRe.test(text)) {
         const mailto = `mailto:${text}`;
         return `<a href="${mailto}">${text}</a>`;
     }
-    // URL (http/https only)
     const urlRe = /^(https?:\/\/[^\s]+)$/i;
     if (urlRe.test(text)) {
-        const url = text;
-        return `<a href="${url}" target="_blank" rel="noopener noreferrer">${text}</a>`;
+        return `<a href="${text}" target="_blank" rel="noopener noreferrer">${text}</a>`;
     }
     return text;
 }
+function resolveFieldPresentation(field, value, options) {
+    const config = buildValuePresentationConfig(field, value);
+    if (!config)
+        return null;
+    return resolveValuePresentation(config, {
+        valueLocale: resolveFieldLocale(field),
+        localization: mergeLocalization(options?.localization, buildLegacyFieldLocalization(field)),
+        surfaceLocale: options?.surfaceLocale || undefined,
+        appLocale: options?.appLocale || undefined,
+    });
+}
+function buildValuePresentationConfig(field, value) {
+    const explicit = normalizeExplicitValuePresentation(field?.valuePresentation);
+    if (explicit) {
+        return {
+            ...explicit,
+            currency: {
+                ...resolveLegacyCurrencyOverrides(field),
+                ...(explicit.currency || {}),
+            },
+            number: {
+                ...resolveLegacyNumberOverrides(field),
+                ...(explicit.number || {}),
+            },
+        };
+    }
+    const inferredType = inferValuePresentationType(field, value);
+    if (!inferredType)
+        return null;
+    return {
+        type: inferredType,
+        style: inferLegacyPresentationStyle(field),
+        format: normalizeString(field?.format) || undefined,
+        currency: resolveLegacyCurrencyOverrides(field),
+        number: resolveLegacyNumberOverrides(field),
+    };
+}
+function normalizeExplicitValuePresentation(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const config = value;
+    if (!config.type)
+        return null;
+    return config;
+}
+function inferValuePresentationType(field, value) {
+    const controlType = String(field?.controlType || '').trim().toLowerCase();
+    const dataType = String(field?.dataType || '').trim().toLowerCase();
+    const numericFormat = String(field?.numericFormat || '').trim().toLowerCase();
+    const format = normalizeString(field?.format)?.toLowerCase();
+    if (field?.currency || field?.numberFormat?.currency) {
+        return 'currency';
+    }
+    if (numericFormat === 'percent' || format === 'percent') {
+        return 'percentage';
+    }
+    if (controlType === 'currency' ||
+        controlType === 'inlinecurrency') {
+        return 'currency';
+    }
+    if (controlType === 'date' ||
+        controlType === 'dateinput' ||
+        controlType === 'inlinedate') {
+        return 'date';
+    }
+    if (controlType === 'datetime' ||
+        controlType === 'datetimelocal' ||
+        controlType === 'datetimepicker') {
+        return 'datetime';
+    }
+    if (controlType === 'time' ||
+        controlType === 'timepicker' ||
+        controlType === 'inlinetime') {
+        return 'time';
+    }
+    if (controlType === 'numerictextbox' ||
+        controlType === 'inlinenumber' ||
+        controlType === 'year' ||
+        controlType === 'month') {
+        return 'number';
+    }
+    if (dataType === FieldDataType.DATE) {
+        return 'date';
+    }
+    if (dataType === FieldDataType.NUMBER) {
+        return 'number';
+    }
+    if (typeof value === 'boolean') {
+        return 'boolean';
+    }
+    if (typeof value === 'string') {
+        if (isISODate(value.trim()))
+            return 'date';
+        if (isISODateTimeLocal(value.trim()))
+            return 'datetime';
+    }
+    return null;
+}
+function inferLegacyPresentationStyle(field) {
+    const style = normalizeString(field?.displayStyle || field?.styleVariant);
+    switch ((style || '').toLowerCase()) {
+        case 'short':
+            return 'short';
+        case 'medium':
+            return 'medium';
+        case 'long':
+            return 'long';
+        case 'full':
+            return 'full';
+        case 'compact':
+            return 'compact';
+        default:
+            return undefined;
+    }
+}
+function resolveFieldLocale(field) {
+    return (normalizeString(field?.locale) ||
+        normalizeString(field?.numberFormat?.locale) ||
+        undefined);
+}
+function buildLegacyFieldLocalization(field) {
+    const locale = resolveFieldLocale(field);
+    const currency = resolveLegacyCurrencyOverrides(field);
+    const number = resolveLegacyNumberOverrides(field);
+    if (!locale && !currency && !number) {
+        return undefined;
+    }
+    return {
+        ...(locale ? { locale } : {}),
+        direction: 'ltr',
+        ...(currency ? { currency } : {}),
+        ...(number ? { number } : {}),
+    };
+}
+function resolveLegacyCurrencyOverrides(field) {
+    const code = normalizeString(field?.currency) ||
+        normalizeString(field?.numberFormat?.currency);
+    const position = normalizeCurrencyPosition(field?.currencyPosition) ||
+        normalizeCurrencyPosition(field?.numberFormat?.currencyPosition);
+    const precision = resolveLegacyPrecision(field);
+    if (!code && !position && precision == null) {
+        return undefined;
+    }
+    return {
+        code: code || 'USD',
+        symbol: code || 'USD',
+        position: position || 'before',
+        spacing: true,
+        precision: precision ?? 2,
+    };
+}
+function resolveLegacyNumberOverrides(field) {
+    const precision = resolveLegacyPrecision(field);
+    const decimalSeparator = normalizeString(field?.decimalSeparator);
+    const thousandsSeparator = normalizeString(field?.thousandsSeparator);
+    if (precision == null &&
+        !decimalSeparator &&
+        !thousandsSeparator) {
+        return undefined;
+    }
+    return {
+        defaultPrecision: precision ?? 2,
+        decimalSeparator: decimalSeparator || '.',
+        thousandsSeparator: thousandsSeparator || ',',
+        negativeSign: '-',
+        negativeSignPosition: 'before',
+    };
+}
+function resolveLegacyPrecision(field) {
+    const direct = toFiniteNumber(field?.decimalPlaces);
+    if (direct != null)
+        return direct;
+    const nested = toFiniteNumber(field?.numberFormat?.decimalPlaces);
+    if (nested != null)
+        return nested;
+    return undefined;
+}
+function normalizeCurrencyPosition(value) {
+    return value === 'before' || value === 'after' ? value : undefined;
+}
+function mergeLocalization(base, override) {
+    if (!base && !override)
+        return undefined;
+    return {
+        ...(base || {}),
+        ...(override || {}),
+        ...((base?.dateTime || override?.dateTime)
+            ? {
+                dateTime: {
+                    ...(base?.dateTime || {}),
+                    ...(override?.dateTime || {}),
+                },
+            }
+            : {}),
+        ...((base?.number || override?.number)
+            ? {
+                number: {
+                    ...(base?.number || {}),
+                    ...(override?.number || {}),
+                },
+            }
+            : {}),
+        ...((base?.currency || override?.currency)
+            ? {
+                currency: {
+                    ...(base?.currency || {}),
+                    ...(override?.currency || {}),
+                },
+            }
+            : {}),
+        ...((base?.formatting || override?.formatting)
+            ? {
+                formatting: {
+                    ...(base?.formatting || {}),
+                    ...(override?.formatting || {}),
+                },
+            }
+            : {}),
+    };
+}
+function formatTypedValue(field, value, presentation) {
+    switch (presentation.type) {
+        case 'boolean':
+            return formatBooleanPresentation(value, presentation.locale);
+        case 'date':
+        case 'datetime':
+        case 'time':
+            return formatDatePresentation(value, presentation);
+        case 'currency':
+            return formatNumberPresentation(value, presentation, {
+                style: 'currency',
+                currency: presentation.currency?.code || 'USD',
+                currencyPosition: presentation.currency?.position ||
+                    normalizeCurrencyPosition(field?.currencyPosition),
+            });
+        case 'percentage':
+            return formatNumberPresentation(value, presentation, {
+                style: 'percent',
+            });
+        case 'number':
+            return formatNumberPresentation(value, presentation, {
+                style: 'decimal',
+            });
+        default:
+            return String(value);
+    }
+}
+function formatBooleanPresentation(value, locale) {
+    const [trueLabel, falseLabel] = resolveBooleanLabels(locale);
+    if (typeof value === 'string') {
+        const normalized = value.trim().toLowerCase();
+        if (normalized === 'true')
+            return trueLabel;
+        if (normalized === 'false')
+            return falseLabel;
+    }
+    return value ? trueLabel : falseLabel;
+}
+function resolveBooleanLabels(locale) {
+    const normalized = String(locale || '').trim().toLowerCase();
+    if (normalized.startsWith('pt')) {
+        return ['Sim', 'Nao'];
+    }
+    if (normalized.startsWith('es')) {
+        return ['Si', 'No'];
+    }
+    if (normalized.startsWith('fr')) {
+        return ['Oui', 'Non'];
+    }
+    if (normalized.startsWith('de')) {
+        return ['Ja', 'Nein'];
+    }
+    return ['Yes', 'No'];
+}
+function formatDatePresentation(value, presentation) {
+    const dt = presentation.type === 'date'
+        ? coerceDateOnlyCalendarValue(value)
+        : coerceDateValue(value, presentation.type);
+    if (Number.isNaN(dt.getTime())) {
+        return String(value);
+    }
+    try {
+        return formatDate(dt, presentation.format || 'shortDate', presentation.locale);
+    }
+    catch {
+        return new Intl.DateTimeFormat(presentation.locale || undefined).format(dt);
+    }
+}
+function formatNumberPresentation(value, presentation, kind) {
+    const numericValue = typeof value === 'number'
+        ? value
+        : value instanceof Date
+            ? value.getTime()
+            : Number(value);
+    if (!Number.isFinite(numericValue)) {
+        return String(value);
+    }
+    const digits = parseDigitsFormat(presentation.format);
+    const options = {
+        style: kind.style,
+    };
+    if (digits) {
+        options.minimumIntegerDigits = digits.minimumIntegerDigits;
+        options.minimumFractionDigits = digits.minimumFractionDigits;
+        options.maximumFractionDigits = digits.maximumFractionDigits;
+    }
+    if (kind.style === 'currency') {
+        options.currency = kind.currency || 'USD';
+        const parts = (presentation.format || '').split('|').filter(Boolean);
+        if ((parts[1] || '').trim() === 'code') {
+            options.currencyDisplay = 'code';
+        }
+    }
+    const formatter = new Intl.NumberFormat(presentation.locale || undefined, options);
+    const formatted = formatter.format(numericValue);
+    if (kind.style !== 'currency' || !kind.currencyPosition) {
+        return formatted;
+    }
+    return applyCurrencyPosition(formatter, numericValue, formatted, kind.currencyPosition);
+}
+function applyCurrencyPosition(formatter, value, formatted, position) {
+    const parts = formatter.formatToParts(value);
+    const currency = parts
+        .filter((part) => part.type === 'currency')
+        .map((part) => part.value)
+        .join('');
+    if (!currency)
+        return formatted;
+    const withoutCurrency = parts
+        .filter((part) => part.type !== 'currency')
+        .map((part) => part.value)
+        .join('')
+        .trim();
+    if (!withoutCurrency)
+        return formatted;
+    return position === 'after'
+        ? `${withoutCurrency} ${currency}`
+        : `${currency} ${withoutCurrency}`;
+}
+function parseDigitsFormat(format) {
+    if (!format)
+        return null;
+    const match = /^(\d+)\.(\d+)-(\d+)$/.exec(format.trim());
+    if (!match)
+        return null;
+    return {
+        minimumIntegerDigits: Number(match[1]),
+        minimumFractionDigits: Number(match[2]),
+        maximumFractionDigits: Number(match[3]),
+    };
+}
+function formatHeuristicDate(value, options) {
+    try {
+        return formatDate(coerceDateValue(value, 'date'), 'shortDate', options?.surfaceLocale || options?.appLocale || 'en-US');
+    }
+    catch {
+        return value;
+    }
+}
+function formatHeuristicDateTime(value, options) {
+    try {
+        const source = coerceDateValue(value, 'datetime');
+        return formatDate(source, 'short', options?.surfaceLocale || options?.appLocale || 'en-US');
+    }
+    catch {
+        return value instanceof Date ? String(value) : value.replace('T', ' ');
+    }
+}
+function toFiniteNumber(value) {
+    if (typeof value !== 'number' || Number.isNaN(value)) {
+        return undefined;
+    }
+    return Math.floor(value);
+}
+function normalizeString(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed ? trimmed : undefined;
+}
+function coerceDateValue(value, type) {
+    if (value instanceof Date) {
+        return value;
+    }
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (type === 'date' && isISODate(trimmed)) {
+            const [year, month, day] = trimmed.split('-').map(Number);
+            return new Date(year, month - 1, day);
+        }
+        if (type === 'datetime' && isISODateTimeLocal(trimmed)) {
+            return new Date(trimmed);
+        }
+    }
+    return new Date(value);
+}
+function coerceDateOnlyCalendarValue(value) {
+    if (value instanceof Date) {
+        if (Number.isNaN(value.getTime())) {
+            return value;
+        }
+        const localMidnight = value.getHours() === 0 &&
+            value.getMinutes() === 0 &&
+            value.getSeconds() === 0 &&
+            value.getMilliseconds() === 0;
+        if (localMidnight) {
+            return new Date(value.getFullYear(), value.getMonth(), value.getDate());
+        }
+        const utcMidnight = value.getUTCHours() === 0 &&
+            value.getUTCMinutes() === 0 &&
+            value.getUTCSeconds() === 0 &&
+            value.getUTCMilliseconds() === 0;
+        if (utcMidnight) {
+            return new Date(value.getUTCFullYear(), value.getUTCMonth(), value.getUTCDate());
+        }
+    }
+    return coerceDateValue(value, 'date');
+}
 
 /**
  * Internal wrapper used by {@link DynamicFieldLoaderDirective}.
@@ -4262,6 +4664,7 @@ function formatDisplayHtml(field, value) {
  * project additional chrome around the field.
  */
 class FieldShellComponent {
+    hostLocale = inject(LOCALE_ID, { optional: true }) ?? 'en-US';
     /** Metadata for the dynamic field being rendered. */
     field;
     /** Index position of the field within the directive's list. */
@@ -4375,11 +4778,21 @@ class FieldShellComponent {
         const raw = this.control?.value;
         try {
             const fn = this.field?.transformDisplayValue;
-            const formatted = typeof fn === 'function' ? fn(raw) : formatDisplayValue(this.field, raw);
+            const formatted = typeof fn === 'function'
+                ? fn(raw)
+                : formatDisplayValue(this.field, raw, {
+                    appLocale: this.hostLocale,
+                    surfaceLocale: this.field?.localization?.locale ?? this.field?.locale ?? undefined,
+                    localization: this.field?.localization ?? undefined,
+                });
             return formatted == null ? '' : String(formatted);
         }
         catch {
-            return formatDisplayValue(this.field, raw);
+            return formatDisplayValue(this.field, raw, {
+                appLocale: this.hostLocale,
+                surfaceLocale: this.field?.localization?.locale ?? this.field?.locale ?? undefined,
+                localization: this.field?.localization ?? undefined,
+            });
         }
     }
     getPresentationHtml() {
@@ -4388,10 +4801,18 @@ class FieldShellComponent {
             const fn = this.field?.transformDisplayValue;
             const formatted = typeof fn === 'function' ? fn(raw) : null;
             const val = formatted == null ? raw : formatted;
-            return formatDisplayHtml(this.field, val);
+            return formatDisplayHtml(this.field, val, {
+                appLocale: this.hostLocale,
+                surfaceLocale: this.field?.localization?.locale ?? this.field?.locale ?? undefined,
+                localization: this.field?.localization ?? undefined,
+            });
         }
         catch {
-            return formatDisplayHtml(this.field, raw);
+            return formatDisplayHtml(this.field, raw, {
+                appLocale: this.hostLocale,
+                surfaceLocale: this.field?.localization?.locale ?? this.field?.locale ?? undefined,
+                localization: this.field?.localization ?? undefined,
+            });
         }
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.17", ngImport: i0, type: FieldShellComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
@@ -5004,9 +5425,12 @@ class DynamicFieldLoaderDirective {
             });
             this.renderFields();
         }
-        if (changes['readonlyMode'] ||
+        if (changes['presentationMode']) {
+            this.dbg('[DFL] ngOnChanges: presentationMode changed -> re-rendering fields');
+            this.renderFields();
+        }
+        else if (changes['readonlyMode'] ||
             changes['disabledMode'] ||
-            changes['presentationMode'] ||
             changes['visible']) {
             this.applyGlobalStates();
         }
@@ -5497,6 +5921,15 @@ class DynamicFieldLoaderDirective {
             }));
         }
         this.shellSubscriptions.set(field.name, subscriptions);
+        const shouldSkipComponentCreation = shellRef.instance.effectivePresentationMode &&
+            !shellRef.instance.renderContentInPresentation();
+        if (shouldSkipComponentCreation) {
+            this.dbg('[DFL] step: skip field component creation in presentation mode', {
+                name: field.name,
+            });
+            this.shellRefs.set(field.name, shellRef);
+            return null;
+        }
         // Criar o componente dentro do shell
         this.dbg('[DFL] step: create field component start', { name: field.name });
         const componentRef = shellRef.instance.vc.createComponent(componentType);
@@ -9022,15 +9455,15 @@ class MaterialDatepickerComponent extends SimpleBaseInputComponent {
     presentationMode = false;
     minDate = computed(() => {
         const md = this.metadata()?.minDate;
-        return typeof md === 'string' ? new Date(md) : md;
+        return typeof md === 'string' ? this.parseDateOnlyString(md) : md;
     }, ...(ngDevMode ? [{ debugName: "minDate" }] : []));
     maxDate = computed(() => {
         const md = this.metadata()?.maxDate;
-        return typeof md === 'string' ? new Date(md) : md;
+        return typeof md === 'string' ? this.parseDateOnlyString(md) : md;
     }, ...(ngDevMode ? [{ debugName: "maxDate" }] : []));
     startAt = computed(() => {
         const sa = this.metadata()?.startAt;
-        return typeof sa === 'string' ? new Date(sa) : (sa ?? null);
+        return typeof sa === 'string' ? this.parseDateOnlyString(sa) : (sa ?? null);
     }, ...(ngDevMode ? [{ debugName: "startAt" }] : []));
     onDateChange(event) {
         this.setValue(event.value ?? null);
@@ -9101,6 +9534,14 @@ class MaterialDatepickerComponent extends SimpleBaseInputComponent {
         }
         return metadata;
     }
+    parseDateOnlyString(value) {
+        const trimmed = value.trim();
+        if (/^\d{4}-\d{2}-\d{2}$/.test(trimmed)) {
+            const [year, month, day] = trimmed.split('-').map(Number);
+            return new Date(year, month - 1, day);
+        }
+        return new Date(trimmed);
+    }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.17", ngImport: i0, type: MaterialDatepickerComponent, deps: null, target: i0.ɵɵFactoryTarget.Component });
     static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "20.3.17", type: MaterialDatepickerComponent, isStandalone: true, selector: "pdx-material-datepicker", 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": "\"date\"", "attr.data-field-name": "metadata()?.name", "attr.data-component-id": "componentId()" } }, providers: [
             {
@@ -48061,6 +48502,14 @@ class DateUtilsService {
             const date = new Date(y, m - 1, d, h, min, s, ms);
             return isNaN(date.getTime()) ? null : date;
         }
+        if (typeof value === 'string') {
+            const trimmed = value.trim();
+            if (/^\d{4}-\d{2}-\d{2}$/.test(trimmed)) {
+                const [year, month, day] = trimmed.split('-').map(Number);
+                const date = new Date(year, month - 1, day);
+                return isNaN(date.getTime()) ? null : date;
+            }
+        }
         try {
             const parsed = new Date(value);
             return isNaN(parsed.getTime()) ? null : parsed;
@@ -48323,11 +48772,11 @@ const OVERVIEW_SLUG = 'dynamic-fields-overview';
 const SELECTION_GUIDE_SLUG = 'dynamic-fields-field-selection-guide';
 const INLINE_SELECTION_GUIDE_SLUG = 'dynamic-fields-inline-filter-selection-guide';
 const DEFAULT_A11Y_NOTES = [
-    'Use labels claros e nao dependa apenas de placeholder.',
-    'Garanta foco visivel, contraste AA e mensagens de erro textuais.',
+    'Use clear labels and do not rely on placeholders alone.',
+    'Ensure visible focus, AA contrast, and textual error messages.',
 ];
 const DEFAULT_THEMING_NOTES = [
-    'O preview deve respeitar tokens do host e nao introduzir skin isolada da landing.',
+    'The preview must respect host tokens and avoid introducing a landing-only skin.',
 ];
 function detailFragment(controlType) {
     return controlType.toLowerCase().replace(/[^a-z0-9-]+/g, '-');
@@ -48335,6 +48784,95 @@ function detailFragment(controlType) {
 function jsonApiPath(relativePath) {
     return `projects/praxis-dynamic-fields/src/lib/components/${relativePath}`;
 }
+function defaultIconSemantic(input) {
+    const controlType = input.controlType.toLowerCase();
+    let key;
+    let tone;
+    if (controlType.includes('button')) {
+        key = 'action';
+        tone = 'amber';
+    }
+    else if (controlType.includes('cron')) {
+        key = 'automation';
+        tone = 'violet';
+    }
+    else if (controlType.includes('upload') ||
+        controlType.includes('avatar') ||
+        controlType.includes('color')) {
+        key = 'visual';
+        tone = 'teal';
+    }
+    else {
+        switch (input.family) {
+            case 'text':
+                key = 'text';
+                tone = 'blue';
+                break;
+            case 'numbers-range':
+                key = 'numeric';
+                tone = 'amber';
+                break;
+            case 'date-time':
+                key = 'date-time';
+                tone = 'violet';
+                break;
+            case 'selection':
+                key = 'selection';
+                tone = 'green';
+                break;
+            case 'trees-lists':
+                key = 'tree-list';
+                tone = 'slate';
+                break;
+            case 'toggle-choice':
+                key = 'toggle';
+                tone = 'rose';
+                break;
+            case 'upload-color-visual':
+                key = 'visual';
+                tone = 'teal';
+                break;
+            default:
+                key = 'text';
+                tone = 'blue';
+                break;
+        }
+    }
+    return { key, tone };
+}
+function defaultInteractionPattern(input) {
+    const controlType = input.controlType.toLowerCase();
+    if (controlType.includes('textarea'))
+        return 'multi-line';
+    if (controlType.includes('button') || controlType.includes('cron'))
+        return 'trigger';
+    if (controlType.includes('toggle') || controlType.includes('checkbox') || controlType.includes('radio'))
+        return 'toggle';
+    if (controlType.includes('autocomplete') ||
+        controlType.includes('searchable') ||
+        controlType.includes('async') ||
+        controlType.includes('entity-lookup')) {
+        return 'lookup';
+    }
+    if (controlType.includes('multi') || controlType.includes('chips') || controlType.includes('transfer')) {
+        return 'multi-choice';
+    }
+    if (controlType.includes('range') || controlType.includes('period') || controlType.includes('distance')) {
+        return 'range';
+    }
+    if (controlType.includes('avatar') ||
+        controlType.includes('color') ||
+        controlType.includes('rating') ||
+        controlType.includes('pipeline') ||
+        controlType.includes('sentiment') ||
+        controlType.includes('score')) {
+        return 'visual';
+    }
+    if (input.family === 'selection' || input.family === 'trees-lists') {
+        return 'single-choice';
+    }
+    return 'single-value';
+}
 function createEntry(input) {
     const states = input.states ?? ['default', 'filled', 'disabled', 'readonly', 'presentation', 'error'];
     return {
@@ -48375,6 +48913,8 @@ function createEntry(input) {
                 `{ "name": "${input.id}", "label": "${input.friendlyName}", "controlType": "${input.controlType}" }`,
             note: input.snippetNote,
         },
+        icon: input.icon ?? defaultIconSemantic({ controlType: input.controlType, family: input.family }),
+        interactionPattern: input.interactionPattern ?? defaultInteractionPattern({ controlType: input.controlType, family: input.family }),
         a11yNotes: input.a11yNotes ?? DEFAULT_A11Y_NOTES,
         themingNotes: input.themingNotes ?? DEFAULT_THEMING_NOTES,
     };
@@ -48395,11 +48935,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'text',
         friendlyName: 'Text input',
-        description: 'Entrada textual curta e canonica para formularios metadata-driven.',
+        description: 'Short canonical text input for metadata-driven forms.',
         tags: ['text', 'input', 'form'],
         valueShape: 'string',
-        recommendedWhen: ['texto livre curto', 'nome', 'descricao curta'],
-        avoidWhen: ['lista governada de opcoes', 'texto longo multi-linha'],
+        recommendedWhen: ['short free text', 'name', 'short description'],
+        avoidWhen: ['governed option list', 'long multi-line text'],
         dataSourceKind: 'local',
         apiPath: jsonApiPath('text-input/pdx-text-input.json-api.md'),
         metadata: { placeholder: 'Type here' },
@@ -48413,11 +48953,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'text',
         friendlyName: 'Email input',
-        description: 'Campo textual especializado para emails.',
+        description: 'Specialized text field for email addresses.',
         tags: ['text', 'email', 'validation'],
         valueShape: 'string',
-        recommendedWhen: ['email validado', 'contato institucional'],
-        avoidWhen: ['texto livre generico'],
+        recommendedWhen: ['validated email', 'institutional contact'],
+        avoidWhen: ['generic free text'],
         dataSourceKind: 'local',
         apiPath: jsonApiPath('email-input/pdx-email-input.json-api.md'),
         metadata: { placeholder: 'name@company.com' },
@@ -48428,11 +48968,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'text',
         friendlyName: 'Password input',
-        description: 'Campo de segredo com mascaramento e interacao apropriada.',
+        description: 'Secret field with masking and appropriate interaction behavior.',
         tags: ['text', 'password', 'security'],
         valueShape: 'string',
-        recommendedWhen: ['segredos', 'credenciais'],
-        avoidWhen: ['valor que precisa ficar legivel em tela'],
+        recommendedWhen: ['secrets', 'credentials'],
+        avoidWhen: ['value that must remain visible on screen'],
         dataSourceKind: 'local',
         apiPath: jsonApiPath('password-input/pdx-password-input.json-api.md'),
     }),
@@ -48442,11 +48982,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'text',
         friendlyName: 'Textarea',
-        description: 'Campo multi-linha para observacoes e conteudo textual maior.',
+        description: 'Multi-line field for notes and longer text content.',
         tags: ['text', 'textarea', 'multiline'],
         valueShape: 'string',
-        recommendedWhen: ['descricao longa', 'observacoes', 'justificativa'],
-        avoidWhen: ['texto curto de uma linha'],
+        recommendedWhen: ['long description', 'notes', 'justification'],
+        avoidWhen: ['short single-line text'],
         dataSourceKind: 'local',
         apiPath: jsonApiPath('material-textarea/pdx-material-textarea.json-api.md'),
         metadata: { rows: 4, placeholder: 'Describe the situation' },
@@ -48457,11 +48997,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'text',
         friendlyName: 'Search input',
-        description: 'Entrada textual dedicada a busca.',
+        description: 'Text input dedicated to search.',
         tags: ['text', 'search', 'query'],
         valueShape: 'string',
-        recommendedWhen: ['busca textual', 'query curta'],
-        avoidWhen: ['campo de negocio comum sem semantica de busca'],
+        recommendedWhen: ['text search', 'short query'],
+        avoidWhen: ['common business field without search semantics'],
         dataSourceKind: 'local',
         apiPath: jsonApiPath('search-input/pdx-search-input.json-api.md'),
         metadata: { placeholder: 'Search records' },
@@ -48472,11 +49012,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'text',
         friendlyName: 'Phone input',
-        description: 'Campo especializado para telefone.',
+        description: 'Specialized phone field.',
         tags: ['text', 'phone', 'formatted'],
         valueShape: 'string',
-        recommendedWhen: ['telefone', 'contato'],
-        avoidWhen: ['dominio sem telefone'],
+        recommendedWhen: ['phone', 'contact'],
+        avoidWhen: ['domain without phone data'],
         dataSourceKind: 'local',
         status: 'partial-docs',
         apiPath: jsonApiPath('phone-input/pdx-phone-input.json-api.md'),
@@ -48487,11 +49027,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'text',
         friendlyName: 'URL input',
-        description: 'Campo para links e URLs.',
+        description: 'Field for links and URLs.',
         tags: ['text', 'url', 'link'],
         valueShape: 'string',
-        recommendedWhen: ['website', 'link institucional'],
-        avoidWhen: ['texto generico'],
+        recommendedWhen: ['website', 'institutional link'],
+        avoidWhen: ['generic text'],
         dataSourceKind: 'local',
         status: 'partial-docs',
         apiPath: jsonApiPath('url-input/pdx-url-input.json-api.md'),
@@ -48502,11 +49042,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'text',
         friendlyName: 'CPF/CNPJ input',
-        description: 'Campo regionalizado para documento brasileiro.',
+        description: 'Regionalized field for Brazilian documents.',
         tags: ['text', 'brazil', 'document'],
         valueShape: 'string',
-        recommendedWhen: ['CPF', 'CNPJ', 'documento BR'],
-        avoidWhen: ['dominio internacional ou sem documento nacional'],
+        recommendedWhen: ['CPF', 'CNPJ', 'Brazilian document'],
+        avoidWhen: ['international domain or domain without a national document'],
         dataSourceKind: 'local',
         status: 'partial-docs',
         apiPath: jsonApiPath('material-cpf-cnpj-input/pdx-material-cpf-cnpj-input.json-api.md'),
@@ -48517,11 +49057,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'numbers-range',
         friendlyName: 'Number input',
-        description: 'Campo numerico canonico para valores pontuais.',
+        description: 'Canonical numeric field for single values.',
         tags: ['number', 'numeric', 'form'],
         valueShape: 'number',
-        recommendedWhen: ['idade', 'quantidade', 'score unico'],
-        avoidWhen: ['range', 'moeda'],
+        recommendedWhen: ['age', 'quantity', 'single score'],
+        avoidWhen: ['range', 'currency'],
         dataSourceKind: 'local',
         status: 'partial-docs',
         apiPath: jsonApiPath('number-input/pdx-number-input.json-api.md'),
@@ -48532,12 +49072,13 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'numbers-range',
         friendlyName: 'Currency input',
-        description: 'Campo monetario para valor unico.',
+        description: 'Currency field for a single monetary value.',
         tags: ['number', 'currency', 'money'],
         valueShape: 'number',
-        recommendedWhen: ['orcamento', 'ticket medio', 'valor monetario unico'],
-        avoidWhen: ['faixa monetaria'],
+        recommendedWhen: ['budget', 'average ticket', 'single monetary value'],
+        avoidWhen: ['currency range'],
         dataSourceKind: 'local',
+        interactionPattern: 'single-value',
         apiPath: jsonApiPath('material-currency/pdx-material-currency.json-api.md'),
         metadata: { currency: 'BRL', locale: 'pt-BR' },
         stateRecipes: [
@@ -48550,11 +49091,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'numbers-range',
         friendlyName: 'Slider',
-        description: 'Campo de faixa continua para valor unico.',
+        description: 'Continuous range control for a single value.',
         tags: ['number', 'slider', 'range'],
         valueShape: 'number',
-        recommendedWhen: ['nota', 'nivel', 'escala continua'],
-        avoidWhen: ['valor financeiro complexo', 'range duplo'],
+        recommendedWhen: ['rating', 'level', 'continuous scale'],
+        avoidWhen: ['complex financial value', 'dual range'],
         dataSourceKind: 'local',
         apiPath: jsonApiPath('material-slider/pdx-material-slider.json-api.md'),
         metadata: { min: 0, max: 10 },
@@ -48565,11 +49106,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'numbers-range',
         friendlyName: 'Range slider',
-        description: 'Campo para faixa numerica com um ou dois bounds.',
+        description: 'Field for a numeric range with one or two bounds.',
         tags: ['number', 'range', 'slider'],
         valueShape: 'number | { start, end }',
-        recommendedWhen: ['faixa numerica', 'limite minimo e maximo'],
-        avoidWhen: ['datas ou horarios'],
+        recommendedWhen: ['numeric range', 'minimum and maximum bound'],
+        avoidWhen: ['dates or times'],
         dataSourceKind: 'local',
         status: 'partial-docs',
         apiPath: jsonApiPath('material-range-slider/pdx-material-range-slider.json-api.md'),
@@ -48580,12 +49121,13 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'numbers-range',
         friendlyName: 'Price range',
-        description: 'Faixa monetaria com semantica propria.',
+        description: 'Currency range with dedicated semantics.',
         tags: ['number', 'currency', 'range'],
         valueShape: '{ min, max }',
-        recommendedWhen: ['faixa de preco', 'banda salarial', 'orcamento minimo/maximo'],
-        avoidWhen: ['valor monetario unico'],
+        recommendedWhen: ['price range', 'salary band', 'minimum and maximum budget'],
+        avoidWhen: ['single monetary value'],
         dataSourceKind: 'local',
+        interactionPattern: 'range',
         status: 'partial-docs',
         apiPath: jsonApiPath('material-price-range/pdx-material-price-range.json-api.md'),
         metadata: { currency: 'BRL', locale: 'pt-BR' },
@@ -48596,12 +49138,14 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'numbers-range',
         friendlyName: 'Rating',
-        description: 'Controle visual de nota.',
+        description: 'Visual rating control.',
         tags: ['number', 'rating', 'visual'],
         valueShape: 'number',
-        recommendedWhen: ['avaliacao visual', 'satisfacao', 'score legivel'],
-        avoidWhen: ['quando numero bruto ja basta'],
+        recommendedWhen: ['visual rating', 'satisfaction', 'readable score'],
+        avoidWhen: ['when a raw number is enough'],
         dataSourceKind: 'local',
+        icon: { key: 'visual', tone: 'amber' },
+        interactionPattern: 'visual',
         apiPath: jsonApiPath('material-rating/pdx-material-rating.json-api.md'),
         metadata: { max: 5 },
     }),
@@ -48611,11 +49155,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'date-time',
         friendlyName: 'Date input',
-        description: 'Input nativo de data.',
+        description: 'Native date input.',
         tags: ['date', 'native', 'time'],
         valueShape: 'string | Date',
-        recommendedWhen: ['integracao simples com input nativo'],
-        avoidWhen: ['quando a UX Material padronizada e obrigatoria'],
+        recommendedWhen: ['simple integration with a native input'],
+        avoidWhen: ['when standardized Material UX is required'],
         dataSourceKind: 'local',
         status: 'partial-docs',
         apiPath: jsonApiPath('date-input/pdx-date-input.json-api.md'),
@@ -48626,11 +49170,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'date-time',
         friendlyName: 'Date picker',
-        description: 'Datepicker Material canonico.',
+        description: 'Canonical Material datepicker.',
         tags: ['date', 'picker', 'material'],
         valueShape: 'Date | string',
-        recommendedWhen: ['data unica', 'consistencia de design system'],
-        avoidWhen: ['range temporal'],
+        recommendedWhen: ['single date', 'design system consistency'],
+        avoidWhen: ['time range'],
         dataSourceKind: 'local',
         apiPath: jsonApiPath('material-datepicker/pdx-material-datepicker.json-api.md'),
     }),
@@ -48640,11 +49184,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'date-time',
         friendlyName: 'Date range',
-        description: 'Intervalo de datas.',
+        description: 'Date interval.',
         tags: ['date', 'range', 'time'],
         valueShape: '{ startDate, endDate }',
-        recommendedWhen: ['periodo', 'janela temporal'],
-        avoidWhen: ['data unica'],
+        recommendedWhen: ['period', 'time window'],
+        avoidWhen: ['single date'],
         dataSourceKind: 'local',
         apiPath: jsonApiPath('material-date-range/pdx-material-date-range.json-api.md'),
         stateRecipes: [
@@ -48657,11 +49201,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'date-time',
         friendlyName: 'Datetime local',
-        description: 'Campo unificado para data e hora local.',
+        description: 'Unified field for local date and time.',
         tags: ['date', 'time', 'datetime'],
         valueShape: 'string',
-        recommendedWhen: ['agendamento local', 'data + hora no mesmo campo'],
-        avoidWhen: ['quando data e hora precisam de UX separada'],
+        recommendedWhen: ['local scheduling', 'date and time in the same field'],
+        avoidWhen: ['when date and time need separate UX'],
         dataSourceKind: 'local',
         status: 'partial-docs',
         apiPath: jsonApiPath('datetime-local-input/pdx-datetime-local-input.json-api.md'),
@@ -48672,11 +49216,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'date-time',
         friendlyName: 'Month input',
-        description: 'Campo especializado para mes e ano.',
+        description: 'Specialized month and year field.',
         tags: ['date', 'month', 'competence'],
         valueShape: 'string',
-        recommendedWhen: ['competencia', 'mes/ano'],
-        avoidWhen: ['data completa'],
+        recommendedWhen: ['accounting period', 'month/year'],
+        avoidWhen: ['full date'],
         dataSourceKind: 'local',
         status: 'partial-docs',
         apiPath: jsonApiPath('month-input/pdx-month-input.json-api.md'),
@@ -48687,11 +49231,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'date-time',
         friendlyName: 'Time input',
-        description: 'Campo simples para horario.',
+        description: 'Simple time field.',
         tags: ['time', 'input', 'hour'],
         valueShape: 'string',
-        recommendedWhen: ['hora simples', 'slot horario'],
-        avoidWhen: ['range horario'],
+        recommendedWhen: ['single time', 'time slot'],
+        avoidWhen: ['time range'],
         dataSourceKind: 'local',
         apiPath: jsonApiPath('time-input/pdx-time-input.json-api.md'),
     }),
@@ -48701,11 +49245,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'date-time',
         friendlyName: 'Time picker',
-        description: 'Seletor Material de horario.',
+        description: 'Material time picker.',
         tags: ['time', 'picker', 'hour'],
         valueShape: 'string',
-        recommendedWhen: ['escolha guiada de horario'],
-        avoidWhen: ['texto/mascara simples e suficiente'],
+        recommendedWhen: ['guided time selection'],
+        avoidWhen: ['simple text or mask is enough'],
         dataSourceKind: 'local',
         apiPath: jsonApiPath('material-timepicker/pdx-material-timepicker.json-api.md'),
     }),
@@ -48715,11 +49259,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'date-time',
         friendlyName: 'Time range',
-        description: 'Intervalo de horario.',
+        description: 'Time interval.',
         tags: ['time', 'range', 'hour'],
         valueShape: '{ start, end }',
-        recommendedWhen: ['janela de atendimento', 'turno'],
-        avoidWhen: ['horario unico'],
+        recommendedWhen: ['service window', 'shift'],
+        avoidWhen: ['single time'],
         dataSourceKind: 'local',
         status: 'partial-docs',
         apiPath: jsonApiPath('pdx-material-time-range/pdx-material-time-range.json-api.md'),
@@ -48730,11 +49274,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'date-time',
         friendlyName: 'Week input',
-        description: 'Campo de semana ISO.',
+        description: 'ISO week field.',
         tags: ['date', 'week', 'iso'],
         valueShape: 'string',
-        recommendedWhen: ['semana de referencia'],
-        avoidWhen: ['negocio centrado em datas convencionais'],
+        recommendedWhen: ['reference week'],
+        avoidWhen: ['domain centered on conventional calendar dates'],
         dataSourceKind: 'local',
         status: 'partial-docs',
         apiPath: jsonApiPath('week-input/pdx-week-input.json-api.md'),
@@ -48745,11 +49289,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'date-time',
         friendlyName: 'Year input',
-        description: 'Campo para ano isolado.',
+        description: 'Field for a standalone year.',
         tags: ['date', 'year', 'fiscal'],
         valueShape: 'number | string',
-        recommendedWhen: ['ano fiscal', 'ano civil isolado'],
-        avoidWhen: ['mes/ano ou data completa'],
+        recommendedWhen: ['fiscal year', 'standalone calendar year'],
+        avoidWhen: ['month/year or full date'],
         dataSourceKind: 'local',
         status: 'partial-docs',
         apiPath: jsonApiPath('pdx-year-input/pdx-year-input.json-api.md'),
@@ -48760,11 +49304,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'selection',
         friendlyName: 'Select',
-        description: 'Lista fechada simples para escolha unica.',
+        description: 'Simple closed list for a single selection.',
         tags: ['selection', 'select', 'options'],
         valueShape: 'string | number | object',
-        recommendedWhen: ['lista pequena estavel', 'escolha unica'],
-        avoidWhen: ['lista grande ou remota'],
+        recommendedWhen: ['small stable list', 'single selection'],
+        avoidWhen: ['large or remote list'],
         dataSourceKind: 'mixed',
         apiPath: jsonApiPath('material-select/pdx-material-select.json-api.md'),
         metadata: {
@@ -48783,14 +49327,28 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'selection',
         friendlyName: 'Searchable select',
-        description: 'Select com busca local para listas medias ou grandes.',
+        description: 'Select with local search for medium or large lists.',
         tags: ['selection', 'select', 'search'],
         valueShape: 'string | number | object',
-        recommendedWhen: ['lista maior com busca', 'descoberta de opcao'],
-        avoidWhen: ['lista remota sob demanda'],
+        recommendedWhen: ['larger list with search', 'option discovery'],
+        avoidWhen: ['remote on-demand list'],
         dataSourceKind: 'mixed',
+        interactionPattern: 'lookup',
         status: 'partial-docs',
         apiPath: jsonApiPath('material-searchable-select/pdx-material-searchable-select.json-api.md'),
+        metadata: {
+            options: [
+                { label: 'Finance', value: 'FINANCE' },
+                { label: 'Operations', value: 'OPERATIONS' },
+                { label: 'People', value: 'PEOPLE' },
+                { label: 'Risk', value: 'RISK' },
+            ],
+            searchable: true,
+            placeholder: 'Search and select',
+        },
+        stateRecipes: [
+            createDefaultSeedRecipe('OPERATIONS', 'Seeded default preview to reveal local search and selected-label rendering.'),
+        ],
     }),
     createEntry({
         id: 'async-select',
@@ -48798,12 +49356,13 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'selection',
         friendlyName: 'Async select',
-        description: 'Select remoto para opcoes sob demanda.',
+        description: 'Remote select for on-demand options.',
         tags: ['selection', 'remote', 'async'],
         valueShape: 'string | number | object',
-        recommendedWhen: ['lookup remoto', 'lista paginada', 'catalogo grande'],
-        avoidWhen: ['opcoes locais pequenas'],
+        recommendedWhen: ['remote lookup', 'paginated list', 'large catalog'],
+        avoidWhen: ['small local options'],
         dataSourceKind: 'remote',
+        interactionPattern: 'lookup',
         status: 'partial-docs',
         apiPath: jsonApiPath('material-async-select/pdx-material-async-select.json-api.md'),
         metadata: { resourcePath: 'cities', optionLabelKey: 'name', optionValueKey: 'id' },
@@ -48814,13 +49373,25 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'selection',
         friendlyName: 'Autocomplete',
-        description: 'Busca incremental com sugestoes.',
+        description: 'Incremental search with suggestions.',
         tags: ['selection', 'autocomplete', 'search'],
         valueShape: 'string | number | object',
-        recommendedWhen: ['sugestoes incrementais', 'descoberta textual'],
-        avoidWhen: ['lista pequena e fechada'],
+        recommendedWhen: ['incremental suggestions', 'textual discovery'],
+        avoidWhen: ['small closed list'],
         dataSourceKind: 'mixed',
+        interactionPattern: 'lookup',
         apiPath: jsonApiPath('material-autocomplete/pdx-material-autocomplete.json-api.md'),
+        metadata: {
+            options: [
+                { label: 'Analyst', value: 'ANALYST' },
+                { label: 'Architect', value: 'ARCHITECT' },
+                { label: 'Manager', value: 'MANAGER' },
+            ],
+            placeholder: 'Start typing a role',
+        },
+        stateRecipes: [
+            createDefaultSeedRecipe('ARCHITECT', 'Seeded default preview to show suggestion-driven discovery instead of an empty shell.'),
+        ],
     }),
     createEntry({
         id: 'multi-select',
@@ -48828,11 +49399,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'selection',
         friendlyName: 'Multi select',
-        description: 'Selecao multipla de opcoes.',
+        description: 'Multi-select options.',
         tags: ['selection', 'multiple', 'options'],
         valueShape: 'unknown[]',
-        recommendedWhen: ['multiplas escolhas discretas'],
-        avoidWhen: ['escolha unica'],
+        recommendedWhen: ['multiple discrete choices'],
+        avoidWhen: ['single selection'],
         dataSourceKind: 'mixed',
         status: 'partial-docs',
         apiPath: jsonApiPath('material-multi-select/pdx-material-multi-select.json-api.md'),
@@ -48843,12 +49414,14 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'trees-lists',
         friendlyName: 'Multi select tree',
-        description: 'Arvore hierarquica com selecao multipla.',
+        description: 'Hierarchical tree with multi-selection.',
         tags: ['tree', 'selection', 'hierarchy'],
         valueShape: 'unknown[]',
-        recommendedWhen: ['taxonomia hierarquica com multiplas escolhas'],
-        avoidWhen: ['lista plana pequena'],
+        recommendedWhen: ['hierarchical taxonomy with multiple selections'],
+        avoidWhen: ['small flat list'],
         dataSourceKind: 'mixed',
+        icon: { key: 'tree-list', tone: 'slate' },
+        interactionPattern: 'multi-choice',
         status: 'partial-docs',
         apiPath: jsonApiPath('material-multi-select-tree/pdx-material-multi-select-tree.json-api.md'),
     }),
@@ -48858,12 +49431,14 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'trees-lists',
         friendlyName: 'Tree select',
-        description: 'Arvore hierarquica com selecao simples.',
+        description: 'Hierarchical tree with single selection.',
         tags: ['tree', 'selection', 'hierarchy'],
         valueShape: 'string | number | object',
-        recommendedWhen: ['estrutura hierarquica com escolha unica'],
-        avoidWhen: ['multiplas escolhas'],
+        recommendedWhen: ['hierarchical structure with a single selection'],
+        avoidWhen: ['multiple selections'],
         dataSourceKind: 'mixed',
+        icon: { key: 'tree-list', tone: 'slate' },
+        interactionPattern: 'single-choice',
         status: 'partial-docs',
         apiPath: jsonApiPath('material-tree-select/pdx-material-tree-select.json-api.md'),
     }),
@@ -48873,11 +49448,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'trees-lists',
         friendlyName: 'Selection list',
-        description: 'Lista explicita de opcoes selecionaveis.',
+        description: 'Explicit list of selectable options.',
         tags: ['list', 'selection', 'explicit'],
         valueShape: 'unknown[]',
-        recommendedWhen: ['lista visivel de opcoes', 'affordance forte de lista'],
-        avoidWhen: ['dropdown compacto resolve melhor'],
+        recommendedWhen: ['visible list of options', 'strong list affordance'],
+        avoidWhen: ['a compact dropdown is a better fit'],
         dataSourceKind: 'mixed',
         status: 'partial-docs',
         apiPath: jsonApiPath('material-selection-list/pdx-material-selection-list.json-api.md'),
@@ -48888,12 +49463,14 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'trees-lists',
         friendlyName: 'Transfer list',
-        description: 'Move itens entre listas disponivel e selecionado.',
+        description: 'Moves items between available and selected lists.',
         tags: ['list', 'transfer', 'selection'],
         valueShape: 'unknown[]',
-        recommendedWhen: ['alocacao entre disponiveis e selecionados'],
-        avoidWhen: ['selecao simples ou pequena'],
+        recommendedWhen: ['allocation between available and selected items'],
+        avoidWhen: ['simple or small selection'],
         dataSourceKind: 'mixed',
+        icon: { key: 'tree-list', tone: 'slate' },
+        interactionPattern: 'multi-choice',
         status: 'partial-docs',
         apiPath: jsonApiPath('material-transfer-list/pdx-material-transfer-list.json-api.md'),
     }),
@@ -48903,11 +49480,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'trees-lists',
         friendlyName: 'Chip input',
-        description: 'Entrada de itens textuais em formato de chips.',
+        description: 'Text item input in chip format.',
         tags: ['chips', 'list', 'text'],
         valueShape: 'string[]',
-        recommendedWhen: ['emails', 'labels editaveis', 'lista textual'],
-        avoidWhen: ['valor unico'],
+        recommendedWhen: ['email addresses', 'editable labels', 'text list'],
+        avoidWhen: ['single value'],
         dataSourceKind: 'local',
         status: 'partial-docs',
         apiPath: jsonApiPath('material-chips/pdx-material-chips.json-api.md'),
@@ -48918,11 +49495,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'trees-lists',
         friendlyName: 'Chip list',
-        description: 'Lista textual em chips.',
+        description: 'Text list in chips.',
         tags: ['chips', 'list', 'display'],
         valueShape: 'string[]',
-        recommendedWhen: ['lista curta em chips', 'edicao leve'],
-        avoidWhen: ['valor unico'],
+        recommendedWhen: ['short list in chips', 'light editing'],
+        avoidWhen: ['single value'],
         dataSourceKind: 'local',
         status: 'partial-docs',
         apiPath: jsonApiPath('material-chips/pdx-material-chips.json-api.md'),
@@ -48933,13 +49510,23 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'toggle-choice',
         friendlyName: 'Checkbox group',
-        description: 'Escolhas discretas booleanas ou multiplas.',
+        description: 'Discrete boolean or multiple choices.',
         tags: ['choice', 'checkbox', 'boolean'],
         valueShape: 'boolean | unknown[]',
-        recommendedWhen: ['multiplas escolhas discretas', 'booleano com selectionMode apropriado'],
-        avoidWhen: ['escolha unica'],
+        recommendedWhen: ['multiple discrete choices', 'boolean with the appropriate selectionMode'],
+        avoidWhen: ['single selection'],
         dataSourceKind: 'mixed',
         apiPath: jsonApiPath('material-checkbox-group/pdx-material-checkbox-group.json-api.md'),
+        metadata: {
+            selectionMode: 'boolean',
+            description: 'Enable publishing notifications for this record.',
+            links: [{ label: 'Privacy terms', href: '/privacy' }],
+        },
+        snippet: `{ "name": "privacyConsent", "controlType": "checkbox", "selectionMode": "boolean", "description": "Enable publishing notifications for this record." }`,
+        snippetNote: 'Checkbox is only didactic when selectionMode is explicit. Use `boolean` for a single consent/flag or `multiple` for option groups.',
+        stateRecipes: [
+            createDefaultSeedRecipe(true, 'Seeded default preview to make the boolean contract visible immediately.'),
+        ],
     }),
     createEntry({
         id: 'radio-group',
@@ -48947,13 +49534,25 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'toggle-choice',
         friendlyName: 'Radio group',
-        description: 'Escolha unica explicita.',
+        description: 'Explicit single choice.',
         tags: ['choice', 'radio', 'single'],
         valueShape: 'string | number | boolean',
-        recommendedWhen: ['escolha unica com poucas opcoes e alta legibilidade'],
-        avoidWhen: ['muitas opcoes'],
+        recommendedWhen: ['single choice with few options and high readability'],
+        avoidWhen: ['many options'],
         dataSourceKind: 'mixed',
         apiPath: jsonApiPath('material-radio-group/pdx-material-radio-group.json-api.md'),
+        metadata: {
+            selectionMode: 'single',
+            options: [
+                { label: 'Low', value: 'LOW' },
+                { label: 'Medium', value: 'MEDIUM' },
+                { label: 'High', value: 'HIGH' },
+            ],
+        },
+        snippet: `{ "name": "priority", "controlType": "radio", "selectionMode": "single", "options": [{ "label": "Low", "value": "LOW" }, { "label": "Medium", "value": "MEDIUM" }, { "label": "High", "value": "HIGH" }] }`,
+        stateRecipes: [
+            createDefaultSeedRecipe('MEDIUM', 'Seeded default preview to expose the explicit single-choice contract.'),
+        ],
     }),
     createEntry({
         id: 'toggle',
@@ -48961,11 +49560,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'toggle-choice',
         friendlyName: 'Toggle',
-        description: 'Booleano binario on/off.',
+        description: 'Binary on/off boolean.',
         tags: ['choice', 'toggle', 'boolean'],
         valueShape: 'boolean',
-        recommendedWhen: ['booleano simples'],
-        avoidWhen: ['mais de dois estados'],
+        recommendedWhen: ['simple boolean'],
+        avoidWhen: ['more than two states'],
         dataSourceKind: 'local',
         apiPath: jsonApiPath('material-slide-toggle/pdx-material-slide-toggle.json-api.md'),
         stateRecipes: [
@@ -48978,11 +49577,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'toggle-choice',
         friendlyName: 'Button toggle',
-        description: 'Grupo segmentado para poucas opcoes.',
+        description: 'Segmented group for a small number of options.',
         tags: ['choice', 'toggle', 'segmented'],
         valueShape: 'string | number',
-        recommendedWhen: ['poucas opcoes curtas', 'segmentacao visivel'],
-        avoidWhen: ['lista longa'],
+        recommendedWhen: ['few short options', 'visible segmentation'],
+        avoidWhen: ['long list'],
         dataSourceKind: 'local',
         status: 'partial-docs',
         apiPath: jsonApiPath('material-button-toggle/pdx-material-button-toggle.json-api.md'),
@@ -48993,13 +49592,21 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'upload-color-visual',
         friendlyName: 'File upload',
-        description: 'Campo para anexos e documentos.',
+        description: 'Field for attachments and documents.',
         tags: ['upload', 'files', 'attachments'],
         valueShape: 'File | File[] | metadata',
-        recommendedWhen: ['documentos', 'anexos', 'comprovantes'],
-        avoidWhen: ['fluxo sem arquivos'],
+        recommendedWhen: ['documents', 'attachments', 'supporting documents'],
+        avoidWhen: ['flow without files'],
         dataSourceKind: 'specialized',
+        icon: { key: 'visual', tone: 'teal' },
+        interactionPattern: 'trigger',
         apiPath: jsonApiPath('material-file-upload/pdx-material-file-upload.json-api.md'),
+        metadata: {
+            accept: '.pdf,.png,.jpg',
+            hint: 'Current runtime is a lightweight placeholder based on native file input.',
+        },
+        snippet: `{ "name": "attachment", "controlType": "upload", "accept": ".pdf,.png,.jpg", "hint": "Current runtime is a lightweight placeholder based on native file input." }`,
+        snippetNote: 'This preview intentionally demonstrates the current placeholder runtime, not a full asset-management experience.',
     }),
     createEntry({
         id: 'color-input',
@@ -49007,11 +49614,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'upload-color-visual',
         friendlyName: 'Color input',
-        description: 'Entrada simples de cor.',
+        description: 'Simple color input.',
         tags: ['color', 'input', 'visual'],
         valueShape: 'string',
-        recommendedWhen: ['cor por valor simples'],
-        avoidWhen: ['paleta rica ou presets'],
+        recommendedWhen: ['color by simple value'],
+        avoidWhen: ['rich palette or presets'],
         dataSourceKind: 'local',
         apiPath: jsonApiPath('color-input/pdx-color-input.json-api.md'),
     }),
@@ -49021,11 +49628,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'upload-color-visual',
         friendlyName: 'Color picker',
-        description: 'Picker avancado de cor com paleta.',
+        description: 'Advanced color picker with palette.',
         tags: ['color', 'picker', 'visual'],
         valueShape: 'string',
-        recommendedWhen: ['paleta rica', 'preset visual', 'tema'],
-        avoidWhen: ['valor simples textual basta'],
+        recommendedWhen: ['rich palette', 'visual preset', 'theme'],
+        avoidWhen: ['a simple textual value is enough'],
         dataSourceKind: 'local',
         apiPath: jsonApiPath('color-picker/pdx-color-picker.json-api.md'),
     }),
@@ -49035,13 +49642,26 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'upload-color-visual',
         friendlyName: 'Avatar',
-        description: 'Representacao visual de entidade/usuario.',
+        description: 'Visual representation of an entity or user.',
         tags: ['visual', 'avatar', 'display'],
         valueShape: 'string | object',
-        recommendedWhen: ['representacao visual de usuario ou entidade'],
-        avoidWhen: ['captura de dado textual'],
+        recommendedWhen: ['visual representation of a user or entity'],
+        avoidWhen: ['text data capture'],
         dataSourceKind: 'specialized',
+        icon: { key: 'visual', tone: 'teal' },
+        interactionPattern: 'visual',
         apiPath: jsonApiPath('material-avatar/pdx-material-avatar.json-api.md'),
+        metadata: {
+            imageSrc: 'https://cdn.corp.example/avatar/u123.png',
+            extra: {
+                initials: 'AS',
+                name: 'Ana Souza',
+                ariaLabel: 'Avatar do responsavel',
+            },
+        },
+        stateRecipes: [
+            createDefaultSeedRecipe({ imageSrc: 'https://cdn.corp.example/avatar/u123.png', name: 'Ana Souza', initials: 'AS' }, 'Seeded default preview to show the visual contract instead of an empty shell.'),
+        ],
     }),
     createEntry({
         id: 'button',
@@ -49049,14 +49669,23 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'upload-color-visual',
         friendlyName: 'Button',
-        description: 'Acao auxiliar embutida no layout do formulario.',
+        description: 'Auxiliary action embedded in the form layout.',
         tags: ['action', 'button', 'visual'],
         valueShape: 'n/a',
-        recommendedWhen: ['acao auxiliar no layout'],
-        avoidWhen: ['submit/cancel padrao do form'],
+        recommendedWhen: ['auxiliary action in the layout'],
+        avoidWhen: ['default form submit or cancel action'],
         dataSourceKind: 'specialized',
+        icon: { key: 'action', tone: 'amber' },
+        interactionPattern: 'trigger',
         apiPath: jsonApiPath('material-button/pdx-material-button.json-api.md'),
         states: ['default', 'disabled', 'readonly'],
+        metadata: {
+            label: 'Validate data',
+            action: 'validateForm',
+            variant: 'stroked',
+        },
+        snippet: `{ "name": "validateBtn", "controlType": "button", "label": "Validate data", "action": "validateForm", "variant": "stroked" }`,
+        snippetNote: 'Button previews are only meaningful when the action contract is explicit. Treat this as an embedded auxiliary action, not the form submit surface.',
     }),
     createEntry({
         id: 'cron-builder',
@@ -49064,13 +49693,22 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'primary-form',
         family: 'upload-color-visual',
         friendlyName: 'Cron builder',
-        description: 'Controle especializado para expressoes CRON.',
+        description: 'Specialized control for CRON expressions.',
         tags: ['cron', 'schedule', 'specialized'],
         valueShape: 'string',
-        recommendedWhen: ['agenda cron', 'frequencia recorrente'],
-        avoidWhen: ['datas ou ranges simples'],
+        recommendedWhen: ['cron schedule', 'recurring frequency'],
+        avoidWhen: ['dates or simple ranges'],
         dataSourceKind: 'specialized',
+        icon: { key: 'automation', tone: 'violet' },
+        interactionPattern: 'trigger',
         status: 'partial-docs',
+        metadata: {
+            placeholder: '0 9 * * 1-5',
+            hint: 'Use when the business contract is truly cron-based, not just date or time range based.',
+        },
+        stateRecipes: [
+            createDefaultSeedRecipe('0 9 * * 1-5', 'Seeded default preview to expose the recurring-expression contract immediately.'),
+        ],
         snippetNote: 'A documentacao detalhada continua vivendo na lib especializada @praxisui/cron-builder.',
     }),
     createEntry({
@@ -49079,11 +49717,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'inline-filter',
         family: 'text',
         friendlyName: 'Inline input',
-        description: 'Filtro textual compacto para toolbar.',
+        description: 'Compact text filter for the toolbar.',
         tags: ['inline', 'filter', 'text'],
         valueShape: 'string',
-        recommendedWhen: ['busca curta em toolbar', 'identificador', 'nome'],
-        avoidWhen: ['texto longo', 'validacao complexa'],
+        recommendedWhen: ['short search in the toolbar', 'identifier', 'name'],
+        avoidWhen: ['long text', 'complex validation'],
         dataSourceKind: 'local',
         apiPath: jsonApiPath('inline-input/pdx-inline-input.json-api.md'),
         stateRecipes: [
@@ -49096,11 +49734,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'inline-filter',
         family: 'selection',
         friendlyName: 'Inline select',
-        description: 'Selecao compacta em pill para filtros.',
+        description: 'Compact pill selection for filters.',
         tags: ['inline', 'filter', 'selection'],
         valueShape: 'simple value',
-        recommendedWhen: ['lista pequena ou media em toolbar'],
-        avoidWhen: ['lookup remoto grande'],
+        recommendedWhen: ['small or medium list in the toolbar'],
+        avoidWhen: ['large remote lookup'],
         dataSourceKind: 'mixed',
         apiPath: jsonApiPath('inline-select/pdx-inline-select.json-api.md'),
         stateRecipes: [
@@ -49113,11 +49751,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'inline-filter',
         family: 'selection',
         friendlyName: 'Inline searchable select',
-        description: 'Selecao compacta com busca.',
+        description: 'Compact selection with search.',
         tags: ['inline', 'filter', 'selection', 'search'],
         valueShape: 'simple value | option object',
-        recommendedWhen: ['lista media/grande com busca em toolbar'],
-        avoidWhen: ['select simples ja resolve'],
+        recommendedWhen: ['medium or large list with search in the toolbar'],
+        avoidWhen: ['a simple select is enough'],
         dataSourceKind: 'mixed',
         apiPath: jsonApiPath('inline-searchable-select/pdx-inline-searchable-select.json-api.md'),
     }),
@@ -49127,11 +49765,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'inline-filter',
         family: 'selection',
         friendlyName: 'Inline async select',
-        description: 'Selecao remota compacta para toolbar.',
+        description: 'Compact remote selection for the toolbar.',
         tags: ['inline', 'filter', 'selection', 'remote'],
         valueShape: 'simple value | option object',
-        recommendedWhen: ['lookup remoto em toolbar', 'lista sob demanda'],
-        avoidWhen: ['lista local pequena'],
+        recommendedWhen: ['remote lookup in the toolbar', 'on-demand list'],
+        avoidWhen: ['small local list'],
         dataSourceKind: 'remote',
         apiPath: jsonApiPath('inline-async-select/pdx-inline-async-select.json-api.md'),
     }),
@@ -49141,11 +49779,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'inline-filter',
         family: 'selection',
         friendlyName: 'Inline entity lookup',
-        description: 'Lookup compacto de entidade com semantica corporativa.',
+        description: 'Compact entity lookup with enterprise semantics.',
         tags: ['inline', 'filter', 'lookup', 'remote'],
         valueShape: 'object | id',
-        recommendedWhen: ['id + descricao', 'identidade de entidade'],
-        avoidWhen: ['select local simples'],
+        recommendedWhen: ['id and description', 'entity identity'],
+        avoidWhen: ['simple local select'],
         dataSourceKind: 'remote',
         apiPath: jsonApiPath('inline-entity-lookup/pdx-inline-entity-lookup.json-api.md'),
     }),
@@ -49155,11 +49793,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'inline-filter',
         family: 'selection',
         friendlyName: 'Inline autocomplete',
-        description: 'Autocomplete compacto para filtros.',
+        description: 'Compact autocomplete for filters.',
         tags: ['inline', 'filter', 'autocomplete'],
         valueShape: 'simple value | option object',
-        recommendedWhen: ['sugestao incremental em toolbar'],
-        avoidWhen: ['select simples basta'],
+        recommendedWhen: ['incremental suggestion in the toolbar'],
+        avoidWhen: ['a simple select is enough'],
         dataSourceKind: 'mixed',
         apiPath: jsonApiPath('inline-autocomplete/pdx-inline-autocomplete.json-api.md'),
     }),
@@ -49169,11 +49807,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'inline-filter',
         family: 'selection',
         friendlyName: 'Inline multi select',
-        description: 'Selecao multipla compacta com resumo em pill.',
+        description: 'Compact multi-selection with pill summary.',
         tags: ['inline', 'filter', 'multiple'],
         valueShape: 'unknown[]',
-        recommendedWhen: ['poucas selecoes simultaneas com resumo curto'],
-        avoidWhen: ['necessidade de leitura integral de todos os itens'],
+        recommendedWhen: ['few simultaneous selections with a short summary'],
+        avoidWhen: ['need to read every selected item in full'],
         dataSourceKind: 'mixed',
         apiPath: jsonApiPath('inline-multi-select/pdx-inline-multi-select.json-api.md'),
     }),
@@ -49183,10 +49821,10 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'inline-filter',
         family: 'numbers-range',
         friendlyName: 'Inline number',
-        description: 'Filtro numerico compacto.',
+        description: 'Compact numeric filter.',
         tags: ['inline', 'filter', 'number'],
         valueShape: 'number',
-        recommendedWhen: ['valor numerico pontual em toolbar'],
+        recommendedWhen: ['single numeric value in the toolbar'],
         avoidWhen: ['range'],
         dataSourceKind: 'local',
         apiPath: jsonApiPath('inline-number/pdx-inline-number.json-api.md'),
@@ -49197,11 +49835,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'inline-filter',
         family: 'numbers-range',
         friendlyName: 'Inline currency',
-        description: 'Filtro monetario compacto.',
+        description: 'Compact currency filter.',
         tags: ['inline', 'filter', 'currency'],
         valueShape: 'number',
-        recommendedWhen: ['valor monetario unico em toolbar'],
-        avoidWhen: ['faixa monetaria'],
+        recommendedWhen: ['single monetary value in the toolbar'],
+        avoidWhen: ['currency range'],
         dataSourceKind: 'local',
         apiPath: jsonApiPath('inline-currency/pdx-inline-currency.json-api.md'),
     }),
@@ -49211,11 +49849,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'inline-filter',
         family: 'numbers-range',
         friendlyName: 'Inline currency range',
-        description: 'Faixa monetaria compacta para toolbar.',
+        description: 'Compact currency range for the toolbar.',
         tags: ['inline', 'filter', 'currency', 'range'],
         valueShape: '{ minPrice?, maxPrice?, currency? }',
-        recommendedWhen: ['faixa monetaria em toolbar'],
-        avoidWhen: ['valor unico'],
+        recommendedWhen: ['currency range in the toolbar'],
+        avoidWhen: ['single value'],
         dataSourceKind: 'specialized',
         apiPath: jsonApiPath('inline-currency-range/pdx-inline-currency-range.json-api.md'),
     }),
@@ -49225,11 +49863,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'inline-filter',
         family: 'numbers-range',
         friendlyName: 'Inline range',
-        description: 'Range numerico compacto para toolbar.',
+        description: 'Compact numeric range for the toolbar.',
         tags: ['inline', 'filter', 'range', 'slider'],
         valueShape: 'number | { start?, end? }',
-        recommendedWhen: ['faixa numerica compacta'],
-        avoidWhen: ['datas ou horarios'],
+        recommendedWhen: ['compact numeric range'],
+        avoidWhen: ['dates or times'],
         dataSourceKind: 'specialized',
         apiPath: jsonApiPath('inline-currency-range/pdx-inline-currency-range.json-api.md'),
         detailFragment: 'inline-range',
@@ -49240,11 +49878,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'inline-filter',
         family: 'numbers-range',
         friendlyName: 'Inline rating',
-        description: 'Filtro visual de rating para toolbar.',
+        description: 'Visual rating filter for the toolbar.',
         tags: ['inline', 'filter', 'rating'],
         valueShape: 'number | { start?, end? }',
-        recommendedWhen: ['score visual', 'avaliacao em estrelas'],
-        avoidWhen: ['quando numero bruto ja basta'],
+        recommendedWhen: ['visual score', 'star rating'],
+        avoidWhen: ['when a raw number is enough'],
         dataSourceKind: 'specialized',
         apiPath: jsonApiPath('inline-rating/pdx-inline-rating.json-api.md'),
     }),
@@ -49254,12 +49892,13 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'inline-filter',
         family: 'numbers-range',
         friendlyName: 'Inline distance radius',
-        description: 'Filtro semantico de distancia e raio.',
+        description: 'Semantic distance and radius filter.',
         tags: ['inline', 'filter', 'distance', 'radius'],
         valueShape: 'number | { start?, end? }',
-        recommendedWhen: ['raio de busca', 'proximidade'],
-        avoidWhen: ['range numerico generico'],
+        recommendedWhen: ['search radius', 'proximity'],
+        avoidWhen: ['generic numeric range'],
         dataSourceKind: 'specialized',
+        interactionPattern: 'range',
         apiPath: jsonApiPath('inline-distance-radius/pdx-inline-distance-radius.json-api.md'),
     }),
     createEntry({
@@ -49268,12 +49907,14 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'inline-filter',
         family: 'numbers-range',
         friendlyName: 'Inline score priority',
-        description: 'Filtro semantico de score/prioridade.',
+        description: 'Semantic score or priority filter.',
         tags: ['inline', 'filter', 'score', 'priority'],
         valueShape: 'number | { start?, end? }',
-        recommendedWhen: ['prioridade', 'criticidade', 'banda de score'],
-        avoidWhen: ['numero simples sem ganho semantico'],
+        recommendedWhen: ['priority', 'criticality', 'score band'],
+        avoidWhen: ['simple number with no semantic gain'],
         dataSourceKind: 'specialized',
+        icon: { key: 'visual', tone: 'amber' },
+        interactionPattern: 'visual',
         apiPath: jsonApiPath('inline-score-priority/pdx-inline-score-priority.json-api.md'),
     }),
     createEntry({
@@ -49282,11 +49923,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'inline-filter',
         family: 'date-time',
         friendlyName: 'Inline date',
-        description: 'Filtro de data compacta.',
+        description: 'Compact date filter.',
         tags: ['inline', 'filter', 'date'],
         valueShape: 'Date',
-        recommendedWhen: ['data unica em toolbar'],
-        avoidWhen: ['periodo completo'],
+        recommendedWhen: ['single date in the toolbar'],
+        avoidWhen: ['full period'],
         dataSourceKind: 'specialized',
         apiPath: jsonApiPath('inline-date/pdx-inline-date.json-api.md'),
     }),
@@ -49296,11 +49937,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'inline-filter',
         family: 'date-time',
         friendlyName: 'Inline date range',
-        description: 'Range de data compacta com semantica de toolbar.',
+        description: 'Compact date range with toolbar semantics.',
         tags: ['inline', 'filter', 'date', 'range'],
         valueShape: '{ startDate?, endDate? }',
-        recommendedWhen: ['janela temporal em toolbar'],
-        avoidWhen: ['toolbar saturada ou data unica'],
+        recommendedWhen: ['time window in the toolbar'],
+        avoidWhen: ['dense toolbar or a single date'],
         dataSourceKind: 'specialized',
         apiPath: jsonApiPath('inline-date-range/pdx-inline-date-range.json-api.md'),
         stateRecipes: [
@@ -49313,11 +49954,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'inline-filter',
         family: 'date-time',
         friendlyName: 'Inline time',
-        description: 'Filtro compacto de horario.',
+        description: 'Compact time filter.',
         tags: ['inline', 'filter', 'time'],
         valueShape: 'string HH:mm',
-        recommendedWhen: ['horario unico em toolbar'],
-        avoidWhen: ['periodo relativo ou range'],
+        recommendedWhen: ['single time in the toolbar'],
+        avoidWhen: ['relative period or range'],
         dataSourceKind: 'specialized',
         apiPath: jsonApiPath('inline-time/pdx-inline-time.json-api.md'),
     }),
@@ -49327,11 +49968,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'inline-filter',
         family: 'date-time',
         friendlyName: 'Inline time range',
-        description: 'Faixa horaria compacta para toolbar.',
+        description: 'Compact time range for the toolbar.',
         tags: ['inline', 'filter', 'time', 'range'],
         valueShape: '{ start?, end? }',
-        recommendedWhen: ['turno', 'janela operacional'],
-        avoidWhen: ['horario unico'],
+        recommendedWhen: ['shift', 'operational window'],
+        avoidWhen: ['single time'],
         dataSourceKind: 'specialized',
         apiPath: jsonApiPath('inline-time-range/pdx-inline-time-range.json-api.md'),
     }),
@@ -49341,11 +49982,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'inline-filter',
         family: 'trees-lists',
         friendlyName: 'Inline tree select',
-        description: 'Arvore compacta para filtro em toolbar.',
+        description: 'Compact tree filter for the toolbar.',
         tags: ['inline', 'filter', 'tree', 'hierarchy'],
         valueShape: 'simple node value',
-        recommendedWhen: ['taxonomia ou unidade organizacional em toolbar'],
-        avoidWhen: ['arvore profunda demais'],
+        recommendedWhen: ['taxonomy or organizational unit in the toolbar'],
+        avoidWhen: ['tree that is too deep'],
         dataSourceKind: 'mixed',
         apiPath: jsonApiPath('inline-tree-select/pdx-inline-tree-select.json-api.md'),
     }),
@@ -49355,12 +49996,14 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'inline-filter',
         family: 'selection',
         friendlyName: 'Inline pipeline status',
-        description: 'Filtro semantico de status de pipeline.',
+        description: 'Semantic pipeline status filter.',
         tags: ['inline', 'filter', 'pipeline', 'status'],
         valueShape: 'simple value | unknown[]',
-        recommendedWhen: ['esteira operacional', 'pipeline comercial'],
-        avoidWhen: ['status simples sem ganho visual'],
+        recommendedWhen: ['operational pipeline', 'sales pipeline'],
+        avoidWhen: ['simple status with no visual gain'],
         dataSourceKind: 'specialized',
+        icon: { key: 'visual', tone: 'violet' },
+        interactionPattern: 'visual',
         apiPath: jsonApiPath('inline-pipeline-status/pdx-inline-pipeline-status.json-api.md'),
     }),
     createEntry({
@@ -49369,11 +50012,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'inline-filter',
         family: 'date-time',
         friendlyName: 'Inline relative period',
-        description: 'Preset semantico de periodo relativo.',
+        description: 'Semantic relative period preset.',
         tags: ['inline', 'filter', 'date', 'relative'],
         valueShape: 'string',
-        recommendedWhen: ['hoje', 'ontem', 'ultimos 7 dias', 'este mes'],
-        avoidWhen: ['API fora da trilha canonica que nao normaliza presets'],
+        recommendedWhen: ['today', 'yesterday', 'last 7 days', 'this month'],
+        avoidWhen: ['API outside the canonical track that does not normalize presets'],
         dataSourceKind: 'specialized',
         apiPath: jsonApiPath('inline-relative-period/pdx-inline-relative-period.json-api.md'),
     }),
@@ -49383,12 +50026,14 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'inline-filter',
         family: 'selection',
         friendlyName: 'Inline sentiment',
-        description: 'Filtro semantico de sentimento/polaridade.',
+        description: 'Semantic sentiment or polarity filter.',
         tags: ['inline', 'filter', 'sentiment'],
         valueShape: 'string',
-        recommendedWhen: ['sentimento', 'polaridade', 'humor'],
-        avoidWhen: ['enum simples sem ganho visual'],
+        recommendedWhen: ['sentiment', 'polarity', 'mood'],
+        avoidWhen: ['simple enum with no visual gain'],
         dataSourceKind: 'specialized',
+        icon: { key: 'visual', tone: 'rose' },
+        interactionPattern: 'visual',
         apiPath: jsonApiPath('inline-sentiment/pdx-inline-sentiment.json-api.md'),
     }),
     createEntry({
@@ -49397,12 +50042,14 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'inline-filter',
         family: 'selection',
         friendlyName: 'Inline color label',
-        description: 'Filtro de labels coloridas semanticas.',
+        description: 'Semantic colored-label filter.',
         tags: ['inline', 'filter', 'color', 'labels'],
         valueShape: 'simple value | unknown[]',
-        recommendedWhen: ['tags coloridas', 'categorias visuais'],
-        avoidWhen: ['quando cor e o unico canal de significado'],
+        recommendedWhen: ['colored tags', 'visual categories'],
+        avoidWhen: ['when color is the only channel of meaning'],
         dataSourceKind: 'specialized',
+        icon: { key: 'visual', tone: 'teal' },
+        interactionPattern: 'visual',
         apiPath: jsonApiPath('inline-color-label/pdx-inline-color-label.json-api.md'),
         a11yNotes: [
             'Nunca dependa apenas de cor para comunicar estado ou significado.',
@@ -49415,11 +50062,11 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         track: 'inline-filter',
         family: 'toggle-choice',
         friendlyName: 'Inline toggle',
-        description: 'Booleano compacto com estado neutro para toolbar.',
+        description: 'Compact boolean with neutral state for the toolbar.',
         tags: ['inline', 'filter', 'toggle', 'boolean'],
         valueShape: 'boolean | null',
-        recommendedWhen: ['booleano simples em toolbar'],
-        avoidWhen: ['false e null nao estao bem documentados no fluxo'],
+        recommendedWhen: ['simple boolean in the toolbar'],
+        avoidWhen: ['false and null are not well documented in the flow'],
         dataSourceKind: 'local',
         apiPath: jsonApiPath('inline-toggle/pdx-inline-toggle.json-api.md'),
         stateRecipes: [
@@ -50826,6 +51473,24 @@ function getControlTypeCatalog(controlType) {
  * Lida com campos que não possuem controlType definido,
  * inferindo tipos apropriados baseado no schema JSON.
  */
+const VALUE_PRESENTATION_TYPES = new Set([
+    'string',
+    'number',
+    'currency',
+    'percentage',
+    'date',
+    'datetime',
+    'time',
+    'boolean',
+]);
+const VALUE_PRESENTATION_STYLES = new Set([
+    'default',
+    'short',
+    'medium',
+    'long',
+    'full',
+    'compact',
+]);
 /**
  * Mapeia um JSON Schema completo para array de FieldMetadata
  *
@@ -50925,6 +51590,10 @@ function mapPropertyToFieldMetadata(fieldName, property, requiredFields = []) {
         // Propriedades específicas baseadas no tipo
         ...extractTypeSpecificProperties(property, uiConfig),
     };
+    const valuePresentation = mapValuePresentation(uiConfig.valuePresentation);
+    if (valuePresentation) {
+        fieldMetadata.valuePresentation = valuePresentation;
+    }
     // Keep a lightweight trace for downstream editors/runtimes to distinguish
     // explicit schema text from convenience-generated labels.
     if (!uiConfig.label && !property.title) {
@@ -50942,6 +51611,41 @@ function mapPropertyToFieldMetadata(fieldName, property, requiredFields = []) {
     }
     return fieldMetadata;
 }
+function mapValuePresentation(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return undefined;
+    }
+    const typeToken = String(value.type ?? '').trim();
+    if (!typeToken || !VALUE_PRESENTATION_TYPES.has(typeToken)) {
+        if (typeToken) {
+            logger.warn(`[JsonSchemaMapper] Ignorando x-ui.valuePresentation.type invalido: ${typeToken}`);
+        }
+        return undefined;
+    }
+    const presentation = {
+        type: typeToken,
+    };
+    const styleToken = String(value.style ?? '').trim();
+    if (styleToken) {
+        if (VALUE_PRESENTATION_STYLES.has(styleToken)) {
+            presentation.style = styleToken;
+        }
+        else {
+            logger.warn(`[JsonSchemaMapper] Ignorando x-ui.valuePresentation.style invalido: ${styleToken}`);
+        }
+    }
+    const formatToken = String(value.format ?? '').trim();
+    if (formatToken) {
+        presentation.format = formatToken;
+    }
+    if (value.currency && typeof value.currency === 'object') {
+        presentation.currency = { ...value.currency };
+    }
+    if (value.number && typeof value.number === 'object') {
+        presentation.number = { ...value.number };
+    }
+    return presentation;
+}
 /**
  * Infere controlType baseado no schema JSON quando x-ui não está disponível
  *