@acorex/modules 20.0.11 → 20.0.13

package/calendar-management/README.md

@@ -0,0 +1,271 @@
+# Calendar Management Module
+
+This module provides comprehensive calendar management functionality for the ACoreX Platform, enabling administrators to define, manage, and configure calendar systems with support for multiple calendar types, inheritance, special days, and scoping.
+
+## 🎯 **Core Features**
+
+### **Calendar System**
+
+- **Multiple Calendar Types**: Support for Gregorian, Persian (Jalali), Hijri (Islamic), Chinese, Hebrew, and custom calendar systems
+- **Calendar Inheritance**: Hierarchical calendar structure where child calendars inherit from parent calendars
+- **No Inheritance Depth Limit**: Unlimited levels of calendar inheritance for complex organizational structures
+- **Weekend Configuration**: Flexible weekend patterns (Friday-Saturday, Saturday-Sunday, etc.)
+- **Working Hours Management**: Configurable working hours per calendar with daily granularity
+
+### **Date Exception Management**
+
+- **Special Days**: Define holidays, workdays, half-days, events, maintenance days, and deadlines
+- **Recurrence Rules**: Support for recurring events with complex patterns
+- **Override System**: Child calendars can override parent calendar exceptions
+- **Priority-based Resolution**: Conflict resolution using priority system
+- **Time Granularity**: Full-day or time-specific exceptions
+
+### **Scoping System**
+
+- **Multi-level Scoping**: Platform, tenant, division, and user-level calendars
+- **Scope Permissions**: Granular permission system for calendar access
+- **Inheritance Control**: Override capabilities at each scope level
+
+## 📚 **Architecture**
+
+### **Entity Structure**
+
+```
+Calendar (Main Entity - Hierarchical)
+├── CalendarType (Lookup)
+├── DateException (Related)
+│   └── RecurrenceRule (Related)
+└── CalendarScope (Related)
+```
+
+### **Core Entities**
+
+#### **1. Calendar (Main Entity)**
+
+The primary entity representing calendar systems with inheritance support.
+
+**Key Properties:**
+
+- `name`: Unique calendar identifier
+- `title`: Display name
+- `calendarTypeId`: Calendar system type
+- `parentId`: Parent calendar for inheritance
+- `scopeType`: Application scope (platform/tenant/division/user)
+- `weekendPattern`: Array of weekend days
+- `workingHours`: JSON configuration of daily working hours
+- `isTemplate`: Can be used as base for other calendars
+
+#### **2. CalendarType (Lookup Entity)**
+
+Defines different calendar system types.
+
+**Key Properties:**
+
+- `title`: Calendar type name
+- `code`: System code (gregorian, persian, hijri, etc.)
+- `isDefault`: Default calendar type flag
+
+#### **3. DateException (Related Entity)**
+
+Manages special days and exceptions in calendars.
+
+**Key Properties:**
+
+- `calendarId`: Parent calendar reference
+- `date`: Exception date
+- `exceptionType`: Type of exception (holiday, workday, etc.)
+- `isRecurring`: Whether exception repeats
+- `overridesParent`: Overrides parent calendar exception
+- `priority`: Conflict resolution priority
+
+#### **4. RecurrenceRule (Related Entity)**
+
+Defines recurring patterns for date exceptions.
+
+**Key Properties:**
+
+- `frequency`: Recurrence frequency (daily, weekly, monthly, yearly)
+- `interval`: Interval between occurrences
+- `endDate`: End date for recurrence
+- `byDay`: Day-based rules
+- `byMonth`: Month-based rules
+
+#### **5. CalendarScope (Related Entity)**
+
+Manages calendar access and permissions by scope.
+
+**Key Properties:**
+
+- `calendarId`: Calendar reference
+- `scopeType`: Scope level
+- `scopeEntityId`: Entity ID within scope
+- `permissions`: Access permissions
+
+## 🔧 **Configuration Examples**
+
+### **Basic Calendar Setup**
+
+```typescript
+// Create a base Persian calendar
+const iranNationalCalendar = {
+  name: 'iran-national',
+  title: 'Iran National Calendar',
+  calendarTypeId: 'persian-type-id',
+  scopeType: 'platform',
+  weekendPattern: ['friday'],
+  isTemplate: true,
+  isActive: true,
+};
+
+// Create company calendar inheriting from national
+const companyCalendar = {
+  name: 'company-calendar',
+  title: 'Company Calendar',
+  calendarTypeId: 'persian-type-id',
+  parentId: iranNationalCalendar.id,
+  scopeType: 'tenant',
+  scopeEntityId: 'company-tenant-id',
+  weekendPattern: ['friday', 'saturday'], // Override weekend
+};
+```
+
+### **Date Exception Configuration**
+
+```typescript
+// Recurring holiday (Nowruz)
+const nowruzException = {
+  calendarId: iranNationalCalendar.id,
+  date: new Date('2024-03-20'),
+  exceptionType: 'holiday',
+  title: 'Nowruz',
+  isRecurring: true,
+  recurrenceRuleId: 'yearly-march-20-rule',
+  isAllDay: true,
+  priority: 1,
+};
+
+// Company-specific working day override
+const companyWorkday = {
+  calendarId: companyCalendar.id,
+  date: new Date('2024-03-21'), // Normally holiday
+  exceptionType: 'workday',
+  title: 'Special Working Day',
+  overridesParent: true,
+  isAllDay: false,
+  startTime: '09:00',
+  endTime: '13:00',
+  priority: 2,
+};
+```
+
+## 🚀 **Usage**
+
+### **Module Installation**
+
+```typescript
+import { AXMCalendarManagementModule } from '@acorex/modules/calendar-management';
+
+@NgModule({
+  imports: [
+    AXMCalendarManagementModule,
+    // other modules
+  ],
+})
+export class AppModule {}
+```
+
+### **Service Usage**
+
+```typescript
+import { AXMCalendarService } from '@acorex/modules/calendar-management';
+
+@Injectable()
+export class CalendarBusinessService {
+  constructor(private calendarService: AXMCalendarService) {}
+
+  async getEffectiveCalendar(calendarId: string): Promise<Calendar> {
+    // Gets calendar with resolved inheritance
+    return await this.calendarService.getOne(calendarId);
+  }
+
+  async isWorkingDay(calendarId: string, date: Date): Promise<boolean> {
+    // Business logic to determine if date is working day
+    // considering calendar hierarchy and exceptions
+  }
+}
+```
+
+## 🌍 **Internationalization**
+
+The module includes complete translations for:
+
+- **English (en-US)**: Full UI translations
+- **Persian (fa-IR)**: Native Persian translations
+
+Translation files are located in:
+
+- `apps/demo/src/assets/i18n/en-US/calendar-management.json`
+- `apps/demo/src/assets/i18n/fa-IR/calendar-management.json`
+
+## 🔐 **Permissions**
+
+Granular permission system includes:
+
+- `calendar.view`: View calendars
+- `calendar.create`: Create new calendars
+- `calendar.update`: Modify existing calendars
+- `calendar.delete`: Delete calendars
+- `calendar-type.manage`: Manage calendar types
+- `date-exception.*`: Date exception permissions
+- `calendar.admin`: Full administrative access
+
+## 📋 **Admin UI Features**
+
+### **Calendar Management**
+
+- List view with hierarchical display
+- Create/Edit calendar with inheritance dropdown
+- Preview effective calendar (merged view from parent)
+- Scope-based filtering and access control
+
+### **Date Exception Management**
+
+- Calendar-specific date exception management
+- Recurring pattern configuration
+- Visual calendar view with exceptions highlighted
+- Override conflict resolution interface
+
+### **Calendar Resolution**
+
+When fetching calendar data, the system resolves inheritance recursively:
+
+```
+Base Calendar → Parent Calendar → Current Calendar → Final Merged View
+```
+
+Child calendars override parent settings for specific dates, providing flexible calendar customization while maintaining consistency through inheritance.
+
+## 🤝 **Contributing**
+
+When extending this module:
+
+1. **Follow ACoreX entity patterns** for consistency
+2. **Add comprehensive tests** for calendar resolution logic
+3. **Update translations** for new features
+4. **Consider backward compatibility** when modifying inheritance logic
+5. **Document complex business rules** in code comments
+
+## 📝 **Future Enhancements**
+
+Planned features include:
+
+- **Time Zone Support**: Multi-timezone calendar management
+- **Calendar Templates**: Pre-built calendar templates for different regions
+- **Import/Export**: ICS/CSV support for external calendar integration
+- **Calendar Visualization**: Interactive calendar view components
+- **Notification System**: Alerts for upcoming important dates
+- **Calendar Analytics**: Usage and exception statistics
+
+---
+
+> 💡 **Note**: This module is designed to be a comprehensive calendar management solution for enterprise applications requiring complex calendar hierarchies and multi-cultural calendar support.

