@memberjunction/explorer

The @memberjunction/explorer package provides the primary user interface for the MemberJunction platform. It's a feature-rich web application that allows users to browse, search, and interact with data stored in the MemberJunction system.

Overview

MemberJunction Explorer is an advanced tool for power users to navigate, browse, and search their unified data. It offers a modern, responsive interface with powerful data visualization, reporting, and management capabilities.

Key Features

Entity Browse and Search: Navigate and search through all entities in the system
Record Management: Create, read, update, and delete entity records
Dynamic Views: Create custom views with filtering, sorting, and field selection
Dashboards: Build interactive dashboards with charts and visualizations
Reports: Generate and export reports in various formats
User Management: Administer users, roles, and permissions
Skip AI Integration: Interact with data using natural language (requires Skip license)

Components

Explorer Application

The Explorer application is the main container for all UI components:

class ExplorerApplication {
  // Initialization
  public static initialize(config: ExplorerConfig): Promise<void>;
  
  // Navigation
  public static navigateToEntity(entityName: string): void;
  public static navigateToRecord(entityName: string, recordId: any): void;
  
  // UI state management
  public static showDialog(dialog: Dialog): void;
  public static showNotification(notification: Notification): void;
  
  // Application lifecycle
  public static async start(): Promise<void>;
  public static async stop(): Promise<void>;
}

ExplorerConfig

ExplorerConfig defines the configuration for the Explorer application:

interface ExplorerConfig {
  // API configuration
  apiUrl: string;
  graphqlUrl: string;
  
  // Authentication configuration
  authProvider: AuthenticationProvider;
  
  // UI configuration
  theme: ThemeConfig;
  layout: LayoutConfig;
  
  // Feature flags
  features: {
    skipEnabled: boolean;
    dashboardsEnabled: boolean;
    reportsEnabled: boolean;
    adminEnabled: boolean;
  };
  
  // Customization
  customComponents?: Record<string, ComponentType>;
  customMenuItems?: MenuItem[];
}

EntityBrowser

The EntityBrowser component displays a list of records for an entity:

class EntityBrowser {
  // Constructor
  constructor(entityName: string, viewId?: string);
  
  // View methods
  public loadView(viewId: string): Promise<void>;
  public saveView(view: View): Promise<string>;
  
  // Data loading
  public loadData(filter?: Filter[], sort?: Sort[]): Promise<void>;
  public refresh(): Promise<void>;
  
  // Selection
  public getSelectedRecords(): any[];
  public selectRecord(recordId: any): void;
  
  // Actions
  public createRecord(): void;
  public editRecord(recordId: any): void;
  public deleteRecord(recordId: any): Promise<boolean>;
  public exportData(format: ExportFormat): Promise<void>;
}

RecordEditor

The RecordEditor component allows editing of entity records:

class RecordEditor {
  // Constructor
  constructor(entityName: string, recordId?: any);
  
  // Lifecycle methods
  public async load(): Promise<void>;
  public async save(): Promise<boolean>;
  
  // Validation
  public validate(): ValidationResult;
  
  // Field management
  public setFieldValue(fieldName: string, value: any): void;
  public getFieldValue(fieldName: string): any;
  
  // Related records
  public loadRelatedRecords(relationshipName: string): Promise<any[]>;
  public addRelatedRecord(relationshipName: string, recordId: any): Promise<void>;
  public removeRelatedRecord(relationshipName: string, recordId: any): Promise<void>;
}

ViewController

The ViewController manages custom views for entities:

class ViewController {
  // Constructor
  constructor(entityName: string);
  
  // View management
  public async getViews(): Promise<View[]>;
  public async getView(viewId: string): Promise<View>;
  public async saveView(view: View): Promise<string>;
  public async deleteView(viewId: string): Promise<boolean>;
  
  // Default views
  public async getDefaultView(): Promise<View>;
  public async setDefaultView(viewId: string): Promise<void>;
  
  // View folders
  public async getFolders(): Promise<ViewFolder[]>;
  public async createFolder(folder: ViewFolder): Promise<string>;
}

DashboardManager

The DashboardManager handles dashboard creation and management:

class DashboardManager {
  // Dashboard retrieval
  public async getDashboards(): Promise<Dashboard[]>;
  public async getDashboard(dashboardId: string): Promise<Dashboard>;
  
  // Dashboard CRUD
  public async createDashboard(dashboard: Dashboard): Promise<string>;
  public async updateDashboard(dashboard: Dashboard): Promise<boolean>;
  public async deleteDashboard(dashboardId: string): Promise<boolean>;
  
