📊 ngx-data-visualizer

Este proyecto ha sido desarrollado por el Área de Políticas Públicas de la Universidad Nacional de Cuyo. Consiste en un workspace de Angular que incluye:

@uncuyoapp/ngx-data-visualizer: una librería open-source diseñada para facilitar la visualización de datos en proyectos Angular, a través de componentes reutilizables, accesibles y adaptables a distintos contextos.
demo: una aplicación de ejemplo que muestra cómo integrar y utilizar la librería en un proyecto Angular real.

El objetivo principal del proyecto es promover el uso de herramientas tecnológicas abiertas para la exploración, presentación y análisis de datos públicos, en el marco de iniciativas de gobierno abierto y políticas basadas en evidencia.

✨ Características principales

Completamente standalone (sin NgModules) - Compatible con Angular moderno
Sistema de proveedores configurables - Usa solo las funcionalidades que necesitas
Integración con ECharts y PivotTable.js - Las mejores librerías de visualización
Exportación avanzada - Soporta Excel, PNG, JPG y SVG
Visualizaciones personalizables - Mediante inputs simples y temas
TypeScript completo - Interfaces tipadas para mejor DX
Optimizado para rendimiento - Lazy loading y tree shaking incluido

🚀 Instalación rápida

npm install @uncuyoapp/ngx-data-visualizer echarts ngx-echarts pivottable jquery

⚙️ Configuración básica

En tu app.config.ts:

import { ApplicationConfig } from '@angular/core';
import { provideDataVisualizerCharts, provideDataVisualizerTables } from '@uncuyoapp/ngx-data-visualizer';

export const appConfig: ApplicationConfig = {
  providers: [
    // Otros providers...
    provideDataVisualizerCharts(), // Para gráficos
    provideDataVisualizerTables(), // Para tablas
  ]
};

En tu componente:

import { Component } from '@angular/core';
import { ChartDirective, Dataset, ChartOptions } from '@uncuyoapp/ngx-data-visualizer';

@Component({
  selector: 'app-my-chart',
  standalone: true,
  imports: [ChartDirective],
  template: `<div libChart [dataset]="dataset" [chartOptions]="options"></div>`
})
export class MyChartComponent {
  dataset = new Dataset({
    dimensions: [/* ... */],
    rowData: [/* ... */]
  });
  
  options: ChartOptions = {
    chartType: 'bar',
    // más opciones...
  };
}

🧩 Tecnologías y librerías utilizadas

Este proyecto está desarrollado en Angular 18 e integra múltiples librerías de visualización y manipulación de datos. La librería @uncuyoapp/ngx-data-visualizer funciona como un wrapper que simplifica el uso combinado de las siguientes dependencias clave:

Dependencias principales

Angular 18+ — Framework base con APIs standalone
ECharts y ngx-echarts — Para visualizaciones interactivas
PivotTable.js — Para análisis dinámico de datos tabulados
XLSX — Para exportación e importación de hojas de cálculo
FileSaver.js — Para descarga de archivos desde el navegador

Dependencias de utilidad

lodash.clonedeep y lodash.uniqby — Para manipulación de objetos y arrays
jQuery — Requerido por PivotTable.js
RxJS — Programación reactiva

Dependencias de desarrollo y demo

Bootstrap 5 — Para layout responsivo y estilos (solo en demo)
Prism.js — Para highlighting de código (solo en demo)

📁 Estructura del Proyecto

ngx-data-visualizer-workspace/
├── projects/
│   ├── ngx-data-visualizer/    # 📦 Librería principal
│   │   ├── src/lib/
│   │   │   ├── chart/          # Componentes de gráficos
│   │   │   ├── table/          # Componentes de tablas
│   │   │   ├── multiple-chart/ # Múltiples gráficos
│   │   │   ├── providers.ts    # ⭐ Proveedores configurables
│   │   │   └── public-api.ts   # API pública
│   │   └── README.md
│   └── demo/                   # 🧪 Aplicación de demostración
│       ├── src/app/
│       │   ├── configuration/  # 📚 Guía de uso
│       │   ├── chart-demo/     # Ejemplos de gráficos
│       │   ├── table-demo/     # Ejemplos de tablas
│       │   ├── dashboard/      # Dashboard completo
│       │   └── full-example/   # Ejemplo integral
│       └── README.md
├── dist/                       # Builds de distribución
├── package.json               # Configuración del workspace
└── README.md                  # Este archivo

🧩 Componentes Principales

📦 @uncuyoapp/ngx-data-visualizer - Librería Principal

La librería proporciona un conjunto de directivas standalone y servicios para visualización de datos:

Directivas:
- ChartDirective - Gráficos individuales
- MultipleChartDirective - Múltiples gráficos
- TableDirective - Tablas dinámicas
Clases y tipos:
- Dataset - Gestión de conjuntos de datos
- ChartOptions, TableOptions - Configuraciones tipadas
- Dimension, RowData, Goal - Interfaces de datos
Proveedores:
- provideDataVisualizerCharts() - Para funcionalidad de gráficos
- provideDataVisualizerTables() - Para funcionalidad de tablas

👉 Documentación completa: README de la librería

🧪 Proyecto Demo - Documentación Interactiva

Una aplicación Angular completa que sirve como documentación viva y ejemplos de uso:

Guía de configuración - Setup paso a paso
Ejemplos interactivos - Para cada directiva
Casos de uso reales - Dashboard y análisis de datos
Código fuente - Todos los ejemplos incluyen código

👉 Ver ejemplos: README del demo o visita la Demo Online.

⚙️ Requisitos del Sistema

