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

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

@@ -1,6 +1,126 @@
-import type { IChartPieLabelSpec, IChartSliceStyleSpec } from '@univerjs-pro/engine-chart';
+import type { DeepNullish, IChartInfo, IChartPieCompositeSpec, IChartPieLabelSpec, IChartSliceStyleSpec } from '@univerjs-pro/engine-chart';
 import { FChartBuilderBase } from '../f-chart-builder-base';
-export declare class FPieChartBuilder extends FChartBuilderBase {
+/**
+ * Fluent, type-specific Builder for Pie and Donut Charts.
+ *
+ * For a conventional category/value source, select the slice-label field with
+ * `setCategoryField()` and select its numeric value field with `setValueFields([index])`.
+ * Field indexes are zero-based in the normalized data source. A value field is required;
+ * without an explicit category field, slices fall back to generated ordinal labels.
+ * Explicit mapping is recommended for ambiguous sources, especially Sheet ranges containing
+ * only numeric values, because automatic inference cannot determine the intended label column.
+ *
+ * A regular Pie uses the first selected value series. This example intentionally selects one
+ * value field so each source row becomes one labeled slice. Negative values render by absolute
+ * magnitude and retain a negative label and tooltip.
+ *
+ * @example Sheet
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+ * const chartInfo = fWorksheet
+ *   .newChart(univerAPI.Enum.ChartTypeString.Donut)
+ *   .setSource('A1:B8')
+ *   .setCategoryField(0)
+ *   .setValueFields([1])
+ *   .setDoughnutHole(0.4)
+ *   .setSliceStyle(0, { color: '#2563eb', fillOpacity: 0.8 })
+ *   .setExplosion(0.01)
+ *   .setSliceBorderColor('#ffffff')
+ *   .setPaddingAngleEnabled(true)
+ *   .setLabelLineVisible(true)
+ *   .setValueScale(1)
+ *   .setPieLabel({ visible: true, position: univerAPI.Enum.ChartPieLabelPosition.Outside })
+ *   .build();
+ * await fWorksheet.insertChart(chartInfo);
+ * ```
+ *
+ * @example Doc
+ * ```ts
+ * const fDocument = univerAPI.getActiveDocument();
+ * const chartInfo = fDocument
+ *   .newChart(univerAPI.Enum.ChartTypeString.Donut)
+ *   .setSource([['Channel', 'Sales'], ['Online', 180], ['Retail', 120]])
+ *   .setCategoryField(0)
+ *   .setValueFields([1])
+ *   .setDoughnutHole(0.4)
+ *   .setSliceStyle(0, { color: '#2563eb', fillOpacity: 0.8 })
+ *   .setExplosion(0.01)
+ *   .setSliceBorderColor('#ffffff')
+ *   .setPaddingAngleEnabled(true)
+ *   .setLabelLineVisible(true)
+ *   .setValueScale(1)
+ *   .setPieLabel({ visible: true, position: univerAPI.Enum.ChartPieLabelPosition.Outside })
+ *   .build();
+ * await fDocument.insertChart(chartInfo);
+ * ```
+ *
+ * @example Slide
+ * ```ts
+ * const fPresentation = univerAPI.getActivePresentation();
+ * const fSlide = fPresentation.getSlideByIndex(0);
+ * const chartInfo = fSlide
+ *   .newChart(univerAPI.Enum.ChartTypeString.Donut)
+ *   .setSource([['Channel', 'Sales'], ['Online', 180], ['Retail', 120]])
+ *   .setCategoryField(0)
+ *   .setValueFields([1])
+ *   .setDoughnutHole(0.4)
+ *   .setSliceStyle(0, { color: '#2563eb', fillOpacity: 0.8 })
+ *   .setExplosion(0.01)
+ *   .setSliceBorderColor('#ffffff')
+ *   .setPaddingAngleEnabled(true)
+ *   .setLabelLineVisible(true)
+ *   .setValueScale(1)
+ *   .setPieLabel({ visible: true, position: univerAPI.Enum.ChartPieLabelPosition.Outside })
+ *   .build();
+ * await fSlide.insertChart(chartInfo);
+ * ```
+ *
+ * @example Board
+ * ```ts
+ * const fBoard = univerAPI.getActiveBoard();
+ * const chartInfo = fBoard
+ *   .newChart(univerAPI.Enum.ChartTypeString.Donut)
+ *   .setSource([['Channel', 'Sales'], ['Online', 180], ['Retail', 120]])
+ *   .setCategoryField(0)
+ *   .setValueFields([1])
+ *   .setDoughnutHole(0.4)
+ *   .setSliceStyle(0, { color: '#2563eb', fillOpacity: 0.8 })
+ *   .setExplosion(0.01)
+ *   .setSliceBorderColor('#ffffff')
+ *   .setPaddingAngleEnabled(true)
+ *   .setLabelLineVisible(true)
+ *   .setValueScale(1)
+ *   .setPieLabel({ visible: true, position: univerAPI.Enum.ChartPieLabelPosition.Outside })
+ *   .build();
+ * await fBoard.insertChart(chartInfo);
+ * ```
+ */
+export declare class FPieChartBuilder<TSource = never[], TDataSource = TSource, TInfo extends IChartInfo<TDataSource> = IChartInfo<TDataSource>> extends FChartBuilderBase<TSource, TDataSource, TInfo> {
+    /**
+     * Sets secondary-plot and composite layout options for a Pie Chart.
+     *
+     * @param value The composite Pie specification.
+     * @returns This Builder for chaining.
+     * @example
+     * ```ts
+     * builder.setPieComposite({
+     *   enabled: true,
+     *   secondaryPlot: { type: univerAPI.Enum.ChartPieSecondaryPlotType.Pie },
+     * });
+     * ```
+     */
+    setPieComposite(value: DeepNullish<IChartPieCompositeSpec>): this;
+    /**
+     * Clears composite Pie layout options.
+     *
+     * @returns This Builder for chaining.
+     * @example
+     * ```ts
+     * builder.clearPieComposite();
+     * ```
+     */
+    clearPieComposite(): this;
     /**
      * Sets the style for the materialized slice at `index`.
      *
@@ -13,8 +133,6 @@ export declare class FPieChartBuilder extends FChartBuilderBase {
      * ```ts
      * import { chartLinearGradient } from '@univerjs-pro/engine-chart';
      *
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Pie);
      * const color = chartLinearGradient({
      *     start: { x: 0, y: 0 },
      *     end: { x: 1, y: 1 },
@@ -36,8 +154,6 @@ export declare class FPieChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Pie);
      * builder.clearSliceStyle(0);
      * ```
      */
@@ -51,8 +167,6 @@ export declare class FPieChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Pie);
      * builder.setDoughnutHole(0.6);
      * ```
      */
@@ -65,24 +179,22 @@ export declare class FPieChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Pie);
      * builder.clearDoughnutHole();
      * ```
      */
     clearDoughnutHole(): this;
     /**
-     * Sets the explosion configuration and returns this builder for chaining.
+     * Sets the distance that every slice is offset from the Pie center.
      *
-     * This method executes synchronously.
+     * The value is a ratio of the Chart's shorter side, not a pixel distance. For example,
+     * `0.01` produces an offset of about 2.2 px in a 480 px square Chart. Large values can
+     * move every slice outside the visible plot area.
      *
-     * @param value The semantic value to record.
+     * @param value Non-negative explosion ratio.
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Pie);
-     * builder.setExplosion(8);
+     * builder.setExplosion(0.01);
      * ```
      */
     setExplosion(value: number): this;
@@ -94,8 +206,6 @@ export declare class FPieChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Pie);
      * builder.resetExplosion();
      * ```
      */
@@ -109,8 +219,6 @@ export declare class FPieChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Pie);
      * builder.setSliceBorderColor('#ffffff');
      * ```
      */
