stz-chart-maker 2.3.7 → 2.3.8

package/README.md

@@ -96,6 +96,7 @@ module.exports = {
 | `defaultColor` | `string[]` | 내부 기본 팔레트 | 차트 전역 기본 색상 배열 |
 | `zoom` | `boolean \| object` | `false` | `line`, `bar`, `bubble` 차트에 전역 zoom 기본값 적용 |
 | `loading` | `boolean` | `false` | Cartesian 차트에 전역 loading 기본값 적용 |
+| `spinnerOverlay` | `boolean \| object` | `false` | `_chartId` 기반 `mountChart(...)` 사용 시 DOM spinner overlay 기본값 적용 |
 | `legend` | `object` | 차트 기본값 사용 | 차트 전역 legend 기본 옵션 적용 |
 | `tooltip` | `object` | 차트 기본값 사용 | 차트 전역 tooltip 기본 옵션 적용 |
 

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { ChartTypeRegistry, ChartType, ChartDataset, GridLineOptions, FontSpec, Tick, PluginOptionsByType, Chart as Chart$1, ChartOptions, ChartEvent, ActiveElement, LegendOptions, TooltipOptions, Plugin as Plugin$1, TooltipItem } from 'chart.js';
+import { ChartTypeRegistry, ChartType, ChartDataset, GridLineOptions, FontSpec, Tick, Chart as Chart$1, ChartOptions, PluginOptionsByType, ChartEvent, ActiveElement, LegendOptions, TooltipOptions, Plugin as Plugin$1, TooltipItem } from 'chart.js';
 import { TreemapControllerDatasetOptions } from 'chartjs-chart-treemap';
-import { ZoomPluginOptions } from 'chartjs-plugin-zoom/types/options';
+import { ZoomOptions, PanOptions, LimitOptions, ScaleLimits } from 'chartjs-plugin-zoom/types/options';
 
 /**
  * ═════════════════════════════════════════════════════════════
@@ -246,23 +246,63 @@ interface CommonAxesSacels {
  * ═════════════════════════════════════════════════════════════
  */
 
-interface PanOptions {
-    enabled: boolean;
-    mode?: 'x' | 'y' | 'xy';
-    modifierKey?: 'ctrl' | 'alt' | 'shift' | 'meta' | null;
-    scaleMode?: 'x' | 'y' | 'xy' | undefined;
-    overScaleMode?: 'x' | 'y' | 'xy' | undefined;
-    threshold?: number;
-}
-interface ZoomLimit {
-    min?: number;
-    max?: number;
-}
-type ZoomLimits = Record<string, ZoomLimit>;
-interface CustomZoomType<TType extends ChartType = ChartType> extends PluginOptionsByType<TType> {
-    zoom: ZoomPluginOptions;
+type AutoZoomLimitMode = 'original' | 'data';
+/**
+ * 자동 zoom limit 계산 모드입니다.
+ *
+ * - `original`: 초기 렌더 시점의 차트 범위를 사용합니다.
+ * - `data`: 현재 데이터 값에서 min/max를 계산합니다.
+ *
+ * @group Zoom
+ */
+type AutoZoomLimits = AutoZoomLimitMode | Partial<Record<string, AutoZoomLimitMode | false>>;
+type ZoomScaleLimits = ScaleLimits;
+type ZoomLimitOptions = LimitOptions;
+/**
+ * `setZoom()` / `addZoom()`에서 사용하는 `chartjs-plugin-zoom` 호환 옵션입니다.
+ *
+ * `limits`는 하위 plugin으로 그대로 전달됩니다.
+ * `autoLimits`는 `stz-chart-maker`가 제공하는 편의 옵션이며, 마운트 전에 `limits`로 변환됩니다.
+ *
+ * @example
+ * ```ts
+ * chart.setZoom(true, {
+ *   limits: {
+ *     x: { min: 'original', max: 'original' },
+ *     y: { min: 0, max: 100 },
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * chart.setZoom(true, {
+ *   autoLimits: 'original',
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * chart.setZoom(true, {
+ *   autoLimits: { x: 'original', y1: 'data' },
+ * });
+ * ```
+ *
+ * @group Zoom
+ */
+interface CustomZoomType {
+    zoom?: ZoomOptions;
     pan?: PanOptions;
-    zoomLimits?: ZoomLimits;
+    limits?: ZoomLimitOptions;
+    /**
+     * @deprecated `limits`를 사용하세요.
+     */
+    zoomLimits?: ZoomLimitOptions;
+    /**
+     * `original`은 초기 렌더 범위를, `data`는 현재 데이터 범위를 기준으로 zoom 한계를 자동 설정합니다.
+     * 문자열을 주면 `x`, `y` 축 모두에 적용되고, 객체를 주면 축/scale id별로 개별 설정할 수 있습니다.
+     */
+    autoLimits?: AutoZoomLimits;
 }
 type DeepPartialZoomType = DeepPartial<CustomZoomType>;
 
@@ -337,6 +377,109 @@ interface StreamingOptions {
     onRefresh?: (chart: Chart$1) => void;
 }
 
+/**
+ * `spinnerOverlay`에서 사용하는 인라인 스타일 맵입니다.
+ * 키는 CSS 속성명이며 값은 `HTMLElement.style.setProperty(...)`로 적용됩니다.
+ *
+ * @group Spinner Overlay
+ */
+type SpinnerOverlayStyle = Record<string, string | number>;
+/**
+ * 사용자 정의 spinner 렌더러에 전달되는 컨텍스트 객체입니다.
+ *
+ * @group Spinner Overlay
+ */
+interface SpinnerOverlayRenderContext {
+    /** `build(id)` 또는 `_chartId`로 지정된 안정적인 차트 id입니다. */
+    chartId: string;
+}
+/**
+ * DOM 오버레이에 사용할 사용자 정의 spinner 콘텐츠입니다.
+ *
+ * - `string`: `innerHTML`로 삽입됩니다.
+ * - `HTMLElement`: 마운트 전에 복제되어 사용됩니다.
+ * - `function`: 현재 차트 id를 받아 마운트 시점에 호출됩니다.
+ *
+ * @group Spinner Overlay
+ */
+type SpinnerOverlaySpinnerContent = string | HTMLElement | ((context: SpinnerOverlayRenderContext) => string | HTMLElement);
+/**
+ * {@link mountChart} 와 `setChartConfig({ spinnerOverlay: ... })` 에서 사용하는 DOM 오버레이 설정입니다.
+ *
+ * 이 기능은 Chart.js canvas plugin이 아닙니다.
+ * `new Chart(...)`가 실행되기 전에 차트 래퍼 DOM 위에 overlay를 만들고,
+ * 첫 번째 paint가 끝나면 overlay를 제거합니다.
+ *
+ * @example
+ * ```ts
+ * const config = ChartWrapper
+ *   .create('bar', labels, datasets)
+ *   .setSpinnerOverlay({
+ *     enabled: true,
+ *     text: '차트 준비 중...',
+ *     minVisibleMs: 200,
+ *     overlayStyle: {
+ *       background: 'rgba(255,255,255,0.94)'
+ *     },
+ *   })
+ *   .build('sales-chart');
+ * ```
+ *
+ * @example
+ * ```ts
+ * setChartConfig({
+ *   spinnerOverlay: {
+ *     enabled: true,
+ *     text: '로딩 중...',
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * chart.setSpinnerOverlay({
+ *   enabled: true,
+ *   text: '라인 경로 계산 중',
+ *   spinner: () => {
+ *     const spinner = document.createElement('div');
+ *     spinner.innerHTML = '<svg width="42" height="42" viewBox="0 0 42 42"><circle cx="21" cy="21" r="18" fill="none" stroke="#bfdbfe" stroke-width="4" /><path d="M21 3 A18 18 0 0 1 39 21" fill="none" stroke="#2563eb" stroke-width="4" stroke-linecap="round" /></svg>';
+ *     return spinner;
+ *   }
+ * });
+ * ```
+ *
+ * @group Spinner Overlay
+ */
+interface SpinnerOverlayConfig {
+    enabled?: boolean;
+    text?: string | false;
+    delayMs?: number;
+    minVisibleMs?: number;
+    backgroundColor?: string;
+    textColor?: string;
+    spinnerColor?: string;
+    spinnerTrackColor?: string;
+    zIndex?: number;
+    target?: 'parent' | 'canvas-parent';
+    className?: string;
+    textClassName?: string;
+    spinnerClassName?: string;
+    overlayStyle?: SpinnerOverlayStyle;
+    textStyle?: SpinnerOverlayStyle;
+    spinnerStyle?: SpinnerOverlayStyle;
+    spinner?: SpinnerOverlaySpinnerContent;
+}
+/**
+ * spinner overlay를 간단히 켜고 끄기 위한 편의 유니온 타입입니다.
+ *
+ * - `true`: 기본값으로 활성화
+ * - `false`: 비활성화
+ * - `SpinnerOverlayConfig`: 명시적인 DOM 오버레이 설정
+ *
+ * @group Spinner Overlay
+ */
+type SpinnerOverlayOption = boolean | SpinnerOverlayConfig;
+
 /**
  * ═════════════════════════════════════════════════════════════
  * 📄 FILE     : options.ts
@@ -449,6 +592,11 @@ type CustomChartOptions<TType extends ChartType = ChartType> = Override<ChartOpt
     _chartId?: string;
     _loading?: boolean;
     _noDataText?: string;
+    /**
+     * DOM 기반 spinner overlay 설정입니다.
+     * 이 옵션은 내장 canvas loading plugin이 아니라 {@link mountChart} 에서 소비됩니다.
+     */
+    spinnerOverlay?: SpinnerOverlayOption;
 };
 type CustomArcChartOptions<TType extends ArcChartType = ArcChartType> = CustomChartOptions<TType> & {
     scales?: never;
@@ -496,6 +644,7 @@ interface ChartBuilder<TType extends ChartType> {
     setTitle(titleOptions: CommonCartesianTitleConfig): this;
     setLegend(legendOptions: DeepPartial<LegendOptions<any>>): this;
     setTooltip(tooltipOptions: DeepPartial<TooltipOptions<any>>): this;
+    setSpinnerOverlay(spinnerOverlay: SpinnerOverlayOption): this;
     mergeOptions(options: DeepPartial<CustomChartOptions<TType>>): this;
     getChartData(uid: string): CustomChartDatasets<TType>;
     setChartData(uid: string, data: CustomChartDatasets<TType>): void;
@@ -518,7 +667,7 @@ interface CartesianChartBuilder<TType extends CartesianChartType> extends ChartB
         lineWidth?: number;
     }): this;
     setZoom(enabled: boolean, zoomOption?: DeepPartialZoomType): this;
-    addZoom(defaultZoom?: boolean, zoomOption?: object): this;
+    addZoom(defaultZoom?: boolean, zoomOption?: DeepPartialZoomType): this;
     addDataLabels(defultDataLabels?: boolean, dataLabelsOptions?: PartialDataLabels): this;
     setYAxisForDataset(datasetIndex: number, axisId?: string): this;
     setAxisRange(axis: 'x' | 'y', min?: number, max?: number): this;
@@ -692,13 +841,18 @@ type Types_RadarChartBuilder = RadarChartBuilder;
 type Types_RadialChartType = RadialChartType;
 type Types_SegmentImageConfig = SegmentImageConfig;
 type Types_SettingOptions = SettingOptions;
+type Types_SpinnerOverlayConfig = SpinnerOverlayConfig;
+type Types_SpinnerOverlayOption = SpinnerOverlayOption;
+type Types_SpinnerOverlayRenderContext = SpinnerOverlayRenderContext;
+type Types_SpinnerOverlaySpinnerContent = SpinnerOverlaySpinnerContent;
+type Types_SpinnerOverlayStyle = SpinnerOverlayStyle;
 type Types_TimeScaleConfig = TimeScaleConfig;
 type Types_TimeScaleType = TimeScaleType;
 type Types_TimeUnit = TimeUnit;
 type Types_TreemapChartBuilder = TreemapChartBuilder;
 type Types_UidImageMapping = UidImageMapping;
 declare namespace Types {
-  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_CustomChartDatasets as CustomChartDatasets, Types_CustomChartOptions as CustomChartOptions, Types_CustomDoughnutChartOptions as CustomDoughnutChartOptions, Types_CustomLineChartOptions as CustomLineChartOptions, Types_CustomOptionPlugins as CustomOptionPlugins, Types_CustomPieChartOptions as CustomPieChartOptions, Types_CustomTreemapChartOptions as CustomTreemapChartOptions, Types_CustomTreemapDataset as CustomTreemapDataset, Types_DeepPartial as DeepPartial, Types_DeepPartialCartesianAxes as DeepPartialCartesianAxes, Types_DeepPartialPluginOptions as DeepPartialPluginOptions, Types_DoughnutChartBuilder as DoughnutChartBuilder, Types_HierarchicalChartType as HierarchicalChartType, Types_HtmlLegendOptions as HtmlLegendOptions, Types_LineChartBuilder as LineChartBuilder, Types_Mode as Mode, Types_Override as Override, Types_PieChartBuilder as PieChartBuilder, Types_Position as Position, Types_RadarChartBuilder as RadarChartBuilder, Types_RadialChartType as RadialChartType, Types_SegmentImageConfig as SegmentImageConfig, Types_SettingOptions as SettingOptions, Types_TimeScaleConfig as TimeScaleConfig, Types_TimeScaleType as TimeScaleType, Types_TimeUnit as TimeUnit, Types_TreemapChartBuilder as TreemapChartBuilder, Types_UidImageMapping as UidImageMapping };
+  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_CustomChartDatasets as CustomChartDatasets, Types_CustomChartOptions as CustomChartOptions, Types_CustomDoughnutChartOptions as CustomDoughnutChartOptions, Types_CustomLineChartOptions as CustomLineChartOptions, Types_CustomOptionPlugins as CustomOptionPlugins, Types_CustomPieChartOptions as CustomPieChartOptions, Types_CustomTreemapChartOptions as CustomTreemapChartOptions, Types_CustomTreemapDataset as CustomTreemapDataset, Types_DeepPartial as DeepPartial, Types_DeepPartialCartesianAxes as DeepPartialCartesianAxes, Types_DeepPartialPluginOptions as DeepPartialPluginOptions, Types_DoughnutChartBuilder as DoughnutChartBuilder, Types_HierarchicalChartType as HierarchicalChartType, Types_HtmlLegendOptions as HtmlLegendOptions, Types_LineChartBuilder as LineChartBuilder, Types_Mode as Mode, Types_Override as Override, Types_PieChartBuilder as PieChartBuilder, Types_Position as Position, Types_RadarChartBuilder as RadarChartBuilder, Types_RadialChartType as RadialChartType, Types_SegmentImageConfig as SegmentImageConfig, Types_SettingOptions as SettingOptions, Types_SpinnerOverlayConfig as SpinnerOverlayConfig, Types_SpinnerOverlayOption as SpinnerOverlayOption, Types_SpinnerOverlayRenderContext as SpinnerOverlayRenderContext, Types_SpinnerOverlaySpinnerContent as SpinnerOverlaySpinnerContent, Types_SpinnerOverlayStyle as SpinnerOverlayStyle, Types_TimeScaleConfig as TimeScaleConfig, Types_TimeScaleType as TimeScaleType, Types_TimeUnit as TimeUnit, Types_TreemapChartBuilder as TreemapChartBuilder, Types_UidImageMapping as UidImageMapping };
 }
 
 interface ChartConfig {
@@ -836,6 +990,34 @@ declare abstract class Chart<TType extends ChartType, TOptions extends CustomCha
      * });
      */
     setTooltip(tooltipOptions: DeepPartial<TooltipOptions<TType>>): this;
