@praxisui/files-upload

Praxis Files Upload

🔰 Exemplos / Quickstart

Para ver esta biblioteca em funcionamento em uma aplicação completa, utilize o projeto de exemplo (Quickstart):

• 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.

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

import { Component } from "@angular/core";
import { PraxisFilesUpload, FilesUploadConfig, FileMetadata } from "@praxisui/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.

<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.

{
  "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):

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:

{ 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:

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:

import { FILES_UPLOAD_TEXTS } 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",
    },
  },
];