stz-chart-maker 1.2.5 → 1.3.0

package/dist/index.d.ts

@@ -1,4 +1,3 @@
-import * as chart_js from 'chart.js';
 import { ChartType, PluginOptionsByType, ChartOptions, GridLineOptions, FontSpec, Tick, Chart, ChartEvent, ActiveElement, LegendOptions, ChartDataset, Plugin as Plugin$1, TooltipItem, ChartTypeRegistry } from 'chart.js';
 import { ZoomPluginOptions } from 'chartjs-plugin-zoom/types/options';
 import { DeepPartial as DeepPartial$1 } from 'chart.js/dist/types/utils';
@@ -264,14 +263,30 @@ type CustomLineChartOptions = CustomChartOptions<'line'>;
 type CustomBubbleChartOptions = CustomChartOptions<'bubble'>;
 type CustomPieChartOptions = CustomArcChartOptions<'pie'>;
 type CustomDoughnutChartOptions = CustomArcChartOptions<'doughnut'>;
+type ArcDataset<TType extends ArcChartType = ArcChartType> = ChartDataset<TType, (number | null)[]> & {
+    _aux?: boolean;
+    _group?: string | number;
+    _legendOrder?: number;
+    _visible?: boolean;
+    _tooltip?: string | ((context: any) => string);
+    _groupLabel?: string;
+    _toggleBehavior?: 'normal' | 'radio' | 'disabled';
+};
 type CartesianDataset<TType extends CartesianChartType = CartesianChartType> = ChartDataset<TType, (number | null)[]> & {
     yAxisID?: string;
     xAxisID?: string;
     stack?: string;
     order?: number;
     DATASET_ID?: string;
+    _aux?: boolean;
+    _group?: string | number;
+    _legendOrder?: number;
+    _visible?: boolean;
+    _tooltip?: string | ((context: any) => string);
+    _groupLabel?: string;
+    _toggleBehavior?: 'normal' | 'radio' | 'disabled';
 };
