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

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

@@ -1,19 +1,79 @@
-import type { ChartPublicSeriesSelector, IChartSeriesPatch, IChartWaterfallConnectorStyleSpec, IChartWaterfallPointRoleSpec, WaterfallStackTypeEnum } from '@univerjs-pro/engine-chart';
-import type { DeepReadonly } from '@univerjs/core';
+import type { ChartPublicSeriesSelector, IChartInfo, IChartSeriesPatch, IChartSeriesStyleSpec, IChartWaterfallConnectorStyleSpec, IChartWaterfallPointRoleSpec, WaterfallStackTypeEnum } from '@univerjs-pro/engine-chart';
 import { FCartesianChartBuilder } from '../f-cartesian-chart-builder';
-export declare class FWaterfallChartBuilder extends FCartesianChartBuilder {
-    /**
-     * Returns the canonical point-role list, including pending changes.
-     *
-     * @returns The current Waterfall point roles in canonical order.
-     * @example
-     * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Waterfall);
-     * const roles = builder.getPointRoles();
-     * ```
-     */
-    getPointRoles(): DeepReadonly<IChartWaterfallPointRoleSpec[]>;
+/**
+ * Fluent, type-specific Builder for Waterfall Charts.
+ *
+ * @example Sheet
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+ * const chartInfo = fWorksheet
+ *   .newChart(univerAPI.Enum.ChartTypeString.Waterfall)
+ *   .setSource('A1:B8')
+ *   .setPointRoles([{ series: 0, dataPointIndex: 3, role: univerAPI.Enum.ChartWaterfallPointRole.Total }])
+ *   .setConnector(true)
+ *   .setStackType(univerAPI.Enum.ChartWaterfallStackTypeEnum.Arrangement)
+ *   .setUseSubtotal(true)
+ *   .setPositiveStyle(0, { color: '#16a34a' })
+ *   .setNegativeStyle(0, { color: '#dc2626' })
+ *   .setSubtotalStyle(0, { color: '#2563eb' })
+ *   .build();
+ * await fWorksheet.insertChart(chartInfo);
+ * ```
+ *
+ * @example Doc
+ * ```ts
+ * const fDocument = univerAPI.getActiveDocument();
+ * const chartInfo = fDocument
+ *   .newChart(univerAPI.Enum.ChartTypeString.Waterfall)
+ *   .setSource([['Stage', 'Change'], ['Revenue', 300], ['Costs', -180], ['Profit', 120]])
+ *   .setPointRoles([{ series: 0, dataPointIndex: 2, role: univerAPI.Enum.ChartWaterfallPointRole.Total }])
+ *   .setConnector(true)
+ *   .setStackType(univerAPI.Enum.ChartWaterfallStackTypeEnum.Arrangement)
+ *   .setUseSubtotal(true)
+ *   .setPositiveStyle(0, { color: '#16a34a' })
+ *   .setNegativeStyle(0, { color: '#dc2626' })
+ *   .setSubtotalStyle(0, { color: '#2563eb' })
+ *   .build();
+ * await fDocument.insertChart(chartInfo);
+ * ```
+ *
+ * @example Slide
+ * ```ts
+ * const fPresentation = univerAPI.getActivePresentation();
+ * const fSlide = fPresentation.getSlideByIndex(0);
+ * const chartInfo = fSlide
+ *   .newChart(univerAPI.Enum.ChartTypeString.Waterfall)
+ *   .setSource([['Stage', 'Change'], ['Revenue', 300], ['Costs', -180], ['Profit', 120]])
+ *   .setPointRoles([{ series: 0, dataPointIndex: 2, role: univerAPI.Enum.ChartWaterfallPointRole.Total }])
+ *   .setConnector(true)
+ *   .setStackType(univerAPI.Enum.ChartWaterfallStackTypeEnum.Arrangement)
+ *   .setUseSubtotal(true)
+ *   .setPositiveStyle(0, { color: '#16a34a' })
+ *   .setNegativeStyle(0, { color: '#dc2626' })
+ *   .setSubtotalStyle(0, { color: '#2563eb' })
+ *   .build();
+ * await fSlide.insertChart(chartInfo);
+ * ```
+ *
+ * @example Board
+ * ```ts
+ * const fBoard = univerAPI.getActiveBoard();
+ * const chartInfo = fBoard
+ *   .newChart(univerAPI.Enum.ChartTypeString.Waterfall)
+ *   .setSource([['Stage', 'Change'], ['Revenue', 300], ['Costs', -180], ['Profit', 120]])
+ *   .setPointRoles([{ series: 0, dataPointIndex: 2, role: univerAPI.Enum.ChartWaterfallPointRole.Total }])
+ *   .setConnector(true)
+ *   .setStackType(univerAPI.Enum.ChartWaterfallStackTypeEnum.Arrangement)
+ *   .setUseSubtotal(true)
+ *   .setPositiveStyle(0, { color: '#16a34a' })
+ *   .setNegativeStyle(0, { color: '#dc2626' })
+ *   .setSubtotalStyle(0, { color: '#2563eb' })
+ *   .build();
+ * await fBoard.insertChart(chartInfo);
+ * ```
+ */
+export declare class FWaterfallChartBuilder<TSource = never[], TDataSource = TSource, TInfo extends IChartInfo<TDataSource> = IChartInfo<TDataSource>> extends FCartesianChartBuilder<Omit<IChartSeriesPatch, 'selector'>, IChartSeriesStyleSpec, TSource, TDataSource, TInfo> {
     /**
      * Replaces all Waterfall point roles.
      *
@@ -23,10 +83,8 @@ export declare class FWaterfallChartBuilder extends FCartesianChartBuilder {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Waterfall);
      * builder.setPointRoles([{ series: 0, dataPointIndex: 0, role: univerAPI.Enum.ChartWaterfallPointRole.Total }]);
-     * const roles = builder.getPointRoles();
+     * const roles = builder.build().config.waterfall?.pointRoles;
      * ```
      */
     setPointRoles(roles: readonly IChartWaterfallPointRoleSpec[]): this;
@@ -37,16 +95,14 @@ export declare class FWaterfallChartBuilder extends FCartesianChartBuilder {
      * and a neutral `#8C8C8C` base color that is adapted by the active light or dark theme. An object
      * starts from those defaults and overrides only the supplied fields. Pass `false` to hide it.
      *
-     * Read the current value from `builder.describe().waterfall?.connector`.
+     * Read the current value from `builder.build().config.waterfall?.connector`.
      *
      * @param value `false` disables, `true` enables the default dashed style, and an object enables style overrides.
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Waterfall);
      * builder.setConnector(true);
-     * const connector = builder.describe().waterfall?.connector;
+     * const connector = builder.build().config.waterfall?.connector;
      * ```
      */
     setConnector(value: boolean | IChartWaterfallConnectorStyleSpec): this;
@@ -54,15 +110,13 @@ export declare class FWaterfallChartBuilder extends FCartesianChartBuilder {
      * Clears connector configuration. With no persisted connector setting, the renderer does not
      * draw connectors; call `setConnector(true)` to restore the default dashed connector.
      *
-     * Read the cleared value from `builder.describe().waterfall?.connector`.
+     * Read the cleared value from `builder.build().config.waterfall?.connector`.
      *
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Waterfall);
      * builder.clearConnector();
-     * const connector = builder.describe().waterfall?.connector;
+     * const connector = builder.build().config.waterfall?.connector;
      * ```
      */
     clearConnector(): this;
@@ -75,9 +129,7 @@ export declare class FWaterfallChartBuilder extends FCartesianChartBuilder {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Waterfall);
-     * builder.setStackType(univerAPI.Enum.WaterfallStackTypeEnum.Arrangement);
+     * builder.setStackType(univerAPI.Enum.ChartWaterfallStackTypeEnum.Arrangement);
      * ```
      */
     setStackType(value: WaterfallStackTypeEnum): this;
@@ -89,8 +141,6 @@ export declare class FWaterfallChartBuilder extends FCartesianChartBuilder {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Waterfall);
      * builder.resetStackType();
      * ```
      */
@@ -104,8 +154,6 @@ export declare class FWaterfallChartBuilder extends FCartesianChartBuilder {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Waterfall);
      * builder.setUseSubtotal(true);
      * ```
      */
@@ -118,8 +166,6 @@ export declare class FWaterfallChartBuilder extends FCartesianChartBuilder {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Waterfall);
      * builder.resetUseSubtotal();
      * ```
      */
@@ -134,10 +180,8 @@ export declare class FWaterfallChartBuilder extends FCartesianChartBuilder {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Waterfall);
      * builder.setPositiveStyle(0, { color: '#52c41a' });
-     * const positive = builder.describe().series[0]?.waterfallStyles?.positive;
+     * const positive = builder.build().config.series[0]?.waterfallStyles?.positive;
      * ```
      */
     setPositiveStyle(selector: ChartPublicSeriesSelector, value: Omit<IChartSeriesPatch, 'selector'>): this;
@@ -150,10 +194,8 @@ export declare class FWaterfallChartBuilder extends FCartesianChartBuilder {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Waterfall);
      * builder.clearPositiveStyle(0);
-     * const positive = builder.describe().series[0]?.waterfallStyles?.positive;
+     * const positive = builder.build().config.series[0]?.waterfallStyles?.positive;
      * ```
      */
     clearPositiveStyle(selector: ChartPublicSeriesSelector): this;
@@ -167,10 +209,8 @@ export declare class FWaterfallChartBuilder extends FCartesianChartBuilder {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Waterfall);
      * builder.setNegativeStyle(0, { color: '#f5222d' });
-     * const negative = builder.describe().series[0]?.waterfallStyles?.negative;
+     * const negative = builder.build().config.series[0]?.waterfallStyles?.negative;
      * ```
      */
     setNegativeStyle(selector: ChartPublicSeriesSelector, value: Omit<IChartSeriesPatch, 'selector'>): this;
@@ -183,10 +223,8 @@ export declare class FWaterfallChartBuilder extends FCartesianChartBuilder {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Waterfall);
      * builder.clearNegativeStyle(0);
-     * const negative = builder.describe().series[0]?.waterfallStyles?.negative;
+     * const negative = builder.build().config.series[0]?.waterfallStyles?.negative;
      * ```
      */
     clearNegativeStyle(selector: ChartPublicSeriesSelector): this;
@@ -200,10 +238,8 @@ export declare class FWaterfallChartBuilder extends FCartesianChartBuilder {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Waterfall);
      * builder.setSubtotalStyle(0, { color: '#1677ff' });
-     * const subtotal = builder.describe().series[0]?.waterfallStyles?.subtotal;
+     * const subtotal = builder.build().config.series[0]?.waterfallStyles?.subtotal;
      * ```
      */
     setSubtotalStyle(selector: ChartPublicSeriesSelector, value: Omit<IChartSeriesPatch, 'selector'>): this;
@@ -216,10 +252,8 @@ export declare class FWaterfallChartBuilder extends FCartesianChartBuilder {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Waterfall);
      * builder.clearSubtotalStyle(0);
-     * const subtotal = builder.describe().series[0]?.waterfallStyles?.subtotal;
+     * const subtotal = builder.build().config.series[0]?.waterfallStyles?.subtotal;
      * ```
      */
     clearSubtotalStyle(selector: ChartPublicSeriesSelector): this;

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,33 +1,58 @@
-import type { ChartTypeString } from '@univerjs-pro/engine-chart';
-import type { FAreaChartBuilder, FBoxplotChartBuilder, FBubbleChartBuilder, FCandlestickChartBuilder, FCombinationChartBuilder, FFunnelChartBuilder, FHeatmapChartBuilder, FHistogramChartBuilder, FLineChartBuilder, FParetoChartBuilder, FPieChartBuilder, FRadarChartBuilder, FRelationChartBuilder, FScatterChartBuilder, FTreemapChartBuilder, FWaterfallChartBuilder, FWordCloudChartBuilder } from './builders';
+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';
+import type { FCandlestickChartBuilder } from './builders/f-candlestick-chart-builder';
+import type { FChordChartBuilder } from './builders/f-chord-chart-builder';
+import type { FCombinationChartBuilder } from './builders/f-combination-chart-builder';
+import type { FFunnelChartBuilder } from './builders/f-funnel-chart-builder';
+import type { FGaugeChartBuilder } from './builders/f-gauge-chart-builder';
+import type { FHeatmapChartBuilder } from './builders/f-heatmap-chart-builder';
+import type { FHistogramChartBuilder } from './builders/f-histogram-chart-builder';
+import type { FLineChartBuilder } from './builders/f-line-chart-builder';
+import type { FParetoChartBuilder } from './builders/f-pareto-chart-builder';
+import type { FPieChartBuilder } from './builders/f-pie-chart-builder';
+import type { FRadarChartBuilder } from './builders/f-radar-chart-builder';
+import type { FRelationChartBuilder } from './builders/f-relation-chart-builder';
+import type { FScatterChartBuilder } from './builders/f-scatter-chart-builder';
+import type { FSunburstChartBuilder } from './builders/f-sunburst-chart-builder';
+import type { FTreemapChartBuilder } from './builders/f-treemap-chart-builder';
+import type { FWaterfallChartBuilder } from './builders/f-waterfall-chart-builder';
+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;
+/** 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 {};