@saulwade/swl-ses 1.0.0

package/habilidades/react-experto/recursos/patrones-y-ejemplos-completos.md

@@ -0,0 +1,240 @@
+# React Experto — Patrones y Ejemplos Completos
+
+Referencia extendida de la skill `react-experto`. Contiene ejemplos completos
+de data fetching, state management, performance patterns y Next.js App Router.
+
+---
+
+## React Query — Ejemplo completo
+
+```tsx
+"use client";
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+
+export function ListaUsuarios() {
+  const { data, isPending, error } = useQuery({
+    queryKey: ['usuarios'],
+    queryFn: () => fetch('/api/usuarios').then(r => r.json()),
+    staleTime: 5 * 60 * 1000,  // 5 minutos
+  });
+
+  if (isPending) return <Skeleton />;
+  if (error) return <ErrorMessage error={error} />;
+
+  return <ul>{data.map(u => <li key={u.id}>{u.nombre}</li>)}</ul>;
+}
+
+// Mutacion con invalidacion de cache
+export function CrearUsuario() {
+  const queryClient = useQueryClient();
+  const mutation = useMutation({
+    mutationFn: (nuevoUsuario) =>
+      fetch('/api/usuarios', {
+        method: 'POST',
+        body: JSON.stringify(nuevoUsuario),
+      }).then(r => r.json()),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['usuarios'] });
+    },
+  });
+
+  return (
+    <button onClick={() => mutation.mutate({ nombre: 'Ana' })}>
+      Crear usuario
+    </button>
+  );
+}
+```
+
+---
+
+## Server Actions — Formularios y mutaciones desde RSC
+
+```tsx
+// app/actions/usuario.ts
+"use server";
+import { revalidatePath } from 'next/cache';
+import { db } from '@/lib/db';
+import { z } from 'zod';
+
+const UsuarioSchema = z.object({
+  nombre: z.string().min(2),
+  email: z.string().email(),
+});
+
+export async function crearUsuario(formData: FormData) {
+  const resultado = UsuarioSchema.safeParse({
+    nombre: formData.get('nombre'),
+    email: formData.get('email'),
+  });
+
+  if (!resultado.success) {
+    return { error: resultado.error.flatten() };
+  }
+
+  await db.usuario.create({ data: resultado.data });
+  revalidatePath('/usuarios');
+  return { success: true };
+}
+
+// Uso en un form (Server Component)
+export default function FormularioUsuario() {
+  return (
+    <form action={crearUsuario}>
+      <input name="nombre" required />
+      <input name="email" type="email" required />
+      <button type="submit">Crear</button>
+    </form>
+  );
+}
+```
+
+---
+
+## State Management — Zustand
+
+```typescript
+// lib/store/usuario.store.ts
+import { create } from 'zustand';
+import { immer } from 'zustand/middleware/immer';
+
+interface UsuarioStore {
+  usuarios: Usuario[];
+  filtro: string;
+  setFiltro: (filtro: string) => void;
+  agregarUsuario: (usuario: Usuario) => void;
+}
+
+export const useUsuarioStore = create<UsuarioStore>()(
+  immer((set) => ({
+    usuarios: [],
+    filtro: '',
+    setFiltro: (filtro) => set(state => { state.filtro = filtro; }),
+    agregarUsuario: (usuario) => set(state => {
+      state.usuarios.push(usuario);
+    }),
+  }))
+);
+
+// Selectores especificos para evitar re-renders
+export const useFiltroDatos = () =>
+  useUsuarioStore(state => state.filtro);
+```
+
+---
+
+## State Management — Jotai
+
+```typescript
+// lib/atoms/filtros.ts
+import { atom, useAtom, useAtomValue } from 'jotai';
+
+const filtroBaseAtom = atom('');
+const usuariosAtom = atom<Usuario[]>([]);
+
+// Atomo derivado (computed)
+const usuariosFiltradosAtom = atom(get => {
+  const filtro = get(filtroBaseAtom).toLowerCase();
+  return get(usuariosAtom).filter(u =>
+    u.nombre.toLowerCase().includes(filtro)
+  );
+});
+
+// Uso
+function ListaFiltrada() {
+  const usuariosFiltrados = useAtomValue(usuariosFiltradosAtom);
+  return <ul>{usuariosFiltrados.map(...)}</ul>;
+}
+```
+
+---
+
+## Next.js App Router — Estructura de directorios
+
+```
+app/
++-- layout.tsx           # Layout raiz (Server Component)
++-- page.tsx             # Home
++-- loading.tsx          # UI de carga automatica (Suspense)
++-- error.tsx            # Manejo de errores ('use client')
++-- not-found.tsx        # 404
++-- (auth)/              # Route Group — no afecta URL
+|   +-- login/page.tsx
+|   +-- registro/page.tsx
++-- dashboard/
+|   +-- layout.tsx       # Layout anidado
+|   +-- page.tsx
+|   +-- [id]/
+|       +-- page.tsx     # Ruta dinamica
++-- api/
+    +-- usuarios/
+        +-- route.ts     # Route Handler
+```
+
+---
+
+## Route Handlers (API routes)
+
+```typescript
+// app/api/usuarios/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { db } from '@/lib/db';
+
+export async function GET(req: NextRequest) {
+  const { searchParams } = new URL(req.url);
+  const pagina = Number(searchParams.get('pagina') ?? '1');
+
+  const usuarios = await db.usuario.findMany({
+    skip: (pagina - 1) * 20,
+    take: 20,
+  });
+
+  return NextResponse.json({ items: usuarios, pagina });
+}
+
+export async function POST(req: NextRequest) {
+  const body = await req.json();
+  const usuario = await db.usuario.create({ data: body });
+  return NextResponse.json(usuario, { status: 201 });
+}
+```
+
+---
+
+## Metadata dinamica
+
+```tsx
+// app/usuarios/[id]/page.tsx
+export async function generateMetadata({ params }: Props) {
+  const usuario = await getUsuario(params.id);
+  return {
+    title: `${usuario.nombre} — Mi App`,
+    description: `Perfil de ${usuario.nombre}`,
+  };
+}
+```
+
+---
+
+## Streaming con Suspense (Next.js App Router)
+
+```tsx
+// app/dashboard/page.tsx
+import { Suspense } from 'react';
+
+export default function DashboardPage() {
+  return (
+    <div>
+      <Encabezado />
+
+      <Suspense fallback={<SkeletonGrafica />}>
+        <GraficaVentas />
+      </Suspense>
+
+      <Suspense fallback={<SkeletonTabla />}>
+        <TablaReciente />
+      </Suspense>
+    </div>
+  );
+}
+```

