@praxisui/files-upload 0.0.1

package/LICENSE

@@ -0,0 +1,7 @@
+This package is licensed under the Apache License, Version 2.0.
+
+For the full license text, see the repository root LICENSE file:
+../../LICENSE
+
+Apache License 2.0: https://www.apache.org/licenses/LICENSE-2.0
+

package/README.md

@@ -0,0 +1,162 @@
+# 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.
+
+## Component Overview
+
+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`).
+- `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.
+- `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.
+- `proximityChange: boolean` Proximity overlay visibility toggles.
+
+## Components
+
+### `PraxisFilesUpload`
+
+```ts
+import { Component } from "@angular/core";
+import { PraxisFilesUpload, FilesUploadConfig, FileMetadata } from "@praxis/files-upload";
+
+@Component({
+  standalone: true,
+  imports: [PraxisFilesUpload],
+  template: `<praxis-files-upload [config]="config" (uploadSuccess)="onSuccess($event)"></praxis-files-upload>`,
+})
+export class DemoComponent {
+  config: FilesUploadConfig = {
+    strategy: "auto",
+    ui: { showDropzone: true },
+  };
+
+  onSuccess(event: { file: FileMetadata }) {
+    console.log("uploaded", event.file);
+  }
+}
+```
+
+### `PdxFilesUploadFieldComponent`
+
+Wrapper for dynamic forms that implements `ControlValueAccessor` and emits either file metadata or the uploaded id according to the configured `valueMode`.
+
+```ts
+<form [formGroup]="form">
+  <pdx-material-files-upload formControlName="attachment" />
+</form>
+```
+
+## Configuration options
+
+The editor allows adjusting UI behavior, bulk parameters, limits, quotas, rate limit handling, headers and messages for individual error codes.
+
+- `strategy`: `direct` | `presign` | `auto` — `auto` tenta upload pré-assinado e recorre ao modo direto se a etapa de presign falhar.
+
+```json
+{
+  "ui": { "accept": ["image/png", "application/pdf"], "showMetadataForm": true },
+  "limits": { "maxFileSizeBytes": 1048576 },
+  "bulk": { "parallelUploads": 2, "retryCount": 3 },
+  "quotas": { "showQuotaWarnings": true },
+  "rateLimit": { "autoRetryOn429": true, "maxAutoRetry": 2 },
+  "headers": { "tenantHeader": "X-Tenant-Id" },
+  "messages": {
+    "successSingle": "Uploaded",
+    "errors": { "QUOTA_EXCEEDED": "Quota reached" }
+  }
+}
+```
+
+## Constraints
+
+Client-side constraints can be enforced via `config` and validated by built-in validators:
+
+- 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`
+- Count per batch: `limits.maxFilesPerBulk`
+- Total size per batch: `limits.maxBulkSizeBytes`
+
+Example (2 files max, 5 MB each, PNG/JPEG only):
+
+```ts
+const cfg: FilesUploadConfig = {
+  ui: { accept: ['image/png', 'image/jpeg'], showDropzone: true },
+  limits: { maxFileSizeBytes: 5 * 1024 * 1024, maxFilesPerBulk: 2 },
+};
+```
+
+## Services
+
+- `FilesApiClient` – performs direct or bulk uploads and requests presigned URLs.
+- `PresignedUploaderService` – posts files to presigned targets with headers and form fields.
+- `ConfigService` – retrieves effective backend configuration with ETag caching scoped by base URL and tenant/user headers.
+- `useEffectiveUploadConfig` – Angular composable exposing loading/data/error/context signals and a refetch method.
+
+## Validators
+
+- `acceptValidator`
+- `maxFileSizeValidator`
+- `maxFilesPerBulkValidator`
+- `maxBulkSizeValidator`
+
+## Error handling
+
+`ErrorMapperService` translates backend `ErrorCode` values 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:
+
+```ts
+{ provide: FILES_UPLOAD_ERROR_MESSAGES, useValue: { QUOTA_EXCEEDED: 'Limite atingido' } }
+```
+
+## Configuration persistence
+
+The configuration editor stores settings in `CONFIG_STORAGE` with fallback to `localStorage`, using the key `files-upload-config:<componentId>`.
+
+## 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.*`.
+
+As traduções padrão podem ser registradas com o objeto `FILES_UPLOAD_PT_BR`:
+
+```ts
+import { TranslateService } from '@ngx-translate/core';
+import { FILES_UPLOAD_PT_BR } from '@praxis/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 "@praxis/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",
+    },
+  },
+];
+```