@epegasys/ui

Librería de componentes UI para Angular 18+ basada en Angular Material y TailwindCSS, diseñada para construir interfaces de administración, paneles de control y aplicaciones empresariales de forma rápida y consistente.

Requisitos

| Dependencia | Versión mínima | |---|---| | Angular | ^18.0.0 | | Angular Material + CDK | ^18.0.0 | | @ngx-translate/core | ^15.0.0 | | luxon | ^3.5.0 | | moment | ^2.30.1 | | file-saver | ^2.0.5 | | @github/relative-time-element | ^4.4.3 |

Instalación

npm install @epegasys/ui

Asegúrate de tener instaladas las dependencias peer:

npm install @angular/material @angular/cdk @ngx-translate/core luxon moment file-saver @github/relative-time-element

Configuración inicial

1. Importar estilos

Incluye los estilos de la librería en tu angular.json o en el archivo global de estilos:

// angular.json → architect → build → options → styles
"styles": [
  "node_modules/@epegasys/ui/css/style.css"
]

2. Configurar i18n (ngx-translate)

// app.module.ts
import { TranslateModule, TranslateLoader } from '@ngx-translate/core';
import { HttpClient } from '@angular/common/http';
import { TranslateHttpLoader } from '@ngx-translate/http-loader';

export function HttpLoaderFactory(http: HttpClient) {
  return new TranslateHttpLoader(http);
}

@NgModule({
  imports: [
    TranslateModule.forRoot({
      loader: { provide: TranslateLoader, useFactory: HttpLoaderFactory, deps: [HttpClient] }
    })
  ]
})
export class AppModule {}

Componentes

<epegasys-button>

Botón reutilizable con variantes de estilo y color.

<epegasys-button
  [type]="'basic'"
  [color]="'primary'"
  [title]="'Guardar'"
  [icon]="'save'"
  (onClick)="onSave($event)">
</epegasys-button>

| Input | Tipo | Descripción | |---|---|---| | type | PegasysButtonType | Estilo del botón (ver tipos) | | color | PegasysColors | Color del botón | | title | string | Texto del botón | | icon | string | Ícono de Material Icons | | fullWidth | boolean | Ocupa el ancho completo | | customClass | string | Clases CSS adicionales |

| Output | Tipo | Descripción | |---|---|---| | onClick | EventEmitter<MouseEvent> | Clic en el botón |

<epegasys-card>

Contenedor tipo tarjeta con orientación configurable.

<epegasys-card [orientation]="'vertical'" [bordered]="true">
  <!-- contenido -->
</epegasys-card>

| Input | Tipo | Default | Descripción | |---|---|---|---| | orientation | 'horizontal' \| 'vertical' | 'horizontal' | Dirección del layout | | type | 'basic' \| 'components' | 'basic' | Estilo de la tarjeta | | bordered | boolean | true | Muestra borde |

<epegasys-chip>

Etiqueta compacta de estado o categoría.

<epegasys-chip [color]="'success'" [type]="'basic'" [title]="'Activo'"></epegasys-chip>

| Input | Tipo | Default | Descripción | |---|---|---|---| | color | PegasysColors | 'primary' | Color del chip | | type | 'basic' \| 'bordered' | 'bordered' | Estilo del chip | | title | string | — | Texto del chip |

<epegasys-crud>

Tabla CRUD completa con búsqueda, filtros, paginación y multiselección.

<epegasys-crud
  [service]="myService"
  [displayedColumns]="['name', 'status', 'createdAt']"
  [displayedHeaders]="headers"
  [componentName]="'usuarios'"
  [componentIcon]="'people'"
  [createFormGroup]="createForm"
  [createFields]="createTemplate">
</epegasys-crud>

| Input clave | Tipo | Descripción | |---|---|---| | service | PegasysCrudService | Servicio de datos | | displayedColumns | string[] | Columnas a mostrar | | displayedHeaders | PegasysDisplayHeader[] | Configuración de columnas | | componentName | string | Nombre del recurso | | componentIcon | string | Ícono del encabezado | | componentColor | PegasysColors | Color del encabezado | | enableMultiselect | boolean | Habilitar selección múltiple | | createFormGroup | FormGroup | Formulario de creación | | createFields | TemplateRef | Template de campos de creación | | updateFormGroup | FormGroup | Formulario de edición | | updateFields | TemplateRef | Template de campos de edición | | showHeader | boolean | Mostrar/ocultar cabecera |

