@heytherevibin/skillforge 0.2.1

package/skills/angular-developer/references/reactive-forms.md

@@ -0,0 +1,122 @@
+# Reactive Forms
+
+Reactive forms provide a model-driven approach to handling form inputs. They are built around observable streams and provide synchronous access to the data model, making them more scalable and testable than template-driven forms.
+
+## Core Classes
+
+Reactive forms are built using these fundamental classes from `@angular/forms`:
+
+- `FormControl`: Manages the value and validity of an individual input.
+- `FormGroup`: Manages a group of controls (an object-like structure).
+- `FormArray`: Manages a numerically indexed array of controls.
+- `FormBuilder`: A service that provides factory methods for creating control instances.
+
+## Setup
+
+Import `ReactiveFormsModule` into your component.
+
+```ts
+import {Component, inject} from '@angular/core';
+import {ReactiveFormsModule, FormGroup, FormControl, Validators, FormBuilder} from '@angular/forms';
+
+@Component({
+  selector: 'app-profile-editor',
+  imports: [ReactiveFormsModule],
+  templateUrl: './profile-editor.component.html',
+})
+export class ProfileEditor {
+  private fb = inject(FormBuilder);
+
+  // Using FormBuilder for concise definition
+  profileForm = this.fb.group({
+    firstName: ['', Validators.required],
+    lastName: [''],
+    address: this.fb.group({
+      street: [''],
+      city: [''],
+    }),
+    aliases: this.fb.array([this.fb.control('')]),
+  });
+
+  onSubmit() {
+    console.warn(this.profileForm.value);
+  }
+}
+```
+
+## Template Binding
+
+Use directives to bind the model to the view:
+
+- `[formGroup]`: Binds a `FormGroup` to a `<form>` or `<div>`.
+- `formControlName`: Binds a named control within a group to an input.
+- `formGroupName`: Binds a nested `FormGroup`.
+- `formArrayName`: Binds a nested `FormArray`.
+- `[formControl]`: Binds a standalone `FormControl`.
+
+```html
+<form [formGroup]="profileForm" (ngSubmit)="onSubmit()">
+  <input type="text" formControlName="firstName" />
+
+  <div formGroupName="address">
+    <input type="text" formControlName="street" />
+  </div>
+
+  <div formArrayName="aliases">
+    @for (alias of aliases.controls; track $index) {
+    <input type="text" [formControlName]="$index" />
+    }
+  </div>
+
+  <button type="submit" [disabled]="!profileForm.valid">Submit</button>
+</form>
+```
+
+## Accessing Controls
+
+Use getters for easy access to controls, especially for `FormArray`.
+
+```ts
+get aliases() {
+  return this.profileForm.get('aliases') as FormArray;
+}
+
+addAlias() {
+  this.aliases.push(this.fb.control(''));
+}
+```
+
+## Updating Values
+
+- `patchValue()`: Updates only the specified properties. Fails silently on structural mismatches.
+- `setValue()`: Replaces the entire model. Strictly enforces the form structure.
+
+```ts
+updateProfile() {
+  this.profileForm.patchValue({
+    firstName: 'Nancy',
+    address: { street: '123 Drew Street' }
+  });
+}
+```
+
+## Unified Change Events
+
+Modern Angular (v18+) provides a single `events` observable on all controls to track value, status, pristine, touched, reset, and submit events.
+
+```ts
+import {ValueChangeEvent, StatusChangeEvent} from '@angular/forms';
+
+this.profileForm.events.subscribe((event) => {
+  if (event instanceof ValueChangeEvent) {
+    console.log('New value:', event.value);
+  }
+});
+```
+
+## Manual State Management
+
+- `markAsTouched()` / `markAllAsTouched()`: Useful for showing validation errors on submit.
+- `markAsDirty()` / `markAsPristine()`: Tracks if the value has been modified.
+- `updateValueAndValidity()`: Manually triggers recalculation of value and status.
+- Options `{ emitEvent: false }` or `{ onlySelf: true }` can be passed to most methods to control propagation.

