hms-erebus-kit

Biblioteca de componentes React y toolkit para aplicaciones empresariales. Incluye autenticacion, autorizacion, manejo de formularios, visualizacion de datos y gestion de archivos.

Instalacion

npm install hms-erebus-kit

Configuracion inicial

1. Configurar el kit

import { setKitConfig } from "hms-erebus-kit/kit.config";

setKitConfig({
  apiBaseUrl: "https://api.ejemplo.com",
  navigateTo: (route) => navigate(route),
});

2. Envolver la aplicacion con el provider

import { KitContextProvider } from "hms-erebus-kit/kit.context";

function App() {
  return (
    <KitContextProvider>
      <MiAplicacion />
    </KitContextProvider>
  );
}

3. Importar estilos

import "hms-erebus-kit/style";

Modulos disponibles

import { ... } from "hms-erebus-kit/components";
import { ... } from "hms-erebus-kit/interfaces";
import { ... } from "hms-erebus-kit/services";
import { ... } from "hms-erebus-kit/utils";
import { KitContextProvider } from "hms-erebus-kit/kit.context";
import { setKitConfig, getKitConfig } from "hms-erebus-kit/kit.config";

Componentes

PageComponent

Componente compuesto para estructurar paginas.

import { PageComponent } from "hms-erebus-kit/components";

<PageComponent>
  <PageComponent.ContentCard title="Usuarios" filters={<FiltrosComponent />}>
    {contenido}
  </PageComponent.ContentCard>

  <PageComponent.GridCard>
    <div>Columna 1</div>
    <div>Columna 2</div>
  </PageComponent.GridCard>

  <PageComponent.ButtonsCard>
    <ButtonComponent text="Guardar" />
  </PageComponent.ButtonsCard>

  <PageComponent.Fieldset>
    {camposSoloLectura}
  </PageComponent.Fieldset>
</PageComponent>

| Sub-componente | Descripcion | |---|---| | ContentCard | Tarjeta con titulo y area de filtros opcional | | GridCard | Grilla responsiva para columnas | | ButtonsCard | Contenedor de botones (opcion fija al fondo) | | Fieldset | Grupo de campos deshabilitados |

FormComponent

Componente compuesto para formularios, integrado con react-hook-form.

import { FormComponent } from "hms-erebus-kit/components";

<FormComponent action={handleSubmit(onSubmit)}>
  <FormComponent.Input
    idInput="email"
    typeInput="email"
    label="Correo"
    register={register}
    errors={errors}
    className="col-12 col-md-6"
  />

  <FormComponent.Select
    idInput="rol"
    label="Rol"
    register={register}
    errors={errors}
    data={roles}
    className="col-12 col-md-6"
  />

  <FormComponent.MultiSelect
    idInput="permisos"
    label="Permisos"
    register={register}
    errors={errors}
    data={permisos}
  />

  <FormComponent.PhoneNumber
    idInput="telefono"
    label="Telefono"
    register={register}
    errors={errors}
  />

  <FormComponent.Search
    idInput="cliente"
    label="Cliente"
    register={register}
    errors={errors}
    searchConfig={configBusqueda}
  />

  <FormComponent.Button text="Enviar" />
</FormComponent>

| Sub-componente | Descripcion | |---|---| | Input | Entrada de texto, email, password, textarea, date, number, etc. | | Select | Selector desplegable con soporte de teclado | | MultiSelect | Selector multiple con checkboxes | | PhoneNumber | Telefono internacional con selector de pais y bandera | | Search | Busqueda con modal de seleccion paginado | | Button | Boton de formulario |

TableComponent

Tabla con paginacion, acciones por fila y renderizado personalizado.

import { TableComponent } from "hms-erebus-kit/components";

const columnas: ITableElement<IUsuario>[] = [
  { header: "Nombre", accessor: "nombre" },
  { header: "Email", accessor: "email" },
  { header: "Estado", accessor: "activo", renderCell: (row) => row.activo ? "Activo" : "Inactivo" },
];

<TableComponent
  ref={tablaRef}
  url="/api/usuarios"
  columns={columnas}
  actions={[
    { icon: "detail", onClick: (row) => verDetalle(row) },
    { icon: "edit", onClick: (row) => editar(row) },
    { icon: "delete", onClick: (row) => eliminar(row) },
  ]}
/>

Caracteristicas:

• Paginacion integrada con selector de registros por pagina
• Acciones por fila: detalle, editar, eliminar
• Renderizado personalizado de celdas
• Estado de carga con spinner
• Estado vacio

ListComponent

Lista de elementos con avatar, titulo, descripcion y acciones.

import { ListComponent } from "hms-erebus-kit/components";