<epegasys-dynamic-table>

Tabla dinámica con columnas personalizables, acciones y sub-tablas.

<epegasys-dynamic-table
  [dataSource]="data"
  [columns]="columns"
  [customActions]="actions">
</epegasys-dynamic-table>

| Input clave | Tipo | Descripción | |---|---|---| | dataSource | any[] | Datos de la tabla | | columns | DynamicColumn[] | Definición de columnas | | customActions | DynamicActionButton[] | Botones de acción por fila | | enablePagination | boolean | Habilitar paginación | | enableMultiselect | boolean | Selección múltiple |

<epegasys-header>

Encabezado de página/módulo con búsqueda, filtros y acciones.

<epegasys-header
  [name]="'Usuarios'"
  [icon]="'people'"
  [color]="'primary'"
  [primary]="primaryAction"
  [search]="searchConfig">
</epegasys-header>

| Input clave | Tipo | Descripción | |---|---|---| | name | string | Título del módulo | | icon | string | Ícono del módulo | | color | PegasysColors | Color del encabezado | | primary | PegasysHeaderAction | Acción primaria | | secondary | PegasysHeaderAction | Acción secundaria | | search | PegasysHeaderSearchAction | Configuración de búsqueda | | filter | PegasysHeaderFilterAction | Configuración de filtro | | actions | object | Menú de acciones | | options | object | Menú de opciones |

<epegasys-date>

Formatea y muestra una fecha en distintos formatos.

<epegasys-date [type]="'DD/MM/YYYY'" [value]="myDate"></epegasys-date>

| Input | Tipo | Descripción | |---|---|---| | type | PegasysDateType | Formato de salida | | value | Date \| null | Fecha a mostrar |

Formatos disponibles: 'YYYY-MM-DD', 'YYYY-MM-DD HH:mm:ss', 'DD/MM/YYYY', 'DD/MM/YYYY HH:mm:ss', 'relative', ''

<epegasys-document-preview>

Visor de documentos con soporte para Google Docs Viewer.

<epegasys-document-preview
  [documentName]="'Contrato'"
  [documents]="docs"
  [enableDownload]="true">
</epegasys-document-preview>

| Input | Tipo | Descripción | |---|---|---| | documentName | string \| null | Título del documento | | documents | PegasysDocumentPreview[] | Lista de documentos {url, name} | | actions | PegasysDocumentPreviewAction[] | Botones de acción | | enableDownload | boolean | Mostrar opción de descarga |

<epegasys-download>

Botón de descarga de archivos.

<epegasys-download [url]="fileUrl" [name]="'reporte.pdf'"></epegasys-download>

<epegasys-progress>

Indicador de progreso de tipo barra o spinner.

<epegasys-progress [type]="'spinner'" [size]="24"></epegasys-progress>

| Input | Tipo | Default | Descripción | |---|---|---|---| | type | 'bar' \| 'spinner' | 'bar' | Tipo de indicador | | size | number | 16 | Tamaño del spinner |

<epegasys-loading>

Indica el estado de carga global. Controlado por PegasysLoadingService.

<epegasys-notifications>

Menú desplegable de notificaciones con soporte de tipos: normal, no leída, activa e importante.

<epegasys-drawer>

Panel lateral deslizable. Controlado por PegasysDrawerService.

<epegasys-icon>

Wrapper de Material Icons para iconografía consistente.

<epegasys-icon>home</epegasys-icon>

Otros componentes

| Componente | Selector | Descripción | |---|---|---| | Card Grid | <epegasys-card-grid> | Grilla de tarjetas | | Card List | <epegasys-card-list> | Lista CRUD en tarjetas | | Chat | <epegasys-chat> | Interfaz de chat | | Date Time Picker | <epegasys-date-time-picker> | Selector de fecha y hora | | Dialog | app-dialog | Modal (uso interno vía servicio) | | Document PDFTron | <epegasys-document-pdftron> | Visor PDF con PDFTron SDK | | Documents | <epegasys-documents> | Gestor de documentos | | Filters | <epegasys-filters> | Panel de filtros | | Stepper | <epegasys-stepper> | Formulario multipaso | | Timeline | <epegasys-timeline> | Historial de eventos | | Upload | <epegasys-upload> | Carga de archivos |

