botech-library 1.0.76 → 1.0.78

package/README.md

@@ -1,125 +1,308 @@
-# Botech Library
+# botech-library
 
-Una biblioteca de componentes React para sistemas escolares.
+Librería de componentes React compartida entre los sistemas web de **BO-TECH** (PASS, Seguimiento y otros). Publicada en npm y consumida como dependencia estándar en cada proyecto.
 
-## Componentes
+---
 
-### Header
+## Instalación
+
+```bash
+npm install botech-library
+```
+
+### Peer dependencies requeridas
+
+```bash
+npm install react react-dom axios sweetalert2
+```
+
+---
+
+## Componentes disponibles
+
+### Auth
+
+#### `LoginPage`
+
+Página de inicio de sesión con soporte para email/contraseña y Google SSO.
+
+```tsx
+import { LoginPage } from 'botech-library';
+
+<LoginPage
+  systemName="PASS"
+  leftPanelTitle={<>Simplicidad y<br />Seguridad Absoluta</>}
+  googleClientId={import.meta.env.VITE_GOOGLE_CLIENT_ID}
+  onLogin={async (email, password) => { /* lógica de login */ }}
+  onGoogleCredential={async (credential) => { /* lógica con JWT de Google */ }}
+  onForgotPassword={async (email) => ({ ok: true })}
+  onNavigateToRegister={() => navigate('/register-product-key')}
+/>
+```
+
+**Props:**
 
-El componente Header muestra información del sistema y la página actual.
+| Prop | Tipo | Descripción |
+|---|---|---|
+| `systemName` | `string` | Nombre del sistema mostrado en el panel izquierdo |
+| `leftPanelTitle` | `ReactNode` | Título decorativo del panel izquierdo |
+| `quote` | `string?` | Cita inspiracional (opcional) |
+| `quoteAuthor` | `string?` | Autor de la cita (opcional) |
+| `googleClientId` | `string` | Client ID de Google OAuth 2.0 |
+| `onLogin` | `(email, password) => Promise<void>` | Handler de login con credenciales |
+| `onGoogleCredential` | `(credential) => Promise<void>` | Handler con el JWT de Google |
+| `onForgotPassword` | `(email) => Promise<{ok, message?, error?}>` | Handler de recuperación de contraseña |
+| `onNavigateToRegister` | `() => void` | Navegación al registro |
 
-#### Props
+> El botón de Google usa un patrón de polling con `setInterval` para esperar que el SDK de Google Identity Services (cargado vía GTM) esté disponible antes de inicializarlo.
 
-- `title`: Título de la página actual
-- `description`: Descripción de la página actual
-- `systemName`: Nombre del sistema (por defecto: "PASS")
-- `systemSubtitle`: Subtítulo del sistema (por defecto: "Sistema Escolar")
-- `showPageInfo`: Controla si se muestra la información de la página en el lado derecho (por defecto: true)
-- `onMenuToggle`: Función que se ejecuta al hacer clic en el botón de menú
+---
 
-#### Uso
+#### `RegisterProductKeyPage`
+
+Página de registro en dos pasos: validación de product key y creación de cuenta.
+
+```tsx
+import { RegisterProductKeyPage } from 'botech-library';
+
+<RegisterProductKeyPage
+  googleClientId={import.meta.env.VITE_GOOGLE_CLIENT_ID}
+  onValidateKey={async (key) => ({ ok: true })}
+  onRegisterWithForm={async (email, password, fullName, phone, key) => ({ ok: true })}
+  onGoogleSignIn={async (credential) => ({ ok: true, localId: '...', idToken: '...' })}
+  onSuccess={() => navigate('/private/dashboard')}
+  onNavigateToLogin={() => navigate('/login')}
+/>
+```
+
+---
+
+### `Header`
+
+Barra de navegación superior con logo del sistema, nombre de la página actual e información contextual.
+
+```tsx
+import { Header } from 'botech-library';
 
-```jsx
 <Header
   title="Dashboard"
   description="Panel principal del sistema"
+  logoUrl="/assets/logo-colegio.png"
+  logoAlt="Logo PASS"
   systemName="PASS"
