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

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

@@ -1,6 +1,67 @@
-import type { WordCloudShapeEnum } from '@univerjs-pro/engine-chart';
+import type { IChartInfo, WordCloudShapeEnum } from '@univerjs-pro/engine-chart';
 import { FChartBuilderBase } from '../f-chart-builder-base';
-export declare class FWordCloudChartBuilder extends FChartBuilderBase {
+/**
+ * Fluent, type-specific Builder for Word Cloud Charts.
+ *
+ * @example Sheet
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+ * const chartInfo = fWorksheet
+ *   .newChart(univerAPI.Enum.ChartTypeString.WordCloud)
+ *   .setSource('A1:B8')
+ *   .setCategoryField(0)
+ *   .setValueFields([1])
+ *   .setShape(univerAPI.Enum.ChartWordCloudShapeEnum.Circle)
+ *   .setRepeat(true)
+ *   .build();
+ * await fWorksheet.insertChart(chartInfo);
+ * ```
+ *
+ * @example Doc
+ * ```ts
+ * const fDocument = univerAPI.getActiveDocument();
+ * const chartInfo = fDocument
+ *   .newChart(univerAPI.Enum.ChartTypeString.WordCloud)
+ *   .setSource([['Word', 'Frequency'], ['Univer', 42], ['Chart', 28], ['Data', 18]])
+ *   .setCategoryField(0)
+ *   .setValueFields([1])
+ *   .setShape(univerAPI.Enum.ChartWordCloudShapeEnum.Circle)
+ *   .setRepeat(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.WordCloud)
+ *   .setSource([['Word', 'Frequency'], ['Univer', 42], ['Chart', 28], ['Data', 18]])
+ *   .setCategoryField(0)
+ *   .setValueFields([1])
+ *   .setShape(univerAPI.Enum.ChartWordCloudShapeEnum.Circle)
+ *   .setRepeat(true)
+ *   .build();
+ * await fSlide.insertChart(chartInfo);
+ * ```
+ *
+ * @example Board
+ * ```ts
+ * const fBoard = univerAPI.getActiveBoard();
+ * const chartInfo = fBoard
+ *   .newChart(univerAPI.Enum.ChartTypeString.WordCloud)
+ *   .setSource([['Word', 'Frequency'], ['Univer', 42], ['Chart', 28], ['Data', 18]])
+ *   .setCategoryField(0)
+ *   .setValueFields([1])
+ *   .setShape(univerAPI.Enum.ChartWordCloudShapeEnum.Circle)
+ *   .setRepeat(true)
+ *   .build();
+ * await fBoard.insertChart(chartInfo);
+ * ```
+ */
+export declare class FWordCloudChartBuilder<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 FWordCloudChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.WordCloud);
-     * builder.setShape(univerAPI.Enum.WordCloudShapeEnum.Cloud);
+     * builder.setShape(univerAPI.Enum.ChartWordCloudShapeEnum.Cloud);
      * ```
      */
     setShape(value: WordCloudShapeEnum): this;
@@ -24,8 +83,6 @@ export declare class FWordCloudChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.WordCloud);
      * builder.resetShape();
      * ```
      */
@@ -39,8 +96,6 @@ export declare class FWordCloudChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.WordCloud);
      * builder.setMaskImage('resource-id');
      * ```
      */
@@ -53,8 +108,6 @@ export declare class FWordCloudChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.WordCloud);
      * builder.clearMaskImage();
      * ```
      */
@@ -68,8 +121,6 @@ export declare class FWordCloudChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.WordCloud);
      * builder.setRepeat(true);
      * ```
      */
@@ -82,8 +133,6 @@ export declare class FWordCloudChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.WordCloud);
      * builder.resetRepeat();
      * ```
      */

package/lib/types/facade/chart-builder-registry.d.ts

@@ -1,8 +1,8 @@
-import type { ChartBuilder } from '@univerjs-pro/engine-chart';
+import type { ChartBuilder, ChartTypeString, IChartInfo } from '@univerjs-pro/engine-chart';
 import type { IChartBuilderTypeMap } from './chart-builder-type-map';
 import type { FChartBuilderBase } from './f-chart-builder-base';
 import type { IChartBuilderFacadeContext } from './internal/chart-builder-facade-context';
 export type ChartBuilderConstructor<T extends FChartBuilderBase = FChartBuilderBase> = new (context: IChartBuilderFacadeContext<ChartBuilder>) => T;