@@ -123,8 +231,6 @@ export declare class FPieChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Pie);
      * builder.clearSliceBorderColor();
      * ```
      */
@@ -138,8 +244,6 @@ export declare class FPieChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Pie);
      * builder.setPaddingAngleEnabled(true);
      * ```
      */
@@ -152,8 +256,7 @@ export declare class FPieChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Pie).resetPaddingAngleEnabled();
+     * builder.resetPaddingAngleEnabled();
      * ```
      */
     resetPaddingAngleEnabled(): this;
@@ -166,8 +269,6 @@ export declare class FPieChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Pie);
      * builder.setHalfPie(true);
      * ```
      */
@@ -180,8 +281,7 @@ export declare class FPieChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Pie).resetHalfPie();
+     * builder.resetHalfPie();
      * ```
      */
     resetHalfPie(): this;
@@ -194,8 +294,6 @@ export declare class FPieChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Pie);
      * builder.setRosePie(true);
      * ```
      */
@@ -208,8 +306,7 @@ export declare class FPieChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Pie).resetRosePie();
+     * builder.resetRosePie();
      * ```
      */
     resetRosePie(): this;
@@ -222,8 +319,6 @@ export declare class FPieChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Pie);
      * builder.setLabelLineVisible(true);
      * ```
      */