+    /**
+     * @description 차트 마운트 직전 DOM 오버레이 spinner를 설정합니다.
+     * 실제 동작은 {@link mountChart} helper가 담당하며, `build(id)` 또는 `_chartId`로 안정적인 canvas id가 필요합니다.
+     * @param spinnerOverlay
+     * @returns {this}
+     * @since 2.4.0
+     * @example
+     * chart.setSpinnerOverlay(true);
+     *
+     * @example
+     * chart.setSpinnerOverlay({
+     *   enabled: true,
+     *   text: '차트 준비 중...',
+     *   minVisibleMs: 200,
+     * });
+     *
+     * @example
+     * chart.setSpinnerOverlay({
+     *   enabled: true,
+     *   text: false,
+     *   spinner: () => {
+     *     const spinner = document.createElement('div');
+     *     spinner.innerHTML = '<svg width="42" height="42" viewBox="0 0 42 42"><circle cx="21" cy="21" r="18" fill="none" stroke="#bfdbfe" stroke-width="4" /><path d="M21 3 A18 18 0 0 1 39 21" fill="none" stroke="#2563eb" stroke-width="4" stroke-linecap="round" /></svg>';
+     *     return spinner;
+     *   }
+     * });
+     */
+    setSpinnerOverlay(spinnerOverlay: SpinnerOverlayOption): this;
     /**
      * @description 기존 옵션에 부분 옵션을 병합합니다.
      * @param {DeepPartial<TOptions>} options
@@ -1035,6 +1217,7 @@ declare abstract class CartesianChart<TType extends CartesianChartType> extends
     protected decorateDataset(ds: any, idx: number): void;
     protected mustHavePlugins(): ({
         id: string;
+        beforeInit(chart: any): void;
         afterDraw(chart: any, args: any, options: any): void;
         afterDestroy(chart: any): void;
     } | {
@@ -1058,6 +1241,16 @@ declare abstract class CartesianChart<TType extends CartesianChartType> extends
     protected applyGlobalZoomConfig(): void;
     protected ensureZoomResetPlugin(): void;
     protected removeZoomResetPlugin(): void;
+    protected normalizeZoomOptions(zoomOption?: DeepPartialZoomType): DeepPartialZoomType;
+    protected resolveAutoZoomLimits(autoLimits: AutoZoomLimits): ZoomLimitOptions;
+    protected resolveAxisZoomLimits(axisId: string): ZoomScaleLimits | undefined;
+    protected resolveZoomAxis(axisId: string): 'x' | 'y' | undefined;
+    protected resolveAxisLabelLimitValues(axisId: string, datasets: CustomCartesianDataset<TType>[]): number[];
+    protected extractParsedPointValue(point: unknown, dataset: CustomCartesianDataset<TType>, axis: 'x' | 'y'): number | undefined;
+    protected resolveParsingKey(dataset: CustomCartesianDataset<TType>, axis: 'x' | 'y'): string;
+    protected readValueByPath(source: Record<string, unknown>, path: string): unknown;
+    protected normalizeLimitValue(value: unknown): number | undefined;
+    protected toZoomScaleLimits(values: number[]): ZoomScaleLimits | undefined;
     protected normalize(): void;
     protected configAop(config: any): any;
     /**
@@ -1185,9 +1378,26 @@ declare abstract class CartesianChart<TType extends CartesianChartType> extends
      * @description 줌 기능을 설정합니다. `false`를 전달하면 현재 차트의 줌 설정을 제거합니다.
      * 전역 `setChartConfig({ zoom: true })` 설정이 있더라도 이 메서드로 차트별 비활성화가 가능합니다.
      * @param {boolean} enabled
-     * @param {CustomZoomType<TType>} zoomOption
+     * @param {DeepPartialZoomType} zoomOption
      * @returns {this}
      * @since 2.4.0
+     * @example
+     * chart.setZoom(true, {
+     *   limits: {
+     *     x: { min: 'original', max: 'original' },
+     *     y: { min: 0, max: 100 },
+     *   },
+     * });
+     *
+     * @example
+     * chart.setZoom(true, {
+     *   autoLimits: 'original',
+     * });
+     *
+     * @example
+     * chart.setZoom(true, {
+     *   autoLimits: { x: 'original', y1: 'data' },
+     * });
      */
     setZoom(enabled: boolean, zoomOption?: DeepPartialZoomType): this;
     /**
@@ -1943,6 +2153,7 @@ declare abstract class ArcChart<TType extends ArcChartType> extends Chart<TType>
     protected decorateDataset(ds: any, idx: number): void;
     protected mustHavePlugins(): {
         id: string;
+        beforeInit(chart: any): void;
         afterDraw(chart: any, args: any, options: any): void;
         afterDestroy(chart: any): void;
     }[];
@@ -2350,6 +2561,7 @@ declare class TreemapChart extends Chart<'treemap', CustomTreemapChartOptions> i
     protected normalize(): void;
     protected mustHavePlugins(): {
         id: string;
+        beforeInit(chart: any): void;
         afterDraw(chart: any, args: any, options: any): void;
         afterDestroy(chart: any): void;
     }[];
@@ -2527,14 +2739,15 @@ declare const zoomResetPlugin: {
     afterEvent(chart: any, args: any): void;
 };
 /**
- * @description 차트 초기 로드 시 원형 프로그레스 애니메이션을 표시하는 플러그인입니다.
+ * @description 차트 첫 렌더 직전까지 placeholder 로딩 화면을 표시하는 플러그인입니다.
  * @group Common Plugins
  */
 declare const loadingPlugin: {
     id: string;
-    beforeInit(chart: any, args: any, options: any): void;
-    beforeDraw(chart: any): void;
-    startLoadingAnimation(chart: any): void;
+    beforeInit(chart: any): void;
+    beforeDraw(chart: any): false | undefined;
+    drawLoadingPlaceholder(chart: any): void;
+    afterDestroy(chart: any): void;
 };
 /**
  * @description 외부 HTML 컨테이너에 커스텀 범례를 렌더링하는 플러그인입니다.
@@ -2585,6 +2798,7 @@ declare const customLegend: {
  */
 declare const chartMountPlugin: {
     id: string;
+    beforeInit(chart: any): void;
     afterDraw(chart: any, args: any, options: any): void;
     afterDestroy(chart: any): void;
 };
