@praxisui/dynamic-fields 9.0.0-beta.17 → 9.0.0-beta.19

package/package.json

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

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

@@ -21,8 +21,8 @@ source_of_truth:
   - "projects/praxis-dynamic-fields/src/lib/components/material-file-upload/material-file-upload.metadata.ts"
   - "projects/praxis-dynamic-fields/src/lib/components/material-file-upload/material-file-upload.component.ts"
   - "projects/praxis-dynamic-fields/src/lib/base/simple-base-input.component.ts"
-source_of_truth_last_verified: "2026-03-06"
-last_updated: "2026-03-06"
+source_of_truth_last_verified: "2026-06-24"
+last_updated: "2026-06-24"
 toc: true
 sidebar: true
 tags:
@@ -149,10 +149,14 @@ Nao ha paths experimentais confirmados no contrato publico desta revisao.
 | `metadata.hint` | string | false | n/a | component-defined | Partial; verify per source_of_truth. |
 | `metadata.placeholder` | string | false | n/a | component-defined | Partial; verify per source_of_truth. |
 | `metadata.validators.*` | object | false | n/a | component-defined | Partial; verify per source_of_truth. |
-| `metadata.accept` | string | false | n/a | component-defined | Partial; verify per source_of_truth. |
-| `metadata.multiple` | boolean | false | n/a | component-defined | Partial; verify per source_of_truth. |
-| `metadata.maxFileSize` | number | false | n/a | component-defined | Partial; verify per source_of_truth. |
+| `metadata.accept` | string | false | n/a | comma-separated extensions or MIME patterns | Active; applied to native input and local file validation. |
+| `metadata.multiple` | boolean | false | `false` | boolean | Active; selected value is `File[]` when true and `File | null` otherwise. |
+| `metadata.maxFileSize` | number | false | n/a | positive byte count | Active; rejects selected files above the configured limit. |
+| `metadata.maxFiles` | number | false | n/a | positive integer | Active; rejects selections above the configured number of files. |
 | `metadata.allowedTypes` | string[] | false | n/a | component-defined | Partial; verify per source_of_truth. |
+| `metadata.imagePreview` | boolean | false | `false` | boolean | Active; renders local image preview for selected image files. |
+| `metadata.preview` | string | false | n/a | `image` | Active; `image` is an alias for local image preview. |
+| `metadata.previewAlt` | string | false | localized fallback | component-defined | Active; accessible alt text for the local preview image. |
 
 ### Input bindings (inbound data)
 
@@ -268,12 +272,13 @@ Em conflito entre alias legado e path canonico, priorizar path canonico e regist
 ### Preserved technical reference (normalized from previous revision)
 
 ### 1. Visao Geral e Quando Usar
-`pdx-material-file-upload` e um upload basico (placeholder funcional) com `<input type="file">` simples e integracao CVA.
+`pdx-material-file-upload` e um upload basico de campo com `<input type="file">`, integracao CVA, validacao local de tipo/tamanho e preview local de imagem.
 
 Use quando precisar:
 - prototipar upload rapido no form;
-- capturar um unico arquivo selecionado;
-- evoluir depois para fluxo corporativo completo (preview/chunk/validacoes avancadas).
+- capturar um arquivo selecionado ou uma lista curta de arquivos;
+- mostrar preview local para fluxos de foto/avatar antes da persistencia;
+- delegar persistencia, presign, progresso, conflito e storage governado para a camada canonica de upload.
 
 ### 2. API do Componente (Inputs/Outputs)
 | Propriedade | Tipo | Padrao | Obrigatorio | Comportamento |
@@ -283,7 +288,7 @@ Use quando precisar:
 | `disabledMode` | `boolean` | `false` | Nao | Sobrescreve disabled no host. |
 | `visible` | `boolean` | `true` | Nao | Controla exibicao no host. |
 | `presentationMode` | `boolean` | `false` | Nao | Modo apresentacao sem edicao. |
-| `valueChange` | `File \| null` | - | Output base input | Arquivo selecionado no input. |
+| `valueChange` | `File \| File[] \| null` | - | Output base input | Arquivo selecionado no input; quando `multiple=true`, emite array. |
 
 ### 3. Matriz de Cobertura JSON (Completa)
 #### 3.1 Campos especificos do componente
@@ -294,25 +299,29 @@ Use quando precisar:
 | `metadata.hint` | `string` | Ativo | Mensagem de apoio quando sem erro. |
 | `metadata.placeholder` | `string` | Parcial | `setFileUploadMetadata` remove placeholder do estado efetivo. |
 | `metadata.validators.*` | `object` | Parcial | Validacoes basicas do `SimpleBaseInput` podem atuar no control, sem parser de arquivo dedicado. |
