1.1.0 • Published 4 months ago

hms-erebus-kit

Licence

ISC

Version

1.1.0

Deps

Size

298 kB

Vulns

Weekly

Summary Dependency Versions

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