package/skills/angular-developer/references/rendering-strategies.md

@@ -0,0 +1,44 @@
+# Rendering Strategies
+
+Angular supports multiple rendering strategies to optimize for SEO, performance, and interactivity.
+
+## 1. Client-Side Rendering (CSR)
+
+**Default Strategy.** Content is rendered entirely in the browser.
+
+- **Use case**: Interactive dashboards, internal tools.
+- **Pros**: Simplest to configure, low server cost.
+- **Cons**: Poor SEO, slower initial content visibility (must wait for JS).
+
+## 2. Static Site Generation (SSG / Prerendering)
+
+Content is pre-rendered into static HTML files at **build time**.
+
+- **Use case**: Marketing pages, blogs, documentation.
+- **Pros**: Fastest initial load, excellent SEO, CDN-friendly.
+- **Cons**: Requires rebuild for content updates, not for user-specific data.
+
+## 3. Server-Side Rendering (SSR)
+
+Content is rendered on the server for the **initial request**. Subsequent navigations happen client-side (SPA style).
+
+- **Use case**: E-commerce product pages, news sites, personalized dynamic content.
+- **Pros**: Excellent SEO, fast initial content visibility.
+- **Cons**: Requires a server (Node.js), higher server cost/latency.
+
+## Hydration
+
+Hydration is the process of making server-rendered HTML interactive in the browser.
+
+- **Full Hydration**: The entire app becomes interactive at once.
+- **Incremental Hydration**: (Advanced) Parts become interactive as needed using `@defer` blocks.
+- **Event Replay**: Captures and replays user events that happened before hydration finished.
+
+## Decision Matrix
+
+| Requirement                     | Strategy             |
+| :------------------------------ | :------------------- |
+| **SEO + Static Content**        | SSG                  |
+| **SEO + Dynamic Content**       | SSR                  |
+| **No SEO + High Interactivity** | CSR                  |
+| **Mixed**                       | Hybrid (Route-based) |

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

@@ -0,0 +1,77 @@
+# Async Reactivity with `resource`
+
+> [!IMPORTANT]
+> The `resource` API is currently experimental in Angular.
+
+A `Resource` incorporates asynchronous data fetching into Angular's signal-based reactivity. It executes an async loader function whenever its dependencies change, exposing the status and result as synchronous signals.
+
+## Basic Usage
+
+The `resource` function accepts an options object with two main properties:
+
+1. `params`: A reactive computation (like `computed`). When signals read here change, the resource re-fetches.
+2. `loader`: An async function that fetches data based on the parameters.
+
+```ts
+import { Component, resource, signal, computed } from '@angular/core';
+
+@Component({...})
+export class UserProfile {
+  userId = signal('123');
+
+  userResource = resource({
+    // Reactively tracking userId
+    params: () => ({ id: this.userId() }),
+
+    // Executes whenever params change
+    loader: async ({ params, abortSignal }) => {
+      const response = await fetch(`/api/users/${params.id}`, { signal: abortSignal });
+      if (!response.ok) throw new Error('Network error');
+      return response.json();
+    }
+  });
+
+  // Use the resource value in computed signals
+  userName = computed(() => {
+    if (this.userResource.hasValue()) {
+      return this.userResource.value()?.name;
+    } else {
+      return 'Loading...';
+    }
+  });
+}
+```
+
+## Aborting Requests
+
+If the `params` signal changes while a previous loader is still running, the `Resource` will attempt to abort the outstanding request using the provided `abortSignal`. **Always pass `abortSignal` to your `fetch` calls.**
+
+## Reloading Data
+
+You can imperatively force the resource to re-run the loader without the params changing by calling `.reload()`.
+
+```ts
+this.userResource.reload();
+```
+
+## Resource Status Signals
+
+The `Resource` object provides several signals to read its current state:
+
+- `value()`: The resolved data, or `undefined`.
+- `hasValue()`: Type-guard boolean. `true` if a value exists.
+- `isLoading()`: Boolean indicating if the loader is currently running.
+- `error()`: The error thrown by the loader, or `undefined`.
+- `status()`: A string constant representing the exact state (`'idle'`, `'loading'`, `'resolved'`, `'error'`, `'reloading'`, `'local'`).
+
+## Local Mutation
+
+You can optimistically update the resource's value directly. This changes the status to `'local'`.
+
+```ts
+this.userResource.value.set({name: 'Optimistic Update'});
+```
+
+## Reactive Data Fetching with `httpResource`
+
+If you are using Angular's `HttpClient`, prefer using `httpResource`. It is a specialized wrapper that leverages the Angular HTTP stack (including interceptors) while providing the same signal-based resource API.

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

