@memberjunction/ng-explorer-core 2.43.0 → 2.44.0

package/README.md

@@ -2,17 +2,24 @@
 
 The `@memberjunction/ng-explorer-core` package provides the core components and infrastructure for the MemberJunction Explorer application. It serves as the foundation for building a complete data exploration and management interface based on MemberJunction entities.
 
+## Overview
+
+Explorer Core is a comprehensive Angular library that implements the MemberJunction Explorer application's core functionality. It provides a dynamic resource-based architecture for managing entities, records, reports, dashboards, queries, and other data resources within the MemberJunction ecosystem.
+
 ## Features
 
-- Resource container architecture for dynamic loading of components
-- Navigation and browsing components for entity records, reports, dashboards, and queries
-- Resource wrapper components that facilitate consistent display of different resource types
-- Header, navigation, and UI structure components
-- Authentication and user profile components
-- Home screen and application components
-- Dashboard builder and viewer components
-- Form toolbar and common UI patterns
-- Integration with MemberJunction's metadata system
+- **Dynamic Resource Container Architecture**: Loads components at runtime based on resource type
+- **Complete Navigation System**: Drawer-based navigation with workspace and tab management
+- **Entity Management**: Browse, view, create, edit, and delete entity records
+- **Dashboard System**: Create, edit, and view interactive dashboards
+- **Report Integration**: Display and manage reports
+- **Query Support**: Execute and display query results
+- **Search Integration**: Unified search results display
+- **User Views**: Support for custom user-defined views
+- **Authentication**: Built-in authentication components and guards
+- **Responsive Design**: Mobile-friendly UI that adapts to different screen sizes
+- **Workspace Management**: Persistent workspace with saved tabs and state
+- **Event-Driven Architecture**: Comprehensive event system for component communication
 
 ## Installation
 
@@ -22,158 +29,435 @@ npm install @memberjunction/ng-explorer-core
 
 ## Requirements
 
-- Angular 18+
-- MemberJunction core libraries (@memberjunction/core, @memberjunction/core-entities)
-- Various MemberJunction UI components
-- Kendo UI Angular components
+- Angular 18.0.2 or higher
+- MemberJunction core libraries:
+  - `@memberjunction/core` v2.43.0+
+  - `@memberjunction/core-entities` v2.43.0+
+  - `@memberjunction/global` v2.43.0+
+- Kendo UI for Angular v16.2.0+
+- TypeScript 4.9+
 
-## Usage
+## Basic Setup
 
-### Basic Setup
+### Module Import
 
-Import the ExplorerCoreModule in your application module:
+Import the `ExplorerCoreModule` in your application module:
 
 ```typescript
+import { NgModule } from '@angular/core';
+import { BrowserModule } from '@angular/platform-browser';
 import { ExplorerCoreModule } from '@memberjunction/ng-explorer-core';
 
 @NgModule({
+  declarations: [AppComponent],
   imports: [
-    // other imports...
+    BrowserModule,
     ExplorerCoreModule
   ],
+  bootstrap: [AppComponent]
 })
 export class AppModule { }
 ```
 
-### Resource Container Architecture
+### Routing Configuration
 
-The core of the Explorer is built on a resource container architecture that dynamically loads components based on resource type:
+The Explorer Core module includes its own routing configuration. You can integrate it with your application's routing:
 