-| `metadata.accept` | `string` | Declared-only | Nao aplicado ao atributo `accept` no input atual. |
-| `metadata.multiple` | `boolean` | Declared-only | Input atual usa apenas o primeiro arquivo selecionado. |
-| `metadata.maxFileSize` | `number` | Declared-only | Nao ha validacao de tamanho especifica no componente. |
+| `metadata.accept` | `string` | Ativo | Aplicado ao atributo `accept` e validado localmente por extensao/MIME antes de atualizar o control. |
+| `metadata.multiple` | `boolean` | Ativo | Permite selecionar varios arquivos e atualiza o valor como `File[]`. |
+| `metadata.maxFileSize` | `number` | Ativo | Rejeita arquivos acima do limite em bytes antes de atualizar o control. |
+| `metadata.maxFiles` | `number` | Ativo | Rejeita selecoes acima da quantidade maxima configurada. |
 | `metadata.allowedTypes` | `string[]` | Declared-only | Nao ha filtro dedicado por tipo no componente atual. |
+| `metadata.imagePreview` | `boolean` | Ativo | Mostra preview local para o primeiro arquivo de imagem selecionado. |
+| `metadata.preview` | `'image'` | Ativo | Alias declarativo para habilitar preview local de imagem. |
+| `metadata.previewAlt` | `string` | Ativo | Texto alternativo do preview local. |
 
 #### 3.2 Campos herdados compartilhados (exaustivo)
 Contrato compartilhado de input base:
 - [pdx-base-input-runtime-contract.json-api.md](projects/praxis-dynamic-fields/src/lib/base/pdx-base-input-runtime-contract.json-api.md)
 
 Resumo de composicao deste componente:
-- `Ativo`: fluxo basico de selecao de um arquivo e bind no control.
+- `Ativo`: fluxo basico de selecao, bind no control, preview local de imagem e validacao local de tipo/tamanho/quantidade.
 - `Parcial`: placeholder e validacoes genericas do base.
-- `Declared-only`: capacidade avancada de upload ainda nao implementada.
+- `Declared-only`: politica avancada por `allowedTypes`.
 
 ### 4. Mapeamento de Comportamento
-- Selecao: ao `change`, pega `files[0]` e grava no control.
-- Valor: tipo `File | null`.
-- Renderizacao: label + input file + erro/hint.
-- Estado corporativo: componente se declara "placeholder" no proprio codigo.
+- Selecao: ao `change`, valida arquivos e grava `File` ou `File[]` no control.
+- Valor: `File | null` quando `multiple` esta ausente/falso; `File[]` quando `multiple=true`.
+- Renderizacao: label, input file, resumo da selecao, preview local de imagem, erro/hint e acao de limpar.
+- Persistencia corporativa: fora deste componente. Use `@praxisui/files-upload` para presign, progresso, conflito, retry e storage governado.
 
 ### 5. Exemplo Minimo (JSON + Uso)
 ```json
@@ -345,12 +354,30 @@ Uso: captura um arquivo unico para envio posterior.
 ```
 Uso: etapa inicial de upload, deixando validacoes profundas para API backend.
 
+### 6.1 Exemplo para troca de avatar (JSON + Uso)
+```json
+{
+  "componentId": "pdx-material-file-upload",
+  "metadata": {
+    "name": "profileImageFile",
+    "label": "Foto de perfil",
+    "controlType": "upload",
+    "accept": "image/*",
+    "maxFileSize": 4194304,
+    "maxFiles": 1,
+    "imagePreview": true,
+    "hint": "Escolha uma imagem para revisar antes de salvar a foto do perfil."
+  }
+}
+```
+Uso: combine este campo com `pdx-material-avatar` para preview/display e com a capability canonica de persistencia de arquivo para publicar a URL final consumida pelo avatar.
+
 ### 7. Troubleshooting e Armadilhas Comuns
-1. Esperar upload multiplo.
-Correcao: componente atual captura somente o primeiro arquivo.
+1. Esperar persistencia automatica.
+Correcao: este componente escolhe e valida localmente; persistencia pertence ao host ou a `@praxisui/files-upload`.
 
-2. Esperar filtro automatico por tipo/tamanho.
-Correcao: nao ha `accept`/validacao dedicada implementada nesta versao.
+2. Esperar crop/zoom.
+Correcao: preview local nao e editor de imagem. Crop deve nascer em contrato proprio de avatar/image authoring.
 
 3. Placeholder nao aparece.
 Correcao: `setFileUploadMetadata` remove placeholder explicitamente.
@@ -358,8 +385,8 @@ Correcao: `setFileUploadMetadata` remove placeholder explicitamente.
 4. Arquivo nao persiste no payload final.
 Correcao: verificar serializacao de `File` no host e estrategia de envio multipart.
 
-5. Necessidade de preview/progresso/chunk.
-Correcao: esse renderer e baseline; implementar camada avancada para cenarios enterprise.
+5. Necessidade de progresso/chunk/presign.
+Correcao: usar `@praxisui/files-upload`, que e a fronteira canonica de upload operacional.
 
 ### 8. Cross-links
 - `projects/praxis-dynamic-fields/src/lib/base/pdx-base-input-runtime-contract.json-api.md`
@@ -388,10 +415,14 @@ Correcao: esse renderer e baseline; implementar camada avancada para cenarios en
 | `metadata.hint` | string | false | n/a | Partial | See Detailed API reference. |
 | `metadata.placeholder` | string | false | n/a | Partial | See Detailed API reference. |
 | `metadata.validators.*` | object | false | n/a | Partial | See Detailed API reference. |
