@flusys/ng-shared 3.0.1 → 4.0.0-rc

package/README.md

@@ -9,7 +9,7 @@
 ## Package Information
 
 - **Package:** `@flusys/ng-shared`
-- **Version:** 3.0.1
+- **Version:** 4.0.0-rc
 - **Dependencies:** ng-core
 - **Dependents:** ng-layout, ng-auth, ng-iam, ng-storage, flusysng
 - **Build Command:** `npm run build:ng-shared`
@@ -1268,28 +1268,18 @@ interface IUserPermissionProvider {
 
 **Token Error Message:** `'USER_PERMISSION_PROVIDER not configured. Please provide an implementation in app.config.ts'`
 
-#### IProfileUploadProvider / `PROFILE_UPLOAD_PROVIDER`
+#### IFileProvider / `FILE_PROVIDER`
 
-Profile picture upload for ng-auth profile page. Implemented by ng-storage. **Optional token** - use with `inject(..., { optional: true })`.
+File operations provider for file selection and upload. Implemented by ng-storage. **Optional token** - use with `inject(..., { optional: true })`.
 
 ```typescript
-interface IProfileUploadResult {
-  id: string; // File manager ID (UUID)
-  name: string; // Original file name
-  key: string; // Storage key/path
-  size: number; // File size in bytes
-  contentType: string; // MIME type
-}
-
-interface IProfileUploadOptions {
-  folderPath?: string;
-  compress?: boolean;
-  maxWidth?: number;
-  maxHeight?: number;
-}
-
-interface IProfileUploadProvider {
-  uploadProfilePicture(file: File, options?: IProfileUploadOptions): Observable<ISingleResponse<IProfileUploadResult>>;
+interface IFileProvider {
+  loadFiles(filter: IFileSelectFilter): Observable<IListResponse<IFileBasicInfo>>;
+  uploadFile(file: File, options?: IFileUploadOptions): Observable<ISingleResponse<IUploadedFile>>;
+  uploadMultipleFiles?(files: File[], options?: IFileUploadOptions): Observable<ISingleResponse<IUploadedFile[]>>;
+  getFileUrls?(fileIds: string[]): Observable<ISingleResponse<IFileBasicInfo[]>>;
+  loadFolders?(filter: ISelectFilter): Observable<IListResponse<IFolderBasicInfo>>;
+  loadStorageConfigs?(filter: ISelectFilter): Observable<IListResponse<IStorageConfigBasicInfo>>;
 }
 ```
 
@@ -1635,11 +1625,16 @@ providers: [...provideAuthProviders()];
 | `IUserSelectFilter`     | User select filter params                                                      |
 | `LoadUsersFn`           | User loading function type                                                     |
 | `IFileBasicInfo`        | Basic file info for selectors                                                  |
+| `IFolderBasicInfo`      | Folder info for selectors                                                      |
+| `IStorageConfigBasicInfo` | Storage config info for selectors                                            |
 | `IFileUploadOptions`    | Upload options (compression, etc.)                                             |
 | `IUploadedFile`         | Uploaded file response                                                         |
 | `IFileSelectFilter`     | File select filter params                                                      |
+| `ISelectFilter`         | Filter params for folder/config selectors                                      |
 | `LoadFilesFn`           | File loading function type                                                     |
-| `UploadFileFn`          | File upload function type                                                      |
+| `UploadFileFn`          | Single file upload function type                                               |
+| `UploadMultipleFilesFn` | Multiple files upload function type                                            |
+| `IFileProvider`         | File operations provider interface                                             |
 | `FilesResponseDto`      | File URL service response                                                      |
 | `IAuthStateProvider`    | Auth state provider interface                                                  |
 | `IUserListProvider`     | User list extensions provider                                                  |
@@ -1658,10 +1653,153 @@ providers: [...provideAuthProviders()];
 | `COMPANY_API_PROVIDER`        | `ICompanyApiProvider`        | No       | Company list for IAM                  |
 | `USER_PERMISSION_PROVIDER`    | `IUserPermissionProvider`    | No       | User permission queries               |
 | `AUTH_STATE_PROVIDER`         | `IAuthStateProvider`         | No       | Auth state for feature packages       |
-| `PROFILE_UPLOAD_PROVIDER`     | `IProfileUploadProvider`     | Yes      | Profile picture upload (ng-storage)   |
+| `FILE_PROVIDER`               | `IFileProvider`              | Yes      | File operations (ng-storage)          |
 | `PROFILE_PERMISSION_PROVIDER` | `IProfilePermissionProvider` | Yes      | User permissions for profile (ng-iam) |
 | `USER_LIST_PROVIDER`          | `IUserListProvider`          | Yes      | User list extensions                  |
 
+---
+
+## 10. Translation & Localization
+
+### Overview
+
+The ng-shared package provides optional localization support via two modes:
+
+1. **Fallback-Only Mode** - Hardcoded fallback messages (no API)
+2. **Full API Mode** - Dynamic translations from API with fallback safety net
+
+### Fallback-Only Mode
+
+Use when you want simple hardcoded translations without a localization system:
+
+```typescript
+// app.config.ts
+import { provideFallbackLocalization } from '@flusys/ng-shared';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    // ... other providers
+    ...provideFallbackLocalization(),  // ← One-liner setup
+  ],
+};
+```
+
+**What it provides:**
+- `FALLBACK_MESSAGES_REGISTRY` - Token for storing hardcoded messages
+- `TRANSLATE_ADAPTER` - Fallback implementation that reads from registry
+- Works with route resolvers that register fallback messages
+
+**Message flow:**
+```
+Route with resolveTranslationModule({
+  modules: ['email'],
+  fallbackMessages: EMAIL_MESSAGES
+})
+    ↓
+Resolver registers in FALLBACK_MESSAGES_REGISTRY
+    ↓
+TRANSLATE_ADAPTER reads from registry
+    ↓
+Components/TranslatePipe render values
+```
+
+### Full API Mode
+
+Use when you need dynamic translations, language switching, and management UI:
+
+```typescript
+// app.config.ts
+import { provideLocalization, getLocalizationConfig } from '@flusys/ng-localization';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    // ... other providers
+    ...provideLocalization(
+      getLocalizationConfig({
+        defaultLanguageCode: 'en',
+        enableLayoutSelector: true,  // Show language switcher
+      })
+    ),
+  ],
+};
+```
+
+**What it provides:**
+- `LocalizationStateService` - Manages current language and translations
+- `LocalizationApiService` - Fetches translations from backend
+- `TranslateService` - Registered as `TRANSLATE_ADAPTER`
+- Language selector component (if `enableLayoutSelector: true`)
+- Management pages for languages and translations
+
+### Route Resolver Setup
+
+All routes should use `resolveTranslationModule` with fallback messages:
+
+```typescript
+// email.routes.ts
+import { resolveTranslationModule, EMAIL_MESSAGES, SHARED_MESSAGES } from '@flusys/ng-shared';
+
+export const EMAIL_ROUTES: Routes = [
+  {
+    path: '',
+    resolve: {
+      translations: resolveTranslationModule({
+        modules: ['email'],
+        fallbackMessages: { ...EMAIL_MESSAGES, ...SHARED_MESSAGES }
+      })
+    },
+    // ... route definition
+  }
+];
+```
+
+### TranslatePipe Usage
+
+Works identically in both modes:
+
+```typescript
+// Template
+<h1>{{ 'email.title' | translate }}</h1>
+<p>{{ 'email.message' | translate: { count: itemCount } }}</p>
+
+// Component
+const title = this.translateAdapter.translate('email.title');
+```
+
+### Configuration (Full API Mode Only)
+
+```typescript
+interface ILocalizationConfig {
+  defaultLanguageCode: string;        // Required: 'en', 'ar', etc.
+  loadStrategy?: 'all' | 'modules';   // Default: 'modules'
+  initialModules?: string[];          // Default: []
+  enableLayoutSelector?: boolean;     // Default: false
+}
+```
+
+### Key Files
+
+| File | Purpose |
+|------|---------|
+| `providers/fallback-localization.providers.ts` | Fallback mode setup |
+| `resolvers/translation-module.resolver.ts` | Route resolver for both modes |
+| `pipes/translate.pipe.ts` | Translation pipe |
+
+### When to Use Each Mode
+
+**Use Fallback-Only:**
+- Simple applications with static content
+- No language switching needed
+- No translation management UI
+- Lightweight setup
+
+**Use Full API:**
+- Multi-language support required
+- User can switch languages
+- Admin manages translations
+- Real-time translation updates
+- Translation management UI needed
+
 ## See Also
 
 - **[CORE-GUIDE.md](./CORE-GUIDE.md)** - Configuration, interceptors
@@ -1671,6 +1809,6 @@ providers: [...provideAuthProviders()];
 
 ---
 
-**Last Updated:** 2026-02-25
+**Last Updated:** 2026-03-01
 **Version:** 3.0.1
 **Angular Version:** 21