@univerjs-pro/engine-chart 1.0.0-alpha.8 → 1.0.0-beta.1

package/lib/types/chart-builder/conversion/resolve-chart-model-data.d.ts

@@ -1,5 +1,5 @@
-import type { ChartModel } from '../../models/chart-model';
+import type { ChartModel } from '../../models/chart-model/chart-model';
 import type { IChartData, IUniverDataSet } from '../../types';
 import type { ChartPendingConfig } from '../chart-types';
 /** Resolves fresh engine semantic data from the model plus an uncommitted Facade patch. */
-export declare function resolveChartModelData(model: ChartModel, pending: ChartPendingConfig, dataSet?: IUniverDataSet, isRowDirection?: boolean): IChartData;
+export declare function resolveChartModelData(model: ChartModel, pending: ChartPendingConfig, dataSet?: IUniverDataSet): IChartData;

package/lib/types/chart-builder/detached-chart-builder-adapter.d.ts

@@ -1,4 +1,5 @@
-import type { IChartRenderModelImageExportOptions, IUniverDataSet } from '../types';
+import type { Injector } from '@univerjs/core';
+import type { IUniverDataSet } from '../types';
 import type { IChartBuilderAdapter } from './chart-builder-adapter';
 import type { ChartPendingConfig, IChartDescription } from './chart-types';
 /** Shared adapter behavior for builders that have not been inserted into a host. */
@@ -6,14 +7,13 @@ export declare class DetachedChartBuilderAdapter<THostDescription extends object
     private readonly _description;
     private readonly _commitError;
     /** Creates detached behavior for a description and host-specific commit error. */
-    constructor(_description: IChartDescription & THostDescription, _commitError: string);
+    constructor(_description: IChartDescription & THostDescription, _commitError: string, injector: Injector);
+    private readonly _localeTexts;
     /** Returns a clone of the detached description. */
     describe(config?: ChartPendingConfig, dataSet?: IUniverDataSet): IChartDescription & THostDescription;
     /** Rejects persistence until the chart has been inserted into a host. */
     commit(): never;
     /** Detached drafts have no hosted materialization lifecycle. */
     resolveData(): never;
-    /** Returns `null` because a detached chart has no render model. */
-    exportImage(_options?: IChartRenderModelImageExportOptions): Promise<null>;
     protected rejectCommit(): never;
 }

package/lib/types/chart-builder/internal/apply-pending-to-description.d.ts

@@ -0,0 +1,2 @@
+import type { ChartPendingConfig, IChartDescription } from '../chart-types';
+export declare function applyChartPendingConfigToDescription<THost extends object>(baseline: IChartDescription & THost, pending: ChartPendingConfig): IChartDescription & THost;

package/lib/types/chart-builder/internal/chart-host-config-adapter.d.ts

@@ -0,0 +1,3 @@
+import type { IUniverDataSet } from '../../types';
+/** Builds a detached data set from raw inline values and disposes the temporary source. */
+export declare function resolveChartDataSetFromValues<TCell>(values: TCell[][], buildDataSet: (data: TCell[][]) => IUniverDataSet, isRowDirection?: boolean): IUniverDataSet;

package/lib/types/chart-builder/internal/chart-patch-replace-policy.d.ts

@@ -0,0 +1,6 @@
+export declare const REPLACE_ONLY_PIE_COMPOSITE_SECONDARY_PLOT_SPLIT_PATH = "pie.composite.secondaryPlot.split";
+/**
+ * Object values at these paths are complete authored values, not partial object patches.
+ * Deep-merging them would retain fields omitted by the replacement value.
+ */
+export declare function isReplaceOnlyChartPatchPath(path: readonly string[]): boolean;

package/lib/types/chart-builder/internal/chart-pending-patch.d.ts

@@ -0,0 +1,11 @@
+import type { DeepNullish, IChartHistogramSpec } from '../../types';
+import type { ChartPendingConfig, IChartDescription, IChartMappingSpec } from '../chart-types';
+import type { IPatchFieldSchema, PatchSchema } from './patch-interpreter';
+type MappingPatch = DeepNullish<IChartMappingSpec>;
+type HistogramPatch = DeepNullish<IChartHistogramSpec>;
+export declare const mappingPatchSchema: PatchSchema<IChartMappingSpec, MappingPatch>;
+export declare const histogramPatchSchema: PatchSchema<IChartHistogramSpec, HistogramPatch>;
+export declare function semanticField<TKey extends keyof IChartDescription, TPatchValue>(key: TKey, path: readonly string[]): IPatchFieldSchema<IChartDescription, TPatchValue>;
+export declare function appendCollectionField<TKey extends keyof IChartDescription, TValue>(key: TKey): IPatchFieldSchema<IChartDescription, TValue[] | null | undefined>;
+export declare const seriesField: IPatchFieldSchema<IChartDescription, ChartPendingConfig['series']>;
+export {};