-| `metadata.accept` | string | false | n/a | Partial | See Detailed API reference. |
-| `metadata.multiple` | boolean | false | n/a | Partial | See Detailed API reference. |
-| `metadata.maxFileSize` | number | false | n/a | Partial | See Detailed API reference. |
+| `metadata.accept` | string | false | n/a | Active | Applied to native input and local type validation. |
+| `metadata.multiple` | boolean | false | `false` | Active | Emits `File[]` when true. |
+| `metadata.maxFileSize` | number | false | n/a | Active | Rejects files above the byte limit. |
+| `metadata.maxFiles` | number | false | n/a | Active | Rejects selections above the configured number of files. |
 | `metadata.allowedTypes` | string[] | false | n/a | Partial | See Detailed API reference. |
+| `metadata.imagePreview` | boolean | false | `false` | Active | Enables local image preview. |
+| `metadata.preview` | string | false | n/a | Active | `image` enables local image preview. |
+| `metadata.previewAlt` | string | false | localized fallback | Active | Accessible alt text for preview image. |
 
 ## Events reference (obrigatorio)
 

package/types/praxisui-dynamic-fields.d.ts

@@ -241,6 +241,18 @@ interface PraxisDynamicFieldsI18nOverrides {
     validation?: {
         genericFailed?: PraxisDynamicFieldText;
     };
+    fileUpload?: {
+        emptySummary?: PraxisDynamicFieldText;
+        multipleSummary?: PraxisDynamicFieldText;
+        clearSelection?: PraxisDynamicFieldText;
+        clearSelectionAriaLabel?: PraxisDynamicFieldText;
+        selectedSummaryAriaLabel?: PraxisDynamicFieldText;
+        previewAlt?: PraxisDynamicFieldText;
+        sizeUnitBytes?: PraxisDynamicFieldText;
+        sizeUnitKb?: PraxisDynamicFieldText;
+        sizeUnitMb?: PraxisDynamicFieldText;
+        sizeUnitGb?: PraxisDynamicFieldText;
+    };
     select?: {
         loadSchemaError?: PraxisDynamicFieldText;
         loadOptionsError?: PraxisDynamicFieldText;
@@ -6068,17 +6080,22 @@ declare class MaterialSelectionListComponent extends SimpleBaseSelectComponent i
 }
 
 /**
- * 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.
  */
-declare class MaterialFileUploadComponent extends SimpleBaseInputComponent {
+declare class MaterialFileUploadComponent extends SimpleBaseInputComponent implements OnDestroy {
     readonlyMode: boolean;
     disabledMode: boolean;
     visible: boolean;
     presentationMode: boolean;
+    readonly selectedFiles: _angular_core.WritableSignal<File[]>;
+    readonly previewUrl: _angular_core.WritableSignal<string | null>;
+    private externalValueSyncSubscription;
+    readonly selectedSummaryText: _angular_core.Signal<string>;
+    readonly selectedDetailText: _angular_core.Signal<string>;
     /**
      * Updates the control value when the user selects a file.
      */
@@ -6089,12 +6106,41 @@ declare class MaterialFileUploadComponent extends SimpleBaseInputComponent {
     setFileUploadMetadata(metadata: ComponentMetadata): void;
     fileAccept(): string | null;
     allowsMultiple(): boolean;
+    imagePreviewEnabled(): boolean;
     isInteractionDisabled(): boolean;
+    clearSelectedFiles(options?: {
+        resetInput?: boolean;
+    }): void;
+    clearLabel(): string;
+    clearAriaLabel(): string;
+    selectedSummaryAriaLabel(): string;
+    fileInputDescribedBy(): string | null;
+    hintId(): string;
+    errorId(): string;
+    previewAltText(): string;
+    writeValue(value: unknown): void;
+    ngOnDestroy(): void;
     /**
      * CSS classes specific to the file upload wrapper.
      */
     protected getSpecificCssClasses(): string[];
+    protected onActiveControlChanged(previousControl: FormControl, currentControl: FormControl): void;
     private metadataRecord;
+    private updatePreview;
+    private clearPreview;
+    private validateSelectedFiles;
+    private isAcceptedFile;
+    private maxFileSize;
+    private maxFiles;
+    private applyFileError;
+    private clearFileErrors;
+    private syncSelectedFilesFromValue;
+    private extractFilesFromValue;
+    private isFile;
+    private isImageFile;
+    private hasKnownImageExtension;
+    private formatBytes;
+    private dynamicFieldsText;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<MaterialFileUploadComponent, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<MaterialFileUploadComponent, "pdx-material-file-upload", never, { "readonlyMode": { "alias": "readonlyMode"; "required": false; }; "disabledMode": { "alias": "disabledMode"; "required": false; }; "visible": { "alias": "visible"; "required": false; }; "presentationMode": { "alias": "presentationMode"; "required": false; }; }, {}, never, never, true, never>;
 }