-```html
-<mj-resource
-  [Data]="resourceData"
-  [isVisible]="activeResourceId === resourceData.ID"
-  (ResourceRecordSaved)="handleResourceSaved($event)"
-  (ContentLoadingStarted)="handleLoadingStarted($event)"
-  (ContentLoadingComplete)="handleLoadingComplete($event)">
-</mj-resource>
+```typescript
+import { Routes } from '@angular/router';
+import { AuthGuardService } from '@memberjunction/ng-explorer-core';
+
+const routes: Routes = [
+  {
+    path: '',
+    canActivate: [AuthGuardService],
+    loadChildren: () => import('@memberjunction/ng-explorer-core').then(m => m.ExplorerCoreModule)
+  }
+];
 ```
 
-Where resourceData is a ResourceData object that includes configuration for loading the appropriate component.
+## Core Components
+
+### Resource Container Component
+
+The heart of the Explorer architecture, dynamically loading components based on resource type:
+
+```typescript
+import { Component } from '@angular/core';
+import { ResourceData } from '@memberjunction/core-entities';
+
+@Component({
+  template: `
+    <mj-resource
+      [Data]="resourceData"
+      [isVisible]="isActive"
+      (ResourceRecordSaved)="onResourceSaved($event)"
+      (ContentLoadingStarted)="onLoadingStarted($event)"
+      (ContentLoadingComplete)="onLoadingComplete($event)">
+    </mj-resource>
+  `
+})
+export class MyComponent {
+  resourceData: ResourceData = {
+    ID: 'unique-id',
+    Name: 'My Resource',
+    ResourceType: 'Records',
+    ResourceRecordID: '123',
+    Configuration: {
+      Entity: 'Contacts'
+    }
+  };
+  
+  isActive = true;
+  
+  onResourceSaved(entity: BaseEntity) {
+    console.log('Resource saved:', entity);
+  }
+  
+  onLoadingStarted(container: ResourceContainerComponent) {
+    console.log('Loading started');
+  }
+  
+  onLoadingComplete(container: ResourceContainerComponent) {
+    console.log('Loading complete');
+  }
+}
+```
 
 ### Navigation Component
 
-The navigation component provides the main menu structure:
+Provides the main application navigation with workspace and tab management:
 
-```html
-<mj-navigation
-  [selectedItem]="currentNavigationItem"
-  (itemSelected)="handleNavigationItemSelected($event)">
-</mj-navigation>
+```typescript
+@Component({
+  template: `
+    <mj-navigation 
+      [applicationName]="'My Application'">
+    </mj-navigation>
+  `
+})
+export class AppComponent { }
 ```
 
 ### Home Component
 
-The home component serves as the landing page for the application:
+Displays navigation items configured to show on the home screen:
 
-```html
-<mj-home></mj-home>
+```typescript
+@Component({
+  template: `<mj-home></mj-home>`
+})
+export class HomePageComponent { }
 ```
 
-### Entity and Record Management
+### Entity Management Components
 
-For displaying and managing entity records:
+#### Entity Browser
+```typescript
+@Component({
+  template: `
+    <mj-single-entity 
+      [entityName]="'Contacts'"
+      [viewID]="viewId">
+    </mj-single-entity>
+  `
+})
+export class EntityBrowserComponent {
+  viewId?: string; // Optional view ID
+}
+```
 
-```html
-<mj-single-entity [entityName]="entityName"></mj-single-entity>
-<mj-single-record [entityName]="entityName" [PrimaryKey]="recordKey"></mj-single-record>
+#### Record Editor
+```typescript
+@Component({
+  template: `
+    <mj-single-record 
+      [entityName]="'Contacts'"
+      [PrimaryKey]="recordKey"
+      [newRecordValues]="defaultValues"
+      (recordSaved)="onRecordSaved($event)"
+      (loadComplete)="onLoadComplete()">
+    </mj-single-record>
+  `
+})
+export class RecordEditorComponent {
+  recordKey = new CompositeKey([{ FieldName: 'ID', Value: '123' }]);
+  defaultValues = { CompanyID: 1 }; // For new records
+  
+  onRecordSaved(entity: BaseEntity) {
+    console.log('Record saved:', entity);
+  }
+  
+  onLoadComplete() {
+    console.log('Record loaded');
+  }
+}
 ```
 
 ### Dashboard Components
 
