stz-chart-maker 2.3.6 → 2.3.8

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 {
@@ -752,7 +906,6 @@ declare abstract class Chart<TType extends ChartType, TOptions extends CustomCha
      * @param plugin - 단일 플러그인 또는 플러그인 배열
      * @param replaceIfExists
      * @Since 1.0.0
-     * @category plugin
      */
     setPlugin(plugin: any | any[], replaceIfExists?: boolean): this;
     /**
@@ -760,14 +913,12 @@ declare abstract class Chart<TType extends ChartType, TOptions extends CustomCha
      * @param {string} id
      * @returns {ChartConfig}
      * @Since 1.0.0
-     * @category config
      */
     makeConfig(id?: string): ChartConfig;
     /**
      * @description 플러그인을 제거합니다.
      * @param pluginId
      * @Since 1.0.0
-     * @category plugin
      *
      */
     removePlugin(pluginId: string): this;
@@ -776,7 +927,6 @@ declare abstract class Chart<TType extends ChartType, TOptions extends CustomCha
      * @param pluginId
      * @returns {boolean}
      * @Since 1.0.0
-     * @category plugin
      */
     hasPlugin(pluginId: string): boolean;
     /**
@@ -785,7 +935,6 @@ declare abstract class Chart<TType extends ChartType, TOptions extends CustomCha
      * @param callback
      * @returns {this}
      * @Since 1.0.0
-     * @category options
      */
     onResize(callback: (chart: Chart$1<TType>, size: {
         width: number;
@@ -796,7 +945,6 @@ declare abstract class Chart<TType extends ChartType, TOptions extends CustomCha
      * @param {DeepPartial<CommonCartesianTitleConfig>} titleOptions
      * @returns {this}
      * @Since 1.0.0
-     * @category options
      * @example
      * chart.setTitle({
      *   text: '차트 제목',
@@ -809,7 +957,6 @@ declare abstract class Chart<TType extends ChartType, TOptions extends CustomCha
      * @param {DeepPartial<LegendOptions<TType>>} legendOptions
      * @returns {this}
      * @Since 1.0.0
-     * @category options
      * @example
      * chart.setLegend({
      * position: 'bottom',
@@ -836,7 +983,6 @@ declare abstract class Chart<TType extends ChartType, TOptions extends CustomCha
      * @param {DeepPartial<TooltipOptions<TType>>} tooltipOptions
      * @returns {this}
      * @Since 2.4.0
-     * @category options
      * @example
      * chart.setTooltip({
      *   enabled: true,
@@ -844,12 +990,39 @@ 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
      * @returns {this}
      * @since 2.4.0
-     * @category options
      */
     mergeOptions(options: DeepPartial<TOptions>): this;
     /**
@@ -857,7 +1030,6 @@ declare abstract class Chart<TType extends ChartType, TOptions extends CustomCha
      * @param {string} uid
      * @returns {CustomChartDatasets<TType>}
      * @since 1.0.0
-     * @category dataset
      * @example
      * const dataset = chart.getChartData('dataset-uid-or-label');
      * console.log(dataset);
@@ -869,7 +1041,6 @@ declare abstract class Chart<TType extends ChartType, TOptions extends CustomCha
      * @param {string} uid
      * @param {CustomChartDatasets<TType>} newDataset
      * @since 1.0.0
-     * @category dataset
      * @example
      * chart.setChartData('dataset-uid-or-label', { label: 'New Dataset', data: [10, 20, 30] });
      * @beta
@@ -881,7 +1052,6 @@ declare abstract class Chart<TType extends ChartType, TOptions extends CustomCha
      * @param {DeepPartial<CustomChartDatasets<TType>>} style
      * @returns {this}
      * @since 2.4.0
-     * @category dataset
      */
     setDatasetStyle(uidOrIndex: string | number, style: DeepPartial<CustomChartDatasets<TType>>): this;
     /**
@@ -889,7 +1059,6 @@ declare abstract class Chart<TType extends ChartType, TOptions extends CustomCha
      * @param {DeepPartial<CustomChartDatasets<TType>>} style
      * @returns {this}
      * @since 2.4.0
-     * @category dataset
      */
     setAllDatasetStyle(style: DeepPartial<CustomChartDatasets<TType>>): this;
     /**
@@ -897,7 +1066,6 @@ declare abstract class Chart<TType extends ChartType, TOptions extends CustomCha
      * @param {string | number} uidOrIndex
      * @returns {this}
      * @since 2.4.0
-     * @category dataset
      */
     removeDataset(uidOrIndex: string | number): this;
     /**
@@ -906,7 +1074,6 @@ declare abstract class Chart<TType extends ChartType, TOptions extends CustomCha
      * @param {string | number} dataUidOrIndex
      * @returns {this}
      * @since 2.4.0
-     * @category dataset
      */
     removeData(datasetUidOrIndex: string | number, dataUidOrIndex?: string | number): this;
     /**
@@ -914,7 +1081,6 @@ declare abstract class Chart<TType extends ChartType, TOptions extends CustomCha
      * @param {string | number} datasetUidOrIndex
      * @returns {this}
      * @since 2.4.0
-     * @category dataset
      */
     clearData(datasetUidOrIndex?: string | number): this;
     /**
@@ -924,7 +1090,6 @@ declare abstract class Chart<TType extends ChartType, TOptions extends CustomCha
      * @param {boolean} syncGroup
      * @returns {this}
      * @since 2.4.0
-     * @category dataset
      */
     setDatasetVisible(uidOrIndex: string | number, visible: boolean, syncGroup?: boolean): this;
     /**
@@ -933,7 +1098,6 @@ declare abstract class Chart<TType extends ChartType, TOptions extends CustomCha
      * @param {boolean} syncGroup
      * @returns {this}
      * @since 2.4.0
-     * @category dataset
      */
     toggleDataset(uidOrIndex: string | number, syncGroup?: boolean): this;
     /**
@@ -942,7 +1106,6 @@ declare abstract class Chart<TType extends ChartType, TOptions extends CustomCha
      * @param {string | number} group
      * @returns {this}
      * @since 2.4.0
-     * @category dataset
      */
     setDatasetGroup(uidOrIndex: string | number, group: string | number): this;
     /**
@@ -951,7 +1114,6 @@ declare abstract class Chart<TType extends ChartType, TOptions extends CustomCha
      * @param {StreamingOptions} streamingOptions - `chartjs-plugin-streaming` 플러그인에 전달할 옵션 객체.
      * @returns {this}
      * @since 1.8.0
-     * @category plugin
      * @example
      * // 1. 사용자 측에서 웹소켓 등 데이터 소스 설정
      * const myWebSocket = new WebSocket('wss://my-data-source');
@@ -1051,11 +1213,11 @@ declare abstract class CartesianChart<TType extends CartesianChartType> extends
      * @param {number} idx
      * @Returns {void}
      * @Since 1.0.1
-     * @category Dataset
      */
     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;
     } | {
@@ -1079,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;
     /**
@@ -1086,7 +1258,6 @@ declare abstract class CartesianChart<TType extends CartesianChartType> extends
      * @param id
      * @returns {ChartConfig}
      * @Since 1.0.0
-     * @category Chart
      */
     build(id?: string): ChartConfig;
     /**
@@ -1106,7 +1277,6 @@ declare abstract class CartesianChart<TType extends CartesianChartType> extends
      * @private
      * @description Cartesian chart type을 체크 합니다.
      * @since 1.0.0
-     * @category Chart
      */
     private isCartesianChartType;
     /**
@@ -1114,7 +1284,6 @@ declare abstract class CartesianChart<TType extends CartesianChartType> extends
      * @param scales
      * @returns {this}
      * @since 1.0.0
-     * @category Scales
      */
     setScales(scales: CommonAxesSacels): this;
     /**
@@ -1138,7 +1307,6 @@ declare abstract class CartesianChart<TType extends CartesianChartType> extends
      * @param {TimeScaleConfig} timeScaleConfig - 시간 축 상세 설정입니다. 비워두면 기본 시간 축 설정이 적용됩니다.
      * @returns {this}
      * @since 2.3.2
-     * @category Scales
      * @example
      * // 기본 시간 축 적용
      * const chart = ChartWrapper.create('line', [], [
@@ -1188,7 +1356,6 @@ declare abstract class CartesianChart<TType extends CartesianChartType> extends
      * @param {CommonCartesianTitleConfig} titleConfig - 축 제목 설정 옵션
      * @returns {this}
      * @since 1.0.0
-     * @category Scales
      * @example
      * chart.setAxisTitle('y', { display: true, text: 'Primary Y Axis' });
      * chart.setAxisTitle('y1', { display: true, text: 'Secondary Y Axis' });
@@ -1201,7 +1368,6 @@ declare abstract class CartesianChart<TType extends CartesianChartType> extends
      * @param gridOptions
      * @returns {this}
      * @since 1.0.0
-     * @category Scales
      */
     setGridOptions(axis: 'x' | 'y', gridOptions: {
         display?: boolean;
@@ -1212,10 +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
-     * @category Plugins
+     * @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;
     /**
@@ -1225,7 +1407,6 @@ declare abstract class CartesianChart<TType extends CartesianChartType> extends
      * @param zoomOption - 사용자 정의 줌 옵션입니다.
      * @returns {this}
      * @since 1.0.0
-     * @category Plugins
      * @defaultValue defaultZoom = false
      * @example
      * // 기존 방식
@@ -1252,7 +1433,6 @@ declare abstract class CartesianChart<TType extends CartesianChartType> extends
      * @param axisId
      * @returns {this}
      * @since 1.0.0
-     * @category Scales
      * @defaultValue axisId = 'y'
      */
     setYAxisForDataset(datasetIndex: number, axisId?: string): this;
@@ -1260,7 +1440,6 @@ declare abstract class CartesianChart<TType extends CartesianChartType> extends
      * @private
      * @description y1 축을 보장합니다.
      * @since 1.0.0
-     * @category Scales
      */
     private ensureY1AxisExists;
     /**
@@ -1270,7 +1449,6 @@ declare abstract class CartesianChart<TType extends CartesianChartType> extends
      * @param max
      * @returns {this}
      * @since 1.0.0
-     * @category Scales
      */
     setAxisRange(axis: 'x' | 'y', min?: number, max?: number): this;
     /**
@@ -1280,7 +1458,6 @@ declare abstract class CartesianChart<TType extends CartesianChartType> extends
      * @returns {this}
      * @throws {CustomError} 해당 차트 타입이 yAxisID 옵션을 지원하지 않을 경우 에러를 발생시킵니다.
      * @since 1.0.0
-     * @category Scales
      */
     setYAxisID(datasetIndex: number, axisID: string): this;
     /**
@@ -1290,7 +1467,6 @@ declare abstract class CartesianChart<TType extends CartesianChartType> extends
      * @returns {this}
      * @throws {CustomError} 해당 축이 존재하지 않거나 position 옵션을 지원하지 않을 경우 에러를 발생시킵니다.
      * @since 1.0.0
-     * @category Scales
      */
     setAxisPosition(axis: string, position: 'left' | 'right'): this;
     /**
@@ -1371,7 +1547,6 @@ declare abstract class CartesianChart<TType extends CartesianChartType> extends
      * @returns {this}
      * @throws {CustomError} 옵션이 비어있거나 객체가 아닐 경우 에러를 발생시킵니다.
      * @Since 1.0.0
-     * @category Plugins
      */
     customLegend(obj: HtmlLegendOptions): this;
     /**
@@ -1381,7 +1556,6 @@ declare abstract class CartesianChart<TType extends CartesianChartType> extends
      * @returns {CustomCartesianDataset<TType> | undefined}
      * @throws {CustomError} UID가 없거나 데이터셋이 비어있을 때 에러를 발생시킵니다.
      * @Since 1.0.0
-     * @category Dataset
      */
     getDataset(uid: string): CustomCartesianDataset<TType> | undefined;
     /**
@@ -1392,7 +1566,6 @@ declare abstract class CartesianChart<TType extends CartesianChartType> extends
      * @returns {this}
      * @throws {CustomError} UID가 없거나 데이터셋이 비어있을 때 에러를 발생시킵니다.
      * @Since 1.0.0
-     * @category Dataset
      */
     setDataset(uid: string, dataset: CustomCartesianDataset<TType>): this;
     /**
@@ -1401,7 +1574,6 @@ declare abstract class CartesianChart<TType extends CartesianChartType> extends
      * @returns {CustomCartesianDataset<TType> | undefined}
      * @throws {CustomError} 데이터셋이 없거나 찾을 수 없을 때 에러를 발생시킵니다.
      * @since 1.6.6
-     * @category Dataset
      * @example
      * // UID로 조회
      * const dataset = chart.getData('dataset-uid');
@@ -1417,7 +1589,6 @@ declare abstract class CartesianChart<TType extends CartesianChartType> extends
      * @returns {this}
      * @throws {CustomError} 데이터셋이 없거나 찾을 수 없을 때 에러를 발생시킵니다.
      * @since 1.6.6
-     * @category Dataset
      * @example
      * // UID로 교체
      * chart.setData('dataset-uid', { label: 'New Dataset', data: [...] });
@@ -1433,7 +1604,6 @@ declare abstract class CartesianChart<TType extends CartesianChartType> extends
      * @returns {string}
      * @throws {CustomError} 데이터셋이 null 또는 undefined일 때 에러를 발생시킵니다.
      * @Since 1.0.0
-     * @category Dataset
      */
     addDataset(dataset: CustomCartesianDataset<TType>): string;
     /**
@@ -1442,7 +1612,6 @@ declare abstract class CartesianChart<TType extends CartesianChartType> extends
      * @param {GridLineOptions} gridOptions
      * @returns {this}
      * @Since 1.0.0
-     * @category scales
      * @example
      * chart.setGrid('y', { color: 'rgba(0, 0, 0, 0.1)', lineWidth: 1 });
      */
@@ -1452,7 +1621,6 @@ declare abstract class CartesianChart<TType extends CartesianChartType> extends
      * @param {string} color
      * @returns {this}
      * @Since 1.0.0
-     * @category options
      * @example
      * chart.setBackgroundColor('rgba(255, 255, 255, 0.5)');
      * chart.setBackgroundColor('#f0f0f0');
@@ -1465,7 +1633,6 @@ declare abstract class CartesianChart<TType extends CartesianChartType> extends
      * @returns {this}
      * @throws {CustomError} 데이터셋이 없거나 인덱스가 유효하지 않을 경우 에러를 발생시킵니다.
      * @since 1.6.6
-     * @category Dataset
      * @example
      * // 마지막 데이터셋에 단일 데이터 추가
      * chart.addData({ x: 10, y: 20 });
@@ -1505,7 +1672,6 @@ declare class BarChart extends CartesianChart<'bar'> implements BarChartBuilder
      * @param {number} thickness
      * @description 데이터셋의 Bar Thickness를 설정합니다.
      * @Since 1.0.0
-     * @category dataset
      */
     setBarThickness(datasetIndex: number, thickness: number): this;
     /**
@@ -1513,7 +1679,6 @@ declare class BarChart extends CartesianChart<'bar'> implements BarChartBuilder
      * @param {number} thickness
      * @description 모든 데이터셋의 Bar Thickness를 설정합니다.
      * @Since 1.0.0
-     * @category dataset
      */
     setAllBarThickness(thickness: number): this;
     /**
@@ -1522,7 +1687,6 @@ declare class BarChart extends CartesianChart<'bar'> implements BarChartBuilder
      * @param {number} maxThickness
      * @description 데이터셋의 Max Bar Thickness를 설정합니다.
      * @Since 1.0.0
-     * @category dataset
      */
     setMaxBarThickness(datasetIndex: number, maxThickness: number): this;
     /**
@@ -1530,7 +1694,6 @@ declare class BarChart extends CartesianChart<'bar'> implements BarChartBuilder
      * @param {number} maxThickness
      * @description 모든 데이터셋의 Max Bar Thickness를 설정합니다.
      * @Since 1.0.0
-     * @category dataset
      */
     setAllMaxBarThickness(maxThickness: number): this;
     /**
@@ -1539,7 +1702,6 @@ declare class BarChart extends CartesianChart<'bar'> implements BarChartBuilder
      * @param {number} percentage
      * @description 데이터셋의 Bar Percentage를 설정합니다.
      * @Since 1.0.0
-     * @category dataset
      */
     setBarPercentage(datasetIndex: number, percentage: number): this;
     /**
@@ -1547,7 +1709,6 @@ declare class BarChart extends CartesianChart<'bar'> implements BarChartBuilder
      * @param {number} percentage
      * @description 모든 데이터셋의 Bar Percentage를 설정합니다.
      * @Since 1.0.0
-     * @category dataset
      */
     setAllBarPercentage(percentage: number): this;
     /**
@@ -1556,7 +1717,6 @@ declare class BarChart extends CartesianChart<'bar'> implements BarChartBuilder
      * @param {number} percentage
      * @description 데이터셋의 Category Percentage를 설정합니다.
      * @Since 1.0.0
-     * @category dataset
      */
     setCategoryPercentage(datasetIndex: number, percentage: number): this;
     /**
@@ -1564,7 +1724,6 @@ declare class BarChart extends CartesianChart<'bar'> implements BarChartBuilder
      * @param {number} percentage
      * @description 모든 데이터셋의 Category Percentage를 설정합니다.
      * @Since 1.0.0
-     * @category dataset
      */
     setAllCategoryPercentage(percentage: number): this;
     /**
@@ -1573,7 +1732,6 @@ declare class BarChart extends CartesianChart<'bar'> implements BarChartBuilder
      * @param {number} borderWidth
      * @description 데이터셋의 Border Width 설정합니다.
      * @Since 1.0.0
-     * @category dataset
      */
     setBorderWidth(datasetIndex: number, borderWidth: number): this;
     /**
@@ -1581,7 +1739,6 @@ declare class BarChart extends CartesianChart<'bar'> implements BarChartBuilder
      * @param {number} borderWidth
      * @description 모든 데이터셋의 Border Width 설정합니다.
      * @Since 1.0.0
-     * @category dataset
      */
     setAllBorderWidth(borderWidth: number): this;
     /**
@@ -1590,7 +1747,6 @@ declare class BarChart extends CartesianChart<'bar'> implements BarChartBuilder
      * @param {number} borderRadius
      * @description 데이터셋의 Border Radius 를 설정합니다.
      * @Since 1.0.0
-     * @category dataset
      */
     setBorderRadius(datasetIndex: number, borderRadius: number): this;
     /**
@@ -1598,7 +1754,6 @@ declare class BarChart extends CartesianChart<'bar'> implements BarChartBuilder
      * @param {number} borderRadius
      * @description 모든 데이터셋의 Border Radius 를 설정합니다.
      * @Since 1.0.0
-     * @category dataset
      */
     setAllBorderRadius(borderRadius: number): this;
     /**
@@ -1606,7 +1761,6 @@ declare class BarChart extends CartesianChart<'bar'> implements BarChartBuilder
      * @param {boolean} isStacked
      * @description 모든 축에 대해 Stacked 옵션을 설정합니다.
      * @Since 1.0.0
-     * @category scales
      */
     setStacked(isStacked: boolean): this;
     /**
@@ -1614,7 +1768,6 @@ declare class BarChart extends CartesianChart<'bar'> implements BarChartBuilder
      * @param {string} axis
      * @description 축에 이미지를 설정합니다. 축이 이미 존재하는 경우 경고 메시지를 출력합니다.
      * @Since 1.0.0
-     * @category plugins
      * @Returns {this}
      */
     setBarImg(axis: string): this;
@@ -1622,7 +1775,6 @@ declare class BarChart extends CartesianChart<'bar'> implements BarChartBuilder
      * @description 스파크바 차트 옵션을 적용합니다. mixed 차트에서는 동작하지 않습니다.
      * @returns {this}
      * @since 1.0.0
-     * @category options
      * @beta (기능 테스트 중)
      */
     sparkBarChart(): this;
@@ -1633,7 +1785,6 @@ declare class BarChart extends CartesianChart<'bar'> implements BarChartBuilder
      * @returns {this}
      * @throws {CustomError} 데이터가 yyyy-mm-dd 포맷이 아닐 경우 INVALID_DATA_STRUCTURE 에러 발생
      * @since 1.0.0
-     * @category options
      * @example
      * // 간트차트 데이터 형식 (배열):
      * const datasets = [
@@ -1676,7 +1827,6 @@ declare class LineChart extends CartesianChart<'line'> implements LineChartBuild
      * @returns {boolean}
      * @description 라인 차트는 카테고리형 x축일 때 라벨이 필수입니다.
      * @Since 1.0.0
-     * @category config
      * @override
      */
     protected requireLabels(): boolean;
@@ -1686,7 +1836,6 @@ declare class LineChart extends CartesianChart<'line'> implements LineChartBuild
      * @returns {ChartConfiguration}
      * @description 차트 설정 객체를 생성합니다.
      * @Since 1.0.0
-     * @category config
      * @override
      * @Deprecated use build() Method
      */
@@ -1704,7 +1853,6 @@ declare class LineChart extends CartesianChart<'line'> implements LineChartBuild
      * @param {string} backgroundColor
      * @description 데이터셋의 Fill 설정을 합니다.
      * @Since 1.0.0
-     * @category dataset
      */
     setFill(datasetIndex: number, enable: boolean, backgroundColor?: string): this;
     /**
@@ -1713,7 +1861,6 @@ declare class LineChart extends CartesianChart<'line'> implements LineChartBuild
      * @param {string} backgroundColor
      * @description 모든 데이터셋의 Fill 설정을 합니다.
      * @Since 1.0.0
-     * @category dataset
      *
      */
     setAllFill(enable: boolean, backgroundColor?: string): this;
@@ -1723,7 +1870,6 @@ declare class LineChart extends CartesianChart<'line'> implements LineChartBuild
      * @param {number} tension
      * @description 라인 차트의 곡률을 설정합니다.
      * @Since 1.0.0
-     * @category dataset
      */
     setTension(datasetIndex: number, tension: number): this;
     /**
@@ -1731,7 +1877,6 @@ declare class LineChart extends CartesianChart<'line'> implements LineChartBuild
      * @param {number} tension
      * @description 모든 데이터셋의 곡률을 설정합니다.
      * @Since 1.0.0
-     * @category dataset
      *
      */
     setAllTension(tension: number): this;
@@ -1741,7 +1886,6 @@ declare class LineChart extends CartesianChart<'line'> implements LineChartBuild
      * @param {number} borderWidth
      * @description 데이터셋의 Border Width를 설정합니다.
      * @Since 1.0.0
-     * @category dataset
      */
     setBorderWidth(datasetIndex: number, borderWidth: number): this;
     setAllBorderWidth(borderWidth: number): this;
@@ -1757,7 +1901,6 @@ declare class LineChart extends CartesianChart<'line'> implements LineChartBuild
      * @param {number} radius
      * @description 모든 라인 차트의 Point Radius를 설정합니다.
      * @Since 1.0.0
-     * @category dataset
      */
     setAllPointRadius(radius: number): this;
     /**
@@ -1766,7 +1909,6 @@ declare class LineChart extends CartesianChart<'line'> implements LineChartBuild
      * @param {number} hoverRadius
      * @description 데이터셋의 Point Hover Radius를 설정합니다.
      * @Since 1.0.0
-     * @category dataset
      */
     setPointHoverRadius(datasetIndex: number, hoverRadius: number): this;
     /**
@@ -1774,7 +1916,6 @@ declare class LineChart extends CartesianChart<'line'> implements LineChartBuild
      * @param {number} hoverRadius
      * @description 모든 데이터셋의 Point Hover Radius를 설정합니다.
      * @Since 1.0.0
-     * @category dataset
      *
      */
     setAllPointHoverRadius(hoverRadius: number): this;
@@ -1787,7 +1928,6 @@ declare class LineChart extends CartesianChart<'line'> implements LineChartBuild
      * @description 지정된 데이터셋에 단계별 그라디언트를 적용합니다.
      * @remarks step 인자는 2 이상만 지원할것입니다.
      * @Since 1.0.0
-     * @category dataset
      * @beta (기능 테스트 중)
      */
     setGradient(datasetIndex: number, steps: number, colors: string[], direction?: 'vertical' | 'horizontal'): this;
@@ -1798,7 +1938,6 @@ declare class LineChart extends CartesianChart<'line'> implements LineChartBuild
      * @param {'vertical' | 'horizontal'} direction - 그라디언트 방향 (기본값: vertical)
      * @description 모든 데이터셋에 동일한 그라디언트를 적용합니다.
      * @Since 1.0.0
-     * @category dataset
      * @beta (기능 테스트 중)
      */
     setAllGradient(steps: number, colors: string[], direction?: 'vertical' | 'horizontal'): this;
@@ -1807,7 +1946,6 @@ declare class LineChart extends CartesianChart<'line'> implements LineChartBuild
      * @param {number} datasetIndex - 대상 데이터셋 인덱스
      * @description 지정된 데이터셋의 그라디언트를 제거합니다.
      * @Since 1.0.0
-     * @category dataset
      * @beta (기능 테스트 중)
      */
     removeGradient(datasetIndex: number): this;
@@ -1815,7 +1953,6 @@ declare class LineChart extends CartesianChart<'line'> implements LineChartBuild
      *
      * @description 모든 데이터셋의 그라디언트를 제거합니다.
      * @Since 1.0.0
-     * @category dataset
      * @beta (기능 테스트 중)
      */
     removeAllGradients(): this;
@@ -1825,7 +1962,6 @@ declare class LineChart extends CartesianChart<'line'> implements LineChartBuild
      * @returns {number[]} 0부터 1까지의 위치 배열
      * @description 주어진 단계 수에 따라 그라디언트 위치를 계산합니다.
      * @Since 1.0.0
-     * @category utility
      * @private
      * @beta (기능 테스트 중)
      */
@@ -1834,7 +1970,6 @@ declare class LineChart extends CartesianChart<'line'> implements LineChartBuild
      * @description 스파크라인 차트 옵션을 적용합니다. mixed 차트에서는 동작하지 않습니다.
      * @returns {this}
      * @since 1.0.1
-     * @category options
      * @beta (기능 테스트 중)
      */
     sparkLineChart(): this;
@@ -1856,7 +1991,6 @@ declare class BubbleChart extends CartesianChart<'bubble'> implements BubbleChar
      * @param {number} radius - 반지름 값
      * @returns {this}
      * @since 1.0.0
-     * @category dataset
      */
     setBubbleRadius(datasetIndex: number, radius: number): this;
     /**
@@ -1864,7 +1998,6 @@ declare class BubbleChart extends CartesianChart<'bubble'> implements BubbleChar
      * @param {number} radius - 반지름 값
      * @returns {this}
      * @since 1.0.0
-     * @category dataset
      */
     setAllBubbleRadius(radius: number): this;
     /**
@@ -1874,7 +2007,6 @@ declare class BubbleChart extends CartesianChart<'bubble'> implements BubbleChar
      * @param {number} radius - 반지름 값
      * @returns {this}
      * @since 1.0.0
-     * @category data
      * @example
      * bubbleChart.setBubbleDataRadius(0, 2, 25); // 첫 번째 데이터셋의 세 번째 버블 크기를 25로 설정
      */
@@ -1885,7 +2017,6 @@ declare class BubbleChart extends CartesianChart<'bubble'> implements BubbleChar
      * @param {number} radius - 반지름 값
      * @returns {this}
      * @since 1.0.0
-     * @category data
      * @example
      * bubbleChart.setAllBubbleDataRadius(0, 15); // 첫 번째 데이터셋의 모든 버블 크기를 15로 설정
      */
@@ -1897,7 +2028,6 @@ declare class BubbleChart extends CartesianChart<'bubble'> implements BubbleChar
      * @param {number} radius - 반지름 값
      * @returns {this}
      * @since 1.0.0
-     * @category data
      * @example
      * bubbleChart.setBubbleDataRadiusByName(0, '서울', 50); // '서울' 버블의 크기를 50으로 설정
      */
@@ -1908,7 +2038,6 @@ declare class BubbleChart extends CartesianChart<'bubble'> implements BubbleChar
      * @param {Function} updateFn - 업데이트 함수 (dataPoint, index) => newRadius
      * @returns {this}
      * @since 1.0.0
-     * @category data
      * @example
      * // 모든 버블의 크기를 2배로
      * bubbleChart.updateBubbleDataRadius(0, (data) => data.r * 2);
@@ -1929,7 +2058,6 @@ declare class BubbleChart extends CartesianChart<'bubble'> implements BubbleChar
      * @param {number} radius - 반지름 값
      * @returns {this}
      * @since 1.0.0
-     * @category data
      * @example
      * // 인구가 50 이상인 도시만 크기 50으로
      * bubbleChart.setBubbleDataRadiusWhere(0, (data) => data.population >= 50, 50);
@@ -1941,7 +2069,6 @@ declare class BubbleChart extends CartesianChart<'bubble'> implements BubbleChar
      * @param {number} hoverRadius - 호버 시 반지름 값
      * @returns {this}
      * @since 1.0.0
-     * @category dataset
      */
     setHoverRadius(datasetIndex: number, hoverRadius: number): this;
     /**
@@ -1949,7 +2076,6 @@ declare class BubbleChart extends CartesianChart<'bubble'> implements BubbleChar
      * @param {number} hoverRadius - 호버 시 반지름 값
      * @returns {this}
      * @since 1.0.0
-     * @category dataset
      */
     setAllHoverRadius(hoverRadius: number): this;
     /**
@@ -1958,7 +2084,6 @@ declare class BubbleChart extends CartesianChart<'bubble'> implements BubbleChar
      * @param {number} borderWidth - 테두리 두께
      * @returns {this}
      * @since 1.0.0
-     * @category dataset
      */
     setBorderWidth(datasetIndex: number, borderWidth: number): this;
     /**
@@ -1966,14 +2091,12 @@ declare class BubbleChart extends CartesianChart<'bubble'> implements BubbleChar
      * @param {number} borderWidth - 테두리 두께
      * @returns {this}
      * @since 1.0.0
-     * @category dataset
      */
     setAllBorderWidth(borderWidth: number): this;
     /**
      * @description 스파크 버블 차트 옵션을 적용합니다.
      * @returns {this}
      * @since 1.0.0
-     * @category options
      * @beta (기능 테스트 중)
      */
     sparkBubbleChart(): this;
@@ -1983,7 +2106,6 @@ declare class BubbleChart extends CartesianChart<'bubble'> implements BubbleChar
      * @param {number} rotation - 회전 각도 (도 단위)
      * @returns {this}
      * @since 1.0.0
-     * @category dataset
      */
     setRotation(datasetIndex: number, rotation: number): this;
     /**
@@ -1991,7 +2113,6 @@ declare class BubbleChart extends CartesianChart<'bubble'> implements BubbleChar
      * @param {number} rotation - 회전 각도 (도 단위)
      * @returns {this}
      * @since 1.0.0
-     * @category dataset
      */
     setAllRotation(rotation: number): this;
 }
@@ -2027,12 +2148,12 @@ declare abstract class ArcChart<TType extends ArcChartType> extends Chart<TType>
      * @param {number} idx
      * @Returns {void}
      * @Since 1.0.1
-     * @category Dataset
      * @beta
      */
     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;
     }[];
@@ -2044,7 +2165,6 @@ declare abstract class ArcChart<TType extends ArcChartType> extends Chart<TType>
      * @param id
      * @returns {ChartConfig}
      * @Since 1.0.0
-     * @category Chart
      * @beta
      */
     build(id?: string): ChartConfig;
@@ -2053,7 +2173,6 @@ declare abstract class ArcChart<TType extends ArcChartType> extends Chart<TType>
      * @param rotation - 시작 각도 (도 단위)
      * @returns {this}
      * @since 1.0.0
-     * @category Options
      * @beta
      */
     setRotation(rotation: number): this;
@@ -2062,7 +2181,6 @@ declare abstract class ArcChart<TType extends ArcChartType> extends Chart<TType>
      * @param circumference - 원주각 (도 단위, 360 = 완전한 원)
      * @returns {this}
      * @since 1.0.0
-     * @category Options
      * @beta
      */
     setCircumference(circumference: number): this;
@@ -2071,7 +2189,6 @@ declare abstract class ArcChart<TType extends ArcChartType> extends Chart<TType>
      * @param cutout - 구멍 크기 (퍼센트 문자열 또는 픽셀 숫자)
      * @returns {this}
      * @since 1.0.0
-     * @category Options
      * @beta
      */
     setCutout(cutout: string | number): this;
@@ -2080,7 +2197,6 @@ declare abstract class ArcChart<TType extends ArcChartType> extends Chart<TType>
      * @param radius - 반지름 (퍼센트 문자열 또는 픽셀 숫자)
      * @returns {this}
      * @since 1.0.0
-     * @category Options
      * @beta
      */
     setRadius(radius: string | number): this;
@@ -2090,7 +2206,6 @@ declare abstract class ArcChart<TType extends ArcChartType> extends Chart<TType>
      * @param borderWidth - 경계선 너비
      * @returns {this}
      * @since 1.0.0
-     * @category Dataset
      * @beta
      */
     setBorderWidth(datasetIndex: number, borderWidth: number): this;
@@ -2099,7 +2214,6 @@ declare abstract class ArcChart<TType extends ArcChartType> extends Chart<TType>
      * @param borderWidth - 경계선 너비
      * @returns {this}
      * @since 1.0.0
-     * @category Dataset
      * @beta
      */
     setAllBorderWidth(borderWidth: number): this;
@@ -2109,7 +2223,6 @@ declare abstract class ArcChart<TType extends ArcChartType> extends Chart<TType>
      * @param borderColor - 경계선 색상
      * @returns {this}
      * @since 1.0.0
-     * @category Dataset
      * @beta
      */
     setBorderColor(datasetIndex: number, borderColor: string | string[]): this;
@@ -2118,7 +2231,6 @@ declare abstract class ArcChart<TType extends ArcChartType> extends Chart<TType>
      * @param borderColor - 경계선 색상
      * @returns {this}
      * @since 1.0.0
-     * @category Dataset
      * @beta
      */
     setAllBorderColor(borderColor: string | string[]): this;
@@ -2128,7 +2240,6 @@ declare abstract class ArcChart<TType extends ArcChartType> extends Chart<TType>
      * @param config - 이미지 설정 옵션
      * @returns {this}
      * @since 1.6.0
-     * @category Dataset
      * @beta
      * @example
      * // URL 방식 (순서대로 매핑)
@@ -2160,7 +2271,6 @@ declare class DoughnutChart extends ArcChart<'doughnut'> implements DoughnutChar
      * @param {string} id
      * @returns {ChartConfig}
      * @Since 1.0.0
-     * @category config
      * @beta
      */
     makeConfig(id?: string): ChartConfig;
@@ -2169,7 +2279,6 @@ declare class DoughnutChart extends ArcChart<'doughnut'> implements DoughnutChar
      * @param cutout - 구멍 크기 ('50%', '60%' 또는 픽셀값)
      * @returns {this}
      * @since 1.0.0
-     * @category Options
      * @beta
      */
     setCutout(cutout: string | number): this;
@@ -2177,7 +2286,6 @@ declare class DoughnutChart extends ArcChart<'doughnut'> implements DoughnutChar
      * @description 도넛 차트를 파이 차트로 변경합니다 (구멍 제거).
      * @returns {this}
      * @since 1.0.0
-     * @category Options
      * @beta
      */
     convertToPie(): this;
@@ -2186,7 +2294,6 @@ declare class DoughnutChart extends ArcChart<'doughnut'> implements DoughnutChar
      * @param colors - 색상 배열
      * @returns {this}
      * @since 1.0.0
-     * @category Dataset
      * @beta
      */
     setSegmentColors(colors: string[]): this;
@@ -2196,7 +2303,6 @@ declare class DoughnutChart extends ArcChart<'doughnut'> implements DoughnutChar
      * @param offset - 분리 거리 (픽셀)
      * @returns {this}
      * @since 1.0.0
-     * @category Dataset
      * @beta
      */
     setSegmentOffset(dataIndex: number, offset: number): this;
@@ -2205,7 +2311,6 @@ declare class DoughnutChart extends ArcChart<'doughnut'> implements DoughnutChar
      * @param rotation - 회전 각도 (도 단위)
      * @returns {this}
      * @since 1.0.0
-     * @category Options
      * @beta
      */
     setRotation(rotation: number): this;
@@ -2214,7 +2319,6 @@ declare class DoughnutChart extends ArcChart<'doughnut'> implements DoughnutChar
      * @param circumference - 원주각 (도 단위, 360 = 완전한 원)
      * @returns {this}
      * @since 1.0.0
-     * @category Options
      * @beta
      */
     setCircumference(circumference: number): this;
@@ -2223,7 +2327,6 @@ declare class DoughnutChart extends ArcChart<'doughnut'> implements DoughnutChar
      * @param radius - 반지름 ('90%', '100%' 또는 픽셀값)
      * @returns {this}
      * @since 1.0.0
-     * @category Options
      * @beta
      */
     setRadius(radius: string | number): this;
@@ -2232,7 +2335,6 @@ declare class DoughnutChart extends ArcChart<'doughnut'> implements DoughnutChar
      * @param borderWidth - 경계선 너비
      * @returns {this}
      * @since 1.0.0
-     * @category Dataset
      * @beta
      */
     setAllBorderWidth(borderWidth: number): this;
@@ -2241,7 +2343,6 @@ declare class DoughnutChart extends ArcChart<'doughnut'> implements DoughnutChar
      * @param borderColor - 경계선 색상
      * @returns {this}
      * @since 1.0.0
-     * @category Dataset
      * @beta
      */
     setAllBorderColor(borderColor: string | string[]): this;
@@ -2250,7 +2351,6 @@ declare class DoughnutChart extends ArcChart<'doughnut'> implements DoughnutChar
      * @param {{text: string | string[], color?: string, fontStyle?: string, sidePadding?: number, minFontSize?: number, maxFontSize?: number}} config
      * @returns {this}
      * @since 1.0.0
-     * @category plugin
      * @example
      * const chart = chartWrapper.create('doughnut', labels, datasets, options).setCenterText({
      *   text: 'Center Text',
@@ -2280,7 +2380,6 @@ declare class PieChart extends ArcChart<'pie'> implements PieChartBuilder {
      * @param {string} id
      * @returns {ChartConfig}
      * @Since 1.0.0
-     * @category config
      * @beta
      */
     makeConfig(id?: string): ChartConfig;
@@ -2289,7 +2388,6 @@ declare class PieChart extends ArcChart<'pie'> implements PieChartBuilder {
      * @param colors - 색상 배열
      * @returns {this}
      * @since 1.0.0
-     * @category Dataset
      * @beta
      */
     setSegmentColors(colors: string[]): this;
@@ -2299,7 +2397,6 @@ declare class PieChart extends ArcChart<'pie'> implements PieChartBuilder {
      * @param offset - 분리 거리 (픽셀)
      * @returns {this}
      * @since 1.0.0
-     * @category Dataset
      * @beta
      */
     setSegmentOffset(dataIndex: number, offset: number): this;
@@ -2308,7 +2405,6 @@ declare class PieChart extends ArcChart<'pie'> implements PieChartBuilder {
      * @param rotation - 회전 각도 (도 단위)
      * @returns {this}
      * @since 1.0.0
-     * @category Options
      * @beta
      */
     setRotation(rotation: number): this;
@@ -2317,7 +2413,6 @@ declare class PieChart extends ArcChart<'pie'> implements PieChartBuilder {
      * @param circumference - 원주각 (도 단위, 360 = 완전한 원)
      * @returns {this}
      * @since 1.0.0
-     * @category Options
      * @beta
      */
     setCircumference(circumference: number): this;
@@ -2326,7 +2421,6 @@ declare class PieChart extends ArcChart<'pie'> implements PieChartBuilder {
      * @param radius - 반지름 ('90%', '100%' 또는 픽셀값)
      * @returns {this}
      * @since 1.0.0
-     * @category Options
      * @beta
      */
     setRadius(radius: string | number): this;
@@ -2335,7 +2429,6 @@ declare class PieChart extends ArcChart<'pie'> implements PieChartBuilder {
      * @param borderWidth - 경계선 너비
      * @returns {this}
      * @since 1.0.0
-     * @category Dataset
      * @beta
      */
     setAllBorderWidth(borderWidth: number): this;
@@ -2344,7 +2437,6 @@ declare class PieChart extends ArcChart<'pie'> implements PieChartBuilder {
      * @param borderColor - 경계선 색상
      * @returns {this}
      * @since 1.0.0
-     * @category Dataset
      * @beta
      */
     setAllBorderColor(borderColor: string | string[]): this;
@@ -2352,7 +2444,6 @@ declare class PieChart extends ArcChart<'pie'> implements PieChartBuilder {
      * @description 상단 반원형 파이 차트를 생성합니다.
      * @returns {this}
      * @since 1.0.0
-     * @category Options
      * @beta
      */
     setHalfPieTop(): this;
@@ -2360,7 +2451,6 @@ declare class PieChart extends ArcChart<'pie'> implements PieChartBuilder {
      * @description 하단 반원형 파이 차트를 생성합니다.
      * @returns {this}
      * @since 1.0.0
-     * @category Options
      * @beta
      */
     setHalfPieBottom(): this;
@@ -2368,7 +2458,6 @@ declare class PieChart extends ArcChart<'pie'> implements PieChartBuilder {
      * @description 좌측 반원형 파이 차트를 생성합니다.
      * @returns {this}
      * @since 1.0.0
-     * @category Options
      * @beta
      */
     setHalfPieLeft(): this;
@@ -2376,7 +2465,6 @@ declare class PieChart extends ArcChart<'pie'> implements PieChartBuilder {
      * @description 우측 반원형 파이 차트를 생성합니다.
      * @returns {this}
      * @since 1.0.0
-     * @category Options
      * @beta
      */
     setHalfPieRight(): this;
@@ -2385,7 +2473,6 @@ declare class PieChart extends ArcChart<'pie'> implements PieChartBuilder {
      * @param offset - 분리 거리 (픽셀, 기본값: 10)
      * @returns {this}
      * @since 1.0.0
-     * @category Dataset
      * @beta
      */
     highlightMaxSegment(offset?: number): this;
@@ -2394,7 +2481,6 @@ declare class PieChart extends ArcChart<'pie'> implements PieChartBuilder {
      * @param offset - 분리 거리 (픽셀, 기본값: 10)
      * @returns {this}
      * @since 1.0.0
-     * @category Dataset
      * @beta
      */
     highlightMinSegment(offset?: number): this;
@@ -2403,7 +2489,6 @@ declare class PieChart extends ArcChart<'pie'> implements PieChartBuilder {
      * @param offsets - 각 세그먼트의 offset 배열 또는 모든 세그먼트에 적용할 단일 값
      * @returns {this}
      * @since 1.0.0
-     * @category Dataset
      * @beta
      * @example
      * // 각 세그먼트마다 다른 offset
@@ -2419,7 +2504,6 @@ declare class PieChart extends ArcChart<'pie'> implements PieChartBuilder {
      * @param endColor - 종료 색상 (hex 형식, 예: '#36A2EB')
      * @returns {this}
      * @since 1.0.0
-     * @category Dataset
      * @beta
      */
     setGradientColors(startColor: string, endColor: string): this;
@@ -2429,7 +2513,6 @@ declare class PieChart extends ArcChart<'pie'> implements PieChartBuilder {
      * @param color - 적용할 색상
      * @returns {this}
      * @since 1.0.0
-     * @category Dataset
      * @beta
      * @example
      * // 값이 100 이상인 세그먼트만 빨간색으로
@@ -2478,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;
     }[];
@@ -2488,7 +2572,6 @@ declare class TreemapChart extends Chart<'treemap', CustomTreemapChartOptions> i
      * @param id
      * @returns {ChartConfig}
      * @Since 1.0.0
-     * @category Chart
      */
     build(id?: string): ChartConfig;
     /**
@@ -2496,7 +2579,6 @@ declare class TreemapChart extends Chart<'treemap', CustomTreemapChartOptions> i
      * @param data - 계층적 트리 데이터
      * @returns {this}
      * @since 1.0.0
-     * @category Data
      */
     setTreeData(data: Record<string, unknown>[] | number[] | Record<string, unknown>): this;
     /**
@@ -2504,7 +2586,6 @@ declare class TreemapChart extends Chart<'treemap', CustomTreemapChartOptions> i
      * @param key - 색상 키
      * @returns {this}
      * @since 1.0.0
-     * @category Options
      */
     setColorKey(key: string): this;
     /**
@@ -2512,7 +2593,6 @@ declare class TreemapChart extends Chart<'treemap', CustomTreemapChartOptions> i
      * @param key - 라벨 키
      * @returns {this}
      * @since 1.0.0
-     * @category Options
      */
     setLabelKey(key: string): this;
     /**
@@ -2520,7 +2600,6 @@ declare class TreemapChart extends Chart<'treemap', CustomTreemapChartOptions> i
      * @param key - 값 키
      * @returns {this}
      * @since 1.0.0
-     * @category Options
      */
     setValueKey(key: string): this;
     /**
@@ -2528,7 +2607,6 @@ declare class TreemapChart extends Chart<'treemap', CustomTreemapChartOptions> i
      * @param spacing - 간격 (픽셀)
      * @returns {this}
      * @since 1.0.0
-     * @category Options
      */
     setSpacing(spacing: number): this;
     /**
@@ -2536,7 +2614,6 @@ declare class TreemapChart extends Chart<'treemap', CustomTreemapChartOptions> i
      * @param borderWidth - 경계선 너비
      * @returns {this}
      * @since 1.0.0
-     * @category Options
      */
     setBorderWidth(borderWidth: number): this;
     /**
@@ -2544,7 +2621,6 @@ declare class TreemapChart extends Chart<'treemap', CustomTreemapChartOptions> i
      * @param borderColor - 경계선 색상
      * @returns {this}
      * @since 1.0.0
-     * @category Options
      */
     setBorderColor(borderColor: string): this;
 }
@@ -2552,7 +2628,6 @@ declare class TreemapChart extends Chart<'treemap', CustomTreemapChartOptions> i
 /**
  * @description Cartesian 차트에서 사용할 수 있는 플러그인들을 제공합니다.
  * @since 1.6.6
- * @category Plugins
  */
 /**
  * @description 오늘 날짜에 수직선을 그리는 플러그인을 생성합니다.
@@ -2560,7 +2635,7 @@ declare class TreemapChart extends Chart<'treemap', CustomTreemapChartOptions> i
  * @param text (기본값 : 'TODAY')
  * @returns {object} Chart.js 플러그인 객체
  * @since 1.6.6
- * @category Plugins
+ * @group Cartesian Plugins
  * @example
  * const todayLine = createTodayLinePlugin('rgb(255,0,0)');
  * chart.setPlugin(todayLine);
@@ -2574,7 +2649,7 @@ declare const createTodayLinePlugin: (color?: string, text?: string) => {
  * @param {string} color - 주말 배경색 (기본값: 'rgba(102, 102, 102, 0.2)')
  * @returns {object} Chart.js 플러그인 객체
  * @since 1.6.6
- * @category Plugins
+ * @group Cartesian Plugins
  * @example
  * const weekend = createWeekendPlugin('rgba(255, 0, 0, 0.1)');
  * chart.setPlugin(weekend);
@@ -2589,7 +2664,7 @@ declare const createWeekendPlugin: (color?: string) => {
  * @param {string} statusField - 상태값을 가져올 데이터 포인트의 필드명 (기본값: 'status')
  * @returns {object} Chart.js 플러그인 객체
  * @since 1.6.6
- * @category Plugins
+ * @group Cartesian Plugins
  * @example
  * // 기본 아이콘 사용
  * const status = createStatusPlugin();
@@ -2618,7 +2693,7 @@ declare const createStatusPlugin: (imageUrls?: {
  * @param {object} options - 텍스트 스타일 옵션
  * @returns {object} Chart.js 플러그인 객체
  * @since 1.6.6
- * @category Plugins
+ * @group Cartesian Plugins
  * @example
  * // assignee 필드 표시
  * const assignedTasks = createAssignedTasksPlugin('assignee');
@@ -2644,23 +2719,41 @@ declare const createAssignedTasksPlugin: (fieldName?: string, options?: {
     afterDatasetsDraw(chart: any, args: any, pluginOptions: any): void;
 };
 
+/**
+ * @description 데이터가 없을 때 'No data' 텍스트를 차트 중앙에 표시하는 플러그인입니다.
+ * @group Common Plugins
+ */
 declare const noDataPlugin: {
     id: string;
     beforeUpdate: (chart: any) => void;
     afterDraw: (chart: any) => void;
     beforeDestroy(chart: any): void;
 };
+/**
+ * @description 차트 줌 상태에서 초기 뷰로 돌아가는 리셋 버튼을 차트 위에 표시하는 플러그인입니다.
+ * @group Common Plugins
+ */
 declare const zoomResetPlugin: {
     id: string;
     afterDraw(chart: any, args: any, options: any): void;
     afterEvent(chart: any, args: any): void;
 };
+/**
+ * @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 컨테이너에 커스텀 범례를 렌더링하는 플러그인입니다.
+ * containerID 옵션으로 렌더링 대상 엘리먼트를 지정합니다.
+ * @group Common Plugins
+ */
 declare const customLegend: {
     id: string;
     _Default: {
@@ -2700,10 +2793,12 @@ declare const customLegend: {
     afterUpdate(chart: any, args: any, options: any): void;
 };
 /**
- * @description 차트가 마운트될 때 호출되는 플러그인입니다.
+ * @description 차트가 마운트될 때 `_mounted` 콜백을 호출하고 ChartInstance에 등록하는 플러그인입니다.
+ * @group Common Plugins
  */
 declare const chartMountPlugin: {
     id: string;
+    beforeInit(chart: any): void;
     afterDraw(chart: any, args: any, options: any): void;
     afterDestroy(chart: any): void;
 };
@@ -2719,7 +2814,6 @@ declare const chartMountPlugin: {
  * - `_tooltip: string | function` - 범례 항목 마우스 오버 시 툴팁 표시
  *
  * @since 1.3.0
- * @category plugin
  * @example
  * ```typescript
  * // 기본 사용법
@@ -2778,6 +2872,7 @@ declare const chartMountPlugin: {
  * - 메모리 누수 방지를 위해 차트 파괴 시 자동으로 정리됩니다
  *
  * @beta (aux 정상동작 , _group : 에러 , groupLabel : 정상 , _tooltip : 에러 , _toggleBehavior : 정상 , _visible : 정상 , _legendOrder : 확인중)
+ * @group Common Plugins
  */
 declare const customDatasetPlugins: {
     id: string;
@@ -2793,12 +2888,33 @@ declare const customDatasetPlugins: {
     _hideTooltip(chart: any): void;
     afterDestroy(chart: any): void;
 };
+/**
+ * @description 임계값을 초과하는 데이터 포인트에 깜빡이는 하이라이트 효과를 표시하는 플러그인입니다.
+ * @group Common Plugins
+ */
 declare const blinkPlugin: Plugin$1;
+/**
+ * @description 도넛 차트 중앙에 표시할 HTML 문자열을 생성하는 유틸리티 함수입니다.
+ * @param percent - 퍼센트 값
+ * @param ok - 정상 건수
+ * @param warn - 경고 건수
+ * @param ng - 불량 건수
+ * @group Common Plugins
+ */
 declare const makeCenterHtml: (percent: number, ok?: number, warn?: number, ng?: number) => string;
+/**
+ * @description 바 차트 축 레이블 위치에 이미지를 표시하는 플러그인입니다.
+ * 데이터셋에 `image` 프로퍼티를 지정하면 해당 이미지가 렌더링됩니다.
+ * @group Common Plugins
+ */
 declare const barScaleImgPlugin: {
     id: string;
     beforeDatasetsDraw(chart: any, args: any, options: any): void;
 };
+/**
+ * @description 차트 우측 상단에 설정 아이콘 버튼을 표시하고 클릭 이벤트를 처리하는 플러그인입니다.
+ * @group Common Plugins
+ */
 declare const changeSetting: {
     id: string;
     _Default: SettingOptions;
@@ -2806,6 +2922,11 @@ declare const changeSetting: {
     beforeDraw(chart: any): void;
     afterDestroy(chart: any): void;
 };
+/**
+ * @description 차트 하단에 드래그 가능한 범위 슬라이더를 렌더링하여 x축 줌을 제어하는 플러그인입니다.
+ * 색상 커스터마이징이 필요하다면 {@link CreateZoomRangeSlider}를 사용하세요.
+ * @group Common Plugins
+ */
 declare const zoomRangeSlider: {
     id: string;
     var: {
@@ -2817,8 +2938,26 @@ declare const zoomRangeSlider: {
     afterUpdate(chart: any, args: any, options: any): void;
     afterEvent(chart: any, args: any, options: any): void;
 };
+/**
+ * @description 색상을 커스터마이징 가능한 줌 범위 슬라이더 플러그인 인스턴스를 생성합니다.
+ * @param colors - 슬라이더 색상 옵션 {@link ZoomRangeSliderColors}
+ * @returns Chart.js 플러그인 객체
+ * @group Common Plugins
+ */
 declare const CreateZoomRangeSlider: (colors?: ZoomRangeSliderColors) => ZoomRangeSliderPlugin;
 
+/**
+ * @description 도넛 차트 중앙에 텍스트를 HTML 오버레이로 표시하는 플러그인 인스턴스를 생성합니다.
+ * 데이터가 없으면 자동으로 숨겨집니다.
+ * @param config - 텍스트, 색상, 폰트 설정
+ * @returns Chart.js 플러그인 객체
+ * @group Doughnut Plugins
+ * @example
+ * ```typescript
+ * const plugin = doughnutCenterTextPlugin({ text: ['75%', '정상'], color: '#333' });
+ * chart.setPlugin(plugin);
+ * ```
+ */
 declare function doughnutCenterTextPlugin(config: {
     text: string | string[];
     color?: string;
@@ -2831,6 +2970,13 @@ declare function doughnutCenterTextPlugin(config: {
     updatePosition(chart: Chart$1): void;
     destroy(chart: Chart$1): void;
 };
+/**
+ * @description 도넛/파이 차트의 각 세그먼트 중앙에 이미지를 렌더링하는 플러그인 인스턴스를 생성합니다.
+ * `string[]` 또는 `_uid` 매핑 방식을 모두 지원합니다.
+ * @param config - 이미지 소스 및 크기 설정 {@link SegmentImageConfig}
+ * @returns Chart.js 플러그인 객체
+ * @group Doughnut Plugins
+ */
 declare function segmentImagePlugin(config: SegmentImageConfig): {
     id: string;
     afterDatasetDraw(chart: Chart$1<"doughnut" | "pie">, args: any): void;
@@ -2916,7 +3062,6 @@ declare const DefaultDataLabelsOptions: {
  * @description `setTimeScale()` 호출 시 별도 값이 전달되지 않았을 때 적용되는 시간 축 기본 옵션입니다.
  * `unit`, `tooltipFormat`, `displayFormats.hour`의 기본값을 제공합니다.
  * @since 2.4.0
- * @category Scales
  * @example
  * // setTimeScale('x')만 호출하면 아래 기본값이 적용됩니다.
  * ChartWrapper.create('line', [], datasets)
@@ -3141,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. */
@@ -3185,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;
@@ -3198,7 +3399,6 @@ type ChartTarget = string | Chart$1;
  * @param target 차트 ID 또는 Chart 인스턴스
  * @returns Chart.js 인스턴스
  * @since 2.3.5
- * @category util
  * @example
  * ```ts
  * const chart = getChartInstance('sales-chart');
@@ -3211,7 +3411,6 @@ declare function getChartInstance(chartId: string): Chart$1;
  * 차트의 zoom 상태를 초기화합니다.
  * @param target 차트 ID 또는 Chart 인스턴스
  * @since 2.3.5
- * @category util
  * @example
  * ```ts
  * resetChartZoom('sales-chart');
@@ -3224,7 +3423,6 @@ 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');
@@ -3236,7 +3434,6 @@ declare function updateChart(chartId: string, mode?: Parameters<Chart$1['update'
  * 차트 크기를 다시 계산합니다.
  * @param target 차트 ID 또는 Chart 인스턴스
  * @since 2.3.5
- * @category util
  * @example
  * ```ts
  * resizeChart('sales-chart');
@@ -3249,7 +3446,6 @@ declare function resizeChart(chartId: string): void;
  * @param target 차트 ID 또는 Chart 인스턴스
  * @param activeElements 활성화할 요소 목록
  * @since 2.3.5
- * @category util
  * @example
  * ```ts
  * setChartActiveElements('sales-chart', [{ datasetIndex: 0, index: 2 }]);
@@ -3261,7 +3457,6 @@ declare function setChartActiveElements(chartId: string, activeElements: ActiveE
  * 차트의 active element를 모두 해제합니다.
  * @param target 차트 ID 또는 Chart 인스턴스
  * @since 2.3.5
- * @category util
  * @example
  * ```ts
  * clearChartActiveElements('sales-chart');
@@ -3275,7 +3470,6 @@ declare function clearChartActiveElements(chartId: string): void;
  * @param datasetIndex dataset index
  * @param visible 표시 여부
  * @since 2.3.5
- * @category util
  * @example
  * ```ts
  * setChartDatasetVisibility('sales-chart', 1, false);
@@ -3289,7 +3483,6 @@ declare function setChartDatasetVisibility(chartId: string, datasetIndex: number
  * @param datasetIndex dataset index
  * @returns 토글 후 표시 여부
  * @since 2.3.5
- * @category util
  * @example
  * ```ts
  * const visible = toggleChartDatasetVisibility('sales-chart', 1);
@@ -3303,7 +3496,6 @@ declare function toggleChartDatasetVisibility(chartId: string, datasetIndex: num
  * @param datasetIndex dataset index
  * @returns 표시 여부
  * @since 2.3.5
- * @category util
  * @example
  * ```ts
  * const visible = isChartDatasetVisible('sales-chart', 1);
@@ -3317,7 +3509,6 @@ declare function isChartDatasetVisible(chartId: string, datasetIndex: number): b
  * @param activeElements 활성화할 요소 목록
  * @param position tooltip 위치. 생략 시 활성 요소 위치를 사용합니다.
  * @since 2.3.5
- * @category util
  * @example
  * ```ts
  * showChartTooltip('sales-chart', [{ datasetIndex: 0, index: 2 }]);
@@ -3335,7 +3526,6 @@ declare function showChartTooltip(chartId: string, activeElements: ActiveElement
  * 차트 tooltip을 숨기고 active element를 해제합니다.
  * @param target 차트 ID 또는 Chart 인스턴스
  * @since 2.3.5
- * @category util
  * @example
  * ```ts
  * hideChartTooltip('sales-chart');
@@ -3349,7 +3539,6 @@ declare function hideChartTooltip(chartId: string): void;
  * @param datasetIndex dataset index
  * @returns dataset meta
  * @since 2.3.5
- * @category util
  * @example
  * ```ts
  * const meta = getChartDatasetMeta('sales-chart', 0);
@@ -3363,7 +3552,6 @@ declare function getChartDatasetMeta(chartId: string, datasetIndex: number): Ret
  * @param target 차트 ID 또는 Chart 인스턴스
  * @param options 이미지 내보내기 옵션
  * @since 1.5.0
- * @category util
  */
 declare function downloadChartAsImage(target: Chart$1, options?: ChartImageExportOptions): void;
 declare function downloadChartAsImage(target: string, options?: ChartImageExportOptions): void;
@@ -3372,7 +3560,6 @@ declare function downloadChartAsImage(target: string, options?: ChartImageExport
  * @param chart Chart 인스턴스
  * @param options 이미지 내보내기 옵션
  * @since 1.5.0
- * @category util
  */
 declare function downloadChartAsImageByInstance(chart: Chart$1, options?: ChartImageExportOptions): void;
 /**
@@ -3381,7 +3568,6 @@ declare function downloadChartAsImageByInstance(chart: Chart$1, options?: ChartI
  * @param options 이미지 내보내기 옵션
  * @returns Base64 인코딩된 이미지 데이터 URL
  * @since 1.5.0
- * @category util
  */
 declare function getChartAsBase64(target: Chart$1, options?: Omit<ChartImageExportOptions, 'filename'>): string;
 declare function getChartAsBase64(target: string, options?: Omit<ChartImageExportOptions, 'filename'>): string;
@@ -3391,7 +3577,6 @@ declare function getChartAsBase64(target: string, options?: Omit<ChartImageExpor
  * @param options 이미지 내보내기 옵션
  * @returns Base64 인코딩된 이미지 데이터 URL
  * @since 1.5.0
- * @category util
  */
 declare function getChartAsBase64ByInstance(chart: Chart$1, options?: Omit<ChartImageExportOptions, 'filename'>): string;
 /**
@@ -3400,7 +3585,6 @@ declare function getChartAsBase64ByInstance(chart: Chart$1, options?: Omit<Chart
  * @param options 이미지 내보내기 옵션
  * @returns Promise<Blob> 이미지 Blob
  * @since 1.5.0
- * @category util
  */
 declare function getChartAsBlob(target: Chart$1, options?: Omit<ChartImageExportOptions, 'filename'>): Promise<Blob>;
 declare function getChartAsBlob(target: string, options?: Omit<ChartImageExportOptions, 'filename'>): Promise<Blob>;
@@ -3410,7 +3594,6 @@ declare function getChartAsBlob(target: string, options?: Omit<ChartImageExportO
  * @param options 이미지 내보내기 옵션
  * @returns Promise<Blob> 이미지 Blob
  * @since 1.5.0
- * @category util
  */
 declare function getChartAsBlobByInstance(chart: Chart$1, options?: Omit<ChartImageExportOptions, 'filename'>): Promise<Blob>;
 
@@ -3447,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 };