theus-cli 0.2.83 → 0.2.85

package/vendor/theus-arsenal/skills/motion-avanzado/SKILL.md

@@ -1,592 +0,0 @@
----
-name: motion-avanzado
-description: Patrones avanzados de animación para React / Next.js con motion — drag & drop, gestos, animación de texto, trazado de rutas SVG, hooks personalizados, secuencias imperativas (useAnimate), loaders y el árbol de decisión completo de la API. Requiere fundamentos-animacion.
----
-
-# Motion avanzado
-
-Patrones de animación complejos, interactivos y basados en física.
-Requiere que `fundamentos-animacion` esté configurada primero.
-Úsalos cuando `patrones-animacion` no sea suficiente.
-
-## Cuándo activarla
-
-- Al construir hojas (sheets) con arrastrar-para-cerrar, gestos de swipe o listas reordenables
-- Al animar texto palabra por palabra, carácter por carácter, o como contador en vivo
-- Al dibujar rutas SVG, transformar iconos (morphing) o animar progreso circular
-- Al escribir un hook de animación personalizado (`useScrollReveal`, botón magnético, seguidor de cursor)
-- Al secuenciar animaciones de varios pasos de forma imperativa con `useAnimate`
-- Al construir spinners, skeletons con shimmer, indicadores de pulso o estados de carga en botones
-
-## Salidas
-
-Esta skill produce:
-
-- Interacciones de arrastre: tarjetas arrastrables, hojas con arrastrar-para-cerrar, listas con `Reorder.Group`
-- Hooks de gestos: detección de swipe, pulsación larga, esbozo de pinch
-- Componentes de animación de texto: revelado por palabra, máquina de escribir por carácter, contador numérico
-- Animación SVG: dibujado de rutas, morphing de iconos, anillo de progreso por trazo
-- Hooks personalizados: `useScrollReveal`, `useHoverScale`, `useNavigationDirection`, `useInViewOnce`
-- Secuencias imperativas vía `useAnimate` con `async/await` seguro ante interrupciones
-- Componentes de carga: spinner, shimmer, punto pulsante, barra de progreso, estado de carga en botón
-
-## Principios
-
-- El movimiento basado en física (`useSpring`, `springs.*`) siempre se siente más natural que el basado en duración para manipulación directa.
-- `useMotionValue` + `useTransform` calcula valores derivados sin provocar re-renderizados.
-- Las secuencias de `useAnimate` son imperativas y seguras ante interrupciones — llamar a `animate()` a mitad de vuelo cancela automáticamente la animación anterior.
-- Los motion values (`useMotionValue`, `useSpring`) son seguros para SSR y no causan errores de hidratación.
-
-## Reglas
-
-1. **Las interacciones de arrastre deben probarse en dispositivos táctiles**, no solo con ratón. La prop `drag` funciona en ambos, pero la sensación y los umbrales difieren.
-2. **Las animaciones infinitas deben pausarse cuando `document.visibilityState === "hidden"`.** Las pestañas en segundo plano no deben consumir GPU/CPU.
-3. **El umbral de swipe debe ser explícito.** Nunca infieras la intención solo por velocidad; combina verificaciones de `offset` + `velocity`.
-4. **El ref de scope de `useAnimate` debe estar adjunto a un elemento del DOM montado.** Llamar a `animate()` antes del montaje falla silenciosamente.
-5. **Los motion values no deben recrearse en cada render.** `useMotionValue(0)` dentro del cuerpo del componente es correcto; `new MotionValue(0)` en un render no lo es.
-6. **Todos los valores de tokens se importan de `fundamentos-animacion`.** Nada de números en línea.
-7. **Los hooks personalizados deben gestionar la limpieza.** Cada `window.addEventListener` necesita su `removeEventListener` correspondiente en el return del `useEffect`.
-8. **El morphing de SVG requiere el mismo número de comandos de ruta.** Rutas con estructuras de comandos distintas saltan en lugar de interpolar.
-
-## Guía de decisión
-
-### Elegir la API avanzada correcta
-
-| Escenario | API |
-| ------------------------------ | -------------------------------- |
-| Arrastre con física al soltar | `drag` + `dragTransition: springs.release` |
-| Lista ordenada con arrastrar-para-reordenar | `Reorder.Group` + `Reorder.Item` |
-| Cerrar según el offset de arrastre | `drag="y"` + verificación de offset en `onDragEnd` |
-| Swipe izquierda/derecha | `drag="x"` + verificación de offset en `onDragEnd` |
-| Pulsación larga | hook `useLongPress` |
-| Valor suavizado en el tiempo | `useSpring` |
-| Valor derivado de otro | `useTransform` |
-| Secuencia de varios pasos | `useAnimate` con `async/await` |
-| Animación imperativa puntual | `animate()` de `motion` |
-| Texto que entra palabra por palabra | Stagger sobre spans `inline-block` |
-| SVG que se dibuja | `pathLength` 0 → 1 |
-| Morphing de SVG | Tween del atributo `d` (comandos iguales) |
-| Progreso circular | Tween de `strokeDashoffset` |
-
-### Cuándo usar `useSpring` vs una transición de spring
-
-| | `useSpring` | `transition: springs.*` |
-| -------------- | ---------------------------------------- | ----------------------- |
-| Úsalo para | Seguidor de cursor, valores ligados al puntero | Cambios de estado discretos |
-| Actualizaciones | Continuas, en cada frame | Disparadas por cambio de estado |
-| Interrupción | Suave — la física retoma desde la velocidad | Reinicia desde el valor actual |
-
-## Conceptos centrales
-
-### useMotionValue + useTransform
-
-Cómputo reactivo sin re-renderizados:
-
-```tsx
-const x = useMotionValue(0)
-const opacity = useTransform(x, [-200, 0, 200], [0, 1, 0])
-// opacity se actualiza en cada frame conforme x cambia — sin setState, sin re-render
-```
-
-### useAnimate
-
-Devuelve `[scope, animate]`. El ref de scope debe estar adjunto a un elemento del DOM.
-Las llamadas a `animate()` son seguras ante interrupciones — llamarla a mitad de vuelo cancela la ejecución anterior.
-
-```tsx
-const [scope, animate] = useAnimate()
-
-async function play() {
-  await animate(".step-1", { opacity: 1 }, { duration: 0.3 })
-  await animate(".step-2", { x: 0 },       { duration: 0.4 })
-        animate(".step-3", { scale: 1 },    { duration: 0.25 })  // dispara y olvida
-}
-
-return <div ref={scope}>...</div>
-```
-
-## Ejemplos de código
-
-### Tarjeta arrastrable
-
-```tsx
-"use client"
-import { motion } from "motion/react"
-import { springs, motionTokens } from "@/lib/motion-tokens"
-
-<motion.div
-  drag
-  dragConstraints={{ left: -100, right: 100, top: -100, bottom: 100 }}
-  dragElastic={0.1}
-  whileDrag={{
-    scale: motionTokens.scale.pop,
-    boxShadow: "0 16px 40px rgba(0,0,0,0.2)",
-  }}
-  dragTransition={springs.release}
-/>
-```
-
-### Hoja con arrastrar-para-cerrar
-
-```tsx
-"use client"
-import { motion, useMotionValue, useTransform } from "motion/react"
-
-export function BottomSheet({ onClose }: { onClose: () => void }) {
-  const y = useMotionValue(0)
-  const opacity = useTransform(y, [0, 200], [1, 0])
-
-  return (
-    <motion.div
-      drag="y"
-      dragConstraints={{ top: 0 }}
-      style={{ y, opacity }}
-      onDragEnd={(_, info) => {
-        // Regla 3: combinar offset + velocity
-        if (info.offset.y > 120 || info.velocity.y > 500) onClose()
-      }}
-    />
-  )
-}
-```
-
-### Lista reordenable
-
-```tsx
-"use client"
-import { Reorder } from "motion/react"
-
-export function SortableList() {
-  const [items, setItems] = useState(initialItems)
-  return (
-    <Reorder.Group axis="y" values={items} onReorder={setItems}>
-      {items.map((item) => (
-        <Reorder.Item key={item.id} value={item}>
-          {item.label}
-        </Reorder.Item>
-      ))}
-    </Reorder.Group>
-  )
-}
-```
-
-### Detección de swipe
-
-```tsx
-"use client"
-import { motion } from "motion/react"
-
-const OFFSET_THRESHOLD  = 50
-const VELOCITY_THRESHOLD = 300
-
-<motion.div
-  drag="x"
-  dragConstraints={{ left: 0, right: 0 }}
-  onDragEnd={(_, info) => {
-    const swipedRight = info.offset.x > OFFSET_THRESHOLD  || info.velocity.x > VELOCITY_THRESHOLD
-    const swipedLeft  = info.offset.x < -OFFSET_THRESHOLD || info.velocity.x < -VELOCITY_THRESHOLD
-    if (swipedRight) onSwipeRight()
-    if (swipedLeft)  onSwipeLeft()
-  }}
-/>
-```
-
-### Hook de pulsación larga
-
-```tsx
-import { useRef } from "react"
-
-export function useLongPress(callback: () => void, ms = 600) {
-  const timerRef = useRef<ReturnType<typeof setTimeout>>()
-  return {
-    onPointerDown:  () => { timerRef.current = setTimeout(callback, ms) },
-    onPointerUp:    () => clearTimeout(timerRef.current),
-    onPointerLeave: () => clearTimeout(timerRef.current),
-  }
-}
-```
-
-### Revelado palabra por palabra
-
-```tsx
-"use client"
-import { motion } from "motion/react"
-import { springs } from "@/lib/motion-tokens"
-
-export function AnimatedText({ text }: { text: string }) {
-  return (
-    <motion.p
-      variants={{ visible: { transition: { staggerChildren: 0.05 } } }}
-      initial="hidden"
-      animate="visible"
-    >
-      {text.split(" ").map((word, i) => (
-        <motion.span
-          key={i}
-          className="inline-block mr-1"
-          variants={{
-            hidden:  { opacity: 0, y: 12 },
-            visible: { opacity: 1, y: 0, transition: springs.gentle },
-          }}
-        >
-          {word}
-        </motion.span>
-      ))}
-    </motion.p>
-  )
-}
-```
-
-### Contador numérico
-
-```tsx
-"use client"
-import { useRef, useEffect } from "react"
-import { animate } from "motion"
-import { motionTokens } from "@/lib/motion-tokens"
-
-export function Counter({ to }: { to: number }) {
-  const nodeRef = useRef<HTMLSpanElement>(null)
-
-  useEffect(() => {
-    const controls = animate(0, to, {
-      duration: motionTokens.duration.crawl,
-      ease: motionTokens.easing.smooth,
-      onUpdate: (v) => {
-        if (nodeRef.current) nodeRef.current.textContent = Math.round(v).toString()
-      },
-    })
-    return controls.stop   // Regla 7: limpieza
-  }, [to])
-
-  return <span ref={nodeRef} />
-}
-```
-
-### Dibujado de ruta SVG
-
-```tsx
-"use client"
-import { motion } from "motion/react"
-import { motionTokens } from "@/lib/motion-tokens"
-
-<motion.path
-  d="M 0 100 Q 50 0 100 100"
-  initial={{ pathLength: 0, opacity: 0 }}
-  animate={{ pathLength: 1, opacity: 1 }}
-  transition={{ duration: motionTokens.duration.slow, ease: motionTokens.easing.smooth }}
-/>
-```
-
-### Anillo de progreso por trazo
-
-```tsx
-"use client"
-import { motion } from "motion/react"
-import { motionTokens } from "@/lib/motion-tokens"
-
-const CIRCUMFERENCE = 2 * Math.PI * 40   // r=40
-
-export function ProgressRing({ progress }: { progress: number }) {
-  return (
-    <svg width="100" height="100" viewBox="0 0 100 100">
-      <circle cx="50" cy="50" r="40" fill="none" stroke="#e5e7eb" strokeWidth="8" />
-      <motion.circle
-        cx="50" cy="50" r="40"
-        fill="none" stroke="#6366f1" strokeWidth="8"
-        strokeLinecap="round"
-        strokeDasharray={CIRCUMFERENCE}
-        animate={{ strokeDashoffset: CIRCUMFERENCE - (progress / 100) * CIRCUMFERENCE }}
-        transition={{ duration: motionTokens.duration.normal, ease: motionTokens.easing.smooth }}
-        style={{ rotate: -90, transformOrigin: "center" }}
-      />
-    </svg>
-  )
-}
-```
-
-### Hook useScrollReveal
-
-```tsx
-"use client"
-import { useRef } from "react"
-import { useScroll, useTransform } from "motion/react"
-import { motionTokens } from "@/lib/motion-tokens"
-
-export function useScrollReveal() {
-  const ref = useRef(null)
-  const { scrollYProgress } = useScroll({ target: ref, offset: ["start end", "end start"] })
-  const opacity = useTransform(scrollYProgress, [0, 0.3], [0, 1])
-  const y       = useTransform(scrollYProgress, [0, 0.3], [motionTokens.distance.lg, 0])
-  return { ref, style: { opacity, y } }
-}
-
-// Uso
-const { ref, style } = useScrollReveal()
-<motion.section ref={ref} style={style} />
-```
-
-### Seguidor de cursor
-
-```tsx
-"use client"
-import { useEffect } from "react"
-import { motion, useMotionValue, useSpring } from "motion/react"
-import { springs } from "@/lib/motion-tokens"
-
-export function CursorFollower() {
-  const x = useMotionValue(-100)
-  const y = useMotionValue(-100)
-  const sx = useSpring(x, springs.gentle)
-  const sy = useSpring(y, springs.gentle)
-
-  useEffect(() => {
-    const move = (e: MouseEvent) => { x.set(e.clientX); y.set(e.clientY) }
-    window.addEventListener("mousemove", move)
-    return () => window.removeEventListener("mousemove", move)   // Regla 7
-  }, [])
-
-  return (
-    <motion.div
-      className="fixed top-0 left-0 w-6 h-6 rounded-full bg-indigo-500
-                 pointer-events-none -translate-x-1/2 -translate-y-1/2 z-50"
-      style={{ x: sx, y: sy }}
-    />
-  )
-}
-```
-
-### Skeleton con shimmer
-
-```tsx
-"use client"
-import { useEffect } from "react"
-import { motion, useAnimation } from "motion/react"
-import { motionTokens } from "@/lib/motion-tokens"
-
-export function ShimmerSkeleton({ className = "" }: { className?: string }) {
-  const controls = useAnimation()
-
-  useEffect(() => {
-    const play = () =>
-      controls.start({
-        x: ["-100%", "100%"],
-        transition: {
-          repeat: Infinity,
-          duration: motionTokens.duration.crawl,
-          ease: motionTokens.easing.linear,
-        },
-      })
-
-    const handleVisibility = () => {
-      if (document.visibilityState === "hidden") controls.stop()
-      else void play()
-    }
-
-    void play()
-    document.addEventListener("visibilitychange", handleVisibility)
-    return () => {
-      controls.stop()
-      document.removeEventListener("visibilitychange", handleVisibility)
-    }
-  }, [controls])
-
-  return (
-    <div className={`relative overflow-hidden bg-gray-200 rounded ${className}`}>
-      <motion.div
-        className="absolute inset-0 bg-gradient-to-r from-transparent via-white/60 to-transparent"
-        initial={{ x: "-100%" }}
-        animate={controls}
-      />
-    </div>
-  )
-}
-```
-
-### Estado de carga en botón
-
-```tsx
-"use client"
-import { motion, AnimatePresence } from "motion/react"
-import { motionTokens, springs } from "@/lib/motion-tokens"
-
-export function LoadingButton({
-  loading,
-  label,
-  onClick,
-}: {
-  loading: boolean
-  label: string
-  onClick: () => void
-}) {
-  return (
-    <motion.button
-      onClick={onClick}
-      animate={{ opacity: loading ? 0.7 : 1 }}
-      whileTap={loading ? {} : { scale: motionTokens.scale.press }}
-      transition={springs.snappy}
-      disabled={loading}
-    >
-      <AnimatePresence mode="wait">
-        {loading ? (
-          <motion.span
-            key="loading"
-            initial={{ opacity: 0 }} animate={{ opacity: 1 }} exit={{ opacity: 0 }}
-            transition={{ duration: motionTokens.duration.fast }}
-          >
-            …
-          </motion.span>
-        ) : (
-          <motion.span
-            key="label"
-            initial={{ opacity: 0 }} animate={{ opacity: 1 }} exit={{ opacity: 0 }}
-            transition={{ duration: motionTokens.duration.fast }}
-          >
-            {label}
-          </motion.span>
-        )}
-      </AnimatePresence>
-    </motion.button>
-  )
-}
-```
-
-### Animación infinita con pausa por visibilidad
-
-```tsx
-"use client"
-import { useEffect } from "react"
-import { motion, useAnimation } from "motion/react"
-import { motionTokens } from "@/lib/motion-tokens"
-
-export function PulseDot() {
-  const controls = useAnimation()
-
-  useEffect(() => {
-    const pulse = () =>
-      controls.start({
-        scale: [1, 1.4, 1],
-        opacity: [1, 0.6, 1],
-        transition: { repeat: Infinity, duration: motionTokens.duration.crawl },
-      })
-
-    // Regla 2: pausar cuando la pestaña está oculta
-    const handleVisibility = () => {
-      if (document.visibilityState === "hidden") controls.stop()
-      else void pulse()
-    }
-
-    void pulse()
-    document.addEventListener("visibilitychange", handleVisibility)
-    // Regla 7: detener controls y quitar listeners al desmontar.
-    return () => {
-      controls.stop()
-      document.removeEventListener("visibilitychange", handleVisibility)
-    }
-  }, [controls])
-
-  return <motion.span className="w-2 h-2 rounded-full bg-green-400" animate={controls} />
-}
-```
-
-## Ejemplo de extremo a extremo
-
-Hoja con arrastrar-para-cerrar, contenido con shimmer, estado de carga y soporte
-de movimiento reducido — combinando `useMotionValue`, `useTransform`, `useSafeMotion`,
-`AnimatePresence` y los tokens de `fundamentos-animacion`:
-
-```tsx
-"use client"
-import { useState } from "react"
-import { motion, AnimatePresence, useMotionValue, useTransform } from "motion/react"
-import { springs, motionTokens } from "@/lib/motion-tokens"
-import { useSafeMotion } from "@/hooks/use-reduced-motion"
-import { ShimmerSkeleton } from "./shimmer-skeleton"
-
-export function DismissibleSheet({
-  isOpen,
-  onClose,
-  loading,
-  children,
-}: {
-  isOpen: boolean
-  onClose: () => void
-  loading: boolean
-  children: React.ReactNode
-}) {
-  const safe = useSafeMotion(motionTokens.distance.xl)
-  const y = useMotionValue(0)
-  const opacity = useTransform(y, [0, 200], [1, 0])
-
-  return (
-    <AnimatePresence>
-      {isOpen && (
-        <>
-          {/* Fondo (backdrop) */}
-          <motion.div
-            key="backdrop"
-            className="fixed inset-0 bg-black/40"
-            initial={{ opacity: 0 }}
-            animate={{ opacity: 1 }}
-            exit={{ opacity: 0 }}
-            onClick={onClose}
-          />
-
-          {/* Hoja — arrastrar para cerrar */}
-          <motion.div
-            key="sheet"
-            className="fixed bottom-0 inset-x-0 rounded-t-2xl bg-white p-6"
-            drag="y"
-            dragConstraints={{ top: 0 }}
-            style={{ y, opacity }}
-            onDragEnd={(_, info) => {
-              if (info.offset.y > 120 || info.velocity.y > 500) onClose()
-            }}
-            initial={safe.initial}
-            animate={safe.animate}
-            exit={safe.exit}
-            transition={springs.gentle}
-          >
-            {loading ? (
-              <div className="space-y-3">
-                <ShimmerSkeleton className="h-4 w-3/4" />
-                <ShimmerSkeleton className="h-4 w-1/2" />
-                <ShimmerSkeleton className="h-20 w-full" />
-              </div>
-            ) : children}
-          </motion.div>
-        </>
-      )}
-    </AnimatePresence>
-  )
-}
-```
-
-## Restricciones / fuera de alcance
-
-Esta skill **no** cubre:
-
-- Definiciones de tokens y springs → ver `fundamentos-animacion`
-- Patrones de UI estándar (botón, modal, stagger, transiciones de página) → ver `patrones-animacion`
-- Animaciones solo con CSS o `animate-*` de Tailwind sin `motion/react`
-- Animación basada en Canvas o WebGL (Three.js, Pixi, etc.)
-- Sistemas completos de drag-and-drop con gestores de estado externos (dnd-kit, react-beautiful-dnd)
-- Animación de bucle de juego o frame a frame
-
-## Antipatrones
-
-| Antipatrón | Regla violada | Corrección |
-| ---------------------------------------------- | ------- | ------------------------------------------------ |
-| `drag` probado solo en escritorio | Regla 1 | Probar en emulador táctil y en dispositivo real |
-| `animate={{ repeat: Infinity }}` sin pausa | Regla 2 | Añadir listener de `visibilitychange` |
-| `onDragEnd` verificando solo offset, no velocity | Regla 3 | Verificar `info.offset` e `info.velocity` |
-| `animate(scope, ...)` antes del `useEffect` | Regla 4 | Llamar a `animate()` solo tras el montaje |
-| `const x = new MotionValue(0)` en un render | Regla 5 | Usar `const x = useMotionValue(0)` |
-| `transition={{ duration: 1.2 }}` en línea | Regla 6 | Usar `motionTokens.duration.crawl` |
-| `useEffect` sin limpieza | Regla 7 | Devolver `removeEventListener` / `controls.stop` |
-| Morphing entre rutas SVG con comandos distintos | Regla 8 | Normalizar los comandos de ruta antes de animar |
-
-## Skills relacionadas
-
-- **`fundamentos-animacion`** — define todos los tokens, springs, `useSafeMotion` y las guardas de SSR que se importan aquí. Debe configurarse antes de usar esta skill.
-- **`patrones-animacion`** — cubre los patrones de UI estándar (botón, modal, stagger, transiciones de página, revelados por scroll). Úsala antes de recurrir a los patrones avanzados de aquí.