  // Dashboard components
  public async addComponent(dashboardId: string, component: DashboardComponent): Promise<string>;
  public async updateComponent(dashboardId: string, component: DashboardComponent): Promise<boolean>;
  public async removeComponent(dashboardId: string, componentId: string): Promise<boolean>;
}

ReportGenerator

The ReportGenerator handles report creation and export:

class ReportGenerator {
  // Constructor
  constructor(reportDefinition: ReportDefinition);
  
  // Report generation
  public async generateReport(): Promise<ReportResult>;
  
  // Export formats
  public async exportToPdf(): Promise<Blob>;
  public async exportToCsv(): Promise<Blob>;
  public async exportToExcel(): Promise<Blob>;
  
  // Scheduling
  public async scheduleReport(schedule: ReportSchedule): Promise<string>;
}

AdminConsole

The AdminConsole provides administration functionality:

class AdminConsole {
  // User management
  public async getUsers(): Promise<User[]>;
  public async createUser(user: User): Promise<string>;
  public async updateUser(user: User): Promise<boolean>;
  public async deleteUser(userId: string): Promise<boolean>;
  
  // Role management
  public async getRoles(): Promise<Role[]>;
  public async createRole(role: Role): Promise<string>;
  public async updateRole(role: Role): Promise<boolean>;
  public async deleteRole(roleId: string): Promise<boolean>;
  
  // Permission management
  public async getPermissions(): Promise<Permission[]>;
  public async setPermission(entityName: string, roleId: string, permission: PermissionType): Promise<boolean>;
  
  // System settings
  public async getSettings(): Promise<SystemSettings>;
  public async updateSettings(settings: SystemSettings): Promise<boolean>;
}

SkipInterface

The SkipInterface component provides integration with the Skip AI assistant:

class SkipInterface {
  // Query methods
  public async askQuestion(question: string): Promise<SkipResponse>;
  public async generateReport(prompt: string): Promise<ReportDefinition>;
  
  // Conversation management
  public getConversationHistory(): SkipMessage[];
  public clearConversation(): void;
  
  // UI components
  public renderChatInterface(): JSX.Element;
  public renderDataVisualization(data: any, visualizationType: string): JSX.Element;
}

User Interface Components

EntityList

The EntityList component displays a list of available entities:

function EntityList(props: EntityListProps): JSX.Element;

interface EntityListProps {
  filter?: string;
  onEntitySelect?: (entityName: string) => void;
  showFavorites?: boolean;
  groupByCategory?: boolean;
}

DataGrid

The DataGrid component displays tabular data with sorting and filtering:

function DataGrid(props: DataGridProps): JSX.Element;

interface DataGridProps {
  entityName: string;
  columns: ColumnDefinition[];
  data?: any[];
  loading?: boolean;
  selectionMode?: 'none' | 'single' | 'multiple';
  onRowClick?: (row: any) => void;
  onSelectionChange?: (selectedRows: any[]) => void;
  pagination?: PaginationOptions;
}

RecordForm

The RecordForm component provides a form for editing entity records:

function RecordForm(props: RecordFormProps): JSX.Element;

interface RecordFormProps {
  entityName: string;
  recordId?: any;
  mode?: 'view' | 'edit' | 'create';
  onSave?: (savedRecord: any) => void;
  onCancel?: () => void;
  customFields?: CustomFieldConfig[];
}

FilterBuilder

The FilterBuilder component allows users to create complex filters:

function FilterBuilder(props: FilterBuilderProps): JSX.Element;

interface FilterBuilderProps {
  entityName: string;
  initialFilter?: Filter[];
  onChange?: (filter: Filter[]) => void;
  onApply?: (filter: Filter[]) => void;
  showApplyButton?: boolean;
}

ChartComponent

The ChartComponent renders various chart types:

function ChartComponent(props: ChartProps): JSX.Element;

interface ChartProps {
  type: 'bar' | 'line' | 'pie' | 'scatter' | 'area';
  data: ChartData;
  options?: ChartOptions;
  height?: number;
  width?: number;
  onDataPointClick?: (point: any) => void;
}

DashboardDesigner

The DashboardDesigner component provides a drag-and-drop interface for creating dashboards:

function DashboardDesigner(props: DashboardDesignerProps): JSX.Element;

interface DashboardDesignerProps {
  dashboardId?: string;
  initialLayout?: LayoutConfig;
  availableComponents?: ComponentDefinition[];
  onSave?: (dashboard: Dashboard) => void;
}

Usage Examples

Initializing the Explorer

import { ExplorerApplication } from '@memberjunction/explorer';
import { MsalAuthProvider } from '@memberjunction/msal-auth';

