stz-chart-maker 2.3.4 → 2.3.6

package/README.md

@@ -66,6 +66,7 @@ setChartConfig({
   silentMode: false,
   defaultColor: ['#FF6B6B', '#4ECDC4', '#45B7D1', '#FFA07A', '#98D8C8', '#F7DC6F'],
   zoom: true,
+  loading: true,
   legend: {
     position: 'top'
   },
@@ -94,9 +95,43 @@ module.exports = {
 | `silentMode` | `boolean` | `true` | 에러 발생 시 예외를 던지지 않고 처리 |
 | `defaultColor` | `string[]` | 내부 기본 팔레트 | 차트 전역 기본 색상 배열 |
 | `zoom` | `boolean \| object` | `false` | `line`, `bar`, `bubble` 차트에 전역 zoom 기본값 적용 |
+| `loading` | `boolean` | `false` | Cartesian 차트에 전역 loading 기본값 적용 |
 | `legend` | `object` | 차트 기본값 사용 | 차트 전역 legend 기본 옵션 적용 |
 | `tooltip` | `object` | 차트 기본값 사용 | 차트 전역 tooltip 기본 옵션 적용 |
 
+## Export / Empty State
+
+```tsx
+import { ChartWrapper, downloadChartAsImage, setChartConfig } from 'stz-chart-maker';
+
+setChartConfig({ loading: true });
+
+const chartConfig = ChartWrapper
+  .create('bar', [], [{ data: [] }], {
+    _noDataText: '데이터 없음',
+  })
+  .build('sales-chart');
+
+downloadChartAsImage('sales-chart');
+```
+
+```tsx
+import {
+  hideChartTooltip,
+  isChartDatasetVisible,
+  setChartDatasetVisibility,
+  showChartTooltip,
+  toggleChartDatasetVisibility,
+} from 'stz-chart-maker';
+
+setChartDatasetVisibility('sales-chart', 1, false);
+const visible = toggleChartDatasetVisibility('sales-chart', 0);
+console.log(isChartDatasetVisible('sales-chart', 0), visible);
+
+showChartTooltip('sales-chart', [{ datasetIndex: 0, index: 2 }]);
+hideChartTooltip('sales-chart');
+```
+
 ### 변경기록
 [CHANGELOG.md](./CHANGELOG.md) 파일을 참조하세요.
 

package/dist/index.d.ts

@@ -448,6 +448,7 @@ type CustomChartOptions<TType extends ChartType = ChartType> = Override<ChartOpt
     _mounted?: (chart: Chart$1<TType>) => void;
     _chartId?: string;
     _loading?: boolean;
+    _noDataText?: string;
 };
 type CustomArcChartOptions<TType extends ArcChartType = ArcChartType> = CustomChartOptions<TType> & {
     scales?: never;
@@ -1071,6 +1072,7 @@ declare abstract class CartesianChart<TType extends CartesianChartType> extends
         _hideTooltip(chart: any): void;
         afterDestroy(chart: any): void;
     })[];
+    protected resolveMustHavePlugins(options?: CustomChartOptions<TType>): any[];
     protected isLine(): boolean;
     protected isScatter(): boolean;
     protected isBar(): boolean;
@@ -2034,6 +2036,7 @@ declare abstract class ArcChart<TType extends ArcChartType> extends Chart<TType>
         afterDraw(chart: any, args: any, options: any): void;
         afterDestroy(chart: any): void;
     }[];
+    protected resolveMustHavePlugins(options?: CustomArcChartOptions<TType>): any[];
     protected normalize(): void;
     protected configAop(config: any): any;
     /**
@@ -2478,6 +2481,7 @@ declare class TreemapChart extends Chart<'treemap', CustomTreemapChartOptions> i
         afterDraw(chart: any, args: any, options: any): void;
         afterDestroy(chart: any): void;
     }[];
+    protected resolveMustHavePlugins(options?: CustomTreemapChartOptions): any[];
     protected configAop(config: any): any;
     /**
      * @Description 차트 설정 객체를 생성합니다.
@@ -3136,6 +3140,7 @@ interface StzConfig {
     silentMode?: boolean;
     defaultColor?: string[];
     zoom?: boolean | DeepPartialZoomType;
+    loading?: boolean;
     legend?: DeepPartial<LegendOptions<any>>;
     tooltip?: DeepPartial<TooltipOptions<any>>;
     /** @deprecated no-op. Built-in chart types are bootstrapped at package load time. */
