npm package: @jerinmg/dashboard-viewer
Description: Angular dashboard viewer library with customizable widgets (charts, tables, filters) and grid-based dashboard view using ECharts and GridStack
Author: Jerin
Latest version: 3.2.1

# Angular Dashboard Viewer

[![npm version](https://img.shields.io/npm/v/@jerinmg/dashboard-viewer.svg)](https://www.npmjs.com/package/@jerinmg/dashboard-viewer)
[![npm downloads](https://img.shields.io/npm/dm/@jerinmg/dashboard-viewer.svg)](https://www.npmjs.com/package/@jerinmg/dashboard-viewer)
[![license](https://img.shields.io/npm/l/@jerinmg/dashboard-viewer.svg)](https://github.com/yourusername/angular-dashboard-components/blob/main/LICENSE)

A comprehensive Angular library providing reusable dashboard components with customizable widgets and a flexible grid-based dashboard view.

## ✨ Features

- 📊 **Chart Widgets**: Area, Bar, Line, Pie, Donut, and Stacked Bar charts powered by ECharts
- 📋 **Data Table Widget**: Responsive table with sorting and custom styling
- 🎛️ **Filter Widget**: Customizable filter component
- 📈 **Status Widget**: Visual status indicators with charts
- 🎨 **Dashboard View**: Grid-based layout system using GridStack
- 🌗 **Theme Support**: Built-in dark/light theme support via CSS variables
- 🔌 **Standalone Components**: All components are standalone for easy integration
- 📦 **Self-contained**: Dashboard data is bundled into the library — no asset copying or HTTP configuration needed in consuming projects

## 📦 Installation

```bash
npm install @jerinmg/dashboard-viewer echarts gridstack
```

## 🔧 Peer Dependencies

This library requires:

- **Angular**: ^16.0.0
- **ECharts**: ^5.0.0 || ^6.0.0
- **GridStack**: ^10.0.0 || ^11.0.0 || ^12.0.0

## 🚀 Quick Start

### Import Components

```typescript
import {
  AreaChartWidgetComponent,
  BarChartWidgetComponent,
  LineChartWidgetComponent,
  PieChartWidgetComponent,
  DonutChartWidgetComponent,
  StackedBarChartWidgetComponent,
  StatusWidgetComponent,
  TableWidgetComponent,
  FilterWidgetComponent,
  DashboardViewComponent,
  DashboardLoaderService,
} from '@jerinmg/dashboard-viewer';
```

### Using Chart Widgets

All chart widgets accept `title` and `isDark` inputs:

```typescript
import { Component } from '@angular/core';
import { BarChartWidgetComponent } from '@jerinmg/dashboard-viewer';

@Component({
  selector: 'app-my-dashboard',
  standalone: true,
  imports: [BarChartWidgetComponent],
  template: ` <sc-bar-chart-widget [title]="'Sales Overview'" [isDark]="false"> </sc-bar-chart-widget> `,
})
export class MyDashboardComponent {}
```

### Using Dashboard View Component

The dashboard view component creates a grid-based layout for your widgets. The widget registry is built-in, so you don't need to import individual widgets or create a registry manually.

#### Loading Dashboard by ID

```typescript
import { Component } from '@angular/core';
import { DashboardViewComponent } from '@jerinmg/dashboard-viewer';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [DashboardViewComponent],
  template: ` <sc-dashboard-view [dashboardId]="'dashboard-npt'"> </sc-dashboard-view> `,
})
export class AppComponent {}
```

The component will automatically load the dashboard from the built-in registry — **no asset configuration or HTTP setup required**.

#### Passing Dashboard Object Directly

```typescript
import { Component } from '@angular/core';
import { DashboardViewComponent, Dashboard } from '@jerinmg/dashboard-viewer';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [DashboardViewComponent],
  template: ` <sc-dashboard-view [dashboard]="myDashboard"> </sc-dashboard-view> `,
})
export class AppComponent {
  myDashboard: Dashboard = {
    id: 'custom-dashboard',
    name: 'My Dashboard',
    description: 'Custom dashboard',
    rows: 12,
    columns: 12,
    widgets: [
      {
        id: 'widget-1',
        component: 'BarChartWidget',
        title: 'Sales Data',
        x: 0,
        y: 0,
        w: 6,
        h: 4,
      },
    ],
  };
}
```

#### Using DashboardLoaderService

You can also use the service directly to load dashboards programmatically:

```typescript
import { Component, inject, OnInit } from '@angular/core';
import { DashboardLoaderService, Dashboard } from '@jerinmg/dashboard-viewer';

@Component({ ... })
export class MyComponent implements OnInit {
  private loader = inject(DashboardLoaderService);
  dashboard: Dashboard | null = null;

  ngOnInit() {
    this.loader.loadDashboard('dashboard-npt').subscribe(d => {
      this.dashboard = d;
    });
  }
}
```

### CSS Variables for Theming

Add these CSS variables to your global styles to customize appearance:

```css
:root {
  --chart-text: #333;
  --chart-axis: #666;
  --chart-tooltip-bg: #fff;
  --chart-tooltip-border: #ccc;
  --chart-surface: #fff;
  --card-bg: #fff;
  --card-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
  --border-color: #e0e0e0;
  --surface-secondary: #f5f5f5;
  --text-primary: #333;
  --text-secondary: #666;
}
```

### Import GridStack CSS

Add GridStack CSS to your `angular.json`:

```json
{
  "styles": ["node_modules/gridstack/dist/gridstack.min.css", "src/styles.css"]
}
```

## Available Components

### Chart Widgets

- `sc-area-chart-widget` - Stacked area chart
- `sc-bar-chart-widget` - Bar chart
- `sc-line-chart-widget` - Line chart with area fill
- `sc-pie-chart-widget` - Pie chart
- `sc-donut-chart-widget` - Donut chart
- `sc-stacked-bar-chart-widget` - Horizontal stacked bar
- `sc-status-widget` - Status visualization chart

### Data Widgets

- `sc-table-widget` - Data table with headers
- `sc-filter-widget` - Filter component

### Layout

- `sc-dashboard-view` - Grid-based dashboard container

## Component Inputs

### Chart Widgets

| Input  | Type    | Default | Description       |
| ------ | ------- | ------- | ----------------- |
| title  | string  | Varies  | Widget title      |
| isDark | boolean | false   | Enable dark theme |

### Dashboard View

| Input       | Type              | Default | Description                            |
| ----------- | ----------------- | ------- | -------------------------------------- |
| dashboardId | string \| null    | null    | ID of dashboard to load from registry  |
| dashboard   | Dashboard \| null | null    | Dashboard configuration (direct input) |

## Built-in Dashboards

The library ships with these pre-built dashboards (loaded by ID):

| ID                     | Name                  | Description                                  |
| ---------------------- | --------------------- | -------------------------------------------- |
| dashboard-1            | Sales Analytics       | Sales performance metrics and trends         |
| dashboard-2            | Marketing Insights    | Campaign performance and engagement          |
| dashboard-3            | Operations Dashboard  | Operational metrics and resource utilization |
| dashboard-4            | Financial Overview    | Financial performance and budget tracking    |
| dashboard-5            | Customer Analytics    | Customer behavior and satisfaction metrics   |
| dashboard-npt          | NPT Analysis          | Non-Productive Time analysis                 |
| dashboard-npt-detailed | NPT Detailed Analysis | Comprehensive NPT with scatter plots         |
| dashboard-npt-events   | NPT Events & Lessons  | NPT Events tracking and lessons learned      |

## 🛠️ Development

### Building the Library

```bash
ng build dashboard-viewer
```

The build artifacts will be stored in the `dist/dashboard-viewer` directory.

### Publishing Updates

1. Update the version in `projects/dashboard-viewer/package.json`
2. Build the library: `ng build dashboard-viewer`
3. Navigate to the dist directory: `cd dist/dashboard-viewer`
4. Publish: `npm publish --access public`

## 📚 Resources

- **NPM Package:** https://www.npmjs.com/package/@jerinmg/dashboard-viewer
- **Angular Documentation:** https://angular.dev
- **ECharts Documentation:** https://echarts.apache.org
- **GridStack Documentation:** https://gridstackjs.com

## 📄 License

MIT © Jerin