@praxisui/dynamic-fields 9.0.0-beta.16 → 9.0.0-beta.18

package/fesm2022/praxisui-dynamic-fields.mjs

@@ -130,6 +130,7 @@ const PRAXIS_DYNAMIC_FIELDS_EN_US = {
     'praxis.dynamicFields.validation.unique': 'Value is already in use',
     'praxis.dynamicFields.validation.fileType': 'File type is not allowed',
     'praxis.dynamicFields.validation.maxFileSize': 'File exceeds the maximum size',
+    'praxis.dynamicFields.validation.maxFiles': 'Select at most {{count}} file(s)',
     'praxis.dynamicFields.validation.minWords': 'Text has too few words',
     'praxis.dynamicFields.validation.conditional': 'Validation rule not satisfied',
     'praxis.dynamicFields.validation.invalidValue': 'Invalid value',
@@ -142,6 +143,16 @@ const PRAXIS_DYNAMIC_FIELDS_EN_US = {
     'praxis.dynamicFields.actions.clear.tooltip': 'Clear',
     'praxis.dynamicFields.actions.clear.ariaLabel': 'Clear field',
     'praxis.dynamicFields.actions.clear.ariaLabelWithLabel': 'Clear {{label}}',
+    'praxis.dynamicFields.fileUpload.emptySummary': 'No file selected',
+    'praxis.dynamicFields.fileUpload.multipleSummary': '{{count}} files selected',
+    'praxis.dynamicFields.fileUpload.clearSelection': 'Clear',
+    'praxis.dynamicFields.fileUpload.clearSelectionAriaLabel': 'Clear selected file',
+    'praxis.dynamicFields.fileUpload.selectedSummaryAriaLabel': 'Selected file',
+    'praxis.dynamicFields.fileUpload.previewAlt': 'Selected image preview',
+    'praxis.dynamicFields.fileUpload.sizeUnitBytes': 'B',
+    'praxis.dynamicFields.fileUpload.sizeUnitKb': 'KB',
+    'praxis.dynamicFields.fileUpload.sizeUnitMb': 'MB',
+    'praxis.dynamicFields.fileUpload.sizeUnitGb': 'GB',
     'praxis.dynamicFields.array.add': 'Add item',
     'praxis.dynamicFields.array.remove': 'Remove',
     'praxis.dynamicFields.array.empty': 'No items registered.',
@@ -509,6 +520,7 @@ const PRAXIS_DYNAMIC_FIELDS_PT_BR = {
     'praxis.dynamicFields.validation.unique': 'Valor já utilizado',
     'praxis.dynamicFields.validation.fileType': 'Tipo de arquivo não permitido',
     'praxis.dynamicFields.validation.maxFileSize': 'Arquivo excede o tamanho máximo',
+    'praxis.dynamicFields.validation.maxFiles': 'Selecione no máximo {{count}} arquivo(s)',
     'praxis.dynamicFields.validation.minWords': 'Texto com poucas palavras',
     'praxis.dynamicFields.validation.conditional': 'Regra de validação não atendida',
     'praxis.dynamicFields.validation.invalidValue': 'Valor inválido',
@@ -521,6 +533,16 @@ const PRAXIS_DYNAMIC_FIELDS_PT_BR = {
     'praxis.dynamicFields.actions.clear.tooltip': 'Limpar',
     'praxis.dynamicFields.actions.clear.ariaLabel': 'Limpar campo',
     'praxis.dynamicFields.actions.clear.ariaLabelWithLabel': 'Limpar {{label}}',
+    'praxis.dynamicFields.fileUpload.emptySummary': 'Nenhum arquivo selecionado',
+    'praxis.dynamicFields.fileUpload.multipleSummary': '{{count}} arquivos selecionados',
+    'praxis.dynamicFields.fileUpload.clearSelection': 'Limpar',
+    'praxis.dynamicFields.fileUpload.clearSelectionAriaLabel': 'Limpar arquivo selecionado',
+    'praxis.dynamicFields.fileUpload.selectedSummaryAriaLabel': 'Arquivo selecionado',
+    'praxis.dynamicFields.fileUpload.previewAlt': 'Pré-visualização da imagem selecionada',
+    'praxis.dynamicFields.fileUpload.sizeUnitBytes': 'B',
+    'praxis.dynamicFields.fileUpload.sizeUnitKb': 'KB',
+    'praxis.dynamicFields.fileUpload.sizeUnitMb': 'MB',
+    'praxis.dynamicFields.fileUpload.sizeUnitGb': 'GB',
     'praxis.dynamicFields.array.add': 'Adicionar item',
     'praxis.dynamicFields.array.remove': 'Remover',
     'praxis.dynamicFields.array.empty': 'Nenhum item cadastrado.',
@@ -775,7 +797,7 @@ const PRAXIS_DYNAMIC_FIELDS_PT_BR = {
     'praxis.dynamicFields.entityLookup.action.create': 'Novo',
     'praxis.dynamicFields.entityLookup.action.clear': 'Limpar',
     'praxis.dynamicFields.entityLookup.sort.label': 'Ordenar por',
-    'praxis.dynamicFields.entityLookup.sort.default': 'Padrao',
+    'praxis.dynamicFields.entityLookup.sort.default': 'Padrão',
     'praxis.dynamicFields.entityLookup.filter.clearAll': 'Limpar filtros',
     'praxis.dynamicFields.entityLookup.dialog.open': 'Busca avançada',
     'praxis.dynamicFields.entityLookup.dialog.openSupporting': 'Refine a busca com filtros, ordenacao e contexto.',
@@ -812,7 +834,7 @@ const PRAXIS_DYNAMIC_FIELDS_PT_BR = {
     'praxis.dynamicFields.entityLookup.dialog.preview.legacy': 'Valor legado',
     'praxis.dynamicFields.entityLookup.dialog.preview.blocked': 'Bloqueado',
     'praxis.dynamicFields.entityLookup.dialog.preview.selectable': 'Selecionavel',
-    'praxis.dynamicFields.entityLookup.selectionLimitReached': 'Limite de {max} selecoes atingido.',
+    'praxis.dynamicFields.entityLookup.selectionLimitReached': 'Limite de {max} seleções atingido.',
     'praxis.dynamicFields.entityLookup.action.removeSelection': 'Remover {label}',
     'praxis.dynamicFields.entityLookup.noResults': 'Nenhuma entidade encontrada para os filtros atuais.',
     'praxis.dynamicFields.entityLookup.unmetDependencies': 'Preencha os campos dependentes antes de buscar.',
@@ -864,7 +886,7 @@ const PRAXIS_DYNAMIC_FIELDS_PT_BR = {
     'praxis.dynamicFields.editorial.avatar.inputs.emphasis.description': 'Estado de destaque visual usado para avatares selecionados, principais ou de atenção sem alterar valores submetidos.',
     'praxis.dynamicFields.editorial.avatar.inputs.emphasisColor.description': 'Token de cor usado pelo anel ou halo de destaque.',
     'praxis.dynamicFields.editorial.avatar.inputs.emphasisLabel.description': 'Rotulo acessivel que descreve o significado do destaque visual.',
-    'praxis.dynamicFields.editorial.avatar.inputs.initialsMaxLength.description': 'Numero maximo de iniciais renderizadas',
+    'praxis.dynamicFields.editorial.avatar.inputs.initialsMaxLength.description': 'Número máximo de iniciais renderizadas',
     'praxis.dynamicFields.editorial.avatar.inputs.tooltip.description': 'Texto do tooltip',
     'praxis.dynamicFields.editorial.avatar.inputs.ariaLabel.description': 'Rótulo ARIA',
     'praxis.dynamicFields.editorial.avatar.inputs.class.description': 'Classes CSS adicionais no host',
@@ -2980,8 +3002,8 @@ class SimpleBaseButtonComponent {
         // Adicionar confirmação se configurada
         if (action && meta.confirmDialog) {
             action.confirmation = {
-                title: meta.confirmDialog.title || this.tDynamicFields('button.confirmTitle', 'Confirmar acao'),
-                message: meta.confirmDialog.message || this.tDynamicFields('button.confirmMessage', 'Deseja continuar com esta acao?'),
+                title: meta.confirmDialog.title || this.tDynamicFields('button.confirmTitle', 'Confirmar ação'),
+                message: meta.confirmDialog.message || this.tDynamicFields('button.confirmMessage', 'Deseja continuar com esta ação?'),
                 confirmLabel: meta.confirmDialog.confirmLabel || this.tDynamicFields('dialog.confirm', 'Confirmar'),
                 cancelLabel: meta.confirmDialog.cancelLabel || this.tDynamicFields('dialog.cancel', 'Cancelar'),
             };
@@ -8809,7 +8831,7 @@ const LoggerPresets = {
     }
 };
 
-const EMPTY_DISPLAY = '-- Nao informado';
+const EMPTY_DISPLAY = '-- Não informado';
 function isISODate(v) {
     return /^\d{4}-\d{2}-\d{2}$/.test(v);
 }
@@ -9064,7 +9086,7 @@ function resolveFieldPresentation(field, value, options) {
     const config = buildValuePresentationConfig(field, value);
     if (!config)
         return null;
-    const effectiveLocalization = mergeLocalization(options?.localization, buildLegacyFieldLocalization(field));
+    const effectiveLocalization = mergeLocalization(mergeLocalization(buildLegacyFieldLocalization(field), field?.localization), options?.localization);
     const fallbackCurrencyCode = config.type === 'currency' && !config.currency?.code
         ? inferCurrencyCodeFromLocale(effectiveLocalization?.locale ||
             options?.surfaceLocale ||
@@ -9072,7 +9094,7 @@ function resolveFieldPresentation(field, value, options) {
             undefined)
         : undefined;
     return resolveValuePresentation(config, {
-        valueLocale: resolveFieldLocale(field),
+        valueLocale: effectiveLocalization?.locale,
         localization: fallbackCurrencyCode
             ? mergeLocalization(effectiveLocalization, {
                 ...(effectiveLocalization?.locale ? { locale: effectiveLocalization.locale } : {}),
@@ -9356,7 +9378,7 @@ function formatBooleanPresentation(value, locale) {
 function resolveBooleanLabels(locale) {
     const normalized = String(locale || '').trim().toLowerCase();
     if (normalized.startsWith('pt')) {
-        return ['Sim', 'Nao'];
+        return ['Sim', 'Não'];
     }
     if (normalized.startsWith('es')) {
         return ['Si', 'No'];
@@ -9729,7 +9751,8 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImpo
  * project additional chrome around the field.
  */
 class FieldShellComponent {
-    hostLocale = inject(LOCALE_ID, { optional: true }) ?? 'en-US';
+    angularLocale = inject(LOCALE_ID, { optional: true }) ?? 'en-US';
+    i18n = inject(PraxisI18nService, { optional: true });
     cdr = inject(ChangeDetectorRef);
     optionDisplayResolver = inject(OptionDisplayResolverService);
     crudService = inject(GenericCrudService, {
@@ -9898,7 +9921,7 @@ class FieldShellComponent {
             const formatted = typeof fn === 'function'
                 ? fn(raw)
                 : formatDisplayValue(this.field, raw, {
-                    appLocale: this.hostLocale,
+                    appLocale: this.resolvePresentationAppLocale(),
                     surfaceLocale: this.field?.localization?.locale ?? this.field?.locale ?? undefined,
                     localization: this.field?.localization ?? undefined,
                 });
@@ -9906,7 +9929,7 @@ class FieldShellComponent {
         }
         catch {
             return formatDisplayValue(this.field, raw, {
-                appLocale: this.hostLocale,
+                appLocale: this.resolvePresentationAppLocale(),
                 surfaceLocale: this.field?.localization?.locale ?? this.field?.locale ?? undefined,
                 localization: this.field?.localization ?? undefined,
             });
@@ -9924,14 +9947,14 @@ class FieldShellComponent {
                     : null;
             const val = formatted == null ? raw : formatted;
             return formatDisplayHtml(this.field, val, {
-                appLocale: this.hostLocale,
+                appLocale: this.resolvePresentationAppLocale(),
                 surfaceLocale: this.field?.localization?.locale ?? this.field?.locale ?? undefined,
                 localization: this.field?.localization ?? undefined,
             });
         }
         catch {
             return formatDisplayHtml(this.field, raw, {
-                appLocale: this.hostLocale,
+                appLocale: this.resolvePresentationAppLocale(),
                 surfaceLocale: this.field?.localization?.locale ?? this.field?.locale ?? undefined,
                 localization: this.field?.localization ?? undefined,
             });
@@ -10029,6 +10052,14 @@ class FieldShellComponent {
         const value = String(position ?? '').trim().toLowerCase();
         return ['end', 'right', 'after', 'suffix', 'trailing'].includes(value);
     }
+    resolvePresentationAppLocale() {
+        const praxisLocale = this.i18n?.getLocale()?.trim();
+        if (praxisLocale) {
+            return praxisLocale;
+        }
+        const angularLocale = this.angularLocale?.trim();
+        return angularLocale || 'en-US';
+    }
     refreshPresentationDisplayValue() {
         this.resolveSub?.unsubscribe();
         this.resolveSub = undefined;
@@ -13108,7 +13139,7 @@ class InlineEntityLookupComponent extends MaterialAsyncSelectComponent {
     }
     selectionLimitReachedText(maxSelections) {
         const max = Number(maxSelections ?? 0);
-        const template = this.tDynamicFields('entityLookup.selectionLimitReached', 'Limite de {max} selecoes atingido.', { max: Number.isFinite(max) && max > 0 ? max : 0 });
+        const template = this.tDynamicFields('entityLookup.selectionLimitReached', 'Limite de {max} seleções atingido.', { max: Number.isFinite(max) && max > 0 ? max : 0 });
         return template.replace('{max}', String(Number.isFinite(max) && max > 0 ? max : 0));
     }
     onDetailAction(event, item) {
@@ -13278,7 +13309,7 @@ class InlineEntityLookupComponent extends MaterialAsyncSelectComponent {
     }
     resetOptionText() {
         const custom = String(this.metadata()?.resetLabel || '').trim();
-        return custom || 'Limpar selecao';
+        return custom || 'Limpar seleção';
     }
     showQuickClear() {
         const clearCfg = this.currentMetadata().clearButton;
@@ -13382,7 +13413,7 @@ class InlineEntityLookupComponent extends MaterialAsyncSelectComponent {
         this.retry();
     }
     errorStateLabel() {
-        return this.error() || this.tDynamicFields('select.loadOptionsError', 'Erro ao carregar opcoes.');
+        return this.error() || this.tDynamicFields('select.loadOptionsError', 'Erro ao carregar opções.');
     }
     dependencyStateLabel() {
         const dependencyLabels = this.missingDependencyLabels();
@@ -13453,7 +13484,7 @@ class InlineEntityLookupComponent extends MaterialAsyncSelectComponent {
         return this.tDynamicFields('entityLookup.sort.label', 'Ordenar por');
     }
     sortDefaultOptionText() {
-        return this.tDynamicFields('entityLookup.sort.default', 'Padrao');
+        return this.tDynamicFields('entityLookup.sort.default', 'Padrão');
     }
     clearAllFiltersText() {
         return this.tDynamicFields('entityLookup.filter.clearAll', 'Limpar filtros');
@@ -17626,11 +17657,11 @@ function createInlinePhoneComponentMetadata(locale = 'en-US') {
 }
 
 /**
- * Placeholder component for file upload fields.
+ * Baseline file upload field.
  *
- * Currently provides a simple `<input type="file">` element and basic
- * ControlValueAccessor integration. A full-featured implementation will
- * be provided in future iterations.
+ * This component owns local file selection, validation and preview. Persisting
+ * the selected file remains a host/backend concern; use @praxisui/files-upload
+ * when the flow needs presign, progress, conflict policy or storage events.
  */
 class MaterialFileUploadComponent extends SimpleBaseInputComponent {
     // Praxis Field States
@@ -17638,13 +17669,55 @@ class MaterialFileUploadComponent extends SimpleBaseInputComponent {
     disabledMode = false;
     visible = true;
     presentationMode = false;
+    selectedFiles = signal([], ...(ngDevMode ? [{ debugName: "selectedFiles" }] : /* istanbul ignore next */ []));
+    previewUrl = signal(null, ...(ngDevMode ? [{ debugName: "previewUrl" }] : /* istanbul ignore next */ []));
+    externalValueSyncSubscription = new Subscription();
+    selectedSummaryText = computed(() => {
+        const files = this.selectedFiles();
+        if (!files.length) {
+            return this.dynamicFieldsText('fileUpload.emptySummary', 'No file selected');
+        }
+        if (files.length === 1) {
+            return files[0].name;
+        }
+        return this.dynamicFieldsText('fileUpload.multipleSummary', '{{count}} files selected', {
+            count: files.length,
+        });
+    }, ...(ngDevMode ? [{ debugName: "selectedSummaryText" }] : /* istanbul ignore next */ []));
+    selectedDetailText = computed(() => {
+        const files = this.selectedFiles();
+        if (!files.length)
+            return '';
+        const total = files.reduce((sum, file) => sum + file.size, 0);
+        return this.formatBytes(total);
+    }, ...(ngDevMode ? [{ debugName: "selectedDetailText" }] : /* istanbul ignore next */ []));
     /**
      * Updates the control value when the user selects a file.
      */
     onFileSelected(event) {
         const input = event.target;
-        const file = input.files?.[0] ?? null;
-        this.setValue(file);
+        const files = Array.from(input.files ?? []);
+        if (!files.length) {
+            this.clearSelectedFiles({ resetInput: false });
+            return;
+        }
+        const selected = this.allowsMultiple() ? files : files.slice(0, 1);
+        const validationError = this.validateSelectedFiles(selected);
+        if (validationError) {
+            this.clearPreview();
+            this.selectedFiles.set([]);
+            this.setValue(this.allowsMultiple() ? [] : null, { emitEvent: true });
+            this.applyFileError(validationError);
+            input.value = '';
+            return;
+        }
+        this.clearFileErrors();
+        this.selectedFiles.set(selected);
+        this.updatePreview(selected);
+        this.setValue(this.allowsMultiple() ? selected : selected[0], { emitEvent: true });
+        const control = this.control();
+        control.markAsDirty();
+        control.markAsTouched();
     }
     /**
      * Exposes metadata setter for integration with dynamic form loader.
@@ -17660,8 +17733,71 @@ class MaterialFileUploadComponent extends SimpleBaseInputComponent {
     allowsMultiple() {
         return this.metadataRecord()?.['multiple'] === true;
     }
+    imagePreviewEnabled() {
+        const metadata = this.metadataRecord();
+        if (metadata?.['imagePreview'] === true)
+            return true;
+        if (metadata?.['preview'] === 'image')
+            return true;
+        const accept = this.fileAccept()?.toLowerCase() ?? '';
+        return accept.includes('image/');
+    }
     isInteractionDisabled() {
-        return this.disabledMode || this.readonlyMode || this.presentationMode;
+        return this.isInteractionBlockedByState();
+    }
+    clearSelectedFiles(options = {}) {
+        this.clearPreview();
+        this.selectedFiles.set([]);
+        this.clearFileErrors();
+        this.setValue(this.allowsMultiple() ? [] : null, { emitEvent: true });
+        const control = this.control();
+        control.markAsDirty();
+        control.markAsTouched();
+        if (options.resetInput !== false) {
+            const input = this.elementRef.nativeElement.querySelector('input[type="file"]');
+            if (input)
+                input.value = '';
+        }
+    }
+    clearLabel() {
+        return this.dynamicFieldsText('fileUpload.clearSelection', 'Clear');
+    }
+    clearAriaLabel() {
+        return this.dynamicFieldsText('fileUpload.clearSelectionAriaLabel', 'Clear selected file');
+    }
+    selectedSummaryAriaLabel() {
+        return this.dynamicFieldsText('fileUpload.selectedSummaryAriaLabel', 'Selected file');
+    }
+    fileInputDescribedBy() {
+        const ids = [
+            this.metadata()?.ariaDescribedby,
+            this.hasValidationError() ? this.errorId() : null,
+            this.metadata()?.hint && !this.hasValidationError() ? this.hintId() : null,
+        ]
+            .map((id) => (typeof id === 'string' ? id.trim() : ''))
+            .filter(Boolean);
+        return ids.length ? ids.join(' ') : null;
+    }
+    hintId() {
+        return `${this.componentId()}-hint`;
+    }
+    errorId() {
+        return `${this.componentId()}-error`;
+    }
+    previewAltText() {
+        const label = this.metadataRecord()?.['previewAlt'];
+        if (typeof label === 'string' && label.trim())
+            return label.trim();
+        return this.dynamicFieldsText('fileUpload.previewAlt', 'Selected image preview');
+    }
+    writeValue(value) {
+        super.writeValue(value);
+        this.syncSelectedFilesFromValue(value);
+    }
+    ngOnDestroy() {
+        this.externalValueSyncSubscription.unsubscribe();
+        this.clearPreview();
+        super.ngOnDestroy();
     }
     /**
      * CSS classes specific to the file upload wrapper.
@@ -17669,12 +17805,168 @@ class MaterialFileUploadComponent extends SimpleBaseInputComponent {
     getSpecificCssClasses() {
         return ['pdx-material-file-upload'];
     }
+    onActiveControlChanged(previousControl, currentControl) {
+        super.onActiveControlChanged(previousControl, currentControl);
+        this.externalValueSyncSubscription.unsubscribe();
+        this.externalValueSyncSubscription = currentControl.valueChanges.subscribe((value) => {
+            this.syncSelectedFilesFromValue(value);
+        });
+        this.syncSelectedFilesFromValue(currentControl.value);
+    }
     metadataRecord() {
         const metadata = this.metadata();
         return metadata && typeof metadata === 'object'
             ? metadata
             : null;
     }
+    updatePreview(files) {
+        this.clearPreview();
+        if (!this.imagePreviewEnabled())
+            return;
+        const image = files.find((file) => this.isImageFile(file));
+        if (!image || typeof URL === 'undefined' || typeof URL.createObjectURL !== 'function') {
+            return;
+        }
+        this.previewUrl.set(URL.createObjectURL(image));
+    }
+    clearPreview() {
+        const current = this.previewUrl();
+        if (current && typeof URL !== 'undefined' && typeof URL.revokeObjectURL === 'function') {
+            URL.revokeObjectURL(current);
+        }
+        this.previewUrl.set(null);
+    }
+    validateSelectedFiles(files) {
+        const maxFileSize = this.maxFileSize();
+        const maxFiles = this.maxFiles();
+        if (maxFiles !== null && files.length > maxFiles) {
+            return {
+                key: 'maxFiles',
+                message: this.dynamicFieldsText('validation.maxFiles', 'Too many files selected', {
+                    count: maxFiles,
+                }),
+            };
+        }
+        for (const file of files) {
+            if (!this.isAcceptedFile(file)) {
+                return {
+                    key: 'fileType',
+                    message: this.dynamicFieldsText('validation.fileType', 'File type is not allowed'),
+                };
+            }
+            if (maxFileSize !== null && file.size > maxFileSize) {
+                return {
+                    key: 'maxFileSize',
+                    message: this.dynamicFieldsText('validation.maxFileSize', 'File exceeds the maximum size'),
+                };
+            }
+        }
+        return null;
+    }
+    isAcceptedFile(file) {
+        const accept = this.fileAccept();
+        if (!accept)
+            return true;
+        const fileName = file.name.toLowerCase();
+        const fileType = file.type.toLowerCase();
+        return accept
+            .split(',')
+            .map((token) => token.trim().toLowerCase())
+            .filter(Boolean)
+            .some((token) => {
+            if (token === '*/*')
+                return true;
+            if (token === 'image/*')
+                return fileType.startsWith('image/') || this.hasKnownImageExtension(fileName);
+            if (token.endsWith('/*'))
+                return fileType.startsWith(token.slice(0, -1));
+            if (token.startsWith('.'))
+                return fileName.endsWith(token);
+            return fileType === token;
+        });
+    }
+    maxFileSize() {
+        const raw = this.metadataRecord()?.['maxFileSize'];
+        const value = typeof raw === 'number' ? raw : Number(raw);
+        return Number.isFinite(value) && value > 0 ? value : null;
+    }
+    maxFiles() {
+        const raw = this.metadataRecord()?.['maxFiles'];
+        const value = typeof raw === 'number' ? raw : Number(raw);
+        return Number.isInteger(value) && value > 0 ? value : null;
+    }
+    applyFileError(error) {
+        const control = this.control();
+        const current = control.errors ?? {};
+        control.setErrors({
+            ...current,
+            [error.key]: { message: error.message },
+        });
+        control.markAsDirty();
+        control.markAsTouched();
+    }
+    clearFileErrors() {
+        const control = this.control();
+        const current = control.errors;
+        if (!current)
+            return;
+        const { fileType: _fileType, maxFileSize: _maxFileSize, maxFiles: _maxFiles, ...rest } = current;
+        control.setErrors(Object.keys(rest).length ? rest : null);
+    }
+    syncSelectedFilesFromValue(value) {
+        const files = this.extractFilesFromValue(value);
+        this.selectedFiles.set(files);
+        this.updatePreview(files);
+    }
+    extractFilesFromValue(value) {
+        if (!value)
+            return [];
+        if (this.isFile(value))
+            return [value];
+        if (Array.isArray(value))
+            return value.filter((item) => this.isFile(item));
+        return [];
+    }
+    isFile(value) {
+        return typeof File !== 'undefined' && value instanceof File;
+    }
+    isImageFile(file) {
+        return file.type.toLowerCase().startsWith('image/') || this.hasKnownImageExtension(file.name.toLowerCase());
+    }
+    hasKnownImageExtension(fileName) {
+        return [
+            '.apng',
+            '.avif',
+            '.bmp',
+            '.gif',
+            '.jpeg',
+            '.jpg',
+            '.png',
+            '.svg',
+            '.webp',
+        ].some((extension) => fileName.endsWith(extension));
+    }
+    formatBytes(bytes) {
+        const units = [
+            this.dynamicFieldsText('fileUpload.sizeUnitBytes', 'B'),
+            this.dynamicFieldsText('fileUpload.sizeUnitKb', 'KB'),
+            this.dynamicFieldsText('fileUpload.sizeUnitMb', 'MB'),
+            this.dynamicFieldsText('fileUpload.sizeUnitGb', 'GB'),
+        ];
+        if (!Number.isFinite(bytes) || bytes <= 0)
+            return `0 ${units[0]}`;
+        let value = bytes;
+        let index = 0;
+        while (value >= 1024 && index < units.length - 1) {
+            value /= 1024;
+            index += 1;
+        }
+        const rounded = value >= 10 || index === 0 ? Math.round(value) : Math.round(value * 10) / 10;
+        return `${rounded} ${units[index]}`;
+    }
+    dynamicFieldsText(keySuffix, fallback, params) {
+        return this.i18n.t(`praxis.dynamicFields.${keySuffix}`, params, fallback, 'dynamicFields');
+    }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: MaterialFileUploadComponent, deps: null, target: i0.ɵɵFactoryTarget.Component });
     static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.14", type: MaterialFileUploadComponent, isStandalone: true, selector: "pdx-material-file-upload", inputs: { readonlyMode: "readonlyMode", disabledMode: "disabledMode", visible: "visible", presentationMode: "presentationMode" }, host: { properties: { "class": "componentCssClasses()", "class.praxis-disabled": "disabledMode", "style.display": "visible ? null : \"none\"", "attr.aria-hidden": "visible ? null : \"true\"", "attr.data-field-type": "\"file-upload\"", "attr.data-field-name": "metadata()?.name", "attr.data-component-id": "componentId()" } }, providers: [
             {
@@ -17697,24 +17989,51 @@ class MaterialFileUploadComponent extends SimpleBaseInputComponent {
         [attr.accept]="fileAccept()"
         [attr.multiple]="allowsMultiple() ? '' : null"
         [disabled]="isInteractionDisabled()"
-        [attr.aria-disabled]="disabledMode ? 'true' : null"
+        [attr.aria-disabled]="isInteractionDisabled() ? 'true' : null"
+        [attr.aria-describedby]="fileInputDescribedBy()"
+        [attr.aria-invalid]="hasValidationError() ? 'true' : null"
+        [attr.aria-label]="inputAriaLabel()"
       />
+      @if (selectedFiles().length) {
+        <div
+          class="pdx-file-upload__selection"
+          aria-live="polite"
+          [attr.aria-label]="selectedSummaryAriaLabel()"
+        >
+          @if (previewUrl()) {
+            <img
+              class="pdx-file-upload__preview"
+              [src]="previewUrl()!"
+              [attr.alt]="previewAltText()"
+            />
+          }
+          <div class="pdx-file-upload__summary">
+            <span class="pdx-file-upload__summary-title">{{ selectedSummaryText() }}</span>
+            <span class="pdx-file-upload__summary-detail">{{ selectedDetailText() }}</span>
+          </div>
+          <button
+            class="pdx-file-upload__clear"
+            type="button"
+            [disabled]="isInteractionDisabled()"
+            [attr.aria-label]="clearAriaLabel()"
+            (click)="clearSelectedFiles()"
+          >
+            {{ clearLabel() }}
+          </button>
+        </div>
+      }
       @if (hasValidationError()) {
-        <div class="error">{{ errorMessage() }}</div>
+        <div class="error" [attr.id]="errorId()">{{ errorMessage() }}</div>
       }
       @if (metadata()?.hint && !hasValidationError()) {
-        <div class="hint">{{ metadata()!.hint }}</div>
+        <div class="hint" [attr.id]="hintId()">{{ metadata()!.hint }}</div>
       }
     </div>
-  `, isInline: true, dependencies: [{ kind: "ngmodule", type: ReactiveFormsModule }, { kind: "ngmodule", type: MatTooltipModule }, { kind: "directive", type: i5.MatTooltip, selector: "[matTooltip]", inputs: ["matTooltipPosition", "matTooltipPositionAtOrigin", "matTooltipDisabled", "matTooltipShowDelay", "matTooltipHideDelay", "matTooltipTouchGestures", "matTooltip", "matTooltipClass"], exportAs: ["matTooltip"] }] });
+  `, isInline: true, styles: [".pdx-file-upload{display:flex;flex-direction:column;gap:8px}.pdx-file-upload label{font-size:12px;font-weight:500;line-height:1.25;color:var(--md-sys-color-on-surface, rgba(0, 0, 0, .87))}.pdx-file-upload input[type=file]{max-width:100%}.pdx-file-upload__selection{display:flex;align-items:center;gap:10px;min-width:0;padding:8px;border:1px solid var(--md-sys-color-outline-variant, rgba(0, 0, 0, .16));border-radius:8px;background:var(--md-sys-color-surface-container-low, rgba(0, 0, 0, .03))}.pdx-file-upload__preview{width:48px;height:48px;border-radius:9999px;object-fit:cover;flex:0 0 48px;border:1px solid var(--md-sys-color-outline-variant, rgba(0, 0, 0, .16))}.pdx-file-upload__summary{display:flex;min-width:0;flex:1 1 auto;flex-direction:column;gap:2px}.pdx-file-upload__summary-title,.pdx-file-upload__summary-detail{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.pdx-file-upload__summary-title{font-size:13px;font-weight:600;color:var(--md-sys-color-on-surface, rgba(0, 0, 0, .87))}.pdx-file-upload__summary-detail,.hint{font-size:12px;color:var(--md-sys-color-on-surface-variant, rgba(0, 0, 0, .6))}.pdx-file-upload__clear{border:0;background:transparent;color:var(--md-sys-color-primary, #6750a4);font:inherit;font-size:12px;font-weight:600;cursor:pointer;padding:6px}.pdx-file-upload__clear:disabled{cursor:default;opacity:.5}.error{color:var(--md-sys-color-error, #b3261e);font-size:12px}\n"], dependencies: [{ kind: "ngmodule", type: ReactiveFormsModule }, { kind: "ngmodule", type: MatTooltipModule }, { kind: "directive", type: i5.MatTooltip, selector: "[matTooltip]", inputs: ["matTooltipPosition", "matTooltipPositionAtOrigin", "matTooltipDisabled", "matTooltipShowDelay", "matTooltipHideDelay", "matTooltipTouchGestures", "matTooltip", "matTooltipClass"], exportAs: ["matTooltip"] }] });
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: MaterialFileUploadComponent, decorators: [{
             type: Component,
-            args: [{
-                    selector: 'pdx-material-file-upload',
-                    standalone: true,
-                    imports: [ReactiveFormsModule, MatTooltipModule],
-                    template: `
+            args: [{ selector: 'pdx-material-file-upload', standalone: true, imports: [ReactiveFormsModule, MatTooltipModule], template: `
     <div
       class="pdx-file-upload"
       [matTooltip]="tooltipEnabled() ? errorMessage() : null"
@@ -17729,24 +18048,53 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImpo
         [attr.accept]="fileAccept()"
         [attr.multiple]="allowsMultiple() ? '' : null"
         [disabled]="isInteractionDisabled()"
-        [attr.aria-disabled]="disabledMode ? 'true' : null"
+        [attr.aria-disabled]="isInteractionDisabled() ? 'true' : null"
+        [attr.aria-describedby]="fileInputDescribedBy()"
+        [attr.aria-invalid]="hasValidationError() ? 'true' : null"
+        [attr.aria-label]="inputAriaLabel()"
       />
+      @if (selectedFiles().length) {
+        <div
+          class="pdx-file-upload__selection"
+          aria-live="polite"
+          [attr.aria-label]="selectedSummaryAriaLabel()"
+        >
+          @if (previewUrl()) {
+            <img
+              class="pdx-file-upload__preview"
+              [src]="previewUrl()!"
+              [attr.alt]="previewAltText()"
+            />
+          }
+          <div class="pdx-file-upload__summary">
+            <span class="pdx-file-upload__summary-title">{{ selectedSummaryText() }}</span>
+            <span class="pdx-file-upload__summary-detail">{{ selectedDetailText() }}</span>
+          </div>
+          <button
+            class="pdx-file-upload__clear"
+            type="button"
+            [disabled]="isInteractionDisabled()"
+            [attr.aria-label]="clearAriaLabel()"
+            (click)="clearSelectedFiles()"
+          >
+            {{ clearLabel() }}
+          </button>
+        </div>
+      }
       @if (hasValidationError()) {
-        <div class="error">{{ errorMessage() }}</div>
+        <div class="error" [attr.id]="errorId()">{{ errorMessage() }}</div>
       }
       @if (metadata()?.hint && !hasValidationError()) {
-        <div class="hint">{{ metadata()!.hint }}</div>
+        <div class="hint" [attr.id]="hintId()">{{ metadata()!.hint }}</div>
       }
     </div>
-  `,
-                    providers: [
+  `, providers: [
                         {
                             provide: NG_VALUE_ACCESSOR,
                             useExisting: forwardRef(() => MaterialFileUploadComponent),
                             multi: true,
                         },
-                    ],
-                    host: {
+                    ], host: {
                         '[class]': 'componentCssClasses()',
                         '[class.praxis-disabled]': 'disabledMode',
                         '[style.display]': 'visible ? null : "none"',
@@ -17754,8 +18102,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImpo
                         '[attr.data-field-type]': '"file-upload"',
                         '[attr.data-field-name]': 'metadata()?.name',
                         '[attr.data-component-id]': 'componentId()',
-                    },
-                }]
+                    }, styles: [".pdx-file-upload{display:flex;flex-direction:column;gap:8px}.pdx-file-upload label{font-size:12px;font-weight:500;line-height:1.25;color:var(--md-sys-color-on-surface, rgba(0, 0, 0, .87))}.pdx-file-upload input[type=file]{max-width:100%}.pdx-file-upload__selection{display:flex;align-items:center;gap:10px;min-width:0;padding:8px;border:1px solid var(--md-sys-color-outline-variant, rgba(0, 0, 0, .16));border-radius:8px;background:var(--md-sys-color-surface-container-low, rgba(0, 0, 0, .03))}.pdx-file-upload__preview{width:48px;height:48px;border-radius:9999px;object-fit:cover;flex:0 0 48px;border:1px solid var(--md-sys-color-outline-variant, rgba(0, 0, 0, .16))}.pdx-file-upload__summary{display:flex;min-width:0;flex:1 1 auto;flex-direction:column;gap:2px}.pdx-file-upload__summary-title,.pdx-file-upload__summary-detail{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.pdx-file-upload__summary-title{font-size:13px;font-weight:600;color:var(--md-sys-color-on-surface, rgba(0, 0, 0, .87))}.pdx-file-upload__summary-detail,.hint{font-size:12px;color:var(--md-sys-color-on-surface-variant, rgba(0, 0, 0, .6))}.pdx-file-upload__clear{border:0;background:transparent;color:var(--md-sys-color-primary, #6750a4);font:inherit;font-size:12px;font-weight:600;cursor:pointer;padding:6px}.pdx-file-upload__clear:disabled{cursor:default;opacity:.5}.error{color:var(--md-sys-color-error, #b3261e);font-size:12px}\n"] }]
         }], propDecorators: { readonlyMode: [{
                 type: Input
             }], disabledMode: [{
@@ -43610,7 +43957,7 @@ class InlineDistanceRadiusComponent extends InlineRangeSliderComponent {
         const subtitle = String(md.distanceSubtitle ?? md.inlinePanelSubtitle ?? md.inlineSubtitle ?? md.hint ?? '').trim();
         if (subtitle.length)
             return subtitle;
-        return this.distanceText('inlineDistance.panelSubtitle', 'Visualizacao radial com controle de raio e unidade');
+        return this.distanceText('inlineDistance.panelSubtitle', 'Visualização radial com controle de raio e unidade');
     }
     unitToggleAriaLabel() {
         return this.distanceText('inlineDistance.unitToggleAriaLabel', 'Unidade de distancia atual: {{unit}}', {
@@ -59405,7 +59752,7 @@ const PDX_INLINE_DATE_RANGE_COMPONENT_METADATA = {
     selector: 'pdx-inline-date-range',
     component: InlineDateRangeComponent,
     friendlyName: 'Inline Date Range',
-    description: 'Intervalo de datas compacto para barras de filtro dinamico, com autosize e presets rápidos no overlay do calendário.',
+    description: 'Intervalo de datas compacto para barras de filtro dinâmico, com autosize e presets rápidos no overlay do calendário.',
     icon: 'date_range',
     inputs: [
         { name: 'metadata', type: 'MaterialDateRangeMetadata', description: 'Configuração do campo' },
@@ -59423,10 +59770,10 @@ const PDX_INLINE_TIME_COMPONENT_METADATA = {
     selector: 'pdx-inline-time',
     component: InlineTimeComponent,
     friendlyName: 'Inline Time',
-    description: 'Timepicker compacto para barras de filtro dinamico, com largura por conteudo e selecao inline em lista ou colunas Hor/Min/Seg.',
+    description: 'Timepicker compacto para barras de filtro dinâmico, com largura por conteúdo e seleção inline em lista ou colunas Hor/Min/Seg.',
     icon: 'schedule',
     inputs: [
-        { name: 'metadata', type: 'MaterialTimepickerMetadata', description: 'Configuracao do campo' },
+        { name: 'metadata', type: 'MaterialTimepickerMetadata', description: 'Configuração do campo' },
         { name: 'readonlyMode', type: 'boolean', default: false, description: 'Define modo somente leitura' },
         { name: 'disabledMode', type: 'boolean', default: false, description: 'Desabilita o campo' },
         { name: 'visible', type: 'boolean', default: true, description: 'Controla a visibilidade' },
@@ -59444,7 +59791,7 @@ const PDX_INLINE_TIME_RANGE_COMPONENT_METADATA = {
     description: 'Intervalo de horário compacto para barras de filtro dinâmico, com pill responsiva, slider de faixa, atalhos rápidos e popover não-modal com foco de teclado tratado para uso corporativo.',
     icon: 'schedule',
     inputs: [
-        { name: 'metadata', type: 'MaterialTimeRangeMetadata', description: 'Configuracao do campo' },
+        { name: 'metadata', type: 'MaterialTimeRangeMetadata', description: 'Configuração do campo' },
         { name: 'readonlyMode', type: 'boolean', default: false, description: 'Define modo somente leitura' },
         { name: 'disabledMode', type: 'boolean', default: false, description: 'Desabilita o campo' },
         { name: 'visible', type: 'boolean', default: true, description: 'Controla a visibilidade' },
@@ -59459,10 +59806,10 @@ const PDX_INLINE_TREE_SELECT_COMPONENT_METADATA = {
     selector: 'pdx-inline-tree-select',
     component: InlineTreeSelectComponent,
     friendlyName: 'Inline Tree Select',
-    description: 'Selecao hierarquica compacta para barras de filtro dinamico, com busca no popover e resumo em pill.',
+    description: 'Seleção hierárquica compacta para barras de filtro dinâmico, com busca no popover e resumo em pill.',
     icon: 'account_tree',
     inputs: [
-        { name: 'metadata', type: 'MaterialTreeSelectMetadata', description: 'Configuracao do campo' },
+        { name: 'metadata', type: 'MaterialTreeSelectMetadata', description: 'Configuração do campo' },
         { name: 'readonlyMode', type: 'boolean', default: false, description: 'Define modo somente leitura' },
         { name: 'disabledMode', type: 'boolean', default: false, description: 'Desabilita o campo' },
         { name: 'visible', type: 'boolean', default: true, description: 'Controla a visibilidade' },
@@ -59495,14 +59842,14 @@ const PDX_INLINE_DISTANCE_RADIUS_COMPONENT_METADATA = {
     selector: 'pdx-inline-distance-radius',
     component: InlineDistanceRadiusComponent,
     friendlyName: 'Inline Distance Radius',
-    description: 'Filtro inline de raio de distancia com visual radial, slider single/range, toggle de unidade (km/mi) e presets.',
+    description: 'Filtro inline de raio de distância com visual radial, slider single/range, toggle de unidade (km/mi) e presets.',
     icon: 'place',
     inputs: [
-        { name: 'metadata', type: 'MaterialRangeSliderMetadata', description: 'Configuracao do campo' },
+        { name: 'metadata', type: 'MaterialRangeSliderMetadata', description: 'Configuração do campo' },
         { name: 'readonlyMode', type: 'boolean', default: false, description: 'Define modo somente leitura' },
         { name: 'disabledMode', type: 'boolean', default: false, description: 'Desabilita o campo' },
         { name: 'visible', type: 'boolean', default: true, description: 'Controla a visibilidade' },
-        { name: 'presentationMode', type: 'boolean', default: false, description: 'Modo de apresentacao' },
+        { name: 'presentationMode', type: 'boolean', default: false, description: 'Modo de apresentação' },
     ],
     tags: ['widget', 'field', 'distance', 'radius', 'filter', 'inline'],
     lib: '@praxisui/dynamic-fields',
@@ -59513,14 +59860,14 @@ const PDX_INLINE_PIPELINE_STATUS_COMPONENT_METADATA = {
     selector: 'pdx-inline-pipeline-status',
     component: InlinePipelineStatusComponent,
     friendlyName: 'Inline Pipeline Status',
-    description: 'Filtro inline de status/etapas com popover, barra segmentada e selecao single ou multipla totalmente configuravel por metadados.',
+    description: 'Filtro inline de status/etapas com popover, barra segmentada e seleção single ou múltipla totalmente configurável por metadados.',
     icon: 'timeline',
     inputs: [
-        { name: 'metadata', type: 'MaterialSelectMetadata', description: 'Configuracao do campo' },
+        { name: 'metadata', type: 'MaterialSelectMetadata', description: 'Configuração do campo' },
         { name: 'readonlyMode', type: 'boolean', default: false, description: 'Define modo somente leitura' },
         { name: 'disabledMode', type: 'boolean', default: false, description: 'Desabilita o campo' },
         { name: 'visible', type: 'boolean', default: true, description: 'Controla a visibilidade' },
-        { name: 'presentationMode', type: 'boolean', default: false, description: 'Modo de apresentacao' },
+        { name: 'presentationMode', type: 'boolean', default: false, description: 'Modo de apresentação' },
     ],
     tags: ['widget', 'field', 'pipeline', 'status', 'filter', 'inline', 'multiselect'],
     lib: '@praxisui/dynamic-fields',
@@ -59534,7 +59881,7 @@ const PDX_INLINE_SCORE_PRIORITY_COMPONENT_METADATA = {
     description: 'Filtro inline de score/prioridade com faixa colorida, slider single/range, bandas configuráveis por metadados preservadas integralmente para semântica decisória, rótulos de escala com autoajuste de densidade e painel em popover não-modal.',
     icon: 'speed',
     inputs: [
-        { name: 'metadata', type: 'MaterialRangeSliderMetadata', description: 'Configuracao do campo' },
+        { name: 'metadata', type: 'MaterialRangeSliderMetadata', description: 'Configuração do campo' },
         { name: 'readonlyMode', type: 'boolean', default: false, description: 'Define modo somente leitura' },
         { name: 'disabledMode', type: 'boolean', default: false, description: 'Desabilita o campo' },
         { name: 'visible', type: 'boolean', default: true, description: 'Controla a visibilidade' },
@@ -59585,10 +59932,10 @@ const PDX_INLINE_COLOR_LABEL_COMPONENT_METADATA = {
     selector: 'pdx-inline-color-label',
     component: InlineColorLabelComponent,
     friendlyName: 'Inline Color Label',
-    description: 'Filtro inline de cor/label com grid de cores, selecao visual e badges removiveis.',
+    description: 'Filtro inline de cor/label com grid de cores, seleção visual e badges removíveis.',
     icon: 'palette',
     inputs: [
-        { name: 'metadata', type: 'MaterialSelectMetadata', description: 'Configuracao do campo' },
+        { name: 'metadata', type: 'MaterialSelectMetadata', description: 'Configuração do campo' },
         { name: 'readonlyMode', type: 'boolean', default: false, description: 'Define modo somente leitura' },
         { name: 'disabledMode', type: 'boolean', default: false, description: 'Desabilita o campo' },
         { name: 'visible', type: 'boolean', default: true, description: 'Controla a visibilidade' },
@@ -61256,7 +61603,7 @@ const INLINE_DISTANCE_RADIUS_PREVIEW_METADATA = {
     distanceUnit: 'km',
     distanceBaseUnit: 'km',
     distanceAllowUnitToggle: true,
-    distanceSubtitle: 'Visualizacao radial com controle de raio e unidade',
+    distanceSubtitle: 'Visualização radial com controle de raio e unidade',
     distanceRadialRings: 5,
     distanceAccentColor: '#3f5be6',
     inlineAutoSize: {
@@ -62361,10 +62708,13 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
         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.',
+            maxFileSize: 4194304,
+            maxFiles: 1,
+            imagePreview: true,
+            hint: 'Select a file locally; image flows show a preview before the host persists the file.',
         },
-        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.',
+        snippet: `{ "name": "attachment", "controlType": "upload", "accept": ".pdf,.png,.jpg", "maxFileSize": 4194304, "maxFiles": 1, "imagePreview": true, "hint": "Select a file locally; image flows show a preview before the host persists the file." }`,
+        snippetNote: 'This preview demonstrates local selection, validation and image preview. Use @praxisui/files-upload for presign, progress and persisted storage.',
     }),
     createEntry({
         id: 'color-input',
@@ -62470,7 +62820,7 @@ const DYNAMIC_FIELDS_PLAYGROUND_CATALOG = [
                 metadataPatch: {
                     extra: {
                         icon: 'person',
-                        ariaLabel: 'Avatar com icone de pessoa',
+                        ariaLabel: 'Avatar com ícone de pessoa',
                         size: 'medium',
                         fillMode: 'outline',
                         themeColor: 'primary',
@@ -64059,7 +64409,7 @@ const DISPLAY_ACTION_AI_CAPABILITIES = {
             category: 'appearance',
             valueKind: 'enum',
             allowedValues: ['primary', 'secondary', 'tertiary', 'base', 'info', 'success', 'warning', 'error', 'dark', 'light', 'inverse', 'none'],
-            description: 'Cor semantica do avatar baseada nos tokens de tema Praxis.',
+            description: 'Cor semântica do avatar baseada nos tokens de tema Praxis.',
         },
         {
             path: 'rounded',
@@ -64203,23 +64553,26 @@ const FILE_UPLOAD_AI_CAPABILITIES = {
         uploadMethod: ['POST', 'PUT', 'PATCH'],
     },
     notes: [
-        'Capabilities for file upload controls.',
+        'Capabilities for file upload controls. The baseline pdx-material-file-upload runtime owns local selection, local validation and optional local image preview.',
         'Inherits basic capabilities from FieldMetadata (label, hint, validators).',
+        'Persistence capabilities such as uploadUrl, autoUpload, chunkSize, headers, credentials and method must be grounded by @praxisui/files-upload or a backend upload capability; they are not executed by the baseline local selector alone.',
     ],
     capabilities: [
         {
             path: 'uploadUrl',
             category: 'data',
             valueKind: 'string',
-            description: 'URL do endpoint para upload de arquivos.',
+            description: 'URL do endpoint para upload de arquivos em fluxo persistente governado.',
             intentExamples: ['endpoint de upload de imagens', 'salvar arquivos em /api/docs'],
+            safetyNotes: 'Requer runtime/capability de persistencia como @praxisui/files-upload; o seletor baseline nao executa upload HTTP.',
         },
         {
             path: 'autoUpload',
             category: 'behavior',
             valueKind: 'boolean',
-            description: 'Se true, inicia o upload automaticamente após a seleção do arquivo.',
+            description: 'Se true, inicia o upload automaticamente após a seleção do arquivo em fluxo persistente governado.',
             intentExamples: ['upload automático', 'não iniciar upload imediatamente'],
+            safetyNotes: 'Requer runtime/capability de persistencia; o seletor baseline apenas emite File/File[].',
         },
         {
             path: 'multiple',
@@ -64235,6 +64588,21 @@ const FILE_UPLOAD_AI_CAPABILITIES = {
             description: 'Tipos de arquivo aceitos (ex: "image/*", ".pdf").',
             intentExamples: ['aceitar apenas imagens', 'apenas PDF'],
         },
+        {
+            path: 'imagePreview',
+            category: 'appearance',
+            valueKind: 'boolean',
+            description: 'Exibe preview local para imagens selecionadas antes da persistencia pelo host.',
+            intentExamples: ['mostrar preview da foto escolhida', 'pré-visualizar avatar antes de salvar'],
+        },
+        {
+            path: 'preview',
+            category: 'appearance',
+            valueKind: 'string',
+            allowedValues: ['image'],
+            description: 'Modo de preview local. Use "image" para fluxos de foto/avatar.',
+            safetyNotes: 'Preview local não substitui upload, presign, crop persistido ou validação backend.',
+        },
         {
             path: 'maxFileSize',
             category: 'validation',
@@ -64261,18 +64629,21 @@ const FILE_UPLOAD_AI_CAPABILITIES = {
             category: 'behavior',
             valueKind: 'number',
             description: 'Tamanho dos chunks em bytes para uploads grandes (file chunking).',
+            safetyNotes: 'Aplicavel ao fluxo @praxisui/files-upload ou backend equivalente, nao ao seletor local baseline.',
         },
         {
             path: 'withCredentials',
             category: 'data',
             valueKind: 'boolean',
             description: 'Envia cookies e headers de autorização com a requisição de upload.',
+            safetyNotes: 'Aplicavel ao fluxo @praxisui/files-upload ou backend equivalente, nao ao seletor local baseline.',
         },
         {
             path: 'headers',
             category: 'data',
             valueKind: 'object',
             description: 'Cabeçalhos HTTP personalizados para a requisição de upload.',
+            safetyNotes: 'Aplicavel ao fluxo @praxisui/files-upload ou backend equivalente, nao ao seletor local baseline.',
         },
         {
             path: 'method',
@@ -64280,6 +64651,7 @@ const FILE_UPLOAD_AI_CAPABILITIES = {
             valueKind: 'enum',
             allowedValues: ['POST', 'PUT', 'PATCH'],
             description: 'Método HTTP para a requisição de upload.',
+            safetyNotes: 'Aplicavel ao fluxo @praxisui/files-upload ou backend equivalente, nao ao seletor local baseline.',
         },
         {
             path: 'saveField',
@@ -66160,7 +66532,7 @@ function mapValuePresentation(value) {
     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}`);
+            logger.warn(`[JsonSchemaMapper] Ignorando x-ui.valuePresentation.type inválido: ${typeToken}`);
         }
         return undefined;
     }
@@ -66173,7 +66545,7 @@ function mapValuePresentation(value) {
             presentation.style = styleToken;
         }
         else {
-            logger.warn(`[JsonSchemaMapper] Ignorando x-ui.valuePresentation.style invalido: ${styleToken}`);
+            logger.warn(`[JsonSchemaMapper] Ignorando x-ui.valuePresentation.style inválido: ${styleToken}`);
         }
     }
     const formatToken = String(value.format ?? '').trim();