-export declare function registerChartBuilder<T extends keyof IChartBuilderTypeMap>(type: T, Constructor: ChartBuilderConstructor<IChartBuilderTypeMap[T]>): void;
-export declare function getChartBuilderConstructor<T extends keyof IChartBuilderTypeMap>(type: T): ChartBuilderConstructor<IChartBuilderTypeMap[T]>;
-export declare function getChartBuilderRegistryKeys(): (keyof IChartBuilderTypeMap)[];
+export declare function registerChartBuilder<T extends ChartTypeString>(type: T, Constructor: ChartBuilderConstructor<IChartBuilderTypeMap[T]>): void;
+export declare function getChartBuilderConstructor<T extends ChartTypeString, TSource = never[], TDataSource = TSource, TInfo extends IChartInfo<TDataSource> = IChartInfo<TDataSource>>(type: T): new (context: IChartBuilderFacadeContext<ChartBuilder, TSource, TDataSource, TInfo>) => IChartBuilderTypeMap<TSource, TDataSource, TInfo>[T];
+export declare function getChartBuilderRegistryKeys(): ChartTypeString[];

package/lib/types/facade/chart-builder-type-map.d.ts

@@ -1,4 +1,4 @@
-import type { ChartTypeString } from '@univerjs-pro/engine-chart';
+import type { ChartTypeString, IChartInfo, IChartSeriesPatch, IChartSeriesStyleSpec } from '@univerjs-pro/engine-chart';
 import type { FAreaChartBuilder } from './builders/f-area-chart-builder';
 import type { FBoxplotChartBuilder } from './builders/f-boxplot-chart-builder';
 import type { FBubbleChartBuilder } from './builders/f-bubble-chart-builder';
@@ -21,35 +21,38 @@ import type { FWaterfallChartBuilder } from './builders/f-waterfall-chart-builde
 import type { FWordCloudChartBuilder } from './builders/f-word-cloud-chart-builder';
 import type { FCartesianChartBuilder } from './f-cartesian-chart-builder';
 import type { FChartBuilderBase } from './f-chart-builder-base';
