@nocios/crudify-components

UI component library for the Crudify ecosystem - Modern React components with authentication, session management, and CRUD operations.

Biblioteca completa de componentes UI y hooks de React para aplicaciones Crudify. Proporciona autenticación moderna, manejo de sesiones y una API unificada.

🚀 Características

• 🔐 Autenticación Moderna: Sistema completo con Refresh Token Pattern
• ⚡ Manejo de Sesiones: Persistencia automática y sincronización cross-tab
• 🎨 Componentes UI: Componentes React listos con Material-UI
• 🪝 React Hooks: Hooks especializados para CRUD y autenticación
• 🔄 API Unificada: Re-exporta completamente @nocios/crudify-sdk
• 🌍 Internacionalización: Soporte para múltiples idiomas
• 📱 TypeScript: Completamente tipado

📖 Documentation

• 📋 Complete Documentation - Comprehensive component and API reference
• 🔒 Security Guide - Security features and best practices
• 🏗️ Architecture - Library design and patterns
• 🔧 Migration Guide - Upgrade instructions between versions
• 💡 Examples - Real-world usage examples

⚠️ Migración de Contratos de Tipos (2026-02-16)

Esta versión incluye migración de contratos compartidos a @nocios/frontend-types.

• Ahora debes usar preferentemente los tipos canónicos exportados por esta librería:
  • CrudifyResponse
  • CrudifyTransactionResponse
  • TransactionResponseData
  • ActionDefinition
  • ActionPosition

Guía rápida de reemplazo

// Antes (ya eliminado en esta versión)
import type { CrudifyApiResponse, IAction } from '@nocios/crudify-components';

// Ahora
import type { CrudifyResponse, ActionDefinition } from '@nocios/crudify-components';

📦 Instalación

npm install @nocios/crudify-components

# Peer dependencies
npm install @mui/material @mui/icons-material react react-dom

🏗️ Configuración

⚙️ Sistema de Configuración

La librería utiliza un sistema de configuración por prioridad para obtener credenciales y configuración:

1. Props directos (máxima prioridad) - Override manual
2. Variables de entorno (desarrollo local) - Se leen desde .env
3. Cookies (producción) - Las establece Lambda automáticamente
4. Error - Si no hay configuración válida

🏗️ Arquitectura

📋 Configuración Centralizada

IMPORTANTE: La configuración ahora se pasa al SessionProvider en lugar de individual componentes como CrudifyLogin. Esta arquitectura centralizada garantiza que todos los componentes tengan acceso a la misma configuración.

// ✅ CORRECTO - Nueva arquitectura
<SessionProvider config={{ publicApiKey: "...", env: "dev" }}>
  <CrudifyLogin />
</SessionProvider>

**Requisito**: `CrudifyLogin` debe estar dentro de un `SessionProvider` para funcionar correctamente.

## 🔧 Configuración para Desarrollo Local

#### 1. Crear archivo `.env` en tu proyecto