Servicios

PegasysLoadingService

this.loadingService.show('Cargando datos...');
this.loadingService.hide();

PegasysDialogService

this.dialogService.open(MyComponent, { data: payload });
this.dialogService.openMessage({ title: 'Confirmación', message: '¿Deseas continuar?' });

PegasysDialogService

Abre diálogos de Material con formularios o mensajes de confirmación.

PegasysNotificationsService

Gestiona el listado y estado de notificaciones en el componente <epegasys-notifications>.

PegasysDrawerService

this.drawerService.open();
this.drawerService.close();
this.drawerService.toggle();

PegasysAuthenticationService

// Verificar permiso
const canEdit = this.authService.checkPermission('users:update');

// Verificar contra un array
const canView = this.authService.checkPermissionWithArray(permissions, 'users:read');

PegasysCrudService (abstracto)

Extiende este servicio para conectar tus endpoints REST con los componentes CRUD:

@Injectable({ providedIn: 'root' })
export class UsersService extends PegasysCrudService {
  override findAll(loading = true): void { /* llamada HTTP */ }
  override create(payload: any): void { /* llamada HTTP */ }
  override update(id: number, payload: any): void { /* llamada HTTP */ }
  override delete(id: number): void { /* llamada HTTP */ }
}

Otros servicios disponibles

| Servicio | Descripción | |---|---| | PegasysCardListService | Estado de la lista de tarjetas | | PegasysChatService | Gestión de mensajes de chat | | PegasysDateService | Utilidades de formateo de fechas | | PegasysDateTimePickerService | Estado del selector de fecha/hora | | PegasysDocumentPdftronService | Control del visor PDFTron | | PegasysDocumentsService | Gestión de listado de documentos | | PegasysDownloadService | Descarga de archivos vía HTTP | | PegasysFiltersService | Estado de filtros activos | | PegasysFormatService | Formatos de moneda y fecha | | PegasysHeaderService | Estado y acciones del encabezado | | PegasysProgressService | Control del indicador de progreso | | PegasysUploadService | Carga de archivos al servidor |

Tipos

// Tipos de botón
type PegasysButtonType =
  'basic' | 'bordered' | 'plane' |
  'extended' | 'extended-bordered' | 'extended-plane' |
  'icon' | 'icon-bordered' | 'icon-plane';

// Colores del sistema
type PegasysColors =
  'primary' | 'success' | 'disabled' | 'warning' |
  'error' | 'info' | 'accent' | 'secondary' | 'white';

// Formatos de dato
type PegasysFormat = 'date' | 'datetime' | 'relative' | 'USD' | 'MXN';

// Columna de tabla dinámica
type DynamicColumn = {
  column: string;
  label?: string;
  value?: string;
  showFilter?: boolean;
  format?: (value: any, row: any) => string;
  showChip?: boolean;
  chipColor?: PegasysColors;
  getChipColor?: (value: any) => PegasysColors;
  showButtons?: boolean;
  buttons?: DynamicActionButton[];
};

// Botón de acción en tabla
type DynamicActionButton = {
  icon: string;
  color: PegasysColors;
  type: PegasysButtonType;
  tooltip?: string;
  onClick: (row: any) => void;
};

// Definición de columna de encabezado
type PegasysDisplayHeader = {
  column: string;
  format: null | ((data: any, element?: any) => any);
  format_type?: 'text' | 'a-internal' | 'a-external' | 'a-external-composed' | 'icon' | 'formControl';
  composed_icon?: string;
  showFilter?: boolean;
  filterData?: string[];
};

Desarrollo local

# Instalar dependencias
npm install

# Servidor de desarrollo
npm start

# Compilar la librería
npm run build:lib

# Storybook
npm run storybook

Licencia

LICENSE