@khester/create-dynamics-app 1.1.0 → 2.1.0

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

@@ -1,700 +0,0 @@
-# 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.