package/habilidades/react-optimizacion/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: react-optimizacion
+description: Optimización de rendimiento en React. memo, useMemo, useCallback, code splitting, lazy loading, concurrent features, Suspense y patrones de estado eficiente.
+version: "1.0.0"
+herramientasPermitidas: [Read, Grep]
+exclusiones:
+  - "No cargar para patrones generales de React (Server Components, data fetching, state management) — para fundamentos cargar `react-experto`."
+  - "No cargar para optimización de rendimiento en Angular — las APIs de signals y OnPush son distintas; cargar `angular-moderno` o `angular-avanzado`."
+  - "No cargar para optimización CSS o de imágenes (lazy loading de assets) — para CSS cargar `css-moderno` o `tailwind-experto`."
+  - "No cargar para profiling de backend o queries SQL — la optimización aquí es exclusivamente del renderizado y bundling del cliente React."
+evolvable: true  # default para skill estandar
+---
+# Optimización de Rendimiento en React
+
+## Cuándo NO cargar
+
+- La tarea es sobre patrones generales de React: Server Components, data fetching, state management — cargar `react-experto`.
+- La optimización es para Angular — las APIs de signals, OnPush y zoneless son distintas; cargar `angular-moderno` o `angular-avanzado`.
+- El tema es optimización de CSS, imágenes o assets estáticos — cargar `css-moderno` o `tailwind-experto`.
+- El cuello de botella es el backend o queries SQL, no el renderizado del cliente — este skill es exclusivamente de rendimiento React en el cliente.
+
+## Principio de optimización prematura
+
+**No optimices antes de medir.** La mayoría de los problemas de rendimiento en React
+provienen de re-renders innecesarios o de carga inicial pesada. Primero identifica
+el cuello de botella con React DevTools Profiler, luego aplica la solución correcta.
+
+---
+
+## Re-renders: cuándo ocurren y cómo controlarlos
+
+Un componente se re-renderiza cuando:
+1. Su propio estado cambia (`useState`, `useReducer`).
+2. Su componente padre se re-renderiza (incluso si las props no cambiaron).
+3. Un contexto del que consume cambia.
+
+### React.memo — evitar re-renders por props iguales
+
+```tsx
+import React, { memo } from 'react';
+
+const FacturaCard = memo(function FacturaCard({
+  factura,
+  onCancelar,
+}: {
+  factura: Factura;
+  onCancelar: (id: string) => void;
+}) {
+  return (
+    <div className="border rounded-lg p-4">
+      <h3>{factura.folio}</h3>
+      <button onClick={() => onCancelar(factura.id)}>Cancelar</button>
+    </div>
+  );
+});
+```
+
+### useMemo — memorizar cálculos costosos
+
+```tsx
+const estadisticas = useMemo(() => ({
+  total: facturas.reduce((sum, f) => sum + f.monto, 0),
+  emitidas: facturas.filter(f => f.estatus === 'emitida').length,
+}), [facturas]);
+```
+
+### useCallback — estabilizar referencias de funciones
+
+```tsx
+// Sin useCallback, nueva referencia en cada render → memo del hijo no funciona
+const handleCancelar = useCallback((id: string) => {
+  setFacturas(prev => prev.map(f =>
+    f.id === id ? { ...f, estatus: 'cancelada' } : f
+  ));
+}, []); // Sin dependencias porque usa setter funcional
+```
+
+---
+
+## Code Splitting y Lazy Loading
+
+### React.lazy + Suspense
+
+```tsx
+import React, { lazy, Suspense } from 'react';
+import { Routes, Route } from 'react-router-dom';
+
+const FacturasPage = lazy(() => import('./pages/FacturasPage'));
+const ReportesPage = lazy(() => import('./pages/ReportesPage'));
+
+function App() {
+  return (
+    <Suspense fallback={<PageLoader />}>
+      <Routes>
+        <Route path="/facturas" element={<FacturasPage />} />
+        <Route path="/reportes" element={<ReportesPage />} />
+      </Routes>
+    </Suspense>
+  );
+}
+```
+
+### Lazy loading de componentes pesados
+
+```tsx
+const GraficaVentas = lazy(() => import('./GraficaVentas'));
+
+function Dashboard() {
+  const [mostrarGrafica, setMostrarGrafica] = useState(false);
+  return (
+    <div>
+      <button onClick={() => setMostrarGrafica(true)}>Ver gráfica</button>
+      {mostrarGrafica && (
+        <Suspense fallback={<div className="h-64 animate-pulse bg-gray-100" />}>
+          <GraficaVentas />
+        </Suspense>
+      )}
+    </div>
+  );
+}
+```
+
+---
+
+## Concurrent Features — resumen
+
+- **useTransition**: marca actualizaciones como no urgentes. El input responde inmediatamente mientras los resultados se calculan en segundo plano.
+- **useDeferredValue**: crea una versión diferida de un valor para mantener el UI fluido.
+
+Para ejemplos completos de useTransition, useDeferredValue, virtualización y optimización de Context, ver [recursos/patrones-avanzados.md](recursos/patrones-avanzados.md).
+
+---
+
+## Virtualización para listas largas
+
+Para listas de >100 elementos, usar `@tanstack/react-virtual` para renderizar solo los elementos visibles. Esto reduce el DOM de miles de nodos a decenas.
+
+Para implementación completa, ver [recursos/patrones-avanzados.md](recursos/patrones-avanzados.md).
+
+---
+
+## Optimización de Context
+
+El contexto causa re-render en TODOS los consumidores cuando cambia. Reglas:
+- **Separar** contextos por dominio y frecuencia de cambio (Auth, UI, Datos).
+- **Estabilizar** el valor con `useMemo` para evitar objetos nuevos en cada render.
+- NUNCA un solo contexto monolítico con todo el estado de la app.
+
+Para ejemplo completo de AuthProvider optimizado, ver [recursos/patrones-avanzados.md](recursos/patrones-avanzados.md).
+
+---
+
+## Cuándo NO usar memo/useMemo/useCallback
+
+Estas optimizaciones tienen un costo: complejidad de código y overhead de comparación.
+No aplicar cuando:
+
+- El componente es simple y rápido de renderizar.
+- Las props cambian en casi todos los re-renders de todas formas.
+- El cálculo en `useMemo` es trivial (suma de 3 números).
+- No hay evidencia medida de problema de rendimiento.
+
+**Regla práctica**: medir primero con React DevTools Profiler. Si un componente
+aparece en llamas largas o con muchos re-renders no esperados, entonces optimizar.
+
+## Gotchas / Errores comunes no obvios
+
+**`React.memo` no previene re-renders si alguna prop es una función o array creado inline**: `<Lista onSeleccionar={() => handleSelect(id)} />` crea una nueva referencia de función en cada render del padre — `memo` compara con `===` y siempre detecta cambio. Causa: las funciones y objetos literales tienen identidad diferente en cada render. Fix: estabilizar con `useCallback` la función y con `useMemo` los arrays/objetos antes de pasarlos como props a componentes memoizados.
+
+**`useMemo` con dependencias que incluyen objetos del estado no evita recálculos porque el objeto es siempre nuevo**: `useMemo(() => calcular(filtros), [filtros])` recalcula en cada render si `filtros` es `{ texto: '', page: 1 }` definido en el render como literal. Causa: el objeto es una referencia nueva aunque sus valores sean iguales. Fix: usar propiedades primitivas como dependencias (`[filtros.texto, filtros.page]`) en lugar del objeto completo.
+
+**`useTransition` marca la actualización como diferida pero no previene el bloqueo del hilo principal si el cálculo es síncrono costoso**: `startTransition(() => setFiltros(nuevoFiltro))` pospone la actualización de UI pero si el componente resultante tarda 200ms en renderizarse síncronamente, el hilo principal sigue bloqueado. Causa: `useTransition` prioriza, no paraleliza — React aún renderiza síncronamente. Fix: combinar con `useDeferredValue` para el valor que dispara el cálculo costoso, o mover el cálculo a un Web Worker.
+
+**Virtualización con `@tanstack/react-virtual` falla cuando el contenedor no tiene altura fija**: el virtualizador necesita saber el tamaño del contenedor para calcular qué items son visibles — si el contenedor crece con el contenido (sin `height` o `overflow: auto`), estima incorrectamente y renderiza demasiados o muy pocos items. Causa: `useVirtualizer` lee `scrollElement.clientHeight` para calcular el viewport. Fix: dar al contenedor una altura fija (`height: 400px`) o relativa (`height: 100%` con el padre acotado) y `overflow: auto`.

