@praxisui/files-upload 1.0.0-beta.8 → 3.0.0-beta.0

package/README.md

@@ -1,7 +1,62 @@
+---
+title: "Files Upload"
+slug: "files-upload-overview"
+description: "Visao geral do @praxisui/files-upload com upload direto ou presign, validacoes, i18n, persistencia de configuracao e integracao com backend Praxis."
+doc_type: "reference"
+document_kind: "component-overview"
+component: "files-upload"
+category: "components"
+audience:
+  - "frontend"
+  - "host"
+  - "architect"
+level: "intermediate"
+status: "active"
+owner: "praxis-ui"
+tags:
+  - "files-upload"
+  - "upload"
+  - "presign"
+  - "validation"
+  - "i18n"
+order: 37
+icon: "upload"
+toc: true
+sidebar: true
+search_boost: 0.95
+reading_time: 11
+estimated_setup_time: 20
+version: "1.0"
+related_docs:
+  - "host-files-upload-integration"
+  - "consumer-integration-quickstart"
+  - "host-integration-guide"
+keywords:
+  - "praxis files upload"
+  - "presigned upload"
+  - "upload config"
+  - "bulk upload"
+last_updated: "2026-03-07"
+---
+
 # Praxis Files Upload
 
 Components and services for integrating file uploads with the Praxis backend. Configuration is provided as JSON and can be edited at runtime through the Settings Panel.
 
+`enableCustomization` is opt-in. Hosts that want runtime settings/configuration must declare `[enableCustomization]="true"` explicitly.
+
+## Documentation
+
+- Official documentation: https://praxisui.dev
+- Quickstart reference app: https://github.com/codexrodrigues/praxis-ui-quickstart
+- Recommended for: enterprise upload flows with direct upload, presigned URLs, quotas and operational feedback
+
+## When to use
+
+- Implement file upload with operational feedback and quota-aware UX
+- Support direct and presigned upload strategies from the same component set
+- Keep upload configuration editable at runtime in Praxis-based hosts
+
 ## Component Overview
 
 Main component selector: `praxis-files-upload`
@@ -9,18 +64,110 @@ Main component selector: `praxis-files-upload`
 Inputs
 - `config: FilesUploadConfig | null` UI/limits/options for the upload flow.
 - `baseUrl?: string` Required to enable uploads (backend base URL for files API).
-- `componentId: string` Persistence key suffix for local config (default: `default`).
+- `filesUploadId: string` Required identifier for config persistence.
+- `componentInstanceId?: string` Optional instance key when rendering multiple uploads in the same route.
 - `displayMode: 'full' | 'compact'` Controls UI density and overlays (default: `full`).
+- `enableCustomization: boolean` Enables runtime customization/settings affordances (default: `false`).
 
 Outputs
-- `uploadSuccess: { file: FileMetadata }` Emitted per successful single upload.
-- `bulkComplete: BulkUploadResponse` Summary for batch uploads.
+- `uploadSuccess: FileMetadata` Emitted per successful single upload.
+- `bulkComplete: BulkUploadResponseData` Summary payload for batch uploads.
 - `error: ErrorResponse` Error information for failed requests.
 - `rateLimited: RateLimitInfo` Emits when 429 is detected (with reset hints).
 - `retry | download | copyLink | detailsOpened | detailsClosed: BulkUploadFileResult` Advanced list actions.
-- `pendingFilesChange: File[]` Current selected (pending) files.
+- `pendingStateChange: PendingFilesState` Current manual-selection state (`files`, `count`, `hasPending`).
 - `proximityChange: boolean` Proximity overlay visibility toggles.
 
