motion-presets-kit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Orlando Lopez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,174 @@
+# motion-presets-kit
+
+Set tipado y validado en runtime de helpers para [`motion/react`](https://motion.dev) que facilita crear animaciones de entrada, salida y transiciones con valores por defecto sensatos.
+
+- **API variant-returning**: funciones puras que retornan `Variants` de motion.
+- **Validación con Zod** de todas las opciones (los tipos se derivan de los schemas).
+- **Tree-shakeable**: 3 entry points (`.`, `./presets`, `./components`).
+- **SSR-safe** y respeta `prefers-reduced-motion` por defecto.
+
+## Instalación
+
+```bash
+pnpm add motion-presets-kit motion zod react react-dom
+```
+
+`react`, `react-dom`, `motion` y `zod` son peer dependencies.
+
+## Skill para agentes de IA
+
+El paquete incluye una skill (`skill/motion-presets-kit/SKILL.md`) para que
+asistentes como opencode, Claude o agentes compatibles conozcan la API completa.
+Al terminar la instalación se pregunta si deseas instalarla (solo en terminal
+interactiva; en CI se omite). También puedes instalarla en cualquier momento:
+
+```bash
+npx motion-presets-kit add-skill            # auto-detecta .opencode, .claude, .agents
+npx motion-presets-kit add-skill --global   # instala en tu HOME
+npx motion-presets-kit add-skill --tool opencode --project
+```
+
+Para omitir la pregunta usa `MOTION_PRESETS_KIT_SKIP_SKILL=1`.
+
+## Uso rápido
+
+```tsx
+import { motion } from "motion/react";
+import { fade, parentVariants } from "motion-presets-kit/presets";
+
+export function Hero() {
+	return (
+		<motion.div variants={parentVariants({ delayChildren: 0.12 })}>
+			<motion.h1 variants={fade({ direction: "up" })}>Hola</motion.h1>
+			<motion.p variants={fade({ direction: "up", excludeDelay: true })}>
+				Motion presets kit
+			</motion.p>
+		</motion.div>
+	);
+}
+```
+
+```tsx
+import { TextAnimate, Marquee, useCounter, Draggable } from "motion-presets-kit/components";
+```
+
+## Entry points
+
+| Import | Contenido |
+|---|---|
+| `motion-presets-kit` | schemas + presets + componentes |
+| `motion-presets-kit/presets` | `fade`, `slide`, `scale`, `clipReveal`, `parentVariants` |
+| `motion-presets-kit/components` | `TextAnimate`, `Marquee`, `Draggable`, `useCounter` |
+
+## Presets
+
+Todos los presets aceptan: `duration` (0.5), `delay` (0), `ease` (`[0.16, 1, 0.3, 1]`), `spring`, `excludeDelay` (false) y `reducedMotion` (true).
+
+### `fade(options?)`
+
+`direction` (`"up" | "down" | "left" | "right" | "none"`, default `"up"`), `distance` (60), `blur` (0), `scale` (1).
+
+```tsx
+<motion.div variants={fade({ direction: "left", distance: 40, blur: 8 })} />
+```
+
+### `slide(options?)`
+
+Desplazamiento puro, **sin `opacity`**. `direction` (default `"right"`), `distance` (100).
+
+```tsx
+<motion.div variants={slide({ direction: "right" })} />
+// initial: { x: -100 } → animate: { x: 0 }
+```
+
+### `scale(options?)`
+
+`from` (0.8) → `1` junto con `opacity: 0 → 1`.
+
+```tsx
+<motion.div variants={scale({ from: 0.5 })} />
+```
+
+### `clipReveal(options?)`
+
+Anima `clipPath` con insets por dirección y `scale` opcional.
+
+```tsx
+<motion.div variants={clipReveal({ direction: "up", scale: 1.1 })} />
+// initial: { clipPath: "inset(100% 0% 0% 0%)" } → animate: { clipPath: "inset(0% 0% 0% 0%)" }
+```
+
+### `parentVariants(options?)`
+
+Contenedor para stagger: `delayChildren` (0) y `startDelay` (0).
+
+```tsx
+<motion.div variants={parentVariants({ delayChildren: 0.1 })} initial="initial" whileInView="animate">
+	<motion.span variants={fade({ excludeDelay: true })} />
+	<motion.span variants={fade({ excludeDelay: true })} />
+</motion.div>
+```
+
+## Componentes y hooks
+
+### `<TextAnimate>`
+
+`text` (requerido), `as` (`"p"`), `by` (`"word" | "letter"`), `type` (`blurIn | slideUp | slideDown | slideLeft | slideRight | typeWriter`), `duration`, `startDelay`, `highlight: string[]`, `highlightClassName`.
+
+```tsx
+<TextAnimate text="Hola <strong>mundo</strong>" by="letter" type="blurIn" highlight={["mundo"]} />
+```
+
+El HTML inline se inyecta con `dangerouslySetInnerHTML`; sanitiza `text` si viene de input no confiable.
+
+### `<Marquee>`
+
+CSS puro con `@keyframes` dinámicos. `children` (requerido), `speed` (20 s/vuelta), `direction` (`"left"`), `pauseOnHover` (true), `gap` (`"2rem"`).
+
+```tsx
+<Marquee speed={30} direction="right" gap="1.5rem">
+	<span>Logo 1</span>
+	<span>Logo 2</span>
+</Marquee>
+```
+
+### `<Draggable>`
+
+Wrapper de `motion.div`. `axis` (`"both"`), `bounds` (`"parent" | "document" | {top,right,bottom,left}`), `snapToGrid: [number, number]`, `dragElastic`, `dragMomentum`, `dragControls`, `onDragStart`/`onDrag`/`onDragEnd`.
+
+```tsx
+<Draggable axis="x" bounds="parent" snapToGrid={[20, 20]}>
+	<div>Arrastrame</div>
+</Draggable>
+```
+
+Con `bounds="parent"` el elemento queda restringido a su contenedor; el contenedor debería poder medirse (`position: relative`).
+
+### `useCounter(ref, options?)`
+
+`from` (0), `to` (100), `decimals` (0), `prefix`, `suffix`, `separator` (","), `format`, `duration` (1). Escribe el valor formateado en `ref.current.textContent` y retorna `{ value, start, reset }`.
+
+```tsx
+const ref = useRef<HTMLSpanElement>(null);
+const { start, reset } = useCounter(ref, { to: 1250, separator: ",", suffix: " px" });
+return <span ref={ref} />;
+```
+
+## Casos límite documentados
+
+- **CL-001 — `excludeDelay` con stagger**: un hijo con `delay` propio sobrescribe el stagger del padre. Usa siempre `excludeDelay: true` en los hijos dentro de `parentVariants()`.
+- **CL-003 — ClipReveal con `border-radius`**: el `clip-path` se superpone al radio del borde; es una limitación conocida del `clip-path`.
+- **CL-005 — Counter con negativos**: el formateo preserva el signo (`-1,250`).
+- **CL-007 — Draggable con bounds inválidos**: si `top > bottom` o `left > right`, se emite un `warn()` y se ignoran los límites.
+- **CL-008 — SSR**: los presets retornan variants estáticas (sin `window`). Los componentes usan `whileInView`, que se activa solo en el cliente.
+- **CL-009 — Reduced motion**: con `prefers-reduced-motion: reduce` (y `reducedMotion: true`, por defecto), los presets saltan al estado final, `TextAnimate` muestra el texto sin animar y `Marquee` no reproduce el loop.
+
+## Desarrollo
+
+```bash
+pnpm playground   # demo Vite de todos los presets/componentes
+pnpm test         # build + tests con node:test
+pnpm typecheck
+pnpm lint
+pnpm build
+```

package/bin/cli.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+import {
+	detectTargets,
+	installSkill,
+	readPackageVersion,
+	SKILL_NAME,
+	TOOLS,
+} from "./skill.mjs";
+
+const HELP = `
+motion-presets-kit ${readPackageVersion()}
+
+Uso:
+  motion-presets-kit <comando> [opciones]
+
+Comandos:
+  add-skill           Instala la skill de ${SKILL_NAME} para agentes de IA.
+  help                Muestra esta ayuda.
+
+Opciones:
+  --global            Instala en el directorio de usuario (home).
+  --project           Instala en el proyecto actual (por defecto).
+  --tool <nombre>     ${Object.keys(TOOLS).join(" | ")} | all (por defecto: all).
+  --dir <ruta>        Directorio de skills explícito.
+  --force             Sobrescribe una skill ya instalada.
+
+Ejemplos:
+  npx motion-presets-kit add-skill
+  npx motion-presets-kit add-skill --global
+  npx motion-presets-kit add-skill --tool opencode --project
+`.trim();
+
+function parseArgs(argv) {
+	const options = {
+		command: null,
+		global: false,
+		project: false,
+		tool: "all",
+		dir: undefined,
+		force: false,
+	};
+
+	for (let index = 0; index < argv.length; index += 1) {
+		const arg = argv[index];
+		if (arg === "add-skill" || arg === "skill" || arg === "init") {
+			options.command = "add-skill";
+		} else if (arg === "help" || arg === "--help" || arg === "-h") {
+			options.command = "help";
+		} else if (arg === "--version" || arg === "-v") {
+			options.command = "version";
+		} else if (arg === "--global" || arg === "-g") {
+			options.global = true;
+		} else if (arg === "--project") {
+			options.project = true;
+		} else if (arg === "--force" || arg === "-f") {
+			options.force = true;
+		} else if (arg === "--tool") {
+			options.tool = argv[index + 1] ?? "all";
+			index += 1;
+		} else if (arg === "--dir") {
+			options.dir = argv[index + 1];
+			index += 1;
+		}
+	}
+	return options;
+}
+
+function run() {
+	const options = parseArgs(process.argv.slice(2));
+
+	if (options.command === "version") {
+		console.log(readPackageVersion());
+		return;
+	}
+	if (options.command === "help" || options.command === null) {
+		console.log(HELP);
+		return;
+	}
+
+	if (options.tool !== "all" && !(options.tool in TOOLS)) {
+		console.error(
+			`[${SKILL_NAME}] Herramienta desconocida: ${options.tool}. Usa: ${Object.keys(
+				TOOLS,
+			).join(", ")} o all.`,
+		);
+		process.exitCode = 1;
+		return;
+	}
+
+	const targets = detectTargets({
+		global: options.global && !options.project,
+		tool: options.tool,
+		dir: options.dir,
+	});
+	const results = installSkill(targets, { force: options.force });
+
+	for (const result of results) {
+		if (result.status === "installed") {
+			console.log(
+				`[${SKILL_NAME}] Skill instalada (${result.tool}): ${result.destination}`,
+			);
+		} else if (result.status === "exists") {
+			console.log(
+				`[${SKILL_NAME}] Ya existía (${result.tool}): ${result.destination}. Usa --force para sobrescribir.`,
+			);
+		} else {
+			console.error(
+				`[${SKILL_NAME}] Error al instalar (${result.tool}): ${result.error}`,
+			);
+			process.exitCode = 1;
+		}
+	}
+}
+
+run();

package/bin/skill.mjs

@@ -0,0 +1,94 @@
+import {
+	copyFileSync,
+	existsSync,
+	mkdirSync,
+	readFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+export const PACKAGE_ROOT = resolve(HERE, "..");
+export const SKILL_NAME = "motion-presets-kit";
+export const SKILL_SOURCE = join(
+	PACKAGE_ROOT,
+	"skill",
+	SKILL_NAME,
+	"SKILL.md",
+);
+
+/** Raíces por herramienta: proyecto y global. */
+export const TOOLS = {
+	opencode: { projectRoot: ".opencode", globalRoot: join(".config", "opencode") },
+	claude: { projectRoot: ".claude", globalRoot: ".claude" },
+	agents: { projectRoot: ".agents", globalRoot: ".agents" },
+};
+
+export function readPackageVersion() {
+	try {
+		const pkg = JSON.parse(
+			readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8"),
+		);
+		return pkg.version ?? "0.0.0";
+	} catch {
+		return "0.0.0";
+	}
+}
+
+/**
+ * Resuelve los directorios de skills donde instalar.
+ * Con `dir` se usa ese directorio; si no, auto-detecta las herramientas
+ * existentes (opencode, claude, agents) y cae en opencode si no hay ninguna.
+ */
+export function detectTargets({ global = false, tool = "all", dir } = {}) {
+	if (dir) return [{ tool: "custom", dir: resolve(dir) }];
+
+	const names = tool === "all" ? Object.keys(TOOLS) : [tool];
+	const all = names.map((name) => {
+		const root = global
+			? join(homedir(), TOOLS[name].globalRoot)
+			: resolve(process.cwd(), TOOLS[name].projectRoot);
+		return { tool: name, root, dir: join(root, "skills") };
+	});
+
+	const existing = all.filter((target) => existsSync(target.root));
+	if (existing.length > 0) {
+		return existing.map(({ tool: name, dir: skillsDir }) => ({
+			tool: name,
+			dir: skillsDir,
+		}));
+	}
+	if (tool !== "all") {
+		return all.map(({ tool: name, dir: skillsDir }) => ({
+			tool: name,
+			dir: skillsDir,
+		}));
+	}
+	return [{ tool: names[0], dir: all[0].dir }];
+}
+
+/**
+ * Copia la skill a cada directorio destino.
+ * Devuelve un resultado por destino con el estado de la operación.
+ */
+export function installSkill(targets, { force = false } = {}) {
+	return targets.map((target) => {
+		const destination = join(target.dir, SKILL_NAME, "SKILL.md");
+		try {
+			if (existsSync(destination) && !force) {
+				return { ...target, destination, status: "exists" };
+			}
+			mkdirSync(join(target.dir, SKILL_NAME), { recursive: true });
+			copyFileSync(SKILL_SOURCE, destination);
+			return { ...target, destination, status: "installed" };
+		} catch (error) {
+			return {
+				...target,
+				destination,
+				status: "error",
+				error: error instanceof Error ? error.message : String(error),
+			};
+		}
+	});
+}