-export interface IChartBuilderTypeMap {
-    [ChartTypeString.Line]: FLineChartBuilder;
-    [ChartTypeString.Column]: FCartesianChartBuilder;
-    [ChartTypeString.ColumnStacked]: FCartesianChartBuilder;
-    [ChartTypeString.ColumnPercentStacked]: FCartesianChartBuilder;
-    [ChartTypeString.Bar]: FCartesianChartBuilder;
-    [ChartTypeString.BarStacked]: FCartesianChartBuilder;
-    [ChartTypeString.BarPercentStacked]: FCartesianChartBuilder;
-    [ChartTypeString.Pie]: FPieChartBuilder;
-    [ChartTypeString.Donut]: FPieChartBuilder;
-    [ChartTypeString.Area]: FAreaChartBuilder;
-    [ChartTypeString.AreaStacked]: FAreaChartBuilder;
-    [ChartTypeString.AreaPercentStacked]: FAreaChartBuilder;
-    [ChartTypeString.Radar]: FRadarChartBuilder;
-    [ChartTypeString.Scatter]: FScatterChartBuilder;
-    [ChartTypeString.Combination]: FCombinationChartBuilder;
-    [ChartTypeString.WordCloud]: FWordCloudChartBuilder;
-    [ChartTypeString.Funnel]: FFunnelChartBuilder;
-    [ChartTypeString.Bubble]: FBubbleChartBuilder;
-    [ChartTypeString.Relation]: FRelationChartBuilder;
-    [ChartTypeString.Waterfall]: FWaterfallChartBuilder;
-    [ChartTypeString.Pareto]: FParetoChartBuilder;
-    [ChartTypeString.Sankey]: FChartBuilderBase;
-    [ChartTypeString.Heatmap]: FHeatmapChartBuilder;
-    [ChartTypeString.Boxplot]: FBoxplotChartBuilder;
-    [ChartTypeString.Candlestick]: FCandlestickChartBuilder;
-    [ChartTypeString.Histogram]: FHistogramChartBuilder;
-    [ChartTypeString.Treemap]: FTreemapChartBuilder;
-    [ChartTypeString.Sunburst]: FSunburstChartBuilder;
-    [ChartTypeString.Gauge]: FGaugeChartBuilder;
-    [ChartTypeString.Chord]: FChordChartBuilder;
+/** Maps each canonical Chart type to its type-specific Facade Builder. */
+export interface IChartBuilderTypeMap<TSource = never[], TDataSource = TSource, TInfo extends IChartInfo<TDataSource> = IChartInfo<TDataSource>> {
+    [ChartTypeString.Line]: FLineChartBuilder<TSource, TDataSource, TInfo>;
+    [ChartTypeString.Column]: FCartesianChartBuilder<Omit<IChartSeriesPatch, 'selector'>, IChartSeriesStyleSpec, TSource, TDataSource, TInfo>;
+    [ChartTypeString.ColumnStacked]: FCartesianChartBuilder<Omit<IChartSeriesPatch, 'selector'>, IChartSeriesStyleSpec, TSource, TDataSource, TInfo>;
+    [ChartTypeString.ColumnPercentStacked]: FCartesianChartBuilder<Omit<IChartSeriesPatch, 'selector'>, IChartSeriesStyleSpec, TSource, TDataSource, TInfo>;
+    [ChartTypeString.Bar]: FCartesianChartBuilder<Omit<IChartSeriesPatch, 'selector'>, IChartSeriesStyleSpec, TSource, TDataSource, TInfo>;
+    [ChartTypeString.BarStacked]: FCartesianChartBuilder<Omit<IChartSeriesPatch, 'selector'>, IChartSeriesStyleSpec, TSource, TDataSource, TInfo>;
+    [ChartTypeString.BarPercentStacked]: FCartesianChartBuilder<Omit<IChartSeriesPatch, 'selector'>, IChartSeriesStyleSpec, TSource, TDataSource, TInfo>;
+    [ChartTypeString.Pie]: FPieChartBuilder<TSource, TDataSource, TInfo>;
+    [ChartTypeString.Donut]: FPieChartBuilder<TSource, TDataSource, TInfo>;
+    [ChartTypeString.Area]: FAreaChartBuilder<TSource, TDataSource, TInfo>;
+    [ChartTypeString.AreaStacked]: FAreaChartBuilder<TSource, TDataSource, TInfo>;
+    [ChartTypeString.AreaPercentStacked]: FAreaChartBuilder<TSource, TDataSource, TInfo>;
+    [ChartTypeString.Radar]: FRadarChartBuilder<TSource, TDataSource, TInfo>;
+    [ChartTypeString.Scatter]: FScatterChartBuilder<TSource, TDataSource, TInfo>;
+    [ChartTypeString.Combination]: FCombinationChartBuilder<TSource, TDataSource, TInfo>;
+    [ChartTypeString.WordCloud]: FWordCloudChartBuilder<TSource, TDataSource, TInfo>;
+    [ChartTypeString.Funnel]: FFunnelChartBuilder<TSource, TDataSource, TInfo>;
+    [ChartTypeString.Bubble]: FBubbleChartBuilder<TSource, TDataSource, TInfo>;
+    [ChartTypeString.Relation]: FRelationChartBuilder<TSource, TDataSource, TInfo>;
+    [ChartTypeString.Waterfall]: FWaterfallChartBuilder<TSource, TDataSource, TInfo>;
+    [ChartTypeString.Pareto]: FParetoChartBuilder<TSource, TDataSource, TInfo>;
+    [ChartTypeString.Sankey]: FChartBuilderBase<TSource, TDataSource, TInfo>;
+    [ChartTypeString.Heatmap]: FHeatmapChartBuilder<TSource, TDataSource, TInfo>;
+    [ChartTypeString.Boxplot]: FBoxplotChartBuilder<TSource, TDataSource, TInfo>;
+    [ChartTypeString.Candlestick]: FCandlestickChartBuilder<TSource, TDataSource, TInfo>;
+    [ChartTypeString.Histogram]: FHistogramChartBuilder<TSource, TDataSource, TInfo>;
+    [ChartTypeString.Treemap]: FTreemapChartBuilder<TSource, TDataSource, TInfo>;
+    [ChartTypeString.Sunburst]: FSunburstChartBuilder<TSource, TDataSource, TInfo>;
+    [ChartTypeString.Gauge]: FGaugeChartBuilder<TSource, TDataSource, TInfo>;
+    [ChartTypeString.Chord]: FChordChartBuilder<TSource, TDataSource, TInfo>;
 }
+/** Any concrete engine-only Chart configuration builder. */
+export type FAnyChartBuilder<TSource = never[], TDataSource = TSource, TInfo extends IChartInfo<TDataSource> = IChartInfo<TDataSource>> = IChartBuilderTypeMap<TSource, TDataSource, TInfo>[ChartTypeString];

package/lib/types/facade/chart-host-builder-types.d.ts

@@ -1,21 +1,2 @@
-import type { IChartBuilderTypeMap } from './chart-builder-type-map';
-import type { FChartBuilderBase } from './f-chart-builder-base';
-import type { IChartBuilderHostTypes } from './f-charts-base';
-type RebindHostMethods<TBuilder extends FChartBuilderBase, THostMethods extends object> = {
-    [K in keyof THostMethods]: THostMethods[K] extends (...args: infer TArgs) => infer TResult ? TResult extends THostMethods ? (...args: TArgs) => HostComposedChartBuilder<TBuilder, THostMethods> : THostMethods[K] : THostMethods[K];
-};
-type RebindBuilderMethods<TBuilder extends FChartBuilderBase, THostMethods extends object> = {
-    [K in keyof Omit<TBuilder, keyof THostMethods | 'setType'>]: Omit<TBuilder, keyof THostMethods | 'setType'>[K] extends (...args: infer TArgs) => infer TResult ? TResult extends FChartBuilderBase ? (...args: TArgs) => HostComposedChartBuilder<TResult, THostMethods> : Omit<TBuilder, keyof THostMethods | 'setType'>[K] : Omit<TBuilder, keyof THostMethods | 'setType'>[K];
-};
-export type HostComposedChartBuilder<TBuilder extends FChartBuilderBase, THostMethods extends object> = RebindBuilderMethods<TBuilder, THostMethods> & Pick<TBuilder, 'getId' | 'describe' | 'commit' | 'exportImage'> & RebindHostMethods<TBuilder, THostMethods> & {
-    setType<T extends keyof IChartBuilderTypeMap>(type: T): HostComposedChartBuilder<IChartBuilderTypeMap[T], THostMethods>;
-};
-export type HostChartBuilderOf<T extends keyof IChartBuilderTypeMap, THostMethods extends object> = HostComposedChartBuilder<IChartBuilderTypeMap[T], THostMethods>;
-export type HostAnyChartBuilder<THostMethods extends object> = {
-    [T in keyof IChartBuilderTypeMap]: HostChartBuilderOf<T, THostMethods>;
-}[keyof IChartBuilderTypeMap];
-export interface IHostChartBuilderTypes<THostMethods extends object> extends IChartBuilderHostTypes {
-    Initial: HostComposedChartBuilder<FChartBuilderBase, THostMethods>;
-    Any: HostAnyChartBuilder<THostMethods>;
-}
-export {};
+/** Combines one concrete engine Chart Builder with host-owned creation methods. */
+export type HostComposedChartBuilder<TBuilder extends object, THostMethods extends object> = TBuilder & THostMethods;

package/lib/types/facade/create-chart-builder.d.ts

@@ -0,0 +1,46 @@
+import type { ChartTypeString, IChartDescription, IChartInfo } from '@univerjs-pro/engine-chart';
+import type { Injector } from '@univerjs/core';
+import type { IChartBuilderTypeMap } from './chart-builder-type-map';
+import type { HostComposedChartBuilder } from './chart-host-builder-types';
+/** Host extension hooks used to add placement and ownership methods to a Chart Builder. */
+export interface IChartBuilderExtensionContext<TInfo extends IChartInfo<TDataSource>, TDataSource> {
+    /** Returns a cloned host-specific information field from the detached draft. */
+    getInfo<K extends keyof TInfo>(key: K): TInfo[K] | undefined;
+    /** Replaces a host-specific information field in the detached draft. */
+    setInfo<K extends keyof TInfo>(key: K, value: TInfo[K]): void;
+    /** Sets the common absolute position in the detached draft. */
+    setAbsolutePosition(x: number, y: number): void;
+    /** Sets the common size in the detached draft. */
+    setSize(width: number, height: number): void;
+}
+/** A type-specific engine Builder composed with host-owned creation methods. */
+export type FChartInfoBuilder<T extends ChartTypeString, TSource, TDataSource, TInfo extends IChartInfo<TDataSource>, TExtension extends object = object> = HostComposedChartBuilder<IChartBuilderTypeMap<TSource, TDataSource, TInfo>[T], TExtension>;
+interface IChartBuilderExtensionOptions<T extends ChartTypeString, TSource, TDataSource, TInfo extends IChartInfo<TDataSource>, TExtension extends object> {
+    extension: (context: IChartBuilderExtensionContext<TInfo, TDataSource>) => TExtension & ThisType<FChartInfoBuilder<T, TSource, TDataSource, TInfo, TExtension>>;
+}
+interface INewChartBuilderOptions<T extends ChartTypeString, TSource, TDataSource, TInfo extends IChartInfo<TDataSource>, TExtension extends object> extends IChartBuilderExtensionOptions<T, TSource, TDataSource, TInfo, TExtension> {
+    type: T;
+    injector: Injector;
+    commitError: string;
+    normalizeSource: (source: TSource) => TDataSource;
+    createInfo: () => Omit<TInfo, 'config' | 'dataSource'>;
+}
+interface IExistingChartBuilderOptions<T extends ChartTypeString, TSource, TDataSource, TInfo extends IChartInfo<TDataSource>, TExtension extends object> extends IChartBuilderExtensionOptions<T, TSource, TDataSource, TInfo, TExtension> {
+    type: T;
+    info: TInfo;
+    description: IChartDescription;
+    normalizeSource: (source: TSource) => TDataSource;
+}
+/**
+ * Creates a new detached Chart information Builder.
+ * @param options The Chart type, source normalizer, host information factory, and host extension.
+ * @returns A type-specific Builder that produces an insertable Chart information object.
+ */
+export declare function createChartBuilder<T extends ChartTypeString, TSource, TDataSource, TInfo extends IChartInfo<TDataSource>, TExtension extends object = object>(options: INewChartBuilderOptions<T, TSource, TDataSource, TInfo, TExtension>): FChartInfoBuilder<T, TSource, TDataSource, TInfo, TExtension>;
+/**
+ * Creates a detached Chart information Builder prefilled from an existing Chart snapshot.
+ * @param options The existing information, semantic description, target type, source normalizer, and host extension.
+ * @returns A type-specific Builder for creating a modified copy without updating the live Chart.
+ */
+export declare function createChartBuilder<T extends ChartTypeString, TSource, TDataSource, TInfo extends IChartInfo<TDataSource>, TExtension extends object = object>(options: IExistingChartBuilderOptions<T, TSource, TDataSource, TInfo, TExtension>): FChartInfoBuilder<T, TSource, TDataSource, TInfo, TExtension>;
+export {};

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

@@ -1,6 +1,21 @@
-import type { ChartAxisTarget, IChartAxisSpec, IChartMarkLineSpec } from '@univerjs-pro/engine-chart';
+import type { ChartAxisTarget, IChartAxisSpec, IChartInfo, IChartMarkLineSpec } from '@univerjs-pro/engine-chart';
 import { FChartBuilderBase } from './f-chart-builder-base';
-export declare abstract class FAxisChartBuilder extends FChartBuilderBase {
+/**
+ * Fluent base Builder for Charts that expose Cartesian axes and mark lines.
+ *
+ * @example
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+ * const chartInfo = fWorksheet
+ *   .newChart(univerAPI.Enum.ChartTypeString.Line)
+ *   .setSource('A1:D8')
+ *   .setYAxisTitle('Revenue')
+ *   .build();
+ * await fWorksheet.insertChart(chartInfo);
+ * ```
+ */
+export declare abstract class FAxisChartBuilder<TSource = never[], TDataSource = TSource, TInfo extends IChartInfo<TDataSource> = IChartInfo<TDataSource>> extends FChartBuilderBase<TSource, TDataSource, TInfo> {
     /**
      * Replaces all fixed-axis mark lines.
      *
@@ -8,31 +23,27 @@ export declare abstract class FAxisChartBuilder extends FChartBuilderBase {
      * series color, falling back to the active theme. Endpoint symbols are hidden. Labels are hidden
      * unless a `label` object is supplied; an empty label object shows the axis-formatted value.
      *
-     * Read the current value from `builder.describe().markLines`.
+     * Read the current value from `builder.build().config.markLines`.
      *
      * @param lines The complete ordered mark-line collection. An empty list clears it.
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Line);
      * builder.setMarkLines([{ axis: univerAPI.Enum.ChartSemanticAxis.PrimaryValue, value: 80 }]);
-     * const markLines = builder.describe().markLines;
+     * const markLines = builder.build().config.markLines;
      * ```
      */
     setMarkLines(lines: readonly IChartMarkLineSpec[]): this;
     /**
      * Clears all fixed-axis mark lines.
      *
-     * Read the cleared value from `builder.describe().markLines`.
+     * Read the cleared value from `builder.build().config.markLines`.
      *
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Line);
      * builder.clearMarkLines();
-     * const markLines = builder.describe().markLines;
+     * const markLines = builder.build().config.markLines;
      * ```
      */
     clearMarkLines(): this;
@@ -45,8 +56,6 @@ export declare abstract class FAxisChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Line);
      * builder.setXAxis({ title: 'Month' });
      * ```
      */
@@ -60,8 +69,6 @@ export declare abstract class FAxisChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Line);
      * builder.clearXAxis(univerAPI.Enum.ChartAxisTarget.Label);
      * ```
      */
@@ -75,8 +82,6 @@ export declare abstract class FAxisChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Line);
      * builder.setYAxis({ title: 'Revenue' });
      * ```
      */
@@ -90,8 +95,6 @@ export declare abstract class FAxisChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Line);
      * builder.clearYAxis(univerAPI.Enum.ChartAxisTarget.GridLine);
      * ```
      */
@@ -105,8 +108,6 @@ export declare abstract class FAxisChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Line);
      * builder.setRightYAxis({ title: 'Margin' });
      * ```
      */
@@ -120,8 +121,6 @@ export declare abstract class FAxisChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Line);
      * builder.clearRightYAxis(univerAPI.Enum.ChartAxisTarget.Line);
      * ```
      */