<ListComponent
  ref={listaRef}
  url="/api/items"
  actions={acciones}
/>

TransferBoxComponent

Componente de seleccion dual (disponibles / seleccionados).

import { TransferBoxComponent } from "hms-erebus-kit/components";

<TransferBoxComponent
  ref={transferRef}
  availableItems={itemsDisponibles}
  onChange={(seleccionados) => handleCambio(seleccionados)}
/>

// Metodos via ref
transferRef.current.clear();
transferRef.current.setInitialIds([1, 2, 3]);

FileManagerComponent

Gestion de archivos con drag-and-drop, validacion y subida automatica o manual.

import { FileManagerComponent } from "hms-erebus-kit/components";

<FileManagerComponent
  ref={fileRef}
  entityType="documento"
  entityId={123}
  allowedFormats={[".pdf", ".jpg", ".png"]}
  maxSizeInMB={5}
  autoUpload={true}
  onUploadComplete={(archivo) => console.log("Subido:", archivo)}
  onError={(error) => console.error(error)}
/>

Caracteristicas:

• Drag-and-drop
• Validacion de formato y tamano
• Subida automatica o manual
• Listado de archivos pendientes y subidos
• Eliminacion de archivos

ModalMessageComponent

Modales de alerta, confirmacion e informacion.

import { ModalMessageComponent } from "hms-erebus-kit/components";

<ModalMessageComponent
  show={mostrar}
  code={EResponseCodes.ASK}
  title="Confirmacion"
  message="Desea eliminar este registro?"
  onAccept={() => confirmar()}
  onCancel={() => cancelar()}
  onClose={() => cerrar()}
/>

Codigos disponibles: OK, WARN, FAIL, ASK, INFO

ModalFormComponent

Modal responsivo para formularios.

import { ModalFormComponent } from "hms-erebus-kit/components";

<ModalFormComponent show={mostrar} title="Nuevo usuario" onClose={() => cerrar()}>
  <FormComponent action={handleSubmit(onSubmit)}>
    {campos}
  </FormComponent>
</ModalFormComponent>

Otros componentes

| Componente | Descripcion | |---|---| | ButtonComponent | Boton con estilos Primary, Secondary, Tertiary y estado de carga | | LabelComponent | Etiqueta con variantes: Title, SubTitle, FormInput, Regular | | SpinnerComponent | Overlay de carga con spinner | | BreadCrumbComponent | Navegacion de migas de pan | | LazyIconComponent | Carga dinamica de iconos de react-icons (Fa, Md, Ai, Bi, Bs, Gr) | | MenuButtonComponent | Boton con menu desplegable | | PaginatorComponent | Paginacion con navegacion y elipsis | | InputGroupComponent | Input con icono de prefijo |

Servicios

Hooks que encapsulan llamadas a la API con manejo automatico de tokens JWT.

useAuthService

import { useAuthService } from "hms-erebus-kit/services";

const {
  signIn,
  getAuthorization,
  changePassword,
  recoveryPassword,
  validateTokenRecovery,
  changePasswordToken,
  refreshToken,
  logout,
} = useAuthService();

// Login
const respuesta = await signIn({ identifier: "usuario", password: "clave" });

// Obtener permisos del usuario
const autorizacion = await getAuthorization();

// Cambiar contrasena
await changePassword("nuevaClave123");

// Cerrar sesion
await logout();

useConfigService

import { useConfigService } from "hms-erebus-kit/services";

const { getModules, getMenuAccess, getOptionsByModuleId } = useConfigService();

const modulos = await getModules();
const menu = await getMenuAccess();
const opciones = await getOptionsByModuleId(moduloId);

useFileService

import { useFileService } from "hms-erebus-kit/services";

const { uploadFile, getFileById, getFilesByEntity, deleteFile } = useFileService();

await uploadFile(archivo, metadata);
const archivos = await getFilesByEntity("proyecto", proyectoId);
await deleteFile(archivoId);

useGenericListService

import { useGenericListService } from "hms-erebus-kit/services";

const { getListByGroupers, getListByParent } = useGenericListService();

const items = await getListByGroupers(["TIPO_DOCUMENTO", "ESTADO"]);
const hijos = await getListByParent({ parentId: 1, grouper: "CATEGORIA" });

Utilidades

useApiService

Cliente HTTP basado en Axios con interceptores automaticos.

import { useApiService } from "hms-erebus-kit/utils";

const { get, post, put, del } = useApiService("/api/recurso");

const datos = await get<IUsuario[]>("");
const nuevo = await post<IUsuario>("/crear", datosFormulario);
await put<IUsuario>("/actualizar/1", datosActualizados);
await del("/eliminar/1");

Caracteristicas:

