@khester/create-dynamics-app 1.0.8 → 1.1.0

package/templates/dynamics-365-starter/README.md

@@ -1,178 +1,607 @@
-# Dynamics 365 Application
+# Dynamics 365 Enhanced Template
 
-This is a Dynamics 365 application built with Dynamics UI Kit components, featuring a complete contact management system.
+A sophisticated, enterprise-grade Dynamics 365 application template built with the Dynamics UI Kit.
+Features advanced entity management for Accounts and Contacts with comprehensive CRUD operations,
+smart environment detection, centralized logging, and optimized deployment capabilities.
 
-## Features
+## 🚀 Features
 
-- **Full CRUD Operations**: Create, read, update, and delete contacts
-- **Advanced UI Components**: Uses DetailsList, Dialog, Panel, and Form components
-- **PCF Integration**: Includes wrapper for PowerApps Component Framework
-- **Responsive Design**: Works on desktop and mobile devices
-- **Type Safety**: Full TypeScript support
+### **Dual Entity Management**
 
-## Getting Started
+- **Account Management**: Complete CRUD operations with industry codes, revenue tracking, and
+  address management
+- **Contact Management**: Full contact lifecycle with preferred contact methods and relationship
+  tracking
+- **Unified Interface**: Seamless navigation between Account and Contact management via tabbed
+  interface
 
-### Development
+### **Enterprise Architecture**
 
-1. **Install Dependencies**
-   ```bash
-   npm install
-   ```
+- **BaseEntity Pattern**: Abstract base class with static CRUD methods and validation
+- **ServiceFactory**: Smart environment detection (development vs production) with automatic API
+  service selection
+- **Centralized Logging**: Comprehensive logging system with debug UI and export capabilities
+- **Entity Constants**: Complete field dictionaries with metadata for type safety
 
-2. **Start Development Server**
-   ```bash
-   npm run dev
-   ```
-   This starts the development server at http://localhost:3000
+### **Advanced UI Components**
 
-3. **Build for Production**
-   ```bash
-   npm run build
-   ```
+- **Enhanced Forms**: Account and Contact forms with validation and error handling
+- **Interactive Debug Panel**: Real-time logging with filtering and export functionality
+- **Responsive Design**: Mobile-optimized layouts with accessibility features
+- **PCF Integration**: Multi-entity control wrapper for Dynamics 365 custom controls
 
-### PCF Integration
+### **Production-Ready Deployment**
 
-This project includes a PCF wrapper that allows you to use the contact management component as a custom control in Dynamics 365.
+- **Custom Build System**: D365-optimized webpack configuration with single-file output
+- **Multiple Deployment Targets**: Web Resources, PCF Controls, and Custom Pages
+- **Environment Detection**: Automatic MockApiService vs XrmApiService selection
+- **Performance Optimization**: Minified production builds with deployment guidance
 
-#### Setting up PCF
+## 🏁 Quick Start
 
-1. Install PCF CLI tools:
-   ```bash
-   npm install -g @microsoft/powerapps-cli
-   ```
+### Installation
 
-2. Create a new PCF project:
-   ```bash
-   pac pcf init --namespace YourNamespace --name ContactControl --template field
-   ```
+```bash
+# Using the CLI tool
+npx create-dynamics-app my-d365-app --template dynamics-365-starter
 
-3. Copy the built components to your PCF project and integrate using `ContactControlWrapper`
+# Or clone and install
+git clone <repository-url>
+cd dynamics-365-starter
+npm install
+```
+
+### Development
 
