@flusys/ng-storage 4.0.2 → 4.1.0

package/README.md

@@ -1,562 +1,435 @@
-# Storage Package Guide
+# @flusys/ng-storage
 
-> **Package:** `@flusys/ng-storage`
-> **Version:** 4.0.2
-> **Type:** File storage management with upload, folder organization, and multi-provider support
+> File storage UI library for the FLUSYS Angular platform — file upload, folder management, file browser, presigned URL fetching, and provider adapter registration.
 
----
-
-## Overview
+[![npm version](https://img.shields.io/npm/v/@flusys/ng-storage.svg)](https://www.npmjs.com/package/@flusys/ng-storage)
+[![Angular](https://img.shields.io/badge/Angular-21-red.svg)](https://angular.io)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 
-`@flusys/ng-storage` provides complete file storage management:
+---
 
-- **File Upload** - Single and multiple file uploads with image compression
-- **File Manager** - CRUD operations for file metadata with presigned URLs
-- **Folder Management** - Folder organization for files
-- **Storage Configs** - Multi-provider configurations (AWS S3, Azure Blob, SFTP, Local)
-- **Company Scoping** - Automatic company-scoped queries (when enabled)
-- **Permission Guards** - All routes protected by permission guards
-- **Lazy Loading** - All page components are lazy-loaded via routes
+## Table of Contents
+
+- [Overview](#overview)
+- [Features](#features)
+- [Compatibility](#compatibility)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Module Registration](#module-registration)
+- [File URL Rule](#file-url-rule)
+- [Services](#services)
+  - [FileManagerApiService](#filemanagerapiservice)
+  - [FolderApiService](#folderapiservice)
+  - [UploadService](#uploadservice)
+- [Components](#components)
+  - [FileManagerComponent](#filemanagercomponent)
+  - [FileSelectorDialogComponent](#fileselectordialogcomponent)
+  - [FileUploaderComponent](#fileuploadercomponent)
+- [Storage Routes](#storage-routes)
+- [File Location Enum](#file-location-enum)
+- [API Endpoints](#api-endpoints)
+- [Configuration Reference](#configuration-reference)
+- [Troubleshooting](#troubleshooting)
+- [License](#license)
 
-### Package Hierarchy
+---
 
-```
-@flusys/ng-core           <- Foundation (BaseApiService, APP_CONFIG, getDefaultStorageConfigId)
-        |
-@flusys/ng-shared         <- Shared utilities (ApiResourceService, IBaseEntity, BaseListPage)
-        |
-@flusys/ng-layout         <- Layout (LAYOUT_AUTH_STATE for company context)
-        |
-@flusys/ng-storage        <- File storage (THIS PACKAGE)
-```
+## Overview
 
-### Company Context
+`@flusys/ng-storage` provides the complete file management UI for FLUSYS applications. It supports all four storage backends (Local, S3, Azure Blob, SFTP) transparently — the backend generates the correct presigned URLs for each provider.
 
-Storage components use `LAYOUT_AUTH_STATE` from `@flusys/ng-layout` for company context. This follows the Provider Interface Pattern - ng-storage depends on ng-layout's abstraction, not ng-auth directly. See `BaseStoragePage` class for implementation.
+**Critical rule:** Never construct file URLs manually. Always use `FileUrlService` (from `ng-shared`) or the `FILE_PROVIDER` token. The backend generates presigned URLs that are provider-agnostic and access-controlled.
 
 ---
 
-## Package Architecture
+## Features
 
-```
-ng-storage/
-├── adapters/
-│   └── profile-upload-provider.adapter.ts  # Profile upload adapter for ng-auth
-├── enums/
-│   ├── file-location.enum.ts     # FileLocationEnum, ImageFormat
-│   └── public-api.ts
-├── interfaces/
-│   ├── file-manager.interface.ts  # IFileManager, ICreateFileManagerDto, IUpdateFileManagerDto
-│   ├── folder.interface.ts        # IFolder, ICreateFolderDto, IUpdateFolderDto
-│   ├── storage-config.interface.ts # IStorageConfig, provider-specific configs
-│   ├── upload.interface.ts        # IUploadOptionsDto, IUploadedFileInfo
-│   └── public-api.ts
-├── providers/
-│   └── storage-providers.ts       # provideStorageProviders()
-├── services/
-│   ├── file-manager-api.service.ts   # File metadata CRUD + presigned URLs
-│   ├── folder-api.service.ts         # Folder CRUD
-│   ├── storage-config-api.service.ts # Storage config CRUD
-│   └── upload.service.ts             # File upload/delete operations
-├── utils/
-│   ├── base-storage-page.ts       # BaseStoragePage, BaseStorageListPage base classes
-│   ├── storage-utils.ts           # Utility functions (icons, labels, formatters)
-│   └── public-api.ts
-├── pages/
-│   ├── storage-container/
-│   │   └── storage-container.component.ts  # Tab container (Files, Folders, Configs)
-│   ├── file-manager/
-│   │   ├── file-manager-list.component.ts
-│   │   └── file-manager-form.component.ts
-│   ├── folder/
-│   │   ├── folder-list.component.ts
-│   │   └── folder-form.component.ts
-│   └── storage-config/
-│       ├── storage-config-list.component.ts
-│       └── storage-config-form.component.ts
-├── routes/
-│   └── storage.routes.ts
-└── public-api.ts
-```
+- ✅ File browser with folder navigation
+- ✅ Drag-and-drop upload with progress
+- ✅ Multi-file selection dialog (`FileSelectorDialogComponent`)
+- ✅ Image preview thumbnails
+- ✅ Download and delete actions
+- ✅ `UploadService` — typed multi-part file upload
+- ✅ `provideStorageProviders()` — registers `FILE_PROVIDER` for shared components
+- ✅ Presigned URL fetching via `FileUrlService`
+- ✅ Support for `LOCAL`, `S3`, `AZURE`, `SFTP` backends
 
 ---
 
-## Route Integration
-
-### Adding Storage Routes
+## Compatibility
 
-```typescript
-// app.routes.ts
-export const routes: Routes = [
-  {
-    path: 'storage',
-    loadChildren: () =>
-      import('@flusys/ng-storage').then((m) => m.STORAGE_ROUTES),
-  },
-];
-```
-
-### Route Structure
+| Package | Version |
+|---------|---------|
+| Angular | 21+ |
+| @flusys/ng-core | 4.x |
+| @flusys/ng-shared | 4.x |
 
-All routes are wrapped by `StorageContainerComponent` which provides tab navigation (Files, Folders, Configs). Routes are protected by permission guards.
+---
 
-| Path | Component | Permission |
-|------|-----------|------------|
-| `/storage` | StorageContainerComponent | - |
-| `/storage/files` | FileManagerListComponent | `FILE_PERMISSIONS.READ` |
-| `/storage/files/new` | FileManagerFormComponent | `FILE_PERMISSIONS.CREATE` |
-| `/storage/files/:id` | FileManagerFormComponent | `FILE_PERMISSIONS.UPDATE` |
-| `/storage/folders` | FolderListComponent | `FOLDER_PERMISSIONS.READ` |
-| `/storage/folders/new` | FolderFormComponent | `FOLDER_PERMISSIONS.CREATE` |
-| `/storage/folders/:id` | FolderFormComponent | `FOLDER_PERMISSIONS.UPDATE` |
-| `/storage/configs` | StorageConfigListComponent | `STORAGE_CONFIG_PERMISSIONS.READ` |
-| `/storage/configs/new` | StorageConfigFormComponent | `STORAGE_CONFIG_PERMISSIONS.CREATE` |
-| `/storage/configs/:id` | StorageConfigFormComponent | `STORAGE_CONFIG_PERMISSIONS.UPDATE` |
+## Installation
 
-Default redirect: `/storage` -> `/storage/files`
+```bash
+npm install @flusys/ng-storage @flusys/ng-core @flusys/ng-shared
+```
 
 ---
 
-## Enums
+## Quick Start
 
-### FileLocationEnum
-
-Storage provider types (matches backend).
+### 1. Enable Storage in Config
 
 ```typescript
-enum FileLocationEnum {
-  LOCAL = 'local',
-  AWS = 'aws',
-  AZURE = 'azure',
-  SFTP = 'sftp',
-}
+// environments/environment.ts
+export const environment = {
+  services: {
+    storage: { enabled: true },
+  },
+};
 ```
 
-### ImageFormat
-
-Image compression output formats.
+### 2. Register Storage Providers
 
 ```typescript
-enum ImageFormat {
-  ORIGINAL = 'original',
-  JPEG = 'jpeg',
-  PNG = 'png',
-  WEBP = 'webp',
-}
+// app.config.ts
+import { provideStorageProviders } from '@flusys/ng-storage';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    ...provideStorageProviders(),
+    // Provides: FILE_PROVIDER (IFileProvider) — used by FileSelectorDialogComponent, FileUrlService
+  ],
+};
 ```
 
----
-
-## Interfaces
-
-### Upload
+### 3. Add Storage Routes (Optional)
 
 ```typescript
-interface IUploadOptionsDto {
-  storageConfigId?: string;  // Storage config to use (uses default if not set)
-  folderPath?: string;       // Target folder path
-  maxWidth?: number;         // Image max width (default: 1280)
-  maxHeight?: number;        // Image max height (default: 1280)
-  quality?: number;          // Image quality 1-100 (default: 85)
-  format?: ImageFormat;      // Output format
-  compress?: boolean;        // Enable compression (default: true)
-}
+// app.routes.ts
+import { STORAGE_ROUTES } from '@flusys/ng-storage';
 
-interface IUploadedFileInfo {
-  name: string;              // Original filename
-  key: string;               // Storage key/path
-  size: number;              // File size in bytes
-  contentType: string;       // MIME type
-  location?: string;         // Storage location (optional)
-  storageConfigId?: string;  // Config used for upload (optional)
-}
+export const routes: Routes = [
+  {
+    path: 'storage',
+    loadChildren: () => STORAGE_ROUTES,
+  },
+];
 ```
 
-### File Manager
+---
 
-```typescript
-interface IFileManager extends IBaseEntity {
-  name: string;
-  contentType: string;
-  size: string;                      // In KB (string)
-  key: string;                       // File key/path in storage
-  url: string | null;                // Presigned URL (regenerated by backend)
-  location: FileLocationEnum;
-  storageConfigId: string | null;
-  providerName?: string;             // Storage config name (enriched from storage_config table)
-  expiresAt: Date | null;            // URL expiration time
-  isPrivate: boolean;
-  companyId?: string;                // Only in company mode
-  folderId?: string | null;
-}
+## Module Registration
 
-interface ICreateFileManagerDto {
-  name: string;
-  key: string;
-  size: string;
-  contentType: string;
-  isPrivate: boolean;
-  folderId?: string;
-  storageConfigId?: string;
-  location?: FileLocationEnum;
-}
+### `provideStorageProviders()`
 
-interface IUpdateFileManagerDto {
-  id: string;
-  name?: string;
-  isPrivate?: boolean;
-  folderId?: string | null;
-}
+Registers the storage adapter against the `FILE_PROVIDER` token from `ng-shared`:
+
+```typescript
+import { provideStorageProviders } from '@flusys/ng-storage';
 
-// For fetching files with valid presigned URLs
-interface IGetFilesRequestDto { id: string; }
-interface IFilesResponseDto { id: string; name: string; contentType: string; url: string; }
+providers: [
+  ...provideStorageProviders(),
+]
 ```
 
-### Folder
+This enables:
+- `FileSelectorDialogComponent` (from `ng-shared`) to list/browse files
+- `FileUrlService.fetchSingleFileUrl()` to work correctly
+- `HasPermissionDirective` to show storage-gated content
 
-```typescript
-interface IFolder extends IBaseEntity {
-  name: string;
-  slug: string;              // URL-friendly name
-  companyId?: string | null;
-}
+---
 
-interface ICreateFolderDto { name: string; }
-interface IUpdateFolderDto extends Partial<ICreateFolderDto> { id: string; }
-```
+## File URL Rule
 
-### Storage Config
+**CRITICAL:** Never construct file URLs manually. The backend handles URL generation for all storage providers (Local, S3, Azure, SFTP) including presigned URL rotation.
 
 ```typescript
-interface IStorageConfig extends IBaseEntity {
-  name: string;
-  storage: FileLocationEnum;
-  config: Record<string, unknown>;   // Provider-specific configuration
-  isActive: boolean;                 // Whether config is active and usable
-  isDefault: boolean;                // Set as default configuration
-  companyId?: string | null;
-}
+// ❌ WRONG — breaks with S3, Azure, SFTP
+const url = `${apiBaseUrl}/uploads/${fileId}`;
+const url = `https://my-bucket.s3.amazonaws.com/${path}`;
 
-interface ICreateStorageConfigDto {
-  name: string;
-  storage: FileLocationEnum;
-  config: Record<string, unknown>;
-  isActive?: boolean;
-  isDefault?: boolean;
-}
+// ✅ CORRECT — always use FileUrlService
+import { FileUrlService } from '@flusys/ng-shared';
 
-interface IUpdateStorageConfigDto extends Partial<ICreateStorageConfigDto> {
-  id: string;
-}
+const file = await this.fileUrlService.fetchSingleFileUrl(fileId);
+const url = file?.url ?? null; // Presigned, access-controlled, provider-agnostic
 ```
 
-### Provider-Specific Configs
-
-These define the shape of `IStorageConfig.config` for each provider:
-
-| Interface | Required Fields | Optional Fields |
-|-----------|-----------------|-----------------|
-| `IAwsS3Config` | `region`, `bucket`, `accessKeyId`, `secretAccessKey` | `endpoint` (custom S3-compatible) |
-| `IAzureBlobConfig` | `accountName`, `accountKey`, `containerName` | - |
-| `ISftpConfig` | `host`, `port`, `username`, `basePath` | `password`, `privateKey` |
-| `ILocalStorageConfig` | `basePath` | - |
+**Why backend URLs:**
+- S3/Azure require presigned URLs that expire
+- URLs are access-controlled (user must have permission)
+- Works transparently across all 4 storage providers
+- Automatic URL refresh on expiry
 
 ---
 
 ## Services
 
-All services are `providedIn: 'root'`. Company scoping is automatic when the company feature is enabled.
-
-### UploadService
-
-Handles file upload and deletion. Extends `BaseApiService` (from ng-core) with base path `/storage`.
+### FileManagerApiService
 
-**Methods:**
+Typed API client for file management operations:
 
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| `uploadSingleFile(file, options?)` | `POST /storage/upload/single-file` | Upload single file |
-| `uploadMultipleFiles(files, options?)` | `POST /storage/upload/multiple-file` | Upload multiple files (max 50) |
-| `uploadAndRegister(file, options?)` | Combined | Upload file and create file manager record |
-| `deleteSingleFile(key, storageConfigId?)` | `POST /storage/upload/delete-single-file` | Delete single file from storage |
-| `deleteMultipleFiles(keys, storageConfigId?)` | `POST /storage/upload/delete-multiple-file` | Delete multiple files |
-| `getFileUrl(key)` | `GET /storage/upload/file/:key` | Get direct file download URL |
-| `getDefaultConfigId()` | - | Get default storage config ID from APP_CONFIG |
+```typescript
+import { FileManagerApiService } from '@flusys/ng-storage';
 
-**Upload options** are sent as query parameters. **Storage Config Resolution:** Uses `storageConfigId` from options if provided, otherwise falls back to `getDefaultConfigId()` from APP_CONFIG. See Usage Examples for code samples.
+@Injectable({ ... })
+export class MyService {
+  private fileApi = inject(FileManagerApiService);
 
-### FileManagerApiService
+  getFiles(folderId?: string): Observable<IListResponse<IFile>> {
+    return this.fileApi.getAll({ filters: { folderId } });
+  }
 
-File metadata CRUD. Extends `ApiResourceService<IUpdateFileManagerDto, IFileManager>` with endpoint `/storage/file-manager`.
+  getFileUrls(fileIds: string[]): Observable<ISingleResponse<IFileWithUrl[]>> {
+    return this.fileApi.getFiles(fileIds);
+  }
 
-**Inherited CRUD:** `insert`, `update`, `findById`, `getAll`, `delete` (and `*Async` variants)
+  deleteFile(id: string): Observable<IMessageResponse> {
+    return this.fileApi.delete(id);
+  }
+}
+```
 
-**Additional methods:**
+**FileManagerApiService Methods:**
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| `getFiles(fileIds: string[])` | `POST /storage/file-manager/get-files` | Get files with valid presigned URLs |
-| `createFile(dto: ICreateFileManagerDto)` | `POST /storage/file-manager/insert` | Create file record (Observable) |
-| `createFileAsync(dto: ICreateFileManagerDto)` | `POST /storage/file-manager/insert` | Create file record (Promise) |
-
-**Presigned URL pattern:** Always use `getFiles()` to get valid URLs. Backend regenerates expired presigned URLs for cloud storage. See Usage Examples.
+| `getAll(params)` | `POST /file-manager/get-all` | List files with pagination |
+| `getById(id)` | `POST /file-manager/get/:id` | Get file metadata |
+| `getFiles(ids[])` | `POST /file-manager/get-files` | Batch fetch with presigned URLs |
+| `delete(id)` | `POST /file-manager/delete` | Delete file |
+| `bulkDelete(ids[])` | `POST /file-manager/bulk-delete` | Delete multiple files |
+| `move(id, folderId)` | `POST /file-manager/move` | Move file to folder |
 
 ### FolderApiService
 
-Folder CRUD. Extends `ApiResourceService<ICreateFolderDto | IUpdateFolderDto, IFolder>` with endpoint `/storage/folder`. Standard CRUD operations only.
-
-### StorageConfigApiService
+Typed API client for folder management:
 
-Storage config CRUD. Extends `ApiResourceService<ICreateStorageConfigDto | IUpdateStorageConfigDto, IStorageConfig>` with endpoint `/storage/storage-config`. Standard CRUD operations only.
-
----
-
-## Base Classes
-
-Components extend shared base classes from `utils/base-storage-page.ts`:
-
-| Class | Extends | Purpose | Key Members |
-|-------|---------|---------|-------------|
-| `BaseStoragePage` | - | Form pages | `isLoading`, `showCompanyInfo`, `currentCompanyName`, `showSuccess()`, `showError()`, `navigateTo()` |
-| `BaseStorageListPage<T>` | `BaseListPage<T>` | List pages | `pageSize=50`, `totalRecords`, `currentCompanyName`, `getDeleteConfirmMessage()` |
-
-Both inject: `Router`, `MessageService`, `APP_CONFIG`, `LAYOUT_AUTH_STATE`
-
-**BaseStorageListPage inherits from BaseListPage:** `items`, `total`, `isLoading`, `currentPage`, `onPageChange()`, `getPaginationParams()`, `onCreate()`, `onEdit()`, `onDeleteAsync()`, `loadData()` (abstract), `getResourceRoute()` (abstract)
-
----
-
-## Components
-
-All components are standalone, use Angular 21 signal forms, and lazy-load via routes.
-
-### StorageContainerComponent
-
-Main container with tab navigation between Files, Folders, and Configs sections.
-
-**Selector:** `lib-storage-container`
-
-**Features:**
-- Tab navigation filtered by user permissions (via `PermissionValidatorService`)
-- Horizontal scroll without visible scrollbar (`scrollbar-hide`)
-- Dynamic subtitle based on visible tabs
-- Responsive padding: `p-2 sm:p-4`
-- Dark mode compatible (Tailwind theme classes)
-
-### List Components
-
-All list components extend `BaseStorageListPage<T>` with: lazy pagination (`p-table`), responsive columns (`hidden sm:table-cell`), company info display, delete confirmation (`ConfirmationService`), signal-based state (`isLoading`, `totalRecords`, `pageSize`, `currentPage`), and permission-based actions (`*hasPermission`). Responsive styling: titles `text-lg sm:text-xl`, buttons `w-full sm:w-auto`.
-
-#### FileManagerListComponent
-
-**Selector:** `lib-file-manager-list`
-
-**Features:**
-- File content type icons (image, video, audio, PDF, Word, Excel, generic)
-- Provider location tags with severity colors
-- View file: fetches presigned URL via `getFiles()`, opens in new tab (tracks loading with `viewingFileId` signal)
-- **Soft delete** (`type: 'delete'`) - recoverable | **Permanent delete** (`type: 'permanent'`) - irreversible
+```typescript
+import { FolderApiService } from '@flusys/ng-storage';
 
-#### FolderListComponent
+@Injectable({ ... })
+export class MyService {
+  private folderApi = inject(FolderApiService);
 
-**Selector:** `lib-folder-list`
+  getFolders(parentId?: string): Observable<IListResponse<IFolder>> {
+    return this.folderApi.getAll({ filters: { parentId } });
+  }
 
-Simple CRUD list with folder icon, name, slug, and created date columns.
+  createFolder(name: string, parentId?: string): Observable<ISingleResponse<IFolder>> {
+    return this.folderApi.insert({ name, parentId });
+  }
+}
+```
 
-#### StorageConfigListComponent
+**FolderApiService Methods:**
 
-**Selector:** `lib-storage-config-list`
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `getAll(params)` | `POST /folder/get-all` | List folders |
+| `getById(id)` | `POST /folder/get/:id` | Get folder |
+| `insert(dto)` | `POST /folder/insert` | Create folder |
+| `update(dto)` | `POST /folder/update` | Rename folder |
+| `delete(id)` | `POST /folder/delete` | Delete folder |
 
-Lists storage configurations with provider icons and tags.
+### UploadService
 
-### Form Components
+Handles multi-part file uploads with progress tracking:
 
-All form components share: Signal Forms with `form()` + `required()` validators, create/edit mode detection via `:id` route param, `effect()` + `toSignal(route.paramMap)` initialization, navigation back on save/cancel, computed validation, and consistent button styling (`Cancel: secondary outlined`, `Submit: primary`, order: Cancel → Submit, container: `flex justify-end gap-2 mt-4`).
+```typescript
+import { UploadService } from '@flusys/ng-storage';
+
+@Component({ ... })
+export class UploadComponent {
+  private uploadService = inject(UploadService);
+
+  uploadFile(file: File, folderId?: string): void {
+    this.uploadService.upload(file, { folderId }).subscribe({
+      next: (event) => {
+        if (event.type === 'progress') {
+          console.log(`Progress: ${event.percent}%`);
+        }
+        if (event.type === 'complete') {
+          console.log('Uploaded:', event.file);
+        }
+      },
+      error: (err) => console.error('Upload failed:', err),
+    });
+  }
+
+  uploadMultiple(files: File[]): void {
+    this.uploadService.uploadBatch(files).subscribe(results => {
+      console.log(`Uploaded ${results.length} files`);
+    });
+  }
+}
+```
 
-| Component | Selector | Form Fields | Notes |
-|-----------|----------|-------------|-------|
-| FileManagerForm | `lib-file-manager-form` | `id`, `name`, `isPrivate`, `folderId`, `storageConfigId` | PrimeNG file upload (50MB max), storage config required for upload, edit mode shows metadata only |
-| FolderForm | `lib-folder-form` | `id`, `name` | Simple name-only form |
-| StorageConfigForm | `lib-storage-config-form` | `id`, `name`, `storage`, `isActive`, `isDefault`, provider-specific fields | Dynamic fields based on provider; defaults: `storage: AWS`, `isActive: true`, `sftpPort: '22'` |
+**UploadService API:**
 
-**FileManagerForm Upload Flow:** 1) Upload file via `uploadSingleFile()` 2) Create metadata via `createFileAsync()`. Edit mode only calls `updateAsync()`.
+| Method | Description |
+|--------|-------------|
+| `upload(file, options?)` | Single file upload with progress events |
+| `uploadBatch(files, options?)` | Multiple file upload (sequential) |
+| `cancel(uploadId)` | Cancel in-progress upload |
 
 ---
 
-## Utility Functions
-
-The `utils/storage-utils.ts` file provides helper functions:
-
-| Function | Returns | Description |
-|----------|---------|-------------|
-| `getProviderLabel(storage)` | `string` | Display label: 'AWS S3', 'Azure Blob', 'SFTP', 'Local' |
-| `getProviderIcon(storage)` | `string` | Icon class: `pi pi-cloud`, `pi pi-server`, `pi pi-folder` |
-| `getProviderSeverity(storage)` | severity | Tag severity: `warn` (AWS), `info` (Azure), `contrast` (SFTP), `secondary` (Local) |
-| `getFileIcon(contentType)` | `string` | File icon based on MIME type (image, video, audio, pdf, word, excel, generic) |
-| `formatFileSize(bytes)` | `string` | Human readable: '256 KB', '1.5 MB', '2.3 GB' |
-
-**Constants:** `STORAGE_PROVIDERS` - Dropdown options array with `{ label, value }` for AWS S3, Azure Blob, SFTP, Local Storage.
+## Components
 
----
+### FileManagerComponent
 
-## Usage Examples
+Full-page file browser with folder tree, grid/list view, upload, and actions.
 
-### Upload a File
+```html
+<!-- Full file manager -->
+<flusys-file-manager />
 
-```typescript
-const response = await firstValueFrom(
-  this.uploadService.uploadSingleFile(file, {
-    storageConfigId: 'my-config-id', folderPath: 'images/avatars',
-    compress: true, maxWidth: 800, maxHeight: 800, quality: 80, format: ImageFormat.WEBP,
-  })
-);
-return response.success ? response.data : null;
+<!-- With pre-selected folder -->
+<flusys-file-manager [initialFolderId]="rootFolderId" />
 ```
 
-### Upload and Register (Combined)
-
-Use `uploadAndRegister` for a single call that uploads and creates the file manager record:
-
-```typescript
-const response = await firstValueFrom(
-  this.uploadService.uploadAndRegister(file, { compress: true, quality: 85, isPrivate: false, folderId: 'avatars-folder-id' })
-);
-return response.success ? response.data : null;
+Features:
+- Folder tree (left panel)
+- File grid with thumbnails (right panel)
+- Drag-and-drop upload zone
+- Right-click context menu (rename, move, delete)
+- Breadcrumb navigation
+- Search files
+
+### FileSelectorDialogComponent
+
+Dialog for selecting one or multiple files. Used by other packages (`ng-form-builder`, `ng-email`) to pick files.
+
+```html
+<flusys-file-selector-dialog
+  [visible]="showPicker"
+  [multiple]="true"
+  [accept]="'image/*'"
+  (fileSelected)="onFilesSelected($event)"
+  (cancel)="showPicker = false"
+/>
 ```
 
-### Get Files with Presigned URLs
-
-```typescript
-const response = await firstValueFrom(this.fileService.getFiles(['file-id-1', 'file-id-2']));
-// response.data → [{ id, name, contentType, url }]
+| Input | Type | Description |
+|-------|------|-------------|
+| `visible` | `boolean` | Show/hide dialog |
+| `multiple` | `boolean` | Allow multi-select (default: false) |
+| `accept` | `string` | MIME type filter |
+| `folderId` | `string` | Pre-open specific folder |
+
+| Output | Type | Description |
+|--------|------|-------------|
+| `fileSelected` | `IFile \| IFile[]` | Selected file(s) |
+| `cancel` | `void` | Dialog dismissed |
+
+### FileUploaderComponent
+
+Lightweight standalone upload component (without the full browser):
+
+```html
+<flusys-file-uploader
+  [multiple]="false"
+  [accept]="'image/jpeg,image/png'"
+  [maxSizeMb]="5"
+  [folderId]="profilePicturesFolderId"
+  (uploaded)="onAvatarUploaded($event)"
+/>
 ```
 
-### Delete Files
-
-| Mode | Type | Description |
-|------|------|-------------|
-| Soft delete | `type: 'delete'` | Marks as deleted (recoverable) |
-| Permanent delete | `type: 'permanent'` | Removes from storage provider (irreversible) |
+---
 
-```typescript
-await this.fileService.deleteAsync({ id: file.id, type: 'delete' });     // Soft
-await this.fileService.deleteAsync({ id: file.id, type: 'permanent' });  // Permanent
-```
+## Storage Routes
 
-### Create Storage Configuration
+Lazy-loaded pages for the full file manager:
 
 ```typescript
-await this.configService.insertAsync({
-  name: 'Production AWS S3',
-  storage: FileLocationEnum.AWS,
-  config: { region: 'us-east-1', bucket: 'my-bucket', accessKeyId: 'AKIA...', secretAccessKey: '...' },
-  isActive: true,
-  isDefault: true,
-});
-```
+import { STORAGE_ROUTES } from '@flusys/ng-storage';
 
----
-
-## Backend Integration
-
-All endpoints use **POST-only RPC** style (not REST). Base paths:
+{ path: 'storage', loadChildren: () => STORAGE_ROUTES }
+```
 
-| Service | Base Path | Standard CRUD |
-|---------|-----------|---------------|
-| Upload | `/storage/upload` | Custom methods (see Services section) |
-| FileManager | `/storage/file-manager` | `insert`, `get/:id`, `get-all`, `update`, `delete` + `get-files` |
-| Folder | `/storage/folder` | `insert`, `get/:id`, `get-all`, `update`, `delete` |
-| StorageConfig | `/storage/storage-config` | `insert`, `get/:id`, `get-all`, `update`, `delete` |
+| Route | Component | Description |
+|-------|-----------|-------------|
+| `/storage` | `FileManagerPageComponent` | Full file manager page |
+| `/storage/folder/:id` | `FileManagerPageComponent` | Open specific folder |
 
 ---
 
-## Best Practices
-
-### 1. Always Use Presigned URLs
-
-Never construct file URLs manually. Use `FileManagerApiService.getFiles()` or `FileUrlService` from ng-shared.
+## File Location Enum
 
 ```typescript
-// Wrong: const url = `${apiBaseUrl}/storage/${fileId}`;
-// Correct:
-const files = await firstValueFrom(this.fileService.getFiles([fileId]));
-const url = files.data?.[0]?.url ?? null;
-```
-
-### 2. Specify Storage Config for Multi-Provider Setups
+import { FileLocationEnum } from '@flusys/ng-storage';
 
-```typescript
-this.uploadService.uploadSingleFile(file, { storageConfigId: 'aws-media-bucket', folderPath: 'images' });
+enum FileLocationEnum {
+  LOCAL = 'LOCAL',
+  S3 = 'S3',
+  AZURE = 'AZURE',
+  SFTP = 'SFTP',
+}
 ```
 
-### 3. Compress Images for Web
+Use `FileLocationEnum` when filtering or categorizing files by their storage backend.
 
-```typescript
-{ compress: true, maxWidth: 1920, maxHeight: 1080, quality: 85, format: ImageFormat.WEBP }
-```
+---
 
-### 4. Provide Required Services at App Level
+## API Endpoints
 
-Provide `ConfirmationService` and `MessageService` in `app.config.ts` for dialogs and toasts.
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/file-manager/get-all` | List files with pagination |
+| POST | `/file-manager/get/:id` | Get file metadata |
+| POST | `/file-manager/get-files` | Batch fetch with presigned URLs |
+| POST | `/file-manager/upload` | Upload file (multipart) |
+| POST | `/file-manager/delete` | Delete file |
+| POST | `/file-manager/bulk-delete` | Delete multiple files |
+| POST | `/file-manager/move` | Move file to folder |
+| POST | `/folder/get-all` | List folders |
+| POST | `/folder/get/:id` | Get folder metadata |
+| POST | `/folder/insert` | Create folder |
+| POST | `/folder/update` | Rename folder |
+| POST | `/folder/delete` | Delete folder |
 
-### 5. Enable Storage in APP_CONFIG
+---
 
-```typescript
-services: { storage: { baseUrl: 'http://localhost:2002/storage', enabled: true } }
-```
+## Configuration Reference
 
-### 6. Responsive Design Patterns
+| Config Key | Type | Default | Description |
+|------------|------|---------|-------------|
+| `services.storage.enabled` | `boolean` | `false` | Enable storage module |
 
-| Pattern | Classes |
-|---------|---------|
-| Titles | `text-lg sm:text-xl` |
-| Buttons | `w-full sm:w-auto` |
-| Form grids | `grid grid-cols-1 md:grid-cols-2 gap-4` |
-| Table columns | `hidden sm:table-cell`, `hidden md:table-cell`, etc. |
-| Tab navigation | `scrollbar-hide flex overflow-x-auto` |
+The storage backend (LOCAL/S3/AZURE/SFTP) is configured server-side in `nestjs-storage`. The Angular client doesn't need to know which provider is active.
 
 ---
 
-## Provider Functions
+## Troubleshooting
 
-### provideStorageProviders()
+**File thumbnails don't load**
 
-Registers provider adapters that enable other packages (ng-auth) to access storage functionality without direct dependencies.
+Images are loaded via presigned URLs. Ensure `FileUrlService.fetchSingleFileUrl()` is used (not manual URL construction). Check the browser network tab — are the URLs returning 403?
 
-```typescript
-// app.config.ts - add to providers array
-...provideStorageProviders()
+**Upload fails with 413 Payload Too Large**
+
+The backend has a file size limit. Configure `maxBodySize` in `nestjs-storage` on the server. On the Angular side, validate client-side before upload:
+
+```html
+<flusys-file-uploader [maxSizeMb]="10" />
 ```
 
-**Registers:** `FILE_PROVIDER` → `FileProviderAdapter` (implements `IFileProvider` from ng-shared)
+**`No provider for FILE_PROVIDER`**
 
-**FileProviderAdapter features:**
-- `loadFiles(filter)` - Load files with filtering and pagination
-- `uploadFile(file, options)` - Upload a single file and register in file manager
-- `uploadMultipleFiles(files, options)` - Upload multiple files at once
-- `getFileUrls(fileIds)` - Get file URLs by IDs (for refreshing presigned URLs)
-- `loadFolders(filter)` - Load folders for folder selector
-- `loadStorageConfigs(filter)` - Load storage configs for config selector
+Add `provideStorageProviders()` to `app.config.ts` providers.
 
-**Usage:** `inject(FILE_PROVIDER, { optional: true })?.uploadFile(file, options)`
+**FileSelectorDialog is empty (no files)**
 
----
+Ensure the user has permission to list files (`file:read`) and the backend storage is configured. Check the network tab for errors on `POST /file-manager/get-all`.
 
-## Public API Exports
+**Files visible but download fails**
 
-| Category | Exports |
-|----------|---------|
-| Enums | `FileLocationEnum`, `ImageFormat` |
-| Interfaces | `IFileManager`, `ICreateFileManagerDto`, `IUpdateFileManagerDto`, `IGetFilesRequestDto`, `IFilesResponseDto`, `IFolder`, `ICreateFolderDto`, `IUpdateFolderDto`, `IStorageConfig`, `ICreateStorageConfigDto`, `IUpdateStorageConfigDto`, `IAwsS3Config`, `IAzureBlobConfig`, `ISftpConfig`, `ILocalStorageConfig`, `IUploadOptionsDto`, `IUploadedFileInfo` |
-| Utils | `getProviderLabel`, `getProviderIcon`, `getProviderSeverity`, `getFileIcon`, `formatFileSize`, `STORAGE_PROVIDERS`, `BaseStoragePage`, `BaseStorageListPage` |
-| Adapters | `FileProviderAdapter` |
-| Services | `FileManagerApiService`, `FolderApiService`, `StorageConfigApiService`, `UploadService` |
-| Routes | `STORAGE_ROUTES`, `StorageContainerComponent` |
-| Providers | `provideStorageProviders` |
+The presigned URL may have expired. Call `FileUrlService.clearCache(fileId)` to force a fresh URL fetch.
 
 ---
 
-**Last Updated:** 2026-03-01
-**Version:** 3.0.1
-**Angular Version:** 21
+## License
+
+MIT © FLUSYS

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@flusys/ng-storage",
-  "version": "4.0.2",
+  "version": "4.1.0",
   "description": "File storage module for FLUSYS Angular applications",
   "license": "MIT",
   "peerDependencies": {
     "@angular/common": ">=21.0.0",
     "@angular/core": ">=21.0.0",
     "@angular/router": ">=21.0.0",
-    "@flusys/ng-core": ">=4.0.2",
-    "@flusys/ng-layout": ">=4.0.2",
-    "@flusys/ng-shared": ">=4.0.2",
+    "@flusys/ng-core": ">=4.1.0",
+    "@flusys/ng-layout": ">=4.1.0",
+    "@flusys/ng-shared": ">=4.1.0",
     "@primeuix/themes": ">=1.0.0",
     "primeicons": ">=7.0.0",
     "primeng": ">=21.0.0",