// Create an authentication provider
const authProvider = new MsalAuthProvider({
  clientId: 'your-client-id',
  tenantId: 'your-tenant-id',
  redirectUri: 'http://localhost:3000/auth/callback'
});

// Configure the Explorer
ExplorerApplication.initialize({
  apiUrl: 'http://localhost:3001/api',
  graphqlUrl: 'http://localhost:4000/graphql',
  authProvider: authProvider,
  theme: {
    primaryColor: '#3f51b5',
    secondaryColor: '#f50057',
    darkMode: false
  },
  features: {
    skipEnabled: true,
    dashboardsEnabled: true,
    reportsEnabled: true,
    adminEnabled: true
  }
})
.then(() => {
  // Start the application
  ExplorerApplication.start();
})
.catch(error => {
  console.error('Failed to initialize Explorer:', error);
});

Using the EntityBrowser

import { EntityBrowser } from '@memberjunction/explorer';

// Create an entity browser for Members
const browser = new EntityBrowser('Member');

// Load data with filtering
browser.loadData([
  { fieldName: 'Status', operator: 'eq', value: 'Active' }
])
.then(() => {
  console.log('Data loaded successfully');
})
.catch(error => {
  console.error('Failed to load data:', error);
});

// Handle row selection
browser.onRowSelect = (record) => {
  console.log('Selected record:', record);
  
  // Navigate to the record detail
  ExplorerApplication.navigateToRecord('Member', record.MemberID);
};

Using the RecordEditor

import { RecordEditor } from '@memberjunction/explorer';

// Create a record editor for editing a Member
const editor = new RecordEditor('Member', 123);

// Load the record
editor.load()
  .then(() => {
    console.log('Record loaded successfully');
    
    // Get field values
    const firstName = editor.getFieldValue('FirstName');
    const lastName = editor.getFieldValue('LastName');
    console.log(`Editing member: ${firstName} ${lastName}`);
    
    // Update field values
    editor.setFieldValue('Email', '[email protected]');
    
    // Save changes
    editor.save()
      .then(success => {
        if (success) {
          console.log('Record saved successfully');
        } else {
          console.error('Failed to save record:', editor.getValidationErrors());
        }
      });
  })
  .catch(error => {
    console.error('Failed to load record:', error);
  });

Creating a Custom View

import { ViewController } from '@memberjunction/explorer';

// Create a view controller for the Member entity
const viewController = new ViewController('Member');

// Create a custom view
const newView = {
  name: 'Active Members',
  description: 'Shows all active members',
  entityName: 'Member',
  filter: [
    { fieldName: 'Status', operator: 'eq', value: 'Active' }
  ],
  sort: [
    { fieldName: 'LastName', direction: 'asc' },
    { fieldName: 'FirstName', direction: 'asc' }
  ],
  fields: [
    'MemberID',
    'FirstName',
    'LastName',
    'Email',
    'JoinDate',
    'MembershipTypeID'
  ]
};

// Save the view
viewController.saveView(newView)
  .then(viewId => {
    console.log(`View saved with ID: ${viewId}`);
    
    // Set as default view
    return viewController.setDefaultView(viewId);
  })
  .then(() => {
    console.log('View set as default');
  })
  .catch(error => {
    console.error('Failed to save view:', error);
  });

Creating a Dashboard

import { DashboardManager } from '@memberjunction/explorer';

// Create a dashboard manager
const dashboardManager = new DashboardManager();

// Create a new dashboard
const newDashboard = {
  name: 'Membership Overview',
  description: 'Key metrics about membership',
  layout: {
    type: 'grid',
    columns: 12,
    rowHeight: 100
  },
  components: []
};

// Save the dashboard
dashboardManager.createDashboard(newDashboard)
  .then(dashboardId => {
    console.log(`Dashboard created with ID: ${dashboardId}`);
    
    // Add a chart component
    return dashboardManager.addComponent(dashboardId, {
      type: 'chart',
      name: 'Membership by Type',
      position: { x: 0, y: 0, width: 6, height: 4 },
      config: {
        chartType: 'pie',
        entityName: 'Member',
        aggregation: {
          field: 'MemberID',
          function: 'count'
        },
        groupBy: 'MembershipTypeID',
        filter: [
          { fieldName: 'Status', operator: 'eq', value: 'Active' }
        ]
      }
    });
  })
  .then(componentId => {
    console.log(`Component added with ID: ${componentId}`);
  })
  .catch(error => {
    console.error('Failed to create dashboard:', error);
  });

Using the Skip Interface

import { SkipInterface } from '@memberjunction/explorer';

// Create a Skip interface
const skip = new SkipInterface();