-type Constructor<TType extends ChartType, TInstance> = new (type: TType, labels: (string | number)[], datasets: TType extends CartesianChartType ? CartesianDataset<TType>[] : ChartDataset<TType, (number | null)[]>[], options?: CustomChartOptions<TType>, plugins?: []) => TInstance;
+type Constructor<TType extends ChartType, TInstance> = new (type: TType, labels: (string | number)[], datasets: ChartDataset<TType, (number | null)[]>[], options?: CustomChartOptions<TType>, plugins?: []) => TInstance;
 type CustomCartesianDataset<TType extends CartesianChartType = CartesianChartType> = ChartDataset<TType, (number | null)[]> & {
     yAxisID?: string;
     xAxisID?: string;
@@ -280,6 +295,13 @@ type CustomCartesianDataset<TType extends CartesianChartType = CartesianChartTyp
     _dskey?: string;
     image?: string;
     images?: string[];
+    _aux?: boolean;
+    _group?: string | number;
+    _legendOrder?: number;
+    _visible?: boolean;
+    _tooltip?: string | ((context: any) => string);
+    _groupLabel?: string;
+    _toggleBehavior?: 'normal' | 'radio' | 'disabled';
 };
 type HtmlLegendOptions = {
     containerID: string;
@@ -397,6 +419,7 @@ interface DoughnutChartBuilder extends ArcChartBuilder<'doughnut'> {
 type Types_Align = Align;
 type Types_ArcChartBuilder<TType extends ArcChartType> = ArcChartBuilder<TType>;
 type Types_ArcChartType = ArcChartType;
+type Types_ArcDataset<TType extends ArcChartType = ArcChartType> = ArcDataset<TType>;
 type Types_BarChartBuilder = BarChartBuilder;
 type Types_BubbleChartBuilder = BubbleChartBuilder;
 type Types_CartesianChartBuilder<TType extends CartesianChartType> = CartesianChartBuilder<TType>;
@@ -435,7 +458,7 @@ type Types_RadarChartBuilder = RadarChartBuilder;
 type Types_RadialChartType = RadialChartType;
 type Types_SettingOptions = SettingOptions;
 declare namespace Types {
-  export type { Types_Align as Align, Types_ArcChartBuilder as ArcChartBuilder, Types_ArcChartType as ArcChartType, Types_BarChartBuilder as BarChartBuilder, Types_BubbleChartBuilder as BubbleChartBuilder, Types_CartesianChartBuilder as CartesianChartBuilder, Types_CartesianChartType as CartesianChartType, Types_CartesianDataset as CartesianDataset, Types_ChartBuilder as ChartBuilder, Types_Color as Color, Types_CommonAxes as CommonAxes, Types_CommonAxesSacels as CommonAxesSacels, Types_CommonCartesian as CommonCartesian, Types_CommonCartesianAxes as CommonCartesianAxes, Types_CommonCartesianLegendConfig as CommonCartesianLegendConfig, Types_CommonCartesianTicks as CommonCartesianTicks, Types_CommonCartesianTitleConfig as CommonCartesianTitleConfig, Types_CommonTicks as CommonTicks, Types_Constructor as Constructor, Types_CustomArcChartOptions as CustomArcChartOptions, Types_CustomBarChartOptions as CustomBarChartOptions, Types_CustomBubbleChartOptions as CustomBubbleChartOptions, Types_CustomCartesianDataset as CustomCartesianDataset, Types_CustomChartOptions as CustomChartOptions, Types_CustomDoughnutChartOptions as CustomDoughnutChartOptions, Types_CustomLineChartOptions as CustomLineChartOptions, Types_CustomOptionPlugins as CustomOptionPlugins, Types_CustomPieChartOptions as CustomPieChartOptions, Types_DeepPartial as DeepPartial, Types_DeepPartialCartesianAxes as DeepPartialCartesianAxes, Types_DeepPartialPluginOptions as DeepPartialPluginOptions, Types_DoughnutChartBuilder as DoughnutChartBuilder, Types_HtmlLegendOptions as HtmlLegendOptions, Types_LineChartBuilder as LineChartBuilder, Types_Mode as Mode, Types_PieChartBuilder as PieChartBuilder, Types_Position as Position, Types_RadarChartBuilder as RadarChartBuilder, Types_RadialChartType as RadialChartType, Types_SettingOptions as SettingOptions };
+  export type { Types_Align as Align, Types_ArcChartBuilder as ArcChartBuilder, Types_ArcChartType as ArcChartType, Types_ArcDataset as ArcDataset, Types_BarChartBuilder as BarChartBuilder, Types_BubbleChartBuilder as BubbleChartBuilder, Types_CartesianChartBuilder as CartesianChartBuilder, Types_CartesianChartType as CartesianChartType, Types_CartesianDataset as CartesianDataset, Types_ChartBuilder as ChartBuilder, Types_Color as Color, Types_CommonAxes as CommonAxes, Types_CommonAxesSacels as CommonAxesSacels, Types_CommonCartesian as CommonCartesian, Types_CommonCartesianAxes as CommonCartesianAxes, Types_CommonCartesianLegendConfig as CommonCartesianLegendConfig, Types_CommonCartesianTicks as CommonCartesianTicks, Types_CommonCartesianTitleConfig as CommonCartesianTitleConfig, Types_CommonTicks as CommonTicks, Types_Constructor as Constructor, Types_CustomArcChartOptions as CustomArcChartOptions, Types_CustomBarChartOptions as CustomBarChartOptions, Types_CustomBubbleChartOptions as CustomBubbleChartOptions, Types_CustomCartesianDataset as CustomCartesianDataset, Types_CustomChartOptions as CustomChartOptions, Types_CustomDoughnutChartOptions as CustomDoughnutChartOptions, Types_CustomLineChartOptions as CustomLineChartOptions, Types_CustomOptionPlugins as CustomOptionPlugins, Types_CustomPieChartOptions as CustomPieChartOptions, Types_DeepPartial as DeepPartial, Types_DeepPartialCartesianAxes as DeepPartialCartesianAxes, Types_DeepPartialPluginOptions as DeepPartialPluginOptions, Types_DoughnutChartBuilder as DoughnutChartBuilder, Types_HtmlLegendOptions as HtmlLegendOptions, Types_LineChartBuilder as LineChartBuilder, Types_Mode as Mode, Types_PieChartBuilder as PieChartBuilder, Types_Position as Position, Types_RadarChartBuilder as RadarChartBuilder, Types_RadialChartType as RadialChartType, Types_SettingOptions as SettingOptions };
 }
 
 interface ChartConfig {
@@ -637,7 +660,15 @@ declare abstract class CartesianChartWrapper<TType extends CartesianChartType> e
     protected mustHavePlugins(): {
         id: string;
         afterDraw(chart: any, args: any, options: any): void;
-        afterDestroy(chart: chart_js.Chart): void;
+        afterInit(chart: any, args: any, options: any): void;
+        beforeDatasetUpdate(chart: any, args: any, options: any): void;
+        _handleGroupVisibility(chart: any, datasets: any[]): void;
+        _handleLegendClick(e: any, legendItem: any, legend: any, toggleBehavior: string): void;
+        _setupLegendTooltip(chart: any): void;
+        _hitTestLegend(chart: any, x: number, y: number): any;
+        _showTooltip(e: MouseEvent, tooltipContent: string | ((context: any) => string), legendItem: any): void;
+        _hideTooltip(): void;
+        afterDestroy(chart: any): void;
     }[];
     protected isLine(): boolean;
     protected isScatter(): boolean;
@@ -1375,6 +1406,23 @@ declare class BubbleChartWrapper extends CartesianChartWrapper<'bubble'> impleme
     setAllRotation(rotation: number): this;
 }
 
+/**
+ * ═════════════════════════════════════════════════════════════
+ * 📄 FILE     : ArcChartWrapper.ts
+ * 📁 PACKAGE  : chart-toolbox
+ * 👤 AUTHOR   : stz
+ * 🕒 CREATED  : 25. 9. 28.
+ * ═════════════════════════════════════════════════════════════
+ * ═════════════════════════════════════════════════════════════
+ * 📝 DESCRIPTION
+ *   Arc Chart (Pie, Doughnut) 를 위한 추상 클래스
+ * ═════════════════════════════════════════════════════════════
+ * ═════════════════════════════════════════════════════════════
+ * 🔄 CHANGE LOG
+ *   - DATE : 2025/09/28 | Author : stz | 최초 생성
+ * ═════════════════════════════════════════════════════════════
+ */
+
 declare abstract class ArcChartWrapper<TType extends ArcChartType> extends ChartWrapper<TType> implements ArcChartBuilder<TType> {
     readonly type: TType;
     private _chartId?;
@@ -1396,7 +1444,15 @@ declare abstract class ArcChartWrapper<TType extends ArcChartType> extends Chart
     protected mustHavePlugins(): {
         id: string;
         afterDraw(chart: any, args: any, options: any): void;
-        afterDestroy(chart: chart_js.Chart): void;
+        afterInit(chart: any, args: any, options: any): void;
+        beforeDatasetUpdate(chart: any, args: any, options: any): void;
+        _handleGroupVisibility(chart: any, datasets: any[]): void;
+        _handleLegendClick(e: any, legendItem: any, legend: any, toggleBehavior: string): void;
+        _setupLegendTooltip(chart: any): void;
+        _hitTestLegend(chart: any, x: number, y: number): any;
+        _showTooltip(e: MouseEvent, tooltipContent: string | ((context: any) => string), legendItem: any): void;
+        _hideTooltip(): void;
+        afterDestroy(chart: any): void;
     }[];
     protected normalize(): void;
     protected configAop(config: any): any;
@@ -1672,10 +1728,91 @@ declare const customLegend: {
     }) => HTMLDivElement | undefined;
     afterUpdate(chart: any, args: any, options: any): void;
 };
+/**
+ * @description 차트가 마운트될 때 호출되는 플러그인입니다. 마운트 후 chartjs 인스턴스를 등록하고 _mount 콜백을 실행합니다. 데이터셋의 부가적인 키를 추가하여 범례 동작을 제어하거나 툴팁을 표시할 수 있습니다.
+ *
+ * **지원하는 커스텀 데이터셋 속성:**
+ * - `_aux: boolean` - 차트에는 그려지지만 범례에서 제외
+ * - `_group: string | number` - 같은 그룹의 데이터셋들이 함께 show/hide
+ * - `_visible: boolean` - false면 범례에서 아예 제외하고 데이터셋도 숨김
+ * - `_legendOrder: number` - 범례 표시 순서 제어 (작을수록 앞에 표시)
+ * - `_groupLabel: string` - 같은 그룹을 하나의 범례 항목으로 통합
+ * - `_toggleBehavior: 'normal' | 'radio' | 'disabled'` - 클릭 동작 방식
+ * - `_tooltip: string | function` - 범례 항목 마우스 오버 시 툴팁 표시
+ *
+ * @since 1.0.0
+ * @category plugin
+ * @example
+ * ```typescript
+ * // 기본 사용법
+ * const datasets = [
+ *   {
+ *     label: 'Revenue',
+ *     data: [100, 150, 200],
+ *     _legendOrder: 1,
+ *     _tooltip: 'Monthly revenue data'
+ *   },
+ *   {
+ *     label: 'Background Process',
+ *     data: [10, 15, 20],
+ *     _aux: true // 차트에는 보이지만 범례에서 제외
+ *   },
+ *   {
+ *     label: 'Team A',
+ *     data: [80, 85, 90],
+ *     _groupLabel: 'Team Performance',
+ *     _group: 'teams'
+ *   },
+ *   {
+ *     label: 'Team B',
+ *     data: [75, 80, 85],
+ *     _groupLabel: 'Team Performance',
+ *     _group: 'teams'
+ *   }
+ * ];
+ *
+ * const chart = ChartWrapper
+ *   .create('bar', ['Jan', 'Feb', 'Mar'], datasets)
+ *   .build('advanced-chart');
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // 라디오 버튼 방식 (하나만 선택 가능)
+ * const datasets = [
+ *   {
+ *     label: 'Option A',
+ *     data: [10, 20, 30],
+ *     _toggleBehavior: 'radio'
+ *   },
+ *   {
+ *     label: 'Option B',
+ *     data: [15, 25, 35],
+ *     _toggleBehavior: 'radio'
+ *   }
+ * ];
+ * ```
+ *
+ * @remarks
+ * - customLegend 플러그인이 등록되어 있으면 자동으로 비활성화됩니다
+ * - 범례가 비활성화된 경우에는 동작하지 않습니다
+ * - 모든 차트 타입에서 사용 가능합니다
+ * - 메모리 누수 방지를 위해 차트 파괴 시 자동으로 정리됩니다
+ *
+ * @beta
+ */
 declare const chartMountPlugin: {
     id: string;
     afterDraw(chart: any, args: any, options: any): void;
-    afterDestroy(chart: Chart): void;
+    afterInit(chart: any, args: any, options: any): void;
+    beforeDatasetUpdate(chart: any, args: any, options: any): void;
+    _handleGroupVisibility(chart: any, datasets: any[]): void;
+    _handleLegendClick(e: any, legendItem: any, legend: any, toggleBehavior: string): void;
+    _setupLegendTooltip(chart: any): void;
+    _hitTestLegend(chart: any, x: number, y: number): any;
+    _showTooltip(e: MouseEvent, tooltipContent: string | ((context: any) => string), legendItem: any): void;
+    _hideTooltip(): void;
+    afterDestroy(chart: any): void;
 };
 declare const blinkPlugin: Plugin$1;
 declare const makeCenterHtml: (percent: number, ok?: number, warn?: number, ng?: number) => string;
@@ -1805,6 +1942,7 @@ declare enum ChartTypes {
 
 declare const ChartToolBox: {
     setErrorLog(enabled: boolean): void;
+    setErrorshield(enabled: boolean): void;
 };
 declare const T$: {
     readonly create: typeof ChartWrapper.create;
@@ -1820,8 +1958,9 @@ declare const T$: {
     readonly defaultsOptions: typeof LocalDefaults;
     readonly toolBox: {
         setErrorLog(enabled: boolean): void;
+        setErrorshield(enabled: boolean): void;
     };
 };
 
 export { ArcChartWrapper, BarChartWrapper, BubbleChartWrapper, CartesianChartWrapper, ChartFactory, ChartInstance, ChartToolBox, ChartTypes, ChartWrapper, CreateZoomRangeSlider, DoughnutChartWrapper, LineChartWrapper, T$, barScaleImgPlugin, blinkPlugin, changeSetting, chartMountPlugin, createDefaultBarOptions, createDefaultBubbleOptions, createDefaultLineOptions, customLegend, T$ as default, defaultBarScales, defaultBarTooltipCallback, defaultBubbleScales, defaultBubbleTooltipCallback, defaultLineScales, defaultLineTooltipCallback, doughnutCenterTextPlugin, loadingPlugin, makeCenterHtml, noDataPlugin, sparkBarOptions, sparkBubbleOptions, sparkLineOptions, zoomRangeSlider, zoomResetPlugin };
-export type { Align, AllChartTypes, ArcChartBuilder, ArcChartType, AxisColors, BarChartBuilder, BubbleChartBuilder, CartesianChartBuilder, CartesianChartType, CartesianDataset, ChartBuilder, ChartWithFocus, Color, CommonAxes, CommonAxesSacels, CommonCartesian, CommonCartesianAxes, CommonCartesianLegendConfig, CommonCartesianTicks, CommonCartesianTitleConfig, CommonTicks, Constructor, CustomArcChartOptions, CustomBarChartOptions, CustomBubbleChartOptions, CustomCartesianDataset, CustomChartOptions, CustomDoughnutChartOptions, CustomLineChartOptions, CustomOptionPlugins, CustomPieChartOptions, CustomZoomType, DataLabels, DataLabelsContext, DatasetWithPrevColors, DeepPartial, DeepPartialCartesianAxes, DeepPartialPluginOptions, DeepPartialZoomType, DoughnutChartBuilder, FocusCallback, HtmlLegendOptions, LineChartBuilder, Mode, OriginalColors, PartialDataLabels, PieChartBuilder, Position, RadarChartBuilder, RadialChartType, ScaleWithOriginalColors, SettingOptions, ZoomRangeSliderColors, ZoomRangeSliderPlugin, ZoomRangeSliderVar };
+export type { Align, AllChartTypes, ArcChartBuilder, ArcChartType, ArcDataset, AxisColors, BarChartBuilder, BubbleChartBuilder, CartesianChartBuilder, CartesianChartType, CartesianDataset, ChartBuilder, ChartWithFocus, Color, CommonAxes, CommonAxesSacels, CommonCartesian, CommonCartesianAxes, CommonCartesianLegendConfig, CommonCartesianTicks, CommonCartesianTitleConfig, CommonTicks, Constructor, CustomArcChartOptions, CustomBarChartOptions, CustomBubbleChartOptions, CustomCartesianDataset, CustomChartOptions, CustomDoughnutChartOptions, CustomLineChartOptions, CustomOptionPlugins, CustomPieChartOptions, CustomZoomType, DataLabels, DataLabelsContext, DatasetWithPrevColors, DeepPartial, DeepPartialCartesianAxes, DeepPartialPluginOptions, DeepPartialZoomType, DoughnutChartBuilder, FocusCallback, HtmlLegendOptions, LineChartBuilder, Mode, OriginalColors, PartialDataLabels, PieChartBuilder, Position, RadarChartBuilder, RadialChartType, ScaleWithOriginalColors, SettingOptions, ZoomRangeSliderColors, ZoomRangeSliderPlugin, ZoomRangeSliderVar };