@@ -135,8 +134,6 @@ export declare abstract class FAxisChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Line);
      * builder.setXAxisTitle('Month');
      * ```
      */
@@ -149,8 +146,6 @@ export declare abstract class FAxisChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Line);
      * builder.clearXAxisTitle();
      * ```
      */
@@ -164,8 +159,6 @@ export declare abstract class FAxisChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Line);
      * builder.setYAxisTitle('Revenue');
      * ```
      */
@@ -178,8 +171,6 @@ export declare abstract class FAxisChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Line);
      * builder.clearYAxisTitle();
      * ```
      */
@@ -193,8 +184,6 @@ export declare abstract class FAxisChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Line);
      * builder.setRightYAxisTitle('Margin');
      * ```
      */
@@ -207,8 +196,6 @@ export declare abstract class FAxisChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Line);
      * builder.clearRightYAxisTitle();
      * ```
      */
@@ -222,8 +209,6 @@ export declare abstract class FAxisChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Line);
      * builder.setUseDateAxis(true);
      * ```
      */
@@ -236,8 +221,6 @@ export declare abstract class FAxisChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Line);
      * builder.resetUseDateAxis();
      * ```
      */

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

@@ -1,8 +1,33 @@
-import type { ChartAllSeriesStyleTarget, ChartAxisPointerTarget, ChartPublicSeriesSelector, ChartSeriesClearTarget, ChartSeriesTrendlineSelector, ChartTrendlineSelector, ChartTrendlineValue, DeepNullish, IChartAxisPointerSpec, IChartBarSpec, IChartSeriesPatch, IChartSeriesStyleSpec } from '@univerjs-pro/engine-chart';
+import type { ChartAllSeriesStyleTarget, ChartAxisPointerTarget, ChartPublicSeriesSelector, ChartSeriesClearTarget, ChartSeriesTrendlineSelector, ChartTrendlineSelector, ChartTrendlineValue, DeepNullish, IChartAxisPointerSpec, IChartBarSpec, IChartInfo, IChartSeriesPatch, IChartSeriesStyleSpec } from '@univerjs-pro/engine-chart';
 import { FAxisChartBuilder } from './f-axis-chart-builder';