package/calendar-management/index.d.ts

@@ -0,0 +1,156 @@
+import * as i0 from '@angular/core';
+import { Injector } from '@angular/core';
+import * as i1 from '@angular/common';
+import { AXPEntityModel, AXMEntityCrudServiceImpl, AXPEntityDefinitionLoader, AXPEntityDefinitionPreloader, AXPEntityPreloadEntity } from '@acorex/platform/layout/entity';
+import { AXPEntity, AXPMenuProvider, AXPMenuProviderContext, AXPSearchCommandProvider, AXPSearchResult } from '@acorex/platform/common';
+import { AXPPermissionDefinitionProvider, AXPPermissionDefinitionProviderContext } from '@acorex/platform/auth';
+
+declare class AXMCalendarManagementModule {
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXMCalendarManagementModule, never>;
+    static ɵmod: i0.ɵɵNgModuleDeclaration<AXMCalendarManagementModule, never, [typeof i1.CommonModule], never>;
+    static ɵinj: i0.ɵɵInjectorDeclaration<AXMCalendarManagementModule>;
+}
+
+declare const RootConfig: {
+    config: {
+        i18n: string;
+        module: string;
+    };
+    module: {
+        name: string;
+        title: string;
+        icon: string;
+    };
+    entities: {
+        calendar: {
+            name: string;
+            title: string;
+            titlePlural: string;
+            icon: string;
+        };
+        calendarEvent: {
+            name: string;
+            title: string;
+            titlePlural: string;
+            icon: string;
+        };
+        calendarEventType: {
+            name: string;
+            title: string;
+            titlePlural: string;
+            icon: string;
+        };
+    };
+};
+
+interface AXMCalendarManagementCalendarEntityModel extends AXPEntityModel<string> {
+    name: string;
+    title: string;
+    description?: string;
+    calendarTypeId: any;
+    parentId?: string;
+    weekends: string[];
+    firstDayOfWeek: string;
+    isActive: boolean;
+    isTemplate: boolean;
+    order: number;
+    createdAt: Date;
+    updatedAt: Date;
+    calendarType?: any;
+    parent?: any;
+    dateExceptions?: any[];
+    scopes?: any[];
+}
+
+declare abstract class AXMCalendarService extends AXMEntityCrudServiceImpl<string, AXMCalendarManagementCalendarEntityModel> {
+}
+declare class AXMCalendarServiceImpl extends AXMCalendarService {
+    constructor();
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXMCalendarServiceImpl, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AXMCalendarServiceImpl>;
+}
+
+interface AXMCalendarManagementCalendarEventEntityModel extends AXPEntityModel<string> {
+    calendarId: string;
+    title: string;
+    description?: string;
+    typeId: string;
+    date: Date;
+    isRecurring: boolean;
+    recurrenceRule?: string;
+    isActive: boolean;
+    order: number;
+    calendar?: {
+        id: string;
+        title: string;
+    };
+    type?: {
+        id: string;
+        title: string;
+        color: string;
+        icon?: string;
+    };
+}
+
+declare abstract class AXMCalendarEventService extends AXMEntityCrudServiceImpl<string, AXMCalendarManagementCalendarEventEntityModel> {
+}
+declare class AXMCalendarEventServiceImpl extends AXMCalendarEventService {
+    constructor();
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXMCalendarEventServiceImpl, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AXMCalendarEventServiceImpl>;
+}
+
+interface AXMCalendarManagementCalendarEventTypeEntityModel extends AXPEntityModel<string> {
+    title: string;
+    description?: string;
+    color: string;
+    icon?: string;
+    isActive: boolean;
+    isDefault: boolean;
+    order: number;
+    createdAt: Date;
+    updatedAt: Date;
+}
+
+declare abstract class AXMCalendarEventTypeService extends AXMEntityCrudServiceImpl<string, AXMCalendarManagementCalendarEventTypeEntityModel> {
+}
+declare class AXMCalendarEventTypeServiceImpl extends AXMCalendarEventTypeService {
+    constructor();
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXMCalendarEventTypeServiceImpl, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AXMCalendarEventTypeServiceImpl>;
+}
+
+declare function calendarFactory(injector: Injector): Promise<AXPEntity | null>;
+
+declare function calendarEventFactory(injector: Injector): Promise<AXPEntity | null>;
+
+declare function calendarEventTypeFactory(injector: Injector): Promise<AXPEntity | null>;
+
+declare class AXMCalendarManagementEntityProvider implements AXPEntityDefinitionLoader, AXPEntityDefinitionPreloader {
+    private injector;
+    preload(): AXPEntityPreloadEntity[];
+    get(moduleName: string, entityName: string): Promise<AXPEntity | null>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXMCalendarManagementEntityProvider, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AXMCalendarManagementEntityProvider>;
+}
+
+declare class AXMCalendarManagementMenuProvider implements AXPMenuProvider {
+    private entityService;
+    provide(context: AXPMenuProviderContext): Promise<void>;
+}
+
+declare class AXMCalendarManagementPermissionDefinitionProvider implements AXPPermissionDefinitionProvider {
+    private injector;
+    private readonly translateService;
+    constructor(injector: Injector);
+    define(context: AXPPermissionDefinitionProviderContext): Promise<void>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXMCalendarManagementPermissionDefinitionProvider, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AXMCalendarManagementPermissionDefinitionProvider>;
+}
+
+declare class AXMCalendarManagementSearchCommandProvider extends AXPSearchCommandProvider {
+    commands: AXPSearchResult[];
+}
+
+export { AXMCalendarEventService, AXMCalendarEventServiceImpl, AXMCalendarEventTypeService, AXMCalendarEventTypeServiceImpl, AXMCalendarManagementEntityProvider, AXMCalendarManagementMenuProvider, AXMCalendarManagementModule, AXMCalendarManagementPermissionDefinitionProvider, AXMCalendarManagementSearchCommandProvider, AXMCalendarService, AXMCalendarServiceImpl, RootConfig, calendarEventFactory, calendarEventTypeFactory, calendarFactory };
+export type { AXMCalendarManagementCalendarEntityModel, AXMCalendarManagementCalendarEventEntityModel, AXMCalendarManagementCalendarEventTypeEntityModel };

