@aliaksei-raketski/pi-angular-developer 0.1.0

package/skills/angular-developer/references/docs-helpers.md

@@ -0,0 +1,36 @@
+# Angular Documentation Helpers
+
+Use the local helper scripts bundled with this skill for:
+
+- version-aware Angular best practices lookup
+- official angular.dev documentation search
+
+## Best practices
+
+Before writing or modifying Angular code in an existing workspace, run one of the following commands:
+
+```bash
+# From skills/angular-developer/
+node scripts/get-best-practices.mjs /absolute/path/to/workspace
+
+# From any directory
+node /absolute/path/to/skills/angular-developer/scripts/get-best-practices.mjs /absolute/path/to/workspace
+```
+
+If you do not pass a workspace path, the script searches upward from the current directory for `angular.json`.
+
+## Angular documentation search
+
+Use the local search helper:
+
+```bash
+node scripts/search-documentation.mjs "signals resource" --version 22 --limit 5
+node scripts/search-documentation.mjs "signal forms validation" --version 22 --include-top-content
+```
+
+## Usage notes
+
+- Run the scripts from `skills/angular-developer/`, or by using absolute script paths.
+- If the project Angular version is known, pass the major version to `search-documentation.mjs` with `--version`.
+- If deeper or current docs are needed, add `--include-top-content` to retrieve concise top-page context.
+- Prefer vendored references under `references/` first, then use `search-documentation.mjs` for fresher/cross-topic lookup.

package/skills/angular-developer/references/e2e-testing.md

