@nocios/crudify-ui 1.3.1 → 1.3.2

package/MIGRATION_EXAMPLE.md

@@ -1,538 +0,0 @@
-# CrudifyDataProvider - Guía de Migración
-
-## 🎯 Objetivo
-
-Esta guía muestra cómo migrar de la implementación actual fragmentada (JWTSessionProvider + hooks individuales) al nuevo sistema unificado **CrudifyDataProvider**.
-
-## 📊 Comparación: Antes vs Después
-
-### ❌ ANTES (Sistema Fragmentado)
-
-```tsx
-// App.tsx - Múltiples providers y configuraciones
-import { JWTSessionProvider } from "./services/jwtSession"
-import { CrudifyProvider } from "@nocios/crudify-ui" // Conflicto con DataProvider
-
-function App() {
-  return (
-    <JWTSessionProvider>
-      <CrudifyProvider
-        env={process.env.VITE_TEST_ENV}
-        publicApiKey={process.env.VITE_TEST_PUBLIC_API_KEY}
-      >
-        <Routes>
-          {/* Tu aplicación */}
-        </Routes>
-      </CrudifyProvider>
-    </JWTSessionProvider>
-  )
-}
-
-// TestPage.tsx - Múltiples hooks y estado fragmentado
-import { useJWTSession } from "../services/jwtSession"
-import { useUserProfileWithJWT } from "../hooks/useUserProfileWithJWT"
-import { crudify } from "@nocios/crudify-ui"
-
-function TestPage() {
-  const { token, user, isAuthenticated, logout } = useJWTSession()
-  const { userProfile, loading, error, extendedData } = useUserProfileWithJWT({
-    autoFetch: isAuthenticated
-  })
-
-  // Problemas comunes:
-  // - "Crudify: Not initialized" errors
-  // - Doble inicialización entre providers
-  // - Estado desincronizado entre hooks
-  // - Configuración duplicada y fragmentada
-}
-```
-
-### ✅ DESPUÉS (Sistema Unificado)
-
-```tsx
-// App.tsx - Un solo provider con toda la funcionalidad
-import { CrudifyDataProvider } from "@nocios/crudify-ui"
-
-function App() {
-  return (
-    <CrudifyDataProvider
-      env="dev" // o desde process.env.VITE_TEST_ENV
-      publicApiKey="tu-api-key" // o desde process.env.VITE_TEST_PUBLIC_API_KEY
-      appName="Mi App"
-    >
-      <Routes>
-        {/* Tu aplicación */}
-      </Routes>
-    </CrudifyDataProvider>
-  )
-}
-
-// TestPage.tsx - Hooks simples y estado unificado
-import { useCrudifyAuth, useCrudifyUser, useCrudifyData } from "@nocios/crudify-ui"
-
-function TestPage() {
-  const { isAuthenticated, token, user, logout } = useCrudifyAuth()
-  const { userProfile, profileLoading, extendedData } = useCrudifyUser()
-  const { readItems, isInitialized } = useCrudifyData()
-
-  // Beneficios:
-  // ✅ Sin errores de inicialización
-  // ✅ Estado siempre sincronizado
-  // ✅ Configuración centralizada
-  // ✅ Hooks más simples y robustos
-}
-```
-
-## 🔄 Migración Paso a Paso
-
-### Paso 1: Actualizar npm-crudify-ui
-
-```bash
-npm update @nocios/crudify-ui
-```
-
-### Paso 2: Reemplazar Providers
-
-**Antes:**
-```tsx
-import { JWTSessionProvider } from "./services/jwtSession"
-
-function App() {
-  return (
-    <JWTSessionProvider>
-      {/* tu app */}
-    </JWTSessionProvider>
-  )
-}
-```
-
-**Después:**
-```tsx
-import { CrudifyDataProvider } from "@nocios/crudify-ui"
-
-function App() {
-  return (
-    <CrudifyDataProvider
-      env="dev" // Configuración directa o desde env vars
-      publicApiKey="your-key"
-      appName="Your App"
-    >
-      {/* tu app */}
-    </CrudifyDataProvider>
-  )
-}
-```
-
-### Paso 3: Migrar Hooks de Autenticación
-
-**Antes:**
-```tsx
-import { useJWTSession } from "../services/jwtSession"
-
-function Component() {
-  const { token, user, isAuthenticated, logout } = useJWTSession()
-  // ...
-}
-```
-
-**Después:**
-```tsx
-import { useCrudifyAuth } from "@nocios/crudify-ui"
-
-function Component() {
-  const { token, user, isAuthenticated, logout } = useCrudifyAuth()
-  // ¡Misma API! Sin cambios en el código
-}
-```
-
-### Paso 4: Migrar Hooks de Usuario
-
-**Antes:**
-```tsx
-import { useUserProfileWithJWT } from "../hooks/useUserProfileWithJWT"
-
-function Component() {
-  const {
-    userProfile,
-    loading: profileLoading,
-    error: profileError,
-    extendedData
-  } = useUserProfileWithJWT({ autoFetch: true })
-  // ...
-}
-```
-
-**Después:**
-```tsx
-import { useCrudifyUser } from "@nocios/crudify-ui"
-
-function Component() {
-  const {
-    userProfile,
-    profileLoading,
-    profileError,
-    extendedData
-  } = useCrudifyUser({ autoFetch: true })
-  // ¡Misma API! Sin cambios en el código
-}
-```
-
-### Paso 5: Migrar Operaciones CRUD
-
-**Antes:**
-```tsx
-import { crudify } from "@nocios/crudify-ui"
-
-async function loadUsers() {
-  try {
-    // Posible error: "Crudify: Not initialized"
-    const response = await crudify.readItems("users", { limit: 10 })
-    return response.data
-  } catch (error) {
-    console.error("Error:", error)
-  }
-}
-```
-
-**Después:**
-```tsx
-import { useCrudifyData } from "@nocios/crudify-ui"
-
-function Component() {
-  const { readItems, isReady } = useCrudifyData()
-
-  async function loadUsers() {
-    if (!isReady()) {
-      console.warn("Crudify not ready yet")
-      return
-    }
-
-    try {
-      // Sin errores de inicialización garantizado
-      const response = await readItems("users", { limit: 10 })
-      return response.data
-    } catch (error) {
-      console.error("Error:", error)
-    }
-  }
-}
-```
-
-## 🚀 Ejemplo Completo Migrado
-
-### TestPage.tsx - Versión Migrada
-
-```tsx
-import React from "react"
-import {
-  Box, Container, Paper, Typography, Button,
-  Divider, Alert, CircularProgress
-} from "@mui/material"
-import { useNavigate } from "react-router-dom"
-import {
-  useCrudifyAuth,
-  useCrudifyUser,
-  useCrudifyConfig
-} from "@nocios/crudify-ui"
-
-const TestPage: React.FC = () => {
-  const navigate = useNavigate()
-
-  // 🔐 Autenticación unificada
-  const {
-    isAuthenticated,
-    token,
-    user,
-    logout,
-    loading: authLoading
-  } = useCrudifyAuth()
-
-  // 👤 Datos de usuario desde BD
-  const {
-    userProfile,
-    profileLoading,
-    profileError,
-    extendedData,
-    refreshProfile
-  } = useCrudifyUser({ autoFetch: isAuthenticated })
-
-  // ⚙️ Configuración actual
-  const { config, isConfigured, getDebugInfo } = useCrudifyConfig()
-
-  const handleLogout = () => {
-    logout()
-    navigate("/")
-  }
-
-  const handleGoToDashboard = () => {
-    navigate("/")
-  }
-
-  // 🚫 Guard: Usuario no autenticado
-  if (!isAuthenticated) {
-    return (
-      <Container maxWidth="md" sx={{ minHeight: "100vh", display: "flex", alignItems: "center" }}>
-        <Paper elevation={3} sx={{ p: 4, width: "100%", textAlign: "center" }}>
-          <Typography variant="h4" color="error" gutterBottom>
-            No estás logueado
-          </Typography>
-          <Typography variant="body1" sx={{ mb: 3 }}>
-            Debes iniciar sesión para ver esta página.
-          </Typography>
-          <Button variant="contained" onClick={() => navigate("/")} size="large">
-            Ir al Login
-          </Button>
-        </Paper>
-      </Container>
-    )
-  }
-
-  // 📊 Datos unificados para mostrar
-  const userData = {
-    // Sistema de autenticación
-    authentication: {
-      isAuthenticated,
-      hasToken: !!token,
-      tokenLength: token?.length || 0,
-      userEmail: user?.email || null,
-      userId: user?.sub || null,
-      expiration: user?.exp ? new Date(user.exp * 1000).toISOString() : null
-    },
-    // Perfil desde base de datos
-    profile: {
-      loading: profileLoading,
-      error: profileError,
-      hasProfileData: !!userProfile,
-      totalFields: extendedData?.totalFields || 0,
-      basicProfile: userProfile,
-      displayData: extendedData?.displayData || null
-    },
-    // Configuración actual
-    configuration: {
-      isConfigured,
-      env: config?.env,
-      appName: config?.appName,
-      configSources: config?.configSource
-    }
-  }
-
-  return (
-    <Container maxWidth="md" sx={{ minHeight: "100vh", py: 4 }}>
-      <Paper elevation={3} sx={{ p: 4, width: "100%" }}>
-
-        {/* 🎉 Encabezado de éxito */}
-        <Box sx={{ mb: 4, textAlign: "center" }}>
-          <Typography variant="h3" component="h1" gutterBottom sx={{ color: "primary.main" }}>
-            🎉 Usuario Logueado Exitosamente
-          </Typography>
-          <Typography variant="h6" color="text.secondary">
-            Bienvenido al nuevo sistema unificado CrudifyDataProvider
-          </Typography>
-        </Box>
-
-        <Divider sx={{ my: 3 }} />
-
-        {/* 🔐 Datos de autenticación JWT */}
-        <Box sx={{ mb: 4 }}>
-          <Typography variant="h5" gutterBottom sx={{ color: "secondary.main" }}>
-            🔐 Datos de Autenticación (JWT):
-          </Typography>
-
-          <Box sx={{ mt: 2, mb: 3 }}>
-            <Typography variant="h6" sx={{ mb: 1 }}>
-              👤 <strong>Usuario:</strong> {user?.email || "Sin email"}
-            </Typography>
-            <Typography variant="h6" sx={{ mb: 1 }}>
-              🆔 <strong>User ID:</strong> {user?.sub || "No definido"}
-            </Typography>
-            <Typography variant="h6" sx={{ mb: 1 }}>
-              ✅ <strong>Estado:</strong> {isAuthenticated ? "Autenticado (CrudifyDataProvider)" : "No autenticado"}
-            </Typography>
-            <Typography variant="h6" sx={{ mb: 1 }}>
-              🎟️ <strong>JWT Token:</strong> {token ? "Presente" : "No disponible"}
-              {token && <span style={{ fontSize: '0.8em', color: '#666' }}> ({token.length} caracteres)</span>}
-            </Typography>
-            <Typography variant="h6" sx={{ mb: 1 }}>
-              ⏰ <strong>Token expira:</strong> {user?.exp ? new Date(user.exp * 1000).toLocaleString() : "No disponible"}
-            </Typography>
-          </Box>
-        </Box>
-
-        <Divider sx={{ my: 3 }} />
-
-        {/* 👤 Datos del perfil de usuario */}
-        <Box sx={{ mb: 4 }}>
-          <Typography variant="h5" gutterBottom sx={{ color: "primary.main" }}>
-            👤 Perfil de Usuario (Base de Datos):
-          </Typography>
-
-          {profileLoading && (
-            <Box sx={{ display: 'flex', alignItems: 'center', mb: 2 }}>
-              <CircularProgress size={20} sx={{ mr: 1 }} />
-              <Typography>Cargando perfil automáticamente...</Typography>
-            </Box>
-          )}
-
-          {profileError && (
-            <Alert severity="error" sx={{ mb: 2 }}>
-              Error al cargar perfil: {profileError}
-              <Button onClick={refreshProfile} size="small" sx={{ ml: 1 }}>
-                Reintentar
-              </Button>
-            </Alert>
-          )}
-
-          {userProfile && !profileLoading && (
-            <Box sx={{ mb: 2 }}>
-              <Typography variant="h6" sx={{ mb: 1 }}>
-                👤 <strong>ID:</strong> {extendedData?.displayData?.id || 'No disponible'}
-              </Typography>
-              <Typography variant="h6" sx={{ mb: 1 }}>
-                📧 <strong>Email:</strong> {extendedData?.displayData?.email || 'No disponible'}
-              </Typography>
-              <Typography variant="h6" sx={{ mb: 1 }}>
-                🏷️ <strong>Username:</strong> {extendedData?.displayData?.username || 'No disponible'}
-              </Typography>
-              <Typography variant="h6" sx={{ mb: 1 }}>
-                👨‍💼 <strong>Nombre Completo:</strong> {extendedData?.displayData?.fullName || 'No disponible'}
-              </Typography>
-              <Typography variant="h6" sx={{ mb: 1 }}>
-                🎭 <strong>Rol:</strong> {extendedData?.displayData?.role || 'No definido'}
-              </Typography>
-              <Typography variant="h6" sx={{ mb: 1 }}>
-                🔢 <strong>Total campos BD:</strong> {extendedData?.totalFields || 0}
-              </Typography>
-            </Box>
-          )}
-        </Box>
-
-        <Divider sx={{ my: 3 }} />
-
-        {/* ⚙️ Información de configuración */}
-        <Box sx={{ mb: 4 }}>
-          <Typography variant="h5" gutterBottom sx={{ color: "info.main" }}>
-            ⚙️ Configuración Actual:
-          </Typography>
-
-          <Box sx={{ mt: 2, mb: 3 }}>
-            <Typography variant="h6" sx={{ mb: 1 }}>
-              🌍 <strong>Entorno:</strong> {config?.env || "No definido"}
-            </Typography>
-            <Typography variant="h6" sx={{ mb: 1 }}>
-              🏢 <strong>App Name:</strong> {config?.appName || "No definido"}
-            </Typography>
-            <Typography variant="h6" sx={{ mb: 1 }}>
-              ✅ <strong>Configurado:</strong> {isConfigured ? "Sí" : "No"}
-            </Typography>
-            <Typography variant="h6" sx={{ mb: 1 }}>
-              📚 <strong>Fuentes:</strong> {config?.configSource ? JSON.stringify(config.configSource) : "No disponible"}
-            </Typography>
-          </Box>
-        </Box>
-
-        <Divider sx={{ my: 3 }} />
-
-        {/* 📋 JSON completo para debugging */}
-        <Box sx={{ mb: 4 }}>
-          <Typography variant="h5" gutterBottom sx={{ color: "secondary.main" }}>
-            📋 Datos Completos (Debug):
-          </Typography>
-
-          <Paper
-            elevation={1}
-            sx={{
-              p: 3,
-              backgroundColor: "grey.50",
-              overflow: "auto",
-              maxHeight: "400px"
-            }}
-          >
-            <pre style={{
-              margin: 0,
-              fontFamily: "monospace",
-              fontSize: "14px",
-              whiteSpace: "pre-wrap",
-              wordBreak: "break-word"
-            }}>
-              {JSON.stringify({
-                userData,
-                debugInfo: getDebugInfo()
-              }, null, 2)}
-            </pre>
-          </Paper>
-        </Box>
-
-        <Divider sx={{ my: 3 }} />
-
-        {/* 🎛️ Acciones */}
-        <Box sx={{ display: "flex", gap: 2, justifyContent: "center", flexWrap: "wrap" }}>
-          <Button
-            variant="contained"
-            color="primary"
-            onClick={handleGoToDashboard}
-            size="large"
-          >
-            Ir al Dashboard
-          </Button>
-
-          <Button
-            variant="outlined"
-            color="secondary"
-            onClick={handleLogout}
-            size="large"
-          >
-            Cerrar Sesión
-          </Button>
-
-          <Button
-            variant="outlined"
-            color="info"
-            onClick={refreshProfile}
-            size="large"
-            disabled={profileLoading}
-          >
-            {profileLoading ? "Cargando..." : "Refresh Profile"}
-          </Button>
-        </Box>
-      </Paper>
-    </Container>
-  )
-}
-
-export default TestPage
-```
-
-## 🛡️ Garantías de Compatibilidad
-
-### ✅ Para crudia-ui (Producción)
-- **Sin cambios**: El sistema legacy sigue funcionando exactamente igual
-- **Imports preserved**: Todos los exports existentes se mantienen
-- **API compatibility**: 100% compatible con código existente
-- **Storage compatibility**: Usa la misma clave `"authToken"`
-
-### ✅ Para crudify-ui (Desarrollo)
-- **API familiar**: Los nuevos hooks tienen la misma interfaz que los actuales
-- **Migración gradual**: Puedes migrar componente por componente
-- **Mejor error handling**: Sin más errores "Crudify: Not initialized"
-- **Estado unificado**: Un solo source of truth para toda la app
-
-## 🚀 Beneficios Inmediatos
-
-1. **Sin errores de inicialización**: El doble provider problem está resuelto
-2. **Estado sincronizado**: Token, usuario y configuración siempre consistentes
-3. **Configuración simplificada**: Un solo provider con toda la funcionalidad
-4. **Mejor debugging**: Información completa disponible en `getDebugInfo()`
-5. **Cross-tab sync**: Los tokens se sincronizan automáticamente entre pestañas
-6. **Automatic cleanup**: Tokens expirados se limpian automáticamente
-
-## 🔄 Migración Incremental
-
-Puedes migrar gradualmente:
-
-1. **Fase 1**: Envolver la app con `CrudifyDataProvider`
-2. **Fase 2**: Migrar componentes de autenticación usando `useCrudifyAuth`
-3. **Fase 3**: Migrar componentes de usuario usando `useCrudifyUser`
-4. **Fase 4**: Migrar operaciones CRUD usando `useCrudifyData`
-5. **Fase 5**: Remover providers y hooks legacy
-
-¡El nuevo sistema está listo para usar! 🎉