codeply-cli 0.3.1 → 0.4.1

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

@@ -1,83 +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 {
-  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)._
+# 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 {
+  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/hierarchical-injectors.md

@@ -1,43 +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 `@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.
+# 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 `@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

@@ -1,80 +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 {
-  value = 0;
-  disabled = false;
-  isActive = signal(false);
-  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>
-```
+# 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 {
+  value = 0;
+  disabled = false;
+  isActive = signal(false);
+  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

@@ -1,63 +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 (`@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 {Injectable, inject, EnvironmentInjector, runInInjectionContext} from '@angular/core';
-
-@Injectable({providedIn: 'root'})
-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;
-}
-```
+# 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 (`@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 {Injectable, inject, EnvironmentInjector, runInInjectionContext} from '@angular/core';
+
+@Injectable({providedIn: 'root'})
+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;
+}
+```