@flusys/ng-auth 4.0.0-rc → 4.0.1

package/README.md

@@ -5,7 +5,7 @@
 `@flusys/ng-auth` provides complete authentication functionality including login, registration, token management, company/branch selection, user administration, and permission handling.
 
 **Package:** `@flusys/ng-auth`
-**Version:** 4.0.0-rc
+**Version:** 4.0.1
 **Dependencies:** ng-core, ng-shared, ng-layout
 **Build:** `npm run build:ng-auth`
 
@@ -1436,6 +1436,167 @@ When using extensions, registration data flows as:
 
 ---
 
+## Translation System (v4.0.0+)
+
+### Smart Translation Pattern with Fallback
+
+All text fields (labels, placeholders, headers, titles) now support intelligent translation fallback:
+
+```typescript
+// Interface Pattern
+interface IField {
+  label: string;           // Fallback text (always required)
+  labelKey?: string;       // Translation key (optional)
+  placeholder?: string;    // Fallback text (optional)
+  placeholderKey?: string; // Translation key (optional)
+}
+```
+
+### Message/Validation Parameter Support
+
+Validation messages and custom messages now support parameter interpolation:
+
+```typescript
+// Interface Pattern
+interface IValidationConfig {
+  message?: string;                                      // Fallback message
+  messageKey?: string;                                   // Translation key
+  messageParam?: Record<string, string | number>;       // Interpolation params
+}
+
+interface IField {
+  validationMessage?: string;
+  validationMessageKey?: string;
+  validationMessageParam?: Record<string, string | number>;
+}
+```
+
+**Usage Example:**
+```typescript
+// Provider configuration
+validationConfig: {
+  message: "Password must be at least {{min}} characters",
+  messageKey: "auth.validation.password.min.length",
+  messageParam: { min: 8 }
+}
+
+// Field configuration
+{
+  label: "Company Name",
+  labelKey: "admin.company.name",
+  placeholder: "Enter company name",
+  placeholderKey: "admin.company.name.placeholder",
+  validationMessage: "Company name is required",
+  validationMessageKey: "admin.company.name.required",
+  validationMessageParam: {}
+}
+```
+
+### safeTranslate() Method
+
+All form components have a protected `safeTranslate()` helper method that intelligently falls back when translations are missing:
+
+```typescript
+/** Translate with fallback: if key returns unchanged, use fallback instead */
+safeTranslate(key: string | undefined, fallback: string): string {
+  if (!key) return fallback;
+  const translated = this.translate(key);
+  return translated === key ? fallback : translated;  // Smart fallback!
+}
+```
+
+**Behavior:**
+```
+safeTranslate(undefined, "Name")
+→ Returns: "Name" (no key, use fallback)
+
+safeTranslate("auth.profile.name", "Name")
+→ Returns: "Nome" (translated)
+
+safeTranslate("auth.new.feature", "Name")
+→ Returns: "Name" (no translation, use fallback)
+```
+
+### Template Usage Patterns
+
+**Pattern 1: Simple Label**
+```html
+{{ safeTranslate(field.labelKey, field.label) }}
+```
+
+**Pattern 2: Placeholder with Default**
+```html
+{{ safeTranslate(field.placeholderKey, field.placeholder ?? '') }}
+```
+
+**Pattern 3: Fallback Translation Chain**
+```html
+{{ safeTranslate(field.placeholderKey, field.placeholder ?? ('shared.select' | translate)) }}
+```
+
+**Pattern 4: Complex Nested Fallback**
+```html
+{{ safeTranslate(
+  field.placeholderKey,
+  field.placeholder ?? safeTranslate(field.labelKey, field.label)
+) }}
+```
+
+### Components Using safeTranslate()
+
+- **RegisterPageComponent** - Registration extra fields
+- **ProfilePageComponent** - User editable + admin view-only fields
+- **UserFormComponent** - Admin user form fields
+- **UserListComponent** - Custom columns and action labels
+
+### Translation File Integration
+
+When translations exist, they are automatically used:
+
+**Translation file (en.json):**
+```json
+{
+  "auth.profile.name": "User Name",
+  "auth.phone.placeholder": "Enter phone number",
+  "admin.company.name": "Company",
+  "shared.select": "Select an option"
+}
+```
+
+**When key exists in translations:** Shows translated value
+**When key missing from translations:** Shows fallback text (label/placeholder/message)
+**When key undefined:** Shows fallback text directly
+
+### Corner Cases Handled
+
+| Scenario | Result |
+|----------|--------|
+| Key undefined | Returns fallback ✅ |
+| Translation missing | Returns fallback ✅ |
+| No TRANSLATE_ADAPTER | Returns fallback ✅ |
+| Fallback is empty string | Displays empty string (valid) ✅ |
+| Parameter interpolation | Supported via messageParam ✅ |
+| Nested safeTranslate calls | Works correctly ✅ |
+
+### Migration from v3.0.x
+
+**Removed fields** (no longer needed):
+```typescript
+❌ labelFallback    → Use label directly
+❌ placeholderFallback → Use placeholder directly
+❌ titleFallback    → Use title directly
+❌ headerFallback   → Use header directly
+❌ messageFallback  → Use message directly
+```
+
+**Removed:** `labelFallback`, `placeholderFallback`, `titleFallback`, `headerFallback`, `messageFallback`
+
+**Added:** `messageParam`, `validationMessageParam` for parameter interpolation
+
+**No breaking changes:** Existing implementations still work due to smart fallback logic.
+
+---
+
 ## See Also
 
 - [CORE-GUIDE.md](./CORE-GUIDE.md) - APP_CONFIG configuration
@@ -1446,8 +1607,16 @@ When using extensions, registration data flows as:
 
 ---
 
-**Last Updated:** 2026-03-01
-**Version:** 3.0.1
+**Last Updated:** 2026-03-03
+**Version:** 4.0.0-rc
 **Angular Version:** 21
 
+## Key Changes in v4.0.0-rc
+
+- ✅ Smart translation fallback system with `safeTranslate()` helper
+- ✅ Message parameter support (`messageParam`, `validationMessageParam`)
+- ✅ Removed redundant `*Fallback` interface fields
+- ✅ All 4 form pages use safe translation pattern
+- ✅ Type-safe, TypeScript enforced
+
 All 15 components use responsive design and dark mode support. Form components use Signal Forms.