-export declare class FCartesianChartBuilder<TSeriesPatch extends Omit<IChartSeriesPatch, 'selector'> = Omit<IChartSeriesPatch, 'selector'>, TSeriesStyle extends IChartSeriesStyleSpec = IChartSeriesStyleSpec> extends FAxisChartBuilder {
+/**
+ * Fluent Builder for Cartesian Charts with per-series styling and trendlines.
+ *
+ * @example
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+ * const chartInfo = fWorksheet
+ *   .newChart(univerAPI.Enum.ChartTypeString.Column)
+ *   .setSource('A1:D8')
+ *   .setBar({ gapWidth: 0.2 })
+ *   .build();
+ * await fWorksheet.insertChart(chartInfo);
+ * ```
+ */
+export declare class FCartesianChartBuilder<TSeriesPatch extends Omit<IChartSeriesPatch, 'selector'> = Omit<IChartSeriesPatch, 'selector'>, TSeriesStyle extends IChartSeriesStyleSpec = IChartSeriesStyleSpec, TSource = never[], TDataSource = TSource, TInfo extends IChartInfo<TDataSource> = IChartInfo<TDataSource>> extends FAxisChartBuilder<TSource, TDataSource, TInfo> {
     readonly __seriesPatchType?: TSeriesPatch;
+    /**
+     * Sets Chart-wide Bar and Column spacing and width options.
+     * @param {IChartBarSpec} value The Bar or Column layout specification.
+     * @returns {this} This Builder for chaining.
+     */
     setBar(value: IChartBarSpec): this;
+    /**
+     * Clears Chart-wide Bar and Column layout overrides.
+     * @returns {this} This Builder for chaining.
+     * @example `builder.clearBar()`
+     */
     clearBar(): this;
     /**
      * Sets the series configuration and returns this builder for chaining.
@@ -16,8 +41,6 @@ export declare class FCartesianChartBuilder<TSeriesPatch extends Omit<IChartSeri
      * ```ts
      * import { chartLinearGradient } from '@univerjs-pro/engine-chart';
      *
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Column);
      * const color = chartLinearGradient({
      *     start: { x: 0, y: 1 },
      *     end: { x: 0, y: 0 },
@@ -40,12 +63,15 @@ export declare class FCartesianChartBuilder<TSeriesPatch extends Omit<IChartSeri
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Line);
      * builder.clearSeries(0);
      * ```
      */
     clearSeries(selector: ChartPublicSeriesSelector, target?: ChartSeriesClearTarget): this;
+    /**
+     * Clears every per-series override while preserving all-series defaults.
+     * Use `setSeries()` to write one selector and `describe().series` to read the effective state.
+     */
+    clearAllSeriesOverrides(): this;
     /**
      * Sets persistent defaults inherited by every current and future series.
      *
@@ -55,8 +81,6 @@ export declare class FCartesianChartBuilder<TSeriesPatch extends Omit<IChartSeri
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Line);
      * builder.setAllSeriesStyle({ color: '#1677ff', fillOpacity: 0.8 });
      * ```
      */
@@ -70,8 +94,6 @@ export declare class FCartesianChartBuilder<TSeriesPatch extends Omit<IChartSeri
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Line);
      * builder.clearAllSeriesStyle(univerAPI.Enum.ChartAllSeriesStyleTarget.Color);
      * ```
      */
@@ -86,8 +108,6 @@ export declare class FCartesianChartBuilder<TSeriesPatch extends Omit<IChartSeri
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Line);
      * builder.setTrendline(0, { type: univerAPI.Enum.ChartTrendlineType.linear });
      * ```
      */
@@ -102,8 +122,6 @@ export declare class FCartesianChartBuilder<TSeriesPatch extends Omit<IChartSeri
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Line);
      * builder.removeTrendline(0, 0);
      * ```
      */
@@ -117,8 +135,6 @@ export declare class FCartesianChartBuilder<TSeriesPatch extends Omit<IChartSeri
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Line);
      * builder.clearTrendlines(0);
      * ```
      */
@@ -132,8 +148,6 @@ export declare class FCartesianChartBuilder<TSeriesPatch extends Omit<IChartSeri
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Line);
      * builder.setAxisPointer({ indicatorLineColor: '#1677ff' });
      * ```
      */
@@ -147,8 +161,6 @@ export declare class FCartesianChartBuilder<TSeriesPatch extends Omit<IChartSeri
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Line);
      * builder.clearAxisPointer(univerAPI.Enum.ChartAxisPointerTarget.IndicatorLineColor);
      * ```
      */