+## Backend Contract
+
+`@praxisui/files-upload` consome o contrato final do backend Praxis sem camadas de compatibilidade.
+
+Success envelope:
+
+```json
+{
+  "status": "success",
+  "message": "Upload realizado com sucesso",
+  "timestamp": "2026-03-15T11:00:00Z",
+  "data": {
+    "originalFilename": "contract.pdf",
+    "serverFilename": "stored-contract.pdf",
+    "fileId": "f-123",
+    "fileSize": 1024,
+    "mimeType": "application/pdf",
+    "uploadTimestamp": "2026-03-15T11:00:00Z"
+  }
+}
+```
+
+Bulk success and partial success:
+
+```json
+{
+  "status": "partial_success",
+  "message": "Upload em lote processado com sucesso parcial",
+  "timestamp": "2026-03-15T11:00:00Z",
+  "data": {
+    "totalProcessed": 2,
+    "totalSuccess": 1,
+    "totalFailed": 1,
+    "overallSuccess": false,
+    "results": [
+      {
+        "fileName": "ok.pdf",
+        "status": "SUCCESS",
+        "file": {
+          "id": "f-123",
+          "fileName": "ok.pdf",
+          "contentType": "application/pdf",
+          "fileSize": 1024,
+          "uploadedAt": "2026-03-15T11:00:00Z",
+          "tenantId": "tenant-a",
+          "scanStatus": "PENDING"
+        }
+      },
+      {
+        "fileName": "bad.exe",
+        "status": "FAILED",
+        "error": {
+          "status": "failure",
+          "message": "Falha de validacao",
+          "errors": [
+            {
+              "code": "TIPO_ARQUIVO_INVALIDO",
+              "message": "Tipo de arquivo invalido."
+            }
+          ],
+          "traceId": "trace-1"
+        }
+      }
+    ]
+  }
+}
+```
+
+Error envelope:
+
+```json
+{
+  "status": "failure",
+  "message": "Falha de validacao",
+  "errors": [
+    {
+      "code": "QUOTA_EXCEEDED",
+      "message": "Quota reached."
+    }
+  ],
+  "timestamp": "2026-03-15T11:00:00Z",
+  "traceId": "trace-1"
+}
+```
+
+Leituras feitas pelo componente:
+- upload simples: `data`
+- upload em lote: `data.results`
+- erro: `errors[0]`
+
 ## Components
 
 ### `PraxisFilesUpload`