Node.js >= 18.13.0
npm >= 8.19.0
Angular CLI >= 18.0.0
Angular >= 18.0.0 (con soporte para standalone APIs)

🚀 Desarrollo Local

Instalación completa del workspace

# Clonar el repositorio
git clone https://github.com/uncuyoapp/ngx-data-visualizer.git
cd ngx-data-visualizer

# Instalar dependencias
npm install

Comandos principales

# 🧪 Ejecutar aplicación demo
ng serve demo
# Abre http://localhost:4200

# 📦 Construir la librería
ng build ngx-data-visualizer

# 🧪 Construir demo
ng build demo

# 🔍 Linting
ng lint

Flujo de desarrollo

Desarrollar en la librería: Modifica archivos en projects/ngx-data-visualizer/
Construir la librería: ng build ngx-data-visualizer
Probar en demo: Los cambios se reflejan automáticamente en el demo
Verificar ejemplos: ng serve demo para ver los cambios en acción

📖 Guía de Uso

1. Instalación en tu proyecto

npm install @uncuyoapp/ngx-data-visualizer echarts ngx-echarts pivottable jquery

2. Configurar proveedores (obligatorio)

// app.config.ts
import { ApplicationConfig } from '@angular/core';
import { 
  provideDataVisualizerCharts,
  provideDataVisualizerTables 
} from '@uncuyoapp/ngx-data-visualizer';

export const appConfig: ApplicationConfig = {
  providers: [
    // Solo si usas gráficos
    provideDataVisualizerCharts(),
    
    // Solo si usas tablas
    provideDataVisualizerTables(),
    
    // Otros providers...
  ]
};

3. Importar Estilos Globales (obligatorio)

Para que los componentes se visualicen correctamente, importa el archivo de estilos principal de la librería en tu archivo styles.scss global (o equivalente).

// en src/styles.scss
@import '@uncuyoapp/ngx-data-visualizer/styles';

4. Usar en componentes

import { Component } from '@angular/core';
import { 
  ChartDirective, 
  TableDirective,
  Dataset, 
  ChartOptions 
} from '@uncuyoapp/ngx-data-visualizer';

@Component({
  selector: 'app-data-viz',
  standalone: true,
  imports: [ChartDirective, TableDirective],
  template: `
    <!-- Gráfico -->
    <div libChart 
         [dataset]="dataset" 
         [chartOptions]="chartOptions">
    </div>
    
    <!-- Tabla -->
    <div libTable 
         [dataset]="dataset" 
         [tableOptions]="tableOptions">
    </div>
  `
})
export class DataVizComponent {
  dataset = new Dataset({
    dimensions: [
      {
        id: 1,
        name: 'category',
        nameView: 'Categoría',
        items: [
          { id: 1, name: 'A', selected: true },
          { id: 2, name: 'B', selected: true }
        ]
      }
    ],
    rowData: [
      { category: 'A', value: 100 },
      { category: 'B', value: 200 }
    ]
  });
  
  chartOptions: ChartOptions = {
    chartType: 'bar',
    title: 'Mi Gráfico'
  };
  
  tableOptions = {
    title: 'Mi Tabla'
  };
}

🎨 Ejemplos y Documentación

La mejor manera de aprender a usar la librería es explorando los ejemplos interactivos en la aplicación demo.

# Ejecutar la aplicación demo localmente
ng serve demo

Visita la Demo Online para ver la librería en acción sin necesidad de instalar nada.

Secciones disponibles en la demo:

📚 Configuración: Guía paso a paso de setup
📊 Gráficos: Ejemplos de ChartDirective
📋 Tablas: Ejemplos de TableDirective
📈 Múltiples Gráficos: Ejemplos de MultipleChartDirective
🎛️ Dashboard: Caso de uso completo
🔧 Ejemplo Completo: Integración de todas las funcionalidades

🤝 Contribuciones

¡Las contribuciones son bienvenidas! Sigue estos pasos:

Para reportar bugs o sugerir features

Crea un Issue describiendo el problema o sugerencia
Usa las plantillas proporcionadas
Incluye ejemplos de código si es relevante

Para contribuir código

Haz un fork del repositorio
Crea una nueva rama: git checkout -b feature/nueva-funcionalidad

Desarrolla y prueba tus cambios:

# Construir librería
ng build ngx-data-visualizer

# Probar en demo
ng serve demo

# Verificar linting
ng lint

Commit siguiendo Conventional Commits:

git commit -m "feat: agregar nueva funcionalidad X"

Push a tu fork: git push origin feature/nueva-funcionalidad
Crea un Pull Request con descripción detallada

Estándares de código

Seguir las convenciones de Angular
Incluir documentación JSDoc
Mantener compatibilidad con versiones soportadas
Agregar ejemplos en el demo cuando sea relevante

📋 Roadmap

Próximas versiones

Configurador de gráficos y tablas
Mejoras en la interfaz de usuario

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT.

📬 Contacto y Soporte

🎯 Soporte técnico

Issues: GitHub Issues
Discusiones: GitHub Discussions

🏛️ Información institucional

Coordinación de Proyecto: Gonzalo R. Siman gonzasiman@gmail.com
Área de Políticas Públicas - UNCUYO: politicaspublicasuncuyo@gmail.com
Sitio web: https://www.uncuyo.edu.ar/politicaspublicas/

Desarrollado con ❤️ por el Área de Políticas Públicas - Universidad Nacional de Cuyo

🌐 Website • GitHub • 📊 NPM • 🧪 Demo

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
.github		.github
projects		projects
.editorconfig		.editorconfig
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
angular.json		angular.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

License

uncuyoapp/ngx-data-visualizer

Folders and files

Latest commit

History

Repository files navigation