package/lib/types/chart-builder/internal/patch-interpreter.d.ts

@@ -0,0 +1,17 @@
+type Defined<T> = Exclude<T, null | undefined>;
+export interface IPatchFieldSchema<TState, TPatchValue> {
+    clear(current: TState): TState;
+    applyValue(current: TState, value: Defined<TPatchValue>): TState;
+    composeValue(current: Defined<TPatchValue>, next: Defined<TPatchValue>): Defined<TPatchValue>;
+}
+export type PatchSchema<TState, TPatch extends object> = {
+    [K in keyof TPatch]-?: IPatchFieldSchema<TState, TPatch[K]>;
+};
+export interface IPatchInterpreter<TState, TPatch extends object> {
+    apply(current: TState, patch: TPatch): TState;
+    compose(current: TPatch, next: TPatch): TPatch;
+}
+export declare function replaceField<TState extends object, TKey extends keyof TState>(key: TKey): IPatchFieldSchema<TState, TState[TKey]>;
+export declare function nestedField<TState extends object, TKey extends keyof TState, TNestedState extends object, TNestedPatch extends object>(key: TKey, schema: PatchSchema<TNestedState, TNestedPatch>): IPatchFieldSchema<TState, TNestedPatch>;
+export declare function createPatchInterpreter<TState, TPatch extends object>(schema: PatchSchema<TState, TPatch>): IPatchInterpreter<TState, TPatch>;
+export {};

package/lib/types/chart-data-aggregation.d.ts

@@ -0,0 +1,10 @@
+/** Canonical TopN configuration persisted with a chart. */
+export interface IChartTopNSpec {
+    count: number;
+    sourceIndex?: number;
+}
+/** Authored category aggregation and ranking configuration. */
+export interface IChartDataAggregation {
+    aggregate?: boolean;
+    topN?: IChartTopNSpec;
+}

package/lib/types/config/config.d.ts

@@ -0,0 +1,7 @@
+import type { IWordCloudRenderConfig } from '../wordcloud-chart/word-cloud-render-config';
+export declare const ENGINE_CHART_PLUGIN_CONFIG_KEY = "engine-chart.config";
+export declare const configSymbol: unique symbol;
+export interface IUniverChartConfig {
+    wordCloudRenderConfig?: IWordCloudRenderConfig;
+}
+export declare const defaultPluginConfig: IUniverChartConfig;

package/lib/types/enum.d.ts

