cats-charts 0.0.37 → 0.0.38

package/README.md

@@ -1,341 +1,473 @@
-# CATS4U Charts
-
-![npm](https://img.shields.io/npm/v/cats-charts)
-![npm downloads](https://img.shields.io/npm/dm/cats-charts)
-![license](https://img.shields.io/npm/l/cats-charts)
-![angular](https://img.shields.io/badge/angular-20-red)
-
-**CATS4U Charts** is a reusable Angular chart library built on **Apache ECharts** and **ngx-echarts**.
-It provides easy-to-use components for rendering interactive charts such as **Bar, Line, Area, Pie, Doughnut, Sankey, Timeline**, and more.
-
----
-
-# ✨ Features
-
-- 📊 Multiple chart types
-- ⚡ Powered by Apache ECharts
-- 🔌 Angular Standalone Components
-- 🎨 Built-in theme support
-- 🖱 Click & drill-down events
-- 🧩 Easy integration
-- 📦 Lightweight and reusable
-
----
-
-# 📦 Installation
-
-Install the package along with required dependencies:
-
-```bash
-npm install cats-charts
-```
-
-# 🚀 Usage
-
-## Import Library
-
-```ts
-import { ChartsLib } from 'cats-charts';
-```
-
-## TS Syntax
-
-```ts
-import {
-    BarChart,
-    CustomChartComponent,
-    DoughnutChart,
-    LinesChart,
-    PieChart,
-    SankeyChart
-} from 'cats-charts';
-
-@Component({
-  ...,
-  imports: [
-    BarChart,
-    CustomChartComponent,
-    DoughnutChart,
-    LinesChart,
-    PieChart,
-    SankeyChart
-],
-})
-export class App {}
-```
-
----
-
-# ⚙️ Inputs
-
-| Input              | Type                                              | Description                                                    |
-| ------------------ | ------------------------------------------------- | -------------------------------------------------------------- |
-| config             |                                                   | Configuration options to customize chart and pass dynamic data |
-| theme              | string                                            | default \| dark \| vintage \| essos \| chalk \| roma           |
-| contextMenuOptions | { label: string; value: string; icon?: string }[] | Context menu options                                           |
-| events             | string[]                                          | ['click', 'contextmenu', 'dblclick']                           |
-
----
-
-# 📤 Outputs
-
-| Output           | Description            |
-| ---------------- | ---------------------- |
-| contextMenuClick | ( event: any ) => void |
-| chartEvent       | ( event: any ) => void |
-
-## Bar chart config
-
-```ts
-BarChartConfig {
-  series: {
-    name: string;
-    data: number[];
-    [key: string]: any;
-  }[];
-  xAxisData: string[];
-  colors?: string[];
-  backgroundColor?: string;
-
-  // --------------- Title configs ---------------
-  title?: string;
-  titlePosition?: string;
-  showTitle?: boolean;
-
-  // --------------- Tooltip configs ---------------
-  showTooltip?: boolean;
-  tooltipFormatter?: (params: any) => void;
-
-  // --------------- Grid configs ---------------
-  gridLeft?: string | number;
-  gridRight?: string | number;
-  gridBottom?: string | number;
-  gridTop?: string | number;
-
-  // --------------- Zoom Slider configs ---------------
-  showZoomSlider?: boolean;
-  zoomStart?: number;
-  zoomEnd?: number;
-  zoomControlButtonStyle?: any;
-
-  yAxis?: any;
-  xAxis?: any;
-  stacked?: boolean;
-
-  barWidth?: string | number;
-
-  borderRadius?: number;
-  showLabel?: boolean;
-  labelPosition?: string;
-  showXAxisLine?: boolean;
-  showYAxisLine?: boolean;
-  // Legend
-  hideLegend?: boolean;
-  legendPosition?: 'top' | 'bottom' | 'left' | 'right' | string;
-  legendAlign?: 'left' | 'center' | 'right' | string;
-  legendDirection?: 'horizontal' | 'vertical' | string;
-  legendTextColor?: string;
-  legendFontSize?: number;
-  legendContainerWidth?: number; // 0-1
-  legendIndicatorHeight?: number; // number value is in px
-}
-```
-
-## Line and Area Chart config
-
-```ts
-LineChartConfig {
-  isTrendChart?: boolean;
-  title?: string;
-  showTitle?: boolean;
-  titlePosition?: string;
-  xAxisData: string[];
-  tooltipFormatter?: (params: any) => void;
-  colors?: string[];
-  series: {
-    name: string;
-    data: number[];
-    areaColor?: string;
-    smooth?: boolean;
-    area?: boolean;
-    [key: string]: any;
-  }[];
-  // --------------- Grid configs ---------------
-  gridLeft?: string | number;
-  gridRight?: string | number;
-  gridBottom?: string | number;
-  gridTop?: string | number;
-
-  borderRadius?: number;
-  showLabel?: boolean;
-  labelPosition?: string;
-
-  yAxis?: any;
-  xAxis?: any;
-  showXAxisLine?: boolean;
-  showYAxisLine?: boolean;
-  showTooltip?: boolean;
-
-  backgroundColor?: string;
-
-  // Legend
-  hideLegend?: boolean;
-  legendPosition?: 'top' | 'bottom' | 'left' | 'right' | string;
-  legendAlign?: 'left' | 'center' | 'right' | string;
-  legendDirection?: 'horizontal' | 'vertical' | string;
-  legendTextColor?: string;
-  legendFontSize?: number;
-  legendContainerWidth?: number; // 0-1
-  legendIndicatorHeight?: number; // number value is in px
-}
-```
-
-## Pie and Donut chart config
-
-```ts
-DoughnutChartConfig {
-  title?: string;
-  showTitle?: boolean;
-  titlePosition?: 'left' | 'center' | 'right';
-  top?: any;
-  bottom?: any;
-  backgroundColor?: string;
-  series?: any;
-  data: {
-    name: string;
-    value: number;
-    [key: string]: any;
-  }[];
-
-  colors?: string[];
-
-  // Doughnut
-  innerRadius?: string;
-  outerRadius?: string;
-  center?: string[];
-  // Center Text
-  showCenterText?: boolean;
-  centerLabel?: any;
-  centerValue?: string;
-  centerValueFromTotal?: boolean;
-
-  // Tooltip
-  showTooltip?: boolean;
-  showTooltipPercent?: boolean;
-  tooltipFormatter?: (params: any, config: DoughnutChartConfig) => void;
-  valueFormatter?: (value: number) => string;
-
-  // Legend
-  hideLegend?: boolean;
-  legendBottom?: number;
-  legendPosition?: 'top' | 'bottom' | 'left' | 'right' | string;
-  legendAlign?: 'left' | 'center' | 'right' | string;
-  legendDirection?: 'horizontal' | 'vertical' | string;
-  legendTextColor?: string;
-  legendFontSize?: number;
-  legendContainerWidth?: number; // 0-1
-  // Labels
-  showLabel?: boolean;
-  labelPosition?: 'inside' | 'outside' | 'center';
-  showLabelValue?: boolean;
-  showLabelPercentage?: boolean;
-
-  // Emphasis
-  emphasisScale?: boolean;
-
-  // Style
-  borderRadius?: number;
-  borderColor?: string;
-  borderWidth?: number;
-
-  enableHoverEffect?: boolean;
-}
-```
-
-## Custom chart config
-
-```ts
-CustomChartConfig {
-  startHour?: string;
-  endHour?: string;
-
-  shiftColor?: string;
-  chartMode: 'weekly' | 'daily' | string;
-
-  yAxisData: string[];
-  categories: string[];
-  legends: TimeLineLegends;
-
-  barHeight?: number;
-  shiftHeight?: number;
-
-  data: TimelineData[];
-  hideLegendCategory?: boolean;
-}
-```
-
-## Sankey Chart config
-
-```ts
-SankeyChartConfig {
-  title?: string;
-  showTitle?: boolean;
-  backgroundColor?: string;
-  colors?: string[];
-  showTooltip?: boolean;
-  tooltipFormatter?: (params: any) => string;
-  nodes: SankeyNode[];
-  links: SankeyLink[];
-  seriesOption?: SankeySeriesOption;
-  lineCurveness?: number;
-}
-```
-
-### For `SankeySeriesOption` refer echarts Sankey series documentation
-
-https://echarts.apache.org/en/option.html#series-sankey
-
-# 📊 Supported Charts
-
-- Bar Chart
-- Line Chart
-- Area Chart
-- Pie Chart
-- Doughnut Chart
-- Stacked Area Chart
-- Sankey Chart
-- Custom Charts
-
----
-
-# 🎨 Themes
-
-Available chart themes:
-
-- default
-- dark
-- vintage
-- essos
-- chalk
-- roma
-
----
-
-# 📚 Documentation
-
-Apache ECharts documentation:
-
-https://echarts.apache.org/en/api.html#echarts
-
----
-
-# 🤝 Contributing
-
-Contributions, issues, and feature requests are welcome.
-Feel free to submit a pull request.
-
----
-
-# 📄 License
-
-MIT License
+# CATS4U Charts
+
+![npm](https://img.shields.io/npm/v/cats-charts)
+![npm downloads](https://img.shields.io/npm/dm/cats-charts)
+![license](https://img.shields.io/npm/l/cats-charts)
+![angular](https://img.shields.io/badge/angular-20-red)
+
+**CATS4U Charts** is a reusable Angular chart library built on **Apache ECharts** and **ngx-echarts**.
+It provides easy-to-use components for rendering interactive charts such as **Bar, Line, Area, Pie, Doughnut, Sankey, Timeline**, and more.
+
+---
+
+# ✨ Features
+
+- 📊 Multiple chart types
+- ⚡ Powered by Apache ECharts
+- 🔌 Angular Standalone Components
+- 🎨 Built-in theme support
+- 🖱 Click & drill-down events
+- 🧩 Easy integration
+- 📦 Lightweight and reusable
+
+---
+
+# 📦 Installation
+
+Install the package along with required dependencies:
+
+```bash
+npm install cats-charts
+
+```
+
+# 🚀 Usage
+
+## Import Library
+
+```ts
+import { ChartsLib } from 'cats-charts';
+```
+
+## TS Syntax
+
+```ts
+import {
+    BarChart,
+    CustomChartComponent,
+    DoughnutChart,
+    LinesChart,
+    PieChart,
+    SankeyChart
+} from 'cats-charts';
+
+@Component({
+  ...,
+  imports: [
+    BarChart,
+    CustomChartComponent,
+    DoughnutChart,
+    LinesChart,
+    PieChart,
+    SankeyChart
+],
+})
+export class App {}
+```
+
+---
+
+# ⚙️ Inputs
+
+| Input              | Type                                              | Description                                                    |
+| ------------------ | ------------------------------------------------- | -------------------------------------------------------------- |
+| config             |                                                   | Configuration options to customize chart and pass dynamic data |
+| theme              | string                                            | default \| dark \| vintage \| essos \| chalk \| roma           |
+| contextMenuOptions | { label: string; value: string; icon?: string }[] | Context menu options                                           |
+| events             | string[]                                          | ['click', 'contextmenu', 'dblclick']                           |
+
+---
+
+# 📤 Outputs
+
+| Output           | Description            |
+| ---------------- | ---------------------- |
+| contextMenuClick | ( event: any ) => void |
+| chartEvent       | ( event: any ) => void |
+
+## Bar chart config
+
+```ts
+BarChartConfig {
+  series: {
+    name: string;
+    data: number[];
+    [key: string]: any;
+  }[];
+  xAxisData: string[];
+  colors?: string[];
+  backgroundColor?: string;
+
+  // --------------- Title configs ---------------
+  title?: string;
+  titlePosition?: string;
+  showTitle?: boolean;
+
+  // --------------- Tooltip configs ---------------
+  showTooltip?: boolean;
+  tooltipFormatter?: (params: any) => void;
+
+  // --------------- Grid configs ---------------
+  gridLeft?: string | number;
+  gridRight?: string | number;
+  gridBottom?: string | number;
+  gridTop?: string | number;
+
+  // --------------- Zoom Slider configs ---------------
+  showZoomSlider?: boolean;
+  zoomStart?: number;
+  zoomEnd?: number;
+  zoomControlButtonStyle?: any;
+
+  yAxis?: any;
+  xAxis?: any;
+  stacked?: boolean;
+
+  barWidth?: string | number;
+
+  borderRadius?: number;
+  showLabel?: boolean;
+  labelPosition?: string;
+  showXAxisLine?: boolean;
+  showYAxisLine?: boolean;
+  // Legend
+  hideLegend?: boolean;
+  legendPosition?: 'top' | 'bottom' | 'left' | 'right' | string;
+  legendAlign?: 'left' | 'center' | 'right' | string;
+  legendDirection?: 'horizontal' | 'vertical' | string;
+  legendTextColor?: string;
+  legendFontSize?: number;
+  legendContainerWidth?: number; // 0-1
+  legendIndicatorHeight?: number; // number value is in px
+}
+```
+
+## Line and Area Chart config
+
+```ts
+LineChartConfig {
+  isTrendChart?: boolean;
+  title?: string;
+  showTitle?: boolean;
+  titlePosition?: string;
+  xAxisData: string[];
+  tooltipFormatter?: (params: any) => void;
+  colors?: string[];
+  series: {
+    name: string;
+    data: number[];
+    areaColor?: string;
+    smooth?: boolean;
+    area?: boolean;
+    [key: string]: any;
+  }[];
+  // --------------- Grid configs ---------------
+  gridLeft?: string | number;
+  gridRight?: string | number;
+  gridBottom?: string | number;
+  gridTop?: string | number;
+
+  borderRadius?: number;
+  showLabel?: boolean;
+  labelPosition?: string;
+
+  yAxis?: any;
+  xAxis?: any;
+  showXAxisLine?: boolean;
+  showYAxisLine?: boolean;
+  showTooltip?: boolean;
+
+  backgroundColor?: string;
+
+  // Legend
+  hideLegend?: boolean;
+  legendPosition?: 'top' | 'bottom' | 'left' | 'right' | string;
+  legendAlign?: 'left' | 'center' | 'right' | string;
+  legendDirection?: 'horizontal' | 'vertical' | string;
+  legendTextColor?: string;
+  legendFontSize?: number;
+  legendContainerWidth?: number; // 0-1
+  legendIndicatorHeight?: number; // number value is in px
+}
+```
+
+## Pie and Donut chart config
+
+```ts
+DoughnutChartConfig {
+  title?: string;
+  showTitle?: boolean;
+  titlePosition?: 'left' | 'center' | 'right';
+  top?: any;
+  bottom?: any;
+  backgroundColor?: string;
+  series?: any;
+  data: {
+    name: string;
+    value: number;
+    [key: string]: any;
+  }[];
+
+  colors?: string[];
+
+  // Doughnut
+  innerRadius?: string;
+  outerRadius?: string;
+  center?: string[];
+  // Center Text
+  showCenterText?: boolean;
+  centerLabel?: any;
+  centerValue?: string;
+  centerValueFromTotal?: boolean;
+
+  // Tooltip
+  showTooltip?: boolean;
+  showTooltipPercent?: boolean;
+  tooltipFormatter?: (params: any, config: DoughnutChartConfig) => void;
+  valueFormatter?: (value: number) => string;
+
+  // Legend
+  hideLegend?: boolean;
+  legendBottom?: number;
+  legendPosition?: 'top' | 'bottom' | 'left' | 'right' | string;
+  legendAlign?: 'left' | 'center' | 'right' | string;
+  legendDirection?: 'horizontal' | 'vertical' | string;
+  legendTextColor?: string;
+  legendFontSize?: number;
+  legendContainerWidth?: number; // 0-1
+  // Labels
+  showLabel?: boolean;
+  labelPosition?: 'inside' | 'outside' | 'center';
+  showLabelValue?: boolean;
+  showLabelPercentage?: boolean;
+
+  // Emphasis
+  emphasisScale?: boolean;
+
+  // Style
+  borderRadius?: number;
+  borderColor?: string;
+  borderWidth?: number;
+
+  enableHoverEffect?: boolean;
+}
+```
+
+## Custom chart config
+
+```ts
+CustomChartConfig {
+  startHour?: string;
+  endHour?: string;
+
+  shiftColor?: string;
+  chartMode: 'weekly' | 'daily' | string;
+
+  yAxisData: string[];
+  categories: string[];
+  legends: TimeLineLegends;
+
+  barHeight?: number;
+  shiftHeight?: number;
+
+  data: TimelineData[];
+  hideLegendCategory?: boolean;
+}
+```
+
+## Sankey Chart config
+
+```ts
+SankeyChartConfig {
+  title?: string;
+  showTitle?: boolean;
+  backgroundColor?: string;
+  colors?: string[];
+  showTooltip?: boolean;
+  tooltipFormatter?: (params: any) => string;
+  nodes: SankeyNode[];
+  links: SankeyLink[];
+  seriesOption?: SankeySeriesOption;
+  lineCurveness?: number;
+}
+```
+
+### For `SankeySeriesOption` refer echarts Sankey series documentation
+
+https://echarts.apache.org/en/option.html#series-sankey
+
+# 📊 Supported Charts
+
+- Bar Chart
+- Line Chart
+- Area Chart
+- Pie Chart
+- Doughnut Chart
+- Stacked Area Chart
+- Sankey Chart
+- Heatmap Chart
+- Custom Charts
+
+* Bar Chart
+* Line Chart
+* Area Chart
+* Pie Chart
+* Doughnut Chart
+* Stacked Area Chart
+* Sankey Chart
+* Custom Charts
+
+---
+
+# Heatmap Chart
+
+The heatmap component renders category-based intensity data using Apache ECharts.
+Use `[xIndex, yIndex, value]` tuples, where `xIndex` points to `xAxisData` and `yIndex` points to `yAxisData`.
+
+## Import
+
+```ts
+import { Heatmap } from 'cats-charts';
+
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  imports: [Heatmap],
+  templateUrl: './app.html',
+})
+export class App {}
+```
+
+## HTML
+
+```html
+<div style="width: 100%; height: 340px">
+  <lib-heatmap
+    [config]="heatmapConfig"
+    [theme]="selectedTheme"
+    [events]="['click', 'contextmenu']"
+    (chartEvent)="handleChartEvent($event)"
+  ></lib-heatmap>
+</div>
+```
+
+## TypeScript
+
+```ts
+heatmapConfig = {
+  xAxisData: ['00:00', '01:00', '02:00', '03:00', '04:00', '05:00'],
+  yAxisData: ['eth0', 'eth1', 'wlan0', 'vlan10', 'vlan20'],
+
+  data: [
+    [0, 0, 20],
+    [1, 0, 60],
+    [2, 0, 0],
+    [3, 0, 40],
+    [4, 0, 80],
+    [5, 0, 100],
+
+    [0, 1, 40],
+    [1, 1, 0],
+    [2, 1, 20],
+    [3, 1, 60],
+    [4, 1, 100],
+    [5, 1, 80],
+  ] as [number, number, number][],
+
+  min: 0,
+  max: 100,
+  showTooltip: true,
+
+  grid: {
+    left: 58,
+    right: 18,
+    top: 20,
+    bottom: 46,
+    containLabel: false,
+  },
+
+  xAxis: {
+    axisLabel: { color: '#6b7280' },
+    axisLine: { lineStyle: { color: '#9ca3af' } },
+    axisTick: { show: true },
+  },
+
+  yAxis: {
+    inverse: true,
+    axisLabel: { color: '#6b7280' },
+    axisLine: { show: false },
+    axisTick: { show: true },
+  },
+
+  visualMap: {
+    type: 'piecewise',
+    pieces: [
+      { min: 0, max: 20, label: '20%', color: '#fde6bd' },
+      { min: 21, max: 40, label: '40%', color: '#ffd85a' },
+      { min: 41, max: 60, label: '60%', color: '#ffb247' },
+      { min: 61, max: 80, label: '80%', color: '#ff0b1f' },
+      { min: 81, max: 100, label: '100%', color: '#a51d29' },
+    ],
+  },
+
+  series: {
+    itemStyle: {
+      borderWidth: 0,
+    },
+  },
+};
+```
+
+## Heatmap Config Options
+
+| Option           | Type                       | Description                                                             |
+| ---------------- | -------------------------- | ----------------------------------------------------------------------- |
+| xAxisData        | string[]                   | Labels for the x-axis                                                   |
+| yAxisData        | string[]                   | Labels for the y-axis                                                   |
+| data             | [number, number, number][] | Heatmap cells as `[xIndex, yIndex, value]`                              |
+| min              | number                     | Minimum value for color mapping                                         |
+| max              | number                     | Maximum value for color mapping                                         |
+| colors           | string[]                   | Continuous color range when `visualMap.pieces` is not used              |
+| visualMap        | any                        | ECharts visual map config. `pieces` also drives the custom legend pills |
+| grid             | object                     | ECharts grid config                                                     |
+| xAxis            | any                        | Extra ECharts x-axis config                                             |
+| yAxis            | any                        | Extra ECharts y-axis config                                             |
+| showTooltip      | boolean                    | Enables or disables tooltip                                             |
+| tooltipFormatter | function                   | Custom tooltip formatter                                                |
+| showLabel        | boolean                    | Shows value labels inside cells                                         |
+| labelFormatter   | string \| function         | Cell label formatter                                                    |
+| series           | any \| any[]               | Extra ECharts heatmap series config                                     |
+
+---
+
+# 🎨 Themes
+
+Available chart themes:
+
+- default
+- dark
+- vintage
+- essos
+- chalk
+- roma
+
+---
+
+# 📚 Documentation
+
+Apache ECharts documentation:
+
+https://echarts.apache.org/en/api.html#echarts
+
+---
+
+# 🤝 Contributing
+
+Contributions, issues, and feature requests are welcome.
+Feel free to submit a pull request.
+
+---
+
+# 📄 License
+
+MIT License