@anglr/select 16.0.3 → 16.0.4-beta.20260511085948

package/.claude/skills/angular-developer/references/cli.md

@@ -0,0 +1,86 @@
+# Angular CLI Guide for Agents
+
+The Angular CLI (`ng`) is the primary tool for managing an Angular workspace. Always prefer CLI commands over manual file creation or generic `npm` commands when modifying project structure or adding Angular-specific dependencies.
+
+## 1. Managing Dependencies
+
+**ALWAYS use `ng add` for Angular libraries** instead of `npm install`. `ng add` installs the package AND runs initialization schematics (e.g., configuring `angular.json`, updating root providers).
+
+```bash
+ng add @angular/material
+ng add tailwindcss
+ng add @angular/fire
+```
+
+To update the application and its dependencies (which automatically runs code migrations):
+
+```bash
+ng update @angular/core@<latest or specific version> @angular/cli<latest or specific version>
+```
+
+## 2. Generating Code (`ng generate` or `ng g`)
+
+Always use the CLI to generate code to ensure it adheres to Angular standards and updates necessary configuration files automatically.
+
+| Target       | Command               | Notes                                                                                          |
+| :----------- | :-------------------- | :--------------------------------------------------------------------------------------------- |
+| Component    | `ng g c path/to/name` | Generates a component. Use `--inline-style` (`-s`) or `--inline-template` (`-t`) if requested. |
+| Service      | `ng g s path/to/name` | Generates an `@Injectable({providedIn: 'root'})` service.                                      |
+| Directive    | `ng g d path/to/name` | Generates a directive.                                                                         |
+| Pipe         | `ng g p path/to/name` | Generates a pipe.                                                                              |
+| Guard        | `ng g g path/to/name` | Generates a functional route guard.                                                            |
+| Environments | `ng g environments`   | Scaffolds `src/environments/` and updates `angular.json` with file replacements.               |
+
+_Note: There is no command to generate a single route definition. Generate a component, then manually add it to the `Routes` array in `app.routes.ts`._
+
+## 3. Development Server & Proxying
+
+Start the local development server with hot-module replacement (HMR):
+
+```bash
+ng serve
+```
+
+### Backend API Proxying
+
+To proxy API requests during development (e.g., rerouting `/api` to a local Node server):
+
+1. Create `src/proxy.conf.json`:
+   ```json
+   {
+     "/api/**": {"target": "http://localhost:3000", "secure": false}
+   }
+   ```
+2. Update `angular.json` under the `serve` target:
+   ```json
+   "serve": {
+     "builder": "@angular/build:dev-server",
+     "options": { "proxyConfig": "src/proxy.conf.json" }
+   }
+   ```
+
+## 4. Building the Application
+
+Compile the application into an output directory (default: `dist/<project-name>/browser`). Modern Angular uses the `@angular/build:application` builder (esbuild-based).
+
+```bash
+ng build
+```
+
+- `ng build` defaults to the production configuration, which enables Ahead-of-Time (AOT) compilation, minification, and tree-shaking.
+- Target specific configurations defined in `angular.json` using `--configuration`: `ng build --configuration=staging`.
+
+## 5. Testing
+
+- **Unit Tests**: Run `ng test` to execute unit tests via the configured test runner (e.g., Karma or Vitest).
+- **End-to-End (E2E)**: Run `ng e2e`. If no E2E framework is configured, the CLI will prompt to install one (Cypress, Playwright, Puppeteer, etc.).
+
+## 6. Deployment
+
+To deploy an application, you must first add a deployment builder, then run the deploy command:
+
+```bash
+# Example for Firebase
+ng add @angular/fire
+ng deploy
+```

package/.claude/skills/angular-developer/references/component-harnesses.md

