cats-charts 0.0.84 → 0.0.86

package/README.md

@@ -1,712 +1,712 @@
-# 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
-
-  customLegend?: ChartLegendConfig<LineChartConfig['series'][number]>;
-
-}
-```
-
-### CustomLegend
-
-```ts
-type customLegend = {
-  enabled?: boolean;
-
-  // layout/positioning
-  layout?: 'horizontal' | 'vertical';
-  position?: 'top' | 'bottom' | 'left' | 'right';
-  align?: 'start' | 'center' | 'end';
-
-  // selection behavior
-  selectionMode?: 'multiple' | 'single' | 'exclusive';
-
-  // scrolling / pagination
-  scrollable?: boolean;
-  maxHeight?: string;
-  maxWidth?: string;
-  pageSize?: number;
-  showPagination?: boolean;
-
-  // disabling items
-  disabled?: boolean;
-  disabledNames?: string[];
-
-  // accessibility / styling
-  className?: string;
-  ariaLabel?: string;
-  legendTextColor?: string;
-  legendFontSize?: number;
-
-  // icon rendering
-  icon?: ChartLegendIcon | ((series: TSeries, index: number) => ChartLegendIcon);
-
-  icons?: Record<string, ChartLegendIcon>;
-
-  // label formatting
-  formatter?: (name: string, item: ChartLegendItem) => string;
-  tooltipFormatter?: (item: ChartLegendItem) => string;
-
-  // grouping
-  groupBy?: (item: ChartLegendItem) => string | undefined;
-
-  // custom Angular template
-  itemTemplate?: TemplateRef<ChartLegendTemplateContext>;
-
-  // virtualization (advanced)
-  virtualize?: boolean;
-  virtualItemHeight?: number;
-
-  // hover behavior linking
-  hoverLink?: boolean;
-};
-```
-
-### CustomLegend Example
-
-```ts
-customLegend?: {
-  // enable/disable legend UI
-  enabled?: boolean;
-
-  // layout
-  layout?: 'horizontal' | 'vertical';
-  position?: 'top' | 'bottom' | 'left' | 'right';
-  align?: 'start' | 'center' | 'end';
-
-  // selection behavior
-  selectionMode?: 'multiple' | 'single' | 'exclusive';
-
-  // scrolling/pagination
-  scrollable?: boolean;
-  maxHeight?: string;
-  maxWidth?: string;
-  pageSize?: number;
-  showPagination?: boolean;
-
-  // disabling items
-  disabled?: boolean;
-  disabledNames?: string[];
-
-  // styling & accessibility
-  className?: string;
-  ariaLabel?: string;
-  legendTextColor?: string;
-  legendFontSize?: number;
-
-  // icon configuration
-  // - either a static icon
-  // - or a function that returns an icon per series/index
-  icon?:
-    | ChartLegendIcon
-    | ((series: TSeries, index: number) => ChartLegendIcon);
-
-  // mapping of icon names -> icon types
-  icons?: Record<string, ChartLegendIcon>;
-
-  // text formatting
-  formatter?: (name: string, item: ChartLegendItem) => string;
-
-  // tooltip formatting
-  tooltipFormatter?: (item: ChartLegendItem) => string;
-
-  // grouping
-  groupBy?: (item: ChartLegendItem) => string | undefined;
-
-  // custom Angular template (advanced)
-  itemTemplate?: TemplateRef<ChartLegendTemplateContext>;
-
-  // virtualization (advanced)
-  virtualize?: boolean;
-  virtualItemHeight?: number;
-
-  // hover linking (advanced)
-  hoverLink?: boolean;
-};
-
-```
-
-## 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;
-}
-```
-
-## Scatter Chart config
-
-```ts
-ScatterChartConfig {
-  title?: string;
-  showTitle?: boolean;
-  titlePosition?: string;
-  tooltipFormatter?: (params: any) => void;
-  colors?: string[];
-  series: {
-    name: string;
-    data: number[];
-    [key: string]: any;
-  }[];
-  // --------------- Grid configs ---------------
-  gridLeft?: string | number;
-  gridRight?: string | number;
-  gridBottom?: string | number;
-  gridTop?: string | number;
-
-  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
-  xAxisName?: string;
-  yAxisName?: string;
-}
-```
-
-## 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
-
----
-
-# Status Timeline
-
-`StatusTimelineComponent` renders generic categorical intervals in chronological order. Segment
-widths are proportional to duration, and dense datasets scroll horizontally without aggregation.
-
-## Import and usage
-
-```ts
-import { StatusTimelineComponent, type StatusTimelineConfig } from 'cats-charts';
-
-@Component({
-  standalone: true,
-  imports: [StatusTimelineComponent],
-  template: `
-    <lib-status-timeline
-      [config]="timelineConfig"
-      (chartEvent)="onTimelineEvent($event)"
-    />
-  `,
-})
-export class ExampleComponent {
-  timelineConfig: StatusTimelineConfig = {
-    startLabel: 'Monday',
-    endLabel: 'Today',
-    statuses: [
-      { value: 'ready', label: 'Ready', color: '#2f8f3a' },
-      { value: 'deploying', label: 'Deploying', color: '#d0a020' },
-      { value: 'blocked', label: 'Blocked', color: '#a43b35' },
-    ],
-    data: [
-      { start: '2026-08-24T00:00:00Z', end: '2026-08-25T00:00:00Z', status: 'ready' },
-      {
-        start: '2026-08-25T00:00:00Z',
-        end: '2026-08-25T06:00:00Z',
-        status: 'deploying',
-        label: 'Release deployment',
-      },
-      { start: '2026-08-25T06:00:00Z', end: '2026-08-26T00:00:00Z', status: 'ready' },
-    ],
-  };
-}
-```
-
-## Configuration
-
-| Option | Description |
-| --- | --- |
-| `data` | Dynamic intervals with `start`, `end`, `status`, and optional `label`/`metadata` |
-| `statuses` | Text and optional color for each status value |
-| `showLegend`, `showTooltip` | Toggle supporting UI (both default to `true`) |
-| `legendPosition` | Places the legend at `top`, `bottom`, `left`, or `right` |
-| `legendLayout` | Arranges legend items `horizontal` or `vertical` |
-| `legendAlign` | Aligns the legend at `start`/`left`, `center`, `end`/`right`, or `space-between` |
-| `legendLabelAlign` | Aligns text within vertical legend items to `left`, `center`, or `right` |
-| `legendInteractive` | Enables clicking legend labels to dim/restore matching intervals; defaults to `true` |
-| `legendDimmedOpacity` | Opacity used for inactive legend items and intervals; defaults to `0.3` |
-| `legendScrollable` | Enables bounded legend overflow scrolling; defaults to `true` |
-| `legendMaxWidth`, `legendMaxHeight` | Optional scroll viewport limits |
-| `legendNote` | Optional explanatory text displayed beside the legend |
-| `startLabel`, `endLabel` | Endpoint text; dates are derived when omitted |
-| `showEndpointLabels` | Shows or hides the endpoint-label row; defaults to `true` |
-| `endpointLabelsAlign` | Aligns endpoint labels at `start`/`left`, `center`, `end`/`right`, or `space-between` |
-| `loading`, `loadingLabel`, `emptyLabel`, `error` | Timeline state presentation |
-| `minSegmentWidth`, `segmentGap` | Dense-data and spacing controls in pixels |
-| `dateFormatter`, `durationFormatter`, `tooltipFormatter` | Display customization hooks |
-| `unknownStatus` | Fallback label/color for unconfigured status values |
-| `ariaLabel` | Accessible name for the timeline |
-
-The component emits `chartEvent` with `{ type: 'itemClick', item, index }`. Its appearance can be
-themed with the `--status-timeline-*` CSS custom properties defined in the component stylesheet.
+# 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
+
+  customLegend?: ChartLegendConfig<LineChartConfig['series'][number]>;
+
+}
+```
+
+### CustomLegend
+
+```ts
+type customLegend = {
+  enabled?: boolean;
+
+  // layout/positioning
+  layout?: 'horizontal' | 'vertical';
+  position?: 'top' | 'bottom' | 'left' | 'right';
+  align?: 'start' | 'center' | 'end';
+
+  // selection behavior
+  selectionMode?: 'multiple' | 'single' | 'exclusive';
+
+  // scrolling / pagination
+  scrollable?: boolean;
+  maxHeight?: string;
+  maxWidth?: string;
+  pageSize?: number;
+  showPagination?: boolean;
+
+  // disabling items
+  disabled?: boolean;
+  disabledNames?: string[];
+
+  // accessibility / styling
+  className?: string;
+  ariaLabel?: string;
+  legendTextColor?: string;
+  legendFontSize?: number;
+
+  // icon rendering
+  icon?: ChartLegendIcon | ((series: TSeries, index: number) => ChartLegendIcon);
+
+  icons?: Record<string, ChartLegendIcon>;
+
+  // label formatting
+  formatter?: (name: string, item: ChartLegendItem) => string;
+  tooltipFormatter?: (item: ChartLegendItem) => string;
+
+  // grouping
+  groupBy?: (item: ChartLegendItem) => string | undefined;
+
+  // custom Angular template
+  itemTemplate?: TemplateRef<ChartLegendTemplateContext>;
+
+  // virtualization (advanced)
+  virtualize?: boolean;
+  virtualItemHeight?: number;
+
+  // hover behavior linking
+  hoverLink?: boolean;
+};
+```
+
+### CustomLegend Example
+
+```ts
+customLegend?: {
+  // enable/disable legend UI
+  enabled?: boolean;
+
+  // layout
+  layout?: 'horizontal' | 'vertical';
+  position?: 'top' | 'bottom' | 'left' | 'right';
+  align?: 'start' | 'center' | 'end';
+
+  // selection behavior
+  selectionMode?: 'multiple' | 'single' | 'exclusive';
+
+  // scrolling/pagination
+  scrollable?: boolean;
+  maxHeight?: string;
+  maxWidth?: string;
+  pageSize?: number;
+  showPagination?: boolean;
+
+  // disabling items
+  disabled?: boolean;
+  disabledNames?: string[];
+
+  // styling & accessibility
+  className?: string;
+  ariaLabel?: string;
+  legendTextColor?: string;
+  legendFontSize?: number;
+
+  // icon configuration
+  // - either a static icon
+  // - or a function that returns an icon per series/index
+  icon?:
+    | ChartLegendIcon
+    | ((series: TSeries, index: number) => ChartLegendIcon);
+
+  // mapping of icon names -> icon types
+  icons?: Record<string, ChartLegendIcon>;
+
+  // text formatting
+  formatter?: (name: string, item: ChartLegendItem) => string;
+
+  // tooltip formatting
+  tooltipFormatter?: (item: ChartLegendItem) => string;
+
+  // grouping
+  groupBy?: (item: ChartLegendItem) => string | undefined;
+
+  // custom Angular template (advanced)
+  itemTemplate?: TemplateRef<ChartLegendTemplateContext>;
+
+  // virtualization (advanced)
+  virtualize?: boolean;
+  virtualItemHeight?: number;
+
+  // hover linking (advanced)
+  hoverLink?: boolean;
+};
+
+```
+
+## 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;
+}
+```
+
+## Scatter Chart config
+
+```ts
+ScatterChartConfig {
+  title?: string;
+  showTitle?: boolean;
+  titlePosition?: string;
+  tooltipFormatter?: (params: any) => void;
+  colors?: string[];
+  series: {
+    name: string;
+    data: number[];
+    [key: string]: any;
+  }[];
+  // --------------- Grid configs ---------------
+  gridLeft?: string | number;
+  gridRight?: string | number;
+  gridBottom?: string | number;
+  gridTop?: string | number;
+
+  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
+  xAxisName?: string;
+  yAxisName?: string;
+}
+```
+
+## 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
+
+---
+
+# Status Timeline
+
+`StatusTimelineComponent` renders generic categorical intervals in chronological order. Segment
+widths are proportional to duration, and dense datasets scroll horizontally without aggregation.
+
+## Import and usage
+
+```ts
+import { StatusTimelineComponent, type StatusTimelineConfig } from 'cats-charts';
+
+@Component({
+  standalone: true,
+  imports: [StatusTimelineComponent],
+  template: `
+    <lib-status-timeline
+      [config]="timelineConfig"
+      (chartEvent)="onTimelineEvent($event)"
+    />
+  `,
+})
+export class ExampleComponent {
+  timelineConfig: StatusTimelineConfig = {
+    startLabel: 'Monday',
+    endLabel: 'Today',
+    statuses: [
+      { value: 'ready', label: 'Ready', color: '#2f8f3a' },
+      { value: 'deploying', label: 'Deploying', color: '#d0a020' },
+      { value: 'blocked', label: 'Blocked', color: '#a43b35' },
+    ],
+    data: [
+      { start: '2026-08-24T00:00:00Z', end: '2026-08-25T00:00:00Z', status: 'ready' },
+      {
+        start: '2026-08-25T00:00:00Z',
+        end: '2026-08-25T06:00:00Z',
+        status: 'deploying',
+        label: 'Release deployment',
+      },
+      { start: '2026-08-25T06:00:00Z', end: '2026-08-26T00:00:00Z', status: 'ready' },
+    ],
+  };
+}
+```
+
+## Configuration
+
+| Option | Description |
+| --- | --- |
+| `data` | Dynamic intervals with `start`, `end`, `status`, and optional `label`/`metadata` |
+| `statuses` | Text and optional color for each status value |
+| `showLegend`, `showTooltip` | Toggle supporting UI (both default to `true`) |
+| `legendPosition` | Places the legend at `top`, `bottom`, `left`, or `right` |
+| `legendLayout` | Arranges legend items `horizontal` or `vertical` |
+| `legendAlign` | Aligns the legend at `start`/`left`, `center`, `end`/`right`, or `space-between` |
+| `legendLabelAlign` | Aligns text within vertical legend items to `left`, `center`, or `right` |
+| `legendInteractive` | Enables clicking legend labels to dim/restore matching intervals; defaults to `true` |
+| `legendDimmedOpacity` | Opacity used for inactive legend items and intervals; defaults to `0.3` |
+| `legendScrollable` | Enables bounded legend overflow scrolling; defaults to `true` |
+| `legendMaxWidth`, `legendMaxHeight` | Optional scroll viewport limits |
+| `legendNote` | Optional explanatory text displayed beside the legend |
+| `startLabel`, `endLabel` | Endpoint text; dates are derived when omitted |
+| `showEndpointLabels` | Shows or hides the endpoint-label row; defaults to `true` |
+| `endpointLabelsAlign` | Aligns endpoint labels at `start`/`left`, `center`, `end`/`right`, or `space-between` |
+| `loading`, `loadingLabel`, `emptyLabel`, `error` | Timeline state presentation |
+| `minSegmentWidth`, `segmentGap` | Dense-data and spacing controls in pixels |
+| `dateFormatter`, `durationFormatter`, `tooltipFormatter` | Display customization hooks |
+| `unknownStatus` | Fallback label/color for unconfigured status values |
+| `ariaLabel` | Accessible name for the timeline |
+
+The component emits `chartEvent` with `{ type: 'itemClick', item, index }`. Its appearance can be
+themed with the `--status-timeline-*` CSS custom properties defined in the component stylesheet.