// Ask a question
skip.askQuestion('How many active members do we have by region?')
  .then(response => {
    console.log('Skip response:', response);
    
    // Check if the response includes data visualization
    if (response.visualization) {
      // Render the visualization
      const visualizationElement = document.getElementById('visualization');
      skip.renderDataVisualization(
        response.data,
        response.visualization.type
      );
    }
  })
  .catch(error => {
    console.error('Failed to get response from Skip:', error);
  });

Customization

Custom Components

You can provide custom components to override the default UI:

import { ExplorerApplication } from '@memberjunction/explorer';
import { MyCustomEntityBrowser } from './components/MyCustomEntityBrowser';
import { MyCustomRecordEditor } from './components/MyCustomRecordEditor';

// Configure the Explorer with custom components
ExplorerApplication.initialize({
  // Other configuration...
  customComponents: {
    EntityBrowser: MyCustomEntityBrowser,
    RecordEditor: MyCustomRecordEditor
  }
});

Theme Customization

You can customize the visual appearance of the Explorer:

import { ExplorerApplication } from '@memberjunction/explorer';

// Configure the Explorer with a custom theme
ExplorerApplication.initialize({
  // Other configuration...
  theme: {
    primaryColor: '#2196f3',
    secondaryColor: '#ff9800',
    textColor: '#333333',
    backgroundColor: '#f5f5f5',
    errorColor: '#f44336',
    successColor: '#4caf50',
    warningColor: '#ff9800',
    infoColor: '#2196f3',
    darkMode: false,
    typography: {
      fontFamily: 'Roboto, sans-serif',
      fontSize: 14
    },
    shape: {
      borderRadius: 4
    }
  }
});

Custom Menu Items

You can add custom menu items to the Explorer:

import { ExplorerApplication } from '@memberjunction/explorer';

// Configure the Explorer with custom menu items
ExplorerApplication.initialize({
  // Other configuration...
  customMenuItems: [
    {
      id: 'custom-reports',
      label: 'Custom Reports',
      icon: 'bar_chart',
      onClick: () => {
        // Handle custom menu item click
        showCustomReportsDialog();
      }
    },
    {
      id: 'external-link',
      label: 'External System',
      icon: 'launch',
      href: 'https://external-system.example.com',
      target: '_blank'
    }
  ]
});

Integration with Other Packages

The Explorer package integrates with other MemberJunction packages:

@memberjunction/core: Uses core entities and metadata
@memberjunction/graphql-server: Communicates with the GraphQL API
@memberjunction/skip: Integrates with the Skip AI assistant
@memberjunction/global-types: Shares type definitions across packages
@memberjunction/msal-auth: Handles authentication with Microsoft Identity

Configuration

Configure the Explorer through environment variables or a configuration file:

{
  "explorer": {
    "apiUrl": "http://localhost:3001/api",
    "graphqlUrl": "http://localhost:4000/graphql",
    "features": {
      "skipEnabled": true,
      "dashboardsEnabled": true,
      "reportsEnabled": true,
      "adminEnabled": true
    },
    "theme": {
      "primaryColor": "#3f51b5",
      "secondaryColor": "#f50057",
      "darkMode": false
    }
  }
}

Deployment

The Explorer can be deployed as a standalone web application or embedded within another application.

Standalone Deployment

To deploy as a standalone application:

Build the Explorer application:
```
npm run build
```

Deploy the built files to a web server:

# Example deployment to Azure Static Web Apps
npx @azure/static-web-apps-cli deploy ./dist

Embedded Deployment

To embed the Explorer in another application:

import { ExplorerApplication, ExplorerContainer } from '@memberjunction/explorer';

// Initialize the Explorer
ExplorerApplication.initialize({
  // Configuration...
});

// In your React component
function MyApp() {
  return (
    <div>
      <h1>My Application</h1>
      <div className="explorer-container">
        <ExplorerContainer />
      </div>
    </div>
  );
}

Best Practices

Use Default Views: Create default views for common entity browsing scenarios
Optimize Data Loading: Use pagination and filters to improve performance
Create Role-Specific Dashboards: Tailor dashboards to user roles
Implement Field Security: Use field-level security for sensitive data
Provide Contextual Help: Add help text and tooltips to forms
Use Validation Rules: Implement client-side validation rules
Create Logical Navigation: Organize entities and views logically
Design for Mobile: Consider responsive design for mobile users
Cache Common Data: Implement caching strategies for frequently accessed data
Monitor Performance: Track and optimize slow operations

Resources

User Guide: Comprehensive user documentation
API Reference: Explorer component API documentation
Demo Videos: Video tutorials for common tasks
Sample Configurations: Example configuration files