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

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, 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 },
@@ -29,7 +52,7 @@ export declare class FCartesianChartBuilder<TSeriesPatch extends Omit<IChartSeri
      * builder.setSeries(0, { color });
      * ```
      */
-    setSeries(selector: ChartPublicSeriesSelector, patch: TSeriesPatch): this;
+    setSeries(selector: ChartPublicSeriesSelector, patch: DeepNullish<TSeriesPatch>): this;
     /**
      * Clears the series configuration and returns this builder for chaining.
      *
@@ -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,12 +81,10 @@ 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 });
      * ```
      */
-    setAllSeriesStyle(style: TSeriesStyle): this;
+    setAllSeriesStyle(style: DeepNullish<TSeriesStyle>): this;
     /**
      * Clears persistent defaults inherited by every series.
      *
@@ -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);
      * ```
      */