@praxisui/files-upload 1.0.0-beta.61 → 1.0.0-beta.63

package/README.md

@@ -41,14 +41,19 @@ last_updated: "2026-03-07"
 
 # Praxis Files Upload
 
-## 🔰 Exemplos / Quickstart
+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.
 
-Para ver esta biblioteca em funcionamento em uma aplicação completa, utilize o projeto de exemplo (Quickstart):
+## Documentation
 
-- Repositório: https://github.com/codexrodrigues/praxis-ui-quickstart
-- O Quickstart demonstra a integração das bibliotecas `@praxisui/*` em um app Angular, incluindo instalação, configuração e uso em telas reais.
+- 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
 
-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.
+## 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
 
@@ -62,14 +67,104 @@ Inputs
 - `displayMode: 'full' | 'compact'` Controls UI density and overlays (default: `full`).
 
 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`
@@ -89,25 +184,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.
 
@@ -132,7 +241,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`
 
@@ -161,7 +270,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:
@@ -176,36 +285,26 @@ The configuration editor stores settings in `ASYNC_CONFIG_STORAGE`, using the ke
 
 ## 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.