@khester/create-dynamics-app 2.1.0 → 2.2.0

package/templates/react-custom-page/README.md

@@ -1,607 +1,113 @@
-# Dynamics 365 Enhanced Template
+# React Custom Page (Dataverse)
 
-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.
+A minimal, production-shaped starter for a React app mounted as a **Dynamics 365
+custom page**. It ships one thin example form (edit a single Account) on a clean
+layering you can copy: `component → hook → pure mapper/diff → model → IApiService`.
 
-## 🚀 Features
+UI primitives, theme, and logging come from
+[`@khester/reusable-components`](https://www.npmjs.com/package/@khester/reusable-components);
+the data-access seam (`src/core/services`) is owned by this app.
 
-### **Dual Entity Management**
+## Commands
 
-- **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
+| Command | What it does |
+|---------|--------------|
+| `npm install` | Install dependencies |
+| `npm run dev` | Run in **mock** mode — seeded data, no org needed |
+| `npm run dev:token` | Run against a **live org** — refreshes the token + starts Vite |
+| `npm run auth:token -- --url https://<org>.crm.dynamics.com` | Acquire/refresh a Dataverse token into `.env` (needs `az login`) |
+| `npm run build` | Production build → `dist/` (multi-file) |
+| `npm run build:d365` | Single self-contained `dist/index.html` (the web resource) |
+| `npm run deploy` | Build + upload + **publish** the web resource to your org |
+| `npm test` | Unit-test the pure layers (diff, mappers, record context) |
+| `npm run typecheck` | Type-check (`tsc --noEmit`) |
+| `npm install @khester/reusable-components@latest` | Update the shared component library |
 
-### **Enterprise Architecture**
+> Requires **Node 18+**. For `dev:token` / `deploy` you also need `az login` and
+> `DYNAMICS_URL` in `.env` (set once via `npm run auth:token -- --url …`).
 
-- **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
-
-### **Advanced UI Components**
-
-- **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
-
-### **Production-Ready Deployment**
-
-- **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
-
-## 🏁 Quick Start
-
-### Installation
+## Quick start
 
 ```bash
-# Using the CLI tool
-npx create-dynamics-app my-d365-app --template dynamics-365-starter
-
-# Or clone and install
-git clone <repository-url>
-cd dynamics-365-starter
 npm install
+npm run dev          # mock mode — a seeded account, no org needed
 ```
 
-### Development
+Open http://localhost:3000. Edit a field; **Save** enables when the form is dirty
+and logs a `[CRUD] UPDATE accounts ok` line. On localhost, `window.dumpAppLogs()`
+in the browser console prints the structured log buffer.
 
-```bash
-# Start development server with mock data
-npm start
-# Opens http://localhost:3000 with Account and Contact management
+A floating **🔧 Dev Tools** panel (bottom-right, localhost only) shows the active
+mode (Mock / Token-proxy / Production), lets you load a record by GUID (adds `?id=`
+and reloads), and views the `[CRUD]` log buffer. It renders nothing once deployed.
 
-# Build for development (unminified)
-npm run build:dev
+## Three runtime modes
 
-# Build for production (optimized for D365)
-npm run build:prod
-
-# Serve built files locally
-npm run serve
-```
+`src/core/services/ServiceFactory.ts` picks the data service per environment:
 
-## 📋 Project Structure
-
-```
-src/
-├── 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[]>;
-}
-```
+| Mode | When | Service |
+|------|------|---------|
+| **Mock** | `localhost`, no `DYNAMICS_URL` | `MockApiService` (in-memory, seeds one account) |
+| **Token** | `localhost` + `DYNAMICS_URL` set | `FetchApiService` → Vite proxy → real Dataverse |
+| **Production** | deployed in a model-driven app | `XrmApiService` (Web API, session auth) |
 
-### 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
+### Token mode — test against a real org locally
 
 ```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
-
-```bash
-# .env.local
-REACT_APP_D365_URL=https://yourorg.crm.dynamics.com
-REACT_APP_ENVIRONMENT=development
-```
-
-### 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...
-};
-```
-
-### 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...
-});
-```
-
-## 🛠️ Development Workflow
-
-### Adding New Entities
-
-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>(/*...*/);
-  }
-}
+npm run auth:token -- --url https://<org>.crm.dynamics.com   # writes .env via Azure CLI
+npm run dev
 ```
 