-  systemSubtitle="Sistema Escolar"
-  onMenuToggle={() => setIsSidebarOpen(true)}
+  systemSubtitle="Control de Asistencia"
+  onMenuToggle={() => setSidebarOpen(true)}
   showPageInfo={true}
 />
 ```
 
-#### Notas importantes
-
-- La descripción se muestra en **dos lugares**:
-  1. **Lado izquierdo**: `systemSubtitle` aparece debajo del nombre del sistema
-  2. **Lado derecho**: `description` aparece cuando `showPageInfo` es `true` (solo visible en pantallas medianas y grandes por la clase `hidden sm:block`)
+**Props:**
 
-### Sidebar
+| Prop | Tipo | Descripción |
+|---|---|---|
+| `title` | `string` | Título de la página actual |
+| `description` | `string` | Descripción de la página actual |
+| `logoUrl` | `string?` | URL del logo del colegio |
+| `logoAlt` | `string?` | Texto alternativo del logo |
+| `systemName` | `string` | Nombre del sistema |
+| `systemSubtitle` | `string` | Subtítulo del sistema |
+| `onMenuToggle` | `() => void` | Abre/cierra el sidebar |
+| `showPageInfo` | `boolean` | Muestra el bloque de info de página (solo en `sm:+`) |
 
-El componente Sidebar proporciona navegación lateral con soporte para carpetas y elementos de menú.
+---
 
-#### Props
+### `Sidebar`
 
-- `isOpen`: Controla si el sidebar está abierto
-- `onClose`: Función que se ejecuta al cerrar el sidebar
-- `menuItems`: Array de elementos del menú
-- `overlayClassName`: Clases CSS para el overlay (por defecto: "fixed inset-0 bg-black bg-opacity-25 z-40")
+Navegación lateral con soporte para elementos simples, carpetas con submenús, menú inferior y overlay de cierre.
 
-#### Uso
+```tsx
+import { Sidebar } from 'botech-library';
 
-```jsx
 <Sidebar
-  isOpen={isSidebarOpen}
-  onClose={() => setIsSidebarOpen(false)}
+  isOpen={sidebarOpen}
+  onClose={() => setSidebarOpen(false)}
+  onToggle={() => setSidebarOpen(!sidebarOpen)}
+  dashboardPath="/private/dashboard"
   menuItems={menuItems}
+  logoUrl="/assets/logo-colegio.png"
+  logoAlt="Logo"
   systemName="PASS"
-  activePath="/"
-  onNavigate={(path) => console.log('Navegando a:', path)}
+  activePath={location.pathname}
+  onNavigate={(path) => navigate(path)}
+  showBottomMenu={true}
+  bottomMenuItems={bottomMenuItems}
+  overlayClassName="fixed inset-0 backdrop-blur-xs z-40"
 />
 ```
 
-## Problemas Solucionados
+---
 
-### 1. Overlay del Sidebar
+### `Table`
 
-**Problema**: El overlay estaba completamente negro en lugar de ser semi-transparente.
+Tabla de datos genérica con soporte para columnas configurables, acciones por fila, paginación y modo responsive.
 
-**Solución**: Cambiado de `bg-opacity-50` a `bg-opacity-25` para que sea menos oscuro.
+```tsx
+import { Table } from 'botech-library';
 
-```jsx
-// Antes
-overlayClassName = "fixed inset-0 bg-black bg-opacity-50 z-40"
-
-// Después
-overlayClassName = "fixed inset-0 bg-black bg-opacity-25 z-40"
+<Table
+  columns={columns}
+  data={rows}
+  onEdit={(row) => handleEdit(row)}
+  onDelete={(row) => handleDelete(row)}
+/>
 ```
 
-### 2. Descripción del Header
+---
 
-**Problema**: La descripción no aparecía en el Header.
+### `ProfileSwitcher`
 
-**Solución**: La descripción se muestra en dos lugares diferentes:
+Componente para cambiar entre perfiles de usuario cuando el usuario tiene múltiples perfiles asignados.
 
-1. **systemSubtitle**: En el lado izquierdo debajo del nombre del sistema
-2. **description**: En el lado derecho cuando `showPageInfo` es `true`
+```tsx
+import { ProfileSwitcher } from 'botech-library';
 
