@aliaksei-raketski/pi-angular-developer 0.1.0

package/scripts/sync-angular-skill.mjs

@@ -0,0 +1,307 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import {spawnSync} from 'node:child_process';
+import {fileURLToPath} from 'node:url';
+
+const UPSTREAM_REPO = 'https://github.com/angular/skills';
+const DEFAULT_REF = '28a90e30bba8cbc9d3a6aab56093e5b9b974bc9e';
+const KNOWN_OVERLAY_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'overlays', 'angular-developer');
+const PKG_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
+const TARGET_SKILL_DIR = path.join(PKG_ROOT, 'skills', 'angular-developer');
+const TARGET_UPSTREAM_FILE = path.join(TARGET_SKILL_DIR, 'UPSTREAM.md');
+const TARGET_DATA_FILE = path.join(TARGET_SKILL_DIR, 'data', 'best-practices.md');
+const STALE_PATTERNS = [
+  /find_examples/i,
+  /get_best_practices/i,
+  /search_documentation/i,
+  /references\/mcp\.md/i,
+  /Angular MCP Server/i,
+  /\bMCP\b/i,
+];
+
+main().catch((error) => {
+  console.error(`Fatal: ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(1);
+});
+
+async function main() {
+  const requestedRef = process.env.ANGULAR_SKILLS_REF || DEFAULT_REF;
+  const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'angular-skills-'));
+
+  try {
+    const checkout = await syncUpstreamSource(tempDir, requestedRef, requestedRef === DEFAULT_REF);
+    await copySkillFromUpstream(checkout.repoDir);
+    await applyOverlayAndMetadata(checkout, requestedRef);
+    await sanitizeVendoredContent(TARGET_SKILL_DIR);
+
+    await refreshBestPractices(TARGET_SKILL_DIR);
+    await validateNoStaleMcpReferences(TARGET_SKILL_DIR);
+
+    console.log(`Synced angular-developer skill to ${checkout.resolvedRef} (${checkout.requestedRef}).`);
+  } finally {
+    await fs.rm(tempDir, {recursive: true, force: true});
+  }
+}
+
+async function syncUpstreamSource(tempDir, requestedRef, allowFallback = false) {
+  const cloneDir = path.join(tempDir, 'angular-skills');
+
+  run('git', ['clone', '--depth', '1', '--filter=blob:none', UPSTREAM_REPO, cloneDir]);
+
+  let resolvedRef;
+  let usedFallback = false;
+
+  try {
+    run('git', ['-C', cloneDir, 'checkout', '--quiet', requestedRef]);
+    resolvedRef = revParse(cloneDir, 'HEAD');
+  } catch {
+    try {
+      run('git', ['-C', cloneDir, 'fetch', '--depth', '1', 'origin', requestedRef]);
+      run('git', ['-C', cloneDir, 'checkout', '--quiet', 'FETCH_HEAD']);
+      resolvedRef = revParse(cloneDir, 'HEAD');
+      console.error(`Info: checked out requested ref ${requestedRef} after remote fetch.`);
+    } catch {
+      if (!allowFallback) {
+        throw new Error(`Unable to resolve requested ref ${requestedRef}.`);
+      }
+
+      usedFallback = true;
+      console.error(`Warning: could not resolve ref ${requestedRef}; falling back to origin/main.`);
+      run('git', ['-C', cloneDir, 'fetch', '--depth', '1', 'origin', 'main:refs/remotes/origin/main']);
+      run('git', ['-C', cloneDir, 'checkout', '--quiet', 'origin/main']);
+      resolvedRef = revParse(cloneDir, 'HEAD');
+    }
+  }
+
+  return {
+    repoDir: cloneDir,
+    requestedRef,
+    resolvedRef,
+    usedFallback,
+  };
+}
+
+async function copySkillFromUpstream(repoDir) {
+  const sourceDir = path.join(repoDir, 'angular-developer');
+
+  if (!(await exists(sourceDir))) {
+    throw new Error(`Expected upstream directory ${sourceDir} not found.`);
+  }
+
+  await fs.rm(TARGET_SKILL_DIR, {recursive: true, force: true});
+  await fs.mkdir(path.dirname(TARGET_SKILL_DIR), {recursive: true});
+  await fs.cp(sourceDir, TARGET_SKILL_DIR, {recursive: true});
+}
+
+async function applyOverlayAndMetadata(meta) {
+  const skillPath = path.join(TARGET_SKILL_DIR, 'SKILL.md');
+  let skillContent = await fs.readFile(skillPath, 'utf8');
+
+  const mcpToolingLine =
+    '- **Angular MCP Server**: Available tools, configuration, and experimental features. Read [mcp.md](references/mcp.md)';
+  const mcpToolingReplacement =
+    '- **Angular documentation helpers**: Use local helper scripts for version-aware best practices and official angular.dev documentation search. Read [docs-helpers.md](references/docs-helpers.md)';
+
+  if (!skillContent.includes(mcpToolingReplacement)) {
+    if (!skillContent.includes(mcpToolingLine)) {
+      throw new Error('Expected MCP tooling line was not found in upstream SKILL.md.');
+    }
+
+    skillContent = skillContent.replace(mcpToolingLine, mcpToolingReplacement);
+  }
+
+  const topRule =
+    '4. When you need version-aware Angular best practices or official angular.dev documentation search, use the local helper scripts documented in [docs-helpers.md](references/docs-helpers.md).';
+
+  if (!skillContent.includes(topRule)) {
+    skillContent = skillContent.replace(
+      '\n## Creating New Projects\n',
+      `\n${topRule}\n\n## Creating New Projects\n`,
+    );
+
+    if (!skillContent.includes(topRule)) {
+      throw new Error('Failed to insert local helper rule in SKILL.md.');
+    }
+  }
+
+  await fs.writeFile(skillPath, skillContent, 'utf8');
+
+  await removeIfExists(path.join(TARGET_SKILL_DIR, 'references', 'mcp.md'));
+
+  const overlayReference = path.join(KNOWN_OVERLAY_PATH, 'references', 'docs-helpers.md');
+  await ensureDir(path.join(TARGET_SKILL_DIR, 'references'));
+  await fs.copyFile(overlayReference, path.join(TARGET_SKILL_DIR, 'references', 'docs-helpers.md'));
+
+  const overlayScripts = path.join(KNOWN_OVERLAY_PATH, 'scripts');
+  const targetScripts = path.join(TARGET_SKILL_DIR, 'scripts');
+  await ensureDir(targetScripts);
+
+  const scriptFiles = await fs.readdir(overlayScripts);
+  for (const file of scriptFiles) {
+    await fs.copyFile(path.join(overlayScripts, file), path.join(targetScripts, file));
+  }
+
+  const timestamp = new Date().toISOString();
+  const sourceRef = `resolved ref ${meta.resolvedRef}`;
+
+  const upstreamContent = `# Angular Developer upstream sync metadata
+
+Repository: ${UPSTREAM_REPO}
+Synced at: ${timestamp}
+Requested ref: ${meta.requestedRef}
+Synced ref: ${meta.resolvedRef}
+Fallback used: ${meta.usedFallback ? 'yes' : 'no'}
+Upstream source: ${sourceRef}
+Local overlay source: overlays/angular-developer/
+`;
+
+  await fs.writeFile(TARGET_UPSTREAM_FILE, upstreamContent, 'utf8');
+}
+
+async function sanitizeVendoredContent(skillDir) {
+  const e2eReference = path.join(skillDir, 'references', 'e2e-testing.md');
+  if (await exists(e2eReference)) {
+    const content = await fs.readFile(e2eReference, 'utf8');
+    const sanitized = content.replace(/ng-devtools-mcp/g, 'ng-devtools');
+    if (sanitized !== content) {
+      await fs.writeFile(e2eReference, sanitized, 'utf8');
+    }
+  }
+}
+
+async function refreshBestPractices(skillDir) {
+  const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'angular-core-'));
+  try {
+    const packResult = run('npm', ['pack', '@angular/core@latest', '--silent', '--json'], {cwd: tempDir});
+    const packEntries = JSON.parse(packResult);
+
+    if (!Array.isArray(packEntries) || !packEntries.length) {
+      throw new Error('npm pack output did not contain package metadata.');
+    }
+
+    const entry = packEntries[0];
+    if (typeof entry.filename !== 'string') {
+      throw new Error('npm pack output missing filename.');
+    }
+
+    const tarballPath = path.join(tempDir, entry.filename);
+    const packageJsonText = run('tar', ['-xOf', tarballPath, 'package/package.json']);
+    const packageJson = JSON.parse(packageJsonText);
+
+    const bestPractices = packageJson?.angular?.bestPractices;
+    if (!bestPractices || bestPractices.format !== 'markdown' || typeof bestPractices.path !== 'string') {
+      throw new Error('Invalid @angular/core best-practices metadata.');
+    }
+
+    const normalizedPath = normalizePackagePath(bestPractices.path);
+    const markdownText = run('tar', ['-xOf', tarballPath, `package/${normalizedPath}`]);
+
+    await ensureDir(path.join(skillDir, 'data'));
+    await fs.writeFile(TARGET_DATA_FILE, markdownText, 'utf8');
+    console.log(`Updated data/best-practices.md from ${packageJson.version ?? 'latest @angular/core'}.`);
+  } finally {
+    await fs.rm(tempDir, {recursive: true, force: true});
+  }
+}
+
+function normalizePackagePath(rawPath) {
+  const normalized = path.posix.normalize(rawPath.replace(/^\/+/, ''));
+
+  if (normalized.startsWith('../') || normalized.includes('/../') || path.posix.isAbsolute(normalized)) {
+    throw new Error(`Unsafe best-practices path in package metadata: ${rawPath}`);
+  }
+
+  return normalized;
+}
+
+async function validateNoStaleMcpReferences(skillDir) {
+  const staleMatches = [];
+
+  const paths = await gatherFiles(skillDir);
+  for (const filePath of paths) {
+    const ext = path.extname(filePath).toLowerCase();
+    if (!['.md', '.mjs', '.json'].includes(ext)) {
+      continue;
+    }
+
+    const text = await fs.readFile(filePath, 'utf8');
+
+    for (const pattern of STALE_PATTERNS) {
+      if (pattern.test(text)) {
+        staleMatches.push(`${path.relative(PKG_ROOT, filePath)}: ${pattern.source}`);
+        break;
+      }
+    }
+  }
+
+  if (staleMatches.length > 0) {
+    throw new Error(`Found stale MCP references in vendored skill:\n${staleMatches.join('\n')}`);
+  }
+
+  console.log('Validation passed: no stale MCP references found.');
+}
+
+async function gatherFiles(root) {
+  const results = [];
+  const entries = await fs.readdir(root, {withFileTypes: true});
+
+  for (const entry of entries) {
+    const fullPath = path.join(root, entry.name);
+
+    if (entry.isDirectory()) {
+      results.push(...(await gatherFiles(fullPath)));
+      continue;
+    }
+
+    if (entry.isFile()) {
+      results.push(fullPath);
+    }
+  }
+
+  return results;
+}
+
+function revParse(repoDir, rev) {
+  return run('git', ['-C', repoDir, 'rev-parse', rev]);
+}
+
+function run(command, args, options = {}) {
+  const {cwd} = options;
+  const result = spawnSync(command, args, {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+  if (result.error) {
+    throw new Error(result.error.message);
+  }
+
+  if (result.status !== 0) {
+    const stderr = String(result.stderr || '').trim();
+    const prefix = stderr ? `: ${stderr}` : '';
+    throw new Error(`${command} ${args.join(' ')} failed with code ${result.status}${prefix}`);
+  }
+
+  return String(result.stdout || '').trim();
+}
+
+async function exists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function removeIfExists(target) {
+  await fs.rm(target, {recursive: true, force: true});
+}
+
+async function ensureDir(target) {
+  await fs.mkdir(target, {recursive: true});
+}

package/skills/angular-developer/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: angular-developer
+description: Generates Angular code and provides architectural guidance. Trigger when creating projects, components, or services, or for best practices on reactivity (signals, linkedSignal, resource), forms, dependency injection, routing, SSR, accessibility (ARIA), animations, styling (component styles, Tailwind CSS), testing, or CLI tooling.
+license: MIT
+metadata:
+  author: Copyright 2026 Google LLC
+  version: '1.0'
+---
+
+# Angular Developer Guidelines
+
+1. Always analyze the project's Angular version before providing guidance, as best practices and available features can vary significantly between versions. If creating a new project with Angular CLI, do not specify a version unless prompted by the user.
+
+2. When generating code, follow Angular's style guide and best practices for maintainability and performance. Use the Angular CLI for scaffolding components, services, directives, pipes, and routes to ensure consistency.
+
+3. Once you finish generating code, run `ng build` to ensure there are no build errors. If there are errors, analyze the error messages and fix them before proceeding. Do not skip this step, as it is critical for ensuring the generated code is correct and functional.
+
+4. When you need version-aware Angular best practices or official angular.dev documentation search, use the local helper scripts documented in [docs-helpers.md](references/docs-helpers.md).
+
+## Creating New Projects
+
+If no guidelines are provided by the user, here are same default rules to follow when creating a new Angular project:
+
+1. Use the latest stable version of Angular unless the user specifies otherwise.
+2. Use Signals Forms for form management in new projects (available in Angular v21 and newer) [Find out more](references/signal-forms.md).
+
+**Execution Rules for `ng new`:**
+When asked to create a new Angular project, you must determine the correct execution command by following these strict steps:
+
+**Step 1: Check for an explicit user version.**
+
+- **IF** the user requests a specific version (e.g., Angular 15), bypass local installations and strictly use `npx`.
+- **Command:** `npx @angular/cli@<requested_version> new <project-name>`
+
+**Step 2: Check for an existing Angular installation.**
+
+- **IF** no specific version is requested, run `ng version` in the terminal to check if the Angular CLI is already installed on the system.
+- **IF** the command succeeds and returns an installed version, use the local/global installation directly.
+- **Command:** `ng new <project-name>`
+
+**Step 3: Fallback to Latest.**
+
+- **IF** no specific version is requested AND the `ng version` command fails (indicating no Angular installation exists), you must use `npx` to fetch the latest version.
+- **Command:** `npx @angular/cli@latest new <project-name>`
+
+## Components
+
+When working with Angular components, consult the following references based on the task:
+
+- **Fundamentals**: Anatomy, metadata, core concepts, and template control flow (@if, @for, @switch). Read [components.md](references/components.md)
+- **Inputs**: Signal-based inputs, transforms, and model inputs. Read [inputs.md](references/inputs.md)
+- **Outputs**: Signal-based outputs and custom event best practices. Read [outputs.md](references/outputs.md)
+- **Host Elements**: Host bindings and attribute injection. Read [host-elements.md](references/host-elements.md)
+
+If you require deeper documentation not found in the references above, read the documentation at `https://angular.dev/guide/components`.
+
+## Reactivity and Data Management
+
+When managing state and data reactivity, use Angular Signals and consult the following references:
+
+- **Signals Overview**: Core signal concepts (`signal`, `computed`), reactive contexts, and `untracked`. Read [signals-overview.md](references/signals-overview.md)
+- **Dependent State (`linkedSignal`)**: Creating writable state linked to source signals. Read [linked-signal.md](references/linked-signal.md)
+- **Async Reactivity (`resource`)**: Fetching asynchronous data directly into signal state. Read [resource.md](references/resource.md)
+- **Side Effects (`effect`)**: Logging, third-party DOM manipulation (`afterRenderEffect`), and when NOT to use effects. Read [effects.md](references/effects.md)
+
+## Forms
+
+In most cases for new apps, **prefer signal forms**. When making a forms decision, analyze the project and consider the following guidelines:
+
+- if the application is using v21 or newer and this is a new form, **prefer signal forms**.
+  -For older applications or when working with existing forms, use the appropriate form type that matches the applications current form strategy.
+
+- **Signal Forms**: Use signals for form state management. Read [signal-forms.md](references/signal-forms.md)
+- **Template-driven forms**: Use for simple forms. Read [template-driven-forms.md](references/template-driven-forms.md)
+- **Reactive forms**: Use for complex forms. Read [reactive-forms.md](references/reactive-forms.md)
+
+## Dependency Injection
+
+When implementing dependency injection in Angular, follow these guidelines:
+
+- **Fundamentals**: Overview of Dependency Injection, services, and the `inject()` function. Read [di-fundamentals.md](references/di-fundamentals.md)
+- **Creating and Using Services**: Creating services, the `providedIn: 'root'` option, and injecting into components or other services. Read [creating-services.md](references/creating-services.md)
+- **Defining Dependency Providers**: Automatic vs manual provision, `InjectionToken`, `useClass`, `useValue`, `useFactory`, and scopes. Read [defining-providers.md](references/defining-providers.md)
+- **Injection Context**: Where `inject()` is allowed, `runInInjectionContext`, and `assertInInjectionContext`. Read [injection-context.md](references/injection-context.md)
+- **Hierarchical Injectors**: The `EnvironmentInjector` vs `ElementInjector`, resolution rules, modifiers (`optional`, `skipSelf`), and `providers` vs `viewProviders`. Read [hierarchical-injectors.md](references/hierarchical-injectors.md)
+
+## Angular Aria
+
+When building accessible custom components for any of the following patterns: Accordion, Listbox, Combobox, Menu, Tabs, Toolbar, Tree, Grid, consult the following reference:
+
+- **Angular Aria Components**: Building headless, accessible components (Accordion, Listbox, Combobox, Menu, Tabs, Toolbar, Tree, Grid) and styling ARIA attributes. Read [angular-aria.md](references/angular-aria.md)
+
+## Routing
+
+When implementing navigation in Angular, consult the following references:
+
+- **Define Routes**: URL paths, static vs dynamic segments, wildcards, and redirects. Read [define-routes.md](references/define-routes.md)
+- **Route Loading Strategies**: Eager vs lazy loading, and context-aware loading. Read [loading-strategies.md](references/loading-strategies.md)
+- **Show Routes with Outlets**: Using `<router-outlet>`, nested outlets, and named outlets. Read [show-routes-with-outlets.md](references/show-routes-with-outlets.md)
+- **Navigate to Routes**: Declarative navigation with `RouterLink` and programmatic navigation with `Router`. Read [navigate-to-routes.md](references/navigate-to-routes.md)
+- **Control Route Access with Guards**: Implementing `CanActivate`, `CanMatch`, and other guards for security. Read [route-guards.md](references/route-guards.md)
+- **Data Resolvers**: Pre-fetching data before route activation with `ResolveFn`. Read [data-resolvers.md](references/data-resolvers.md)
+- **Router Lifecycle and Events**: Chronological order of navigation events and debugging. Read [router-lifecycle.md](references/router-lifecycle.md)
+- **Rendering Strategies**: CSR, SSG (Prerendering), and SSR with hydration. Read [rendering-strategies.md](references/rendering-strategies.md)
+- **Route Transition Animations**: Enabling and customizing the View Transitions API. Read [route-animations.md](references/route-animations.md)
+
+If you require deeper documentation or more context, visit the [official Angular Routing guide](https://angular.dev/guide/routing).
+
+## Styling and Animations
+
+When implementing styling and animations in Angular, consult the following references:
+
+- **Using Tailwind CSS with Angular**: Integrating Tailwind CSS into Angular projects. Read [tailwind-css.md](references/tailwind-css.md)
+- **Angular Animations**: Using native CSS (recommended) or the legacy DSL for dynamic effects. Read [angular-animations.md](references/angular-animations.md)
+- **Styling components**: Best practices for component styles and encapsulation. Read [component-styling.md](references/component-styling.md)
+
+## Testing
+
+When writing or updating tests, consult the following references based on the task:
+
+- **Fundamentals**: Best practices for unit testing (Vitest), async patterns, and `TestBed`. Read [testing-fundamentals.md](references/testing-fundamentals.md)
+- **Component Harnesses**: Standard patterns for robust component interaction. Read [component-harnesses.md](references/component-harnesses.md)
+- **Router Testing**: Using `RouterTestingHarness` for reliable navigation tests. Read [router-testing.md](references/router-testing.md)
+- **End-to-End (E2E) Testing**: Best practices for E2E tests with Cypress. Read [e2e-testing.md](references/e2e-testing.md)
+
+## Tooling
+
+When working with Angular tooling, consult the following references:
+
+- **Angular CLI**: Creating applications, generating code (components, routes, services), serving, and building. Read [cli.md](references/cli.md)
+- **Code Modernization**: Automatically refactoring to modern standards using migrations. Read [migrations.md](references/migrations.md)
+- **Angular documentation helpers**: Use local helper scripts for version-aware best practices and official angular.dev documentation search. Read [docs-helpers.md](references/docs-helpers.md)
+- **Environment Configuration**: Strategies for build-time and runtime configuration. Read [environment-configuration.md](references/environment-configuration.md)

package/skills/angular-developer/UPSTREAM.md

@@ -0,0 +1,9 @@
+# Angular Developer upstream sync metadata
+
+Repository: https://github.com/angular/skills
+Synced at: 2026-06-25T20:51:50.643Z
+Requested ref: 28a90e30bba8cbc9d3a6aab56093e5b9b974bc9e
+Synced ref: ba11b0bc3e2382082b8961bff15798a19666bee9
+Fallback used: yes
+Upstream source: resolved ref ba11b0bc3e2382082b8961bff15798a19666bee9
+Local overlay source: overlays/angular-developer/

package/skills/angular-developer/data/best-practices.md

@@ -0,0 +1,56 @@
+You are an expert in TypeScript, Angular, and scalable web application development. You write functional, maintainable, performant, and accessible code following Angular and TypeScript best practices.
+
+## TypeScript Best Practices
+
+- Use strict type checking
+- Prefer type inference when the type is obvious
+- Avoid the `any` type; use `unknown` when type is uncertain
+
+## Angular Best Practices
+
+- Always use standalone components over NgModules
+- Must NOT set `standalone: true` inside Angular decorators. It's the default in Angular v20+.
+- Do NOT set `changeDetection: ChangeDetectionStrategy.OnPush` explicitly. `OnPush` is the default in Angular v22+.
+- Use signals for state management
+- Implement lazy loading for feature routes
+- Do NOT use the `@HostBinding` and `@HostListener` decorators. Put host bindings inside the `host` object of the `@Component` or `@Directive` decorator instead
+- Use `NgOptimizedImage` for all static images.
+  - `NgOptimizedImage` does not work for inline base64 images.
+
+## Accessibility Requirements
+
+- It MUST pass all AXE checks.
+- It MUST follow all WCAG AA minimums, including focus management, color contrast, and ARIA attributes.
+
+### Components
+
+- Keep components small and focused on a single responsibility
+- Use `input()` and `output()` functions instead of decorators
+- Use `computed()` for derived state
+- Prefer inline templates for small components
+- Prefer Signal Forms (`@angular/forms/signals`) for new forms. They are stable in Angular v22+ and provide signal-based state, type-safe field access, and schema-based validation
+- When not using Signal Forms, prefer Reactive forms instead of Template-driven ones
+- Do NOT use `ngClass`, use `class` bindings instead
+- Do NOT use `ngStyle`, use `style` bindings instead
+- When using external templates/styles, use paths relative to the component TS file.
+
+## State Management
+
+- Use signals for local component state
+- Use `computed()` for derived state
+- Keep state transformations pure and predictable
+- Do NOT use `mutate` on signals, use `update` or `set` instead
+
+## Templates
+
+- Keep templates simple and avoid complex logic
+- Use native control flow (`@if`, `@for`, `@switch`) instead of `*ngIf`, `*ngFor`, `*ngSwitch`
+- Use the async pipe to handle observables
+- Do not assume globals like (`new Date()`) are available.
+
+## Services
+
+- Design services around a single responsibility
+- Use the `providedIn: 'root'` option for singleton services
+- Prefer the `@Service` decorator over `@Injectable({providedIn: 'root'})` for new singleton services (Angular v22+)
+- Use the `inject()` function instead of constructor injection

package/skills/angular-developer/references/angular-animations.md

@@ -0,0 +1,160 @@
+# Angular Animations
+
+When animating elements in Angular, **first analyze the project's Angular version** in `package.json`.
+For modern applications (**Angular v20.2 and above**), prefer using native CSS with `animate.enter` and `animate.leave`. For older applications, you may need to use the deprecated `@angular/animations` package.
+
+## 1. Native CSS Animations (v20.2+ Recommended)
+
+Modern Angular provides `animate.enter` and `animate.leave` to animate elements as they enter or leave the DOM. They apply CSS classes at the appropriate times.
+
+### `animate.enter` and `animate.leave`
+
+Use these directly on elements to apply CSS classes during the enter or leave phase. Angular automatically removes the enter classes when the animation completes. For `animate.leave`, Angular waits for the animation to finish before removing the element from the DOM.
+
+`animate.enter` example:
+
+```html
+@if (isShown()) {
+<div class="enter-container" animate.enter="enter-animation">
+  <p>The box is entering.</p>
+</div>
+}
+```
+
+```css
+/* Ensure you have a starting style if using transitions instead of keyframes */
+.enter-container {
+  border: 1px solid #dddddd;
+  margin-top: 1em;
+  padding: 20px;
+  font-weight: bold;
+  font-size: 20px;
+}
+.enter-container p {
+  margin: 0;
+}
+.enter-animation {
+  animation: slide-fade 1s;
+}
+@keyframes slide-fade {
+  from {
+    opacity: 0;
+    transform: translateY(20px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+```
+
+_Note: `animate.leave` may be added to child elements being removed._
+
+### Event Bindings and Third-party Libraries
+
+You can bind to `(animate.enter)` and `(animate.leave)` to call functions or use JS libraries like GSAP.
+
+```html
+@if(show()) {
+<div (animate.leave)="onLeave($event)">...</div>
+}
+```
+
+```ts
+import { AnimationCallbackEvent } from '@angular/core';
+
+onLeave(event: AnimationCallbackEvent) {
+  // Custom animation logic here
+  // CRITICAL: You MUST call animationComplete() when done so Angular removes the element!
+  event.animationComplete();
+}
+```
+
+## 2. Advanced CSS Animations
+
+CSS offers robust tools for advanced animation sequences.
+
+### Animating State and Styles
+
+Toggle CSS classes on elements using property binding to trigger transitions.
+
+```html
+<div [class.open]="isOpen">...</div>
+```
+
+```css
+div {
+  transition: height 0.3s ease-out;
+  height: 100px;
+}
+div.open {
+  height: 200px;
+}
+```
+
+### Animating Auto Height
+
+You can use `css-grid` to animate to auto height.
+
+```css
+.container {
+  display: grid;
+  grid-template-rows: 0fr;
+  transition: grid-template-rows 0.3s;
+}
+.container.open {
+  grid-template-rows: 1fr;
+}
+.container > div {
+  overflow: hidden;
+}
+```
+
+### Staggering and Parallel Animations
+
+- **Staggering**: Use `animation-delay` or `transition-delay` with different values for items in a list.
+- **Parallel**: Apply multiple animations in the `animation` shorthand (e.g., `animation: rotate 3s, fade-in 2s;`).
+
+### Programmatic Control
+
+Retrieve animations directly using standard Web APIs:
+
+```ts
+const animations = element.getAnimations();
+animations.forEach((anim) => anim.pause());
+```
+
+## 3. Legacy Animations DSL (Deprecated)
+
+For older projects (pre v20.2 or where `@angular/animations` is already heavily used), you use the component metadata DSL.
+
+**Important:** Do not mix legacy animations and `animate.enter`/`leave` in the same component.
+
+### Setup
+
+```ts
+bootstrapApplication(App, {
+  providers: [provideAnimationsAsync()],
+});
+```
+
+### Defining Transitions
+
+```ts
+import {signal} from '@angular/core';
+import {trigger, state, style, animate, transition} from '@angular/animations';
+
+@Component({
+  animations: [
+    trigger('openClose', [
+      state('open', style({opacity: 1})),
+      state('closed', style({opacity: 0})),
+      transition('open <=> closed', [animate('0.5s')]),
+    ]),
+  ],
+  template: `<div [@openClose]="isOpen() ? 'open' : 'closed'">...</div>`,
+})
+export class OpenClose {
+  protected readonly isOpen = signal(true);
+}
+```