@@ -0,0 +1,59 @@
+# Testing with Component Harnesses
+
+Component harnesses are the standard, preferred way to interact with components in tests. They provide a robust, user-centric API that makes tests less brittle and easier to read by insulating them from changes to a component's internal DOM structure.
+
+## Why Use Harnesses?
+
+- **Robustness:** Tests don't break when you refactor a component's internal HTML or CSS classes.
+- **Readability:** Tests describe interactions from a user's perspective (e.g., `button.click()`, `slider.getValue()`) instead of through DOM queries (`fixture.nativeElement.querySelector(...)`).
+- **Reusability:** The same harness can be used in both unit tests and E2E tests.
+
+Angular Material provides a test harness for every component in its library.
+
+## Using a Harness in a Unit Test
+
+The `TestbedHarnessEnvironment` is the entry point for using harnesses in unit tests.
+
+### Example: Testing with a `MatButtonHarness`
+
+```ts
+import {TestbedHarnessEnvironment} from '@angular/cdk/testing/testbed';
+import {MatButtonHarness} from '@angular/material/button/testing';
+import {MyButtonContainerComponent} from './my-button-container.component';
+
+describe('MyButtonContainerComponent', () => {
+  let fixture: ComponentFixture<MyButtonContainerComponent>;
+  let loader: HarnessLoader;
+
+  beforeEach(async () => {
+    await TestBed.configureTestingModule({
+      imports: [MyButtonContainerComponent, MatButtonModule],
+    }).compileComponents();
+
+    fixture = TestBed.createComponent(MyButtonContainerComponent);
+    // Create a harness loader for the component's fixture
+    loader = TestbedHarnessEnvironment.loader(fixture);
+  });
+
+  it('should find a button with specific text', async () => {
+    // Load the harness for a MatButton with the text "Submit"
+    const submitButton = await loader.getHarness(MatButtonHarness.with({text: 'Submit'}));
+
+    // Use the harness API to interact with the component
+    expect(await submitButton.isDisabled()).toBe(false);
+    await submitButton.click();
+
+    // ... assertions
+  });
+});
+```
+
+### Key Concepts
+
+1.  **`HarnessLoader`**: An object used to find and create harness instances. Get a loader for your component's fixture using `TestbedHarnessEnvironment.loader(fixture)`.
+
+2.  **`loader.getHarness(HarnessClass)`**: Asynchronously finds and returns a harness instance for the first matching component.
+
+3.  **`HarnessClass.with({ ... })`**: Many harnesses provide a static `with` method that returns a `HarnessPredicate`. This allows you to filter and find components based on their properties, like text, selector, or disabled state. Always use this to precisely target the component you want to test.
+
+4.  **Harness API:** Once you have a harness instance, use its methods (e.g., `.click()`, `.getText()`, `.getValue()`) to interact with the component. These methods automatically handle waiting for async operations and change detection.

package/.claude/skills/angular-developer/references/component-styling.md

@@ -0,0 +1,91 @@
+# Component Styling
+
+Angular components can define styles that apply specifically to their template, enabling encapsulation and modularity.
+
+## Defining Styles
+
+Styles can be defined inline or in separate files.
+
+```ts
+@Component({
+  selector: 'app-photo',
+  // Inline styles
+  styles: `
+    img {
+      border-radius: 50%;
+    }
+  `,
+  // OR external file
+  styleUrl: 'photo.component.css',
+})
+export class Photo {}
+```
+
+## View Encapsulation
+
+Every component has a view encapsulation setting that determines how styles are scoped.
+
+| Mode                            | Behavior                                                                                      |
+| :------------------------------ | :-------------------------------------------------------------------------------------------- |
+| `Emulated` (Default)            | Scopes styles to the component using unique HTML attributes. Global styles can still leak in. |
+| `ShadowDom`                     | Uses the browser's native Shadow DOM API to isolate styles completely.                        |
+| `None`                          | Disables encapsulation. Component styles become global.                                       |
+| `ExperimentalIsolatedShadowDom` | Strictly guarantees that only the component's styles apply.                                   |
+
+### Usage
+
+```ts
+import { ViewEncapsulation } from '@angular/core';
+
+@Component({
+  ...,
+  encapsulation: ViewEncapsulation.None,
+})
+export class GlobalStyled {}
+```
+
+## Special Selectors
+
+### `:host`
+
+Targets the component's host element (the element matching the component's selector).
+
+```css
+:host {
+  display: block;
+  border: 1px solid black;
+}
+```
+
+### `:host-context()`
+
+Targets the host element based on some condition in its ancestry.
+
+```css
+/* Apply styles if any ancestor has the 'theme-dark' class */
+:host-context(.theme-dark) {
+  background-color: #333;
+}
+```
+
+### `::ng-deep`
+
+Disables view encapsulation for a specific rule, allowing it to "leak" into child components.
+**Note: The Angular team strongly discourages the use of `::ng-deep`.** It is supported only for backwards compatibility.
+
+## Styles in Templates
+
+You can use `<style>` elements directly in a component's template. View encapsulation rules still apply.
+
+```html
+<style>
+  .dynamic-class {
+    color: red;
+  }
+</style>
+<div class="dynamic-class">Hello</div>
+```
+
+## External Styles
+
+Using `<link>` or `@import` in CSS is treated as external styles. **External styles are not affected by emulated view encapsulation.**