@@ -3156,6 +3161,7 @@ interface StzConfig {
  *   silentMode: false,
  *   defaultColor: ['#111111', '#22c55e', '#3b82f6'],
  *   zoom: true,
+ *   loading: true,
  *   legend: {
  *     position: 'top'
  *   },
@@ -3186,16 +3192,183 @@ interface ChartImageExportOptions {
     filename?: string;
     scale?: number;
 }
+type ChartTarget = string | Chart$1;
 /**
- * @description 차트를 이미지로 다운로드합니다.
- * @param chartId 차트 ID
+ * 차트 ID 또는 Chart 인스턴스로 실제 Chart.js 인스턴스를 조회합니다.
+ * @param target 차트 ID 또는 Chart 인스턴스
+ * @returns Chart.js 인스턴스
+ * @since 2.3.5
+ * @category util
+ * @example
+ * ```ts
+ * const chart = getChartInstance('sales-chart');
+ * chart.update();
+ * ```
+ */
+declare function getChartInstance(chart: Chart$1): Chart$1;
+declare function getChartInstance(chartId: string): Chart$1;
+/**
+ * 차트의 zoom 상태를 초기화합니다.
+ * @param target 차트 ID 또는 Chart 인스턴스
+ * @since 2.3.5
+ * @category util
+ * @example
+ * ```ts
+ * resetChartZoom('sales-chart');
+ * ```
+ */
+declare function resetChartZoom(chart: Chart$1): void;
+declare function resetChartZoom(chartId: string): void;
+/**
+ * 차트를 수동으로 다시 렌더링합니다.
+ * @param target 차트 ID 또는 Chart 인스턴스
+ * @param mode Chart.js update mode
+ * @since 2.3.5
+ * @category util
+ * @example
+ * ```ts
+ * updateChart('sales-chart', 'none');
+ * ```
+ */
+declare function updateChart(chart: Chart$1, mode?: Parameters<Chart$1['update']>[0]): void;
+declare function updateChart(chartId: string, mode?: Parameters<Chart$1['update']>[0]): void;
+/**
+ * 차트 크기를 다시 계산합니다.
+ * @param target 차트 ID 또는 Chart 인스턴스
+ * @since 2.3.5
+ * @category util
+ * @example
+ * ```ts
+ * resizeChart('sales-chart');
+ * ```
+ */
+declare function resizeChart(chart: Chart$1): void;
+declare function resizeChart(chartId: string): void;
+/**
+ * 차트의 active element를 강제로 설정합니다.
+ * @param target 차트 ID 또는 Chart 인스턴스
+ * @param activeElements 활성화할 요소 목록
+ * @since 2.3.5
+ * @category util
+ * @example
+ * ```ts
+ * setChartActiveElements('sales-chart', [{ datasetIndex: 0, index: 2 }]);
+ * ```
+ */
+declare function setChartActiveElements(chart: Chart$1, activeElements: ActiveElement[]): void;
+declare function setChartActiveElements(chartId: string, activeElements: ActiveElement[]): void;
+/**
+ * 차트의 active element를 모두 해제합니다.
+ * @param target 차트 ID 또는 Chart 인스턴스
+ * @since 2.3.5
+ * @category util
+ * @example
+ * ```ts
+ * clearChartActiveElements('sales-chart');
+ * ```
+ */
+declare function clearChartActiveElements(chart: Chart$1): void;
+declare function clearChartActiveElements(chartId: string): void;
+/**
+ * 특정 dataset의 표시 여부를 강제로 설정합니다.
+ * @param target 차트 ID 또는 Chart 인스턴스
+ * @param datasetIndex dataset index
+ * @param visible 표시 여부
+ * @since 2.3.5
+ * @category util
+ * @example
+ * ```ts
+ * setChartDatasetVisibility('sales-chart', 1, false);
+ * ```
+ */
+declare function setChartDatasetVisibility(chart: Chart$1, datasetIndex: number, visible: boolean): void;
+declare function setChartDatasetVisibility(chartId: string, datasetIndex: number, visible: boolean): void;
+/**
+ * 특정 dataset의 표시 여부를 토글합니다.
+ * @param target 차트 ID 또는 Chart 인스턴스
+ * @param datasetIndex dataset index
+ * @returns 토글 후 표시 여부
+ * @since 2.3.5
+ * @category util
+ * @example
+ * ```ts
+ * const visible = toggleChartDatasetVisibility('sales-chart', 1);
+ * ```
+ */
+declare function toggleChartDatasetVisibility(chart: Chart$1, datasetIndex: number): boolean;
+declare function toggleChartDatasetVisibility(chartId: string, datasetIndex: number): boolean;
+/**
+ * 특정 dataset의 현재 표시 여부를 반환합니다.
+ * @param target 차트 ID 또는 Chart 인스턴스
+ * @param datasetIndex dataset index
+ * @returns 표시 여부
+ * @since 2.3.5
+ * @category util
+ * @example
+ * ```ts
+ * const visible = isChartDatasetVisible('sales-chart', 1);
+ * ```
+ */
+declare function isChartDatasetVisible(chart: Chart$1, datasetIndex: number): boolean;
+declare function isChartDatasetVisible(chartId: string, datasetIndex: number): boolean;
+/**
+ * 차트 tooltip과 active element를 함께 표시합니다.
+ * @param target 차트 ID 또는 Chart 인스턴스
+ * @param activeElements 활성화할 요소 목록
+ * @param position tooltip 위치. 생략 시 활성 요소 위치를 사용합니다.
+ * @since 2.3.5
+ * @category util
+ * @example
+ * ```ts
+ * showChartTooltip('sales-chart', [{ datasetIndex: 0, index: 2 }]);
+ * ```
+ */
+declare function showChartTooltip(chart: Chart$1, activeElements: ActiveElement[], position?: {
+    x: number;
+    y: number;
+}): void;
+declare function showChartTooltip(chartId: string, activeElements: ActiveElement[], position?: {
+    x: number;
+    y: number;
+}): void;
+/**
+ * 차트 tooltip을 숨기고 active element를 해제합니다.
+ * @param target 차트 ID 또는 Chart 인스턴스
+ * @since 2.3.5
+ * @category util
+ * @example
+ * ```ts
+ * hideChartTooltip('sales-chart');
+ * ```
+ */
+declare function hideChartTooltip(chart: Chart$1): void;
+declare function hideChartTooltip(chartId: string): void;
+/**
+ * 특정 dataset의 메타 정보를 반환합니다.
+ * @param target 차트 ID 또는 Chart 인스턴스
+ * @param datasetIndex dataset index
+ * @returns dataset meta
+ * @since 2.3.5
+ * @category util
+ * @example
+ * ```ts
+ * const meta = getChartDatasetMeta('sales-chart', 0);
+ * console.log(meta.data);
+ * ```
+ */
+declare function getChartDatasetMeta(chart: Chart$1, datasetIndex: number): ReturnType<Chart$1['getDatasetMeta']>;
+declare function getChartDatasetMeta(chartId: string, datasetIndex: number): ReturnType<Chart$1['getDatasetMeta']>;
+/**
+ * 차트를 이미지로 다운로드합니다.
+ * @param target 차트 ID 또는 Chart 인스턴스
  * @param options 이미지 내보내기 옵션
  * @since 1.5.0
  * @category util
  */
-declare function downloadChartAsImage(chartId: string, options?: ChartImageExportOptions): void;
+declare function downloadChartAsImage(target: Chart$1, options?: ChartImageExportOptions): void;
+declare function downloadChartAsImage(target: string, options?: ChartImageExportOptions): void;
 /**
- * @description Chart 인스턴스를 이미지로 다운로드합니다.
+ * Chart 인스턴스를 이미지로 다운로드합니다.
  * @param chart Chart 인스턴스
  * @param options 이미지 내보내기 옵션
  * @since 1.5.0
@@ -3203,16 +3376,17 @@ declare function downloadChartAsImage(chartId: string, options?: ChartImageExpor
  */
 declare function downloadChartAsImageByInstance(chart: Chart$1, options?: ChartImageExportOptions): void;
 /**
- * @description 차트를 Base64 문자열로 반환합니다.
- * @param chartId 차트 ID
+ * 차트를 Base64 문자열로 반환합니다.
+ * @param target 차트 ID 또는 Chart 인스턴스
  * @param options 이미지 내보내기 옵션
  * @returns Base64 인코딩된 이미지 데이터 URL
  * @since 1.5.0
  * @category util
  */
-declare function getChartAsBase64(chartId: string, options?: Omit<ChartImageExportOptions, 'filename'>): string;
+declare function getChartAsBase64(target: Chart$1, options?: Omit<ChartImageExportOptions, 'filename'>): string;
+declare function getChartAsBase64(target: string, options?: Omit<ChartImageExportOptions, 'filename'>): string;
 /**
- * @description Chart 인스턴스를 Base64 문자열로 반환합니다.
+ * Chart 인스턴스를 Base64 문자열로 반환합니다.
  * @param chart Chart 인스턴스
  * @param options 이미지 내보내기 옵션
  * @returns Base64 인코딩된 이미지 데이터 URL
@@ -3221,16 +3395,17 @@ declare function getChartAsBase64(chartId: string, options?: Omit<ChartImageExpo
  */
 declare function getChartAsBase64ByInstance(chart: Chart$1, options?: Omit<ChartImageExportOptions, 'filename'>): string;
 /**
- * @description 차트를 Blob 객체로 반환합니다.
- * @param chartId 차트 ID
+ * 차트를 Blob 객체로 반환합니다.
+ * @param target 차트 ID 또는 Chart 인스턴스
  * @param options 이미지 내보내기 옵션
  * @returns Promise<Blob> 이미지 Blob
  * @since 1.5.0
  * @category util
  */
-declare function getChartAsBlob(chartId: string, options?: Omit<ChartImageExportOptions, 'filename'>): Promise<Blob>;
+declare function getChartAsBlob(target: Chart$1, options?: Omit<ChartImageExportOptions, 'filename'>): Promise<Blob>;
+declare function getChartAsBlob(target: string, options?: Omit<ChartImageExportOptions, 'filename'>): Promise<Blob>;
 /**
- * @description Chart 인스턴스를 Blob 객체로 반환합니다.
+ * Chart 인스턴스를 Blob 객체로 반환합니다.
  * @param chart Chart 인스턴스
  * @param options 이미지 내보내기 옵션
  * @returns Promise<Blob> 이미지 Blob
@@ -3272,5 +3447,5 @@ declare const T$: {
     };
 };
 
-export { ArcChart, ArcChart as ArcChartWrapper, BarChart, BarChart as BarChartWrapper, BubbleChart, BubbleChart as BubbleChartWrapper, CartesianChart, CartesianChart as CartesianChartWrapper, Chart, ChartFactory, ChartInstance, ChartToolBox, ChartTypes, Chart as ChartWrapper, CreateZoomRangeSlider, DefaultArcRadius, DefaultDataLabelsOptions, DefaultHiddenLegendTopOptions, DefaultHiddenSparkScales, DefaultResponsiveChartOptions, DefaultSparkPluginOptions, DefaultTimeScaleOptions, DefaultTopLegendOptions, DefaultZoomOptions, DoughnutChart, DoughnutChart as DoughnutChartWrapper, LineChart, LineChart as LineChartWrapper, PieChart, PieChart as PieChartWrapper, T$, TreemapChart, TreemapChart as TreemapChartWrapper, barScaleImgPlugin, blinkPlugin, changeSetting, chartMountPlugin, createAssignedTasksPlugin, createDefaultBarOptions, createDefaultBubbleOptions, createDefaultCartesianScales, createDefaultDoughnutOptions, createDefaultLineOptions, createDefaultPieOptions, createDefaultTreemapOptions, createStatusPlugin, createTodayLinePlugin, createWeekendPlugin, customDatasetPlugins, customLegend, T$ as default, defaultBarScales, defaultBarTooltipCallback, defaultBubbleScales, defaultBubbleTooltipCallback, defaultDoughnutTooltipCallback, defaultLineScales, defaultLineTooltipCallback, defaultPieTooltipCallback, defaultTreemapTooltipCallback, doughnutCenterTextPlugin, downloadChartAsImage, downloadChartAsImageByInstance, getChartAsBase64, getChartAsBase64ByInstance, getChartAsBlob, getChartAsBlobByInstance, loadingPlugin, makeCenterHtml, noDataPlugin, segmentImagePlugin, setChartConfig, sparkBarOptions, sparkBubbleOptions, sparkLineOptions, zoomRangeSlider, zoomResetPlugin };
-export type { Align, AllChartTypes, ArcChartBuilder, ArcChartType, ArcDataset, AxisColors, BarChartBuilder, BubbleChartBuilder, CartesianChartBuilder, CartesianChartType, CartesianDataset, ChartBuilder, ChartImageExportOptions, ChartWithFocus, Color, CommonAxes, CommonAxesSacels, CommonCartesian, CommonCartesianAxes, CommonCartesianLegendConfig, CommonCartesianTicks, CommonCartesianTitleConfig, CommonTicks, Constructor, CustomArcChartOptions, CustomBarChartOptions, CustomBubbleChartOptions, CustomCartesianDataset, CustomChartDatasets, CustomChartOptions, CustomDoughnutChartOptions, CustomLineChartOptions, CustomOptionPlugins, CustomPieChartOptions, CustomTreemapChartOptions, CustomTreemapDataset, CustomZoomType, DataLabels, DataLabelsContext, DatasetWithPrevColors, DeepPartial, DeepPartialCartesianAxes, DeepPartialPluginOptions, DeepPartialZoomType, DoughnutChartBuilder, FocusCallback, HierarchicalChartType, HtmlLegendOptions, LineChartBuilder, Mode, OriginalColors, Override, PartialDataLabels, PieChartBuilder, Position, RadarChartBuilder, RadialChartType, ScaleWithOriginalColors, SegmentImageConfig, SettingOptions, StzConfig, TimeScaleConfig, TimeScaleType, TimeUnit, TreemapChartBuilder, UidImageMapping, ZoomRangeSliderColors, ZoomRangeSliderPlugin, ZoomRangeSliderVar };
+export { ArcChart, ArcChart as ArcChartWrapper, BarChart, BarChart as BarChartWrapper, BubbleChart, BubbleChart as BubbleChartWrapper, CartesianChart, CartesianChart as CartesianChartWrapper, Chart, ChartFactory, ChartInstance, ChartToolBox, ChartTypes, Chart as ChartWrapper, CreateZoomRangeSlider, DefaultArcRadius, DefaultDataLabelsOptions, DefaultHiddenLegendTopOptions, DefaultHiddenSparkScales, DefaultResponsiveChartOptions, DefaultSparkPluginOptions, DefaultTimeScaleOptions, DefaultTopLegendOptions, DefaultZoomOptions, DoughnutChart, DoughnutChart as DoughnutChartWrapper, LineChart, LineChart as LineChartWrapper, PieChart, PieChart as PieChartWrapper, T$, TreemapChart, TreemapChart as TreemapChartWrapper, barScaleImgPlugin, blinkPlugin, changeSetting, chartMountPlugin, clearChartActiveElements, createAssignedTasksPlugin, createDefaultBarOptions, createDefaultBubbleOptions, createDefaultCartesianScales, createDefaultDoughnutOptions, createDefaultLineOptions, createDefaultPieOptions, createDefaultTreemapOptions, createStatusPlugin, createTodayLinePlugin, createWeekendPlugin, customDatasetPlugins, customLegend, T$ as default, defaultBarScales, defaultBarTooltipCallback, defaultBubbleScales, defaultBubbleTooltipCallback, defaultDoughnutTooltipCallback, defaultLineScales, defaultLineTooltipCallback, defaultPieTooltipCallback, defaultTreemapTooltipCallback, doughnutCenterTextPlugin, downloadChartAsImage, downloadChartAsImageByInstance, getChartAsBase64, getChartAsBase64ByInstance, getChartAsBlob, getChartAsBlobByInstance, getChartDatasetMeta, getChartInstance, hideChartTooltip, isChartDatasetVisible, loadingPlugin, makeCenterHtml, noDataPlugin, resetChartZoom, resizeChart, segmentImagePlugin, setChartActiveElements, setChartConfig, setChartDatasetVisibility, showChartTooltip, sparkBarOptions, sparkBubbleOptions, sparkLineOptions, toggleChartDatasetVisibility, updateChart, zoomRangeSlider, zoomResetPlugin };
+export type { Align, AllChartTypes, ArcChartBuilder, ArcChartType, ArcDataset, AxisColors, BarChartBuilder, BubbleChartBuilder, CartesianChartBuilder, CartesianChartType, CartesianDataset, ChartBuilder, ChartImageExportOptions, ChartTarget, ChartWithFocus, Color, CommonAxes, CommonAxesSacels, CommonCartesian, CommonCartesianAxes, CommonCartesianLegendConfig, CommonCartesianTicks, CommonCartesianTitleConfig, CommonTicks, Constructor, CustomArcChartOptions, CustomBarChartOptions, CustomBubbleChartOptions, CustomCartesianDataset, CustomChartDatasets, CustomChartOptions, CustomDoughnutChartOptions, CustomLineChartOptions, CustomOptionPlugins, CustomPieChartOptions, CustomTreemapChartOptions, CustomTreemapDataset, CustomZoomType, DataLabels, DataLabelsContext, DatasetWithPrevColors, DeepPartial, DeepPartialCartesianAxes, DeepPartialPluginOptions, DeepPartialZoomType, DoughnutChartBuilder, FocusCallback, HierarchicalChartType, HtmlLegendOptions, LineChartBuilder, Mode, OriginalColors, Override, PartialDataLabels, PieChartBuilder, Position, RadarChartBuilder, RadialChartType, ScaleWithOriginalColors, SegmentImageConfig, SettingOptions, StzConfig, TimeScaleConfig, TimeScaleType, TimeUnit, TreemapChartBuilder, UidImageMapping, ZoomRangeSliderColors, ZoomRangeSliderPlugin, ZoomRangeSliderVar };