@@ -0,0 +1,66 @@
+# End-to-End (E2E) Testing
+
+This project uses [Cypress](https://www.cypress.io/) for end-to-end (E2E) testing, which simulates real user interactions in a browser. The E2E tests are located primarily within the `devtools/` package.
+
+## Running E2E Tests
+
+The primary way to run E2E tests is through the `pnpm` script defined in the root `package.json`.
+
+1.  **Build DevTools:** The E2E tests run against a built version of the devtools extension. You must build it first:
+
+    ```shell
+    pnpm -F ng-devtools build:dev
+    ```
+
+2.  **Run Cypress:** Use the `cy:open` or `cy:run` script:
+    - To open the interactive Cypress Test Runner:
+      ```shell
+      pnpm -F ng-devtools cy:open
+      ```
+    - To run the tests headlessly in the terminal (ideal for CI):
+      ```shell
+      pnpm -F ng-devtools cy:run
+      ```
+
+## Test Structure
+
+- **Configuration:** The main Cypress configuration is located at `devtools/cypress.json`.
+- **Specs:** Test files (specs) are located in `devtools/cypress/integration/`.
+- **Custom Commands:** Reusable custom commands and actions are defined in `devtools/cypress/support/`.
+
+### Example E2E Test Snippet
+
+A typical test might look like this:
+
+```typescript
+// in devtools/cypress/integration/profiler.spec.ts
+
+describe('Profiler', () => {
+  beforeEach(() => {
+    cy.visit('/?e2e-app');
+    cy.wait(1000);
+    cy.get('ng-devtools-tabs').find('a').contains('Profiler').click();
+  });
+
+  it('should record and display profiling data', () => {
+    // Find the record button and click it
+    cy.get('button[aria-label="start-recording-button"]').click();
+
+    // Interact with the test application to generate profiling data
+    cy.get('body').find('#cards button').first().click();
+    cy.wait(500);
+
+    // Stop recording
+    cy.get('button[aria-label="stop-recording-button"]').click();
+
+    // Assert that the flame graph is now visible
+    cy.get('ng-devtools-recording-timeline').find('canvas').should('be.visible');
+  });
+});
+```
+
+### Best Practices
+
+- **Use `data-` attributes:** Whenever possible, use `data-cy` or similar attributes for selecting elements to make tests more resilient to CSS or structural changes.
+- **Custom Commands:** Encapsulate common sequences of actions into custom commands in the `support` directory to keep tests clean and readable.
+- **Wait for Application State:** Use `cy.wait()` for arbitrary waits sparingly. Prefer to wait for specific UI elements to appear or for network requests to complete to avoid flaky tests.

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

@@ -0,0 +1,83 @@
+# Side Effects with `effect` and `afterRenderEffect`
+
+In Angular, an **effect** is an operation that runs whenever one or more signal values it tracks change.
+
+## When to use `effect`
+
+Effects are intended for syncing signal state to imperative, non-signal APIs.
+
+**Valid Use Cases:**
+
+- Logging analytics.
+- Syncing state to `localStorage` or `sessionStorage`.
+- Performing custom rendering to a `<canvas>` or 3rd-party charting library.
+
+**CRITICAL RULE: DO NOT use effects to propagate state.**
+If you find yourself using `.set()` or `.update()` on a signal _inside_ an effect to keep two signals in sync, you are making a mistake. This causes `ExpressionChangedAfterItHasBeenChecked` errors and infinite loops. **Always use `computed()` or `linkedSignal()` for state derivation.**
+
+## Basic Usage
+
+Effects execute asynchronously during the change detection process. They always run at least once.
+
+```ts
+import { Component, signal, effect } from '@angular/core';
+
+@Component({...})
+export class Example {
+  protected readonly count = signal(0);
+
+  constructor() {
+    // Effect must be created in an injection context (e.g., a constructor)
+    effect((onCleanup) => {
+      console.log(`Count changed to ${this.count()}`);
+
+      const timer = setTimeout(() => console.log('Timer finished'), 1000);
+
+      // Cleanup function runs before the next execution, or when destroyed
+      onCleanup(() => clearTimeout(timer));
+    });
+  }
+}
+```
+
+## DOM Manipulation with `afterRenderEffect`
+
+Standard `effect` runs _before_ Angular updates the DOM. If you need to manually inspect or modify the DOM based on a signal change (e.g., integrating a 3rd party UI library), use `afterRenderEffect`.
+
+`afterRenderEffect` runs after Angular has finished rendering the DOM.
+
+### Render Phases
+
+To prevent reflows (forced layout thrashing), `afterRenderEffect` forces you to divide your DOM reads and writes into specific phases.
+
+```ts
+import { Component, afterRenderEffect, viewChild, ElementRef } from '@angular/core';
+
+@Component({...})
+export class Chart {
+  canvas = viewChild.required<ElementRef>('canvas');
+
+  constructor() {
+    afterRenderEffect({
+      // 1. Read from the DOM
+      earlyRead: () => {
+        return this.canvas().nativeElement.getBoundingClientRect().width;
+      },
+      // 2. Write to the DOM (receives the result of the previous phase)
+      write: (width) => {
+        // NEVER read from the DOM in the write phase.
+        setupChart(this.canvas().nativeElement, width);
+      }
+    });
+  }
+}
+```
+
+**Available Phases (executed in this order):**
+
+1. `earlyRead`
+2. `write` (Never read here)
+3. `mixedReadWrite` (Avoid if possible)
+4. `read` (Never write here)
+
+_Note: `afterRenderEffect` only runs on the client, never during Server-Side Rendering (SSR)._

package/skills/angular-developer/references/environment-configuration.md

@@ -0,0 +1,132 @@
+# Environment configuration
+
+## Configuration strategies
+
+Angular supports two main configuration strategies:
+
+- **Build-time configuration** using environment files
+- **Runtime configuration** by loading values at application startup
+
+Choose the approach based on your deployment requirements.
+
+---
+
+## Build-time configuration
+
+Environment files define configuration values that are replaced at build time.
+
+> **Security note:** Environment files are bundled into the client-side application.
+> They are visible to anyone who can load the page.
+> Never store sensitive information like API keys, secrets, or credentials in environment files.
+> These values can be easily accessed by users.
+
+Generate environment files using the CLI:
+
+```bash
+ng generate environments
+```
+
+This creates environment-specific files such as:
+
+```ts
+// environment.ts
+export const environment = {
+  apiUrl: 'https://api.example.com',
+};
+```
+
+```ts
+// environment.development.ts
+export const environment = {
+  apiUrl: 'http://localhost:3000',
+};
+```
+
+Import the environment where needed:
+
+```ts
+import {environment} from '../environments/environment';
+
+const apiUrl = environment.apiUrl;
+```
+
+The Angular CLI replaces the appropriate file based on the build configuration.
+
+If you need a development-mode check, use `isDevMode()` from `@angular/core` instead of relying on a manually maintained `production` flag.
+
+> Changes to environment files require rebuilding the application.
+
+---
+
+## Runtime configuration (advanced)
+
+In some scenarios, applications need to load configuration at runtime instead of build time.
+
+This allows the same build artifact to be deployed across multiple environments without rebuilding.
+
+A common approach is to load a JSON configuration file from the `assets` folder during application
+initialization.
+
+### Example
+
+```json
+// src/assets/config.json
+{
+  "apiUrl": "https://api.example.com"
+}
+```
+
+Load the configuration before the application starts:
+
+```ts
+import {Service, inject} from '@angular/core';
+import {HttpClient} from '@angular/common/http';
+
+@Service()
+export class AppConfigService {
+  private config!: {apiUrl: string};
+
+  private readonly http = inject(HttpClient);
+
+  loadConfig() {
+    return this.http.get<AppConfig>('/assets/config.json').pipe(
+      tap((data) => {
+        this.config = data;
+      }),
+    );
+  }
+
+  get apiUrl(): string {
+    return this.config.apiUrl;
+  }
+}
+```
+
+Register the loader during application bootstrap:
+
+```ts
+import {provideAppInitializer, inject} from '@angular/core';
+
+provideAppInitializer(() => {
+  const config = inject(AppConfigService);
+  return config.loadConfig();
+});
+```
+
+This ensures configuration is available before the application renders.
+
+> Runtime configuration is an advanced pattern and is not required for most applications.
+
+---
+
+## Choosing a strategy
+
+| Criteria               | Build-time | Runtime      |
+| ---------------------- | ---------- | ------------ |
+| Change without rebuild | No         | Yes          |
+| Startup performance    | Faster     | Slight delay |
+| Complexity             | Low        | Moderate     |
+| Deployment flexibility | Limited    | High         |
+
+Use build-time configuration for most applications, and runtime configuration when you need to
+deploy the same build across multiple environments.

package/skills/angular-developer/references/hierarchical-injectors.md

@@ -0,0 +1,43 @@
+# Hierarchical Injectors
+
+Angular's dependency injection system is hierarchical, meaning services can be scoped to different levels of the application.
+
+## Types of Injector Hierarchies
+
+1. **`EnvironmentInjector` Hierarchy**: Configured via `@Service()`, `@Injectable({ providedIn: 'root' })` or `ApplicationConfig.providers` during bootstrap. These are global singletons.
+2. **`ElementInjector` Hierarchy**: Created implicitly at each DOM element. Configured via the `providers` or `viewProviders` array in `@Component()` or `@Directive()`.
+
+## Resolution Rules
+
+When a dependency is requested, Angular resolves it in two phases:
+
+1. It searches up the **`ElementInjector`** tree, starting from the requesting component/directive up to the root element.
+2. If not found, it searches the **`EnvironmentInjector`** tree, starting from the closest environment injector up to the root.
+3. If still not found, it throws an error (unless marked optional).
+
+## Resolution Modifiers
+
+You can alter how Angular searches for a dependency using the options object in `inject()`:
+
+- **`optional`**: If the dependency isn't found, return `null` instead of throwing an error.
+- **`self`**: Only check the current `ElementInjector`. Do not look up the parent tree.
+- **`skipSelf`**: Start searching in the parent `ElementInjector`, skipping the current element.
+- **`host`**: Stop searching when reaching the host component's view boundary.
+
+```ts
+@Component({...})
+export class Example {
+  // Returns null if not found instead of crashing
+  optionalService = inject(MyService, { optional: true });
+
+  // Skips this component's providers, looks at parent
+  parentService = inject(ParentService, { skipSelf: true });
+}
+```
+
+## `providers` vs `viewProviders`
+
+When providing a service at the component level:
+
+- **`providers`**: The service is available to the component, its view (template), and any **projected content** (`<ng-content>`).
+- **`viewProviders`**: The service is available to the component and its view, but **NOT** to projected content. Use this to isolate services from content passed in by consumers.

package/skills/angular-developer/references/host-elements.md

@@ -0,0 +1,80 @@
+# Component Host Elements
+
+The **host element** is the DOM element that matches a component's selector. The component's template renders inside this element.
+
+## Binding to the Host Element
+
+Use the `host` property in the `@Component` decorator to bind properties, attributes, styles, and events to the host element. This is the **preferred approach** over legacy decorators.
+
+```ts
+@Component({
+  selector: 'custom-slider',
+  host: {
+    'role': 'slider', // Static attribute
+    '[attr.aria-valuenow]': 'value', // Attribute binding
+    '[class.active]': 'isActive()', // Class binding
+    '[style.color]': 'color()', // Style binding
+    '[tabIndex]': 'disabled ? -1 : 0', // Property binding
+    '(keydown)': 'onKeyDown($event)', // Event binding
+  },
+})
+export class CustomSlider {
+  protected readonly value = 0;
+  protected readonly disabled = false;
+  protected readonly isActive = signal(false);
+  protected readonly color = signal('blue');
+
+  onKeyDown(event: KeyboardEvent) {
+    /* ... */
+  }
+}
+```
+
+## Legacy Decorators
+
+`@HostBinding` and `@HostListener` are supported for backwards compatibility but should be avoided in new code.
+
+```ts
+export class CustomSlider {
+  @HostBinding('tabIndex')
+  get tabIndex() {
+    return this.disabled ? -1 : 0;
+  }
+
+  @HostListener('keydown', ['$event'])
+  onKeyDown(event: KeyboardEvent) {
+    /* ... */
+  }
+}
+```
+
+## Binding Collisions
+
+If both the component (host binding) and the consumer (template binding) bind to the same property:
+
+1. **Static vs Static**: The instance (consumer) binding wins.
+2. **Static vs Dynamic**: The dynamic binding wins.
+3. **Dynamic vs Dynamic**: The component's host binding wins.
+
+## Injecting Host Attributes
+
+Use `HostAttributeToken` with the `inject` function to read static attributes from the host element at construction time.
+
+```ts
+import {Component, HostAttributeToken, inject} from '@angular/core';
+
+@Component({
+  selector: 'app-btn',
+  template: `<ng-content />`,
+})
+export class AppButton {
+  // Throws error if 'type' is missing unless injected with { optional: true }
+  type = inject(new HostAttributeToken('type'));
+}
+```
+
+Usage:
+
+```html
+<app-btn type="primary">Click Me</app-btn>
+```

package/skills/angular-developer/references/injection-context.md

@@ -0,0 +1,63 @@
+# Injection Context
+
+The `inject()` function can only be used when code is executing within an **injection context**.
+
+## Where is an Injection Context Available?
+
+An injection context is automatically available in:
+
+1. **Field initializers** of classes instantiated by DI (`@Service`, `@Injectable`, `@Component`, `@Directive`, `@Pipe`).
+2. **Constructors** of classes instantiated by DI.
+3. **Factory functions** specified in `useFactory` or `InjectionToken` configurations.
+4. **Functional APIs** executed by Angular (e.g., functional route guards, resolvers, interceptors).
+
+```ts
+@Component({...})
+export class Example {
+  // ✅ Valid: Field initializer
+  private router = inject(Router);
+
+  constructor() {
+    // ✅ Valid: Constructor
+    const http = inject(HttpClient);
+  }
+
+  onClick() {
+    // ❌ Invalid: Not an injection context
+    // const auth = inject(AuthService);
+  }
+}
+```
+
+## `runInInjectionContext`
+
+If you need to run a function within an injection context (often needed for dynamic component creation or testing), use `runInInjectionContext`. This requires access to an existing injector (like `EnvironmentInjector` or `Injector`).
+
+```ts
+import {inject, EnvironmentInjector, runInInjectionContext, Service} from '@angular/core';
+
+@Service()
+export class MyService {
+  private injector = inject(EnvironmentInjector);
+
+  doSomethingDynamic() {
+    runInInjectionContext(this.injector, () => {
+      // ✅ Now valid to use inject() here
+      const router = inject(Router);
+    });
+  }
+}
+```
+
+## `assertInInjectionContext`
+
+Use `assertInInjectionContext` in utility functions to guarantee they are called from a valid context. It throws a clear error if not.
+
+```ts
+import {assertInInjectionContext, inject, ElementRef} from '@angular/core';
+
+export function injectNativeElement<T extends Element>(): T {
+  assertInInjectionContext(injectNativeElement);
+  return inject(ElementRef).nativeElement;
+}
+```

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

@@ -0,0 +1,101 @@
+# Inputs
+
+Inputs allow data to flow from a parent component to a child component. Angular recommends using the signal-based `input` API for modern applications.
+
+## Signal-based Inputs
+
+Declare inputs using the `input()` function. This returns an `InputSignal`.
+
+```ts
+import {Component, input, computed} from '@angular/core';
+
+@Component({
+  selector: 'app-user',
+  template: `<p>{{ label() }} ({{ age() }})</p>`,
+})
+export class User {
+  // Optional input with default value
+  readonly name = input('Guest');
+
+  // Required input
+  readonly age = input.required<number>();
+
+  // Inputs are reactive signals
+  protected readonly label = computed(() => `Name: ${this.name()}`);
+}
+```
+
+### Usage in Template
+
+```html
+<app-user [name]="userName" [age]="25" />
+```
+
+## Configuration Options
+
+The `input` function accepts a config object:
+
+- **Alias**: Change the property name used in templates.
+- **Transform**: Modify the value before it reaches the component.
+
+```ts
+import { input, booleanAttribute } from '@angular/core';
+
+@Component({...})
+export class CustomButton {
+  // Alias example
+  readonly label = input('', { alias: 'btnLabel' });
+
+  // Transform example using built-in helper
+  readonly disabled = input(false, { transform: booleanAttribute });
+}
+```
+
+## Model Inputs (Two-Way Binding)
+
+Use `model()` to create an input that supports two-way data binding.
+
+```ts
+@Component({
+  selector: 'custom-counter',
+  template: `<button (click)="increment()">+</button>`,
+})
+export class CustomCounter {
+  readonly value = model(0);
+
+  increment() {
+    this.value.update((v) => v + 1);
+  }
+}
+```
+
+### Usage
+
+```html
+<!-- Two-way binding with a signal -->
+<custom-counter [(value)]="mySignal" />
+
+<!-- Two-way binding with a plain property -->
+<custom-counter [(value)]="myProperty" />
+```
+
+## Decorator-based Inputs (@Input)
+
+The legacy API remains supported but is not recommended for new code.
+
+```ts
+import { Component, Input } from '@angular/core';
+
+@Component({...})
+export class Legacy {
+  @Input({ required: true }) value = 0;
+  @Input({ transform: trimString }) label = '';
+}
+```
+
+## Best Practices
+
+- **Prefer Signals**: Use `input()` instead of `@Input()` for better reactivity and type safety.
+- **Required Inputs**: Use `input.required()` for mandatory data to get build-time errors.
+- **Pure Transforms**: Ensure input transform functions are pure and statically analyzable.
+- **Avoid Collisions**: Do not use input names that collide with standard DOM properties (e.g., `id`, `title`).

package/skills/angular-developer/references/linked-signal.md

@@ -0,0 +1,59 @@
+# Dependent State with `linkedSignal`
+
+The `linkedSignal` function lets you create writable state that is intrinsically linked to some other state. It is perfect for state that needs a default value derived from an input or another signal, but can still be independently modified by the user.
+
+If the source state changes, the `linkedSignal` resets to a new computed value.
+
+## Basic Usage
+
+When you only need to recompute based on a source, pass a computation function. `linkedSignal` works like `computed`, but the resulting signal is writable (you can call `.set()` or `.update()` on it).
+
+```ts
+import { Component, signal, linkedSignal } from '@angular/core';
+
+@Component({...})
+export class ShippingMethodPicker {
+  protected readonly shippingOptions = signal(['Ground', 'Air', 'Sea']);
+
+  // Defaults to the first option.
+  // If shippingOptions changes, selectedOption resets to the new first option.
+  protected readonly selectedOption = linkedSignal(() => this.shippingOptions()[0]);
+
+  changeShipping(index: number) {
+    // We can still manually update this signal!
+    this.selectedOption.set(this.shippingOptions()[index]);
+  }
+}
+```
+
+## Advanced Usage: Accounting for Previous State
+
+Sometimes, when the source state changes, you want to preserve the user's manual selection if it is still valid. To do this, use the object syntax providing `source` and `computation`.
+
+The `computation` function receives the new value of the source, and a `previous` object containing the previous source value and the previous `linkedSignal` value.
+
+```ts
+interface ShippingMethod { id: number; name: string; }
+
+@Component({...})
+export class ShippingMethodPicker {
+  protected readonly shippingOptions = signal<ShippingMethod[]>([
+    {id: 0, name: 'Ground'}, {id: 1, name: 'Air'}, {id: 2, name: 'Sea'}
+  ]);
+
+  protected readonly selectedOption = linkedSignal<ShippingMethod[], ShippingMethod>({
+    source: this.shippingOptions,
+    computation: (newOptions, previous) => {
+      // If the newly loaded options still contain the user's previously
+      // selected option, keep it selected. Otherwise, reset to the first option.
+      return newOptions.find(opt => opt.id === previous?.value.id) ?? newOptions[0];
+    }
+  });
+}
+```
+
+### When to use `linkedSignal` vs `computed` vs `effect`
+
+- Use `computed`: When state is **strictly** derived from other state and should never be manually updated.
+- Use `linkedSignal`: When state is derived from other state, but the user **must** be able to override or manually update it.
+- **Never** use `effect` to sync one piece of state to another. That is an anti-pattern. Use `computed` or `linkedSignal` instead.