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

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;

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

@@ -1,4 +1,4 @@
-import type { IChartChordEmphasisSpec, IChartChordLabelSpec, IChartChordLayoutSpec, IChartChordMappingSpec, IChartChordNodeStyleSpec, IChartChordRibbonStyleSpec } from '@univerjs-pro/engine-chart';
+import type { IChartChordEmphasisSpec, IChartChordLabelSpec, IChartChordLayoutSpec, IChartChordMappingSpec, IChartChordNodeStyleSpec, IChartChordRibbonStyleSpec, IChartInfo } from '@univerjs-pro/engine-chart';
 import { FChartBuilderBase } from '../f-chart-builder-base';
 /**
  * Fluent semantic builder for an undirected Source/Target/optional-Value edge list.
@@ -8,23 +8,195 @@ import { FChartBuilderBase } from '../f-chart-builder-base';
  * non-positive/non-finite mapped weights are skipped without coercion. Aggregate
  * values are formatted after summing. Defaults are renderer-owned and require the
  * native ECharts 6.1 Chord series; no renderer nodes, links, or layout are persisted.
+ *
+ * @example Sheet
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+ * const chartInfo = fWorksheet
+ *   .newChart(univerAPI.Enum.ChartTypeString.Chord)
+ *   .setSource('A1:C8')
+ *   .setChordMapping({ sourceIndex: 0, targetIndex: 1, valueIndex: 2 })
+ *   .setChordLayout({ startAngle: 90, clockwise: true, innerRadiusRatio: 0.4, outerRadiusRatio: 0.8 })
+ *   .setChordNode({ color: '#2563eb', opacity: 0.8 })
+ *   .setChordLabel({ visible: true, position: univerAPI.Enum.ChartChordLabelPosition.Outside, color: '#334155' })
+ *   .setChordRibbon({ color: univerAPI.Enum.ChartChordRibbonColorMode.Gradient, opacity: 0.6 })
+ *   .setChordEmphasis({ focus: univerAPI.Enum.ChartChordFocusMode.Adjacency })
+ *   .build();
+ * await fWorksheet.insertChart(chartInfo);
+ * ```
+ *
+ * @example Doc
+ * ```ts
+ * const fDocument = univerAPI.getActiveDocument();
+ * const chartInfo = fDocument
+ *   .newChart(univerAPI.Enum.ChartTypeString.Chord)
+ *   .setSource([['Source', 'Target', 'Value'], ['A', 'B', 5], ['A', 'C', 3], ['B', 'C', 2]])
+ *   .setChordMapping({ sourceIndex: 0, targetIndex: 1, valueIndex: 2 })
+ *   .setChordLayout({ startAngle: 90, clockwise: true, innerRadiusRatio: 0.4, outerRadiusRatio: 0.8 })
+ *   .setChordNode({ color: '#2563eb', opacity: 0.8 })
+ *   .setChordLabel({ visible: true, position: univerAPI.Enum.ChartChordLabelPosition.Outside, color: '#334155' })
+ *   .setChordRibbon({ color: univerAPI.Enum.ChartChordRibbonColorMode.Gradient, opacity: 0.6 })
+ *   .setChordEmphasis({ focus: univerAPI.Enum.ChartChordFocusMode.Adjacency })
+ *   .build();
+ * await fDocument.insertChart(chartInfo);
+ * ```
+ *
+ * @example Slide
+ * ```ts
+ * const fPresentation = univerAPI.getActivePresentation();
+ * const fSlide = fPresentation.getSlideByIndex(0);
+ * const chartInfo = fSlide
+ *   .newChart(univerAPI.Enum.ChartTypeString.Chord)
+ *   .setSource([['Source', 'Target', 'Value'], ['A', 'B', 5], ['A', 'C', 3], ['B', 'C', 2]])
+ *   .setChordMapping({ sourceIndex: 0, targetIndex: 1, valueIndex: 2 })
+ *   .setChordLayout({ startAngle: 90, clockwise: true, innerRadiusRatio: 0.4, outerRadiusRatio: 0.8 })
+ *   .setChordNode({ color: '#2563eb', opacity: 0.8 })
+ *   .setChordLabel({ visible: true, position: univerAPI.Enum.ChartChordLabelPosition.Outside, color: '#334155' })
+ *   .setChordRibbon({ color: univerAPI.Enum.ChartChordRibbonColorMode.Gradient, opacity: 0.6 })
+ *   .setChordEmphasis({ focus: univerAPI.Enum.ChartChordFocusMode.Adjacency })
+ *   .build();
+ * await fSlide.insertChart(chartInfo);
+ * ```
+ *
+ * @example Board
+ * ```ts
+ * const fBoard = univerAPI.getActiveBoard();
+ * const chartInfo = fBoard
+ *   .newChart(univerAPI.Enum.ChartTypeString.Chord)
+ *   .setSource([['Source', 'Target', 'Value'], ['A', 'B', 5], ['A', 'C', 3], ['B', 'C', 2]])
+ *   .setChordMapping({ sourceIndex: 0, targetIndex: 1, valueIndex: 2 })
+ *   .setChordLayout({ startAngle: 90, clockwise: true, innerRadiusRatio: 0.4, outerRadiusRatio: 0.8 })
+ *   .setChordNode({ color: '#2563eb', opacity: 0.8 })
+ *   .setChordLabel({ visible: true, position: univerAPI.Enum.ChartChordLabelPosition.Outside, color: '#334155' })
+ *   .setChordRibbon({ color: univerAPI.Enum.ChartChordRibbonColorMode.Gradient, opacity: 0.6 })
+ *   .setChordEmphasis({ focus: univerAPI.Enum.ChartChordFocusMode.Adjacency })
+ *   .build();
+ * await fBoard.insertChart(chartInfo);
+ * ```
  */
