\n Hook de React para gestión avanzada de formularios con validación, seguridad y TypeScript\n
\n\n## 📋 Tabla de Contenidos\n\n- [Instalación](#-instalación)\n- [Inicio Rápido](#-inicio-rápido)\n- [Características](#-características)\n- [Modos de Uso](#️-modos-de-uso)\n- [Ejemplos](#-ejemplos)\n- [Validación con Zod](#-validación-con-zod)\n- [API Reference](#-api-reference)\n- [Seguridad](#-seguridad)\n- [Mejores Prácticas](#-mejores-prácticas)\n\n---\n\n## 🚀 Instalación\n\n```bash\nnpm install usetargethandler\n```\n\n### Actualizar versión\n\n```bash\nnpm update usetargethandler\n```\n\n---\n\n## ⚡ Inicio Rápido\n\n### Importación\n\n#### JavaScript\n```javascript\nimport { useTargetHandler } from \"usetargethandler\";\n```\n\n#### TypeScript\n```typescript\nimport { useTargetHandler, ValidationRules, FormValues } from \"usetargethandler\";\n```\n\n#### TypeScript con Zod\n```typescript\nimport { useTargetHandler, z } from \"usetargethandler\";\n```\n\n### Ejemplo Básico\n\n```typescript\nimport { useTargetHandler } from \"usetargethandler\";\n\nfunction LoginForm() {\n const [target, handleTarget, handleSubmit, errors] = useTargetHandler(\n { email: \"\", password: \"\" },\n {\n email: {\n required: true,\n pattern: /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/,\n patternMessage: \"Email inválido\"\n },\n password: {\n required: true,\n minLength: 6,\n minLengthMessage: \"Mínimo 6 caracteres\"\n }\n }\n );\n\n const onSubmit = (data) => {\n console.log(\"Formulario válido:\", data);\n };\n\n return (\n \n );\n}\n```\n\n---\n\n## ✨ Características\n\n### 🎉 TypeScript y Validación\n- **Soporte TypeScript completo (v1.4.0+)** - Tipos completos, funciona sin configuración adicional\n- **Zod integrado (v1.4.0+)** - Validación avanzada sin instalación adicional\n- **Validaciones personalizadas** - Sistema de reglas flexible y extensible\n- **Detección automática** - El hook detecta si usas Zod o ValidationRules nativas\n\n### 🔒 Seguridad\n- **Protección XSS** - Sanitización automática con DOMPurify\n- **Protección CSRF** - Token automático en solicitudes HTTP\n- **Rate Limiting** - Prevención de spam y ataques\n- **Validación de entrada** - Filtrado de datos maliciosos\n\n### 🚀 Rendimiento y UX\n- **Gestión de estado en tiempo real** - Actualización instantánea de campos\n- **Persistencia de datos** - LocalStorage o SessionStorage configurable\n- **Estados de carga** - Indicadores `isLoading` integrados\n- **Reinicialización automática** - Limpieza del formulario tras envío\n\n### 🔗 Integración HTTP\n- **useHttpRequest integrado** - Llamadas API simplificadas\n- **Sentry opcional** - Monitoreo de errores y eventos\n- **Variables de entorno** - Configuración flexible de API URL\n- **Respuestas tipadas** - Manejo de respuestas con TypeScript\n\n---\n\n## ⚙️ Modos de Uso\n\n### 1️⃣ Modo Básico (Solo Validación)\n\nPerfecto para formularios simples sin llamadas API.\n\n```typescript\nimport { useTargetHandler } from \"usetargethandler\";\n\nconst [target, handleTarget, handleSubmit, errors] = useTargetHandler(\n { email: \"\", password: \"\" },\n {\n email: { required: true, pattern: /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/ },\n password: { required: true, minLength: 6 }\n },\n { storageType: \"session\", storageKey: \"loginForm\" },\n { enableCSRF: false, rateLimit: 1000 }\n);\n```\n\n### 2️⃣ Modo HTTP (Con useHttpRequest)\n\nPara formularios que necesitan comunicarse con APIs.\n\n```typescript\nimport { useTargetHandler } from \"usetargethandler\";\nimport { useHttpRequest } from \"usehttprequest\";\n\nconst [target, handleTarget, handleSubmit, errors, httpRequest] = useTargetHandler(\n { email: \"\", password: \"\" },\n {\n email: { required: true, pattern: /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/ },\n password: { required: true, minLength: 6 }\n },\n { storageType: \"session\", storageKey: \"loginForm\" },\n { enableCSRF: true, rateLimit: 3000 },\n useHttpRequest // ← Habilita funcionalidades HTTP\n);\n\n// Acceso a funcionalidades HTTP\nconst { \n apiCall, // Llamadas a la API\n apiResponse, // Respuesta de la última llamada\n isLoading, // Estado de carga\n error, // Errores HTTP\n SentryError, // Logging de errores\n SentryInfo // Logging de información\n} = httpRequest;\n```\n\n### Variables de Entorno (Modo HTTP)\n\n```bash\n# Vite\nVITE_API_URL=https://api.ejemplo.com\n\n# Create React App\nREACT_APP_API_URL=https://api.ejemplo.com\n```\n\n> ⚠️ **Importante:** Reinicia el servidor de desarrollo después de modificar `.env`\n\n---\n\n## 📖 Ejemplos\n\n### Ejemplo 1: Formulario de Login con HTTP\n\n```typescript\nimport React from \"react\";\nimport { useTargetHandler } from \"usetargethandler\";\nimport { useHttpRequest } from \"usehttprequest\";\n\nexport function LoginForm() {\n const [target, handleTarget, handleSubmit, errors, httpRequest] = useTargetHandler(\n { email: \"\", password: \"\" },\n {\n email: {\n required: true,\n requiredMessage: \"Email es requerido\",\n pattern: /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/,\n patternMessage: \"Email inválido\",\n },\n password: {\n required: true,\n minLength: 6,\n minLengthMessage: \"Mínimo 6 caracteres\",\n },\n },\n { storageType: \"session\", storageKey: \"loginForm\" },\n { enableCSRF: true, rateLimit: 3000 },\n useHttpRequest\n );\n\n const { apiCall, isLoading, error, apiResponse, SentryError, SentryInfo } = httpRequest;\n\n const onSubmit = async (data: typeof initialValues) => {\n try {\n SentryInfo(\"Intentando login\", { email: data.email });\n \n await apiCall(\"POST\", \"/auth/login\", data);\n\n if (apiResponse) {\n localStorage.setItem(\"token\", apiResponse.token);\n window.location.href = \"/dashboard\";\n }\n\n if (error) {\n SentryError(\"Error en login\", error);\n }\n } catch (err) {\n console.error(\"Error:\", err);\n }\n };\n\n return (\n \n );\n}\n```\n\n### Ejemplo 2: Formulario Completo de Registro\n\n```typescript\nimport { useTargetHandler } from \"usetargethandler\";\n\nexport function RegisterForm() {\n const [target, handleTarget, handleSubmit, errors] = useTargetHandler(\n {\n nombre: \"\",\n email: \"\",\n password: \"\",\n confirmPassword: \"\",\n age: \"\",\n terms: false,\n ciudad: \"\",\n },\n {\n nombre: {\n required: true,\n requiredMessage: \"El nombre es obligatorio\",\n pattern: /^[a-zA-Z\\s]+$/,\n patternMessage: \"Solo letras permitidas\",\n minLength: 2,\n maxLength: 50,\n },\n email: {\n required: true,\n pattern: /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/,\n patternMessage: \"Email inválido\",\n },\n password: {\n required: true,\n minLength: 8,\n minLengthMessage: \"Mínimo 8 caracteres\",\n },\n confirmPassword: {\n required: true,\n matches: \"password\",\n matchMessage: \"Las contraseñas no coinciden\",\n },\n age: {\n required: true,\n min: 18,\n max: 99,\n requiredMessage: \"Debes ser mayor de 18 años\",\n },\n terms: {\n checked: true,\n checkedMessage: \"Debes aceptar los términos\",\n },\n ciudad: {\n selected: true,\n selectedMessage: \"Selecciona una ciudad\",\n },\n },\n { storageType: \"local\", storageKey: \"registerForm\" },\n { enableCSRF: true, rateLimit: 3000 }\n );\n\n const onSubmit = (data) => {\n console.log(\"Registro exitoso:\", data);\n };\n\n return (\n \n );\n}\n```\n\n### Métodos HTTP - Casos de Uso Reales\n\n#### GET - Obtener Datos\n\n```typescript\n// Obtener lista de usuarios con paginación\nconst fetchUsers = async (page = 1, limit = 10) => {\n await apiCall(\"GET\", `/users?page=${page}&limit=${limit}`);\n if (apiResponse) {\n console.log(\"Usuarios:\", apiResponse.data);\n console.log(\"Total:\", apiResponse.total);\n }\n};\n\n// Buscar usuarios con filtros\nconst searchUsers = async (searchTerm: string) => {\n await apiCall(\"GET\", `/users/search?q=${encodeURIComponent(searchTerm)}&status=active`);\n};\n\n// Obtener detalle de un usuario específico\nconst getUserById = async (userId: string) => {\n await apiCall(\"GET\", `/users/${userId}`);\n};\n```\n\n#### POST - Crear Recursos\n\n```typescript\n// Crear nuevo usuario con validación\nconst createUser = async (formData: typeof target) => {\n await apiCall(\"POST\", \"/users\", {\n name: formData.name,\n email: formData.email,\n role: \"user\",\n metadata: {\n createdAt: new Date().toISOString(),\n source: \"web\"\n }\n });\n \n if (apiResponse) {\n console.log(\"Usuario creado:\", apiResponse.id);\n // Redirigir o mostrar mensaje de éxito\n }\n};\n\n// Subir archivo con FormData\nconst uploadAvatar = async (file: File, userId: string) => {\n const formData = new FormData();\n formData.append(\"avatar\", file);\n formData.append(\"userId\", userId);\n \n await apiCall(\"POST\", \"/upload/avatar\", formData);\n};\n\n// Login con credenciales\nconst login = async () => {\n await apiCall(\"POST\", \"/auth/login\", {\n email: target.email,\n password: target.password,\n rememberMe: true\n });\n \n if (apiResponse?.token) {\n localStorage.setItem(\"authToken\", apiResponse.token);\n window.location.href = \"/dashboard\";\n }\n};\n```\n\n#### PUT - Actualizar Completamente\n\n```typescript\n// Actualizar perfil completo del usuario\nconst updateUserProfile = async (userId: string) => {\n await apiCall(\"PUT\", `/users/${userId}`, {\n name: target.name,\n email: target.email,\n phone: target.phone,\n address: {\n street: target.street,\n city: target.city,\n country: target.country\n },\n preferences: {\n language: \"es\",\n notifications: true\n }\n });\n};\n```\n\n#### PATCH - Actualizar Parcialmente\n\n```typescript\n// Actualizar solo el email del usuario\nconst updateEmail = async (userId: string, newEmail: string) => {\n await apiCall(\"PATCH\", `/users/${userId}`, { \n email: newEmail \n });\n};\n\n// Cambiar estado de un pedido\nconst updateOrderStatus = async (orderId: string, status: string) => {\n await apiCall(\"PATCH\", `/orders/${orderId}`, { \n status,\n updatedAt: new Date().toISOString()\n });\n};\n\n// Activar/desactivar usuario\nconst toggleUserStatus = async (userId: string, isActive: boolean) => {\n await apiCall(\"PATCH\", `/users/${userId}/status`, { \n isActive \n });\n};\n```\n\n#### DELETE - Eliminar Recursos\n\n```typescript\n// Eliminar usuario con confirmación\nconst deleteUser = async (userId: string) => {\n if (confirm(\"¿Estás seguro de eliminar este usuario?\")) {\n await apiCall(\"DELETE\", `/users/${userId}`);\n \n if (!error) {\n console.log(\"Usuario eliminado exitosamente\");\n // Actualizar lista o redirigir\n }\n }\n};\n\n// Eliminar múltiples elementos\nconst deleteBatch = async (userIds: string[]) => {\n await apiCall(\"DELETE\", \"/users/batch\", { \n ids: userIds \n });\n};\n\n// Soft delete (marcar como eliminado)\nconst softDeleteUser = async (userId: string) => {\n await apiCall(\"PATCH\", `/users/${userId}`, { \n deletedAt: new Date().toISOString(),\n isDeleted: true \n });\n};\n```\n\n#### Ejemplo Completo: Sistema de Paginación\n\n```typescript\nimport { useState, useEffect } from \"react\";\nimport { useTargetHandler } from \"usetargethandler\";\nimport { useHttpRequest } from \"usehttprequest\";\n\nexport function UsersList() {\n const [page, setPage] = useState(1);\n const [users, setUsers] = useState([]);\n const [totalPages, setTotalPages] = useState(0);\n\n const [target, handleTarget, handleSubmit, errors, httpRequest] = useTargetHandler(\n { search: \"\" },\n {},\n {},\n { enableCSRF: true, rateLimit: 2000 },\n useHttpRequest\n );\n\n const { apiCall, isLoading, apiResponse } = httpRequest;\n\n // Cargar usuarios al montar o cambiar página\n useEffect(() => {\n fetchUsers(page);\n }, [page]);\n\n const fetchUsers = async (currentPage: number) => {\n await apiCall(\"GET\", `/users?page=${currentPage}&limit=20&sort=createdAt:desc`);\n \n if (apiResponse) {\n setUsers(apiResponse.data);\n setTotalPages(Math.ceil(apiResponse.total / 20));\n }\n };\n\n // Buscar usuarios con debounce\n const handleSearch = async (searchTerm: string) => {\n if (searchTerm.length > 2) {\n await apiCall(\"GET\", `/users/search?q=${encodeURIComponent(searchTerm)}`);\n if (apiResponse) {\n setUsers(apiResponse.data);\n }\n } else if (searchTerm.length === 0) {\n fetchUsers(page);\n }\n };\n\n return (\n