package/contact-management/README.md

@@ -412,6 +412,156 @@ Maps relationships between contacts (family, business, professional).
 ]
 ```
 
+### 9. EmergencyContactCategory (Hierarchical Lookup Entity)
+
+Represents categories for classifying emergency contacts (e.g., Police, Fire, Medical). Supports hierarchical (parent-child) relationships and visual customization.
+
+**Key Properties:**
+
+|    Name     |  Type   | Description                        |
+| :---------: | :-----: | :--------------------------------- |
+|    title    | string  | Category title                     |
+| description | string  | Description of the category        |
+|  parentId   | string  | Parent category ID (for hierarchy) |
+| childCount  | number  | Number of child categories         |
+|    icon     | string  | FontAwesome icon                   |
+|    color    | string  | Category color (HEX)               |
+|  priority   | number  | Display priority                   |
+|  isActive   | boolean | Active status                      |
+|    order    | number  | Display order                      |
+
+**Sample Data:**
+
+```json
+[
+  {
+    "id": "ecat1",
+    "title": "Police",
+    "description": "Law enforcement emergency services",
+    "icon": "fa-light fa-shield-halved",
+    "color": "#1976d2",
+    "priority": 1,
+    "isActive": true,
+    "order": 1
+  },
+  {
+    "id": "ecat2",
+    "title": "Fire Department",
+    "description": "Fire and rescue services",
+    "icon": "fa-light fa-fire-extinguisher",
+    "color": "#d32f2f",
+    "priority": 2,
+    "isActive": true,
+    "order": 2
+  }
+]
+```
+
+### 10. EmergencyContact (Public Emergency Number Entity)
+
+Stores public emergency contact numbers (e.g., 911, 112, local hotlines) with rich metadata, categorization, and geographic/availability details.
+
+**Key Properties:**
+
+|         Name         |   Type   | Description                               |
+| :------------------: | :------: | :---------------------------------------- |
+|         name         |  string  | Emergency service name                    |
+|      shortName       |  string  | Short label (e.g., 911, 112)              |
+|     description      |  string  | Description of the service                |
+|     categoryIds      | string[] | Linked EmergencyContactCategory IDs       |
+|     phoneNumber      |  string  | Main emergency phone number               |
+|   alternateNumbers   | string[] | Alternate numbers                         |
+|      textNumber      |  string  | SMS/text number                           |
+|       website        |  string  | Service website                           |
+|        email         |  string  | Contact email                             |
+|       country        |  string  | Country of service                        |
+|        region        |  string  | Region/State                              |
+|         city         |  string  | City                                      |
+|      isNational      | boolean  | National coverage flag                    |
+|      isRegional      | boolean  | Regional coverage flag                    |
+|       isLocal        | boolean  | Local coverage flag                       |
+|     availability     |  string  | Availability (24/7, business hours, etc.) |
+|      languages       | string[] | Supported languages                       |
+|    isTextCapable     | boolean  | Supports SMS/text                         |
+|  isVideoCallCapable  | boolean  | Supports video calls                      |
+|      whenToCall      |  string  | When to call                              |
+|    whenNotToCall     |  string  | When NOT to call                          |
+|     instructions     |  string  | Special instructions                      |
+|       priority       |  number  | Display priority                          |
+|       isActive       | boolean  | Active status                             |
+|      isVerified      | boolean  | Verification status                       |
+|     lastVerified     |   date   | Last verification date                    |
+|   showOnDashboard    | boolean  | Show on dashboard                         |
+| requiresConfirmation | boolean  | Requires confirmation before calling      |
+|     isQuickDial      | boolean  | Mark as quick dial                        |
+|    additionalInfo    |  string  | Additional information                    |
+
+**Sample Data:**
+
+```json
+[
+  {
+    "id": "ec1",
+    "name": "Police Emergency",
+    "shortName": "911",
+    "description": "General police emergency number.",
+    "categoryIds": ["ecat1"],
+    "phoneNumber": "911",
+    "country": "United States",
+    "isNational": true,
+    "availability": "24/7",
+    "languages": ["en"],
+    "isTextCapable": true,
+    "isVideoCallCapable": false,
+    "isActive": true,
+    "isVerified": true,
+    "priority": 1
+  },
+  {
+    "id": "ec2",
+    "name": "Fire Department",
+    "shortName": "101",
+    "description": "Fire and rescue emergency number.",
+    "categoryIds": ["ecat2"],
+    "phoneNumber": "101",
+    "country": "United States",
+    "isNational": true,
+    "availability": "24/7",
+    "languages": ["en"],
+    "isTextCapable": false,
+    "isVideoCallCapable": false,
+    "isActive": true,
+    "isVerified": true,
+    "priority": 2
+  }
+]
+```
+
+### Relationship: Category & Emergency Contact
+
+- Each **EmergencyContact** can belong to one or more **EmergencyContactCategory** (many-to-many).
+- Categories are hierarchical, supporting parent-child relationships for flexible grouping (e.g., "Medical" > "Poison Control").
+
+**Example:**
+
+```json
+{
+  "category": {
+    "id": "ecat1",
+    "title": "Police"
+  },
+  "contacts": [
+    {
+      "id": "ec1",
+      "name": "Police Emergency",
+      "categoryIds": ["ecat1"]
+    }
+  ]
+}
+```
+
+> 💡 **Tip:** Use these entities to manage public emergency numbers for any country, region, or city, with full support for categorization, localization, and advanced filtering.
+
 ## Integration Examples
 
 ### Complete Contact Profile

package/contact-management/index.d.ts

@@ -16,7 +16,6 @@ declare const RootConfig: {
         i18n: string;
     };
     module: {
-        module: string;
         name: string;
         title: string;
         icon: string;
@@ -70,6 +69,18 @@ declare const RootConfig: {
             titlePlural: string;
             icon: string;
         };
+        emergencyContactCategory: {
+            name: string;
+            title: string;
+            titlePlural: string;
+            icon: string;
+        };
+        emergencyContact: {
+            name: string;
+            title: string;
+            titlePlural: string;
+            icon: string;
+        };
     };
 };
 
@@ -130,7 +141,7 @@ declare class AXMContactServiceImpl extends AXMContactService {
 declare function contactTypeFactory(injector: Injector): Promise<AXPEntity | null>;
 
 interface AXMContactManagementContactTypeEntityModel extends AXPEntityModel<string> {
-    name: string;
+    title: string;
     description?: string;
     icon?: string;
     isDefault: boolean;
@@ -147,7 +158,7 @@ declare class AXMContactTypeServiceImpl extends AXMContactTypeService {
 }
 
 interface AXMContactManagementContactSourceEntityModel extends AXPEntityModel<string> {
-    name: string;
+    title: string;
     description?: string;
     icon?: string;
     isDefault: boolean;
@@ -166,7 +177,7 @@ declare class AXMContactSourceServiceImpl extends AXMContactSourceService {
 declare function contactMethodTypeFactory(injector: Injector): Promise<AXPEntity | null>;
 
 interface AXMContactManagementContactMethodTypeEntityModel extends AXPEntityModel<string> {
-    name: string;
+    title: string;
     description?: string;
     icon?: string;
     validationRegex?: string;