@@ -0,0 +1,56 @@
+# Route Transition Animations
+
+Angular Router supports the browser's **View Transitions API** for smooth visual transitions between routes.
+
+## Enabling View Transitions
+
+Add `withViewTransitions()` to your router configuration.
+
+```ts
+provideRouter(routes, withViewTransitions());
+```
+
+This is a **progressive enhancement**. In browsers that don't support the API, the router will still work but without the transition animation.
+
+## How it Works
+
+1. Browser takes a screenshot of the old state.
+2. Router updates the DOM (activates new component).
+3. Browser takes a screenshot of the new state.
+4. Browser animates between the two states.
+
+## Customizing with CSS
+
+Transitions are customized in **global CSS files** (not component-scoped CSS).
+
+Use the `::view-transition-old()` and `::view-transition-new()` pseudo-elements.
+
+```css
+/* Example: Cross-fade + Slide */
+::view-transition-old(root) {
+  animation: 90ms cubic-bezier(0.4, 0, 1, 1) both fade-out;
+}
+::view-transition-new(root) {
+  animation: 210ms cubic-bezier(0, 0, 0.2, 1) 90ms both fade-in;
+}
+```
+
+## Advanced Control
+
+Use `onViewTransitionCreated` to skip transitions or customize behavior based on the navigation context.
+
+```ts
+withViewTransitions({
+  onViewTransitionCreated: ({transition, from, to}) => {
+    // Skip animation for specific routes
+    if (to.url === '/no-animation') {
+      transition.skipTransition();
+    }
+  },
+});
+```
+
+## Best Practices
+
+- **Global Styles**: Always define transition animations in `styles.css` to avoid view encapsulation issues.
+- **View Transition Names**: Assign unique `view-transition-name` to elements that should transition smoothly across routes (e.g., a header image).

package/skills/angular-developer/references/route-guards.md

@@ -0,0 +1,52 @@
+# Route Guards
+
+Route guards control whether a user can navigate to or leave a route.
+
+## Types of Guards
+
+- **`CanActivate`**: Can the user access this route? (e.g., Auth check).
+- **`CanActivateChild`**: Can the user access children of this route?
+- **`CanDeactivate`**: Can the user leave this route? (e.g., Unsaved changes).
+- **`CanMatch`**: Should this route even be considered for matching? (e.g., Feature flags). If it returns `false`, the router continues checking other routes.
+
+## Creating a Guard
+
+Guards are typically functional since Angular 15.
+
+```ts
+export const authGuard: CanActivateFn = (route, state) => {
+  const authService = inject(AuthService);
+  const router = inject(Router);
+
+  if (authService.isLoggedIn()) {
+    return true;
+  }
+
+  // Redirect to login
+  return router.parseUrl('/login');
+};
+```
+
+## Applying Guards
+
+Add them to the route configuration as an array. They execute in order.
+
+```ts
+{
+  path: 'admin',
+  component: Admin,
+  canActivate: [authGuard],
+  canActivateChild: [adminChildGuard],
+  canDeactivate: [unsavedChangesGuard]
+}
+```
+
+## Return Values
+
+- `boolean`: `true` to allow, `false` to block.
+- `UrlTree` or `RedirectCommand`: Redirect to a different route.
+- `Observable` or `Promise`: Resolves to the above types.
+
+## Security Note
+
+**Client-side guards are NOT a substitute for server-side security.** Always verify permissions on the server.

