@silvestv/migration-planificator 3.0.0

package/dist/src/data/markdown/angular-migration-17-18.md

@@ -0,0 +1,408 @@
+# Guide Migration Angular 17→18 avec Exemples
+
+## 🔴 RÈGLES OBLIGATOIRES (Breaking Changes)
+
+### 1. Environnement
+```bash
+# ❌ Avant: Node v16, TypeScript 4.9
+# ✅ Après: 
+node --version  # v18.19.1+
+npm install typescript@~5.4.0
+ng update @angular/core@18 @angular/cli@18
+```
+
+### 2. Imports à modifier
+```typescript
+// ❌ Avant
+import { async } from '@angular/core';
+import { StateKey, TransferState } from '@angular/platform-browser';
+
+// ✅ Après
+import { waitForAsync } from '@angular/core';
+import { StateKey, TransferState } from '@angular/core';
+```
+
+### 3. APIs supprimées
+```typescript
+// ❌ Avant
+animationDriver.matchesElement(element, selector);
+if (isPlatformWorkerUi(platformId)) { }
+testability.increasePendingRequestCount();
+
+// ✅ Après
+// Supprimer matchesElement - utiliser une autre approche
+// Supprimer isPlatformWorkerUi - plus supporté
+// Supprimer Testability methods - géré par ZoneJS
+```
+
+### 4. Platform Server
+```typescript
+// ❌ Avant
+import { platformDynamicServer } from '@angular/platform-server';
+import { ServerTransferStateModule } from '@angular/platform-server';
+
+@NgModule({
+  imports: [ServerTransferStateModule]
+})
+
+// ✅ Après
+import { platformServer } from '@angular/platform-server';
+import '@angular/compiler';
+// ServerTransferStateModule supprimé - plus nécessaire
+```
+
+### 5. Routing
+```typescript
+// ❌ Avant
+const route: Route = {
+  path: 'old',
+  redirectTo: '/new' // string uniquement
+};
+
+// ✅ Après
+const route: Route = {
+  path: 'old',
+  redirectTo: () => {
+    // Peut être une fonction
+    return '/new';
+  }
+};
+
+// Guards peuvent retourner RedirectCommand
+canActivate(): boolean | UrlTree | RedirectCommand {
+  return new RedirectCommand('/login');
+}
+```
+
+### 6. Templates ngModel
+```typescript
+// ❌ Avant
+template: `<input [(ngModel)]="user.name = processName(user.name)">`
+
+// ✅ Après
+template: `<input [(ngModel)]="user.name" (ngModelChange)="onNameChange($event)">`
+```
+
+### 7. Providers Environment
+```typescript
+// ❌ Avant
+@Component({
+  template: `<router-outlet></router-outlet>`,
+  providers: [MyService] // Provider dans le composant avec RouterOutlet
+})
+
+// ✅ Après
+bootstrapApplication(App, {
+  providers: [MyService] // Déplacer vers bootstrap
+});
+// OU dans la config de route
+const routes: Routes = [{
+  path: 'feature',
+  providers: [MyService],
+  loadChildren: () => import('./feature')
+}];
+```
+
+### 8. Tests Change Detection
+```typescript
+// ❌ Tests qui échouent avec multiples détections
+beforeEach(() => {
+  fixture = TestBed.createComponent(Component);
+  fixture.autoDetect = true; // Peut causer des problèmes d'ordre
+});
+
+// ✅ Après - Si problèmes, ajouter:
+TestBed.configureTestingModule({
+  providers: [
+    provideZoneChangeDetection({
+      ignoreChangesOutsideZone: true
+    })
+  ]
+});
+```
+
+### 9. OnPush Components
+```typescript
+// ❌ Avant - Host bindings non mis à jour
+@Component({
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  host: { '[class.active]': 'isActive' }
+})
+export class MyComponent {
+  isActive = false;
+  toggle() {
+    this.isActive = true; // Binding peut ne pas se mettre à jour
+  }
+}
+
+// ✅ Après
+export class MyComponent {
+  constructor(private cdr: ChangeDetectorRef) {}
+  
+  toggle() {
+    this.isActive = true;
+    this.cdr.markForCheck(); // Forcer la détection
+  }
+}
+```
+
+---
+
+## 🟡 RÈGLES RECOMMANDÉES
+
+### 1. Mode Sans Zones
+```typescript
+// main.ts
+// ❌ Ancien mode avec zone.js
+bootstrapApplication(App);
+
+// ✅ Nouveau mode expérimental
+import { provideExperimentalZonelessChangeDetection } from '@angular/core';
+
+bootstrapApplication(App, {
+  providers: [
+    provideExperimentalZonelessChangeDetection()
+  ]
+});
+
+// angular.json - retirer zone.js des polyfills
+"polyfills": [
+  // "zone.js" ← Supprimer
+]
+```
+
+### 2. Coalescence
+```typescript
+// ❌ Sans coalescence (multiples détections)
+@Component({
+  template: `
+    <button (click)="onClick()">
+    <button (click)="onClick2()">
+  `
+})
+
+// ✅ Avec coalescence
+bootstrapApplication(App, {
+  providers: [
+    provideZoneChangeDetection({ eventCoalescing: true })
+  ]
+});
+```
+
+### 3. Signaux
+```typescript
+// ❌ Avant
+@Component({
+  template: `{{ count }}`
+})
+export class Counter {
+  count = 0;
+  increment() {
+    this.count++;
+  }
+}
+
+// ✅ Après avec signaux
+@Component({
+  template: `{{ count() }}`
+})
+export class Counter {
+  count = signal(0);
+  increment() {
+    this.count.update(v => v + 1);
+  }
+}
+```
+
+### 4. Event Replay (SSR)
+```typescript
+// main.server.ts
+bootstrapApplication(App, {
+  providers: [
+    provideClientHydration(withEventReplay())
+  ]
+});
+```
+
+### 5. Forms Events
+```typescript
+// ❌ Avant
+const control = new FormControl();
+control.valueChanges.subscribe(v => {});
+control.statusChanges.subscribe(s => {});
+
+// ✅ Après
+const control = new FormControl();
+control.events.subscribe(event => {
+  if (event instanceof ValueChangeEvent) { }
+  if (event instanceof StatusChangeEvent) { }
+});
+```
+
+---
+
+## 🟢 RÈGLES OPTIONNELLES
+
+### 1. ng-content par défaut
+```typescript
+// ❌ Avant
+@Component({
+  template: `<ng-content></ng-content>`
+})
+
+// ✅ Après
+@Component({
+  template: `
+    <ng-content select=".header">
+      <div class="default-header">Titre par défaut</div>
+    </ng-content>
+    <ng-content>Contenu par défaut</ng-content>
+  `
+})
+```
+
+### 2. HTTP Cache Auth
+```typescript
+// Pour apps avec auth
+bootstrapApplication(App, {
+  providers: [
+    provideHttpClient(
+      withHttpTransferCache({ 
+        includeRequestsWithAuthHeaders: true 
+      })
+    )
+  ]
+});
+```
+
+### 3. Hydratation Partielle
+```typescript
+// Template avec defer
+@Component({
+  template: `
+    @defer (render on server; on viewport) {
+      <heavy-component />
+    }
+    @placeholder {
+      <div>Chargement...</div>
+    }
+  `
+})
+```
+
+---
+
+## 📊 Checklist Migration Complète
+
+```typescript
+// migration-check.ts
+interface MigrationStatus {
+  obligatoire: {
+    node18: boolean;           // node --version >= 18.19
+    typescript5: boolean;      // tsc --version >= 5.4
+    imports: boolean;          // waitForAsync, StateKey, TransferState
+    platformServer: boolean;   // platformDynamicServer -> platformServer
+    routing: boolean;          // RedirectCommand, redirectTo function
+    ngModelExpressions: boolean; // Pas d'assignation dans [(ngModel)]
+    testability: boolean;      // Supprimer increasePendingRequestCount
+    resourceCache: boolean;    // Supprimer RESOURCE_CACHE_PROVIDER
+    serverTransfer: boolean;   // Supprimer ServerTransferStateModule
+    environmentProviders: boolean; // Déplacer de RouterOutlet
+    onPushDetection: boolean;  // markForCheck() pour host bindings
+    testDetection: boolean;    // ignoreChangesOutsideZone si nécessaire
+  };
+  recommandee: {
+    zoneless?: boolean;        // provideExperimentalZonelessChangeDetection
+    coalescence: boolean;      // eventCoalescing: true
+    signals?: boolean;         // signal() usage
+    eventReplay?: boolean;     // SSR withEventReplay
+    formsEvents?: boolean;     // control.events au lieu de multiple subscribes
+  };
+  optionnelle: {
+    ngContent?: boolean;       // default content
+    httpCache?: boolean;       // includeRequestsWithAuthHeaders
+    partialHydration?: boolean; // @defer SSR
+    asyncAwait?: boolean;      // natif sans zones
+  };
+}
+```
+
+## 🚀 Script Migration Automatisé
+
+```bash
+#!/bin/bash
+# migration-v18.sh
+
+echo "🔄 Angular 17 -> 18 Migration Starting..."
+
+# 1. Backup
+git checkout -b migration-angular-18
+git add . && git commit -m "Pre-migration backup"
+
+# 2. Update deps
+echo "📦 Updating dependencies..."
+npm install typescript@~5.4.0
+ng update @angular/core@18 @angular/cli@18 --verbose
+
+# 3. Fix imports automatiquement
+echo "🔧 Fixing imports..."
+find . -name "*.ts" -not -path "*/node_modules/*" | while read file; do
+  # async -> waitForAsync
+  sed -i "s/import { async }/import { waitForAsync }/g" "$file"
+  sed -i "s/async(/waitForAsync(/g" "$file"
+  
+  # StateKey, TransferState
+  sed -i "s/@angular\/platform-browser'/@angular\/core'/g" "$file"
+  
+  # platformDynamicServer -> platformServer
+  sed -i "s/platformDynamicServer/platformServer/g" "$file"
+  
+  # Remove ServerTransferStateModule
+  sed -i "/ServerTransferStateModule/d" "$file"
+done
+
+# 4. Add compiler import where needed
+echo "import '@angular/compiler';" >> src/main.server.ts
+
+# 5. Verify & Test
+echo "🧪 Running tests..."
+ng test --no-watch --code-coverage
+ng build --configuration production
+
+echo "✅ Migration complete! Check git diff for review"
+```
+
+## ⚠️ Points d'Attention & Validation
+
+| Catégorie | Risque | Solution | Vérification |
+|-----------|--------|----------|--------------|
+| Tests | `whenStable()` plus lent | `ignoreChangesOutsideZone: true` | `ng test` passe |
+| OnPush | Host bindings non mis à jour | `markForCheck()` manuel | Vérifier les `@HostBinding` |
+| SSR | Event loss avant hydratation | Activer Event Replay | Tester interactions précoces |
+| Platform Server | URLs incorrectes | Pathname avec `/` final | Vérifier routes SSR |
+| Guards | Redirections non appliquées | Utiliser `RedirectCommand` | Tester auth flows |
+| Providers | Services non disponibles | Déplacer vers bootstrap | Vérifier injection |
+
+## 📈 Validation Finale
+
+```typescript
+// validation.spec.ts
+describe('Migration Angular 18 Validation', () => {
+  it('should verify all obligatory changes', () => {
+    // Node version
+    expect(process.version).toMatch(/^v(18\.19|[2-9]\d)/);
+    
+    // TypeScript version
+    const ts = require('typescript');
+    expect(ts.version).toMatch(/^5\.[4-9]/);
+    
+    // No deprecated imports
+    const hasAsync = /import.*async.*from.*@angular\/core/.test(code);
+    expect(hasAsync).toBe(false);
+    
+    // No ServerTransferStateModule
+    const hasSTSM = /ServerTransferStateModule/.test(code);
+    expect(hasSTSM).toBe(false);
+  });
+});
+```