theus-cli 0.2.83 → 0.2.84

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

@@ -1,59 +0,0 @@
-# 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

@@ -1,91 +0,0 @@
-# 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

@@ -1,117 +0,0 @@
-# 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

@@ -1,97 +0,0 @@
-# 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

@@ -1,69 +0,0 @@
-# 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

@@ -1,67 +0,0 @@
-# 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

@@ -1,72 +0,0 @@
-# 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

@@ -1,120 +0,0 @@
-# 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();
-};
-```