-## Project Structure
+```bash
+# Start development server with mock data
+npm start
+# Opens http://localhost:3000 with Account and Contact management
+
+# Build for development (unminified)
+npm run build:dev
+
+# Build for production (optimized for D365)
+npm run build:prod
+
+# Serve built files locally
+npm run serve
+```
+
+## 📋 Project Structure
 
 ```
 src/
-├── components/               # React components
-│   ├── ContactManagement.tsx # Main contact management interface
-│   ├── ContactForm.tsx       # Contact form component
-│   └── *.css                # Component styles
-├── providers/               # Context providers
-│   └── DynamicsProvider.tsx # Dynamics 365 API provider
-├── pcf/                    # PCF integration
-│   └── ContactControlWrapper.tsx # PCF wrapper component
-├── styles/                 # Global styles
-│   └── index.css          # Global CSS
-└── index.tsx              # Application entry point
-```
-
-## Key Components
-
-### ContactManagement
-The main component that provides:
-- Contact list with search and filtering
-- CRUD operations (Create, Read, Update, Delete)
-- Selection and bulk operations
-- Responsive data grid
-
-### ContactForm
-A reusable form component for:
-- Creating new contacts
-- Editing existing contacts
-- Form validation
-- Error handling
-
-### DynamicsProvider
-Context provider that:
-- Manages Dynamics 365 API connections
-- Provides CRUD operations
-- Handles authentication
-- Error management
-
-## Deployment Options
-
-### Option 1: Web Resource
-1. Build the application: `npm run build`
-2. Upload `dist/main.js` and `dist/main.css` as web resources
-3. Create an HTML web resource that includes these files
-4. Add the HTML web resource to your Dynamics 365 forms or dashboards
-
-### Option 2: PCF Custom Control
-1. Use the `ContactControlWrapper` in your PCF project
-2. Build and deploy as a PCF component
-3. Add the custom control to forms, views, or dashboards
-
-### Option 3: Canvas App
-1. Build the application and host it externally
-2. Embed in a Canvas App using an iframe
-3. Use Power Platform connectors for data access
-
-## Configuration
+├── components/
+│   ├── AccountManagement.tsx     # Account CRUD interface
+│   ├── AccountForm.tsx           # Account creation/editing form
+│   ├── ContactManagement.tsx     # Contact CRUD interface
+│   ├── ContactForm.tsx           # Contact creation/editing form
+│   └── Logging/                  # Centralized logging system
+│       ├── logger.ts             # Logger utility class
+│       ├── LoggingContext.tsx    # React context for logs
+│       ├── LoggingProvider.tsx   # Provider component
+│       └── LoggingDebugPanel.tsx # Debug UI with filtering
+├── models/
+│   ├── BaseEntity.ts             # Abstract base class with CRUD
+│   ├── Account.ts                # Account entity with validation
+│   └── Contact.ts                # Contact entity with validation
+├── constants/
+│   ├── account.ts                # Account field constants & metadata
+│   └── contact.ts                # Contact field constants & metadata
+├── services/
+│   ├── ServiceFactory.ts         # Environment-aware service factory
+│   ├── XrmApiService.ts          # Production Dynamics 365 API service
+│   └── MockApiService.ts         # Development mock service
+├── providers/
+│   └── DynamicsProvider.tsx      # API context with environment detection
+├── pcf/
+│   ├── ContactControlWrapper.tsx      # Single-entity PCF wrapper
+│   └── MultiEntityControlWrapper.tsx  # Multi-entity PCF wrapper
+├── scripts/
+│   └── custom-build.js           # D365-optimized build configuration
+├── styles/
+│   └── index.css                 # Global styles and responsive design
+└── index.tsx                     # Application entry with navigation
+```
+
+## 🏗️ Entity Model Architecture
+
+### BaseEntity Pattern
+
+All entities inherit from `BaseEntity` which provides:
+
+```typescript
+// Static CRUD methods with validation and logging
+export abstract class BaseEntity {
+  protected static async createEntity<T>(
+    apiService: IApiService,
+    entity: T,
+    entityCollectionName: string,
+    loggerContext: string
+  ): Promise<T>;
+
+  protected static async updateEntity<T>(...): Promise<T>;
+  protected static async deleteEntity(...): Promise<void>;
+  protected static async retrieveEntitiesByFilter<T>(...): Promise<T[]>;
+}
+```
+
+### Entity Implementation Example
+
+```typescript
+// Account entity with complete CRUD operations
+export class Account extends BaseEntity implements IAccount {
+  // Constructor and properties...
+
+  // Static CRUD methods
+  public static async create(apiService: IApiService, account: Account): Promise<Account> {
+    const loggerContext = 'Account.create';
+    console.log(`${loggerContext}: Creating new account`, { name: account.name });
+
+    return await this.createEntity<Account>(
+      apiService,
+      account,
+      AccountConstants.EntityCollectionName,
+      loggerContext
+    );
+  }
+
+  public static async retrieveActiveAccounts(apiService: IApiService): Promise<Account[]> {
+    // Built-in FetchXML generation and error handling
+    const filter = `<filter type="and">
+      <condition attribute="${AccountConstants.StateCode}" operator="eq" value="0" />
+    </filter>`;
+
+    return await this.retrieveByFilter(apiService, filter);
+  }
+
+  // Client-side validation
+  validate(): boolean {
+    if (!this.name || this.name.trim().length === 0) {
+      throw new Error('Account name is required');
+    }
+    // Additional validation rules...
+    return true;
+  }
+}
+```
+
+### Entity Constants
+
+Complete field dictionaries with metadata:
+
+```typescript
+export class AccountConstants {
+  /** Type: String, RequiredLevel: ApplicationRequired, MaxLength: 160 */
+  public static readonly PrimaryName: string = 'name';
+
+  /** Type: String, RequiredLevel: None, MaxLength: 100, Format: Email */
+  public static readonly EMailAddress1: string = 'emailaddress1';
+
+  /** Type: Money, RequiredLevel: None, MinValue: -922337203685477 */
+  public static readonly Revenue: string = 'revenue';
+}
+```
+
+## ⚙️ Service Factory & Environment Detection
+
+The `ServiceFactory` automatically detects the runtime environment:
+
+```typescript
+export class ServiceFactory {
+  // Automatic environment detection
+  public static get isMockEnvironment(): boolean {
+    const hostname = window.location.hostname;
+    return hostname === 'localhost' || hostname === '127.0.0.1';
+  }
+
+  // Smart API service creation
+  public static createApiService(Xrm?: any): IApiService {
+    if (this.isMockEnvironment) {
+      return new MockApiService(); // Development with mock data
+    }
+    return new XrmApiService(Xrm); // Production with Dynamics 365
+  }
+}
+```
+
+## 📊 Centralized Logging System
+
+Comprehensive logging with UI:
+
+```typescript
+// Logger usage throughout the application
+Logger.log('Application initialized', 'App');
+Logger.userAction('Contact created', { contactId: '123' }, 'ContactForm');
+Logger.error('API call failed', 'ContactManagement', error);
+Logger.apiOperation('CREATE', 'contact', contactData, 'ContactForm.submit');
+Logger.validation('Contact', ['Email is required'], 'ContactForm.validate');
+```
+
+The debug panel provides:
+
+- Real-time log viewing with level filtering
+- Search and export capabilities
+- Performance timing and API operation tracking
+- User action audit trail
+
+## 🎯 Deployment Options
+
+### 1. Dynamics 365 Web Resources
+
+**Optimal for**: Dashboard widgets, form sections, custom pages
+
+```bash
+# Build optimized for D365
+npm run build:d365
+
+# Upload generated files as web resources:
+# - dist/main.js → Script (JScript) web resource
+# - dist/index.html → Web Page (HTML) web resource
+# - Set "Available for Dynamics 365 mobile" if needed
+```
+
+The custom build process:
+
+- Disables code splitting for single-file deployment
+- Removes content hashes for consistent web resource naming
+- Optimizes bundle size and provides deployment guidance
+- Generates deployment info with asset details
+
+### 2. PCF Custom Controls
+
+**Optimal for**: Form controls, view extensions, embedded components
+
+#### Single Entity Control
+
+```typescript
+import { ContactControlWrapper } from './pcf/ContactControlWrapper';
+
+// In your PCF component
+export class ContactControl implements ComponentFramework.StandardControl<IInputs, IOutputs> {
+  public init(context: ComponentFramework.Context<IInputs>): void {
+    // Render ContactControlWrapper with PCF context
+    ReactDOM.render(React.createElement(ContactControlWrapper, { context }), this.container);
+  }
+}
+```
+
+#### Multi-Entity Control
+
+```typescript
+import { MultiEntityControlWrapper } from './pcf/MultiEntityControlWrapper';
+
+// Support both Account and Contact management in one control
+ReactDOM.render(
+  React.createElement(MultiEntityControlWrapper, {
+    context,
+    defaultEntity: 'contact',
+    showTabs: true,
+  }),
+  this.container
+);
+```
+
+### 3. Dynamics 365 Custom Pages
+
+**Optimal for**: Full-page applications, complex workflows
+
+```bash
+# Build for Custom Pages
+npm run build:prod
+
+# Deploy as model-driven app page:
+# 1. Upload main.js as web resource
+# 2. Create Custom Page in Power Apps
+# 3. Add HTML control with web resource reference
+```
+
+## 🔧 Configuration
 
 ### Environment Variables
-Create a `.env` file with:
+
+```bash
+# .env.local
+REACT_APP_D365_URL=https://yourorg.crm.dynamics.com
+REACT_APP_ENVIRONMENT=development
 ```
-DYNAMICS_BASE_URL=https://yourorg.crm.dynamics.com
-DYNAMICS_ACCESS_TOKEN=your_access_token
+
+### API Service Configuration
+
+```typescript
+// Automatic configuration via ServiceFactory
+const DynamicsProvider: React.FC = ({ children }) => {
+  useEffect(() => {
+    // ServiceFactory handles environment detection
+    const xrmObject = ServiceFactory.isDynamics365Context() ? window.Xrm : undefined;
+    const service = ServiceFactory.createApiService(xrmObject);
+    setApiService(service);
+  }, []);
+
+  // Provider implementation...
+};
 ```
 
-### API Configuration
-The `DynamicsProvider` can be configured with:
-- `baseUrl`: Your Dynamics 365 organization URL
-- `accessToken`: Authentication token
-- Custom API service implementations
+### PCF Integration
+
+```typescript
+// Custom API service for PCF context
+const createPCFApiService = () => ({
+  createRecord: async (entityName: string, data: any) =>
+    await context.webAPI.createRecord(entityName, data),
+  retrieveMultipleRecords: async (entityName: string, fetchXml: string) =>
+    await context.webAPI.retrieveMultipleRecords(
+      entityName,
+      `?fetchXml=${encodeURIComponent(fetchXml)}`
+    ),
+  // Additional PCF WebAPI methods...
+});
+```
 
-## Customization
+## 🛠️ Development Workflow
 
 ### Adding New Entities
-1. Create new form components following the `ContactForm` pattern
-2. Add CRUD operations to your provider
-3. Create management components like `ContactManagement`
 
-### Styling
-- Global styles: `src/styles/index.css`
-- Component styles: Co-located `.css` files
-- Fluent UI theming: Customize in the provider
+1. **Create Entity Model**:
+
+```typescript
+// src/models/Opportunity.ts
+export class Opportunity extends BaseEntity implements IOpportunity {
+  // Entity properties and validation
+  public static async create(
+    apiService: IApiService,
+    opportunity: Opportunity
+  ): Promise<Opportunity> {
+    return await this.createEntity<Opportunity>(/*...*/);
+  }
+}
+```
 
-### API Integration
-- Extend `DynamicsProvider` for additional entities
-- Add custom business logic in service layers
-- Implement caching and offline capabilities
+2. **Create Entity Constants**:
 
-## Available Scripts
+```typescript
+// src/constants/opportunity.ts
+export class OpportunityConstants {
+  public static readonly EntityName: string = 'opportunity';
+  public static readonly PrimaryName: string = 'name';
+  // Field definitions with metadata...
+}
+```
 
-- `npm run dev` - Start development server
-- `npm run build` - Build for production
-- `npm run start` - Alias for dev
-- `npm run typecheck` - Type check without building
-- `npm run clean` - Clean build directory
-- `npm run lint` - Lint code
+3. **Create Management Component**:
+
+```typescript
+// src/components/OpportunityManagement.tsx
+export const OpportunityManagement: React.FC = () => {
+  // Follow AccountManagement pattern
+  const loadOpportunities = useCallback(async () => {
+    const opportunities = await Opportunity.retrieveActiveOpportunities(apiService);
+    // Component implementation...
+  }, [apiService]);
+};
+```
+
+### Custom Validation
+
+```typescript
+// In entity models
+validate(): boolean {
+  const validationErrors: string[] = [];
+
+  if (!this.name?.trim()) {
+    validationErrors.push('Name is required');
+  }
+
+  if (this.revenue && this.revenue < 0) {
+    validationErrors.push('Revenue cannot be negative');
+  }
+
+  if (validationErrors.length > 0) {
+    Logger.validation('Account', validationErrors, 'Account.validate');
+    throw new Error(validationErrors.join(', '));
+  }
+
+  return true;
+}
+```
+
+### Extending Logging
+
+```typescript
+// Add custom log types
+Logger.performance('Data fetch completed', startTime, 'AccountManagement');
+Logger.businessRule('Credit limit exceeded', { accountId, creditLimit }, 'AccountForm');
+```
+
+## 📋 Available Scripts
+
+```bash
+# Development
+npm start                 # Start development server with hot reload
+npm run dev              # Alias for start
+
+# Building
+npm run build            # Standard webpack production build
+npm run build:dev        # Unminified build for debugging
+npm run build:prod       # Optimized build for D365 deployment
+npm run build:d365       # Alias for build:prod
+
+# Quality Assurance
+npm run typecheck        # TypeScript compilation check
+npm run lint             # ESLint code quality check
+npm run clean            # Clean build directory
+
+# Deployment
+npm run serve            # Serve built files locally on port 62874
+```
 
-## Troubleshooting
+## 🧪 Testing Workflow
+
+### Component Testing
+
+```typescript
+// Test entity models
+const account = new Account({ name: 'Test Account' });
+account.validate(); // Should pass
+
+// Test API operations
+const mockApiService = new MockApiService();
+const createdAccount = await Account.create(mockApiService, account);
+```
+
+### Environment Testing
+
+```bash
+# Test development environment
+npm start # Should use MockApiService
+
+# Test production build
+npm run build:prod
+npm run serve # Verify optimized bundle
+```
+
+### PCF Testing
+
+```typescript
+// Test PCF wrapper with mock context
+const mockContext = {
+  webAPI: {
+    createRecord: jest.fn(),
+    retrieveMultipleRecords: jest.fn()
+  }
+};
+
+render(<ContactControlWrapper context={mockContext} />);
+```
+
+## 🔍 Troubleshooting
 
 ### Common Issues
 
-1. **Authentication Errors**
-   - Verify your access token and organization URL
-   - Check CORS settings in Dynamics 365
+#### Build Errors
+
+```bash
+# Clear cache and reinstall
+rm -rf node_modules package-lock.json
+npm install
 
