@flusys/ng-storage 1.1.0-beta → 1.1.0

package/README.md

@@ -1,6 +1,7 @@
 # Storage Package Guide
 
 > **Package:** `@flusys/ng-storage`
+> **Version:** 1.1.0
 > **Type:** File storage management with upload, folder organization, and multi-provider support
 
 ---
@@ -48,6 +49,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 +60,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 +193,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
@@ -303,9 +313,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:
 
@@ -357,19 +369,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)
@@ -383,6 +434,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
@@ -403,6 +459,41 @@ When `isDefault: true`, this configuration will be used automatically when no `s
 
 ---
 
+## 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 },
+];
+```
+
+---
+
 ## Usage Examples
 
 ### Upload a File
@@ -428,6 +519,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
@@ -566,6 +679,31 @@ 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
@@ -653,5 +791,6 @@ export { provideStorageProviders } from '@flusys/ng-storage';
 
 ---
 
-**Last Updated:** 2026-02-16
+**Last Updated:** 2026-02-23
+**Version:** 1.1.0
 **Angular Version:** 21