@@ -3072,6 +3286,11 @@ interface StzConfig {
     defaultColor?: string[];
     zoom?: boolean | DeepPartialZoomType;
     loading?: boolean;
+    /**
+     * {@link mountChart} 에서 사용하는 DOM 기반 spinner overlay의 전역 기본값입니다.
+     * 차트별 `spinnerOverlay` 옵션이 있으면 그 값이 우선합니다.
+     */
+    spinnerOverlay?: SpinnerOverlayOption;
     legend?: DeepPartial<LegendOptions<any>>;
     tooltip?: DeepPartial<TooltipOptions<any>>;
     /** @deprecated no-op. Built-in chart types are bootstrapped at package load time. */
@@ -3116,6 +3335,57 @@ interface StzConfig {
  */
 declare function setChartConfig(config: StzConfig): void;
 
+/**
+ * {@link mountChart} 가 반환하는 마운트 결과입니다.
+ *
+ * @group Spinner Overlay
+ */
+interface MountChartHandle {
+    /** `config._chartId` 또는 `config.options._chartId` 에서 해석된 안정적인 차트 id입니다. */
+    chartId: string;
+    /** 마운트된 차트를 제거하고 활성 overlay도 함께 정리합니다. */
+    destroy: () => void;
+    /** 차트 인스턴스 생성과 spinner overlay lifecycle이 모두 끝나면 resolve 됩니다. */
+    ready: Promise<Chart$1>;
+}
+/**
+ * `_chartId`를 기준으로 대상 canvas를 찾아 차트 설정을 마운트합니다.
+ *
+ * 차트 옵션이나 전역 설정에서 `spinnerOverlay`가 활성화되어 있으면,
+ * 이 helper는 먼저 DOM overlay를 만들고 브라우저 paint를 한 번 양보한 뒤 Chart.js 인스턴스를 생성합니다.
+ * 첫 렌더가 안정화되면 overlay를 제거합니다.
+ *
+ * 즉 `spinnerOverlay`의 실제 런타임은 이 helper이며, `build()`만으로는 설정 객체만 만들어집니다.
+ *
+ * @param config `build(id)`로 생성한 차트 설정 객체
+ * @returns `ready`, `destroy`를 포함한 마운트 핸들
+ *
+ * @example
+ * ```ts
+ * const config = ChartWrapper
+ *   .create('bar', labels, datasets)
+ *   .setSpinnerOverlay({
+ *     enabled: true,
+ *     text: '차트 준비 중...',
+ *   })
+ *   .build('sales-chart');
+ *
+ * const mounted = mountChart(config);
+ * await mounted.ready;
+ * ```
+ *
+ * @example
+ * ```tsx
+ * useEffect(() => {
+ *   const mounted = mountChart(config);
+ *   return () => mounted.destroy();
+ * }, [config]);
+ * ```
+ *
+ * @group Spinner Overlay
+ */
+declare function mountChart(config: ChartConfig): MountChartHandle;
+
 interface ChartImageExportOptions {
     format?: 'png' | 'jpeg' | 'webp';
     quality?: number;
@@ -3360,5 +3630,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, 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 };
+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, mountChart, noDataPlugin, resetChartZoom, resizeChart, segmentImagePlugin, setChartActiveElements, setChartConfig, setChartDatasetVisibility, showChartTooltip, sparkBarOptions, sparkBubbleOptions, sparkLineOptions, toggleChartDatasetVisibility, updateChart, zoomRangeSlider, zoomResetPlugin };
+export type { Align, AllChartTypes, ArcChartBuilder, ArcChartType, ArcDataset, AutoZoomLimitMode, AutoZoomLimits, 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, MountChartHandle, OriginalColors, Override, PartialDataLabels, PieChartBuilder, Position, RadarChartBuilder, RadialChartType, ScaleWithOriginalColors, SegmentImageConfig, SettingOptions, SpinnerOverlayConfig, SpinnerOverlayOption, SpinnerOverlayRenderContext, SpinnerOverlaySpinnerContent, SpinnerOverlayStyle, StzConfig, TimeScaleConfig, TimeScaleType, TimeUnit, TreemapChartBuilder, UidImageMapping, ZoomLimitOptions, ZoomRangeSliderColors, ZoomRangeSliderPlugin, ZoomRangeSliderVar, ZoomScaleLimits };