-For displaying and managing dashboards:
-
-```html
-<mj-single-dashboard [dashboardId]="dashboardId"></mj-single-dashboard>
+```typescript
+@Component({
+  template: `
+    <mj-single-dashboard 
+      [dashboardId]="dashboardId"
+      [editMode]="false">
+    </mj-single-dashboard>
+  `
+})
+export class DashboardViewerComponent {
+  dashboardId = '456';
+}
 ```
 
-## Architecture
+### Form Toolbar
 
-### Resource Wrappers
+Provides consistent form actions across the application:
 
-The Explorer is built on a resource wrapper pattern where different types of content (records, reports, dashboards, etc.) are wrapped in specialized components that handle their specific requirements:
+```typescript
+@Component({
+  template: `
+    <mj-form-toolbar
+      [record]="entity"
+      [EditMode]="true"
+      (SaveRecord)="save()"
+      (DeleteRecord)="delete()"
+      (CancelEdit)="cancel()">
+    </mj-form-toolbar>
+  `
+})
+export class FormComponent {
+  entity: BaseEntity;
+  
+  save() { /* Save logic */ }
+  delete() { /* Delete logic */ }
+  cancel() { /* Cancel logic */ }
+}
+```
 
-- `EntityRecordResource` - For displaying and editing entity records
-- `ReportResource` - For displaying and managing reports
-- `DashboardResource` - For displaying dashboards
-- `QueryResource` - For displaying query results
-- `SearchResultsResource` - For displaying search results
-- `UserViewResource` - For displaying custom user views
-- `ListDetailResource` - For displaying list-detail interfaces
+## Resource Types and Wrappers
 
-### Component Registration
+The Explorer supports multiple resource types through specialized wrapper components:
 
-Components register themselves with MemberJunction's class factory system:
+### Creating Custom Resource Types
 
 ```typescript
-@RegisterClass(BaseResourceComponent, 'ResourceType')
+import { Component } from '@angular/core';
+import { RegisterClass } from '@memberjunction/global';
+import { BaseResourceComponent } from '@memberjunction/ng-shared';
+
+@RegisterClass(BaseResourceComponent, 'CustomResource')
 @Component({
-  selector: 'mj-example-resource',
-  template: `...`
+  selector: 'mj-custom-resource',
+  template: `
+    <div class="custom-resource">
+      <h2>{{ Data.Name }}</h2>
+      <!-- Custom resource implementation -->
+    </div>
+  `
 })
