Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions content/topics/angular-app-config/sources.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
# Authoring sources

Retrieval job: recognize a concrete need for application-wide configuration and recover its provider entry, including the distinction between centralized error reporting and request-specific feedback. Targets Angular 22; reviewed 2026-10-31.

- [ApplicationConfig](https://angular.dev/api/core/ApplicationConfig): providers available during bootstrap and to the root component and descendants.
- [provideBrowserGlobalErrorListeners](https://angular.dev/api/core/provideBrowserGlobalErrorListeners): listens to window error and unhandledrejection and forwards to ErrorHandler.
- [ErrorHandler](https://angular.dev/api/core/ErrorHandler): default console reporting and useClass replacement.
- [Unhandled errors](https://angular.dev/best-practices/error-handling): local handling for operation-specific recovery; global reporting is not UI recovery.
- [provideRouter](https://angular.dev/api/router/provideRouter): route provider setup.
- [HTTP setup](https://angular.dev/guide/http/setup): provideHttpClient with withInterceptors configures request features. Default HTTP availability is already covered by the related HTTP topic.
- [provideAppInitializer](https://angular.dev/api/core/provideAppInitializer): runs at startup in an injection context; loading language data is an explicit use case; returned Promise resolution or Observable completion delays initialization.
- [Dependency providers](https://angular.dev/guide/di/defining-dependency-providers): useClass replacement and providedIn root registration.
- [HTTP interceptors](https://angular.dev/guide/http/interceptors): shared request handling, authentication-header use case and withInterceptors registration.
- [Cognito access tokens](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-the-access-token.html): access tokens authorize API operations; the reader-facing example stays provider-neutral.
- [Using components](https://angular.dev/guide/components#using-components): component imports make template dependencies available.

The optional examples are entries for an existing providers array, not complete files. routes, authInterceptor, loadStartupData and GlobalErrorHandler are application-defined identifiers; the reference does not implement routing, authentication, remote configuration or monitoring. The generic useValue/API_BASE_URL example, bootstrap plumbing and detached import-location paragraph were removed after owner retrieval review. No product exercise code is changed by this reference.
82 changes: 82 additions & 0 deletions content/topics/angular-app-config/topic.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
---
id: '64c227ae-34fd-4c0d-bd8d-668c56205fc1'
title: 'Configure application-wide providers'
status: 'accepted'
summary: 'Recognize when to configure routing, shared HTTP behavior, startup work and global error reporting.'
iconKey: 'operations'
domains:
- 'javascript'
kind: 'operations'
childTopicIds: []
relatedTopicIds:
- 'd48436d1-d79b-4e9a-bac5-9ff8672920f7'
- '6b2a1c19-acaa-4793-9e8a-7a783564bde5'
---

## Configure behavior used across the app

Use **`app.config.ts`** to configure shared behavior, such as **navigation**,
**HTTP request rules** or the app's **default error handler**. Components can then use
that configuration without repeating the setup individually.

```typescript
import { ApplicationConfig, provideBrowserGlobalErrorListeners } from '@angular/core';

export const appConfig: ApplicationConfig = {
providers: [provideBrowserGlobalErrorListeners()],
};
```

> **Your service already has `providedIn: 'root'`?** Inject it directly;
> no extra registration is needed here.

To **render a child component**, add it to the parent's component `imports`.

## Add configuration when you need it

**Give different screens their own URLs** → add `provideRouter(routes)`.

**Send an access token with requests to your API** → register an HTTP
interceptor that adds `Authorization: Bearer <access-token>`:

```typescript
provideHttpClient(withInterceptors([authInterceptor]));
```

**Load essential data before the first screen appears**, such as the initial
language's translations → add `provideAppInitializer(loadStartupData)`. Return a
Promise or Observable from `loadStartupData`: startup **waits for it to resolve
or complete**.

These are optional entries in `providers`. `routes`, `authInterceptor` and
`loadStartupData` are application code you supply.

## Collect unexpected errors in one place

`provideBrowserGlobalErrorListeners()` forwards uncaught browser failures to
Angular's `ErrorHandler` for centralized reporting:

```text
Uncaught JavaScript error or
unhandled Promise rejection
↓
Angular ErrorHandler
↓
Console logging by default
```

To **send errors to an error-tracking service**, replace the default handler
with an entry in `providers`:

```typescript
{
provide: ErrorHandler,
useClass: GlobalErrorHandler,
},
```

`GlobalErrorHandler` is your own implementation of `ErrorHandler`; its
`handleError(error)` method performs the reporting.

**Reporting does not recover the UI.** Handle expected request failures near
the request, where you can show feedback such as “Product not found”.
16 changes: 16 additions & 0 deletions content/topics/angular-app-overview/sources.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# Authoring sources

Retrieval job: recognize the roles of the Angular app pieces encountered in the product exercise and identify when each becomes useful. Targets standalone Angular 22; checked 2026-10-31. Configuration and implementation syntax remain in the related operational references.

- [Components](https://angular.dev/guide/components): class/template/selector, rendering child components, component tree.
- [bootstrapApplication](https://angular.dev/api/platform-browser/bootstrapApplication): chosen standalone root component and application configuration.
- [ApplicationConfig](https://angular.dev/api/core/ApplicationConfig): application-level provider setup.
- [Dependency injection](https://angular.dev/guide/di): dependencies supplied to consumers, sharing behavior and substituting test doubles.
- [Creating and using services](https://angular.dev/guide/di/creating-and-using-services): services and inject.
- [Defining providers](https://angular.dev/guide/di/defining-dependency-providers): provider recipes, automatic providedIn registration and explicit replacement.
- [Hierarchical injectors](https://angular.dev/guide/di/hierarchical-dependency-injection): application and local provider scopes, component sharing and injector lookup; detailed scope choice lives in the child reference.
- [HTTP interceptors](https://angular.dev/guide/http/interceptors): shared request/response behavior, authentication and logging examples, functional interceptor form.

Product component names illustrate composition, not Angular-mandated filenames or special page component types. The startup/composition diagram adapts docs/design/diagrams/starter.svg and preserves the embedded font bytes and complete font licenses. Dependency injection uses a short sentence instead of a redundant diagram. No learner implementation or additional framework API is introduced here.

2026-11-01 retrieval revision: distinguish Angular-supplied dependencies and feature registrations from providers the application author must register. HttpClient version details and the contextual DestroyRef example remain in the HTTP service reference.
251 changes: 251 additions & 0 deletions content/topics/angular-app-overview/startup-and-components.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
64 changes: 64 additions & 0 deletions content/topics/angular-app-overview/topic.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
---
id: 'd48436d1-d79b-4e9a-bac5-9ff8672920f7'
title: 'How an Angular app fits together'
status: 'accepted'
summary: 'Recognize components, services, providers and interceptors, and understand how startup and dependency injection connect them.'
iconKey: 'architecture'
domains:
- 'javascript'
kind: 'concept'
childTopicIds:
- 'fe994f41-dbc9-456c-b50e-53d3a4a9719c'
- '253aba39-8aed-4a85-94fb-7f09406e72d3'
relatedTopicIds:
- 'f7aa760f-30aa-43da-8746-20a39e39529e'
- '6b2a1c19-acaa-4793-9e8a-7a783564bde5'
- '64c227ae-34fd-4c0d-bd8d-668c56205fc1'
---

## Build the screen from components

![main.ts uses app.config.ts to start App. App renders ProductsPage, which renders the create form and product list.](./startup-and-components.svg)

- **Component:** a TypeScript class paired with a template; **owns a piece of UI**.
Split components when those pieces need their own behavior or can be reused.
- **Template:** HTML with Angular bindings for **displaying state and responding
to events**.
- **Root component:** the **first component Angular renders**, usually `App`.
Use it to compose the application's outer layout. “Page” and “child” are
**roles, not special component types**.
- **Application configuration (`app.config.ts`):** shared setup, such as routing,
HTTP interceptors or the default error handler. Configure it when the **same
behavior should apply across the app**.

`main.ts` selects the root component and configuration when starting Angular.

## Reuse behavior through services and DI

Components, services and interceptors can use **`inject(...)` to request
dependencies**; Angular supplies instances using their providers.

Angular supplies some built-in dependencies automatically. Others become
available when you configure a feature, so **not every injected dependency
needs your own `providers` entry**.

- **Service:** a class containing behavior that can be used **independently of a
particular template**. Put product API calls here so components can use them
without each repeating the HTTP code.
- **Dependency injection (DI):** **Angular supplies a class's dependencies** instead
of the class constructing them. This lets components share a service and lets
tests substitute a fake implementation.
- **Provider:** a registration telling Angular **what to supply** for a requested
dependency.
- **Provider scope:** determines **where the dependency is available and which
consumers share it**. Register application-wide services with `providedIn: 'root'`
or application configuration; use route, component or directive providers for
narrower scopes. Module-based apps also support module providers.
- **Injector:** Angular's dependency resolver. It **looks up providers and supplies
the dependencies**.

## Apply shared HTTP behavior

**Interceptor:** a function in Angular's **HTTP request/response pipeline**. Use one
when several API calls need the **same authentication header or request logging**,
so each service method does not repeat that behavior. A basic product lookup needs no custom interceptor.
11 changes: 11 additions & 0 deletions content/topics/angular-component-communication/sources.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Authoring sources

Retrieval job: choose an explicit component boundary and recover the syntax for parent/child data, action events and imperative UI methods. Targets Angular 22; drafted 2026-11-02.

- [Inputs](https://angular.dev/guide/components/inputs): required input signals, parent binding, read-only signals versus mutable referenced objects.
- [Outputs](https://angular.dev/guide/components/outputs): typed output emitters and $event payloads; outputs are not browser events or RxJS Observables.
- [Child queries](https://angular.dev/guide/components/queries): signal view queries, required/optional results, view lifetime and conditional children.
- [Component composition](https://angular.dev/guide/components#using-components): parent imports and selectors.
- [Style guide](https://angular.dev/style-guide): UI responsibilities and separation of behavior. Container/presentational boundaries here are contextual design advice, not an Angular-enforced architecture.

The ProductRow example is a self-contained reference with a two-field local Product shape, not a change to the learner exercise. Parent event handling only selects an edit target; it does not implement an editor or HTTP mutation. The final dialog fragment assumes an existing dialog with a public open(Product) method; query availability and required-child preconditions are stated. Detailed form handling and HTTP lifecycle belong to the related topics. No new dependencies or changes to the exercise are required.
124 changes: 124 additions & 0 deletions content/topics/angular-component-communication/topic.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,124 @@
---
id: '88a16c45-cb2c-45e5-a067-445166a3f509'
title: 'Pass data and events between components'
status: 'accepted'
summary: 'Choose inputs, outputs, child methods or service injection, and make component dependencies explicit.'
iconKey: 'operations'
domains:
- 'javascript'
kind: 'pattern'
childTopicIds: []
relatedTopicIds:
- '6b2a1c19-acaa-4793-9e8a-7a783564bde5'
- '8f0eac15-f8c7-4a92-80bb-0c45ff6b4e87'
---

## Choose the boundary

| Need | Use |
| ------------------------------------- | ---------------------------- |
| Supply data to a child | `input()` + `[property]` |
| Receive an action from a child | `output()` + `(event)` |
| Open or focus child UI | `viewChild()` + child method |
| Access API or shared feature behavior | Inject a service |

**Inputs and outputs define a data/event contract.** A child that also injects
an API service still depends on that service.

## Pass data down and actions up

```text
ProductsPage ── [product] ───────→ ProductRow
ProductsPage ←─ (editRequested) ── ProductRow
```

**`product-row.ts`**

```typescript
import { Component, input, output } from '@angular/core';

export interface Product {
id: string;
name: string;
}

@Component({
selector: 'app-product-row',
template: `
<span>{{ product().name }}</span>
<button type="button" (click)="editRequested.emit(product())">Edit</button>
`,
})
export class ProductRow {
readonly product = input.required<Product>();
readonly editRequested = output<Product>();
}
```

**`products-page.ts`**

```typescript
import { Component, signal } from '@angular/core';
import { Product, ProductRow } from './product-row';

@Component({
imports: [ProductRow],
template: `
<app-product-row [product]="selectedProduct()" (editRequested)="beginEdit($event)" />
@if (editingProduct(); as product) {
<p role="status">Editing {{ product.name }}</p>
}
`,
})
export class ProductsPage {
protected readonly selectedProduct = signal<Product>({ id: 'p1', name: 'Notebook' });
protected readonly editingProduct = signal<Product | null>(null);

protected beginEdit(product: Product): void {
this.editingProduct.set(product);
}
}
```

- **Read an input with `product()`**; `input.required` requires the parent binding.
- **`$event` is the emitted payload** — here a `Product`, not a browser event.
- **Emit an action instead of mutating the input object.** Read-only input signals
do not make the objects they hold deeply immutable.

## Choose who calls the API

| Put API calls in… | When it fits | Cost |
| ---------------------- | --------------------------------- | --------------------------------------- |
| Parent/coordinator | Reuse the child across features | Parent handles events and request state |
| Feature-specific child | Child owns that feature operation | Child depends on the API service |

A reusable form can still own **controls, validation and local interaction state**.
The parent can receive submitted values and call the service. These roles are
sometimes called container/smart and presentational/dumb; they are **design choices,
not Angular component types**.

## Call a child method for a UI action

For an existing `ProductEditDialog` with an `open(product)` method, the parent
renders the child and calls its public method:

```angular-html
<app-product-edit-dialog />
<button type="button" (click)="openEditor(selectedProduct())">Edit</button>
```

```typescript
private readonly editor = viewChild.required(ProductEditDialog);

protected openEditor(product: Product): void {
this.editor().open(product);
}
```

The parent imports `ProductEditDialog` in its component `imports`.
**`viewChild` finds the rendered child; it does not create one.** Access it after
rendering, such as from a click handler. `required` assumes the child is present;
for a conditional child, use `viewChild(ProductEditDialog)` and check for `undefined`.

The parent now depends on the child's **method API**. Use this for actions such as
open/focus; use inputs and outputs for ordinary data and event exchange.
14 changes: 14 additions & 0 deletions content/topics/angular-component-state/sources.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
# Authoring sources

Retrieval job: recover a standalone component/template pair with signal-backed list state and the syntax needed to display and change it. Targets Angular 22; verified 2026-10-30.

- [Component anatomy](https://angular.dev/guide/components): metadata, relative template/style paths, standalone imports and selector composition.
- [Angular signals](https://angular.dev/guide/signals): read/set/update and default equality; deep mutation is not prevented or independently notified.
- [Template bindings](https://angular.dev/guide/templates/binding): interpolation and property bindings; reading signals in templates.
- [Event listeners](https://angular.dev/guide/templates/event-listeners): event-handler syntax.
- [Control flow](https://angular.dev/guide/templates/control-flow): for/track/empty and built-in control flow. Tracking is required; prefer stable unique keys for changing collections, and $index for static collections. Tracking guidance reviewed 2026-11-01.
- [Style guide](https://angular.dev/style-guide): protected template members and readonly references.

Snippets are purpose-built reference examples. Local sample IDs are preview data, not the UUID API model. Compile/render verification is performed in a scratch Angular workspace, separate from the learner exercise.

- [Using components](https://angular.dev/guide/components#using-components): standalone components are directly imported by consuming components; standalone defaults to true from Angular 19. Parent example replaces the former metadata-label table; composition wording reviewed 2026-11-02.
Loading
Loading