@@ -82,8 +82,51 @@ export declare enum ChartTypeBits {
     /** Histogram chart */
     Histogram = 524288,
     /** Treemap chart */
-    Treemap = 1048576
-}
+    Treemap = 1048576,
+    /** Sunburst chart */
+    Sunburst = 2097152,
+    /** Gauge chart */
+    Gauge = 4194304,
+    /** Chord chart */
+    Chord = 8388608
+}
+export declare const ChartChordLabelPosition: {
+    readonly Inside: "inside";
+    readonly Outside: "outside";
+};
+export type ChartChordLabelPosition = typeof ChartChordLabelPosition[keyof typeof ChartChordLabelPosition];
+export declare const ChartChordFocusMode: {
+    readonly Adjacency: "adjacency";
+    readonly Self: "self";
+    readonly None: "none";
+};
+export type ChartChordFocusMode = typeof ChartChordFocusMode[keyof typeof ChartChordFocusMode];
+/** Persisted renderer-independent Chord ribbon color semantics. */
+export declare const ChartChordRibbonColorMode: {
+    readonly Source: "source";
+    readonly Target: "target";
+    readonly Gradient: "gradient";
+};
+export type ChartChordRibbonColorMode = typeof ChartChordRibbonColorMode[keyof typeof ChartChordRibbonColorMode];
+/** Persisted Gauge visual language. Missing historical values resolve to Modern. */
+export declare const ChartGaugeMode: {
+    readonly Modern: "modern";
+    readonly Classic: "classic";
+};
+export type ChartGaugeMode = typeof ChartGaugeMode[keyof typeof ChartGaugeMode];
+/** Persisted renderer-independent Gauge pointer shape. Missing historical values resolve to Needle. */
+export declare const ChartGaugePointerShape: {
+    readonly Needle: "needle";
+    readonly Slim: "slim";
+    readonly Arrow: "arrow";
+};
+export type ChartGaugePointerShape = typeof ChartGaugePointerShape[keyof typeof ChartGaugePointerShape];
+/** Persisted renderer-independent Sunburst label placement. */
+export declare const ChartSunburstLabelPosition: {
+    readonly Inside: "inside";
+    readonly Outside: "outside";
+};
+export type ChartSunburstLabelPosition = typeof ChartSunburstLabelPosition[keyof typeof ChartSunburstLabelPosition];
 export declare enum CategoryType {
     Linear = "Linear",
     Text = "Text",

package/lib/types/facade/builders/f-area-chart-builder.d.ts

@@ -1,6 +1,55 @@
-import type { AreaLineStyle, IChartLineSeriesPatch } from '@univerjs-pro/engine-chart';
+import type { AreaLineStyle, IChartInfo, IChartLineSeriesPatch, IChartSeriesStyleSpec } from '@univerjs-pro/engine-chart';
 import { FCartesianChartBuilder } from '../f-cartesian-chart-builder';
-export declare class FAreaChartBuilder extends FCartesianChartBuilder<Omit<IChartLineSeriesPatch, 'selector'>> {
+/**
+ * Fluent, type-specific Builder for Area Charts.
+ *
+ * @example Sheet
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+ * const chartInfo = fWorksheet
+ *   .newChart(univerAPI.Enum.ChartTypeString.Area)
+ *   .setSource('A1:D8')
+ *   .setAreaLineStyle(univerAPI.Enum.ChartAreaLineStyle.Smooth)
+ *   .build();
+ * await fWorksheet.insertChart(chartInfo);
+ * ```
+ *
+ * @example Doc
+ * ```ts
+ * const fDocument = univerAPI.getActiveDocument();
+ * const chartInfo = fDocument
+ *   .newChart(univerAPI.Enum.ChartTypeString.Area)
+ *   .setSource([['Month', 'East', 'West'], ['Jan', 120, 95], ['Feb', 180, 130]])
+ *   .setAreaLineStyle(univerAPI.Enum.ChartAreaLineStyle.Smooth)
+ *   .build();
+ * await fDocument.insertChart(chartInfo);
+ * ```
+ *
+ * @example Slide
+ * ```ts
+ * const fPresentation = univerAPI.getActivePresentation();
+ * const fSlide = fPresentation.getSlideByIndex(0);
+ * const chartInfo = fSlide
+ *   .newChart(univerAPI.Enum.ChartTypeString.Area)
+ *   .setSource([['Month', 'East', 'West'], ['Jan', 120, 95], ['Feb', 180, 130]])
+ *   .setAreaLineStyle(univerAPI.Enum.ChartAreaLineStyle.Smooth)
+ *   .build();
+ * await fSlide.insertChart(chartInfo);
+ * ```
+ *
+ * @example Board
+ * ```ts
+ * const fBoard = univerAPI.getActiveBoard();
+ * const chartInfo = fBoard
+ *   .newChart(univerAPI.Enum.ChartTypeString.Area)
+ *   .setSource([['Month', 'East', 'West'], ['Jan', 120, 95], ['Feb', 180, 130]])
+ *   .setAreaLineStyle(univerAPI.Enum.ChartAreaLineStyle.Smooth)
+ *   .build();
+ * await fBoard.insertChart(chartInfo);
+ * ```
+ */
+export declare class FAreaChartBuilder<TSource = never[], TDataSource = TSource, TInfo extends IChartInfo<TDataSource> = IChartInfo<TDataSource>> extends FCartesianChartBuilder<Omit<IChartLineSeriesPatch, 'selector'>, IChartSeriesStyleSpec, TSource, TDataSource, TInfo> {
     /**
      * Sets the area line style configuration and returns this builder for chaining.
      *
@@ -10,9 +59,7 @@ export declare class FAreaChartBuilder extends FCartesianChartBuilder<Omit<IChar
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Area);
-     * builder.setAreaLineStyle(univerAPI.Enum.AreaLineStyle.Smooth);
+     * builder.setAreaLineStyle(univerAPI.Enum.ChartAreaLineStyle.Smooth);
      * ```
      */
     setAreaLineStyle(value: AreaLineStyle): this;
@@ -24,8 +71,6 @@ export declare class FAreaChartBuilder extends FCartesianChartBuilder<Omit<IChar
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Area);
      * builder.clearAreaLineStyle();
      * ```
      */

package/lib/types/facade/builders/f-boxplot-chart-builder.d.ts

@@ -1,5 +1,90 @@
-import type { IChartSolidSeriesPatch, IChartSolidSeriesStyleSpec } from '@univerjs-pro/engine-chart';
+import type { IChartInfo, IChartSolidSeriesPatch, IChartSolidSeriesStyleSpec } from '@univerjs-pro/engine-chart';
 import { FCartesianChartBuilder } from '../f-cartesian-chart-builder';
-/** Boxplot keeps its existing automatic preset but does not expose explicit gradients. */
-export declare class FBoxplotChartBuilder extends FCartesianChartBuilder<Omit<IChartSolidSeriesPatch, 'selector'>, IChartSolidSeriesStyleSpec> {
+/**
+ * Boxplot keeps its existing automatic preset but does not expose explicit gradients.
+ *
+ * Each selected numeric field is one distribution and must contain its raw samples.
+ * The renderer calculates the five-number summary; do not supply precomputed
+ * Min/Q1/Median/Q3/Max rows. Field headers become distribution labels.
+ *
+ * @example Sheet
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+ * fWorksheet.getRange('A1:C6').setValues([
+ *   ['Group A', 'Group B', 'Group C'],
+ *   [12, 18, 9],
+ *   [15, 20, 13],
+ *   [19, 24, 16],
+ *   [22, 28, 21],
+ *   [25, 31, 24],
+ * ]);
+ * const chartInfo = fWorksheet
+ *   .newChart(univerAPI.Enum.ChartTypeString.Boxplot)
+ *   .setSource({
+ *     range: 'A1:C6',
+ *     orientation: univerAPI.Enum.ChartSourceOrientation.Columns,
+ *   })
+ *   .setValueFields([0, 1, 2])
+ *   .setTitle('Distribution')
+ *   .build();
+ * await fWorksheet.insertChart(chartInfo);
+ * ```
+ *
+ * @example Doc
+ * ```ts
+ * const fDocument = univerAPI.getActiveDocument();
+ * const chartInfo = fDocument
+ *   .newChart(univerAPI.Enum.ChartTypeString.Boxplot)
+ *   .setSource([
+ *     ['Group A', 'Group B'],
+ *     [12, 18],
+ *     [15, 20],
+ *     [19, 24],
+ *     [22, 28]
+ *   ])
+ *   .setValueFields([0, 1])
+ *   .setTitle('Distribution')
+ *   .build();
+ * await fDocument.insertChart(chartInfo);
+ * ```
+ *
+ * @example Slide
+ * ```ts
+ * const fPresentation = univerAPI.getActivePresentation();
+ * const fSlide = fPresentation.getSlideByIndex(0);
+ * const chartInfo = fSlide
+ *   .newChart(univerAPI.Enum.ChartTypeString.Boxplot)
+ *   .setSource([
+ *     ['Group A', 'Group B'],
+ *     [12, 18],
+ *     [15, 20],
+ *     [19, 24],
+ *     [22, 28]
+ *   ])
+ *   .setValueFields([0, 1])
+ *   .setTitle('Distribution')
+ *   .build();
+ * await fSlide.insertChart(chartInfo);
+ * ```
+ *
+ * @example Board
+ * ```ts
+ * const fBoard = univerAPI.getActiveBoard();
+ * const chartInfo = fBoard
+ *   .newChart(univerAPI.Enum.ChartTypeString.Boxplot)
+ *   .setSource([
+ *     ['Group A', 'Group B'],
+ *     [12, 18],
+ *     [15, 20],
+ *     [19, 24],
+ *     [22, 28]
+ *   ])
+ *   .setValueFields([0, 1])
+ *   .setTitle('Distribution')
+ *   .build();
+ * await fBoard.insertChart(chartInfo);
+ * ```
+ */
+export declare class FBoxplotChartBuilder<TSource = never[], TDataSource = TSource, TInfo extends IChartInfo<TDataSource> = IChartInfo<TDataSource>> extends FCartesianChartBuilder<Omit<IChartSolidSeriesPatch, 'selector'>, IChartSolidSeriesStyleSpec, TSource, TDataSource, TInfo> {
 }

package/lib/types/facade/builders/f-bubble-chart-builder.d.ts

@@ -1,6 +1,63 @@
-import type { IChartBubbleMappingSpec, IChartSolidSeriesPatch, IChartSolidSeriesStyleSpec } from '@univerjs-pro/engine-chart';
+import type { IChartBubbleMappingSpec, IChartInfo, IChartSolidSeriesPatch, IChartSolidSeriesStyleSpec } from '@univerjs-pro/engine-chart';
 import { FCartesianChartBuilder } from '../f-cartesian-chart-builder';
-export declare class FBubbleChartBuilder extends FCartesianChartBuilder<Omit<IChartSolidSeriesPatch, 'selector'>, IChartSolidSeriesStyleSpec> {
+/**
+ * Fluent, type-specific Builder for Bubble Charts.
+ *
+ * The data source is an observation table: each row represents one bubble. X and Y
+ * must map to numeric fields. Size is an optional numeric field; label and series are
+ * optional categorical fields for point labels and grouping. All mapped fields are
+ * aligned by row, so their source vectors must have the same length.
+ *
+ * @example Sheet
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+ * const chartInfo = fWorksheet
+ *   .newChart(univerAPI.Enum.ChartTypeString.Bubble)
+ *   .setSource({
+ *     range: 'A1:E8',
+ *     orientation: univerAPI.Enum.ChartSourceOrientation.Columns,
+ *   })
+ *   .setBubbleMapping({ xIndex: 0, yIndex: 1, sizeIndex: 2, labelIndex: 3, seriesIndex: 4 })
+ *   .build();
+ * await fWorksheet.insertChart(chartInfo);
+ * ```
+ *
+ * @example Doc
+ * ```ts
+ * const fDocument = univerAPI.getActiveDocument();
+ * const chartInfo = fDocument
+ *   .newChart(univerAPI.Enum.ChartTypeString.Bubble)
+ *   .setSource([['X', 'Y', 'Size'], [10, 20, 5], [18, 32, 9]])
+ *   .setBubbleMapping({ xIndex: 0, yIndex: 1, sizeIndex: 2 })
+ *   .build();
+ * await fDocument.insertChart(chartInfo);
+ * ```
+ *
+ * @example Slide
+ * ```ts
+ * const fPresentation = univerAPI.getActivePresentation();
+ * const fSlide = fPresentation.getSlideByIndex(0);
+ * const chartInfo = fSlide
+ *   .newChart(univerAPI.Enum.ChartTypeString.Bubble)
+ *   .setSource([['X', 'Y', 'Size'], [10, 20, 5], [18, 32, 9]])
+ *   .setBubbleMapping({ xIndex: 0, yIndex: 1, sizeIndex: 2 })
+ *   .build();
+ * await fSlide.insertChart(chartInfo);
+ * ```
+ *
+ * @example Board
+ * ```ts
+ * const fBoard = univerAPI.getActiveBoard();
+ * const chartInfo = fBoard
+ *   .newChart(univerAPI.Enum.ChartTypeString.Bubble)
+ *   .setSource([['X', 'Y', 'Size'], [10, 20, 5], [18, 32, 9]])
+ *   .setBubbleMapping({ xIndex: 0, yIndex: 1, sizeIndex: 2 })
+ *   .build();
+ * await fBoard.insertChart(chartInfo);
+ * ```
+ */
+export declare class FBubbleChartBuilder<TSource = never[], TDataSource = TSource, TInfo extends IChartInfo<TDataSource> = IChartInfo<TDataSource>> extends FCartesianChartBuilder<Omit<IChartSolidSeriesPatch, 'selector'>, IChartSolidSeriesStyleSpec, TSource, TDataSource, TInfo> {
     /**
      * Sets the bubble mapping configuration and returns this builder for chaining.
      *
@@ -10,8 +67,6 @@ export declare class FBubbleChartBuilder extends FCartesianChartBuilder<Omit<ICh
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Bubble);
      * builder.setBubbleMapping({ xIndex: 0, yIndex: 1, sizeIndex: 2 });
      * ```
      */
@@ -24,8 +79,6 @@ export declare class FBubbleChartBuilder extends FCartesianChartBuilder<Omit<ICh
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Bubble);
      * builder.clearBubbleMapping();
      * ```
      */

package/lib/types/facade/builders/f-candlestick-chart-builder.d.ts

@@ -1,24 +1,97 @@
-import type { IChartCandlestickMappingSpec, IChartCandlestickStateStyleSpec } from '@univerjs-pro/engine-chart';
+import type { IChartCandlestickMappingSpec, IChartCandlestickStateStyleSpec, IChartInfo } from '@univerjs-pro/engine-chart';
 import { FAxisChartBuilder } from '../f-axis-chart-builder';
-/** Fluent semantic builder for a single OHLC Candlestick series. */
-export declare class FCandlestickChartBuilder extends FAxisChartBuilder {
+/**
+ * Fluent semantic builder for a single OHLC Candlestick series.
+ *
+ * Each source row represents one trading interval. Map one category field and four
+ * distinct numeric fields in Open, High, Low, Close order. A row with any missing or
+ * non-finite OHLC value renders as a gap rather than a partial candle.
+ *
+ * @example Sheet
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+ * const chartInfo = fWorksheet
+ *   .newChart(univerAPI.Enum.ChartTypeString.Candlestick)
+ *   .setSource({
+ *     range: 'A1:E8',
+ *     orientation: univerAPI.Enum.ChartSourceOrientation.Columns,
+ *   })
+ *   .setCategoryField(0)
+ *   .setCandlestickFields({ openIndex: 1, highIndex: 2, lowIndex: 3, closeIndex: 4 })
+ *   .setRisingStyle({ color: '#0DA471', hollow: true })
+ *   .setFallingStyle({ color: '#F05252' })
+ *   .setDojiStyle({ color: '#8C8C8C', border: { width: 2 } })
+ *   .setCandleWidth(18)
+ *   .build();
+ * await fWorksheet.insertChart(chartInfo);
+ * ```
+ *
+ * @example Doc
+ * ```ts
+ * const fDocument = univerAPI.getActiveDocument();
+ * const chartInfo = fDocument
+ *   .newChart(univerAPI.Enum.ChartTypeString.Candlestick)
+ *   .setSource([['Date', 'Open', 'High', 'Low', 'Close'], ['Mon', 100, 112, 96, 108], ['Tue', 108, 116, 102, 105]])
+ *   .setCategoryField(0)
+ *   .setCandlestickFields({ openIndex: 1, highIndex: 2, lowIndex: 3, closeIndex: 4 })
+ *   .setRisingStyle({ color: '#0DA471', hollow: true })
+ *   .setFallingStyle({ color: '#F05252' })
+ *   .setDojiStyle({ color: '#8C8C8C', border: { width: 2 } })
+ *   .setCandleWidth(18)
+ *   .build();
+ * await fDocument.insertChart(chartInfo);
+ * ```
+ *
+ * @example Slide
+ * ```ts
+ * const fPresentation = univerAPI.getActivePresentation();
+ * const fSlide = fPresentation.getSlideByIndex(0);
+ * const chartInfo = fSlide
+ *   .newChart(univerAPI.Enum.ChartTypeString.Candlestick)
+ *   .setSource([['Date', 'Open', 'High', 'Low', 'Close'], ['Mon', 100, 112, 96, 108], ['Tue', 108, 116, 102, 105]])
+ *   .setCategoryField(0)
+ *   .setCandlestickFields({ openIndex: 1, highIndex: 2, lowIndex: 3, closeIndex: 4 })
+ *   .setRisingStyle({ color: '#0DA471', hollow: true })
+ *   .setFallingStyle({ color: '#F05252' })
+ *   .setDojiStyle({ color: '#8C8C8C', border: { width: 2 } })
+ *   .setCandleWidth(18)
+ *   .build();
+ * await fSlide.insertChart(chartInfo);
+ * ```
+ *
+ * @example Board
+ * ```ts
+ * const fBoard = univerAPI.getActiveBoard();
+ * const chartInfo = fBoard
+ *   .newChart(univerAPI.Enum.ChartTypeString.Candlestick)
+ *   .setSource([['Date', 'Open', 'High', 'Low', 'Close'], ['Mon', 100, 112, 96, 108], ['Tue', 108, 116, 102, 105]])
+ *   .setCategoryField(0)
+ *   .setCandlestickFields({ openIndex: 1, highIndex: 2, lowIndex: 3, closeIndex: 4 })
+ *   .setRisingStyle({ color: '#0DA471', hollow: true })
+ *   .setFallingStyle({ color: '#F05252' })
+ *   .setDojiStyle({ color: '#8C8C8C', border: { width: 2 } })
+ *   .setCandleWidth(18)
+ *   .build();
+ * await fBoard.insertChart(chartInfo);
+ * ```
+ */
+export declare class FCandlestickChartBuilder<TSource = never[], TDataSource = TSource, TInfo extends IChartInfo<TDataSource> = IChartInfo<TDataSource>> extends FAxisChartBuilder<TSource, TDataSource, TInfo> {
     /**
      * Replaces Open, High, Low, and Close source fields atomically.
      *
      * Category remains configured through `setCategoryField()`. Every supplied index must be a
      * unique non-negative integer. Read the pending or persisted value with
-     * `builder.describe().mapping?.candlestick`.
+     * `builder.build().config.mapping?.candlestick`.
      *
      * @param fields Required semantic OHLC source field indexes.
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create()
-     *   .setType(univerAPI.Enum.ChartTypeString.Candlestick)
+     * builder
      *   .setCategoryField(0)
      *   .setCandlestickFields({ openIndex: 1, highIndex: 2, lowIndex: 3, closeIndex: 4 });
-     * const mapping = builder.describe().mapping?.candlestick;
+     * const mapping = builder.build().config.mapping?.candlestick;
      * ```
      */
     setCandlestickFields(fields: IChartCandlestickMappingSpec): this;
@@ -28,10 +101,7 @@ export declare class FCandlestickChartBuilder extends FAxisChartBuilder {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * worksheet.charts.create()
-     *   .setType(univerAPI.Enum.ChartTypeString.Candlestick)
-     *   .clearCandlestickFields();
+     * builder.clearCandlestickFields();
      * ```
      */
     clearCandlestickFields(): this;
@@ -42,9 +112,7 @@ export declare class FCandlestickChartBuilder extends FAxisChartBuilder {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Candlestick)
-     *   .setRisingStyle({ color: '#0DA471', hollow: true });
+     * builder.setRisingStyle({ color: '#0DA471', hollow: true });
      * ```
      */
     setRisingStyle(style: IChartCandlestickStateStyleSpec): this;
@@ -54,8 +122,7 @@ export declare class FCandlestickChartBuilder extends FAxisChartBuilder {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Candlestick).clearRisingStyle();
+     * builder.clearRisingStyle();
      * ```
      */
     clearRisingStyle(): this;
@@ -66,9 +133,7 @@ export declare class FCandlestickChartBuilder extends FAxisChartBuilder {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Candlestick)
-     *   .setFallingStyle({ color: '#F05252' });
+     * builder.setFallingStyle({ color: '#F05252' });
      * ```
      */
     setFallingStyle(style: IChartCandlestickStateStyleSpec): this;
@@ -78,8 +143,7 @@ export declare class FCandlestickChartBuilder extends FAxisChartBuilder {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Candlestick).clearFallingStyle();
+     * builder.clearFallingStyle();
      * ```
      */
     clearFallingStyle(): this;
@@ -90,9 +154,7 @@ export declare class FCandlestickChartBuilder extends FAxisChartBuilder {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Candlestick)
-     *   .setDojiStyle({ color: '#8C8C8C', border: { width: 2 } });
+     * builder.setDojiStyle({ color: '#8C8C8C', border: { width: 2 } });
      * ```
      */
     setDojiStyle(style: IChartCandlestickStateStyleSpec): this;
@@ -102,8 +164,7 @@ export declare class FCandlestickChartBuilder extends FAxisChartBuilder {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Candlestick).clearDojiStyle();
+     * builder.clearDojiStyle();
      * ```
      */
     clearDojiStyle(): this;
@@ -114,8 +175,7 @@ export declare class FCandlestickChartBuilder extends FAxisChartBuilder {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Candlestick).setCandleWidth(18);
+     * builder.setCandleWidth(18);
      * ```
      */
     setCandleWidth(width: number): this;
@@ -125,8 +185,7 @@ export declare class FCandlestickChartBuilder extends FAxisChartBuilder {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Candlestick).resetCandleWidth();
+     * builder.resetCandleWidth();
      * ```
      */
     resetCandleWidth(): this;