theus-cli-darwin-x64 0.2.84

package/vendor/theus-arsenal/skills/patrones-angular/references/component-harnesses.md

@@ -0,0 +1,59 @@
+# Testing con harnesses de componentes
+
+Los harnesses de componentes son la forma estándar y preferida de interactuar con componentes en las pruebas. Proveen una API robusta y centrada en el usuario que hace las pruebas menos frágiles y más legibles, aislándolas de los cambios en la estructura DOM interna del componente.
+
+## ¿Por qué usar harnesses?
+
+- **Robustez:** las pruebas no se rompen cuando refactorizas el HTML interno o las clases CSS de un componente.
+- **Legibilidad:** las pruebas describen interacciones desde la perspectiva del usuario (p. ej., `button.click()`, `slider.getValue()`) en lugar de consultas al DOM (`fixture.nativeElement.querySelector(...)`).
+- **Reutilización:** el mismo harness puede usarse tanto en pruebas unitarias como E2E.
+
+Angular Material provee un harness de pruebas para cada componente de su librería.
+
+## Usar un harness en una prueba unitaria
+
+El `TestbedHarnessEnvironment` es el punto de entrada para usar harnesses en pruebas unitarias.
+
+### Ejemplo: probar con un `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);
+    // Crea un loader de harnesses para el fixture del componente
+    loader = TestbedHarnessEnvironment.loader(fixture);
+  });
+
+  it('debería encontrar un botón con un texto específico', async () => {
+    // Carga el harness de un MatButton con el texto "Submit"
+    const submitButton = await loader.getHarness(MatButtonHarness.with({text: 'Submit'}));
+
+    // Usa la API del harness para interactuar con el componente
+    expect(await submitButton.isDisabled()).toBe(false);
+    await submitButton.click();
+
+    // ... verificaciones
+  });
+});
+```
+
+### Conceptos clave
+
+1. **`HarnessLoader`**: objeto usado para encontrar y crear instancias de harnesses. Obtén un loader para el fixture de tu componente con `TestbedHarnessEnvironment.loader(fixture)`.
+
+2. **`loader.getHarness(HarnessClass)`**: encuentra y devuelve de forma asíncrona una instancia del harness para el primer componente que coincida.
+
+3. **`HarnessClass.with({ ... })`**: muchos harnesses proveen un método estático `with` que devuelve un `HarnessPredicate`. Esto permite filtrar y encontrar componentes por sus propiedades, como texto, selector o estado deshabilitado. Úsalo siempre para apuntar con precisión al componente que quieres probar.
+
+4. **API del harness:** una vez que tienes una instancia del harness, usa sus métodos (p. ej., `.click()`, `.getText()`, `.getValue()`) para interactuar con el componente. Estos métodos gestionan automáticamente la espera de operaciones asíncronas y la detección de cambios.

package/vendor/theus-arsenal/skills/patrones-angular/references/component-styling.md

@@ -0,0 +1,91 @@
+# Estilos de componentes
+
+Los componentes de Angular pueden definir estilos que aplican específicamente a su plantilla, lo que permite encapsulación y modularidad.
+
+## Definir estilos
+
+Los estilos pueden definirse inline o en archivos separados.
+
+```ts
+@Component({
+  selector: 'app-photo',
+  // Estilos inline
+  styles: `
+    img {
+      border-radius: 50%;
+    }
+  `,
+  // O archivo externo
+  styleUrl: 'photo.component.css',
+})
+export class Photo {}
+```
+
+## Encapsulación de vistas
+
+Cada componente tiene una configuración de encapsulación de vista que determina cómo se acotan los estilos.
+
+| Modo                            | Comportamiento                                                                                              |
+| :------------------------------ | :----------------------------------------------------------------------------------------------------------- |
+| `Emulated` (por defecto)        | Acota los estilos al componente mediante atributos HTML únicos. Los estilos globales aún pueden filtrarse.  |
+| `ShadowDom`                     | Usa la API nativa de Shadow DOM del navegador para aislar los estilos por completo.                          |
+| `None`                          | Desactiva la encapsulación. Los estilos del componente se vuelven globales.                                   |
+| `ExperimentalIsolatedShadowDom` | Garantiza estrictamente que solo apliquen los estilos del componente.                                         |
+
+### Uso
+
+```ts
+import { ViewEncapsulation } from '@angular/core';
+
+@Component({
+  ...,
+  encapsulation: ViewEncapsulation.None,
+})
+export class GlobalStyled {}
+```
+
+## Selectores especiales
+
+### `:host`
+
+Apunta al elemento host del componente (el elemento que coincide con el selector del componente).
+
+```css
+:host {
+  display: block;
+  border: 1px solid black;
+}
+```
+
+### `:host-context()`
+
+Apunta al elemento host según alguna condición en sus ancestros.
+
+```css
+/* Aplica los estilos si algún ancestro tiene la clase 'theme-dark' */
+:host-context(.theme-dark) {
+  background-color: #333;
+}
+```
+
+### `::ng-deep`
+
+Desactiva la encapsulación de vista para una regla específica, permitiendo que se "filtre" a los componentes hijos.
+**Nota: el equipo de Angular desaconseja firmemente el uso de `::ng-deep`.** Se soporta solo por compatibilidad hacia atrás.
+
+## Estilos en plantillas
+
+Puedes usar elementos `<style>` directamente en la plantilla de un componente. Las reglas de encapsulación de vista siguen aplicando.
+
+```html
+<style>
+  .dynamic-class {
+    color: red;
+  }
+</style>
+<div class="dynamic-class">Hola</div>
+```
+
+## Estilos externos
+
+Usar `<link>` o `@import` en CSS se trata como estilos externos. **Los estilos externos no se ven afectados por la encapsulación de vista emulada.**

package/vendor/theus-arsenal/skills/patrones-angular/references/components.md

@@ -0,0 +1,117 @@
+# Componentes
+
+Los componentes de Angular son los bloques fundamentales de una aplicación. Cada componente consiste en una clase TypeScript con comportamientos, una plantilla HTML y un selector CSS.
+
+## Definición de un componente
+
+Usa el decorador `@Component` para definir los metadatos del componente.
+
+```ts
+@Component({
+  selector: 'app-profile',
+  template: `
+    <img src="profile.jpg" alt="Foto de perfil" />
+    <button (click)="save()">Guardar</button>
+  `,
+  styles: `
+    img {
+      border-radius: 50%;
+    }
+  `,
+})
+export class Profile {
+  save() {
+    /* ... */
+  }
+}
+```
+
+## Opciones de metadatos
+
+- `selector`: el selector CSS que identifica este componente en las plantillas.
+- `template`: plantilla HTML inline (preferida para plantillas pequeñas).
+- `templateUrl`: ruta a un archivo HTML externo.
+- `styles`: estilos CSS inline.
+- `styleUrl` / `styleUrls`: ruta(s) a archivo(s) CSS externo(s).
+- `imports`: lista los componentes, directivas o pipes usados en la plantilla de este componente.
+
+## Usar componentes
+
+Para usar un componente, añádelo al array `imports` del componente consumidor y usa su selector en la plantilla.
+
+```ts
+@Component({
+  selector: 'app-root',
+  imports: [Profile],
+  template: `<app-profile />`,
+})
+export class App {}
+```
+
+## Control de flujo en plantillas
+
+Angular usa bloques integrados para renderizado condicional y bucles.
+
+### Renderizado condicional (`@if`)
+
+Usa `@if` para mostrar contenido condicionalmente. Puedes incluir bloques `@else if` y `@else`.
+
+```html
+@if (user.isAdmin) {
+<admin-dashboard />
+} @else if (user.isModerator) {
+<mod-dashboard />
+} @else {
+<standard-dashboard />
+}
+```
+
+**Alias del resultado**: guarda el resultado de la expresión para reutilizarlo.
+
+```html
+@if (user.settings(); as settings) {
+<p>Tema: {{ settings.theme }}</p>
+}
+```
+
+### Bucles (`@for`)
+
+El bloque `@for` itera sobre colecciones. La expresión `track` es **obligatoria** por rendimiento y reutilización del DOM.
+
+```html
+<ul>
+  @for (item of items(); track item.id; let i = $index, total = $count) {
+  <li>{{ i + 1 }}/{{ total }}: {{ item.name }}</li>
+  } @empty {
+  <li>No hay elementos que mostrar.</li>
+  }
+</ul>
+```
+
+**Variables implícitas**: `$index`, `$count`, `$first`, `$last`, `$even`, `$odd`.
+
+### Contenido alternativo (`@switch`)
+
+El bloque `@switch` renderiza contenido según un valor. Usa igualdad estricta (`===`) y **no tiene fallthrough**.
+
+```html
+@switch (status()) { @case ('loading') { <app-spinner /> } @case ('error') { <app-error-msg /> }
+@case ('success') { <app-data-grid /> } @default {
+<p>Estado desconocido</p>
+} }
+```
+
+**Comprobación exhaustiva de tipos**: usa `@default never;` para asegurar que se manejan todos los casos de un tipo unión.
+
+```html
+@switch (state) { @case ('on') { ... } @case ('off') { ... } @default never; // Falla si se añade
+un estado nuevo como 'standby' }
+```
+
+## Conceptos base
+
+- **Elemento host**: el elemento del DOM que coincide con el selector del componente.
+- **Vista**: el DOM renderizado por la plantilla del componente dentro del elemento host.
+- **Standalone**: por defecto, los componentes son standalone (desde Angular 19, `standalone: true` es el valor por defecto). En versiones anteriores, `standalone: true` debe ser explícito o el componente debe formar parte de un `NgModule`.
+- **Árbol de componentes**: las aplicaciones Angular se estructuran como un árbol de componentes, donde cada componente puede alojar componentes hijos.
+- **Nomenclatura de componentes**: no añadas el sufijo `Component` a las clases de componentes (p. ej., AppComponent) salvo que el proyecto esté configurado para usar esa convención.

package/vendor/theus-arsenal/skills/patrones-angular/references/creating-services.md

@@ -0,0 +1,97 @@
+# Crear y usar servicios
+
+Los servicios en Angular son piezas de código reutilizables que gestionan carga de datos, lógica de negocio o gestión de estado a las que necesitan acceder múltiples componentes u otros servicios.
+
+## Crear un servicio
+
+Puedes generar un servicio con la CLI de Angular:
+
+```bash
+ng generate service my-data
+```
+
+O puedes crear manualmente una clase TypeScript y decorarla con `@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];
+  }
+}
+```
+
+### La opción `providedIn: 'root'`
+
+Usar `providedIn: 'root'` es el enfoque recomendado para la mayoría de los servicios. Le indica a Angular que debe:
+
+- **Crear una única instancia (singleton)** para toda la aplicación.
+- **Ponerla disponible en todas partes** automáticamente, sin necesidad de listarla en ningún array `providers`.
+- **Habilitar tree-shaking**, es decir, el servicio solo se incluye en el bundle JavaScript final si realmente se inyecta en algún sitio.
+
+## Inyectar un servicio
+
+Una vez creado el servicio, puedes inyectarlo en componentes, directivas u otros servicios con la función `inject()`.
+
+### Inyectar en un componente
+
+```ts
+import {Component, inject} from '@angular/core';
+import {BasicDataStore} from './basic-data-store.service';
+
+@Component({
+  selector: 'app-example',
+  template: `
+    <div>
+      <p>Elementos de datos: {{ dataStore.getData().length }}</p>
+      <button (click)="dataStore.addData('Nuevo elemento')">Añadir elemento</button>
+    </div>
+  `,
+})
+export class Example {
+  // Inyecta el servicio como campo de clase
+  dataStore = inject(BasicDataStore);
+}
+```
+
+### Inyectar en otro servicio
+
+Los servicios pueden inyectar otros servicios exactamente de la misma manera.
+
+```ts
+import {Injectable, inject} from '@angular/core';
+import {AdvancedDataStore} from './advanced-data-store.service';
+
+@Injectable({
+  providedIn: 'root',
+})
+export class BasicDataStore {
+  // Inyección de otro servicio
+  private advancedDataStore = inject(AdvancedDataStore);
+
+  private data: string[] = [];
+
+  getData(): string[] {
+    // Combina los datos de este servicio y del servicio inyectado
+    return [...this.data, ...this.advancedDataStore.getData()];
+  }
+}
+```
+
+## Patrones avanzados de servicios
+
+Aunque `providedIn: 'root'` cubre la mayoría de los escenarios, a veces puedes necesitar:
+
+- **Instancias específicas por componente**: si un componente necesita su propia instancia aislada de un servicio, provéelo directamente en el array `@Component({ providers: [MyService] })` del componente.
+- **Providers de fábrica**: para creación dinámica.
+- **Providers de valor**: para inyectar objetos de configuración.

package/vendor/theus-arsenal/skills/patrones-angular/references/data-resolvers.md

@@ -0,0 +1,69 @@
+# Resolvers de datos
+
+Los resolvers de datos obtienen datos antes de que una ruta se active, asegurando que los componentes tengan los datos necesarios al renderizarse.
+
+## Crear un resolver
+
+Implementa el tipo `ResolveFn`.
+
+```ts
+export const userResolver: ResolveFn<User> = (route, state) => {
+  const userService = inject(UserService);
+  const id = route.paramMap.get('id')!;
+  return userService.getUser(id);
+};
+```
+
+## Configurar la ruta
+
+Añade el resolver bajo la clave `resolve`.
+
+```ts
+{
+  path: 'user/:id',
+  component: UserProfile,
+  resolve: {
+    user: userResolver
+  }
+}
+```
+
+## Acceder a los datos resueltos
+
+### 1. Vía `ActivatedRoute` (tradicional)
+
+```ts
+private route = inject(ActivatedRoute);
+data = toSignal(this.route.data);
+user = computed(() => this.data().user);
+```
+
+### 2. Vía inputs del componente (moderno)
+
+Habilita `withComponentInputBinding()` en `provideRouter` para pasar los datos resueltos directamente a `@Input` o `input()`.
+
+```ts
+// app.config.ts
+provideRouter(routes, withComponentInputBinding());
+
+// component.ts
+user = input.required<User>();
+```
+
+## Manejo de errores
+
+La navegación se bloquea si un resolver falla.
+
+- Usa `withNavigationErrorHandler` para el manejo global.
+- Usa `catchError` dentro del resolver para devolver un `RedirectCommand` o datos de reserva.
+
+```ts
+return userService
+  .get(id)
+  .pipe(catchError(() => of(new RedirectCommand(router.parseUrl('/error')))));
+```
+
+## Buenas prácticas
+
+- **Mantenlo ligero**: obtén solo los datos críticos.
+- **Da retroalimentación**: escucha los eventos del router para mostrar una barra de carga global durante la navegación, ya que la UI permanece en la página anterior hasta que el resolver termina.

package/vendor/theus-arsenal/skills/patrones-angular/references/define-routes.md

@@ -0,0 +1,67 @@
+# Definir rutas
+
+Las rutas son objetos que definen qué componente debe renderizarse para una ruta URL específica.
+
+## Configuración básica
+
+Define las rutas en un array `Routes` y provéelas usando `provideRouter` en tu `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)],
+};
+```
+
+## Rutas URL
+
+- **Estáticas**: coinciden con una cadena exacta (p. ej., `'admin'`).
+- **Parámetros de ruta**: segmentos dinámicos con prefijo de dos puntos (p. ej., `'user/:id'`).
+- **Comodín**: coincide con cualquier URL usando `**`. Útil para páginas "No encontrado". **Colócala siempre al final del array.**
+
+## Estrategia de coincidencia
+
+Angular usa una estrategia de **primera coincidencia gana**. Las rutas específicas deben ir antes que las menos específicas.
+
+## Redirecciones
+
+Usa `redirectTo` para apuntar una ruta a otra.
+
+```ts
+{ path: 'articles', redirectTo: '/blog' },
+{ path: 'blog', component: Blog },
+```
+
+## Títulos de página
+
+Asocia títulos a las rutas por accesibilidad. Los títulos pueden ser estáticos o dinámicos (vía `ResolveFn` o una `TitleStrategy` personalizada).
+
+```ts
+{ path: 'home', component: Home, title: 'Página de inicio' }
+```
+
+## Datos y providers de ruta
+
+- **Datos estáticos**: adjunta metadatos con la propiedad `data`.
+- **Providers de ruta**: acota dependencias a una ruta específica y sus hijas con el array `providers`.
+
+## Rutas anidadas (hijas)
+
+Define subvistas con la propiedad `children`. Los componentes padre deben incluir un `<router-outlet />`.
+
+```ts
+{
+  path: 'product/:id',
+  component: Product,
+  children: [
+    { path: 'info', component: ProductInfo },
+    { path: 'reviews', component: ProductReviews },
+  ],
+}
+```

package/vendor/theus-arsenal/skills/patrones-angular/references/defining-providers.md

@@ -0,0 +1,72 @@
+# Definir proveedores de dependencias
+
+Angular ofrece formas automáticas y manuales de proveer dependencias a su sistema de inyección de dependencias (DI).
+
+## Provisión automática
+
+La forma más común de proveer un servicio es usando `providedIn: 'root'` en un `@Injectable()`.
+
+### InjectionToken
+
+Usa `InjectionToken` para dependencias que no son clases (objetos de configuración, funciones, primitivos). Un `InjectionToken` también puede proveerse automáticamente.
+
+```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'}),
+});
+```
+
+## Provisión manual
+
+Usa el array `providers` cuando un servicio no tiene `providedIn`, cuando quieres una instancia nueva para un componente específico, o al configurar valores en tiempo de ejecución.
+
+```ts
+@Component({
+  providers: [
+    // Abreviatura de { provide: LocalService, useClass: LocalService }
+    LocalService,
+
+    // useClass: intercambiar implementaciones
+    {provide: Logger, useClass: BetterLogger},
+
+    // useValue: proveer valores estáticos
+    {provide: API_URL_TOKEN, useValue: 'https://api.example.com'},
+
+    // useFactory: generar el valor dinámicamente
+    {
+      provide: ApiClient,
+      useFactory: (http = inject(HttpClient)) => new ApiClient(http),
+    },
+
+    // useExisting: crear un alias
+    {provide: OldLogger, useExisting: NewLogger},
+
+    // multi: proveer múltiples valores para el mismo token como un array
+    {provide: INTERCEPTOR_TOKEN, useClass: AuthInterceptor, multi: true},
+  ],
+})
+export class Example {}
+```
+
+## Ámbitos de los providers
+
+- **Bootstrap de la aplicación**: singletons globales. Úsalos para clientes HTTP, logging o configuración global de la app.
+- **Componente/Directiva**: instancias aisladas. Úsalas para estado o formularios específicos del componente. Los servicios se destruyen cuando el componente se destruye.
+- **Ruta**: servicios específicos de una funcionalidad, cargados solo con ciertas rutas.
+
+## Patrón de librería: funciones `provide*`
+
+Los autores de librerías deben exportar funciones que devuelvan arrays de providers para encapsular la configuración:
+
+```ts
+export function provideAnalytics(config: AnalyticsConfig): Provider[] {
+  return [{provide: ANALYTICS_CONFIG, useValue: config}, AnalyticsService];
+}
+```

package/vendor/theus-arsenal/skills/patrones-angular/references/di-fundamentals.md

@@ -0,0 +1,120 @@
+# Fundamentos de inyección de dependencias (DI)
+
+La inyección de dependencias (DI) es un patrón de diseño que sirve para organizar y compartir código a lo largo de una aplicación, permitiéndote "inyectar" funcionalidades en distintas partes. Esto mejora la mantenibilidad, escalabilidad y testeabilidad del código.
+
+## Cómo funciona la DI en Angular
+
+Hay dos formas principales en que el código interactúa con el sistema de DI de Angular:
+
+1. **Proveer**: poner valores (objetos, funciones, primitivos) a disposición del sistema de DI.
+2. **Inyectar**: pedirle al sistema de DI esos valores.
+
+Los componentes, directivas y servicios de Angular participan automáticamente en la DI.
+
+## Servicios
+
+Un **servicio** es la forma más común de compartir datos y funcionalidad en una aplicación. Es una clase TypeScript decorada con `@Injectable()`.
+
+### Crear un servicio
+
+Usa la opción `providedIn: 'root'` en el decorador `@Injectable` para hacer del servicio un singleton disponible en toda la aplicación. Es el enfoque recomendado para la mayoría de los servicios.
+
+```ts
+import {Injectable} from '@angular/core';
+
+@Injectable({
+  providedIn: 'root', // Lo convierte en un singleton disponible en todas partes
+})
+export class AnalyticsLogger {
+  trackEvent(category: string, value: string) {
+    console.log('Evento de analítica registrado:', {category, value});
+  }
+}
+```
+
+Usos comunes de los servicios:
+
+- Clientes de datos (llamadas a API)
+- Gestión de estado
+- Autenticación y autorización
+- Logging y manejo de errores
+- Funciones de utilidad
+
+## Inyectar dependencias
+
+Usa la función `inject()` de Angular para solicitar dependencias.
+
+### La función `inject()`
+
+Puedes usar la función `inject()` para obtener una instancia de un servicio (o de cualquier otro token provisto).
+
+```ts
+import {Component, inject} from '@angular/core';
+import {Router} from '@angular/router';
+import {AnalyticsLogger} from './analytics-logger.service';
+
+@Component({
+  selector: 'app-navbar',
+  template: `<a href="#" (click)="navigateToDetail($event)">Página de detalle</a>`,
+})
+export class Navbar {
+  // Inyección de dependencias mediante inicializadores de campos de clase
+  private router = inject(Router);
+  private analytics = inject(AnalyticsLogger);
+
+  navigateToDetail(event: Event) {
+    event.preventDefault();
+    this.analytics.trackEvent('navigation', '/details');
+    this.router.navigate(['/details']);
+  }
+}
+```
+
+### ¿Dónde puede usarse `inject()`? (Contexto de inyección)
+
+Puedes llamar a `inject()` en un **contexto de inyección**. Los contextos de inyección más comunes ocurren durante la construcción de un componente, directiva o servicio.
+
+Lugares válidos para llamar a `inject()`:
+
+1. **Inicializadores de campos de clase** (recomendado)
+2. **Cuerpo del constructor**
+3. **Guards de ruta y resolvers** (se ejecutan en un contexto de inyección)
+4. **Funciones de fábrica** usadas en providers
+
+```typescript
+import {Component, Directive, Injectable, inject, ElementRef} from '@angular/core';
+import {HttpClient} from '@angular/common/http';
+
+// 1. En un componente (inicializador de campo y constructor)
+@Component({
+  /*...*/
+})
+export class Example {
+  private service1 = inject(MyService); // Inicializador de campo válido
+
+  private service2: MyService;
+  constructor() {
+    this.service2 = inject(MyService); // Cuerpo de constructor válido
+  }
+}
+
+// 2. En una directiva
+@Directive({
+  /*...*/
+})
+export class MyDirective {
+  private element = inject(ElementRef); // Inicializador de campo válido
+}
+
+// 3. En un servicio
+@Injectable({providedIn: 'root'})
+export class MyService {
+  private http = inject(HttpClient); // Inicializador de campo válido
+}
+
+// 4. En un guard de ruta (funcional)
+export const authGuard = () => {
+  const auth = inject(AuthService); // Guard de ruta válido
+  return auth.isAuthenticated();
+};
+```