stz-chart-maker 1.0.16 → 1.0.18

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ChartType, PluginOptionsByType, ChartOptions, GridLineOptions, FontSpec, Tick, Chart, ChartDataset, ChartTypeRegistry, Plugin as Plugin$1, TooltipItem } from 'chart.js';
+import { ChartType, PluginOptionsByType, ChartOptions, GridLineOptions, FontSpec, Tick, Chart, ChartEvent, ActiveElement, 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';
 
@@ -210,6 +210,12 @@ type CustomChartOptions<TType extends ChartType = ChartType> = Override<ChartOpt
             right?: number;
         };
     };
+    onResize?: (this: Chart<TType>, chart: Chart<TType>, size: {
+        width: number;
+        height: number;
+    }) => void;
+    onClick?: (this: Chart<TType>, event: ChartEvent, elements: ActiveElement[]) => void;
+    onHover?: (this: Chart<TType>, event: ChartEvent, elements: ActiveElement[]) => void;
 }> & {
     _mounted?: (chart: Chart<TType>) => void;
     _chartId?: string;
@@ -337,6 +343,7 @@ declare namespace Types {
 interface ChartConfig {
     _chartId: string;
     type: ChartType;
+    datasetIdKey?: string;
     data: any;
     options: any;
     plugins?: any;
@@ -350,34 +357,55 @@ declare abstract class ChartWrapper<TType extends ChartType> implements ChartBui
     static registry: Map<string, Constructor<any, any>>;
     constructor(type: TType, labels: (string | number)[], datasets: ChartDataset<TType, (number | null)[]>[], options: CustomChartOptions<TType>, plugins?: any | undefined);
     static create<TType extends ChartType>(type: TType, labels: (string | number)[], datasets: ChartDataset<TType, (number | null)[]>[], options?: CustomChartOptions<TType>, plugins?: any): TType extends CartesianChartType ? CartesianChartBuilder<TType> : ChartBuilder<TType>;
+    static register<TType extends ChartType, TInstance>(type: TType, wrapperClass: Constructor<TType, TInstance>): void;
+    static has(type: ChartType): boolean;
     protected abstract normalize(): void;
     protected abstract configAop(config: any): any;
-    static register<TType extends ChartType, TInstance>(type: TType, wrapperClass: Constructor<TType, TInstance>): void;
+    abstract build(id?: string): ChartConfig;
     /**
-     * 플러그인을 추가합니다.
+     * @description 플러그인을 추가합니다.
      * @param plugin
      * @param replaceIfExists
-     *
+     * @Since 1.0.0
+     * @category plugin
      */
     setPlugin(plugin: any, replaceIfExists?: boolean): this;
     /**
-     * 차트 설정 객체를 생성합니다.
+     * @Description 레거시 지원용 차트 설정 객체를 생성합니다.
      * @param {string} id
      * @returns {ChartConfig}
-     * @Description 레거시 지원용
+     * @Since 1.0.0
+     * @category config
      */
     makeConfig(id?: string): ChartConfig;
     /**
-     * 플러그인을 제거합니다.
+     * @description 플러그인을 제거합니다.
      * @param pluginId
+     * @Since 1.0.0
+     * @category plugin
+     *
      */
     removePlugin(pluginId: string): this;
     /**
-     * 플러그인이 존재하는지 확인합니다.
+     * @description 플러그인이 존재하는지 확인합니다.
      * @param pluginId
+     * @returns {boolean}
+     * @Since 1.0.0
+     * @category plugin
      */
     hasPlugin(pluginId: string): boolean;
-    abstract build(id?: string): ChartConfig;
+    /**
+     * @beta
+     * @description 차트 리사이즈 이벤트 콜백 함수를 설정합니다.
+     * @param callback
+     * @returns {this}
+     * @Since 1.0.0
+     * @category options
+     */
+    onResize(callback: (chart: Chart<TType>, size: {
+        width: number;
+        height: number;
+    }) => void): this;
 }
 
 interface AxisColors {
@@ -449,6 +477,15 @@ declare abstract class CartesianChartWrapper<TType extends CartesianChartType> e
     get chartId(): string;
     set chartId(value: string);
     protected requireLabels(): boolean;
+    /**
+     * @protected
+     * @description 데이터셋의 기본적은 옵션을 추가하거나 부여합니다.
+     * @param ds
+     * @param {number} idx
+     * @Returns {void}
+     * @Since 1.0.1
+     * @category Dataset
+     */
     protected decorateDataset(ds: any, idx: number): void;
     protected mustHavePlugins(): {
         id: string;
@@ -459,7 +496,20 @@ declare abstract class CartesianChartWrapper<TType extends CartesianChartType> e
     protected isBar(): boolean;
     protected normalize(): void;
     protected configAop(config: any): any;
+    /**
+     * @Description 차트 설정 객체를 생성합니다. 이 메소드는 차트의 구성 요소를 종합하여 Chart.js에서 사용할 수 있는 형식으로 반환합니다.
+     * @param id
+     * @returns {ChartConfig}
+     * @Since 1.0.0
+     * @category Chart
+     */
     build(id?: string): ChartConfig;
+    /**
+     * @deprecated
+     * @description 차트 설정 객체를 생성합니다. 이 메소드는 레거시 지원용으로, Chart.js에서 사용할 수 있는 형식으로 반환합니다.
+     * @param {string} id
+     * @returns {{data: any, plugins: any, _chartId: any, options: any, type: any}}
+     */
     makeConfig(id?: string): {
         _chartId: any;
         type: any;
@@ -468,36 +518,25 @@ declare abstract class CartesianChartWrapper<TType extends CartesianChartType> e
         plugins: any;
     };
     /**
-     *  Cartesian chart type을 체크 합니다.
      * @private
-     * *
-     * @remarks cartesina 차트의 타입인지 확인합니다
-     * @example
+     * @description Cartesian chart type을 체크 합니다.
      * @since 1.0.0
      * @category Chart
-     * @defaultValue
-     *
      */
     private isCartesianChartType;
     /**
-     * 카테시안 차트의 스케일을 설정합니다.
+     * @description 카테시안 차트의 스케일을 설정합니다.
      * @param scales
-     * *
-     * @remarks 카테시안 차트의 스케일을 설정합니다. 이 메소드는 차트의 축을 정의하는데 사용됩니다.
-     * @example
+     * @returns {this}
      * @since 1.0.0
      * @category Scales
-     * @defaultValue
-     *
      */
     setScales(scales: CommonAxesSacels): this;
     /**
-     * 카테시안 차트의 축 제목을 설정합니다.
+     * @description 카테시안 차트의 축 제목을 설정합니다.
      * @param axis
      * @param titleConfig
-     * *
-     * @remarks 원하는 축의 제목을 설정합니다.
-     * @example
+     * @returns {this}
      * @since 1.0.0
      * @category Scales
      * @defaultValue
@@ -505,16 +544,12 @@ declare abstract class CartesianChartWrapper<TType extends CartesianChartType> e
      */
     setAxisTitle(axis: 'x' | 'y', titleConfig: CommonCartesianTitleConfig): this;
     /**
-     * 카테시안 차트의 그리드 옵션을 설정합니다.
+     * @description 카테시안 차트의 그리드 옵션을 설정합니다.
      * @param axis
      * @param gridOptions
-     * *
-     * @remarks 차트 뒷 배경의 그리드(선) 옵션을 설정합니다.
-     * @example
+     * @returns {this}
      * @since 1.0.0
      * @category Scales
-     * @defaultValue
-     *
      */
     setGridOptions(axis: 'x' | 'y', gridOptions: {
         display?: boolean;
@@ -522,12 +557,10 @@ declare abstract class CartesianChartWrapper<TType extends CartesianChartType> e
         lineWidth?: number;
     }): this;
     /**
-     * 줌 기능을 추가합니다.
+     * @description 줌 기능을 추가합니다. 해당 기능은 플러그인 설치가 필요합니다.
      * @param defaultZoom
      * @param zoomOption
-     * *
-     * @remarks 차트의 줌 기능을 추가합니다. 해당 기능은 플러그인 설치가 필요합니다.
-     * @example
+     * @returns {this}
      * @since 1.0.0
      * @category Plugins
      * @defaultValue defaultZoom = false
@@ -535,85 +568,70 @@ declare abstract class CartesianChartWrapper<TType extends CartesianChartType> e
      */
     addZoom(defaultZoom?: boolean, zoomOption?: object): this;
     /**
-     * 데이터 라벨 플러그인을 추가합니다.
+     * @Description 차트에 데이터 라벨을 추가합니다. 기본 옵션을 사용하거나 사용자 정의 옵션을 적용할 수 있습니다.
      * @param defultDataLabels
      * @param dataLabelsOptions
-     * @Description 차트에 데이터 라벨을 추가합니다. 기본 옵션을 사용하거나 사용자 정의 옵션을 적용할 수 있습니다.
+     * @returns {this}
      * @Category Plugins
      * @since 1.0.0
      * @defaultValue defultDataLabels = false
      */
     addDataLabels(defultDataLabels: boolean | undefined, dataLabelsOptions: PartialDataLabels): this;
     /**
-     * 데이터셋에 y축을 설정합니다.
+     * @description 데이터셋에 y축을 설정합니다.
      * @param datasetIndex
      * @param axisId
-     * *
-     * @remarks 각 데이터셋의 축을 설정합니다.
-     * @example
+     * @returns {this}
      * @since 1.0.0
      * @category Scales
      * @defaultValue axisId = 'y'
-     *
      */
     setYAxisForDataset(datasetIndex: number, axisId?: string): this;
     /**
-     * y1 축을 보장합니다.
      * @private
-     * *
-     * @remarks y1 축이 없을 경우 기본 구조를 추가합니다. 이 메소드는 y1 축을 사용하는 차트에서 필요합니다.
-     * @example
+     * @description y1 축을 보장합니다.
      * @since 1.0.0
      * @category Scales
-     * @defaultValue
-     *
      */
     private ensureY1AxisExists;
     /**
-     * 카테시안 차트의 축 범위를 설정합니다.
+     * @description 카테시안 차트의 축 범위를 설정합니다. 해당 차트의 스케일을 min, max 를 입력 받은 값으로 고정합니다.
      * @param axis
      * @param min
      * @param max
-     *
-     * *
-     * @remarks 해당 차트의 스케일을 min, max 를 입력 받은 값으로 고정합니다.
-     * @example
+     * @returns {this}
      * @since 1.0.0
      * @category Scales
-     * @defaultValue
-     *
      */
     setAxisRange(axis: 'x' | 'y', min?: number, max?: number): this;
     /**
-     * 데이터셋의 yAxisID를 설정합니다.
+     * @description 데이터셋의 yAxisID를 설정합니다.
      * @param datasetIndex
      * @param axisID
-     * *
-     * @remarks 각 데이터셋의 축 아이디를 변경합니다.
-     * @example
+     * @returns {this}
+     * @throws {CustomError} 해당 차트 타입이 yAxisID 옵션을 지원하지 않을 경우 에러를 발생시킵니다.
      * @since 1.0.0
      * @category Scales
-     * @defaultValue
-     *
      */
     setYAxisID(datasetIndex: number, axisID: string): this;
     /**
-     * 축의 위치를 설정합니다.
+     * @description 축의 위치를 설정합니다.
      * @param axis
      * @param position
-     * *
-     * @remarks 해당하는 축의 위치를 변경합니다.
-     * @example
+     * @returns {this}
+     * @throws {CustomError} 해당 축이 존재하지 않거나 position 옵션을 지원하지 않을 경우 에러를 발생시킵니다.
      * @since 1.0.0
      * @category Scales
-     * @defaultValue
-     *
      */
     setAxisPosition(axis: string, position: 'left' | 'right'): this;
     /**
-     * 축에 이미지를 추가합니다.
+     * @description 축에 이미지를 추가합니다.
      * @param {string} axis
+     * @returns {this}
+     * @throws {CustomError} 이미지 속성이 없는 데이터셋이 있을 경우 에러를 발생시킵니다.
      * @Deprecated
+     * @Category Scales
+     * @Since 1.0.0
      */
     setAddImg(axis: string): this;
     /**
@@ -622,43 +640,106 @@ declare abstract class CartesianChartWrapper<TType extends CartesianChartType> e
      * @Deprecated
      */
     addRangeSlider(colors?: ZoomRangeSliderColors): this;
+    /**
+     * @description 차트의 패딩을 설정합니다.
+     * @param padding
+     * @returns {this}
+     * @Category options
+     * @Since 1.0.0
+     */
     setPadding(padding: any): this;
+    /**
+     * @description 데이터셋의 배경색에 알파 값을 설정합니다.
+     * @param {number} alpha
+     * @returns {this}
+     * @throws {CustomError} 알파 값이 0.0 미만 또는 1.0 초과일 경우 에러를 발생시킵니다.
+     * @Since 1.0.0
+     * @Category Dataset
+     */
     setBackgroundAlpha(alpha: number): this;
     /**
-     * 색상에 알파 값을 추가합니다.
+     * @private
+     * @description 색상에 알파 값을 추가합니다.
      * @param color
      * @param alpha
-     * @private
+     * @returns {string}
      */
     private addAlphaToColor;
     /**
-     *
+     * @description 데이터셋의 파싱 키를 설정합니다. xAxisKey와 yAxisKey를 각각 설정할 수 있습니다. false로 설정하면 해당 축에 대한 파싱을 비활성화합니다.
      * @param {string | false} xAxisKey
      * @param {string | false} yAxisKey
-     * @description
+     * @throws {CustomError} xAxisKey와 yAxisKey가 모두 false일 경우 에러를 발생시킵니다.
+     * @returns {this}
      * @Category options
      * @Since 1.0.0
      */
     setParsingKey(xAxisKey: string | false, yAxisKey: string | false): this;
+    /**
+     * @description 특정 데이터셋의 파싱 키를 설정합니다. xAxisKey와 yAxisKey를 각각 설정할 수 있습니다. false로 설정하면 해당 축에 대한 파싱을 비활성화합니다.
+     * @param {number} datasetIndex
+     * @param {string | false} xAxisKey
+     * @param {string | false} yAxisKey
+     * @returns {this}
+     * @throws {CustomError} 데이터셋이 존재하지 않을 경우 에러를 발생시킵니다.
+     * @Category options
+     * @Since 1.0.0
+     */
     setDatasetParsing(datasetIndex: number, xAxisKey: string | false, yAxisKey: string | false): this;
+    /**
+     * @description 모든 데이터셋의 파싱 키를 설정합니다. xAxisKey와 yAxisKey를 각각 설정할 수 있습니다. false로 설정하면 해당 축에 대한 파싱을 비활성화합니다.
+     * @param {string | false} xAxisKey
+     * @param {string | false} yAxisKey
+     * @returns {this}
+     * @throws {CustomError} 데이터셋이 존재하지 않을 경우 에러를 발생시킵니다.
+     * @Category options
+     * @Since 1.0.0
+     */
     setAllDatasetsParsing(xAxisKey: string | false, yAxisKey: string | false): this;
+    /**
+     * @description HTML 범례를 추가합니다. 해당 기능은 플러그인 설치가 필요합니다.
+     * @param {HtmlLegendOptions} obj
+     * @returns {this}
+     * @throws {CustomError} 옵션이 비어있거나 객체가 아닐 경우 에러를 발생시킵니다.
+     * @Since 1.0.0
+     * @category Plugins
+     */
     customLegend(obj: HtmlLegendOptions): this;
-}
-
-type AllChartTypes = keyof ChartTypeRegistry;
-declare enum ChartTypes {
-    BAR = "bar",
-    LINE = "line",
-    DOUGHNUT = "doughnut",
-    PIE = "pie",
-    RADAR = "radar",
-    BUBBLE = "bubble",
-    SCATTER = "scatter",
-    TREE = "tree"
+    /**
+     * @Beta
+     * @description 데이터셋 배열에서 주어진 UID와 일치하는 데이터셋을 반환합니다. UID가 없거나 데이터셋이 비어있으면 undefined를 반환합니다.
+     * @param {string} uid
+     * @returns {CustomCartesianDataset<TType> | undefined}
+     * @throws {CustomError} UID가 없거나 데이터셋이 비어있을 때 에러를 발생시킵니다.
+     * @Since 1.0.0
+     * @category Dataset
+     */
+    getDataset(uid: string): CustomCartesianDataset<TType> | undefined;
+    /**
+     * @Beta
+     * @description 주어진 UID를 가진 데이터셋을 새로운 데이터셋으로 교체합니다. UID가 없거나 데이터셋이 비어있으면 에러를 발생시킵니다.
+     * @param {string} uid
+     * @param {CustomCartesianDataset<TType>} dataset
+     * @returns {this}
+     * @throws {CustomError} UID가 없거나 데이터셋이 비어있을 때 에러를 발생시킵니다.
+     * @Since 1.0.0
+     * @category Dataset
+     */
+    setDataset(uid: string, dataset: CustomCartesianDataset<TType>): this;
+    /**
+     * @Beta
+     * @description 새로운 데이터셋을 추가하고 고유 식별자(UID)를 반환합니다. 데이터셋 배열이 비어있으면 새로 생성합니다.
+     * @param {CustomCartesianDataset<TType>} dataset
+     * @returns {string}
+     * @throws {CustomError} 데이터셋이 null 또는 undefined일 때 에러를 발생시킵니다.
+     * @Since 1.0.0
+     * @category Dataset
+     */
+    addDataset(dataset: CustomCartesianDataset<TType>): string;
 }
 
 declare class BarChartWrapper extends CartesianChartWrapper<'bar'> implements BarChartBuilder {
-    constructor(type: ChartTypes.BAR, labels: (string | number)[], datasets: CartesianDataset<ChartTypes.BAR>[], options?: CustomBarChartOptions, plugins?: any);
+    constructor(type: 'bar', labels: (string | number)[], datasets: CartesianDataset<'bar'>[], options?: CustomBarChartOptions, plugins?: any);
     protected requireLabels(): boolean;
     makeConfig(id?: string): {
         _chartId: any;
@@ -789,8 +870,27 @@ declare class BarChartWrapper extends CartesianChartWrapper<'bar'> implements Ba
 }
 
 declare class LineChartWrapper extends CartesianChartWrapper<'line'> implements LineChartBuilder {
-    constructor(type: ChartTypes.LINE, labels: (string | number)[], datasets: CartesianDataset<'line'>[], options?: CustomChartOptions<'line'>);
+    constructor(type: 'line', labels: (string | number)[], datasets: CartesianDataset<'line'>[], options?: CustomChartOptions<'line'>);
+    /**
+     *
+     * @protected
+     * @returns {boolean}
+     * @description 라인 차트는 카테고리형 x축일 때 라벨이 필수입니다.
+     * @Since 1.0.0
+     * @category config
+     * @override
+     */
     protected requireLabels(): boolean;
+    /**
+     *
+     * @param id
+     * @returns {ChartConfiguration}
+     * @description 차트 설정 객체를 생성합니다.
+     * @Since 1.0.0
+     * @category config
+     * @override
+     * @Deprecated use build() Method
+     */
     makeConfig(id?: string): {
         _chartId: any;
         type: any;
@@ -879,6 +979,58 @@ declare class LineChartWrapper extends CartesianChartWrapper<'line'> implements
      *
      */
     setAllPointHoverRadius(hoverRadius: number): this;
+    /**
+     *
+     * @param {number} datasetIndex - 대상 데이터셋 인덱스
+     * @param {number} steps - 그라디언트 단계 (2단계면 0,1 / 3단계면 0,0.5,1)
+     * @param {string[]} colors - 색상 배열 (steps와 같은 길이여야 함)
+     * @param {'vertical' | 'horizontal'} direction - 그라디언트 방향 (기본값: vertical)
+     * @description 지정된 데이터셋에 단계별 그라디언트를 적용합니다.
+     * @remarks step 인자는 2 이상만 지원할것입니다.
+     * @Since 1.0.0
+     * @category dataset
+     * @beta (기능 테스트 중)
+     */
+    setGradient(datasetIndex: number, steps: number, colors: string[], direction?: 'vertical' | 'horizontal'): this;
+    /**
+     *
+     * @param {number} steps - 그라디언트 단계
+     * @param {string[]} colors - 색상 배열
+     * @param {'vertical' | 'horizontal'} direction - 그라디언트 방향 (기본값: vertical)
+     * @description 모든 데이터셋에 동일한 그라디언트를 적용합니다.
+     * @Since 1.0.0
+     * @category dataset
+     * @beta (기능 테스트 중)
+     */
+    setAllGradient(steps: number, colors: string[], direction?: 'vertical' | 'horizontal'): this;
+    /**
+     *
+     * @param {number} datasetIndex - 대상 데이터셋 인덱스
+     * @description 지정된 데이터셋의 그라디언트를 제거합니다.
+     * @Since 1.0.0
+     * @category dataset
+     * @beta (기능 테스트 중)
+     */
+    removeGradient(datasetIndex: number): this;
+    /**
+     *
+     * @description 모든 데이터셋의 그라디언트를 제거합니다.
+     * @Since 1.0.0
+     * @category dataset
+     * @beta (기능 테스트 중)
+     */
+    removeAllGradients(): this;
+    /**
+     *
+     * @param {number} steps - 단계 수
+     * @returns {number[]} 0부터 1까지의 위치 배열
+     * @description 주어진 단계 수에 따라 그라디언트 위치를 계산합니다.
+     * @Since 1.0.0
+     * @category utility
+     * @private
+     * @beta (기능 테스트 중)
+     */
+    private calculateGradientPositions;
 }
 
 declare const noDataPlugin: {
@@ -1022,7 +1174,7 @@ declare namespace LocalDefaults {
 declare class ChartFactory {
     private static registry;
     static register<TType extends ChartType, TInstance>(type: TType, wrapperClass: Constructor<TType, TInstance>): void;
-    static create<TType extends ChartType>(type: TType, ...args: ConstructorParameters<Constructor<TType, any>>): any;
+    static create<TType extends ChartType>(type: TType, labels: (string | number)[], datasets: ChartDataset<TType, (number | null)[]>[], options?: CustomChartOptions<TType>, plugins?: any): any;
     static has(type: ChartType): boolean;
     static clear(): void;
 }
@@ -1039,9 +1191,20 @@ declare class ChartInstance {
     static resize(id: string): void;
 }
 
+type AllChartTypes = keyof ChartTypeRegistry;
+declare enum ChartTypes {
+    BAR = "bar",
+    LINE = "line",
+    DOUGHNUT = "doughnut",
+    PIE = "pie",
+    RADAR = "radar",
+    BUBBLE = "bubble",
+    SCATTER = "scatter",
+    TREE = "tree"
+}
+
 declare const ChartToolBox: {
     setErrorLog(enabled: boolean): void;
-    setDebugLog(enabled: boolean): void;
 };
 declare const T$: {
     readonly create: typeof ChartWrapper.create;
@@ -1054,7 +1217,6 @@ declare const T$: {
     readonly defaultsOptions: typeof LocalDefaults;
     readonly toolBox: {
         setErrorLog(enabled: boolean): void;
-        setDebugLog(enabled: boolean): void;
     };
 };