botech-library

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.

Instalación

npm install botech-library

Peer dependencies requeridas

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.

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:

| 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 | | onError | (error: unknown) => void? | Reemplaza el modal de error por defecto |

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.

Errores: onLogin y onGoogleCredential deben lanzar o rechazar cuando el ingreso falla. LoginPage captura ese rechazo y muestra un modal de SweetAlert2 con el mensaje del error, así que la aplicación no necesita su propio try/catch. El mensaje se extrae con resolveErrorMessage, que entiende un Error, un string y un error de axios (mira primero response.data.message, no el Request failed with status code 401 que redacta axios). Si la aplicación ya tiene su propio sistema de notificaciones, pasa onError y el modal no se muestra.

Doble envío: mientras onLogin está en curso el botón queda deshabilitado y muestra "Ingresando...", y un segundo envío no llega al handler. El componente lo maneja solo.

RegisterProductKeyPage

Página de registro en dos pasos: validación de product key y creación de cuenta.

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.

import { Header } from 'botech-library';

<Header
  title="Dashboard"
  description="Panel principal del sistema"
  logoUrl="/assets/logo-colegio.png"
  logoAlt="Logo PASS"
  systemName="PASS"
  systemSubtitle="Control de Asistencia"
  onMenuToggle={() => setSidebarOpen(true)}
  showPageInfo={true}
/>

Props:

| 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:+) |

Sidebar

Navegación lateral con soporte para elementos simples, carpetas con submenús, menú inferior y overlay de cierre.

import { Sidebar } from 'botech-library';

<Sidebar
  isOpen={sidebarOpen}
  onClose={() => setSidebarOpen(false)}
  onToggle={() => setSidebarOpen(!sidebarOpen)}
  dashboardPath="/private/dashboard"
  menuItems={menuItems}
  logoUrl="/assets/logo-colegio.png"
  logoAlt="Logo"
  systemName="PASS"
  activePath={location.pathname}
  onNavigate={(path) => navigate(path)}
  showBottomMenu={true}
  bottomMenuItems={bottomMenuItems}
  overlayClassName="fixed inset-0 backdrop-blur-xs z-40"
/>

Table

Tabla de datos genérica con soporte para columnas configurables, acciones por fila, paginación y modo responsive.

import { Table } from 'botech-library';

<Table
  columns={columns}
  data={rows}
  onEdit={(row) => handleEdit(row)}
  onDelete={(row) => handleDelete(row)}
/>

ProfileSwitcher

Componente para cambiar entre perfiles de usuario cuando el usuario tiene múltiples perfiles asignados.

import { ProfileSwitcher } from 'botech-library';

<ProfileSwitcher />

Modal

Modal genérico accesible con soporte para contenido personalizado.

import { Modal } from 'botech-library';

<Modal isOpen={open} onClose={() => setOpen(false)} title="Confirmar acción">
  <p>¿Estás seguro?</p>
</Modal>

NotFound

Página 404 estándar de BO-TECH.

import { NotFound } from 'botech-library';

<Route path="*" element={<NotFound />} />

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

# 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

# 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:

# 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

Los proyectos consumidores tienen un hook de pre-commit que bloquea commits con file:.yalc/ en package.json.

Estructura del proyecto

src/
├── components/
│   ├── 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, resolveErrorMessage…)
└── 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/ |