• Inyeccion automatica del token Bearer
• Refresh automatico del token cuando quedan menos de 2 minutos de vigencia
• Interceptores de request/response
• Manejo de respuestas estandarizado con ApiResponse<T>

useYupValidationResolver

Puente entre react-hook-form y yup para validacion de esquemas.

import { useYupValidationResolver } from "hms-erebus-kit/utils";
import * as yup from "yup";

const schema = yup.object({
  email: yup.string().email().required(),
  nombre: yup.string().required().min(3),
});

const resolver = useYupValidationResolver(schema);
const { register, handleSubmit, formState: { errors } } = useForm({ resolver });

useAppCommunicator

Sistema de eventos publish/subscribe usando eventos del DOM.

import { useAppCommunicator } from "hms-erebus-kit/utils";

const { subscribe, unsubscribe, publish } = useAppCommunicator();

// Suscribirse a un evento
subscribe("usuario:actualizado", (data) => {
  console.log("Usuario actualizado:", data);
});

// Publicar un evento
publish("usuario:actualizado", { id: 1, nombre: "Juan" });

// Desuscribirse
unsubscribe("usuario:actualizado");

useLoadData

Hook generico para carga de datos.

import { useLoadData } from "hms-erebus-kit/utils";

const { data, reload } = useLoadData<IUsuario[]>(
  () => usuarioService.getAll(),
  [],
  { autoLoad: true }
);

useBreadCrumb

Manejo de estado para navegacion breadcrumb.

import { useBreadCrumb } from "hms-erebus-kit/utils";

const { stringifyContext, updateContext } = useBreadCrumb(datosIniciales);

useExtendedFunctions

Funciones utilitarias extendidas.

import { useExtendedFunctions } from "hms-erebus-kit/utils";

const { confirmDelete } = useExtendedFunctions();

await confirmDelete(registroId, "/api/usuarios", () => recargarTabla());

Funciones auxiliares

import { formatDate, getErrorMessage } from "hms-erebus-kit/utils";

formatDate("2024-01-15T10:30:00", true);  // "2024-01-15 10:30"
formatDate("2024-01-15T10:30:00", false); // "2024-01-15"

const mensaje = getErrorMessage(errors, "email"); // Mensaje de error del campo

ApiResponse y EResponseCodes

import { ApiResponse, EResponseCodes } from "hms-erebus-kit/utils";

// Estructura de respuesta estandar
interface ApiResponse<T> {
  data: T;
  total: number;
  operation: {
    code: EResponseCodes;
    message: string;
  };
}

// Codigos de respuesta
enum EResponseCodes {
  OK = "OK",
  WARN = "WARN",
  FAIL = "FAIL",
  ASK = "ASK",
  INFO = "INFO",
}

Interfaces principales

Autenticacion

| Interface | Descripcion | |---|---| | IUser | Datos del usuario (id, username, email, contacto, fechas) | | ILoginForm | Formulario de login (identifier, password) | | IAuthUser | Respuesta de autenticacion (user, tokens, expiracion) | | IAuthorization | Autorizacion completa (user, permisos, modulos, tokens) | | IAccessOption | Opciones de menu y acciones | | IAction | Permisos de acciones |

Genericas

| Interface | Descripcion | |---|---| | IMessage | Datos para modales de mensaje | | IGenericList | Items de lista generica | | IModule | Modulo de la aplicacion | | IMenuAccess | Estructura del menu de navegacion | | ISearchFilters | Parametros de busqueda | | ISearchResult | Resultado de busqueda | | IFile | Metadata de archivo | | IFileUpload | Metadata de subida de archivo |

Tabla

| Interface | Descripcion | |---|---| | ITableElement<T> | Definicion de columna | | IListTableElement | Item para dropdowns en tabla | | ICustomActionTable | Accion personalizada de tabla | | ITableAction<T> | Accion por fila |

KitContext

El contexto global provee acceso a:

import { useKitContext } from "hms-erebus-kit/kit.context";

const {
  authorization,        // Estado de autorizacion del usuario
  validateActionAccess, // Validar permisos de accion por indicador
  message,              // Estado del modal de mensaje
  setMessage,           // Mostrar/ocultar modal de mensaje
} = useKitContext();

// Validar si el usuario tiene acceso a una accion
const tieneAcceso = validateActionAccess("CREAR_USUARIO");

Tecnologias

• React 19 - Biblioteca UI
• TypeScript - Tipado estatico
• Tailwind CSS 4 - Estilos utilitarios
• react-hook-form - Manejo de formularios
• Yup - Validacion de esquemas
• Axios - Cliente HTTP
• react-icons - Iconos (Fa, Md, Ai, Bi, Bs, Gr)

Autor

Daniel Flores

Licencia

ISC