@flusys/ng-storage 0.1.0-beta.3 → 1.0.0-rc

package/README.md

@@ -48,6 +48,8 @@ readonly currentCompanyName = computed(
 
 ```
 ng-storage/
+├── adapters/
+│   └── profile-upload-provider.adapter.ts  # Profile upload adapter for ng-auth
 ├── enums/
 │   ├── file-location.enum.ts     # FileLocationEnum, ImageFormat
 │   └── public-api.ts
@@ -57,11 +59,17 @@ ng-storage/
 │   ├── 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)
@@ -184,6 +192,7 @@ interface IFileManager {
   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
@@ -233,6 +242,8 @@ interface IStorageConfig extends IBaseEntity {
   name: string;
   storage: FileLocationEnum;
   config: Record<string, any>;   // Provider-specific configuration
+  isActive: boolean;             // Whether config is active and usable
+  isDefault: boolean;            // Set as default configuration
   companyId?: string | null;
 }
 
@@ -240,6 +251,8 @@ interface ICreateStorageConfigDto {
   name: string;
   storage: FileLocationEnum;
   config: Record<string, any>;
+  isActive?: boolean;
+  isDefault?: boolean;
 }
 
 interface IUpdateStorageConfigDto {
@@ -247,6 +260,8 @@ interface IUpdateStorageConfigDto {
   name?: string;
   storage?: FileLocationEnum;
   config?: Record<string, any>;
+  isActive?: boolean;
+  isDefault?: boolean;
 }
 ```
 
@@ -297,9 +312,11 @@ Handles file upload and deletion. Extends `BaseApiService` (from ng-core).
 |--------|----------|-------------|
 | `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 |
 
 Upload options are sent as **query parameters**, not form data:
 
@@ -351,19 +368,58 @@ Storage provider configuration CRUD. Extends `ApiResourceService<IUpdateStorageC
 
 All components are standalone, use Angular 21 signal forms, and lazy-load via routes.
 
+### Base Classes
+
+Components extend shared base classes from `utils/base-storage-page.ts`:
+
+```typescript
+// BaseStoragePage - Common functionality for all storage pages
+abstract class BaseStoragePage {
+  readonly isLoading = signal(false);
+  readonly showCompanyInfo = computed(() => this.appConfig.enableCompanyFeature);
+  readonly currentCompanyName = computed(() =>
+    this.companyContext.currentCompanyInfo()?.name ?? DEFAULT_APP_NAME
+  );
+
+  protected showSuccess(detail: string): void;
+  protected showError(detail: string): void;
+  protected navigateTo(path: string[]): void;
+}
+
+// BaseStorageListPage - Adds pagination support
+abstract class BaseStorageListPage extends BaseStoragePage {
+  readonly totalRecords = signal(0);
+  readonly pageSize = signal(50);
+  readonly currentPage = signal(1);
+
+  onPageChange(event: { first?: number; rows?: number }): void;
+  protected getPaginationParams(): { currentPage: number; pageSize: number };
+  abstract loadData(): Promise<void>;
+}
+```
+
 ### StorageContainerComponent
 
-Main container with tab navigation between Files, Folders, and Configs sections. Uses inline CSS with theme variables (`--primary-color`, `--surface-ground`, etc.).
+Main container with tab navigation between Files, Folders, and Configs sections.
 
 **Selector:** `lib-storage-container`
 
+**Features:**
+- Tab navigation with `scrollbar-hide` CSS (horizontal scroll without visible scrollbar on mobile)
+- Responsive padding: `p-2 sm:p-4`
+- Dark mode compatible using Tailwind theme classes
+
 ### List Components
 
 All list components share:
-- **Lazy pagination** via `p-datatable`
-- **Company info display** when company feature enabled (via `APP_CONFIG`)
+- **Extends `BaseStorageListPage`** for common functionality
+- **Lazy pagination** via `p-table` with `[paginator]="totalRecords() > 0"` (hidden when no data)
+- **Responsive columns** with `hidden sm:table-cell`, `hidden md:table-cell`, etc.
+- **Company info display** when company feature enabled
 - **Delete confirmation** via `ConfirmationService`
-- **Signal-based state:** `isLoading`, `files`/`folders`/`configs`, `totalRecords`, `pageSize`, `currentPage`
+- **Signal-based state:** `isLoading`, data signal, `totalRecords`, `pageSize`, `currentPage`
+- **Responsive title:** `text-lg sm:text-xl`
+- **Responsive buttons:** `w-full sm:w-auto`
 
 **FileManagerListComponent** additionally supports:
 - File content type icons (image, video, audio, PDF, Word, Excel, generic)
@@ -377,6 +433,11 @@ All form components share:
 - **Signal Forms** using Angular 21 `form()` helper with `required()` validators
 - **Create/Edit mode** auto-detection based on route param (`:id`)
 - **Navigation** back to list on save/cancel
+- **Button styling pattern:**
+  - Cancel: `severity="secondary" [outlined]="true"`
+  - Submit: Primary style (no severity attribute)
+  - Order: Cancel first, then Submit (right-aligned)
+  - Responsive: `flex justify-end gap-4 pt-4`
 
 **FileManagerFormComponent** additionally supports:
 - PrimeNG file upload with drag-drop
@@ -389,6 +450,46 @@ All form components share:
 - Azure Blob: accountName, accountKey, containerName
 - SFTP: host, port, username, password, basePath
 - Local: basePath
+- **Active toggle** - enables/disables the configuration
+- **Set as Default toggle** - marks configuration as the default for uploads
+
+**Default Configuration:**
+When `isDefault: true`, this configuration will be used automatically when no `storageConfigId` is provided in upload requests.
+
+---
+
+## Utility Functions
+
+The `utils/storage-utils.ts` file provides helper functions used across components:
+
+```typescript
+// Get display label for storage provider
+getProviderLabel(storage: FileLocationEnum): string;
+// Returns: 'AWS S3', 'Azure Blob', 'SFTP', 'Local'
+
+// Get icon class for storage provider
+getProviderIcon(storage: FileLocationEnum): string;
+// Returns: 'pi pi-cloud', 'pi pi-server', 'pi pi-folder'
+
+// Get severity for p-tag based on provider
+getProviderSeverity(storage: FileLocationEnum): 'success' | 'info' | 'warn' | 'danger' | 'secondary' | 'contrast';
+
+// Get file icon based on content type
+getFileIcon(contentType: string): string;
+// Returns: 'pi pi-image', 'pi pi-video', 'pi pi-file-pdf', etc.
+
+// Format file size to human readable
+formatFileSize(bytes: number): string;
+// Returns: '1.5 MB', '256 KB', etc.
+
+// Storage provider options for dropdowns
+const STORAGE_PROVIDERS = [
+  { label: 'AWS S3', value: FileLocationEnum.AWS },
+  { label: 'Azure Blob Storage', value: FileLocationEnum.AZURE },
+  { label: 'SFTP', value: FileLocationEnum.SFTP },
+  { label: 'Local Storage', value: FileLocationEnum.LOCAL },
+];
+```
 
 ---
 
@@ -417,6 +518,28 @@ async uploadImage(file: File): Promise<IUploadedFileInfo | null> {
 }
 ```
 
+### Upload and Register (Combined)
+
+Use `uploadAndRegister` for a single call that uploads and creates the file manager record:
+
+```typescript
+import { UploadService, IFileManager } from '@flusys/ng-storage';
+
+private readonly uploadService = inject(UploadService);
+
+async uploadProfilePicture(file: File): Promise<IFileManager | null> {
+  const response = await firstValueFrom(
+    this.uploadService.uploadAndRegister(file, {
+      compress: true,
+      quality: 85,
+      isPrivate: false,
+      folderId: 'avatars-folder-id',
+    })
+  );
+  return response.success ? response.data : null;
+}
+```
+
 ### Get Files with Presigned URLs
 
 ```typescript
@@ -555,6 +678,84 @@ services: {
 }
 ```
 
+### 6. Responsive Design Patterns
+
+All components follow these responsive patterns:
+
+```html
+<!-- Titles: smaller on mobile -->
+<h3 class="text-lg sm:text-xl font-semibold">Title</h3>
+
+<!-- Buttons: full width on mobile, auto on larger -->
+<p-button label="New" styleClass="w-full sm:w-auto" />
+
+<!-- Form grids: stack on mobile, 2 columns on md+ -->
+<div class="grid grid-cols-1 md:grid-cols-2 gap-4">
+
+<!-- Labels: smaller text on mobile -->
+<label class="text-sm sm:text-base">Label</label>
+
+<!-- Table columns: hide on smaller screens -->
+<th class="hidden sm:table-cell">Column</th>
+<th class="hidden md:table-cell">Column</th>
+
+<!-- Tab navigation: horizontal scroll without visible scrollbar -->
+<div class="scrollbar-hide flex overflow-x-auto">
+```
+
+---
+
+## Provider Functions
+
+### provideStorageProviders()
+
+Registers provider adapters that enable other packages (ng-auth) to access storage functionality without direct dependencies.
+
+```typescript
+import { provideStorageProviders } from '@flusys/ng-storage';
+
+// app.config.ts
+export const appConfig: ApplicationConfig = {
+  providers: [
+    ...provideStorageProviders(),  // Register storage providers
+  ],
+};
+```
+
+**Registers:**
+
+| Token | Adapter | Purpose |
+|-------|---------|---------|
+| `PROFILE_UPLOAD_PROVIDER` | `ProfileUploadProviderAdapter` | Profile picture upload for ng-auth |
+
+### ProfileUploadProviderAdapter
+
+Implements `IProfileUploadProvider` from ng-shared. Enables ng-auth's profile page to upload profile pictures.
+
+```typescript
+interface IProfileUploadProvider {
+  uploadProfilePicture(
+    file: File,
+    options?: IProfileUploadOptions
+  ): Observable<ISingleResponse<IProfileUploadResult>>;
+}
+```
+
+**Usage in ng-auth profile page:**
+
+```typescript
+// Optional injection - graceful degradation when storage disabled
+private readonly uploadProvider = inject(PROFILE_UPLOAD_PROVIDER, { optional: true });
+
+// Upload profile picture
+if (this.uploadProvider) {
+  this.uploadProvider.uploadProfilePicture(file, { compress: true }).subscribe(response => {
+    // response.data.id contains the file manager ID
+    this.updateUserProfile({ profilePictureId: response.data.id });
+  });
+}
+```
+
 ---
 
 ## Public API Exports
@@ -582,9 +783,12 @@ export {
 // Routes & Components
 export { STORAGE_ROUTES } from '@flusys/ng-storage';
 export { StorageContainerComponent } from '@flusys/ng-storage';
+
+// Provider Functions
+export { provideStorageProviders } from '@flusys/ng-storage';
 ```
 
 ---
 
-**Last Updated:** 2026-02-07
+**Last Updated:** 2026-02-18
 **Angular Version:** 21