-**Importante**: La descripción del lado derecho solo es visible en pantallas medianas y grandes debido a la clase `hidden sm:block`.
+<ProfileSwitcher />
+```
 
-## Instalación
+---
 
-```bash
-npm install botech-library
+### `Modal`
+
+Modal genérico accesible con soporte para contenido personalizado.
+
+```tsx
+import { Modal } from 'botech-library';
+
+<Modal isOpen={open} onClose={() => setOpen(false)} title="Confirmar acción">
+  <p>¿Estás seguro?</p>
+</Modal>
 ```
 
-## Uso
+---
+
+### `NotFound`
 
-```jsx
-import { Header, Sidebar } from 'botech-library';
+Página 404 estándar de BO-TECH.
 
-// Tu componente aquí...
+```tsx
+import { NotFound } from 'botech-library';
+
+<Route path="*" element={<NotFound />} />
 ```
 
-## Desarrollo
+---
+
+### `StudentSummary` y `StudentExcel`
+
+Componentes para visualización resumida de estudiantes y exportación a Excel.
+
+---
+
+### `Selector`
+
+Selector con búsqueda integrada para formularios.
+
+---
+
+## Desarrollo local
+
+### Prerrequisitos
+
+- Node.js >= 24
+- yalc instalado globalmente (`npm i -g yalc`)
+
+### Comandos
 
 ```bash
+# Instalar dependencias
 npm install
+
+# Build de producción (ESM + CJS + tipos)
+npm run build
+
+# Storybook para desarrollo visual de componentes
+npm run storybook
+
+# Tests
+npm test
+
+# Tests en modo watch
+npm run test:watch
+
+# Publicar en yalc y enviar a proyectos locales enlazados
+npm run yalc:push
+```
+
+### Publicar versión en npm
+
+```bash
+# El script yalc:push hace patch de versión automáticamente
+# Para publicar en npm:
 npm run build
+npm publish
+```
+
+---
+
+## Desarrollo con yalc (integración local)
+
+Para probar cambios en la librería desde un proyecto consumidor (ej. PASS) sin publicar en npm:
+
+```bash
+# 1. En este repositorio: compilar y publicar en yalc
+npm run yalc:push
+
+# 2. En el proyecto consumidor (ej. pass/)
+yalc add botech-library
+
+# 3. Al terminar el desarrollo, restaurar la versión de npm
+yalc remove botech-library
+npm install
 ```
 
-## Estructura del Proyecto
+> Los proyectos consumidores tienen un hook de pre-commit que bloquea commits con `file:.yalc/` en `package.json`.
+
+---
+
+## Estructura del proyecto
 
 ```
 src/
 ├── components/
-│   ├── Header/
-│   │   ├── Header.tsx
-│   │   ├── types.ts
-│   │   └── index.ts
-│   ├── Sidebar/
-│   │   ├── Sidebar.tsx
-│   │   ├── types.ts
-│   │   └── index.ts
-│   └── index.ts
-``` 
+│   ├── Auth/               # LoginPage, RegisterProductKeyPage, AuthLayout, PasswordResetModal
+│   ├── Button/             # Botón base reutilizable
+│   ├── Header/             # Header con info de página
+│   ├── Modal/              # Modal genérico
+│   ├── NotFound/           # Página 404
+│   ├── ProfileSwitcher/    # Selector de perfil de usuario
+│   ├── Selector/           # Select con búsqueda
+│   ├── Sidebar/            # Navegación lateral
+│   ├── StudentExcel/       # Exportación de estudiantes a Excel
+│   ├── StudentSummary/     # Resumen visual de estudiante
+│   └── Table/              # Tabla de datos genérica
+├── services/               # Servicios HTTP internos de la librería
+├── types/                  # Tipos TypeScript exportados
+├── utils/                  # Utilidades internas (generateTableColumns…)
+└── index.ts                # Punto de entrada y exportaciones públicas
+```
+
+---
+
+## Build
+
+El build genera tres salidas mediante Rollup:
+
+| Formato | Archivo | Uso |
+|---|---|---|
+| ESM | `dist/esm/index.js` | Bundlers modernos (Vite) |
+| CJS | `dist/cjs/index.js` | Node.js / CommonJS |
+| Tipos | `dist/types/index.d.ts` | TypeScript |
+
+---
+
+## Sistemas que consumen esta librería
+
+| Sistema | URL de producción |
+|---|---|
+| PASS | `botech.com.co/pass/` |
+| Seguimiento | `botech.com.co/seguimiento/` |