@@ -236,8 +331,7 @@ export declare class FPieChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Pie).resetLabelLineVisible();
+     * builder.resetLabelLineVisible();
      * ```
      */
     resetLabelLineVisible(): this;
@@ -250,8 +344,6 @@ export declare class FPieChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Pie);
      * builder.setValueScale(1);
      * ```
      */
@@ -264,71 +356,10 @@ export declare class FPieChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Pie);
      * builder.resetValueScale();
      * ```
      */
     resetValueScale(): this;
-    /**
-     * Sets the value suffix configuration and returns this builder for chaining.
-     *
-     * This method executes synchronously.
-     *
-     * @param value The semantic value to record.
-     * @returns This builder for chaining.
-     * @example
-     * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Pie);
-     * builder.setValueSuffix('%');
-     * ```
-     */
-    setValueSuffix(value: string): this;
-    /**
-     * Clears the value suffix so labels append no custom suffix.
-     *
-     * This method executes synchronously.
-     *
-     * @returns This builder for chaining.
-     * @example
-     * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Pie);
-     * builder.clearValueSuffix();
-     * ```
-     */
-    clearValueSuffix(): this;
-    /**
-     * Sets the decimal places configuration and returns this builder for chaining.
-     *
-     * This method executes synchronously.
-     *
-     * @param value The semantic value to record.
-     * @returns This builder for chaining.
-     * @example
-     * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Pie);
-     * builder.setDecimalPlaces(2);
-     * ```
-     */
-    setDecimalPlaces(value: number): this;
-    /**
-     * Removes the explicit decimal-precision override. When a value scale or suffix still requires
-     * the custom formatter, that formatter falls back to one decimal place.
-     *
-     * This method executes synchronously.
-     *
-     * @returns This builder for chaining.
-     * @example
-     * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Pie);
-     * builder.resetDecimalPlaces();
-     * ```
-     */
-    resetDecimalPlaces(): this;
     /**
      * Sets the pie label configuration and returns this builder for chaining.
      *
@@ -341,12 +372,10 @@ export declare class FPieChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Pie);
-     * builder.setPieLabel({ visible: true, position: univerAPI.Enum.PieLabelPosition.Outside });
+     * builder.setPieLabel({ visible: true, position: univerAPI.Enum.ChartPieLabelPosition.Outside });
      * ```
      */
-    setPieLabel(value: IChartPieLabelSpec): this;
+    setPieLabel(value: DeepNullish<IChartPieLabelSpec>): this;
     /**
      * Clears the pie label override. Labels fall back to visible outside labels containing category,
      * value, and percentage with the active chart font and theme colors.
@@ -356,8 +385,6 @@ export declare class FPieChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Pie);
      * builder.clearPieLabel();
      * ```
      */

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

