@lesterarte/sefin-ui

Una librería de sistema de diseño Angular completa basada en principios de Atomic Design y design tokens de la Secretaría de Finanzas.

Resumen

@lesterarte/sefin-ui es una librería UI Angular lista para producción diseñada para aplicaciones empresariales a gran escala. Proporciona:

• Design Tokens: Variables CSS y constantes TypeScript para temas consistentes
• Estructura Atomic Design: Componentes organizados (atoms, molecules, organisms)
• Múltiples Temas: Temas light, dark y brand (colores de Secretaría de Finanzas)
• Integración con Angular Material: Tema Material personalizado basado en design tokens
• Componentes Type-Safe: Soporte completo de TypeScript
• Testing Completo: Tests unitarios con Jest
• Documentación Storybook: Documentación visual de componentes con cambio de temas

Estructura del Proyecto

sefin-ui/
├── src/
│   ├── atoms/          # Bloques básicos (Button, Icon, Input)
│   ├── molecules/      # Componentes compuestos (FormField, Dropdown, Card)
│   ├── organisms/      # Bloques UI complejos (Header, LoginForm, Toolbar)
│   ├── tokens/         # Design tokens (colors, spacing, typography, etc.)
│   ├── themes/         # Configuraciones de temas (light, dark, brand)
│   ├── utils/          # Utilidades (ThemeLoader)
│   ├── shared/         # Tipos e interfaces compartidos
│   ├── styles/         # Estilos globales y resets
│   └── public-api.ts   # Exportaciones de la API pública
├── .storybook/         # Configuración de Storybook
├── ng-package.json     # Configuración de build
└── package.json        # Configuración del paquete

Instalación

Construir la Librería

npm run build

Esto creará el paquete distribuible en dist/.

Publicar en NPM

1. Actualiza la versión en package.json
2. Construye la librería: npm run build
3. Navega a dist: cd dist
4. Publica: npm publish --access public

Instalar en Tu Aplicación

npm install @lesterarte/sefin-ui

Uso

📖 Guía Completa: Para una guía detallada de cómo usar la librería, consulta GUIA_CONSUMO.md

Inicio Rápido

1. Importar Estilos

En tu styles.scss o angular.json:

@import '@lesterarte/sefin-ui/styles';

O en angular.json:

{
  "styles": [
    "node_modules/@lesterarte/sefin-ui/styles/index.scss"
  ]
}

2. Cargar Tema

En tu app.component.ts:

import { Component, OnInit } from '@angular/core';
import { ThemeLoader } from '@lesterarte/sefin-ui';

@Component({
  selector: 'app-root',
  // ...
})
export class AppComponent implements OnInit {
  ngOnInit(): void {
    // Cargar tema brand (colores de Secretaría de Finanzas)
    ThemeLoader.loadTheme('brand');
    
    // O cargar tema light
    // ThemeLoader.loadTheme('light');
    
    // O cargar tema dark
    // ThemeLoader.loadTheme('dark');
  }
}

3. Usar Componentes

Todos los componentes son standalone y se pueden importar directamente:

import { Component } from '@angular/core';
import { ButtonComponent, CardComponent } from '@lesterarte/sefin-ui';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [ButtonComponent, CardComponent],
  template: `
    <sefin-card variant="elevated">
      <h2>Hola Mundo</h2>
      <sefin-button variant="primary" (clicked)="handleClick()">
        Haz Clic
      </sefin-button>
    </sefin-card>
  `,
})
export class ExampleComponent {
  handleClick() {
    console.log('¡Botón clickeado!');
  }
}

Componentes Disponibles

Atoms

• Button: sefin-button - Múltiples variantes (primary, secondary, outline, ghost, danger) y tamaños
• Icon: sefin-icon - Componente contenedor de iconos
• Input: sefin-input - Input de formulario con soporte ControlValueAccessor

Molecules

• FormField: sefin-form-field - Campo de formulario completo con label, input, hint y error
• Dropdown: sefin-dropdown - Componente de selección dropdown
• Card: sefin-card - Contenedor de tarjeta con variantes (default, elevated, outlined)

Organisms

• Header: sefin-header - Encabezado de aplicación con logo, título y menú de usuario
• LoginForm: sefin-login-form - Componente de formulario de login completo
• Toolbar: sefin-toolbar - Barra de herramientas con título y botones de acción

Design Tokens

Paleta de Colores - Secretaría de Finanzas

• Dark Gray: #383838
• Light Gray: #cecece
• Light Blue: #55C3D8
• White: #ffffff

Usando Variables CSS

Todos los design tokens están disponibles como variables CSS:

.mi-componente {
  color: var(--sefin-color-primary);
  padding: var(--sefin-spacing-md);
  border-radius: var(--sefin-radius-md);
  font-size: var(--sefin-font-size-base);
  box-shadow: var(--sefin-shadow-md);
}

Usando Constantes TypeScript

import { COLOR_TOKENS, SPACING_TOKENS } from '@lesterarte/sefin-ui';

const primaryColor = COLOR_TOKENS.brand.lightBlue;
const mediumSpacing = SPACING_TOKENS.md;

Temas

Temas Disponibles

• brand: Tema con colores exactos de Secretaría de Finanzas (por defecto)
• light: Tema claro
• dark: Tema oscuro

Cambiar Temas