package/skills/angular-developer/references/router-lifecycle.md

@@ -0,0 +1,45 @@
+# Router Lifecycle and Events
+
+Angular Router emits events through the `Router.events` observable, allowing you to track the navigation lifecycle from start to finish.
+
+## Common Router Events (Chronological)
+
+1. **`NavigationStart`**: Navigation begins.
+2. **`RoutesRecognized`**: Router matches the URL to a route.
+3. **`GuardsCheckStart` / `End`**: Evaluation of `canActivate`, `canMatch`, etc.
+4. **`ResolveStart` / `End`**: Data resolution phase (fetching data via resolvers).
+5. **`NavigationEnd`**: Navigation completed successfully.
+6. **`NavigationCancel`**: Navigation canceled (e.g., guard returned `false`).
+7. **`NavigationError`**: Navigation failed (e.g., error in resolver).
+
+## Subscribing to Events
+
+Inject the `Router` and filter the `events` observable.
+
+```ts
+import {Router, NavigationStart, NavigationEnd} from '@angular/router';
+
+export class MyService {
+  private router = inject(Router);
+
+  constructor() {
+    this.router.events.pipe(filter((e) => e instanceof NavigationEnd)).subscribe((event) => {
+      console.log('Navigated to:', event.url);
+    });
+  }
+}
+```
+
+## Debugging
+
+Enable detailed console logging of all routing events during application bootstrap.
+
+```ts
+provideRouter(routes, withDebugTracing());
+```
+
+## Common Use Cases
+
+- **Loading Indicators**: Show a spinner when `NavigationStart` fires and hide it on `NavigationEnd`/`Cancel`/`Error`.
+- **Analytics**: Track page views by listening for `NavigationEnd`.
+- **Scroll Management**: Respond to `Scroll` events for custom scroll behavior.

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