package/.claude/skills/angular-developer/references/components.md

@@ -0,0 +1,117 @@
+# Components
+
+Angular components are the fundamental building blocks of an application. Each component consists of a TypeScript class with behaviors, an HTML template, and a CSS selector.
+
+## Component Definition
+
+Use the `@Component` decorator to define a component's metadata.
+
+```ts
+@Component({
+  selector: 'app-profile',
+  template: `
+    <img src="profile.jpg" alt="Profile photo" />
+    <button (click)="save()">Save</button>
+  `,
+  styles: `
+    img {
+      border-radius: 50%;
+    }
+  `,
+})
+export class Profile {
+  save() {
+    /* ... */
+  }
+}
+```
+
+## Metadata Options
+
+- `selector`: The CSS selector that identifies this component in templates.
+- `template`: Inline HTML template (preferred for small templates).
+- `templateUrl`: Path to an external HTML file.
+- `styles`: Inline CSS styles.
+- `styleUrl` / `styleUrls`: Path(s) to external CSS file(s).
+- `imports`: Lists the components, directives, or pipes used in this component's template.
+
+## Using Components
+
+To use a component, add it to the `imports` array of the consuming component and use its selector in the template.
+
+```ts
+@Component({
+  selector: 'app-root',
+  imports: [Profile],
+  template: `<app-profile />`,
+})
+export class App {}
+```
+
+## Template Control Flow
+
+Angular uses built-in blocks for conditional rendering and loops.
+
+### Conditional Rendering (`@if`)
+
+Use `@if` to conditionally show content. You can include `@else if` and `@else` blocks.
+
+```html
+@if (user.isAdmin) {
+<admin-dashboard />
+} @else if (user.isModerator) {
+<mod-dashboard />
+} @else {
+<standard-dashboard />
+}
+```
+
+**Result aliasing**: Save the result of the expression for reuse.
+
+```html
+@if (user.settings(); as settings) {
+<p>Theme: {{ settings.theme }}</p>
+}
+```
+
+### Loops (`@for`)
+
+The `@for` block iterates over collections. The `track` expression is **required** for performance and DOM reuse.
+
+```html
+<ul>
+  @for (item of items(); track item.id; let i = $index, total = $count) {
+  <li>{{ i + 1 }}/{{ total }}: {{ item.name }}</li>
+  } @empty {
+  <li>No items to display.</li>
+  }
+</ul>
+```
+
+**Implicit Variables**: `$index`, `$count`, `$first`, `$last`, `$even`, `$odd`.
+
+### Switching Content (`@switch`)
+
+The `@switch` block renders content based on a value. It uses strict equality (`===`) and has **no fallthrough**.
+
+```html
+@switch (status()) { @case ('loading') { <app-spinner /> } @case ('error') { <app-error-msg /> }
+@case ('success') { <app-data-grid /> } @default {
+<p>Unknown status</p>
+} }
+```
+
+**Exhaustive Type Checking**: Use `@default never;` to ensure all cases of a union type are handled.
+
+```html
+@switch (state) { @case ('on') { ... } @case ('off') { ... } @default never; // Errors if a new
+state like 'standby' is added }
+```
+
+## Core Concepts
+
+- **Host Element**: The DOM element that matches the component's selector.
+- **View**: The DOM rendered by the component's template inside the host element.
+- **Standalone**: By default, components are standalone (since Angular 19, `standalone: true` is default). For older versions, `standalone: true` must be explicit or the component must be part of an `NgModule`.
+- **Component Tree**: Angular applications are structured as a tree of components, where each component can host child components.
+- **Component Naming**: Do not add suffixes the `Component` suffix for Component classes (e.g., AppComponent) unless the project has been configured to use that naming configuration.

package/.claude/skills/angular-developer/references/creating-services.md