import { ThemeLoader } from '@lesterarte/sefin-ui';

// Cambiar a tema brand
ThemeLoader.loadTheme('brand');

// Cambiar a tema dark
ThemeLoader.loadTheme('dark');

Tipografía

La librería usa la fuente Pluto de Secretaría de Finanzas según las guías de marca:

• Pluto-Light (300) - Para texto ligero
• Pluto-Regular (400) - Para texto normal y body
• Pluto-Bold (700) - Para títulos y encabezados

⚠️ Importante: Incluir Archivos de Fuente

La librería define las declaraciones @font-face para Pluto, pero debes proporcionar los archivos de fuente en tu aplicación consumidora.

Opción 1: Archivos locales (Recomendado)

1. Copia los archivos de fuente a tu proyecto en la carpeta src/assets/fonts/:

   src/
   └── assets/
       └── fonts/
           ├── Pluto-Regular.woff2
           ├── Pluto-Regular.woff
           ├── Pluto-Bold.woff2
           ├── Pluto-Bold.woff
           ├── Pluto-Light.woff2
           └── Pluto-Light.woff

2. Configura Angular para copiar los assets en angular.json:

   {
     "assets": [
       "src/favicon.ico",
       "src/assets",
       {
         "glob": "**/*",
         "input": "src/assets/fonts",
         "output": "/assets/fonts"
       }
     ]
   }

3. Los estilos de la librería buscarán automáticamente los archivos en ./assets/fonts/

Opción 2: CDN o fuente externa

Si prefieres usar una fuente desde CDN o servidor externo, puedes sobrescribir las rutas en tu styles.scss:

@font-face {
  font-family: 'Pluto';
  src: url('https://tu-cdn.com/fonts/Pluto-Regular.woff2') format('woff2');
  font-weight: 400;
  font-style: normal;
  font-display: swap;
}

@font-face {
  font-family: 'Pluto';
  src: url('https://tu-cdn.com/fonts/Pluto-Bold.woff2') format('woff2');
  font-weight: 700;
  font-style: normal;
  font-display: swap;
}

Formatos de fuente soportados

La librería busca los archivos en este orden de prioridad:

1. .woff2 (recomendado - mejor compresión)
2. .woff (fallback)
3. .ttf (fallback)

Nota: Si no incluyes los archivos de fuente, el navegador usará las fuentes de fallback del sistema (Arial, Roboto, etc.).

Desarrollo

Ejecutar Tests

npm test

Ejecutar Tests en Modo Watch

npm run test:watch

Generar Reporte de Cobertura

npm run test:coverage

Ejecutar Storybook

npm run storybook

Esto iniciará Storybook en http://localhost:6006 con:

• Documentación de componentes
• Playground interactivo de componentes
• Cambio de temas
• Testing de accesibilidad

Construir la Librería

npm run build

Versionado

Este proyecto sigue Semantic Versioning:

• MAJOR: Cambios que rompen compatibilidad
• MINOR: Nuevas características (compatibles hacia atrás)
• PATCH: Correcciones de bugs (compatibles hacia atrás)

Flujo de Publicación

1. Actualiza la versión en package.json
2. Actualiza CHANGELOG.md
3. Construye la librería: npm run build
4. Prueba el build localmente
5. Publica: cd dist && npm publish --access public

Mejores Prácticas

Para Mantenedores de la Librería

1. Siempre prueba antes de publicar: Ejecuta tests y Storybook
2. Actualiza documentación: Mantén README y stories de Storybook actualizados
3. Sigue Atomic Design: Mantén los componentes organizados por jerarquía
4. Usa design tokens: Nunca hardcodees colores, spacing, etc.
5. Escribe tests: Mantén alta cobertura de tests

Para Consumidores

1. Importa solo lo que necesites: Usa imports amigables con tree-shaking
2. Carga el tema temprano: Inicializa el tema en AppComponent
3. Usa variables CSS: Prefiere variables CSS sobre constantes TypeScript en estilos
4. Sigue las APIs de componentes: Usa los componentes como están documentados
5. Extiende, no modifiques: Crea componentes wrapper para personalización

Solución de Problemas

Warning del Linter: "Component is used but not imported"

Si ves un warning del linter de Angular que indica que un componente está siendo usado pero no importado, este es un falso positivo conocido.

¿Por qué ocurre?

Aunque el componente está correctamente exportado desde la librería, el linter de Angular no puede detectar su uso en templates HTML cuando se trata de:

• Componentes standalone
• Selectores personalizados (como sefin-button, sefin-card, etc.)

Estado de la Librería

✅ Componente correctamente exportado
✅ Tipos TypeScript bien definidos
✅ Metadata del componente correcta

No hay nada que corregir en la librería. Esta es una limitación conocida del linter de Angular con componentes standalone y selectores personalizados.

Solución en el Proyecto Consumidor

1. Mantener el archivo .eslintrc.json en el proyecto consumidor con la configuración adecuada
2. El código funciona correctamente a pesar del warning
3. Puedes ignorar el warning de forma segura, ya que es un falso positivo

Recomendación

• Documentar en el README del proyecto consumidor que este warning es un falso positivo conocido
• El código funciona correctamente a pesar del warning
• Mantener la configuración del linter en el proyecto consumidor

Soporte

Para problemas, preguntas o contribuciones, por favor abre un issue en el repositorio.

Licencia

MIT