@@ -0,0 +1,87 @@
+# Testing with the RouterTestingHarness
+
+When testing components that involve routing, it is crucial **not to mock the Router or related services**. Instead, use the `RouterTestingHarness`, which provides a robust and reliable way to test routing logic in an environment that closely mirrors a real application.
+
+Using the harness ensures you are testing the actual router configuration, guards, and resolvers, leading to more meaningful tests.
+
+## Setting Up for Router Testing
+
+The `RouterTestingHarness` is the primary tool for testing routing scenarios. You also need to provide your test routes using the `provideRouter` function in your `TestBed` configuration.
+
+### Example Setup
+
+```ts
+import {TestBed} from '@angular/core/testing';
+import {provideRouter} from '@angular/router';
+import {RouterTestingHarness} from '@angular/router/testing';
+import {Dashboard} from './dashboard.component';
+import {HeroDetail} from './hero-detail.component';
+
+describe('Dashboard Component Routing', () => {
+  let harness: RouterTestingHarness;
+
+  beforeEach(async () => {
+    // 1. Configure TestBed with test routes
+    await TestBed.configureTestingModule({
+      providers: [
+        // Use provideRouter with your test-specific routes
+        provideRouter([
+          {path: '', component: Dashboard},
+          {path: 'heroes/:id', component: HeroDetail},
+        ]),
+      ],
+    }).compileComponents();
+
+    // 2. Create the RouterTestingHarness
+    harness = await RouterTestingHarness.create();
+  });
+});
+```
+
+### Key Concepts
+
+1. **`provideRouter([...])`**: Provide a test-specific routing configuration. This should include the routes necessary for the component-under-test to function correctly.
+2. **`RouterTestingHarness.create()`**: Asynchronously creates and initializes the harness and performs an initial navigation to the root URL (`/`).
+
+## Writing Router Tests
+
+Once the harness is created, you can use it to drive navigation and make assertions on the state of the router and the activated components.
+
+### Example: Testing Navigation
+
+```ts
+it('should navigate to a hero detail when a hero is selected', async () => {
+  // 1. Navigate to the initial component and get its instance
+  const dashboard = await harness.navigateByUrl('/', Dashboard);
+
+  // Suppose the dashboard has a method to select a hero
+  const heroToSelect = {id: 42, name: 'Test Hero'};
+  dashboard.selectHero(heroToSelect);
+
+  // Wait for stability after the action that triggers navigation
+  await harness.fixture.whenStable();
+
+  // 2. Assert on the URL
+  expect(harness.router.url).toEqual('/heroes/42');
+
+  // 3. Get the activated component after navigation
+  const heroDetail = await harness.getHarness(HeroDetail);
+
+  // 4. Assert on the state of the new component
+  expect(await heroDetail.componentInstance.hero.name).toBe('Test Hero');
+});
+
+it('should get the activated component directly', async () => {
+  // Navigate and get the component instance in one step
+  const dashboardInstance = await harness.navigateByUrl('/', Dashboard);
+
+  expect(dashboardInstance).toBeInstanceOf(Dashboard);
+});
+```
+
+### Best Practices
+
+- **Navigate with the Harness:** Always use `harness.navigateByUrl()` to simulate navigation. This method returns a promise that resolves with the instance of the activated component.
+- **Access the Router State:** Use `harness.router` to access the live router instance and assert on its state (e.g., `harness.router.url`).
+- **Get Activated Components:** Use `harness.getHarness(ComponentType)` to get an instance of a component harness for the currently activated routed component, or `harness.routeDebugElement` to get the `DebugElement`.
+- **Wait for Stability:** After performing an action that causes navigation, always `await harness.fixture.whenStable()` to ensure the routing is complete before making assertions.

package/skills/angular-developer/references/show-routes-with-outlets.md

@@ -0,0 +1,68 @@
+# Show Routes with Outlets
+
+The `RouterOutlet` directive is a placeholder where Angular renders the component for the current URL.
+
+## Basic Usage
+
+Include `<router-outlet />` in your template. Angular inserts the routed component as a sibling immediately following the outlet.
+
+```html
+<app-header /> <router-outlet />
+<!-- Route content appears here -->
+<app-footer />
+```
+
+## Nested Outlets
+
+Child routes require their own `<router-outlet />` within the parent component's template.
+
+```ts
+// Parent component template
+<h1>Settings</h1>
+<router-outlet /> <!-- Child components like Profile or Security render here -->
+```
+
+## Named Outlets (Secondary Routes)
+
+Pages can have multiple outlets. Assign a `name` to an outlet to target it specifically. The default name is `'primary'`.
+
+```html
+<router-outlet />
+<!-- Primary -->
+<router-outlet name="sidebar" />
+<!-- Secondary -->
+```
+
+Define the `outlet` in the route config:
+
+```ts
+{
+  path: 'chat',
+  component: Chat,
+  outlet: 'sidebar'
+}
+```
+
+## Outlet Lifecycle Events
+
+`RouterOutlet` emits events when components are changed:
+
+- `activate`: New component instantiated.
+- `deactivate`: Component destroyed.
+- `attach` / `detach`: Used with `RouteReuseStrategy`.
+
+```html
+<router-outlet (activate)="onActivate($event)" />
+```
+
+## Passing Data via `routerOutletData`
+
+You can pass contextual data to the routed component using the `routerOutletData` input. The component accesses this via the `ROUTER_OUTLET_DATA` injection token as a signal.
+
+```ts
+// In Parent
+<router-outlet [routerOutletData]="{ theme: 'dark' }" />
+
+// In Routed Component
+outletData = inject(ROUTER_OUTLET_DATA) as Signal<{ theme: string }>;
+```