@@ -0,0 +1,97 @@
+# Creating and Using Services
+
+Services in Angular are reusable pieces of code that handle data fetching, business logic, or state management that multiple components or other services need to access.
+
+## Creating a Service
+
+You can generate a service using the Angular CLI:
+
+```bash
+ng generate service my-data
+```
+
+Or you can manually create a TypeScript class and decorate it with `@Injectable()`.
+
+```ts
+import {Injectable} from '@angular/core';
+
+@Injectable({
+  providedIn: 'root',
+})
+export class BasicDataStore {
+  private data: string[] = [];
+
+  addData(item: string): void {
+    this.data.push(item);
+  }
+
+  getData(): string[] {
+    return [...this.data];
+  }
+}
+```
+
+### The `providedIn: 'root'` Option
+
+Using `providedIn: 'root'` is the recommended approach for most services. It tells Angular to:
+
+- **Create a single instance (singleton)** for the entire application.
+- **Make it available everywhere** automatically, without needing to list it in any `providers` array.
+- **Enable tree-shaking**, meaning the service is only included in the final JavaScript bundle if it is actually injected somewhere.
+
+## Injecting a Service
+
+Once a service is created, you can inject it into components, directives, or other services using the `inject()` function.
+
+### Injecting into a Component
+
+```ts
+import {Component, inject} from '@angular/core';
+import {BasicDataStore} from './basic-data-store.service';
+
+@Component({
+  selector: 'app-example',
+  template: `
+    <div>
+      <p>Data items: {{ dataStore.getData().length }}</p>
+      <button (click)="dataStore.addData('New Item')">Add Item</button>
+    </div>
+  `,
+})
+export class Example {
+  // Inject the service as a class field
+  dataStore = inject(BasicDataStore);
+}
+```
+
+### Injecting into Another Service
+
+Services can inject other services in the exact same way.
+
+```ts
+import {Injectable, inject} from '@angular/core';
+import {AdvancedDataStore} from './advanced-data-store.service';
+
+@Injectable({
+  providedIn: 'root',
+})
+export class BasicDataStore {
+  // Injecting another service
+  private advancedDataStore = inject(AdvancedDataStore);
+
+  private data: string[] = [];
+
+  getData(): string[] {
+    // Combine data from this service and the injected service
+    return [...this.data, ...this.advancedDataStore.getData()];
+  }
+}
+```
+
+## Advanced Service Patterns
+
+While `providedIn: 'root'` covers most scenarios, you may sometimes need:
+
+- **Component-specific instances**: If a component needs its own isolated instance of a service, provide it directly in the component's `@Component({ providers: [MyService] })` array.
+- **Factory providers**: For dynamic creation.
+- **Value providers**: For injecting configuration objects.

package/.claude/skills/angular-developer/references/data-resolvers.md

@@ -0,0 +1,69 @@
+# Data Resolvers
+
+Data resolvers fetch data before a route activates, ensuring components have the necessary data upon rendering.
+
+## Creating a Resolver
+
+Implement the `ResolveFn` type.
+
+```ts
+export const userResolver: ResolveFn<User> = (route, state) => {
+  const userService = inject(UserService);
+  const id = route.paramMap.get('id')!;
+  return userService.getUser(id);
+};
+```
+
+## Configuring the Route
+
+Add the resolver under the `resolve` key.
+
+```ts
+{
+  path: 'user/:id',
+  component: UserProfile,
+  resolve: {
+    user: userResolver
+  }
+}
+```
+
+## Accessing Resolved Data
+
+### 1. Via `ActivatedRoute` (Traditional)
+
+```ts
+private route = inject(ActivatedRoute);
+data = toSignal(this.route.data);
+user = computed(() => this.data().user);
+```
+
+### 2. Via Component Inputs (Modern)
+
+Enable `withComponentInputBinding()` in `provideRouter` to pass resolved data directly to `@Input` or `input()`.
+
+```ts
+// app.config.ts
+provideRouter(routes, withComponentInputBinding());
+
+// component.ts
+user = input.required<User>();
+```
+
+## Error Handling
+
+Navigation is blocked if a resolver fails.
+
+- Use `withNavigationErrorHandler` for global handling.
+- Use `catchError` within the resolver to return a `RedirectCommand` or fallback data.
+
+```ts
+return userService
+  .get(id)
+  .pipe(catchError(() => of(new RedirectCommand(router.parseUrl('/error')))));
+```
+
+## Best Practices
+
+- **Keep it lightweight**: Fetch only critical data.
+- **Provide feedback**: Listen to router events to show a global loading bar during navigation, as the UI stays on the old page until the resolver finishes.

package/.claude/skills/angular-developer/references/define-routes.md