-export class ExampleResource extends BaseResourceComponent {
-  // Component implementation
+export class CustomResource extends BaseResourceComponent {
+  async GetResourceDisplayName(data: ResourceData): Promise<string> {
+    return `Custom: ${data.Name}`;
+  }
+  
+  async GetResourceIconClass(data: ResourceData): Promise<string> {
+    return 'fa-solid fa-star';
+  }
 }
 ```
 
-This allows the `ResourceContainerComponent` to dynamically load the appropriate component based on the resource type.
+### Built-in Resource Types
 
-## Key Components
+- **Records**: Entity record viewing and editing
+- **Reports**: Report display and execution
+- **Dashboards**: Interactive dashboard display
+- **Queries**: Query execution and results
+- **UserViews**: Custom user-defined views
+- **SearchResults**: Unified search results
+- **ListDetail**: Master-detail layouts
 
-### Resource Container
+## Event System
 
-The `ResourceContainerComponent` is the core of the dynamic loading system, using Angular's ViewContainerRef to create components at runtime.
+The Explorer uses a comprehensive event system for component communication:
 
-### Form Toolbar
+```typescript
+import { MJGlobal, MJEventType } from '@memberjunction/global';
+import { EventCodes } from '@memberjunction/ng-shared';
+
+// Subscribe to events
+const subscription = MJGlobal.Instance.GetEventListener(false)
+  .subscribe((event) => {
+    if (event.eventCode === EventCodes.ComponentEvent) {
+      console.log('Component event:', event.args);
+    }
+  });
+
+// Emit events
+MJGlobal.Instance.RaiseEvent({
+  eventCode: EventCodes.ComponentEvent,
+  eventType: MJEventType.ComponentEvent,
+  sourceComponent: this,
+  args: { action: 'save', entityName: 'Contacts' }
+});
+```
 
-The `FormToolbarComponent` provides a consistent interface for form actions like save, delete, and cancel.
+## Authentication and Guards
 
-### Home Component
+### Auth Guard Service
 
-The `HomeComponent` serves as the landing page for the application, displaying navigation items marked for home screen display.
+```typescript
+import { Routes } from '@angular/router';
+import { AuthGuardService } from '@memberjunction/ng-explorer-core';
+
+const routes: Routes = [
+  {
+    path: 'secure',
+    canActivate: [AuthGuardService],
+    component: SecureComponent
+  }
+];
+```
 
-### Navigation Component
+### Entities Guard
 
-The `NavigationComponent` provides the main menu structure based on the Explorer navigation items defined in the metadata.
+```typescript
+import { EntitiesGuard } from '@memberjunction/ng-explorer-core';
+
+const routes: Routes = [
+  {
+    path: 'entities/:entityName',
+    canActivate: [EntitiesGuard],
+    component: EntityComponent
+  }
+];
+```
 
-### Single Entity/Record Components
+## Advanced Features
 
-These components display entity lists and individual records, handling all CRUD operations.
+### Workspace Management
 
-### Dashboard Components
+The Explorer automatically manages workspace state, including:
+- Open tabs and their state
+- Navigation history
+- User preferences
+- Resource configurations
+
+### Tab Management
+
+```typescript
+// Access tab management through the navigation component
+@ViewChild(NavigationComponent) navigation: NavigationComponent;
+
+// Open a new tab
+this.navigation.openTab({
+  label: 'New Contact',
+  icon: 'fa-user',
+  data: {
+    resourceType: 'Records',
+    entityName: 'Contacts',
+    recordId: 'new'
+  }
+});
+```
+
+### Custom Expansion Panels
+
+```typescript
+@Component({
+  template: `
+    <mj-expansion-panel
+      [title]="'Advanced Options'"
+      [expanded]="false"
+      (expandedChange)="onExpandedChange($event)">
+      <!-- Panel content -->
+    </mj-expansion-panel>
+  `
+})
+export class MyPanelComponent { }
+```
+
+## Build Scripts
+
+```json
+{
+  "scripts": {
+    "build": "ngc",
+    "watch": "ngc -w",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  }
+}
+```
+
+## Development
+
+### Building the Package
+
+```bash
+# Build the package
+npm run build
+
+# Watch mode for development
+npm run watch
+```
+
+### Package Structure
+
+```
+explorer-core/
+├── src/
+│   ├── lib/
+│   │   ├── auth-button/
+│   │   ├── dashboard-browser-component/
+│   │   ├── generic/
+│   │   ├── guards/
+│   │   ├── header/
+│   │   ├── home-component/
+│   │   ├── navigation/
+│   │   ├── resource-wrappers/
+│   │   ├── single-dashboard/
+│   │   ├── single-entity/
+│   │   ├── single-record/
+│   │   └── ...
+│   ├── generic/
+│   ├── shared/
+│   ├── module.ts
+│   └── public-api.ts
+├── package.json
+└── tsconfig.json
+```
+
+## Integration with Other MJ Packages
+
+The Explorer Core integrates seamlessly with:
+
+- **@memberjunction/ng-auth-services**: Authentication and authorization
+- **@memberjunction/ng-container-directives**: Layout management
+- **@memberjunction/ng-entity-permissions**: Entity-level permissions
+- **@memberjunction/ng-file-storage**: File upload and management
+- **@memberjunction/ng-record-changes**: Audit trail functionality
+- **@memberjunction/ng-user-view-grid**: Data grid components
+- **@memberjunction/ng-skip-chat**: AI chat integration
+- **@memberjunction/ng-dashboards**: Dashboard creation and management
+- **@memberjunction/ng-resource-permissions**: Resource-level permissions
+
+## Best Practices
 
-Components for creating, editing, and viewing dashboards with support for multiple dashboard items.
+1. **Resource Loading**: Always check `isVisible` before loading heavy resources
+2. **Event Handling**: Unsubscribe from events in `ngOnDestroy`
+3. **Tab Management**: Limit concurrent tabs to maintain performance
+4. **Entity Access**: Use metadata to check entity permissions before operations
+5. **Error Handling**: Implement proper error handling for all async operations
 
-## Integration
+## Troubleshooting
 
-This package integrates with many other MemberJunction packages including:
+### Common Issues
 
-- Auth services for authentication
-- Container directives for layout management
-- Entity permissions for access control
-- File storage for document management
-- Record changes for audit trail
-- User view grid for data display
-- Skip Chat for AI integration
+1. **Resource not loading**: Ensure the resource type is properly registered
+2. **Navigation errors**: Check route configuration and guards
+3. **Missing icons**: Verify Font Awesome is properly loaded
+4. **Performance issues**: Review tab count and resource loading strategies
 
-## Dependencies
+## License
 
-- @angular/common
-- @angular/core
-- @angular/forms
-- @angular/router
-- @memberjunction/global
-- @memberjunction/core
-- @memberjunction/core-entities
-- Various MemberJunction UI component packages
-- Kendo UI Angular components
+ISC License - see LICENSE file for details

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memberjunction/ng-explorer-core",
-  "version": "2.43.0",
+  "version": "2.44.0",
   "description": "MemberJunction Explorer: Core Angular Components",
   "main": "./dist/public-api.js",
   "typings": "./dist/public-api.d.ts",
@@ -26,30 +26,30 @@
     "@angular/router": "18.0.2"
   },
   "dependencies": {
-    "@memberjunction/global": "2.43.0",
-    "@memberjunction/core": "2.43.0",
-    "@memberjunction/core-entities": "2.43.0",
-    "@memberjunction/entity-communications-client": "2.43.0",
-    "@memberjunction/communication-types": "2.43.0",
-    "@memberjunction/templates-base-types": "2.43.0",
-    "@memberjunction/ng-compare-records": "2.43.0",
-    "@memberjunction/ng-file-storage": "2.43.0",
-    "@memberjunction/ng-record-changes": "2.43.0",
-    "@memberjunction/ng-container-directives": "2.43.0",
-    "@memberjunction/ng-user-view-grid": "2.43.0",
-    "@memberjunction/ng-query-grid": "2.43.0",
-    "@memberjunction/ng-user-view-properties": "2.43.0",
-    "@memberjunction/ng-shared": "2.43.0",
-    "@memberjunction/ng-tabstrip": "2.43.0",
-    "@memberjunction/ng-skip-chat": "2.43.0",
-    "@memberjunction/ng-ask-skip": "2.43.0",
-    "@memberjunction/ng-auth-services": "2.43.0",
-    "@memberjunction/ng-explorer-settings": "2.43.0",
-    "@memberjunction/ng-base-forms": "2.43.0",
-    "@memberjunction/ng-entity-form-dialog": "2.43.0",
-    "@memberjunction/ng-record-selector": "2.43.0",
-    "@memberjunction/ng-resource-permissions": "2.43.0",
-    "@memberjunction/ng-dashboards": "2.43.0",
+    "@memberjunction/global": "2.44.0",
+    "@memberjunction/core": "2.44.0",
+    "@memberjunction/core-entities": "2.44.0",
+    "@memberjunction/entity-communications-client": "2.44.0",
+    "@memberjunction/communication-types": "2.44.0",
+    "@memberjunction/templates-base-types": "2.44.0",
+    "@memberjunction/ng-compare-records": "2.44.0",
+    "@memberjunction/ng-file-storage": "2.44.0",
+    "@memberjunction/ng-record-changes": "2.44.0",
+    "@memberjunction/ng-container-directives": "2.44.0",
+    "@memberjunction/ng-user-view-grid": "2.44.0",
+    "@memberjunction/ng-query-grid": "2.44.0",
+    "@memberjunction/ng-user-view-properties": "2.44.0",
+    "@memberjunction/ng-shared": "2.44.0",
+    "@memberjunction/ng-tabstrip": "2.44.0",
+    "@memberjunction/ng-skip-chat": "2.44.0",
+    "@memberjunction/ng-ask-skip": "2.44.0",
+    "@memberjunction/ng-auth-services": "2.44.0",
+    "@memberjunction/ng-explorer-settings": "2.44.0",
+    "@memberjunction/ng-base-forms": "2.44.0",
+    "@memberjunction/ng-entity-form-dialog": "2.44.0",
+    "@memberjunction/ng-record-selector": "2.44.0",
+    "@memberjunction/ng-resource-permissions": "2.44.0",
+    "@memberjunction/ng-dashboards": "2.44.0",
     "@progress/kendo-angular-grid": "16.2.0",
     "@progress/kendo-angular-buttons": "16.2.0",
     "@progress/kendo-angular-listview": "16.2.0",