angular-agents-skills 1.0.0

package/skills/components/dynamic-components/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: dynamic-components
+description: Create and mount Angular components dynamically at runtime using createComponent() and ApplicationRef, and tear them down safely (used for modals, popovers, toasts).
+---
+
+# Dynamic Component Creation
+
+This skill covers programmatically creating and mounting Angular components outside the normal template tree — the foundation of overlay services (modal, popover, toast, tooltip).
+
+## When to use
+- Building a service that opens a modal/dialog/toast/popover imperatively (`.open(SomeComponent, config)`).
+- Any UI that must be rendered detached from its "logical" parent component in the DOM (e.g. attached to `document.body` to escape `overflow: hidden`/z-index contexts).
+
+## Creating a component
+```typescript
+@Injectable({ providedIn: 'root' })
+export class ModalService {
+  private readonly applicationRef = inject(ApplicationRef);
+  private readonly injector = inject(Injector);
+
+  create(component: Type<unknown>, config?: unknown): DialogRef {
+    const dialogRef = new DialogRef(/* ... */);
+
+    const componentRef = createComponent(component, {
+      environmentInjector: this.applicationRef.injector,
+      elementInjector: Injector.create({
+        providers: [{ provide: DIALOG_REF, useValue: dialogRef }],
+        parent: this.injector,
+      }),
+    });
+
+    // Attach the host view to change detection
+    this.applicationRef.attachView(componentRef.hostView);
+
+    // Mount into the DOM (typically document.body for overlays)
+    document.body.appendChild(componentRef.location.nativeElement);
+
+    dialogRef.componentRef = componentRef;
+    return dialogRef;
+  }
+}
+```
+
+## Key pieces
+- `createComponent(Component, options)` — instantiates the component and its view without a host template.
+- `ApplicationRef.attachView(hostView)` — registers the view with Angular's change detection so signal/input changes are picked up. **Required**, otherwise the component silently never updates.
+- `elementInjector` (via `Injector.create`) — the mechanism for providing per-instance tokens (like a `DIALOG_REF` the created component can `inject()` optionally — see `injection-tokens-pattern`).
+- `componentRef.location.nativeElement` — the actual DOM element to insert manually into the document.
+
+## Passing data in and getting data out
+- **In**: provide via `elementInjector`, or set `componentRef.setInput('propName', value)` for signal `input()`s.
+- **Out**: expose a `Subject`/`Observable` (`afterClosed$`) on the returned ref object; the created component calls `dialogRef.close(result)` which the ref translates into emitting that subject.
+
+## Teardown
+```typescript
+destroy(componentRef: ComponentRef<unknown>): void {
+  this.applicationRef.detachView(componentRef.hostView);
+  componentRef.destroy();
+  componentRef.location.nativeElement.remove();
+}
+```
+Always: detach the view **before** destroying, and remove the DOM node explicitly (Angular does not do this automatically for manually-appended elements).
+
+## Coordinating with route changes
+Overlay services in this codebase inject `Router` and subscribe to navigation events to auto-close the dialog if the user navigates away, preventing orphaned overlay elements:
+```typescript
+private readonly router = inject(Router);
+this.router.events.pipe(filter(e => e instanceof NavigationStart)).subscribe(() => this.close());
+```
+
+## Pitfalls
+- Forgetting `attachView`/`detachView` causes either “ghost” components that never update, or memory leaks after destroy.
+- Not removing the DOM node on destroy leaves stale, invisible overlay elements accumulating in `document.body` (a common source of flaky tests — see the `vitest-angular-components` skill's overlay cleanup notes).
+- Always destroy in a `finally`/guaranteed path (e.g. also on component `DestroyRef.onDestroy`) so a thrown error during open doesn't leak the component.

package/skills/components/modern-host-bindings/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: modern-host-bindings
+description: Bind dynamic classes, attributes, and ARIA properties via the @Component "host" object instead of @HostBinding/@HostListener decorators.
+---
+
+# Modern Host Bindings
+
+This skill covers declaring dynamic host classes/attributes/ARIA declaratively in the `@Component` decorator's `host` object, avoiding `@HostBinding`/`@HostListener`.
+
+## When to use
+- A component's root element needs classes that depend on signal state (size, type, disabled, open/closed).
+- A component needs ARIA roles/attributes reflecting internal state.
+- You're reviewing a component that still uses `@HostBinding`/`@HostListener` decorators and want to modernize it.
+
+## Dynamic classes from signals
+```typescript
+@Component({
+  selector: 'ui-button',
+  host: {
+    '[class]': '"ui-button-size-" + this.size() + " ui-button-type-" + this.type()'
+  }
+})
+export class ButtonComponent {
+  size = input<ButtonSize>('medium');
+  type = input<ButtonType>('primary');
+}
+```
+
+## Conditional single classes
+```typescript
+host: {
+  '[class.ui-input-disabled]': 'isDisabledClassValue()',
+  '[class.ui-slot-left]': 'slotLeftClassValue()',
+  '[class.ui-slot-right]': 'slotRightClassValue()',
+  '[class.ui-input-has-value]': 'hasValueClassValue()',
+  '[class]': '"ui-input-size-" + size()'
+}
+```
+Both a computed `[class]` string binding and multiple `[class.x]` boolean bindings can coexist on the same host object.
+
+## ARIA / attribute bindings
+```typescript
+host: {
+  '[class]': '"ui-" + type() + " ui-dropdown-size-" + size()',
+  '[class.ui-dropdown-disabled]': 'isDisabled()',
+  '[attr.role]': '"listbox"',
+  '[attr.aria-multiselectable]': 'multiple()'
+}
+```
+Use `[attr.x]` for ARIA/attribute reflection (attributes can be `null`/removed), and `[class.x]`/`[class]` for CSS classes.
+
+## Event bindings on the host
+```typescript
+host: {
+  '(click)': 'onHostClick($event)',
+  '(keydown.escape)': 'onEscape()'
+}
+```
+This replaces `@HostListener('click', ['$event'])`.
+
+## Migration from decorators
+| Legacy | Modern |
+|---|---|
+| `@HostBinding('class.disabled') get isDisabled() {...}` | `host: { '[class.disabled]': 'isDisabled()' }` |
+| `@HostBinding('attr.role') role = 'listbox';` | `host: { '[attr.role]': '"listbox"' }` |
+| `@HostListener('click', ['$event']) onClick(e) {...}` | `host: { '(click)': 'onClick($event)' }` |
+
+## Pitfalls
+- Expressions in the `host` object are evaluated in the component's context, not a template — signals must still be called with `()`.
+- Don't mix a `[class]` string binding that already contains a class with an unrelated `[class.foo]` binding that toggles the *same* class name — Angular merges them, but it's easy to introduce conflicting logic.
+- Keep expressions in `host` small; if logic gets complex, compute it in a `computed()` signal and reference that signal's name in the binding.

package/skills/components/viewchild-contentchild-signals/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: viewchild-contentchild-signals
+description: Query view and content children with the signal-based viewChild(), viewChildren(), contentChild(), and contentChildren() functions instead of decorators.
+---
+
+# Signal-based ViewChild / ContentChild Queries
+
+This skill covers reading template references and projected content using the functional query API.
+
+## When to use
+- A component needs a reference to a native element or child component/directive in its own template (`viewChild`).
+- A component needs to detect content the consumer projected into it via `<ng-content>` (`contentChild`), e.g. optional header/footer templates.
+- Multiple matching elements need to be queried at once (`viewChildren`/`contentChildren`).
+
+## `viewChild()` / `viewChild.required()`
+```typescript
+// Optional — returns Signal<ElementRef<HTMLInputElement> | undefined>
+inputElementMaybe = viewChild<ElementRef<HTMLInputElement>>('input');
+
+// Required — throws if not found, returns Signal<ElementRef<HTMLInputElement>>
+inputElement = viewChild.required<ElementRef<HTMLInputElement>>('input');
+slotLeft = viewChild.required<ElementRef<HTMLDivElement>>('slotLeft');
+```
+Use `.required()` whenever the template reference is guaranteed to exist for the lifetime of the component (e.g. it's not behind an `@if`). Use the plain (optional) form when the target may be conditionally rendered.
+
+## `contentChild()`
+```typescript
+headerTmpl = contentChild<DropdownHeaderTmplDirective>(DropdownHeaderTmplDirective);
+itemTmpl = contentChild<DropdownItemTmplDirective>(DropdownItemTmplDirective);
+noItemsTmpl = contentChild<DropdownNoItemsTmplDirective>(DropdownNoItemsTmplDirective);
+```
+Typical pattern: define a structural/attribute directive (e.g. `*uiDropdownItemTmpl`) that consumers apply to an `<ng-template>`, then read it with `contentChild()` to know whether a custom template was provided and to get its `TemplateRef`.
+
+## `viewChildren()` / `contentChildren()`
+Return a `Signal<ReadonlyArray<T>>` that updates automatically when the matched set changes (e.g. items added/removed via `@for`).
+
+```typescript
+rows = viewChildren<ElementRef<HTMLTableRowElement>>('row');
+```
+
+## Reading query signals reactively
+Because these are signals, they can be safely read inside `computed()` or `effect()`/`afterRenderEffect()`:
+```typescript
+constructor() {
+  effect(() => {
+    if (this.slotLeft().nativeElement.children.length > 0) {
+      this.slotLeftClassValue.set(true);
+    }
+  });
+}
+```
+
+## Migration from decorators
+| Legacy | Signal-based |
+|---|---|
+| `@ViewChild('input') inputElement!: ElementRef;` | `inputElement = viewChild.required<ElementRef>('input');` |
+| `@ViewChildren(Item) items!: QueryList<Item>;` | `items = viewChildren(Item);` |
+| `@ContentChild(Tmpl) tmpl?: Tmpl;` | `tmpl = contentChild(Tmpl);` |
+| `@ContentChildren(Tmpl) tmpls!: QueryList<Tmpl>;` | `tmpls = contentChildren(Tmpl);` |
+
+All reads change from `this.inputElement` to `this.inputElement()`.
+
+## Pitfalls
+- Query signals are only populated after the component's view/content has been initialized — reading them in the constructor body (outside `effect()`) will return `undefined`/throw for `.required()`.
+- Don't use `ngAfterViewInit`/`ngAfterContentInit` alongside signal queries just to "wait for them" — use `effect()`/`afterRenderEffect()`, which already re-run once the query resolves.
+- `QueryList`-specific APIs (`.changes` Observable) don't exist on signal queries — read the signal reactively instead of subscribing.

package/skills/libraries/library-versioning/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: library-versioning
+description: Update the version of a specific library and manage its peer dependencies accordingly.
+---
+
+# Update Library Version Skill
+
+This skill allows the user to update the version of a specific library in the repository and automatically manages its usage in other libraries' `peerDependencies`.
+
+## Parameters
+The user must provide:
+1.  **Library Name**: The name of the library to update (e.g., `button`, `core`, `input`).
+2.  **Update Type**: `patch`, `minor`, or `major`.
+
+## Process Instructions
+
+### 1. Identify and Read the Target Library
+1.  Locate the library's `package.json` file. Based on the file structure, it is typically in `projects/[project-name]/[library-name]/package.json`.
+2.  Read the file to obtain the current `version`.
+
+### 2. Calculate New Version
+Calculate the new version string based on the **Update Type**:
+-   **Patch**: Increment the third number (z). Reset nothing. (e.g., `1.0.1` -> `1.0.2`)
+-   **Minor**: Increment the second number (y). Reset the third number (z) to `0`. (e.g., `1.0.5` -> `1.1.0`)
+-   **Major**: Increment the first number (x). Reset the second (y) and third (z) numbers to `0`. (e.g., `1.2.3` -> `2.0.0`)
+
+### 3. Update the Target Library
+1. The skill must not use any scripts or commands to update the version. Instead, it should directly edit the `package.json` file.
+2.  Edit `projects/[project-name]/[library-name]/package.json`.
+3.  Replace the old `version` value with the **New Version**.
+
+### 4. Handle Peer Dependencies
+**Condition**:
+-   **IF Update Type is PATCH**: Do **NOT** update references in any other files. `peerDependencies` are assumed to handle patch updates automatically (via ranges like `^` or `~`).
+-   **IF Update Type is MINOR or MAJOR**:
+    1.  Search through all other libraries in `projects/[project-name]/` (look for `projects/[project-name]/*/package.json`).
+    2.  In each `package.json`, check the `peerDependencies` section.
+    3.  If the *Target Library* is listed in `peerDependencies`:
+        -   Update its version value to the **New Version**.
+    4.  Update patch version of the affected libraries if the update type is minor or major, to ensure compatibility. For example, if a library depends on `button` and the `button` library is updated from `1.0.0` to `1.1.0`, the dependent library's version should be updated from `1.0.0` to `1.0.1` (patch update) to reflect the change without breaking compatibility.
+
+### 5. Final Report
+Generate and display a Markdown table summarizing the actions taken:
+
+| Library Name | Old Version | New Version | Strategy | Dependencies Updated |
+| :--- | :--- | :--- | :--- | :--- |
+| `<Found Name>` | `<Old>` | `<New>` | `<Type>` | `<List of other libs updated>` |
+
+*If no dependencies were updated (e.g., for a patch), state "None" or "Skipped (Patch)".*

package/skills/libraries/monorepo-ng-packagr/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: monorepo-ng-packagr
+description: Structure and operate a multi-library Angular monorepo built with ng-packagr, including workspace path aliases and orchestrated build/publish/version scripts.
+---
+
+# Angular Monorepo with ng-packagr
+
+This skill covers organizing a workspace containing many independently-buildable Angular libraries (a design-system style monorepo), and the tooling that ties them together.
+
+## When to use
+- Setting up or maintaining a workspace where each UI component lives in its own publishable library under `projects/<scope>/<name>/`.
+- Writing/maintaining Node.js scripts that build, version, or publish all (or a subset of) libraries in one command.
+- Diagnosing "cannot find module `@scope/lib`" errors caused by stale `dist/` output or missing path aliases.
+
+## Workspace layout
+```
+angular.json          # one "project" entry per library + per app
+package.json           # workspaces: ["dist/ui/*"] — consumers resolve built packages
+tsconfig.json          # path aliases mapping @scope/lib -> dist/scope/lib
+scripts/
+  build-library.mjs           # builds a single library via the Angular CLI builder
+  generate-library.mjs        # scaffolds a new library folder structure
+  update-library-version.mjs  # bumps a library's version + dependent peerDependencies
+  publish-library.mjs         # npm publish for one library
+  publish-libraries.mjs       # publish all libraries in dependency order
+  tests-libraries.mjs         # run tests across all libraries
+projects/
+  ui/
+    button/  input/  core/  ...  # each an independent ng-packagr library
+```
+
+## Why libraries depend on `dist/`, not `src/`
+```json
+// tsconfig.json
+"paths": {
+  "@ui/button": ["dist/ui/button"],
+  "@ui/core": ["dist/ui/core"]
+}
+```
+Libraries import each other via their **built** output (`dist/ui/*`), matching exactly how an external consumer would resolve the published npm package. This catches "works in source, breaks when published" bugs early, at the cost of requiring a build step before you can consume a library's latest changes from a sibling library.
+
+## Build ordering matters
+Libraries that depend on others (e.g. `datepicker` depends on `popover`, `input`, `calendar`, `core`) must be built **after** their dependencies. A build orchestration script typically:
+1. Reads each library's `package.json` `peerDependencies`/`dependencies` on other `@ui/*` packages.
+2. Topologically sorts libraries so dependencies build first.
+3. Invokes the Angular CLI build (`ng build <project>`) for each, writing to `dist/ui/<name>`.
+
+## Versioning across the monorepo
+When a library's version changes (minor/major), every other library that lists it in `peerDependencies` needs a compatible version bump too (see the `update-library-version` skill in this same skills folder for the exact algorithm used in this repo).
+
+## Publishing
+`publish-library.mjs` typically:
+1. Builds the library fresh.
+2. Copies/verifies `package.json` metadata into `dist/ui/<name>`.
+3. Runs `npm publish` from the `dist/ui/<name>` folder (never from `projects/`, since that folder contains source + config files that shouldn't ship).
+
+`publish-libraries.mjs` wraps this for multiple libraries, respecting the same dependency order as the build step.
+
+## Adding a brand-new library to the monorepo
+1. Scaffold it (see `standalone-component-library` skill for the folder layout).
+2. Add a project entry to `angular.json`.
+3. Add its `@ui/<name>` path alias to `tsconfig.json`.
+4. Add it to any orchestration script's library list/const (e.g. `scripts/const/library.const.mjs`).
+5. Build it once (`node scripts/build-library.mjs <name>` or equivalent) before any sibling library imports it.
+
+## Pitfalls
+- Editing a library's `src/` and expecting a sibling library (importing via `@ui/<name>`) to pick up the change without rebuilding — it won't, since imports resolve to `dist/`.
+- Publishing out of dependency order can publish a library whose `peerDependencies` point to a version of another library that isn't published yet.
+- Forgetting to update the `tsconfig.json` path alias when adding a library causes confusing "cannot find module" errors that look like a build problem but are actually a path-mapping problem.

package/skills/libraries/standalone-component-library/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: standalone-component-library
+description: Scaffold and structure a standalone Angular component library (no NgModules) buildable independently with ng-packagr, ready for a multi-library workspace.
+---
+
+# Standalone Component Library
+
+This skill helps create a new Angular library that follows the standalone-only architecture (no `NgModule`), independently buildable and publishable.
+
+## When to use
+- Adding a brand new UI component (e.g. `badge`, `slider`) to a multi-library Angular workspace.
+- Reviewing whether an existing library still relies on `NgModule` and should be converted.
+
+## Folder structure
+```
+projects/ui/<component-name>/
+├── src/
+│   ├── lib/
+│   │   ├── components/
+│   │   │   └── <component-name>.component.ts
+│   │   │   └── <component-name>.component.html
+│   │   │   └── <component-name>.component.scss
+│   │   ├── directives/
+│   │   ├── services/
+│   │   ├── interfaces/
+│   │   ├── injectors/
+│   │   ├── types/
+│   │   ├── adapters/
+│   │   └── helpers/
+│   └── public-api.ts
+├── ng-package.json
+├── package.json
+└── tsconfig.lib.json
+```
+
+## `public-api.ts`
+Only export what consumers are meant to use — component classes, public interfaces/types, directives, and injection tokens. Do not export internal helpers/adapters.
+```typescript
+export * from './lib/components/ui-button.component';
+export * from './lib/types/ui-button-size.type';
+export * from './lib/types/ui-button-type.type';
+```
+
+## Component definition (standalone)
+```typescript
+@Component({
+  selector: 'ui-button',
+  standalone: true, // implicit/default in modern Angular, but explicit is fine
+  templateUrl: './ui-button.component.html',
+  styleUrls: ['./ui-button.component.scss'],
+  imports: [NgTemplateOutlet, IconComponent],
+  host: {
+    '[class]': '"ui-button-size-" + this.size() + " ui-button-type-" + this.type()'
+  }
+})
+export class ButtonComponent { }
+```
+```
+Every dependency the template needs (other components, directives, pipes, `CommonModule` pieces like `NgTemplateOutlet`) must be listed explicitly in `imports`. There is no root `NgModule` providing them implicitly.
+
+## `ng-package.json`
+```json
+{
+  "$schema": "../../../node_modules/ng-packagr/ng-package.schema.json",
+  "dest": "../../../dist/ui/button",
+  "lib": {
+    "entryFile": "src/public-api.ts"
+  }
+}
+```
+
+## `angular.json` project entry
+Register the library as its own project with the `@angular/build:ng-packagr` builder so it can be built in isolation:
+```json
+"button": {
+  "projectType": "library",
+  "root": "projects/ui/button",
+  "sourceRoot": "projects/ui/button/src",
+  "architect": {
+    "build": {
+      "builder": "@angular/build:ng-packagr",
+      "options": { "project": "projects/ui/button/ng-package.json" }
+    }
+  }
+}
+```
+
+## Path aliases for cross-library consumption
+In the workspace `tsconfig.json`, map each library to its **built** output so other libraries/apps import the compiled package, not source:
+```json
+"paths": {
+  "@ui/button": ["dist/ui/button"],
+  "@ui/core": ["dist/ui/core"]
+}
+```
+
+## Checklist for a new component library
+1. Create the folder structure above under `projects/ui/<name>/`.
+2. Write `public-api.ts` exporting only the public surface.
+3. Add `ng-package.json` and `package.json` (with `peerDependencies` on `@angular/core`/`@angular/common` and any `@ui/*` libs it depends on).
+4. Register the project in `angular.json`.
+5. Add the `@ui/<name>` path alias in `tsconfig.json`.
+6. Build with the workspace's library build script (see `angular-monorepo-ng-packagr` skill) before consuming it from another library.

package/skills/performance/control-flow-syntax/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: control-flow-syntax
+description: Use Angular's built-in template control flow (@if, @for, @switch) instead of the *ngIf/*ngFor/*ngSwitch structural directives.
+---
+
+# Built-in Control Flow Syntax
+
+This skill covers Angular's native `@if`/`@for`/`@switch` block syntax, which replaces the `*ngIf`/`*ngFor`/`*ngSwitch` structural directives.
+
+## When to use
+- Writing or reviewing any Angular template (`.html` or inline template).
+- Migrating a component still using `*ngIf`, `*ngFor`, or `*ngSwitch`.
+
+## `@if` / `@else if` / `@else`
+```html
+@if (!iconOnly()) {
+  <ng-container [ngTemplateOutlet]="labelTpl" />
+} @else {
+  <ui-button class="calendar-button" [size]="'small'" [type]="'clear'">
+    <ui-icon [icon]="'ui-calendar'" />
+  </ui-button>
+}
+```
+```html
+@if (formatHours() === '24') {
+  <span class="format-hours">{{ formatHours() }}h</span>
+} @else if (formatHours() === '12') {
+  <div class="format-hours-buttons">
+    <button class="format-hours-button">AM</button>
+    <button class="format-hours-button">PM</button>
+  </div>
+} @else {
+  <span>Unknown format</span>
+}
+```
+Bind the condition result to a local template variable to avoid recomputation, using `as`:
+```html
+@if (itemTmpl(); as tmpl) {
+  <ng-container [ngTemplateOutlet]="tmpl.templateRef" />
+}
+```
+
+## `@for` with mandatory `track`
+```html
+@for (day of weekDays(); track $index) {
+  <div class="day">{{ day }}</div>
+}
+
+@for (item of data(); track item.id; let i = $index) {
+  <div class="tree-node">{{ item.label }}</div>
+}
+```
+`track` is **required** (unlike `*ngFor`'s optional `trackBy`). Prefer tracking by a stable unique key (`item.id`) over `$index` whenever the list can reorder/filter, since `$index` tracking causes Angular to treat every reordering as a full replace.
+
+Available implicit variables: `$index`, `$first`, `$last`, `$even`, `$odd`, `$count`.
+
+`@for` also supports an `@empty` block:
+```html
+@for (item of items(); track item.id) {
+  <div>{{ item.label }}</div>
+} @empty {
+  <div class="no-items">No items found</div>
+}
+```
+
+## `@switch` / `@case` / `@default`
+```html
+@switch (currentView()) {
+  @case ('month') {
+    <gantt-month-view />
+  }
+  @case ('week') {
+    <gantt-week-view />
+  }
+  @default {
+    <gantt-day-view />
+  }
+}
+```
+
+## Migration checklist
+| Legacy | Modern |
+|---|---|
+| `*ngIf="cond"` | `@if (cond) { ... }` |
+| `*ngIf="cond; else tpl"` | `@if (cond) { ... } @else { ... }` |
+| `*ngFor="let x of items; trackBy: fn"` | `@for (x of items; track x.id) { ... }` |
+| `*ngSwitch` / `*ngSwitchCase` / `*ngSwitchDefault` | `@switch` / `@case` / `@default` |
+
+Since these are compiler-level syntax (not directives), `CommonModule`/`NgIf`/`NgFor`/`NgSwitch` no longer need to be imported just to use them — only import `NgTemplateOutlet`/`NgClass`/etc. for directives you still explicitly use.
+
+## Pitfalls
+- Forgetting `track` in `@for` is a compile error — always pick a stable key, not an object reference that changes identity on every request.
+- `@if...as` only binds within that block's scope, not in sibling `@else` blocks.
+- Don't mix `*ngIf`/`*ngFor` and `@if`/`@for` in the same file inconsistently — migrate a whole template at once for readability.

package/skills/performance/defer-blocks/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: defer-blocks
+description: Lazy-load template sections with Angular's @defer block, including triggers (viewport, idle, interaction), placeholder, loading, and error states.
+---
+
+# `@defer` Blocks
+
+This skill covers deferring the loading and rendering of a template section (and the component code it depends on) until a trigger condition is met.
+
+## When to use
+- A heavy/rarely-visible component (charts, rich editors, large tables, secondary tabs) shouldn't be part of the initial bundle.
+- Content only needs to render once it scrolls into the viewport, the browser is idle, or the user interacts with a trigger element.
+- You want an explicit loading/placeholder/error UI for a lazily-loaded section.
+
+## Basic syntax
+```html
+@defer {
+  <app-gantt-chart [data]="ganttData()" />
+} @placeholder {
+  <div class="chart-placeholder">Chart will appear here</div>
+} @loading (minimum 200ms) {
+  <app-spinner />
+} @error {
+  <div class="chart-error">Failed to load chart</div>
+}
+```
+- `@placeholder`: shown before the trigger fires (optional, defaults to nothing rendered).
+- `@loading`: shown while the deferred dependencies are being fetched; supports `minimum`/`after` timing hints to avoid flicker.
+- `@error`: shown if loading the deferred block's dependencies fails.
+
+## Triggers
+```html
+<!-- Render when the placeholder scrolls into the viewport -->
+@defer (on viewport) {
+  <app-heavy-table [data]="rows()" />
+} @placeholder {
+  <div class="table-placeholder"></div>
+}
+
+<!-- Render when the browser is idle -->
+@defer (on idle) {
+  <app-recommendations />
+}
+
+<!-- Render on user interaction with a referenced element -->
+@defer (on interaction(triggerBtn)) {
+  <app-details-panel />
+} @placeholder {
+  <button #triggerBtn>Show details</button>
+}
+
+<!-- Render after another condition/signal becomes true -->
+@defer (when isReady()) {
+  <app-report />
+}
+
+<!-- Combine a timer with another trigger -->
+@defer (on timer(2s)) {
+  <app-promo-banner />
+}
+```
+Other triggers: `on hover(ref)`, `on immediate`.
+
+## Prefetching
+Separate the trigger for *rendering* from the trigger for *fetching the code* ahead of time:
+```html
+@defer (on interaction; prefetch on idle) {
+  <app-modal-content />
+} @placeholder {
+  <button>Open</button>
+}
+```
+This downloads the deferred chunk during idle time but still waits for the interaction to actually render it.
+
+## Guidelines for a component library
+- Reserve `@defer` for genuinely optional/heavy UI (secondary panels, rarely-opened dialogs, charts) — don't wrap every component, since each `@defer` block becomes a separate lazy chunk with its own network round-trip.
+- Always pair `on viewport`/`on interaction` triggers with a meaningful `@placeholder` sized close to the final content to avoid layout shift.
+- `@defer` only affects the components/pipes/directives used **exclusively** inside the block — if a dependency is also used outside the block, it isn't deferred.
+
+## Pitfalls
+- Deferred content unmounts and loses state if its trigger condition becomes false again (depending on trigger) — don't rely on it for state that must persist.
+- `on interaction`/`on hover` without an explicit element reference default to the placeholder itself — make sure a placeholder exists in that case.
+- Testing `@defer` blocks requires explicitly flushing/triggering the deferred state in tests (e.g. Angular's `DeferBlockFixture` APIs) — see the `vitest-angular-components` skill.