package/habilidades/react-optimizacion/recursos/patrones-avanzados.md

@@ -0,0 +1,138 @@
+# React Optimizacion — Patrones avanzados y ejemplos completos
+
+## Concurrent Features
+
+### useTransition — marcar actualizaciones como no urgentes
+
+```tsx
+import { useTransition, useState } from 'react';
+
+function BuscadorFacturas() {
+  const [query, setQuery] = useState('');
+  const [resultados, setResultados] = useState<Factura[]>([]);
+  const [isPending, startTransition] = useTransition();
+
+  const handleBusqueda = (valor: string) => {
+    // Actualización urgente: el input responde inmediatamente
+    setQuery(valor);
+
+    // Actualización no urgente: los resultados pueden esperar
+    startTransition(() => {
+      const filtrados = buscarFacturas(valor);
+      setResultados(filtrados);
+    });
+  };
+
+  return (
+    <div>
+      <input
+        value={query}
+        onChange={e => handleBusqueda(e.target.value)}
+        placeholder="Buscar facturas..."
+      />
+      {isPending && <span className="text-gray-400">Buscando...</span>}
+      <ListaResultados resultados={resultados} />
+    </div>
+  );
+}
+```
+
+### useDeferredValue — versión diferida de un valor
+
+```tsx
+import { useDeferredValue, memo } from 'react';
+
+function ListaFiltrada({ items }: { items: string[] }) {
+  const [filtro, setFiltro] = useState('');
+  // Versión diferida del filtro — permite que el input sea fluido
+  const filtroDeferred = useDeferredValue(filtro);
+
+  // isStale detecta si estamos mostrando resultado desactualizado
+  const isStale = filtro !== filtroDeferred;
+
+  const itemsFiltrados = useMemo(
+    () => items.filter(item => item.includes(filtroDeferred)),
+    [items, filtroDeferred]
+  );
+
+  return (
+    <div>
+      <input value={filtro} onChange={e => setFiltro(e.target.value)} />
+      <ul style={{ opacity: isStale ? 0.6 : 1 }}>
+        {itemsFiltrados.map(item => <li key={item}>{item}</li>)}
+      </ul>
+    </div>
+  );
+}
+```
+
+---
+
+## Virtualización para listas largas
+
+```tsx
+import { useVirtualizer } from '@tanstack/react-virtual';
+import { useRef } from 'react';
+
+function ListaVirtualizada({ facturas }: { facturas: Factura[] }) {
+  const contenedorRef = useRef<HTMLDivElement>(null);
+
+  const virtualizer = useVirtualizer({
+    count: facturas.length,
+    getScrollElement: () => contenedorRef.current,
+    estimateSize: () => 80,  // altura estimada en px por fila
+    overscan: 5,             // filas extra fuera del viewport
+  });
+
+  return (
+    <div ref={contenedorRef} style={{ height: '600px', overflow: 'auto' }}>
+      <div style={{ height: `${virtualizer.getTotalSize()}px`, position: 'relative' }}>
+        {virtualizer.getVirtualItems().map(virtualItem => (
+          <div
+            key={virtualItem.key}
+            style={{
+              position: 'absolute',
+              top: 0,
+              left: 0,
+              width: '100%',
+              transform: `translateY(${virtualItem.start}px)`,
+            }}
+          >
+            <FacturaCard factura={facturas[virtualItem.index]} />
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+---
+
+## Optimización de Context — ejemplo completo
+
+El contexto causa re-render en TODOS los consumidores cuando cambia.
+Dividir en contextos más pequeños o usar selectores:
+
+```tsx
+// MAL: un solo contexto con todo el estado
+const AppContext = createContext<AppState>({...});
+
+// BIEN: separar por dominio y frecuencia de cambio
+const AuthContext = createContext<AuthState>({...});      // Cambia raramente
+const UIContext = createContext<UIState>({...});          // Cambia frecuentemente
+const FacturasContext = createContext<FacturasState>({...}); // Cambia al interactuar
+
+// BIEN: con useMemo para estabilizar el valor del contexto
+function AuthProvider({ children }: { children: React.ReactNode }) {
+  const [usuario, setUsuario] = useState<Usuario | null>(null);
+
+  const value = useMemo(() => ({
+    usuario,
+    login: async (creds: Credentials) => { ... },
+    logout: () => setUsuario(null),
+  }), [usuario]);  // Solo se crea objeto nuevo cuando usuario cambia
+
+  return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;
+}
+```