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

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

@@ -1,8 +1,192 @@
-import type { ChartAggregationTarget, ChartAppearanceTarget, ChartBuilder, ChartDescription, ChartLegendSpec, ChartPendingConfig, ChartSubtitleSpec, ChartTitleSpec, IChartAggregationSpec, IChartAppearanceSpec, InvalidValueType } from '@univerjs-pro/engine-chart';
-import type { IChartBuilderTypeMap } from './chart-builder-type-map';
-import { FChartBase } from './f-chart-base';
-export declare class FChartBuilderBase<TBuilder extends ChartBuilder = ChartBuilder, TDescription extends ChartDescription = ChartDescription> extends FChartBase<TDescription, TBuilder> {
+import type { ChartAggregationTarget, ChartAppearanceTarget, ChartBuilder, ChartDescription, ChartLegendSpec, ChartPendingConfig, ChartSubtitleSpec, ChartTitleSpec, IChartAggregationSpec, IChartAppearanceSpec, IChartInfo, InvalidValueType } from '@univerjs-pro/engine-chart';
+import type { DeepReadonly } from '@univerjs/core';
+import type { IChartBuilderFacadeContext } from './internal/chart-builder-facade-context';
+/**
+ * Fluent base Builder for detached Chart information.
+ *
+ * Builder methods only modify the detached draft. Call {@link build} to create an
+ * insertable `IChartInfo`; use a live `FChart` facade to update an inserted Chart.
+ *
+ * @example Sheet
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+ * fWorksheet.getRange('A1:C5').setValues([
+ *   ['Quarter', 'Revenue', 'Cost'],
+ *   ['Q1', 120, 80],
+ *   ['Q2', 180, 110],
+ *   ['Q3', 160, 100],
+ *   ['Q4', 220, 130],
+ * ]);
+ * const chartInfo = fWorksheet
+ *   .newChart(univerAPI.Enum.ChartTypeString.Column)
+ *   .setSource({
+ *     range: 'A1:C5',
+ *     orientation: univerAPI.Enum.ChartSourceOrientation.Columns,
+ *   })
+ *   .setAbsolutePosition(120, 80)
+ *   .setSize(640, 360)
+ *   .setCategoryField(0)
+ *   .setValueFields([1, 2])
+ *   .setTitle('Quarterly performance')
+ *   .setSubtitle('FY 2026')
+ *   .setLegend({ position: univerAPI.Enum.ChartLegendPositionEnum.Bottom })
+ *   .setPalette(['#1677ff', '#52c41a'])
+ *   .setAppearance({
+ *     background: { color: 'transparent' },
+ *     border: { color: '#d9d9d9', width: 1 },
+ *   })
+ *   .setAutoGradientFill(true)
+ *   .setInvalidValueStrategy(univerAPI.Enum.ChartInvalidValueType.Zero)
+ *   .setAggregation({ aggregate: true })
+ *   .build();
+ * await fWorksheet.insertChart(chartInfo);
+ * ```
+ *
+ * @example Doc
+ * ```ts
+ * const fDocument = univerAPI.getActiveDocument();
+ * const chartInfo = fDocument
+ *   .newChart(univerAPI.Enum.ChartTypeString.Column)
+ *   .setSource([
+ *     ['Quarter', 'Revenue', 'Cost'],
+ *     ['Q1', 120, 80],
+ *     ['Q2', 180, 110],
+ *     ['Q3', 160, 100],
+ *     ['Q4', 220, 130],
+ *   ])
+ *   .setFloating()
+ *   .setAbsolutePosition(120, 80)
+ *   .setSize(640, 360)
+ *   .setCategoryField(0)
+ *   .setValueFields([1, 2])
+ *   .setTitle('Quarterly performance')
+ *   .setSubtitle('FY 2026')
+ *   .setLegend({ position: univerAPI.Enum.ChartLegendPositionEnum.Bottom })
+ *   .setPalette(['#1677ff', '#52c41a'])
+ *   .setAppearance({
+ *     background: { color: 'transparent' },
+ *     border: { color: '#d9d9d9', width: 1 },
+ *   })
+ *   .setAutoGradientFill(true)
+ *   .setInvalidValueStrategy(univerAPI.Enum.ChartInvalidValueType.Zero)
+ *   .setAggregation({ aggregate: 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.Column)
+ *   .setSource([
+ *     ['Quarter', 'Revenue', 'Cost'],
+ *     ['Q1', 120, 80],
+ *     ['Q2', 180, 110],
+ *     ['Q3', 160, 100],
+ *     ['Q4', 220, 130],
+ *   ])
+ *   .setAbsolutePosition(120, 80)
+ *   .setSize(640, 360)
+ *   .setCategoryField(0)
+ *   .setValueFields([1, 2])
+ *   .setTitle('Quarterly performance')
+ *   .setSubtitle('FY 2026')
+ *   .setLegend({ position: univerAPI.Enum.ChartLegendPositionEnum.Bottom })
+ *   .setPalette(['#1677ff', '#52c41a'])
+ *   .setAppearance({
+ *     background: { color: 'transparent' },
+ *     border: { color: '#d9d9d9', width: 1 },
+ *   })
+ *   .setAutoGradientFill(true)
+ *   .setInvalidValueStrategy(univerAPI.Enum.ChartInvalidValueType.Zero)
+ *   .setAggregation({ aggregate: true })
+ *   .build();
+ * await fSlide.insertChart(chartInfo);
+ * ```
+ *
+ * @example Board
+ * ```ts
+ * const fBoard = univerAPI.getActiveBoard();
+ * const chartInfo = fBoard
+ *   .newChart(univerAPI.Enum.ChartTypeString.Column)
+ *   .setSource([
+ *     ['Quarter', 'Revenue', 'Cost'],
+ *     ['Q1', 120, 80],
+ *     ['Q2', 180, 110],
+ *     ['Q3', 160, 100],
+ *     ['Q4', 220, 130],
+ *   ])
+ *   .setAbsolutePosition(120, 80)
+ *   .setSize(640, 360)
+ *   .setCategoryField(0)
+ *   .setValueFields([1, 2])
+ *   .setTitle('Quarterly performance')
+ *   .setSubtitle('FY 2026')
+ *   .setLegend({ position: univerAPI.Enum.ChartLegendPositionEnum.Bottom })
+ *   .setPalette(['#1677ff', '#52c41a'])
+ *   .setAppearance({
+ *     background: { color: 'transparent' },
+ *     border: { color: '#d9d9d9', width: 1 },
+ *   })
+ *   .setAutoGradientFill(true)
+ *   .setInvalidValueStrategy(univerAPI.Enum.ChartInvalidValueType.Zero)
+ *   .setAggregation({ aggregate: true })
+ *   .build();
+ * await fBoard.insertChart(chartInfo);
+ * ```
+ */
+export declare class FChartBuilderBase<TSource = never[], TDataSource = TSource, TInfo extends IChartInfo<TDataSource> = IChartInfo<TDataSource>, TBuilder extends ChartBuilder = ChartBuilder, TDescription extends ChartDescription = ChartDescription> {
+    protected readonly _context: IChartBuilderFacadeContext<TBuilder, TSource, TDataSource, TInfo>;
+    protected readonly _builder: TBuilder;
+    protected readonly _info: Partial<TInfo>;
+    constructor(_context: IChartBuilderFacadeContext<TBuilder, TSource, TDataSource, TInfo>);
+    /**
+     * Sets the host-specific data source stored in the built Chart information.
+     * @param {TSource} source The host-specific source, such as a Sheet range or a two-dimensional value array.
+     * @returns {this} This Builder for chaining.
+     * @example
+     * ```ts
+     * builder.setSource('A1:D8');
+     * ```
+     */
+    setSource(source: TSource): this;
+    /**
+     * Sets an absolute position in the target host.
+     * @param {number} x The horizontal host coordinate.
+     * @param {number} y The vertical host coordinate.
+     * @returns {this} This Builder for chaining.
+     * @example
+     * ```ts
+     * builder.setAbsolutePosition(120, 80);
+     * ```
+     */
+    setAbsolutePosition(x: number, y: number): this;
+    /**
+     * Sets the Chart size in the target host.
+     * @param {number} width The width in host coordinates.
+     * @param {number} height The height in host coordinates.
+     * @returns {this} This Builder for chaining.
+     * @example
+     * ```ts
+     * builder.setSize(640, 360);
+     * ```
+     */
+    setSize(width: number, height: number): this;
+    /**
+     * Builds a detached Chart information snapshot without mutating a host.
+     * @returns {TInfo} A deep-cloned, insertable Chart information object.
+     * @throws {Error} If a new Chart Builder has no data source.
+     * @example
+     * ```ts
+     * const chartInfo = builder.build();
+     * ```
+     */
+    build(): TInfo;
     protected _record(patch: ChartPendingConfig): this;
+    protected _describe(): DeepReadonly<TDescription>;
     /**
      * Sets the title configuration and returns this builder for chaining.
      *
@@ -12,8 +196,6 @@ export declare class FChartBuilderBase<TBuilder extends ChartBuilder = ChartBuil
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create();
      * builder.setTitle({ text: 'Quarterly sales' });
      * ```
      */
@@ -26,8 +208,6 @@ export declare class FChartBuilderBase<TBuilder extends ChartBuilder = ChartBuil
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create();
      * builder.clearTitle();
      * ```
      */
@@ -41,8 +221,6 @@ export declare class FChartBuilderBase<TBuilder extends ChartBuilder = ChartBuil
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create();
      * builder.setSubtitle({ text: 'FY 2026' });
      * ```
      */
@@ -55,8 +233,6 @@ export declare class FChartBuilderBase<TBuilder extends ChartBuilder = ChartBuil
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create();
      * builder.clearSubtitle();
      * ```
      */
@@ -70,8 +246,6 @@ export declare class FChartBuilderBase<TBuilder extends ChartBuilder = ChartBuil
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create();
      * builder.setLegend(true);
      * ```
      */
@@ -84,29 +258,32 @@ export declare class FChartBuilderBase<TBuilder extends ChartBuilder = ChartBuil
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create();
      * builder.clearLegend();
      * ```
      */
     clearLegend(): this;
     /**
-     * Sets the theme configuration and returns this builder for chaining.
+     * Sets a built-in or custom registered theme and returns this builder for chaining.
      *
      * A non-empty chart palette takes precedence over the theme's series colors. This method does
      * not clear that palette; call `clearPalette()` explicitly to use the selected theme colors.
+     * Use `univerAPI.Enum.ChartThemeName` for built-in themes. Custom names must first be
+     * registered through `univerAPI.registerTheme()`.
      *
      * This method executes synchronously.
      *
-     * @param name The stable registered name.
+     * @param name A built-in Chart theme name or the stable name of a custom registered theme.
      * @returns This builder for chaining.
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
-     * if (!fWorksheet) return;
-     * const builder = fWorksheet.charts.create();
-     * builder.setTheme('brand');
+     * const chartInfo = fWorksheet
+     *   .newChart(univerAPI.Enum.ChartTypeString.Column)
+     *   .setSource('A1:B8')
+     *   .setTheme(univerAPI.Enum.ChartThemeName.UniverGradient1)
+     *   .build();
+     * await fWorksheet.insertChart(chartInfo);
      * ```
      */
     setTheme(name: string): this;
@@ -118,10 +295,6 @@ export declare class FChartBuilderBase<TBuilder extends ChartBuilder = ChartBuil
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
-     * if (!fWorksheet) return;
-     * const builder = fWorksheet.charts.create();
      * builder.clearTheme();
      * ```
      */
@@ -138,10 +311,6 @@ export declare class FChartBuilderBase<TBuilder extends ChartBuilder = ChartBuil
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
-     * if (!fWorksheet) return;
-     * const builder = fWorksheet.charts.create();
      * builder.setPalette(['#1677ff', '#52c41a']);
      * ```
      */
@@ -152,11 +321,9 @@ export declare class FChartBuilderBase<TBuilder extends ChartBuilder = ChartBuil
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
-     * if (!fWorksheet) return;
-     * const builder = fWorksheet.charts.list()[0];
-     * builder.clearPalette().commit();
+     * const chart = fWorksheet.getCharts()[0];
+     * const info = chart.toBuilder().clearPalette().build();
+     * await chart.update(info);
      * ```
      */
     clearPalette(): this;
@@ -189,8 +356,6 @@ export declare class FChartBuilderBase<TBuilder extends ChartBuilder = ChartBuil
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create();
      * builder.clearAppearance(univerAPI.Enum.ChartAppearanceTarget.Background);
      * ```
      */
@@ -205,8 +370,6 @@ export declare class FChartBuilderBase<TBuilder extends ChartBuilder = ChartBuil
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Column);
      * builder.setAutoGradientFill(true);
      * ```
      */
@@ -219,8 +382,6 @@ export declare class FChartBuilderBase<TBuilder extends ChartBuilder = ChartBuil
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Column);
      * builder.setAutoGradientFill(true);
      * builder.resetAutoGradientFill();
      * ```
@@ -235,9 +396,7 @@ export declare class FChartBuilderBase<TBuilder extends ChartBuilder = ChartBuil
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create();
-     * builder.setInvalidValueStrategy(univerAPI.Enum.InvalidValueType.Break);
+     * builder.setInvalidValueStrategy(univerAPI.Enum.ChartInvalidValueType.Break);
      * ```
      */
     setInvalidValueStrategy(value: InvalidValueType): this;
@@ -249,8 +408,6 @@ export declare class FChartBuilderBase<TBuilder extends ChartBuilder = ChartBuil
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create();
      * builder.resetInvalidValueStrategy();
      * ```
      */
@@ -264,12 +421,48 @@ export declare class FChartBuilderBase<TBuilder extends ChartBuilder = ChartBuil
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create();
      * builder.setCategoryField(0);
      * ```
      */
     setCategoryField(index: number): this;
+    /**
+     * Sets the ordered category fields used by a multi-level category axis.
+     *
+     * This method executes synchronously.
+     *
+     * @param indexes The zero-based field indexes in root-to-leaf order.
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * builder.setCategoryFields([0, 1, 2]);
+     * ```
+     */
+    setCategoryFields(indexes: readonly number[]): this;
+    /**
+     * Clears the ordered category field configuration.
+     *
+     * This method executes synchronously.
+     *
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * builder.clearCategoryFields();
+     * ```
+     */
+    clearCategoryFields(): this;
+    /**
+     * Enables or disables the multi-level category axis for the selected category fields.
+     *
+     * This method executes synchronously and does not replace the selected category fields.
+     *
+     * @param enabled Whether to render the selected category fields as one multi-level axis.
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * builder.setMultiLevelCategoryAxis(true);
+     * ```
+     */
+    setMultiLevelCategoryAxis(enabled: boolean): this;
     /**
      * Clears the category field configuration and returns this builder for chaining.
      *
@@ -278,8 +471,6 @@ export declare class FChartBuilderBase<TBuilder extends ChartBuilder = ChartBuil
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create();
      * builder.clearCategoryField();
      * ```
      */
@@ -293,8 +484,6 @@ export declare class FChartBuilderBase<TBuilder extends ChartBuilder = ChartBuil
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create();
      * builder.setValueFields([1, 2]);
      * ```
      */
@@ -307,8 +496,6 @@ export declare class FChartBuilderBase<TBuilder extends ChartBuilder = ChartBuil
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create();
      * builder.clearValueFields();
      * ```
      */
@@ -322,8 +509,6 @@ export declare class FChartBuilderBase<TBuilder extends ChartBuilder = ChartBuil
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create();
      * builder.setAggregation({
      *     aggregate: true,
      *     topN: { count: 10, sourceIndex: 2 },
@@ -340,26 +525,8 @@ export declare class FChartBuilderBase<TBuilder extends ChartBuilder = ChartBuil
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create();
      * builder.clearAggregation(univerAPI.Enum.ChartAggregationTarget.TopN);
      * ```
      */
     clearAggregation(target?: ChartAggregationTarget): this;
-    /**
-     * Sets the chart type and returns a builder specialized for that type.
-     *
-     * This method executes synchronously.
-     *
-     * @param type The canonical chart type.
-     * @returns A new specialized builder that shares this builder's pending configuration.
-     * @example
-     * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create();
-     * const column = builder.setType(univerAPI.Enum.ChartTypeString.Column);
-     * ```
-     */
-    setType<T extends keyof IChartBuilderTypeMap>(type: T): IChartBuilderTypeMap[T];
-    protected _setType(type: keyof IChartBuilderTypeMap): void;
 }