npm package: @nocios/crudify-components
Description: Biblioteca de componentes UI para Crudify
Author: Nocios
Latest version: 2.0.88

# @nocios/crudify-components

[![npm version](https://badge.fury.io/js/%40nocios%2Fcrudify-ui.svg)](https://badge.fury.io/js/%40nocios%2Fcrudify-ui)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.1.3-3178c6.svg)](https://typescriptlang.org/)
[![React](https://img.shields.io/badge/React-19.1.0-61dafb.svg)](https://reactjs.org/)

**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](docs/overview.md)** - Comprehensive component and API reference
- 🔒 **[Security Guide](docs/security.md)** - Security features and best practices
- 🏗️ **[Architecture](docs/architecture.md)** - Library design and patterns
- 🔧 **[Migration Guide](docs/migration.md)** - Upgrade instructions between versions
- 💡 **[Examples](docs/examples.md)** - 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

```ts
// 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

```bash
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.

````tsx
// ✅ 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

```tsx
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

```tsx
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:

```tsx
// 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

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

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

  const handleLogin = async () => {
    const result = await login('user@example.com', 'password');
  };

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

### useUserData - Datos del Usuario

```tsx
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

```tsx
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

```tsx
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

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

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

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

```tsx
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`:

```tsx
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

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

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

### Error Handler

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

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

## 🚀 Ejemplo Completo

```tsx
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:

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

## 🌐 Internacionalización

```tsx
// 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](./README_DEPTH.md).

## 📄 Licencia

MIT © [Nocios](https://github.com/nocios)

---

**¿Necesitas ayuda?** Consulta [README_DEPTH.md](./README_DEPTH.md) para documentación completa.