-2. **Create Entity Constants**:
+The Vite dev server proxies `/api/data/*` to the org and injects the bearer token
+**server-side** — the token never enters the browser bundle. Tokens last ~60 min;
+re-run `npm run auth:token` to refresh (no dev-server restart needed). Requires
+`az login` first. See `env.example` for the variables.
 
-```typescript
-// src/constants/opportunity.ts
-export class OpportunityConstants {
-  public static readonly EntityName: string = 'opportunity';
-  public static readonly PrimaryName: string = 'name';
-  // Field definitions with metadata...
-}
-```
-
-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
+Once `DYNAMICS_URL` is in `.env`, **`npm run dev:token`** refreshes the token and
+starts the dev server in one step:
 
 ```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
-```
-
-## 🧪 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);
+npm run dev:token
 ```
 
-### Environment Testing
+## Build & deploy
 
 ```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} />);
+npm run build        # standard multi-file build → dist/
+npm run build:d365   # single self-contained dist/index.html (vite-plugin-singlefile)
+npm run deploy       # build:d365 + upload as an HTML web resource + publish
 ```
 
-## 🔍 Troubleshooting
-
-### Common Issues
-
-#### Build Errors
+**`npm run deploy`** refreshes the token, builds the single-file bundle, and
+upserts + publishes it as an HTML web resource via the Dataverse Web API (no PAC
+CLI needed). Set the web-resource name in `.env` first — the prefix must match a
+publisher that exists in your org:
 
 ```bash
-# Clear cache and reinstall
-rm -rf node_modules package-lock.json
-npm install
-
-# Check TypeScript compilation
-npm run typecheck
+# .env
+WEBRESOURCE_NAME=cr1a2_/myapp/index.html   # use YOUR publisher prefix
+# WEBRESOURCE_SOLUTION=MySolution          # optional: add it to an unmanaged solution
 ```
 
-#### Environment Detection Issues
-
-```typescript
-// Force environment for testing
-ServiceFactory.isMockEnvironment = true; // Development
-ServiceFactory.isMockEnvironment = false; // Production
-```
-
-#### 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
+Then host it on a model-driven **custom page**, or open it via
+`Xrm.Navigation.navigateTo({ pageType: "webresource", webresourceName: "<name>" })`.
+The page reads an optional record id from the URL (`?id=<guid>`); in production it
+resolves `Xrm` from `window.parent`.
 
-```typescript
-// Check logger configuration
-console.log('Has custom logger:', Logger.hasCustomLogger());
+> Some orgs enforce a Content-Security-Policy that blocks inline `<script>`. The
+> single-file bundle is one inline script — if your environment blocks it, use the
+> multi-file `npm run build` output instead.
 
-// Manually set logger function
-Logger.setLoggerFunction((message, source) => {
-  console.log(`[${source}] ${message}`);
-});
-```
-
-### Performance Optimization
+## Make it your own
 
-#### Bundle Size
+1. Replace `src/example/` with your page: `models/<Entity>.ts` (CRUD), a pure
+   `mappers/<entity>Mapper.ts` (+ test), `hooks/`, and the thin component.
+2. Add a seed for your entity in `src/core/services/MockApiService.ts` so
+   `npm run dev` works offline.
+3. Keep CRUD in the model and business rules in the pure layers — see
+   [ARCHITECTURE.md](./ARCHITECTURE.md).
 
 ```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,
-]);
+npm run test         # unit-tests the pure layers (diff, mappers)
+npm run typecheck    # tsc --noEmit
 ```
-
-## 📚 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 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
-
----
-
-Built with ❤️ using [Dynamics UI Kit](https://github.com/your-org/dynamics-ui-kit) | Optimized for
-Microsoft Dynamics 365