@@ -0,0 +1,67 @@
+# Define Routes
+
+Routes are objects that define which component should render for a specific URL path.
+
+## Basic Configuration
+
+Define routes in a `Routes` array and provide them using `provideRouter` in your `appConfig`.
+
+```ts
+// app.routes.ts
+export const routes: Routes = [
+  {path: '', component: HomePage},
+  {path: 'admin', component: AdminPage},
+];
+
+// app.config.ts
+export const appConfig: ApplicationConfig = {
+  providers: [provideRouter(routes)],
+};
+```
+
+## URL Paths
+
+- **Static**: Matches an exact string (e.g., `'admin'`).
+- **Route Parameters**: Dynamic segments prefixed with a colon (e.g., `'user/:id'`).
+- **Wildcard**: Matches any URL using `**`. Useful for "Not Found" pages. **Always place at the end of the array.**
+
+## Matching Strategy
+
+Angular uses a **first-match wins** strategy. Specific routes must come before less specific ones.
+
+## Redirects
+
+Use `redirectTo` to point one path to another.
+
+```ts
+{ path: 'articles', redirectTo: '/blog' },
+{ path: 'blog', component: Blog },
+```
+
+## Page Titles
+
+Associate titles with routes for accessibility. Titles can be static or dynamic (via `ResolveFn` or a custom `TitleStrategy`).
+
+```ts
+{ path: 'home', component: Home, title: 'Home Page' }
+```
+
+## Route Data and Providers
+
+- **Static Data**: Attach metadata using the `data` property.
+- **Route Providers**: Scope dependencies to a specific route and its children using the `providers` array.
+
+## Nested (Child) Routes
+
+Define sub-views using the `children` property. Parent components must include a `<router-outlet />`.
+
+```ts
+{
+  path: 'product/:id',
+  component: Product,
+  children: [
+    { path: 'info', component: ProductInfo },
+    { path: 'reviews', component: ProductReviews },
+  ],
+}
+```

package/.claude/skills/angular-developer/references/defining-providers.md

@@ -0,0 +1,72 @@
+# Defining Dependency Providers
+
+Angular offers automatic and manual ways to provide dependencies to its Dependency Injection (DI) system.
+
+## Automatic Provision
+
+The most common way to provide a service is using `providedIn: 'root'` on an `@Injectable()`.
+
+### InjectionToken
+
+Use `InjectionToken` for non-class dependencies (configuration objects, functions, primitives). An `InjectionToken` can also be automatically provided.
+
+```ts
+import {InjectionToken} from '@angular/core';
+
+export interface AppConfig {
+  apiUrl: string;
+}
+
+export const APP_CONFIG = new InjectionToken<AppConfig>('app.config', {
+  providedIn: 'root',
+  factory: () => ({apiUrl: 'https://api.example.com'}),
+});
+```
+
+## Manual Provision
+
+You use the `providers` array when a service lacks `providedIn`, when you want a new instance for a specific component, or when configuring runtime values.
+
+```ts
+@Component({
+  providers: [
+    // Shorthand for { provide: LocalService, useClass: LocalService }
+    LocalService,
+
+    // useClass: Swap implementations
+    {provide: Logger, useClass: BetterLogger},
+
+    // useValue: Provide static values
+    {provide: API_URL_TOKEN, useValue: 'https://api.example.com'},
+
+    // useFactory: Generate value dynamically
+    {
+      provide: ApiClient,
+      useFactory: (http = inject(HttpClient)) => new ApiClient(http),
+    },
+
+    // useExisting: Create an alias
+    {provide: OldLogger, useExisting: NewLogger},
+
+    // multi: Provide multiple values for the same token as an array
+    {provide: INTERCEPTOR_TOKEN, useClass: AuthInterceptor, multi: true},
+  ],
+})
+export class Example {}
+```
+
+## Scopes of Providers
+
+- **Application Bootstrap**: Global singletons. Use for HTTP clients, logging, or app-wide config.
+- **Component/Directive**: Isolated instances. Use for component-specific state or forms. Services are destroyed when the component is destroyed.
+- **Route**: Feature-specific services loaded only with specific routes.
+
+## Library Pattern: `provide*` functions
+
+Library authors should export functions that return provider arrays to encapsulate configuration:
+
+```ts
+export function provideAnalytics(config: AnalyticsConfig): Provider[] {
+  return [{provide: ANALYTICS_CONFIG, useValue: config}, AnalyticsService];
+}
+```