@@ -32,7 +179,7 @@ import { PraxisFilesUpload, FilesUploadConfig, FileMetadata } from "@praxisui/fi
 @Component({
   standalone: true,
   imports: [PraxisFilesUpload],
-  template: `<praxis-files-upload [config]="config" (uploadSuccess)="onSuccess($event)"></praxis-files-upload>`,
+  template: `<praxis-files-upload filesUploadId="docs-upload" [config]="config" (uploadSuccess)="onSuccess($event)"></praxis-files-upload>`,
 })
 export class DemoComponent {
   config: FilesUploadConfig = {
@@ -40,25 +187,39 @@ export class DemoComponent {
     ui: { showDropzone: true },
   };
 
-  onSuccess(event: { file: FileMetadata }) {
-    console.log("uploaded", event.file);
+  onSuccess(file: FileMetadata) {
+    console.log("uploaded", file);
   }
 }
 ```
 
 ### `PdxFilesUploadFieldComponent`
 
-Wrapper for dynamic forms that implements `ControlValueAccessor` and emits either file metadata or the uploaded id according to the configured `valueMode`.
+Wrapper for dynamic forms that implements `ControlValueAccessor` and resolves the field value according to the configured `valueMode`.
 
 ```ts
 <form [formGroup]="form">
-  <pdx-material-files-upload formControlName="attachment" />
+  <pdx-material-files-upload
+    formControlName="attachment"
+    valueMode="metadata[]"
+  />
 </form>
 ```
 
+Array modes keep a stable shape in both single and bulk uploads:
+- `metadata[]` always resolves to `FileMetadata[]`
+- `id[]` always resolves to `string[]`
+
 ## Configuration options
 
-The editor allows adjusting UI behavior, bulk parameters, limits, quotas, rate limit handling, headers and messages for individual error codes.
+The editor allows adjusting the config in separated responsibility groups:
+
+- `ui`: visual presentation and interaction only
+- `limits`: client-side validation and local flow guards
+- `options`: backend-facing upload options serialized into the request
+- `bulk`: execution policy such as retries and parallelism
+- `quotas`, `rateLimit`, `messages`: feedback and UX behavior
+- `headers`: host-specific contextual header naming
 
 - `strategy`: `direct` | `presign` | `auto` — `auto` tenta upload pré-assinado e recorre ao modo direto se a etapa de presign falhar.
 
@@ -83,7 +244,7 @@ Client-side constraints can be enforced via `config` and validated by built-in v
 
 - Types: `ui.accept: string[]` (e.g., `['image/png','application/pdf']`)
 - Extensions/MIME: `options.allowedExtensions`, `options.acceptMimeTypes`
-- Size per file: `limits.maxFileSizeBytes` (bytes) or `limits.maxUploadSizeMb`
+- Size per file: `limits.maxFileSizeBytes` (bytes) or `options.maxUploadSizeMb`
 - Count per batch: `limits.maxFilesPerBulk`
 - Total size per batch: `limits.maxBulkSizeBytes`
 
@@ -112,7 +273,7 @@ const cfg: FilesUploadConfig = {
 
 ## Error handling
 
-`ErrorMapperService` translates backend `ErrorCode` values into user-facing messages and exposes rate limit information.
+`ErrorMapperService` translates backend error codes from `errors[0]` into user-facing messages and exposes rate limit information.
 
 Default messages are provided in Portuguese but can be overridden globally by
 providing the `FILES_UPLOAD_ERROR_MESSAGES` injection token:
@@ -123,40 +284,30 @@ providing the `FILES_UPLOAD_ERROR_MESSAGES` injection token:
 
 ## Configuration persistence
 
-The configuration editor stores settings in `CONFIG_STORAGE` with fallback to `localStorage`, using the key `files-upload-config:<componentId>`.
+The configuration editor stores settings in `ASYNC_CONFIG_STORAGE`, using the key `files-upload-config:<component_id>`. Provide an async storage implementation (for example, `LocalStorageAsyncAdapter` for local persistence or `ApiConfigStorage` for remote persistence).
 
 ## Internationalização
 
-Todas as mensagens do componente são fornecidas em Português Brasileiro. Para cenários multilíngues, o componente integra-se opcionalmente ao `@ngx-translate/core` e expõe um conjunto de chaves `praxis.filesUpload.*`.
+`@praxisui/files-upload` usa a infraestrutura oficial de i18n do `@praxisui/core`.
 
-As traduções padrão podem ser registradas com o objeto `FILES_UPLOAD_PT_BR`:
+As chaves internas da lib vivem no namespace `praxis.filesUpload.*` e podem ser registradas com `providePraxisFilesUploadI18n(...)`:
 
 ```ts
-import { TranslateService } from '@ngx-translate/core';
-import { FILES_UPLOAD_PT_BR } from '@praxisui/files-upload';
-
-constructor(private translate: TranslateService) {
-  translate.setTranslation('pt-BR', FILES_UPLOAD_PT_BR, true);
-}
-```
-
-Se nenhuma tradução estiver disponível, o componente utiliza o token `FILES_UPLOAD_TEXTS` como fallback. Para sobrescrever os textos manualmente:
-
-```ts
-import { FILES_UPLOAD_TEXTS } from "@praxisui/files-upload";
+import { providePraxisFilesUploadI18n } from '@praxisui/files-upload';
 
 providers: [
-  {
-    provide: FILES_UPLOAD_TEXTS,
-    useValue: {
-      settingsAriaLabel: "Open settings",
-      dropzoneLabel: "Drag files here or",
-      dropzoneButton: "select",
-      conflictPolicyLabel: "Conflict policy",
-      metadataLabel: "Metadata (JSON)",
-      progressAriaLabel: "Upload progress",
-      rateLimitBanner: "Rate limit exceeded. Try again at",
+  providePraxisFilesUploadI18n({
+    locale: 'en-US',
+    fallbackLocale: 'pt-BR',
+    dictionaries: {
+      'en-US': {
+        'praxis.filesUpload.dropzoneLabel': 'Drag files or',
+      },
     },
-  },
+  }),
 ];
 ```
+
+O caminho recomendado para hosts e libs consumidoras e usar esse provider ou a infraestrutura compartilhada do `PraxisI18nService`.
+
+`FILES_UPLOAD_TEXTS` e `TRANSLATE_LIKE` permanecem exportados apenas como camada transitoria de compatibilidade. Quando usados, eles funcionam como fallback para chaves planas da lib, inclusive chaves novas como `fieldPendingSummary` e overrides legados baseados em `instant(...)` ou `t(...)`. Novo codigo nao deve depender desses tokens, e eles devem ser tratados como legado/deprecado.