```bash
# .env (para desarrollo local)
VITE_TEST_PUBLIC_API_KEY=CRUD_tu_api_key_aqui
VITE_TEST_ENV=dev
VITE_TEST_LOGIN_ACTIONS=createUser,forgotPassword

2. Configurar Providers

import { SessionProvider, crudify } from '@nocios/crudify-components';

function App() {
  useEffect(() => {
    // Inicializar crudify (opcional)
    const initCrudify = async () => {
      const publicApiKey = import.meta.env.VITE_TEST_PUBLIC_API_KEY;
      const environment = import.meta.env.VITE_TEST_ENV || 'dev';

      if (publicApiKey) {
        crudify.config(environment);
        await crudify.init(publicApiKey, 'debug');
      }
    };

    initCrudify();
  }, []);

  return (
    <SessionProvider
      options={{
        autoRestore: true,
        enableLogging: process.env.NODE_ENV === 'development',
      }}
      config={{
        publicApiKey: import.meta.env.VITE_TEST_PUBLIC_API_KEY,
        env: import.meta.env.VITE_TEST_ENV,
        loginActions: import.meta.env.VITE_TEST_LOGIN_ACTIONS?.split(','),
      }}
    >
      <YourApp />
    </SessionProvider>
  );
}

3. Usar CrudifyLogin con configuración automática

import { CrudifyLogin } from '@nocios/crudify-components';

function LoginPage() {
  return (
    <CrudifyLogin
      onLoginSuccess={(userData) => {
        console.log('Login exitoso:', userData);
        // Navegar al dashboard
      }}
      onError={(error) => {
        console.error('Error en login:', error);
      }}
    />
  );
}

🌐 Configuración para Producción

En producción (staging/prod), NO uses variables de entorno. El Lambda de AWS se encarga de establecer las cookies automáticamente:

• publicApiKey → Cookie
• environment → Cookie
• loginActions → Cookie

La librería las detectará automáticamente:

// En producción, la configuración se lee de cookies automáticamente
<SessionProvider
  config={{
    appName: 'Mi App',
    colors: { primaryColor: '#1976d2' },
    // publicApiKey, env y loginActions se leen de cookies automáticamente
  }}
>
  <CrudifyLogin />
</SessionProvider>

🪝 Hooks Principales

useAuth - Autenticación

import { useAuth } from '@nocios/crudify-components';

function LoginComponent() {
  const { login, logout, isAuthenticated, isLoading } = useAuth();

  const handleLogin = async () => {
    const result = await login('[email protected]', 'password');
  };

  return isAuthenticated ? (
    <button onClick={logout}>Cerrar Sesión</button>
  ) : (
    <button onClick={handleLogin} disabled={isLoading}>
      Iniciar Sesión
    </button>
  );
}

useUserData - Datos del Usuario

import { useUserData } from '@nocios/crudify-components';

function UserProfile() {
  const { userData, sessionData, isLoading } = useUserData();

  if (isLoading) return <div>Cargando...</div>;

  return (
    <div>
      <h2>{userData?.fullName}</h2>
      <p>Email: {sessionData?.email}</p>
      <img src={userData?.avatar} alt="Avatar" />
    </div>
  );
}

useData - Operaciones CRUD

import { useData } from '@nocios/crudify-components';

function ProductManager() {
  const { create, read, update, remove } = useData();

  const createProduct = async () => {
    await create('products', { name: 'Nuevo Producto', price: 99.99 });
  };

  const getProducts = async () => {
    const products = await read('products', { limit: 10 });
  };

  return <button onClick={createProduct}>Crear Producto</button>;
}

🎨 Componentes UI

CrudifyLogin - Login Completo

import { CrudifyLogin, SessionProvider } from '@nocios/crudify-components';

function AuthPage() {
  return (
    <SessionProvider
      config={{
        appName: 'Mi App',
        logo: '/logo.png',
        colors: { primaryColor: '#1976d2' },
      }}
    >
      <CrudifyLogin
        onLoginSuccess={(userData) => {
          console.log('Login exitoso:', userData);
        }}
        language="es"
      />
    </SessionProvider>
  );
}

ProtectedRoute - Protección de Rutas

import { ProtectedRoute } from '@nocios/crudify-components';

function App() {
  return (
    <ProtectedRoute fallback={<LoginPage />}>
      <Dashboard />
    </ProtectedRoute>
  );
}

Policies - Gestión de Políticas Públicas

import { Policies, POLICY_ACTIONS, PolicyAction } from '@nocios/crudify-components';

function ModuleConfiguration() {
  const [policies, setPolicies] = useState([]);
  const availableFields = ['name', 'email', 'description', 'status'];

  return (
    <Policies
      policies={policies}
      onChange={setPolicies}
      availableFields={availableFields}
      errors={null}
      isSubmitting={false}
    />
  );
}

🔄 API de Crudify SDK

Re-exporta completamente @nocios/crudify-sdk:

import { crudify } from '@nocios/crudify-components';

// Usar directamente la API de crudify
const result = await crudify.create('users', userData);
const users = await crudify.read('users');

🛠️ Utilidades

JWT Utils

import { decodeJwtSafely, getCurrentUserEmail } from '@nocios/crudify-components';

const payload = decodeJwtSafely(token);
const email = getCurrentUserEmail();

Error Handler

import { handleCrudifyError, getErrorMessage } from '@nocios/crudify-components';

try {
  // operación
} catch (error) {
  const parsedError = handleCrudifyError(error);
  const userMessage = getErrorMessage(parsedError.code);
}

🚀 Ejemplo Completo

import React from 'react';
import { BrowserRouter, Routes, Route } from 'react-router-dom';
import { SessionProvider, ProtectedRoute, CrudifyLogin, useSessionContext } from '@nocios/crudify-components';

function Dashboard() {
  const { sessionData, logout } = useSessionContext();

  return (
    <div>
      <h1>Dashboard</h1>
      <p>Bienvenido, {sessionData?.email}</p>
      <button onClick={logout}>Cerrar Sesión</button>
    </div>
  );
}

function LoginPage() {
  return (
    <div style={{ maxWidth: '400px', margin: '0 auto' }}>
      <CrudifyLogin onLoginSuccess={(userData) => console.log('Login:', userData)} />
    </div>
  );
}

function App() {
  return (
    <SessionProvider>
      <BrowserRouter>
        <Routes>
          <Route path="/login" element={<LoginPage />} />
          <Route
            path="/dashboard"
            element={
              <ProtectedRoute fallback={<LoginPage />}>
                <Dashboard />
              </ProtectedRoute>
            }
          />
        </Routes>
      </BrowserRouter>
    </SessionProvider>
  );
}

📱 TypeScript

Tipos completos incluidos:

import type { CrudifyLoginProps, UseAuthReturn, UserProfile, TokenData } from '@nocios/crudify-components';

🌐 Internacionalización

// Idiomas soportados: 'en' | 'es'
<CrudifyLogin language="es" />

// Traducciones personalizadas
<CrudifyLogin
  translations={{
    login: { title: "Iniciar Sesión" }
  }}
/>

🔒 Seguridad

• ✅ Encriptación de tokens
• ✅ Refresh Token Pattern
• ✅ Validación automática
• ✅ Limpieza automática de tokens expirados

📚 Documentación Completa

Para documentación detallada, ejemplos avanzados y guías completas, consulta README_DEPTH.md.

📄 Licencia

MIT © Nocios

¿Necesitas ayuda? Consulta README_DEPTH.md para documentación completa.