-export declare class FChordChartBuilder extends FChartBuilderBase {
+export declare class FChordChartBuilder<TSource = never[], TDataSource = TSource, TInfo extends IChartInfo<TDataSource> = IChartInfo<TDataSource>> extends FChartBuilderBase<TSource, TDataSource, TInfo> {
+    /**
+     * Sets the Source, Target, and optional Value field indexes for Chord edges.
+     *
+     * @param value Zero-based field indexes for each edge component.
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * builder.setChordMapping({ sourceIndex: 0, targetIndex: 1, valueIndex: 2 });
+     * ```
+     */
     setChordMapping(value: IChartChordMappingSpec): this;
-    getChordMapping(): IChartChordMappingSpec | undefined;
+    /**
+     * Sets the Chord radius, rotation, and spacing layout.
+     *
+     * @param value Chord layout settings.
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * builder.setChordLayout({ startAngle: 90, clockwise: true });
+     * ```
+     */
     setChordLayout(value: IChartChordLayoutSpec): this;
+    /**
+     * Resets the Chord layout to renderer defaults.
+     *
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * builder.resetChordLayout();
+     * ```
+     */
     resetChordLayout(): this;
-    getChordLayout(): IChartChordLayoutSpec | undefined;
+    /**
+     * Sets Chart-wide Chord node styling.
+     *
+     * @param value Chord node appearance settings.
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * builder.setChordNode({ color: '#2563eb', opacity: 0.8 });
+     * ```
+     */
     setChordNode(value: IChartChordNodeStyleSpec): this;
+    /**
+     * Resets Chord node styling to renderer defaults.
+     *
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * builder.resetChordNode();
+     * ```
+     */
     resetChordNode(): this;
-    getChordNode(): IChartChordNodeStyleSpec | undefined;
+    /**
+     * Sets Chord node-label visibility, position, and styling.
+     *
+     * @param value Chord label settings.
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * builder.setChordLabel({
+     *   visible: true,
+     *   position: univerAPI.Enum.ChartChordLabelPosition.Outside,
+     *   color: '#334155',
+     * });
+     * ```
+     */
     setChordLabel(value: IChartChordLabelSpec): this;
+    /**
+     * Resets Chord labels to renderer defaults.
+     *
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * builder.resetChordLabel();
+     * ```
+     */
     resetChordLabel(): this;
-    getChordLabel(): IChartChordLabelSpec | undefined;
+    /**
+     * Sets Chord ribbon color, opacity, and border styling.
+     *
+     * @param value Chord ribbon appearance settings.
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * builder.setChordRibbon({
+     *   color: univerAPI.Enum.ChartChordRibbonColorMode.Gradient,
+     *   opacity: 0.6,
+     * });
+     * ```
+     */
     setChordRibbon(value: IChartChordRibbonStyleSpec): this;
+    /**
+     * Resets Chord ribbon styling to renderer defaults.
+     *
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * builder.resetChordRibbon();
+     * ```
+     */
     resetChordRibbon(): this;
-    getChordRibbon(): IChartChordRibbonStyleSpec | undefined;
+    /**
+     * Sets hover emphasis and focus behavior.
+     *
+     * @param value Chord emphasis settings.
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * builder.setChordEmphasis({ focus: univerAPI.Enum.ChartChordFocusMode.Adjacency });
+     * ```
+     */
     setChordEmphasis(value: IChartChordEmphasisSpec): this;
+    /**
+     * Resets Chord emphasis behavior to renderer defaults.
+     *
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * builder.resetChordEmphasis();
+     * ```
+     */
     resetChordEmphasis(): this;
-    getChordEmphasis(): IChartChordEmphasisSpec | undefined;
 }

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

@@ -1,6 +1,59 @@
-import type { ChartPublicSeriesSelector, ChartSeriesAxis, ChartSeriesTypeString } from '@univerjs-pro/engine-chart';
+import type { ChartPublicSeriesSelector, ChartSeriesAxis, ChartSeriesTypeString, IChartInfo, IChartSeriesPatch, IChartSeriesStyleSpec } from '@univerjs-pro/engine-chart';
 import { FCartesianChartBuilder } from '../f-cartesian-chart-builder';
-export declare class FCombinationChartBuilder extends FCartesianChartBuilder {
+/**
+ * Fluent, type-specific Builder for mixed Column, Line, and Area Combination Charts.
+ *
+ * @example Sheet
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+ * const chartInfo = fWorksheet
+ *   .newChart(univerAPI.Enum.ChartTypeString.Combination)
+ *   .setSource('A1:D8')
+ *   .setSeriesType(0, univerAPI.Enum.ChartSeriesTypeString.Line)
+ *   .setSeriesAxis(0, univerAPI.Enum.ChartSeriesAxis.Right)
+ *   .build();
+ * await fWorksheet.insertChart(chartInfo);
+ * ```
+ *
+ * @example Doc
+ * ```ts
+ * const fDocument = univerAPI.getActiveDocument();
+ * const chartInfo = fDocument
+ *   .newChart(univerAPI.Enum.ChartTypeString.Combination)
+ *   .setSource([['Month', 'Sales', 'Profit'], ['Jan', 120, 24], ['Feb', 180, 38]])
+ *   .setSeriesType(0, univerAPI.Enum.ChartSeriesTypeString.Line)
+ *   .setSeriesAxis(0, univerAPI.Enum.ChartSeriesAxis.Right)
+ *   .build();
+ * await fDocument.insertChart(chartInfo);
+ * ```
+ *
+ * @example Slide
+ * ```ts
+ * const fPresentation = univerAPI.getActivePresentation();
+ * const fSlide = fPresentation.getSlideByIndex(0);
+ * const chartInfo = fSlide
+ *   .newChart(univerAPI.Enum.ChartTypeString.Combination)
+ *   .setSource([['Month', 'Sales', 'Profit'], ['Jan', 120, 24], ['Feb', 180, 38]])
+ *   .setSeriesType(0, univerAPI.Enum.ChartSeriesTypeString.Line)
+ *   .setSeriesAxis(0, univerAPI.Enum.ChartSeriesAxis.Right)
+ *   .build();
+ * await fSlide.insertChart(chartInfo);
+ * ```
+ *
+ * @example Board
+ * ```ts
+ * const fBoard = univerAPI.getActiveBoard();
+ * const chartInfo = fBoard
+ *   .newChart(univerAPI.Enum.ChartTypeString.Combination)
+ *   .setSource([['Month', 'Sales', 'Profit'], ['Jan', 120, 24], ['Feb', 180, 38]])
+ *   .setSeriesType(0, univerAPI.Enum.ChartSeriesTypeString.Line)
+ *   .setSeriesAxis(0, univerAPI.Enum.ChartSeriesAxis.Right)
+ *   .build();
+ * await fBoard.insertChart(chartInfo);
+ * ```
+ */
+export declare class FCombinationChartBuilder<TSource = never[], TDataSource = TSource, TInfo extends IChartInfo<TDataSource> = IChartInfo<TDataSource>> extends FCartesianChartBuilder<Omit<IChartSeriesPatch, 'selector'>, IChartSeriesStyleSpec, TSource, TDataSource, TInfo> {
     /**
      * Sets the series type configuration and returns this builder for chaining.
      *
@@ -11,8 +64,6 @@ export declare class FCombinationChartBuilder extends FCartesianChartBuilder {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Combination);
      * builder.setSeriesType(0, univerAPI.Enum.ChartSeriesTypeString.Line);
      * ```
      */
@@ -26,8 +77,6 @@ export declare class FCombinationChartBuilder extends FCartesianChartBuilder {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Combination);
      * builder.resetSeriesType(0);
      * ```
      */
@@ -42,8 +91,6 @@ export declare class FCombinationChartBuilder extends FCartesianChartBuilder {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Combination);
      * builder.setSeriesAxis(0, univerAPI.Enum.ChartSeriesAxis.Right);
      * ```
      */
@@ -57,8 +104,6 @@ export declare class FCombinationChartBuilder extends FCartesianChartBuilder {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Combination);
      * builder.resetSeriesAxis(0);
      * ```
      */