@khester/create-dynamics-app 1.0.8 → 1.1.0

package/templates/dynamics-365-starter/docs/team-standards/coding-standards.md

@@ -0,0 +1,700 @@
+# Coding Standards
+
+## Table of Contents
+
+1. [General Principles](#general-principles)
+2. [TypeScript Standards](#typescript-standards)
+3. [React Component Standards](#react-component-standards)
+4. [Entity Model Standards](#entity-model-standards)
+5. [CSS and Styling Standards](#css-and-styling-standards)
+6. [API and Service Standards](#api-and-service-standards)
+7. [Error Handling Standards](#error-handling-standards)
+8. [Testing Standards](#testing-standards)
+9. [Documentation Standards](#documentation-standards)
+10. [File Organization](#file-organization)
+
+## General Principles
+
+### Code Quality
+
+- **Readability**: Code should be self-documenting
+- **Consistency**: Follow established patterns throughout the codebase
+- **Simplicity**: Choose simple solutions over complex ones
+- **Maintainability**: Write code that's easy to modify and extend
+- **Performance**: Consider performance implications of coding decisions
+
+### Best Practices
+
+- Use meaningful variable and function names
+- Keep functions small and focused (single responsibility)
+- Avoid deep nesting (max 3 levels)
+- Use early returns to reduce complexity
+- Prefer composition over inheritance
+- Follow DRY (Don't Repeat Yourself) principle
+
+## TypeScript Standards
+
+### Type Definitions
+
+```typescript
+// ✅ Good: Explicit interface definitions
+interface IAccount {
+  id: string;
+  name: string;
+  revenue?: number;
+  createdOn: Date;
+}
+
+// ❌ Bad: Using 'any' type
+function processData(data: any): any {
+  return data.something;
+}
+
+// ✅ Good: Proper type guards
+function isAccount(obj: unknown): obj is IAccount {
+  return typeof obj === 'object' && obj !== null && 'id' in obj && 'name' in obj;
+}
+```
+
+### Naming Conventions
+
+```typescript
+// Interfaces: PascalCase with 'I' prefix
+interface IApiService {}
+
+// Classes: PascalCase
+class AccountService {}
+
+// Functions and variables: camelCase
+const fetchAccountData = async () => {};
+
+// Constants: SCREAMING_SNAKE_CASE
+const MAX_RETRY_ATTEMPTS = 3;
+
+// Enums: PascalCase
+enum EntityState {
+  Active = 0,
+  Inactive = 1,
+}
+```
+
+### Generic Types
+
+```typescript
+// ✅ Good: Descriptive generic constraints
+interface IRepository<T extends BaseEntity> {
+  create(entity: T): Promise<T>;
+  update(id: string, entity: Partial<T>): Promise<T>;
+  delete(id: string): Promise<void>;
+}
+
+// ✅ Good: Default generic parameters
+interface IApiResponse<T = unknown> {
+  data: T;
+  success: boolean;
+  message?: string;
+}
+```
+
+## React Component Standards
+
+### Component Structure
+
+```typescript
+// ✅ Good: Functional component with proper typing
+interface AccountFormProps {
+  account?: Account;
+  onSave: (account: Account) => Promise<void>;
+  onCancel: () => void;
+  readOnly?: boolean;
+}
+
+export const AccountForm: React.FC<AccountFormProps> = ({
+  account,
+  onSave,
+  onCancel,
+  readOnly = false
+}) => {
+  // State declarations
+  const [formData, setFormData] = useState<Partial<IAccount>>({});
+  const [loading, setLoading] = useState(false);
+  const [errors, setErrors] = useState<string[]>([]);
+
+  // Effects
+  useEffect(() => {
+    if (account) {
+      setFormData(account);
+    }
+  }, [account]);
+
+  // Event handlers
+  const handleSubmit = async (event: React.FormEvent) => {
+    event.preventDefault();
+    // Implementation
+  };
+
+  // Render
+  return (
+    <form onSubmit={handleSubmit}>
+      {/* JSX content */}
+    </form>
+  );
+};
+```
+
+### Hooks Usage
+
+```typescript
+// ✅ Good: Custom hooks for reusable logic
+const useAccountData = (accountId: string) => {
+  const [account, setAccount] = useState<Account | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    const loadAccount = async () => {
+      try {
+        setLoading(true);
+        const data = await AccountService.getById(accountId);
+        setAccount(data);
+      } catch (err) {
+        setError(err instanceof Error ? err.message : 'Unknown error');
+      } finally {
+        setLoading(false);
+      }
+    };
+
+    loadAccount();
+  }, [accountId]);
+
+  return { account, loading, error };
+};
+```
+
+### Event Handlers
+
+```typescript
+// ✅ Good: Properly typed event handlers
+const handleInputChange = useCallback((event: React.ChangeEvent<HTMLInputElement>) => {
+  const { name, value } = event.target;
+  setFormData((prev) => ({ ...prev, [name]: value }));
+}, []);
+
+const handleDropdownChange = useCallback(
+  (_: React.FormEvent<HTMLDivElement>, option?: IDropdownOption) => {
+    if (option) {
+      setSelectedValue(option.key as string);
+    }
+  },
+  []
+);
+```
+
+## Entity Model Standards
+
+### Entity Class Structure
+
+```typescript
+// ✅ Good: Well-structured entity class
+export class Account extends BaseEntity implements IAccount {
+  // Properties with proper typing
+  public id: string = '';
+  public name: string = '';
+  public revenue?: number;
+  public createdOn?: Date;
+  public modifiedOn?: Date;
+
+  constructor(data?: Partial<IAccount>) {
+    super();
+    if (data) {
+      Object.assign(this, data);
+    }
+  }
+
+  // Static factory methods
+  public static async create(apiService: IApiService, account: Account): Promise<Account> {
+    try {
+      logger.logInfo(`Creating account: ${account.name}`);
+
+      const validation = account.validate();
+      if (!validation.isValid) {
+        throw new Error(`Validation failed: ${validation.errors.join(', ')}`);
+      }
+
+      const result = await apiService.createRecord(
+        AccountConstants.EntityLogicalName,
+        account.toCreateData()
+      );
+
+      return new Account({
+        ...account,
+        id: result.id,
+      });
+    } catch (error) {
+      logger.logError('Error creating account:', error);
+      throw error;
+    }
+  }
+
+  // Instance methods
+  public validate(): ValidationResult {
+    const errors: string[] = [];
+
+    if (!this.name?.trim()) {
+      errors.push('Name is required');
+    }
+
+    if (this.revenue !== undefined && this.revenue < 0) {
+      errors.push('Revenue cannot be negative');
+    }
+
+    return {
+      isValid: errors.length === 0,
+      errors,
+    };
+  }
+
+  private toCreateData(): Partial<IAccount> {
+    return {
+      name: this.name,
+      revenue: this.revenue,
+    };
+  }
+}
+```
+
+### Constants Structure
+
+```typescript
+// ✅ Good: Comprehensive constants class
+export class AccountConstants {
+  // Entity metadata
+  public static readonly EntityLogicalName = 'account';
+  public static readonly EntityCollectionName = 'accounts';
+  public static readonly PrimaryIdAttribute = 'accountid';
+  public static readonly PrimaryNameAttribute = 'name';
+
+  // Field names with metadata comments
+  /** Type: String, RequiredLevel: ApplicationRequired, MaxLength: 160 */
+  public static readonly Name = 'name';
+
+  /** Type: Money, RequiredLevel: None */
+  public static readonly Revenue = 'revenue';
+
+  /** Type: DateTime, ReadOnly: true */
+  public static readonly CreatedOn = 'createdon';
+
+  // Option set values
+  public static readonly StateCodeOptions = {
+    Active: 0,
+    Inactive: 1,
+  } as const;
+
+  // Display names for UI
+  public static readonly FieldDisplayNames = {
+    [this.Name]: 'Account Name',
+    [this.Revenue]: 'Annual Revenue',
+    [this.CreatedOn]: 'Created On',
+  } as const;
+
+  // Required fields array
+  public static readonly RequiredFields = [this.Name] as const;
+}
+```
+
+## CSS and Styling Standards
+
+### CSS Modules
+
+```css
+/* ✅ Good: BEM-like naming with CSS modules */
+.accountForm {
+  padding: 20px;
+  max-width: 600px;
+}
+
+.accountForm__field {
+  margin-bottom: 16px;
+}
+
+.accountForm__field--required {
+  position: relative;
+}
+
+.accountForm__field--required::after {
+  content: '*';
+  color: #d13438;
+  margin-left: 4px;
+}
+
+.accountForm__actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: 12px;
+  margin-top: 24px;
+}
+
+/* Responsive design */
+@media (max-width: 768px) {
+  .accountForm {
+    padding: 16px;
+    max-width: 100%;
+  }
+
+  .accountForm__actions {
+    flex-direction: column;
+  }
+}
+```
+
+### Styling Conventions
+
+- Use CSS Modules for component-specific styles
+- Follow BEM-like naming convention
+- Use semantic class names
+- Implement responsive design principles
+- Use CSS custom properties for theming
+- Avoid inline styles except for dynamic values
+
+## API and Service Standards
+
+### Service Interface
+
+```typescript
+// ✅ Good: Well-defined service interface
+interface IApiService {
+  createRecord(entityName: string, data: Record<string, unknown>): Promise<ApiResponse>;
+  updateRecord(entityName: string, id: string, data: Record<string, unknown>): Promise<void>;
+  deleteRecord(entityName: string, id: string): Promise<void>;
+  retrieveRecord(entityName: string, id: string, fields?: string[]): Promise<ApiResponse>;
+  retrieveMultipleRecords(entityName: string, fetchXml: string): Promise<ApiResponse>;
+}
+```
+
+### Service Implementation
+
+```typescript
+// ✅ Good: Proper error handling and logging
+export class XrmApiService implements IApiService {
+  private readonly baseUrl: string;
+  private readonly timeout: number;
+
+  constructor(config: ApiConfig) {
+    this.baseUrl = config.baseUrl;
+    this.timeout = config.timeout || 30000;
+  }
+
+  public async createRecord(
+    entityName: string,
+    data: Record<string, unknown>
+  ): Promise<ApiResponse> {
+    try {
+      logger.logInfo(`Creating ${entityName} record`);
+
+      const response = await this.makeRequest('POST', `${entityName}`, data);
+
+      logger.logInfo(`Successfully created ${entityName} record`);
+      return response;
+    } catch (error) {
+      logger.logError(`Error creating ${entityName} record:`, error);
+      throw this.handleApiError(error);
+    }
+  }
+
+  private async makeRequest(
+    method: string,
+    endpoint: string,
+    data?: Record<string, unknown>
+  ): Promise<ApiResponse> {
+    const url = `${this.baseUrl}/${endpoint}`;
+    const options: RequestInit = {
+      method,
+      headers: {
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+      },
+      signal: AbortSignal.timeout(this.timeout),
+    };
+
+    if (data) {
+      options.body = JSON.stringify(data);
+    }
+
+    const response = await fetch(url, options);
+
+    if (!response.ok) {
+      throw new ApiError(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    return response.json();
+  }
+
+  private handleApiError(error: unknown): Error {
+    if (error instanceof ApiError) {
+      return error;
+    }
+
+    if (error instanceof Error) {
+      return new ApiError(`API request failed: ${error.message}`);
+    }
+
+    return new ApiError('Unknown API error occurred');
+  }
+}
+```
+
+## Error Handling Standards
+
+### Error Types
+
+```typescript
+// ✅ Good: Custom error classes
+export class ValidationError extends Error {
+  constructor(
+    message: string,
+    public readonly field: string,
+    public readonly value: unknown
+  ) {
+    super(message);
+    this.name = 'ValidationError';
+  }
+}
+
+export class ApiError extends Error {
+  constructor(
+    message: string,
+    public readonly statusCode?: number,
+    public readonly response?: unknown
+  ) {
+    super(message);
+    this.name = 'ApiError';
+  }
+}
+```
+
+### Error Handling Patterns
+
+```typescript
+// ✅ Good: Comprehensive error handling
+const saveAccount = async (account: Account): Promise<void> => {
+  try {
+    // Validate input
+    const validation = account.validate();
+    if (!validation.isValid) {
+      throw new ValidationError(validation.errors.join(', '), 'account', account);
+    }
+
+    // Attempt save
+    await account.save(apiService);
+
+    // Log success
+    logger.logInfo(`Account saved successfully: ${account.name}`);
+  } catch (error) {
+    // Log error with context
+    logger.logError('Failed to save account:', {
+      error,
+      accountName: account.name,
+      accountId: account.id,
+    });
+
+    // Re-throw with user-friendly message
+    if (error instanceof ValidationError) {
+      throw new Error(`Validation failed: ${error.message}`);
+    } else if (error instanceof ApiError) {
+      throw new Error('Unable to save account. Please try again.');
+    } else {
+      throw new Error('An unexpected error occurred.');
+    }
+  }
+};
+```
+
+## Testing Standards
+
+### Unit Test Structure
+
+```typescript
+// ✅ Good: Comprehensive unit tests
+describe('Account', () => {
+  let mockApiService: jest.Mocked<IApiService>;
+
+  beforeEach(() => {
+    mockApiService = {
+      createRecord: jest.fn(),
+      updateRecord: jest.fn(),
+      deleteRecord: jest.fn(),
+      retrieveRecord: jest.fn(),
+      retrieveMultipleRecords: jest.fn(),
+    };
+  });
+
+  describe('validation', () => {
+    it('should require name field', () => {
+      // Arrange
+      const account = new Account({ name: '' });
+
+      // Act
+      const result = account.validate();
+
+      // Assert
+      expect(result.isValid).toBe(false);
+      expect(result.errors).toContain('Name is required');
+    });
+
+    it('should not allow negative revenue', () => {
+      // Arrange
+      const account = new Account({
+        name: 'Test Account',
+        revenue: -1000,
+      });
+
+      // Act
+      const result = account.validate();
+
+      // Assert
+      expect(result.isValid).toBe(false);
+      expect(result.errors).toContain('Revenue cannot be negative');
+    });
+  });
+
+  describe('create', () => {
+    it('should create account successfully', async () => {
+      // Arrange
+      const accountData = { name: 'Test Account', revenue: 100000 };
+      const account = new Account(accountData);
+
+      mockApiService.createRecord.mockResolvedValue({
+        data: { id: 'test-id', ...accountData },
+        success: true,
+      });
+
+      // Act
+      const result = await Account.create(mockApiService, account);
+
+      // Assert
+      expect(mockApiService.createRecord).toHaveBeenCalledWith(
+        AccountConstants.EntityLogicalName,
+        expect.objectContaining(accountData)
+      );
+      expect(result.id).toBe('test-id');
+      expect(result.name).toBe('Test Account');
+    });
+  });
+});
+```
+
+## Documentation Standards
+
+### JSDoc Comments
+
+````typescript
+/**
+ * Represents an Account entity in Dynamics 365
+ *
+ * @example
+ * ```typescript
+ * const account = new Account({ name: 'ACME Corp', revenue: 100000 });
+ * await Account.create(apiService, account);
+ * ```
+ */
+export class Account extends BaseEntity {
+  /**
+   * Creates a new account in Dynamics 365
+   *
+   * @param apiService - The API service instance
+   * @param account - The account data to create
+   * @returns Promise resolving to the created account
+   * @throws {ValidationError} When account data is invalid
+   * @throws {ApiError} When API request fails
+   */
+  public static async create(apiService: IApiService, account: Account): Promise<Account> {
+    // Implementation
+  }
+
+  /**
+   * Validates the account data
+   *
+   * @returns Validation result with isValid flag and error messages
+   */
+  public validate(): ValidationResult {
+    // Implementation
+  }
+}
+````
+
+## File Organization
+
+### Directory Structure
+
+```
+src/
+├── components/           # React components
+│   ├── AccountForm/
+│   │   ├── AccountForm.tsx
+│   │   ├── AccountForm.css
+│   │   ├── AccountForm.test.tsx
+│   │   └── index.ts
+│   └── shared/          # Shared components
+├── models/              # Entity models
+│   ├── BaseEntity.ts
+│   ├── Account.ts
+│   └── Contact.ts
+├── constants/           # Entity constants
+│   ├── account.ts
+│   └── contact.ts
+├── services/           # API services
+│   ├── IApiService.ts
+│   ├── XrmApiService.ts
+│   └── MockApiService.ts
+├── utils/              # Utility functions
+├── types/              # Type definitions
+├── hooks/              # Custom React hooks
+└── providers/          # React context providers
+```
+
+### Import Order
+
+```typescript
+// ✅ Good: Organized imports
+// 1. Node modules
+import React, { useState, useEffect } from 'react';
+import { IColumn, DetailsList } from '@fluentui/react';
+
+// 2. Internal modules (absolute paths)
+import { Account } from '../models/Account';
+import { AccountConstants } from '../constants/account';
+import { useApiService } from '../providers/DynamicsProvider';
+
+// 3. Relative imports
+import './AccountList.css';
+```
+
+### Naming Conventions
+
+- **Files**: PascalCase for components, camelCase for utilities
+- **Directories**: kebab-case or camelCase consistently
+- **Test files**: Same name as source file with `.test.ts` suffix
+- **Type files**: Same name as source file with `.types.ts` suffix
+
+## Code Review Requirements
+
+### Before Submitting
+
+- [ ] All TypeScript errors resolved
+- [ ] All ESLint warnings addressed
+- [ ] Unit tests added/updated
+- [ ] Documentation updated
+- [ ] Manual testing completed
+
+### Review Checklist
+
+- [ ] Code follows established patterns
+- [ ] Proper error handling implemented
+- [ ] Performance considerations addressed
+- [ ] Security best practices followed
+- [ ] Accessibility requirements met
+
+---
+
+These standards ensure consistency, maintainability, and quality across all Dynamics 365 consulting
+projects.