-2. **Build Errors**
-   - Clear node_modules and reinstall
-   - Check TypeScript configuration
+# Check TypeScript compilation
+npm run typecheck
+```
 
-3. **PCF Integration**
-   - Ensure proper manifest configuration
-   - Check component lifecycle methods
+#### Environment Detection Issues
 
-## Learn More
+```typescript
+// Force environment for testing
+ServiceFactory.isMockEnvironment = true; // Development
+ServiceFactory.isMockEnvironment = false; // Production
+```
 
-- [Dynamics UI Kit Documentation](https://github.com/your-org/dynamics-ui-kit)
-- [Dynamics 365 Web API](https://docs.microsoft.com/dynamics365/customer-engagement/web-api/)
+#### PCF Integration Problems
+
+- Verify `context.webAPI` is available
+- Check PCF manifest configuration
+- Ensure proper component lifecycle implementation
+- Review browser console for Xrm object availability
+
+#### Logging Not Working
+
+```typescript
+// Check logger configuration
+console.log('Has custom logger:', Logger.hasCustomLogger());
+
+// Manually set logger function
+Logger.setLoggerFunction((message, source) => {
+  console.log(`[${source}] ${message}`);
+});
+```
+
+### Performance Optimization
+
+#### Bundle Size
+
+```bash
+# Analyze bundle with webpack-bundle-analyzer
+npm install --save-dev webpack-bundle-analyzer
+# Add analyzer to build script and review output
+```
+
+#### Entity Model Performance
+
+```typescript
+// Use selective field retrieval
+const accounts = await Account.retrieveByFilter(apiService, filter, [
+  AccountConstants.PrimaryName,
+  AccountConstants.EMailAddress1,
+  AccountConstants.Telephone1,
+]);
+```
+
+## 📚 Learning Resources
+
+### Essential Documentation
+
+- [Dynamics UI Kit Components](https://github.com/your-org/dynamics-ui-kit)
+- [Dynamics 365 Web API Reference](https://docs.microsoft.com/dynamics365/customer-engagement/web-api/)
 - [PowerApps Component Framework](https://docs.microsoft.com/powerapps/developer/component-framework/)
-- [Fluent UI React](https://developer.microsoft.com/fluentui)
+- [Fluent UI v8 Components](https://developer.microsoft.com/fluentui/get-started/web#fluent-ui-react-v8)
+
+### Advanced Topics
+
+- [Entity Relationship Modeling in D365](https://docs.microsoft.com/dynamics365/customerengagement/on-premises/developer/introduction-entities)
+- [Custom Page Development](https://docs.microsoft.com/powerapps/developer/model-driven-apps/customizable-controls-custom-pages)
+- [FetchXML Query Examples](https://docs.microsoft.com/powerapps/developer/data-platform/use-fetchxml-construct-query)
+
+## 🤝 Contributing
+
+### Development Setup
+
+1. **Fork and Clone**: Create a fork of the repository
+2. **Install Dependencies**: Run `npm install` in the template directory
+3. **Create Feature Branch**: `git checkout -b feature/your-feature`
+4. **Follow Patterns**: Use existing entity models and components as templates
+5. **Add Tests**: Include validation and component tests
+6. **Update Documentation**: Add examples and update README
+
+### Code Standards
+
+- **TypeScript**: Full type safety with strict mode
+- **Entity Models**: Follow BaseEntity pattern with validation
+- **Components**: Use functional components with hooks
+- **Logging**: Include comprehensive logging for debugging
+- **Error Handling**: Implement proper error boundaries and validation
+
+### Pull Request Guidelines
+
+1. Ensure TypeScript compilation is clean
+2. Test in both development and production builds
+3. Verify PCF wrapper functionality
+4. Update documentation for new features
+5. Include migration guide for breaking changes
+
+## 📄 License
+
+This template is part of the Dynamics UI Kit and follows the same licensing terms.
+
+## 🆘 Support
+
+### Getting Help
+
+- **Issues**: Create issues in the Dynamics UI Kit repository
+- **Documentation**: Check the comprehensive guides and examples
+- **Community**: Join discussions in the project community
+
+### Enterprise Support
+
+For enterprise deployments and custom development:
+
+- Architecture consulting for complex D365 integrations
+- Custom entity model development
+- Performance optimization and scaling guidance
+- Advanced PCF control development
 
-## Support
+---
 
-For questions and support:
-- Create an issue in the Dynamics UI Kit repository
-- Check the documentation and examples
-- Join the community discussions
+Built with ❤️ using [Dynamics UI Kit](https://github.com/your-org/dynamics-ui-kit) | Optimized for
+Microsoft Dynamics 365