@@ -1,6 +1,67 @@
-import type { RadarShape } from '@univerjs-pro/engine-chart';
+import type { IChartInfo, RadarShape } from '@univerjs-pro/engine-chart';
 import { FChartBuilderBase } from '../f-chart-builder-base';
-export declare class FRadarChartBuilder extends FChartBuilderBase {
+/**
+ * Fluent, type-specific Builder for Radar Charts.
+ *
+ * @example Sheet
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+ * const chartInfo = fWorksheet
+ *   .newChart(univerAPI.Enum.ChartTypeString.Radar)
+ *   .setSource('A1:D8')
+ *   .setCategoryField(0)
+ *   .setValueFields([1, 2, 3])
+ *   .setShape(univerAPI.Enum.ChartRadarShape.Circle)
+ *   .setFill(true)
+ *   .build();
+ * await fWorksheet.insertChart(chartInfo);
+ * ```
+ *
+ * @example Doc
+ * ```ts
+ * const fDocument = univerAPI.getActiveDocument();
+ * const chartInfo = fDocument
+ *   .newChart(univerAPI.Enum.ChartTypeString.Radar)
+ *   .setSource([['Metric', 'Product A', 'Product B'], ['Speed', 80, 72], ['Quality', 90, 84]])
+ *   .setCategoryField(0)
+ *   .setValueFields([1, 2])
+ *   .setShape(univerAPI.Enum.ChartRadarShape.Circle)
+ *   .setFill(true)
+ *   .build();
+ * await fDocument.insertChart(chartInfo);
+ * ```
+ *
+ * @example Slide
+ * ```ts
+ * const fPresentation = univerAPI.getActivePresentation();
+ * const fSlide = fPresentation.getSlideByIndex(0);
+ * const chartInfo = fSlide
+ *   .newChart(univerAPI.Enum.ChartTypeString.Radar)
+ *   .setSource([['Metric', 'Product A', 'Product B'], ['Speed', 80, 72], ['Quality', 90, 84]])
+ *   .setCategoryField(0)
+ *   .setValueFields([1, 2])
+ *   .setShape(univerAPI.Enum.ChartRadarShape.Circle)
+ *   .setFill(true)
+ *   .build();
+ * await fSlide.insertChart(chartInfo);
+ * ```
+ *
+ * @example Board
+ * ```ts
+ * const fBoard = univerAPI.getActiveBoard();
+ * const chartInfo = fBoard
+ *   .newChart(univerAPI.Enum.ChartTypeString.Radar)
+ *   .setSource([['Metric', 'Product A', 'Product B'], ['Speed', 80, 72], ['Quality', 90, 84]])
+ *   .setCategoryField(0)
+ *   .setValueFields([1, 2])
+ *   .setShape(univerAPI.Enum.ChartRadarShape.Circle)
+ *   .setFill(true)
+ *   .build();
+ * await fBoard.insertChart(chartInfo);
+ * ```
+ */
+export declare class FRadarChartBuilder<TSource = never[], TDataSource = TSource, TInfo extends IChartInfo<TDataSource> = IChartInfo<TDataSource>> extends FChartBuilderBase<TSource, TDataSource, TInfo> {
     /**
      * Sets the shape configuration and returns this builder for chaining.
      *
@@ -10,9 +71,7 @@ export declare class FRadarChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Radar);
-     * builder.setShape(univerAPI.Enum.RadarShape.Polygon);
+     * builder.setShape(univerAPI.Enum.ChartRadarShape.Polygon);
      * ```
      */
     setShape(value: RadarShape): this;
@@ -24,8 +83,6 @@ export declare class FRadarChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Radar);
      * builder.resetShape();
      * ```
      */
@@ -39,8 +96,6 @@ export declare class FRadarChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Radar);
      * builder.setFill(true);
      * ```
      */
@@ -53,8 +108,6 @@ export declare class FRadarChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Radar);
      * builder.resetFill();
      * ```
      */