@silvestv/migration-planificator 3.0.0

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

@@ -0,0 +1,600 @@
+# Guide Migration Angular 18→19 avec Exemples
+
+## 🔴 RÈGLES OBLIGATOIRES (Breaking Changes)
+
+### 1. Environnement
+```bash
+# ❌ Avant: TypeScript 5.4
+# ✅ Après: 
+npm install typescript@~5.5.0  # Minimum 5.5, 5.4 n'est plus supporté
+ng update @angular/core@19 @angular/cli@19
+ng update @angular/material@19  # Si Material est utilisé
+```
+
+### 2. Standalone par défaut & Migration
+```typescript
+// ⚠️ BREAKING CHANGE: standalone est maintenant true par défaut
+
+// Pour les projets existants, 2 options:
+
+// Option 1: Quick fix - Ajouter standalone: false partout
+@Component({
+  selector: 'app-legacy',
+  standalone: false,  // Ajout obligatoire pour composants non-standalone
+  template: `...`
+})
+
+// Option 2: Migration complète (recommandée)
+// Exécuter les 3 commandes dans l'ordre:
+```
+
+```bash
+# 1. Convertir en standalone
+ng generate @angular/core:standalone
+# → "Convert all components, directives and pipes to standalone"
+
+# 2. Supprimer NgModules inutiles  
+ng generate @angular/core:standalone
+# → "Remove unnecessary NgModule classes"
+
+# 3. Bootstrap standalone
+ng generate @angular/core:standalone
+# → "Bootstrap the project using standalone APIs"
+```
+
+### 3. Template Reference Variables
+```typescript
+// ❌ Avant
+@Component({
+  template: `
+    <div #myDiv></div>
+    <button (click)="onClick(this.myDiv)">{{ this.myDiv.textContent }}</button>
+  `
+})
+
+// ✅ Après
+@Component({
+  template: `
+    <div #myDiv></div>
+    <button (click)="onClick(myDiv)">{{ myDiv.textContent }}</button>
+  `
+})
+```
+
+### 4. BrowserModule.withServerTransition
+```typescript
+// ❌ Avant
+@NgModule({
+  imports: [
+    BrowserModule.withServerTransition({ appId: 'my-app' })
+  ]
+})
+
+// ✅ Après
+import { APP_ID } from '@angular/core';
+
+bootstrapApplication(AppComponent, {
+  providers: [
+    { provide: APP_ID, useValue: 'my-app' }
+  ]
+});
+```
+
+### 5. KeyValueDiffers factories
+```typescript
+// ❌ Avant
+const differs = inject(KeyValueDiffers);
+const factories = differs.factories; // Propriété supprimée
+
+// ✅ Après
+const differs = inject(KeyValueDiffers);
+// Utiliser directement les méthodes find() et create()
+const differ = differs.find({}).create();
+```
+
+### 6. Angular.json Localize
+```json
+// ❌ Avant
+{
+  "builder": "@angular/localize:extract",
+  "options": {
+    "name": "my-project"
+  }
+}
+
+// ✅ Après
+{
+  "builder": "@angular/localize:extract",
+  "options": {
+    "project": "my-project"  // "name" → "project"
+  }
+}
+```
+
+### 7. PendingTasks (ExperimentalPendingTasks)
+```typescript
+// ❌ Avant
+import { ExperimentalPendingTasks } from '@angular/core';
+
+@Injectable()
+export class MyService {
+  tasks = inject(ExperimentalPendingTasks);
+}
+
+// ✅ Après
+import { PendingTasks } from '@angular/core';
+
+@Injectable()
+export class MyService {
+  tasks = inject(PendingTasks);
+}
+```
+
+### 8. Router.errorHandler Migration
+```typescript
+// ❌ Avant
+@Injectable()
+export class MyErrorHandler {
+  constructor(private router: Router) {
+    this.router.errorHandler = (error) => {
+      console.error('Navigation error:', error);
+    };
+  }
+}
+
+// ✅ Après
+bootstrapApplication(AppComponent, {
+  providers: [
+    provideRouter(routes, 
+      withNavigationErrorHandler((error) => {
+        console.error('Navigation error:', error);
+      })
+    )
+  ]
+});
+```
+
+### 9. Resolve Interface avec RedirectCommand
+```typescript
+// ❌ Avant
+class UserResolver implements Resolve<User> {
+  resolve(): Observable<User> | Promise<User> | User {
+    return this.userService.getUser();
+  }
+}
+
+// ✅ Après
+import { RedirectCommand } from '@angular/router';
+
+class UserResolver implements Resolve<User | RedirectCommand> {
+  resolve(): Observable<User | RedirectCommand> | Promise<User | RedirectCommand> | User | RedirectCommand {
+    return this.userService.getUser().pipe(
+      catchError(() => of(new RedirectCommand('/error')))
+    );
+  }
+}
+```
+
+### 10. Tests Effects Timing
+```typescript
+// ❌ Avant - Tests avec effects
+it('should update on effect', () => {
+  component.triggerEffect();
+  expect(component.value).toBe('updated'); // Peut échouer
+});
+
+// ✅ Après
+it('should update on effect', async () => {
+  component.triggerEffect();
+  await fixture.whenStable(); // Attendre les effects
+  // OU
+  fixture.detectChanges(); // Déclencher manuellement
+  expect(component.value).toBe('updated');
+});
+```
+
+### 11. FakeAsync Flush par défaut
+```typescript
+// ❌ Avant
+it('should work', fakeAsync(() => {
+  setTimeout(() => value = true, 100);
+  tick(100);
+  // Les timers ne sont pas automatiquement flush
+}));
+
+// ✅ Après
+it('should work', fakeAsync(() => {
+  setTimeout(() => value = true, 100);
+  tick(100);
+  // Les timers sont automatiquement flush
+}));
+
+// Pour l'ancien comportement
+it('should work', fakeAsync(() => {
+  // Code...
+}, {flush: false})); // Désactiver le flush automatique
+```
+
+### 12. CreateComponent et ng-content
+```typescript
+// ❌ Avant
+const componentRef = createComponent(MyComponent, {
+  // Pas de contenu projeté → affiche le fallback par défaut
+});
+
+// ✅ Après
+const componentRef = createComponent(MyComponent, {
+  projectableNodes: [[document.createTextNode('')]] // Évite le fallback
+});
+```
+
+---
+
+## 🟡 RÈGLES RECOMMANDÉES
+
+### 1. Migrations vers Signals (Séparées)
+```typescript
+// Migration @Input vers input()
+ng generate @angular/core:signal-input-migration
+
+// ❌ Avant
+@Input() name: string;
+@Input() required age: number;
+
+// ✅ Après
+readonly name = input<string>();
+readonly age = input.required<number>();
+
+// Migration @Output vers output()
+ng generate @angular/core:output-migration
+
+// ❌ Avant
+@Output() userChange = new EventEmitter<User>();
+
+// ✅ Après
+readonly userChange = output<User>();
+```
+
+### 2. LinkedSignal pour état réactif  
+```typescript
+// ❌ Avant - Gestion manuelle de dépendances
+export class FilterComponent {
+  category = signal('all');
+  itemsPerPage = signal(10);
+  
+  ngOnInit() {
+    effect(() => {
+      if (this.category() !== 'all') {
+        this.itemsPerPage.set(10); // Reset manuel
+      }
+    });
+  }
+}
+
+// ✅ Après avec linkedSignal
+export class FilterComponent {
+  category = signal('all');
+  itemsPerPage = linkedSignal({
+    source: this.category,
+    computation: () => 10  // Reset automatique
+  });
+}
+```
+
+### 4. Nouveaux Initialisateurs
+```typescript
+// ❌ Avant
+export const appConfig = {
+  providers: [
+    {
+      provide: APP_INITIALIZER,
+      useFactory: () => () => inject(ConfigService).load(),
+      multi: true,
+      deps: [ConfigService]
+    }
+  ]
+};
+
+// ✅ Après
+import { provideAppInitializer } from '@angular/core';
+
+export const appConfig = {
+  providers: [
+    provideAppInitializer(() => {
+      const configService = inject(ConfigService);
+      return configService.load();
+    })
+  ]
+};
+```
+
+### 5. Partage via RouterOutlet
+```typescript
+// ❌ Avant - Props drilling ou services
+@Component({
+  template: `<router-outlet></router-outlet>`
+})
+export class ParentComponent {
+  // Données passées via services ou inputs complexes
+}
+
+// ✅ Après avec routerOutletData
+@Component({
+  template: `
+    <router-outlet [routerOutletData]="sharedData"></router-outlet>
+  `
+})
+export class ParentComponent {
+  sharedData = signal({ theme: 'dark', user: currentUser });
+}
+
+// Dans le composant enfant
+export class ChildComponent {
+  data = inject(ROUTER_OUTLET_DATA); // Signal réactif
+}
+```
+
+---
+
+## 🟢 RÈGLES OPTIONNELLES
+
+### 1. API Resource pour HTTP
+```typescript
+// ✅ Nouvelle approche optionnelle
+import { resource, ResourceStatus } from '@angular/core';
+
+@Component({
+  template: `
+    @switch (userResource.status()) {
+      @case (ResourceStatus.Loading) { <p>Chargement...</p> }
+      @case (ResourceStatus.Error) { <p>Erreur: {{ userResource.error() }}</p> }
+      @case (ResourceStatus.Resolved) { 
+        <p>{{ userResource.value().name }}</p>
+        <button (click)="userResource.reload()">Recharger</button>
+      }
+    }
+  `
+})
+export class UserComponent {
+  userResource = resource({
+    loader: () => fetch('/api/user').then(r => r.json())
+  });
+}
+
+// Avec paramètres réactifs
+export class SearchComponent {
+  searchTerm = signal('');
+  results = resource({
+    request: this.searchTerm,
+    loader: ({ request }) => 
+      fetch(`/api/search?q=${request}`).then(r => r.json())
+  });
+}
+```
+
+### 2. Hydratation Incrémentale
+```typescript
+// ✅ Nouveau - Hydratation différée
+@Component({
+  template: `
+    @defer (render on server; hydrate on interaction) {
+      <heavy-component />
+    } @placeholder {
+      <loading-skeleton />
+    }
+  `
+})
+
+// main.ts
+bootstrapApplication(App, {
+  providers: [
+    provideClientHydration(withIncrementalHydration())
+  ]
+});
+```
+
+### 2. Service Worker Amélioré
+```json
+// ngsw-config.json
+{
+  "applicationMaxAge": "7d",  // Nouveau
+  "dataGroups": [{
+    "name": "api-cache",
+    "urls": ["/api/**"],
+    "cacheConfig": {
+      "maxAge": "1h",
+      "refreshAhead": "10m"  // Nouveau
+    }
+  }]
+}
+```
+
+### 3. Rendu Hybride
+```typescript
+// app.routes.server.ts (nouveau fichier)
+import { RenderMode } from '@angular/ssr';
+
+export const serverRoutes = [
+  { path: '', renderMode: RenderMode.Prerender },
+  { path: 'blog/**', renderMode: RenderMode.Server },
+  { path: 'admin/**', renderMode: RenderMode.Client }
+];
+
+// Installation
+// ng add @angular/ssr --server-routing
+```
+
+### 4. Control Flow Migration
+```typescript
+// ❌ Avant - Directives
+<div *ngIf="show">Content</div>
+<div *ngFor="let item of items">{{ item }}</div>
+
+// ✅ Après - Control Flow
+@if (show) {
+  <div>Content</div>
+}
+@for (item of items; track item.id) {
+  <div>{{ item }}</div>
+}
+
+// Migration automatique
+// ng generate @angular/core:control-flow
+```
+
+### 6. Lazy Loading Routes Migration
+```bash
+# Migration automatique vers lazy loading
+ng generate @angular/core:route-lazy-loading
+
+# Pour un dossier spécifique
+ng generate @angular/core:route-lazy-loading --path src/app/features
+```
+
+```typescript
+// ❌ Avant - Eager loading
+const routes: Routes = [
+  {
+    path: 'users',
+    component: UsersComponent  // Composant standalone chargé eagerly
+  }
+];
+
+// ✅ Après - Lazy loading automatique
+const routes: Routes = [
+  {
+    path: 'users',
+    loadComponent: () => import('./users/users.component').then(m => m.UsersComponent)
+  }
+];
+```
+
+---
+
+## 📊 Checklist Migration Complète
+
+```typescript
+interface MigrationStatus19 {
+  obligatoire: {
+    typescript55: boolean;         // v5.5+
+    standaloneDefault: boolean;    // standalone: false explicite
+    templateRefs: boolean;         // Supprimer this.
+    browserModule: boolean;        // APP_ID token
+    keyValueDiffers: boolean;      // Supprimer .factories
+    localizeName: boolean;         // name → project
+    pendingTasks: boolean;         // Experimental → stable
+    routerErrorHandler: boolean;   // withNavigationErrorHandler
+    resolveRedirect: boolean;      // RedirectCommand dans Resolve
+    effectsTiming: boolean;        // whenStable() pour tests
+    fakeAsyncFlush: boolean;       // {flush: false} si nécessaire
+    createComponent: boolean;      // projectableNodes vide
+  };
+  recommandee: {
+    signalsMigration?: boolean;    // @Input → input()
+    resourceAPI?: boolean;         // Gestion état HTTP
+    linkedSignal?: boolean;        // Signaux liés
+    newInitializers?: boolean;     // provideAppInitializer
+    routerOutletData?: boolean;    // Partage parent-enfant
+  };
+  optionnelle: {
+    incrementalHydration?: boolean; // @defer hydrate
+    serviceWorker?: boolean;       // refreshAhead, maxAge
+    hybridRendering?: boolean;     // Rendu par route
+    controlFlow?: boolean;         // @if, @for, @switch
+    injectFunction?: boolean;      // inject() vs constructor
+  };
+}
+```
+
+## 🚀 Script Migration Automatisé
+
+```bash
+#!/bin/bash
+# migration-v19.sh
+
+echo "🔄 Angular 18 -> 19 Migration Starting..."
+
+# 1. Backup
+git checkout -b migration-angular-19
+git add . && git commit -m "Pre-migration v19 backup"
+
+# 2. Core updates
+echo "📦 Updating to Angular 19..."
+npm install typescript@~5.5.0
+ng update @angular/core@19 @angular/cli@19 --verbose
+ng update @angular/material@19 # Si utilisé
+
+# 3. Fix automatiques obligatoires
+echo "🔧 Applying mandatory fixes..."
+find . -name "*.ts" -not -path "*/node_modules/*" | while read file; do
+  # Remove this. prefix from template refs
+  sed -i 's/this\.\([a-zA-Z_][a-zA-Z0-9_]*\)/\1/g' "$file"
+  
+  # Rename ExperimentalPendingTasks
+  sed -i 's/ExperimentalPendingTasks/PendingTasks/g' "$file"
+done
+
+# 4. Angular.json updates
+sed -i 's/"name":/"project":/g' angular.json
+
+# 5. Migrations recommandées (interactives)
+echo "🎯 Running recommended migrations..."
+
+# Migration Standalone (3 étapes)
+echo "📦 Step 1/3: Converting to standalone..."
+ng generate @angular/core:standalone # Choisir option 1
+
+echo "📦 Step 2/3: Removing unnecessary modules..."
+ng generate @angular/core:standalone # Choisir option 2
+
+echo "📦 Step 3/3: Bootstrap with standalone API..."
+ng generate @angular/core:standalone # Choisir option 3
+
+# Migrations des signals (séparées)
+echo "🎯 Migrating inputs to signals..."
+ng generate @angular/core:signal-input-migration --best-effort-mode
+
+echo "🎯 Migrating outputs to signals..."
+ng generate @angular/core:output-migration
+
+echo "🎯 Migrating queries to signals..."
+ng generate @angular/core:signal-queries-migration
+
+# 6. Migrations optionnelles
+read -p "Apply optional migrations? (y/n) " -n 1 -r
+echo
+if [[ $REPLY =~ ^[Yy]$ ]]
+then
+  echo "🔄 Applying optional migrations..."
+  ng generate @angular/core:control-flow
+  ng generate @angular/core:inject
+  ng generate @angular/core:route-lazy-loading
+fi
+
+# 7. Tests
+echo "🧪 Running validation..."
+ng test --no-watch --code-coverage
+ng build --configuration production
+
+echo "✅ Migration complete! Review changes with: git diff"
+echo "📝 Check for TODOs: grep -r 'TODO' src/"
+```
+
+## ⚠️ Points d'Attention & Validation
+
+| Catégorie | Risque | Solution | Vérification |
+|-----------|--------|----------|--------------|
+| Standalone | Composants legacy cassés | Ajouter `standalone: false` | Build sans erreurs |
+| Effects | Tests timing incorrects | Utiliser `whenStable()` | Tests passent |
+| FakeAsync | Comportement modifié | Option `{flush: false}` | Tests timing OK |
+| Signals | Migration incomplète | Mode `--best-effort` | Vérifier TODOs |
+| Hydratation | SSR performance | Activer incremental | Mesurer LCP |
+| Router | ErrorHandler obsolète | Migration provider | Gestion erreurs OK |
+
+## 📈 Métriques Cibles
+
+- **Bundle**: -15% avec signals et lazy loading
+- **Hydratation**: -30% TTI avec incremental
+- **Build**: -20% temps avec esbuild
+- **Tests**: -40% durée avec esbuild runner
+- **Coverage**: Maintenir >80%