sxhundred/ISA-Frontend
1
0
Fork 0
mirror of https://dev.azure.com/hugendubel/ISA/_git/ISA-Frontend synced 2025-12-28 22:42:11 +01:00
Code Issues Packages Projects Releases Wiki Activity

📚 Add state management and testing guidelines documentation

Browse Source 
Introduced new documentation files for state management and testing guidelines to enhance developer understanding and best practices.

- 📚 **Docs**: Added state management guidelines with local and global state recommendations
- 📚 **Docs**: Created testing guidelines including unit testing requirements and best practices
- 📚 **Docs**: Updated project structure documentation for clarity
This commit is contained in:
Lorenz Hilpert
2025-03-31 11:52:17 +02:00
parent 1cbabd2d7a
commit 3c110efdfa
12 changed files with 619 additions and 368 deletions
Download Patch File Download Diff File Expand all files Collapse all files

244
docs/guidelines.md
View File

@@ -1,244 +0,0 @@
# Guidelines
## 📋 Table of Contents
- [Project Structure](#project-structure)
- [Development Workflow](#development-workflow)
- [Code Style](#code-style)
- [Testing](#testing)
- [State Management](#state-management)
- [Performance](#performance)
- [Common Commands](#common-commands)
## Project Structure
### Directory Organization
```
ISA-Frontend/
├── apps/ # Main applications
│ └── isa-app/ # Primary application
├── libs/ # Shared libraries
│ ├── feature/ # Feature libraries with business logic
│ ├── ui/ # Reusable UI components
│ ├── core/ # Core functionality
│ └── shared/ # Cross-cutting concerns
├── generated/ # Generated API clients
└── docs/ # Documentation
```
### Library Types
- **Feature Libraries** (`libs/feature/*`)
- Smart components
- Business logic
- Route configurations
- Feature-specific services
- **UI Libraries** (`libs/ui/*`)
- Presentational components
- Pure functions
- No dependencies on feature libraries
- **Core Libraries** (`libs/core/*`)
- Authentication
- Guards
- Interceptors
- Core services
- **Shared Libraries** (`libs/shared/*`)
- Common utilities
- Shared interfaces
- Common pipes and directives
## Development Workflow
### Creating New Components
```bash
# Generate a new component
npx nx g @nx/angular:component my-component --project=my-lib
# Generate a new library
npx nx g @nx/angular:library my-lib --directory=feature/my-feature
# Generate a service
npx nx g @nx/angular:service my-service --project=my-lib
```
### Code Organization Best Practices
#### Component Structure
```typescript
// Standard component structure
@Component({
selector: 'isa-feature',
standalone: true,
changeDetection: ChangeDetectionStrategy.OnPush,
imports: [CommonModule],
template: `...`,
})
export class FeatureComponent {
// Public properties first
public readonly data = signal<Data[]>([]);
// Private properties
private readonly destroy$ = new DestroyRef();
// Constructor
constructor() {}
// Public methods
public handleAction(): void {
// Implementation
}
// Private methods
private initializeData(): void {
// Implementation
}
}
```
## Code Style
## TypeScript Guidelines
- Use strict mode in all TypeScript files.
- Explicit return types on public methods.
- Avoid using `any` types; use proper typing.
- Use type inference when the type is obvious.
### Angular Guidelines
- Implement OnPush change detection for better performance.
- Prefer Signals over Observables for component-level state.
- Follow Angular naming conventions for files, classes, and selectors.
- Use `inject()` instead of `constructor()` for Dependency Injection (DI).
- Use Angular's new template control flow syntax @if() @for() @switch() @defer() etc...
- Use `trackBy` functions with `ngFor` loops to optimize rendering performance.
- Enable `strictTemplates` in Angular configurations for better type safety.
- Implement reusable error boundaries for consistent error handling.
- Use strongly typed error objects for better debugging and maintainability.
### Import Organization
```typescript
// Angular imports
import { Component } from '@angular/core';
// Third-party imports
import { Store } from '@ngrx/store';
// Application imports
import { MyService } from './my.service';
```
## Testing
### Unit Testing Requirements
- Test files should end with `.spec.ts`.
- Use Spectator for Component, Directive and Service tests.
- Use Jest as the test runner.
- Follow the Arrange-Act-Assert (AAA) pattern in tests.
- Mock external dependencies to isolate the unit under test.
### Example Test Structure
```typescript
import { createComponentFactory, Spectator } from '@ngneat/spectator/jest';
import { MyComponent } from './my-component.component';
describe('MyComponent', () => {
let spectator: Spectator<MyComponent>;
const createComponent = createComponentFactory(MyComponent);
beforeEach(() => {
spectator = createComponent();
});
it('should create', () => {
expect(spectator.component).toBeTruthy();
});
it('should handle action correctly', () => {
spectator.setInput('inputProp', 'testValue');
spectator.click('button');
expect(spectator.component.outputProp).toBe('expectedValue');
});
});
```
## State Management
### Local State
- Use Signals for component-level state
- Keep state close to where it's used
- Document state management decisions
### Global State (NgRx)
- Use for complex application state
- Follow feature-based store organization
- Implement proper error handling
## Error Handling
- Create reusable error boundaries for consistent error handling.
- Use strongly typed error objects to improve debugging and maintainability.
## Performance
### Best Practices
- Use lazy loading for features and modules.
- Use pure pipes instead of methods in templates.
- Optimize images and assets.
- Monitor and minimize bundle sizes.
- Use `trackBy` functions in `ngFor` loops to improve rendering performance.
### Memory Management
- Unsubscribe from observables to avoid memory leaks.
- Use the `destroy$` pattern or `DestroyRef` for cleanup.
- Remove event listeners when components are destroyed.
- Monitor bundle sizes.
## Common Commands
### Git Workflow
```bash
# Create feature branch
git flow feature start my-feature
# Commit changes
git commit -m "feat: add new feature"
# Push changes
git push origin feature/my-feature
```
## Documentation
### README Requirements
- Component usage examples
- Configuration options
- Dependencies
- Common issues and solutions
## Resources
- [Project Guidelines](/docs/guidelines.md)
- [Angular Style Guide](https://angular.dev/style-guide#)
- [Angular Control Flow](https://angular.dev/guide/templates/control-flow#)
- [Nx Documentation](https://nx.dev/getting-started/intro)
- [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/intro.html)
- [Angular Signals Guide](https://angular.io/guide/signals)

218
docs/guidelines/code-style.md Normal file
View File

@@ -0,0 +1,218 @@
# Code Style Guidelines
## General Principles
- **Readability First**: Write code that is easy to read and understand.
- **Consistency**: Follow the same patterns and conventions throughout the codebase.
- **Clean Code**: Avoid unnecessary complexity and keep functions small and focused.
## Extended Guidelines for Angular and TypeScript
This section extends the core code style principles with Angular-specific and advanced TypeScript best practices to ensure consistency and maintainability in our projects.
### Angular Enhancements
- **Change Detection**: Use the OnPush strategy by default for better performance.
- **Lifecycle Hooks**: Explicitly implement Angular lifecycle interfaces.
- **Template Management**: Keep templates concise and use the async pipe to handle observables.
- **Component Structure**: Follow best practices for component modularization to enhance readability and testability.
### TypeScript Enhancements
- **Strict Type Checking**: Enable strict mode (`strict: true`) and avoid excessive use of `any`.
- **Interfaces vs. Types**: Prefer interfaces for object definitions and use type aliases for unions and intersections.
- **Generics**: Use meaningful type parameter names and constrain generics when applicable.
- **Documentation**: Employ JSDoc comments for complex functions and generic parameters to improve code clarity.
## TypeScript Guidelines
- **Strict Typing**:
- Enable `strict: true` in tsconfig.json
- Avoid `any` unless absolutely necessary
- Use `unknown` instead of `any` when type is truly unknown
- Always specify return types for functions
- Use type inference for variable declarations where types are obvious
```typescript
// Good
const user: User = getUserById('123');
const items = ['apple', 'banana']; // Type inference is fine here
// Bad
const user: any = getUserById('123');
const items: string[] = ['apple', 'banana']; // Unnecessary type annotation
```
- **Interfaces and Types**:
- Prefer `interface` over `type` for object definitions
- Use `type` for unions, intersections, and mapped types
- Follow Angular's naming convention: `IComponentProps` for props interfaces
- Extend interfaces instead of repeating properties
- Use readonly modifiers where appropriate
```typescript
// Good
interface IBaseProps {
readonly id: string;
name: string;
}
interface IUserProps extends IBaseProps {
email: string;
}
type ValidationResult = 'success' | 'error' | 'pending';
// Bad
type UserProps = {
id: string;
name: string;
email: string;
};
```
- **Enums and Constants**:
- Use `const enum` for better performance
- Only use regular `enum` when runtime access is required
- Prefer union types for simple string literals
- **Functions and Methods**:
- Use arrow functions for callbacks and class methods
- Explicitly type parameters and return values
- Keep functions pure when possible
- Use function overloads for complex type scenarios
- Document complex functions with JSDoc
```typescript
// Good
/**
* Fetches a user by ID and transforms it to the required format
* @param id - The user's unique identifier
* @param includeDetails - Whether to include additional user details
*/
const getUser = (id: string, includeDetails = false): Promise<IUser> => {
// ...implementation
};
// Bad
function getUser(id) {
// ...implementation
}
```
- **Generics**:
- Use meaningful type parameter names (e.g., `T` for type, `K` for key)
- Constrain generic types when possible using `extends`
- Document generic parameters using JSDoc
Example:
```typescript
// Good
interface IUserProps {
id: string;
name: string;
}
interface IAdminProps extends IUserProps {
permissions: string[];
}
const enum UserRole {
Admin = 'ADMIN',
User = 'USER',
}
const getUser = <T extends IUserProps>(id: string): Promise<T> => {
// ...implementation
};
// Bad
type User = {
id: any;
name: any;
};
function getUser(id) {
// ...implementation
}
```
## Angular-Specific Guidelines
- **Components**:
- Use OnPush change detection strategy by default
- Implement lifecycle hooks interfaces explicitly
- Keep templates small and focused
- Use async pipe instead of manual subscription management
```typescript
// Good
@Component({
selector: 'app-user-list',
changeDetection: ChangeDetectionStrategy.OnPush,
})
export class UserListComponent implements OnInit, OnDestroy {
users$ = this.userService.getUsers().pipe(shareReplay(1));
}
// Bad
@Component({
selector: 'app-user-list',
})
export class UserListComponent {
users: User[] = [];
subscription: Subscription;
ngOnInit() {
this.subscription = this.userService.getUsers().subscribe((users) => (this.users = users));
}
}
```
## Project-Specific Preferences
- **Frameworks**: Follow best practices for Nx, Hono, and Zod.
- **Testing**: Use Jest with Spectator for unit tests and follow the Arrange-Act-Assert pattern.
- **File Naming**: Use kebab-case for filenames (e.g., `my-component.ts`).
- **Comments**: Use JSDoc for documenting functions, classes, and modules.
## Formatting
- **Indentation**: Use 2 spaces for indentation.
- **Line Length**: Limit lines to 80 characters where possible.
- **Semicolons**: Always use semicolons.
- **Quotes**: Use single quotes for strings, except when using template literals.
## Linting and Tools
- Use ESLint with the recommended TypeScript and Nx configurations.
- Prettier should be used for consistent formatting.
## Example
```typescript
// Good Example
interface User {
id: string;
name: string;
}
const getUser = (id: string): User => {
// ...function logic...
};
// Bad Example
function getUser(id) {
// ...function logic...
}
```
## References
- [Angular Style Guide](https://angular.dev/style-guide#)

44
docs/guidelines/project-structur.md Normal file
View File

@@ -0,0 +1,44 @@
## Project Structure
### Directory Organization
```
ISA-Frontend/
├── apps/ # Main applications
│ └── isa-app/ # Primary application
├── libs/ # Shared libraries
│ ├── feature/ # Feature libraries with business logic
│ ├── ui/ # Reusable UI components
│ ├── core/ # Core functionality
│ └── shared/ # Cross-cutting concerns
├── generated/ # Generated API clients
└── docs/ # Documentation
```
### Library Types
- **Feature Libraries** (`libs/feature/*`)
- Smart components
- Business logic
- Route configurations
- Feature-specific services
- **UI Libraries** (`libs/ui/*`)
- Presentational components
- Pure functions
- No dependencies on feature libraries
- **Core Libraries** (`libs/core/*`)
- Authentication
- Guards
- Interceptors
- Core services
- **Shared Libraries** (`libs/shared/*`)
- Common utilities
- Shared interfaces
- Common pipes and directives

13
docs/guidelines/state-management.md Normal file
View File

@@ -0,0 +1,13 @@
# State Management
## Local State
- Use Signals for component-level state
- Keep state close to where it's used
- Document state management decisions
## Global State (NgRx)
- Use for complex application state
- Follow feature-based store organization
- Implement proper error handling

35
docs/guidelines/testing.md Normal file
View File

@@ -0,0 +1,35 @@
# Testing Guidelines
## Unit Testing Requirements
- Test files should end with `.spec.ts`.
- Use Spectator for Component, Directive and Service tests.
- Use Jest as the test runner.
- Follow the Arrange-Act-Assert (AAA) pattern in tests.
- Mock external dependencies to isolate the unit under test.
## Example Test Structure
```typescript
import { createComponentFactory, Spectator } from '@ngneat/spectator/jest';
import { MyComponent } from './my-component.component';
describe('MyComponent', () => {
let spectator: Spectator<MyComponent>;
const createComponent = createComponentFactory(MyComponent);
beforeEach(() => {
spectator = createComponent();
});
it('should create', () => {
expect(spectator.component).toBeTruthy();
});
it('should handle action correctly', () => {
spectator.setInput('inputProp', 'testValue');
spectator.click('button');
expect(spectator.component.outputProp).toBe('expectedValue');
});
});
```

90
docs/tech-stack.md Normal file
View File

@@ -0,0 +1,90 @@
# Tech Stack Documentation
## Core Technologies
### Frontend Framework
- **[Angular](https://angular.dev/overview)** (Latest Version)
- Modern web framework for building scalable single-page applications
- Leverages TypeScript for enhanced type safety and developer experience
### State Management
- **[NgRx](https://ngrx.io/docs)**
- Redux-inspired state management for Angular applications
- Provides predictable state container and powerful dev tools
- Used for managing complex application state and side effects
### Styling
- **[Tailwind CSS](https://tailwindcss.com/)**
- Utility-first CSS framework
- Enables rapid UI development with pre-built classes
- Highly customizable through configuration
## Development Tools
### Language
- **[TypeScript](https://www.typescriptlang.org/docs/handbook/intro.html)**
- Strongly typed programming language
- Provides enhanced IDE support and compile-time error checking
- Used throughout the entire application
### Runtime
- **[Node.js](https://nodejs.org/docs/latest-v22.x/api/index.html)**
- JavaScript runtime environment
- Used for development server and build tools
- Required for running npm scripts and development tools
### Testing Framework
- **[Jest](https://jestjs.io/docs/getting-started)**
- Primary testing framework
- Used for unit and integration tests
- Provides snapshot testing capabilities
- **[Spectator](https://ngneat.github.io/spectator/)**
- Angular testing utility library
- Simplifies component testing
- Reduces boilerplate in test files
### UI Development
- **[Storybook](https://storybook.js.org/docs/get-started/frameworks/angular)**
- UI component development environment
- Enables isolated component development
- Serves as living documentation for components
### Utilities
- **[date-fns](https://date-fns.org/docs/Getting-Started)**
- Modern JavaScript date utility library
- Used for consistent date formatting and manipulation
- Tree-shakeable to optimize bundle size
## Development Environment Setup
1. **Required Software**
- Node.js (Latest LTS version)
- npm (comes with Node.js)
- Git
2. **IDE Recommendations**
- Visual Studio Code with following extensions:
- Angular Language Service
- ESLint
- Prettier
- Tailwind CSS IntelliSense
3. **Getting Started**
```bash
npm install # Install dependencies
npm run start # Start development server
npm run test # Run tests
npm run storybook # Start Storybook
```