@univerjs-pro/engine-chart 1.0.0-alpha.5 → 1.0.0-alpha.7

package/lib/types/chart-builder/chart-color.d.ts

@@ -0,0 +1,49 @@
+/** Stable discriminator used by serializable linear-gradient chart colors. */
+export declare const CHART_LINEAR_GRADIENT_TYPE: "linear-gradient";
+/** A mark-local normalized coordinate used by a chart gradient. */
+export interface IChartGradientPoint {
+    /** Horizontal coordinate, where `0` is the mark's left edge and `1` is its right edge. */
+    x: number;
+    /** Vertical coordinate, where `0` is the mark's top edge and `1` is its bottom edge. */
+    y: number;
+}
+/** One color stop in a serializable chart gradient. */
+export interface IChartGradientStop {
+    /** Position along the gradient vector. Values are forwarded to the renderer. */
+    offset: number;
+    /** CSS color string, including `rgba(...)` when desired. */
+    color: string;
+    /** Optional alpha multiplier applied to the alpha already present in `color`. */
+    opacity?: number;
+}
+/** A mark-local linear gradient with at least two stops. */
+export interface IChartLinearGradient {
+    type: typeof CHART_LINEAR_GRADIENT_TYPE;
+    start: IChartGradientPoint;
+    end: IChartGradientPoint;
+    stops: IChartGradientStop[];
+}
+/** A solid CSS color or a serializable mark-local linear gradient. */
+export type ChartColor = string | IChartLinearGradient;
+/** Input accepted by {@link chartLinearGradient}; the discriminator is added automatically. */
+export type ChartLinearGradientInput = Omit<IChartLinearGradient, 'type'>;
+/**
+ * Creates and validates a serializable linear-gradient chart color.
+ *
+ * @param gradient Gradient coordinates and at least two color stops.
+ * @returns A plain-data gradient carrying the stable chart-color discriminator.
+ * @example
+ * ```ts
+ * import { chartLinearGradient } from '@univerjs-pro/engine-chart';
+ *
+ * const color = chartLinearGradient({
+ *     start: { x: 0, y: 1 },
+ *     end: { x: 0, y: 0 },
+ *     stops: [
+ *         { offset: 0, color: 'rgba(22, 119, 255, 0)' },
+ *         { offset: 1, color: '#1677ff' },
+ *     ],
+ * });
+ * ```
+ */
+export declare function chartLinearGradient(gradient: ChartLinearGradientInput): IChartLinearGradient;

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

@@ -1,5 +1,6 @@
 import type { AreaLineStyle, BarShape, ChartAxisDimension, ChartBorderDashType, ChartMarkLineLabelPosition, ChartSemanticAxis, ChartTrendlineType, ChartWaterfallPointRole, InvalidValueType, IRuntimeAxisPosition, LabelAlignEnum, LabelContentType, LegendPositionEnum, LinePointShape, PieLabelPosition, RadarShape, RelationChartLayoutEnum, SelectModeEnum, SeriesLabelPosition, TitlePositionEnum, WaterfallStackTypeEnum, WordCloudShapeEnum } from '../enum';
 import type { IChartData } from '../types';
+import type { ChartColor } from './chart-color';
 export { ChartAxisDimension, ChartMarkLineLabelPosition, ChartSemanticAxis, ChartWaterfallPointRole } from '../enum';
 /** Canonical semantic chart type names exposed by the chart facade. */
 export declare enum ChartTypeString {
@@ -178,24 +179,41 @@ export interface IChartHeatmapLabelSpec extends IChartFontSpec {
     position?: SeriesLabelPosition;
 }
 export interface IChartSeriesStyleSpec {
-    color?: string;
+    color?: ChartColor;
     fillOpacity?: number;
     border?: IChartSeriesBorderSpec;
     point?: IChartSeriesPointSpec;
     rightAxis?: boolean;
     label?: IChartSeriesLabelSpec;
 }
+/** Style fields accepted by fill-capable chart data points. */
+export interface IChartSeriesDataPointStyleSpec {
+    shape?: LinePointShape;
+    size?: number;
+    color?: ChartColor;
+    fillOpacity?: number;
+}
+/** Style fields accepted by symbol data points, whose color remains solid-only. */
+export interface IChartSymbolDataPointStyleSpec extends Omit<IChartSeriesDataPointStyleSpec, 'color'> {
+    color?: string;
+}
 export interface IChartSeriesPatch extends IChartSeriesStyleSpec {
     selector: ChartSeriesSelector;
     type?: ChartSeriesTypeString;
-    dataPoints?: Record<number, {
-        shape?: LinePointShape;
-        size?: number;
-        color?: string | null;
-        fillOpacity?: number;
-    }>;
+    dataPoints?: Record<number, IChartSeriesDataPointStyleSpec>;
     waterfallStyles?: Partial<Record<ChartWaterfallStyleTarget, Omit<IChartSeriesPatch, 'selector' | 'waterfallStyles'>>>;
 }
+/** Series patch for line-like marks whose data points are symbols. */
+export interface IChartLineSeriesPatch extends Omit<IChartSeriesPatch, 'dataPoints'> {
+    dataPoints?: Record<number, IChartSymbolDataPointStyleSpec>;
+}
+/** Series style for chart types that do not accept explicit gradients in the first release. */
+export interface IChartSolidSeriesStyleSpec extends Omit<IChartSeriesStyleSpec, 'color'> {
+    color?: string;
+}
+/** Series patch for chart marks that expose only solid colors. */
+export interface IChartSolidSeriesPatch extends Omit<IChartLineSeriesPatch, keyof IChartSeriesStyleSpec>, IChartSolidSeriesStyleSpec {
+}
 export interface IChartTrendlineSpec {
     selector: ChartSeriesSelector;
     type: ChartTrendlineType;
@@ -235,7 +253,6 @@ export interface IChartAppearanceSpec {
     background?: {
         /** CSS background color. Use `'transparent'` for an explicit transparent chart and host background. */
         color?: string | null;
-        gradient?: boolean;
     };
     border?: {
         color?: string | null;
@@ -273,6 +290,11 @@ export interface IChartPieLabelSpec extends IChartFontSpec {
     position?: PieLabelPosition;
     contentType?: LabelContentType;
 }
+/** Authored style for one materialized Pie or Donut slice. */
+export interface IChartSliceStyleSpec {
+    color?: ChartColor;
+    fillOpacity?: number;
+}
 export interface IChartPieSpec {
     doughnutHole?: number | null;
     explosion?: number;
@@ -285,6 +307,8 @@ export interface IChartPieSpec {
     valueSuffix?: string;
     digitalFixed?: number;
     label?: IChartPieLabelSpec;
+    /** Sparse authored slice styles keyed by materialized slice index. */
+    sliceStyles?: Partial<Record<number, IChartSliceStyleSpec>>;
 }
 export interface IChartRadarSpec {
     shape?: RadarShape;
@@ -316,14 +340,14 @@ export interface IChartParetoLineLabelStyleSpec extends IChartParetoLabelStyleBa
 }
 /** Supported appearance for the Pareto business bars. */
 export interface IChartParetoBarStyleSpec {
-    color?: string;
+    color?: ChartColor;
     opacity?: number;
     border?: IChartParetoBorderStyleSpec;
     label?: IChartParetoBarLabelStyleSpec;
 }
 /** Supported appearance for the derived Pareto cumulative line. */
 export interface IChartParetoLineStyleSpec {
-    color?: string;
+    color?: ChartColor;
     opacity?: number;
     width?: number;
     dashType?: ChartBorderDashType;
@@ -395,6 +419,7 @@ export interface IChartWaterfallConnectorStyleSpec {
 }
 interface IChartSemanticConfig {
     type?: ChartTypeString;
+    autoGradientFill?: boolean;
     title?: ChartTitleSpec | null;
     subtitle?: ChartSubtitleSpec | null;
     trendlines?: IChartTrendlineSpec[] | null;
@@ -435,9 +460,11 @@ export interface IChartCategoryDescription {
 }
 /** Materialized engine semantic data returned explicitly by hosted builders. */
 export type IResolvedChartData = IChartData;
-export interface IChartDescription extends Omit<IChartSemanticConfig, 'series'> {
+export interface IChartDescription extends Omit<IChartSemanticConfig, 'autoGradientFill' | 'series'> {
     id: string;
     type: ChartTypeString;
+    /** Effective automatic-gradient state after applying chart-type defaults. */
+    autoGradientFill: boolean;
     /** Series metadata keyed by source field index; materialized values are available from `resolveData()`. */
     series: Partial<Record<number, IChartSeriesDescription>>;
     /** Category metadata only; materialized category values are available from `resolveData()`. */

package/lib/types/chart-builder/configuration/assertions.d.ts

@@ -0,0 +1,2 @@
+/** Validates semantic indexes before a Facade operation can mutate Pending state. */
+export declare function assertChartIndex(value: number, name: string): void;

package/lib/types/chart-builder/configuration/auto-gradient-fill.d.ts

@@ -0,0 +1,4 @@
+/** Records whether solid mark colors should use the chart's automatic gradient preset. */
+export declare const setAutoGradientFill: (value: boolean) => import("./chart-config-operation").IChartConfigOperation;
+/** Clears an authored automatic-gradient override so the chart-type default applies. */
+export declare const resetAutoGradientFill: () => import("./chart-config-operation").IChartConfigOperation;

package/lib/types/chart-builder/configuration/chart-config-operation.d.ts

@@ -3,6 +3,7 @@ import type { ChartPendingConfig } from '../chart-types';
 export declare enum ChartConfigGroup {
     AllSeriesStyle = "allSeriesStyle",
     Area = "area",
+    AutoGradientFill = "autoGradientFill",
     AxisPointer = "axisPointer",
     Aggregation = "aggregation",
     Appearance = "appearance",

package/lib/types/chart-builder/configuration/index.d.ts

@@ -3,6 +3,7 @@ export { ChartWaterfallStyleTarget } from '../chart-types';
 export * from './aggregation';
 export * from './appearance';
 export * from './area';
+export * from './auto-gradient-fill';
 export * from './axes';
 export * from './axis-pointer';
 export * from './bar';

package/lib/types/chart-builder/configuration/pie.d.ts

@@ -1,4 +1,4 @@
-import type { IChartPieLabelSpec } from '../chart-types';
+import type { IChartPieLabelSpec, IChartSliceStyleSpec } from '../chart-types';
 export declare const setDoughnutHole: (value: number) => import("./chart-config-operation").IChartConfigOperation;
 export declare const clearDoughnutHole: () => import("./chart-config-operation").IChartConfigOperation;
 export declare const setExplosion: (value: number) => import("./chart-config-operation").IChartConfigOperation;
@@ -21,3 +21,7 @@ export declare const setDecimalPlaces: (value: number) => import("./chart-config
 export declare const resetDecimalPlaces: () => import("./chart-config-operation").IChartConfigOperation;
 export declare const setPieLabel: (value: IChartPieLabelSpec) => import("./chart-config-operation").IChartConfigOperation;
 export declare const clearPieLabel: () => import("./chart-config-operation").IChartConfigOperation;
+/** Records the authored style for one materialized Pie or Donut slice. */
+export declare const setSliceStyle: (index: number, value: IChartSliceStyleSpec) => import("./chart-config-operation").IChartConfigOperation;
+/** Clears the authored style for one materialized Pie or Donut slice. */
+export declare const clearSliceStyle: (index: number) => import("./chart-config-operation").IChartConfigOperation;

package/lib/types/chart-builder/conversion/chart-config-converter.d.ts

@@ -3,6 +3,7 @@ import type { ChartPendingConfig, IChartDescription } from '../chart-types';
 import { ChartTypeBits } from '../../enum';
 interface IChartConfigConversionOptions {
     series?: IChartDataSeries[];
+    currentChartType?: ChartTypeBits;
     currentStyle?: ChartStyle;
     currentContext?: IChartContext;
     currentDataAggregation?: IChartDataAggregation;

package/lib/types/chart-builder/index.d.ts

@@ -1,5 +1,7 @@
 export { ChartBuilder } from './chart-builder';
 export type { IChartBuilderAdapter } from './chart-builder-adapter';
+export { CHART_LINEAR_GRADIENT_TYPE, chartLinearGradient } from './chart-color';
+export type { ChartColor, ChartLinearGradientInput, IChartGradientPoint, IChartGradientStop, IChartLinearGradient } from './chart-color';
 export type { ChartDescription } from './chart-description';
 export * from './chart-types';
 export * from './configuration';

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

@@ -1,6 +1,6 @@
-import type { AreaLineStyle } from '@univerjs-pro/engine-chart';
+import type { AreaLineStyle, IChartLineSeriesPatch } from '@univerjs-pro/engine-chart';
 import { FCartesianChartBuilder } from '../f-cartesian-chart-builder';
-export declare class FAreaChartBuilder extends FCartesianChartBuilder {
+export declare class FAreaChartBuilder extends FCartesianChartBuilder<Omit<IChartLineSeriesPatch, 'selector'>> {
     /**
      * Sets the area line style configuration and returns this builder for chaining.
      *

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

@@ -0,0 +1,5 @@
+import type { IChartSolidSeriesPatch, IChartSolidSeriesStyleSpec } from '@univerjs-pro/engine-chart';
+import { FCartesianChartBuilder } from '../f-cartesian-chart-builder';
+/** Boxplot keeps its existing automatic preset but does not expose explicit gradients. */
+export declare class FBoxplotChartBuilder extends FCartesianChartBuilder<Omit<IChartSolidSeriesPatch, 'selector'>, IChartSolidSeriesStyleSpec> {
+}

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

@@ -1,6 +1,6 @@
-import type { IChartBubbleMappingSpec } from '@univerjs-pro/engine-chart';
+import type { IChartBubbleMappingSpec, IChartSolidSeriesPatch, IChartSolidSeriesStyleSpec } from '@univerjs-pro/engine-chart';
 import { FCartesianChartBuilder } from '../f-cartesian-chart-builder';
-export declare class FBubbleChartBuilder extends FCartesianChartBuilder {
+export declare class FBubbleChartBuilder extends FCartesianChartBuilder<Omit<IChartSolidSeriesPatch, 'selector'>, IChartSolidSeriesStyleSpec> {
     /**
      * Sets the bubble mapping configuration and returns this builder for chaining.
      *

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

@@ -1,6 +1,6 @@
-import type { IChartSeriesBorderSpec } from '@univerjs-pro/engine-chart';
+import type { IChartLineSeriesPatch, IChartSeriesBorderSpec } from '@univerjs-pro/engine-chart';
 import { FCartesianChartBuilder } from '../f-cartesian-chart-builder';
-export declare class FLineChartBuilder extends FCartesianChartBuilder {
+export declare class FLineChartBuilder extends FCartesianChartBuilder<Omit<IChartLineSeriesPatch, 'selector'>> {
     /**
      * Sets the line style configuration and returns this builder for chaining.
      *

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

@@ -1,6 +1,47 @@
-import type { IChartPieLabelSpec } from '@univerjs-pro/engine-chart';
+import type { IChartPieLabelSpec, IChartSliceStyleSpec } from '@univerjs-pro/engine-chart';
 import { FChartBuilderBase } from '../f-chart-builder-base';
 export declare class FPieChartBuilder extends FChartBuilderBase {
+    /**
+     * Sets the style for the materialized slice at `index`.
+     *
+     * This method executes synchronously.
+     *
+     * @param index The zero-based slice index.
+     * @param value The slice style patch.
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * import { chartLinearGradient } from '@univerjs-pro/engine-chart';
+     *
+     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
+     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Pie);
+     * const color = chartLinearGradient({
+     *     start: { x: 0, y: 0 },
+     *     end: { x: 1, y: 1 },
+     *     stops: [
+     *         { offset: 0, color: '#fff1b8' },
+     *         { offset: 1, color: '#faad14' },
+     *     ],
+     * });
+     * builder.setSliceStyle(0, { color });
+     * ```
+     */
+    setSliceStyle(index: number, value: IChartSliceStyleSpec): this;
+    /**
+     * Clears the authored style for the materialized slice at `index`.
+     *
+     * This method executes synchronously.
+     *
+     * @param index The zero-based slice index.
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
+     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Pie);
+     * builder.clearSliceStyle(0);
+     * ```
+     */
+    clearSliceStyle(index: number): this;
     /**
      * Sets the doughnut hole configuration and returns this builder for chaining.
      *

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

@@ -1,5 +1,43 @@
 import type { IChartRelationForceSpec, LinePointShape, RelationChartLayoutEnum } from '@univerjs-pro/engine-chart';
 import { FChartBuilderBase } from '../f-chart-builder-base';
+/**
+ * Configures a relation chart.
+ *
+ * @remarks
+ * Relation chart sources are recognized in the following order:
+ *
+ * 1. **Co-word matrix**. For `N` node rows, the converted chart data must contain `N + 2`
+ *    dimension headers and `N + 1` source columns. Headers starting at index `2`
+ *    provide node names, source column `1` provides each node's category, and numeric matrix cells
+ *    provide link weights. This format is checked before the edge-list format.
+ *    Use this format when nodes need different categories.
+ * 2. **Edge list**. Column `0` is the source node and column `1` is the target node. Both must
+ *    contain non-empty strings. An optional numeric weight column must contain finite, non-negative
+ *    values; without one, every link has weight `1`.
+ *
+ * A two-column edge list is treated as unweighted. A three-column edge list uses column `2` as its
+ * weight automatically. If the range has more than three columns, select exactly one weight column
+ * with {@link FChartBuilderBase.setValueFields}; selecting multiple weight columns or either endpoint
+ * column makes the source invalid. A weighted edge list creates at most one category, named after
+ * the selected weight column when that column has a non-empty header. An unweighted edge list
+ * creates no categories.
+ *
+ * @example
+ * A worksheet range `A1:C4` can contain this weighted edge list:
+ *
+ * | Source | Target | Weight |
+ * | --- | --- | ---: |
+ * | A | B | 5 |
+ * | A | C | 3 |
+ * | C | B | 2 |
+ *
+ * ```ts
+ * worksheet.charts.create()
+ *     .setSource('A1:C4')
+ *     .setType(univerAPI.Enum.ChartTypeString.Relation)
+ *     .setValueFields([2]);
+ * ```
+ */
 export declare class FRelationChartBuilder extends FChartBuilderBase {
     /**
      * Sets the layout configuration and returns this builder for chaining.

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

@@ -1,6 +1,6 @@
-import type { IChartScatterMappingSpec } from '@univerjs-pro/engine-chart';
+import type { IChartScatterMappingSpec, IChartSolidSeriesPatch, IChartSolidSeriesStyleSpec } from '@univerjs-pro/engine-chart';
 import { FCartesianChartBuilder } from '../f-cartesian-chart-builder';
-export declare class FScatterChartBuilder extends FCartesianChartBuilder {
+export declare class FScatterChartBuilder extends FCartesianChartBuilder<Omit<IChartSolidSeriesPatch, 'selector'>, IChartSolidSeriesStyleSpec> {
     /**
      * Sets the scatter mapping configuration and returns this builder for chaining.
      *

package/lib/types/facade/builders/index.d.ts

@@ -1,4 +1,5 @@
 export { FAreaChartBuilder } from './f-area-chart-builder';
+export { FBoxplotChartBuilder } from './f-boxplot-chart-builder';
 export { FBubbleChartBuilder } from './f-bubble-chart-builder';
 export { FCombinationChartBuilder } from './f-combination-chart-builder';
 export { FFunnelChartBuilder } from './f-funnel-chart-builder';

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

@@ -1,5 +1,5 @@
 import type { ChartTypeString } from '@univerjs-pro/engine-chart';
-import type { FAreaChartBuilder, FBubbleChartBuilder, FCombinationChartBuilder, FFunnelChartBuilder, FHeatmapChartBuilder, FLineChartBuilder, FParetoChartBuilder, FPieChartBuilder, FRadarChartBuilder, FRelationChartBuilder, FScatterChartBuilder, FWaterfallChartBuilder, FWordCloudChartBuilder } from './builders';
+import type { FAreaChartBuilder, FBoxplotChartBuilder, FBubbleChartBuilder, FCombinationChartBuilder, FFunnelChartBuilder, FHeatmapChartBuilder, FLineChartBuilder, FParetoChartBuilder, FPieChartBuilder, FRadarChartBuilder, FRelationChartBuilder, FScatterChartBuilder, FWaterfallChartBuilder, FWordCloudChartBuilder } from './builders';
 import type { FCartesianChartBuilder } from './f-cartesian-chart-builder';
 import type { FChartBuilderBase } from './f-chart-builder-base';
 export interface IChartBuilderTypeMap {
@@ -26,5 +26,5 @@ export interface IChartBuilderTypeMap {
     [ChartTypeString.Pareto]: FParetoChartBuilder;
     [ChartTypeString.Sankey]: FChartBuilderBase;
     [ChartTypeString.Heatmap]: FHeatmapChartBuilder;
-    [ChartTypeString.Boxplot]: FCartesianChartBuilder;
+    [ChartTypeString.Boxplot]: FBoxplotChartBuilder;
 }

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

@@ -1,6 +1,6 @@
 import type { ChartAllSeriesStyleTarget, ChartAxisPointerTarget, ChartPublicSeriesSelector, ChartSeriesClearTarget, ChartSeriesTrendlineSelector, ChartTrendlineSelector, ChartTrendlineValue, IChartAxisPointerSpec, IChartBarSpec, 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'>> extends FAxisChartBuilder {
+export declare class FCartesianChartBuilder<TSeriesPatch extends Omit<IChartSeriesPatch, 'selector'> = Omit<IChartSeriesPatch, 'selector'>, TSeriesStyle extends IChartSeriesStyleSpec = IChartSeriesStyleSpec> extends FAxisChartBuilder {
     readonly __seriesPatchType?: TSeriesPatch;
     setBar(value: IChartBarSpec): this;
     clearBar(): this;
@@ -14,9 +14,19 @@ export declare class FCartesianChartBuilder<TSeriesPatch extends Omit<IChartSeri
      * @returns This builder for chaining.
      * @example
      * ```ts
+     * import { chartLinearGradient } from '@univerjs-pro/engine-chart';
+     *
      * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Line);
-     * builder.setSeries(0, { color: '#1677ff' });
+     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Column);
+     * const color = chartLinearGradient({
+     *     start: { x: 0, y: 1 },
+     *     end: { x: 0, y: 0 },
+     *     stops: [
+     *         { offset: 0, color: 'rgba(22, 119, 255, 0)' },
+     *         { offset: 1, color: '#1677ff' },
+     *     ],
+     * });
+     * builder.setSeries(0, { color });
      * ```
      */
     setSeries(selector: ChartPublicSeriesSelector, patch: TSeriesPatch): this;
@@ -50,7 +60,7 @@ export declare class FCartesianChartBuilder<TSeriesPatch extends Omit<IChartSeri
      * builder.setAllSeriesStyle({ color: '#1677ff', fillOpacity: 0.8 });
      * ```
      */
-    setAllSeriesStyle(style: IChartSeriesStyleSpec): this;
+    setAllSeriesStyle(style: TSeriesStyle): this;
     /**
      * Clears persistent defaults inherited by every series.
      *

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

@@ -195,6 +195,37 @@ export declare class FChartBuilderBase<TBuilder extends ChartBuilder = ChartBuil
      * ```
      */
     clearAppearance(target?: ChartAppearanceTarget): this;
+    /**
+     * Enables or disables the automatic gradient preset for supported chart marks.
+     *
+     * Explicit gradient colors configured on a series or slice take precedence over this preset.
+     * This method executes synchronously.
+     *
+     * @param value Whether to apply the chart type's automatic gradient preset.
+     * @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);
+     * ```
+     */
+    setAutoGradientFill(value: boolean): this;
+    /**
+     * Clears the automatic-gradient override and restores the chart type's default behavior.
+     *
+     * This method executes synchronously.
+     *
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
+     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Column);
+     * builder.setAutoGradientFill(true);
+     * builder.resetAutoGradientFill();
+     * ```
+     */
+    resetAutoGradientFill(): this;
     /**
      * Sets the invalid value strategy configuration and returns this builder for chaining.
      *

package/lib/types/index.d.ts

@@ -1,8 +1,8 @@
-export type { ChartDescription, ChartLegendSpec, ChartPublicSeriesSelector, ChartSeriesSelector, ChartSeriesTrendlineSelector, ChartSubtitleSpec, ChartTitleSpec, IChartAggregationSpec, IChartAppearanceSpec, IChartAreaSpec, IChartAxesSpec, IChartAxisBindingDescription, IChartAxisLabelSpec, IChartAxisPointerSpec, IChartAxisSpec, IChartBarSpec, IChartBubbleMappingSpec, IChartDescription, IChartFontSpec, IChartFunnelSpec, IChartHeatmapLabelSpec, IChartHeatmapSpec, IChartLegendOptions, IChartMappingSpec, IChartMarkLineLabelSpec, IChartMarkLineSpec, IChartParetoBarLabelStyleSpec, IChartParetoBarStyleSpec, IChartParetoBorderStyleSpec, IChartParetoLineLabelStyleSpec, IChartParetoLineStyleSpec, IChartParetoPointStyleSpec, IChartParetoSpec, IChartPieLabelSpec, IChartPieSpec, IChartRadarSpec, IChartRelationForceSpec, IChartRelationSpec, IChartScatterMappingSpec, IChartSeriesBorderSpec, IChartSeriesDescription, IChartSeriesLabelSpec, IChartSeriesPatch, IChartSeriesPointSpec, IChartSeriesStyleSpec, IChartSubtitleOptions, IChartTitleOptions, IChartTrendlineSpec, IChartWaterfallConnectorStyleSpec, IChartWaterfallPointRoleSpec, IChartWaterfallSpec, IChartWordCloudDescription, IChartWordCloudSpec, IInlineChartBuilderAdapter, IInlineChartHostPatch, IResolvedChartData, } from './chart-builder';
-export { AREA_CHART_TYPES, AXIS_CHART_TYPES, CARTESIAN_CHART_TYPES, ChartAggregationTarget, ChartAllSeriesStyleTarget, ChartAppearanceTarget, ChartAxisName, ChartAxisPointerTarget, ChartAxisTarget, ChartAxisTickPosition, ChartSeriesAxis, ChartSeriesClearTarget, ChartSeriesTypeString, ChartTypeString, ChartVisualMapType, ChartWaterfallStyleTarget, ChartWordCloudShapeSource, DEFAULT_CHART_TYPE, } from './chart-builder';
-export { ChartBuilder, chartTypeToBits, clearAggregation, clearAllSeriesStyle, clearAppearance, clearAreaLineStyle, clearAxisPointer, clearAxisTitle, clearBar, clearBubbleMapping, clearCategoryField, clearCellLabel, clearCumulativeLineStyle, clearDoughnutHole, clearLegend, clearLineStyle, clearMarkLines, clearPalette, clearMaskImage, clearParetoBarStyle, clearPieLabel, clearRelationForce, clearRightYAxis, clearScatterMapping, clearSeries, clearSliceBorderColor, clearSubtitle, clearTheme, clearTitle, clearTrendlines, clearValueFields, clearValueRange, clearValueSuffix, clearValueUnit, clearWaterfallConnector, clearWaterfallStyle, clearXAxis, clearYAxis, describeChartModel, DetachedChartBuilderAdapter, InlineChartBuilder, removeTrendline, resetCircularLabelRotation, resetCombinationSeriesAxis, resetCombinationSeriesType, resetDecimalPlaces, resetEmphasisEnabled, resetExplosion, resetFunnelGap, resetHalfPie, resetIncludeZeroValues, resetInvalidValueStrategy, resetLabelLineVisible, resetPaddingAngleEnabled, resetRadarFill, resetRadarShape, resetRelationLayout, resetRelationNodeShape, resetRosePie, resetUseAbsoluteValue, resetUseDateAxis, resetUseSubtotal, resetUseValueAsSymbolSize, resetValueScale, resetVisualMapType, resetWaterfallStackType, resetWordCloudRepeat, resetWordCloudShape, resolveChartDescriptionMetadata, resolveChartModelData, resolveInlineChartDataSet, setAggregation, setAllSeriesStyle, setAppearance, setAreaLineStyle, setAxisPointer, setAxisTitle, setBar, setBubbleMapping, setCategoryField, setCellLabel, setCircularLabelRotation, setCombinationSeriesAxis, setCombinationSeriesType, setCumulativeLineStyle, setDecimalPlaces, setDoughnutHole, setEmphasisEnabled, setExplosion, setFunnelGap, setHalfPie, setIncludeZeroValues, setInvalidValueStrategy, setLabelLineVisible, setLegend, setLineStyle, setMarkLines, setMaskImage, setPaddingAngleEnabled, setPalette, setParetoBarStyle, setPieLabel, setRadarFill, setRadarShape, setRelationForce, setRelationLayout, setRelationNodeShape, setRightYAxis, setRosePie, setScatterMapping, setSeries, setSliceBorderColor, setSubtitle, setTheme, setTitle, setTrendline, setUseAbsoluteValue, setUseDateAxis, setUseSubtotal, setUseValueAsSymbolSize, setValueFields, setValueRange, setValueScale, setValueSuffix, setValueUnit, setVisualMapType, setWaterfallConnector, setWaterfallPointRoles, setWaterfallStackType, setWaterfallStyle, setWordCloudRepeat, setWordCloudShape, setXAxis, setYAxis, toChartModelConfig, toCompleteChartModelConfig, } from './chart-builder';
+export type { ChartColor, ChartDescription, ChartLegendSpec, ChartLinearGradientInput, ChartPublicSeriesSelector, ChartSeriesSelector, ChartSeriesTrendlineSelector, ChartSubtitleSpec, ChartTitleSpec, IChartAggregationSpec, IChartAppearanceSpec, IChartAreaSpec, IChartAxesSpec, IChartAxisBindingDescription, IChartAxisLabelSpec, IChartAxisPointerSpec, IChartAxisSpec, IChartBarSpec, IChartBubbleMappingSpec, IChartDescription, IChartFontSpec, IChartFunnelSpec, IChartGradientPoint, IChartGradientStop, IChartHeatmapLabelSpec, IChartHeatmapSpec, IChartLegendOptions, IChartLinearGradient, IChartLineSeriesPatch, IChartMappingSpec, IChartMarkLineLabelSpec, IChartMarkLineSpec, IChartParetoBarLabelStyleSpec, IChartParetoBarStyleSpec, IChartParetoBorderStyleSpec, IChartParetoLineLabelStyleSpec, IChartParetoLineStyleSpec, IChartParetoPointStyleSpec, IChartParetoSpec, IChartPieLabelSpec, IChartPieSpec, IChartRadarSpec, IChartRelationForceSpec, IChartRelationSpec, IChartScatterMappingSpec, IChartSeriesBorderSpec, IChartSeriesDataPointStyleSpec, IChartSeriesDescription, IChartSeriesLabelSpec, IChartSeriesPatch, IChartSeriesPointSpec, IChartSeriesStyleSpec, IChartSliceStyleSpec, IChartSolidSeriesPatch, IChartSolidSeriesStyleSpec, IChartSubtitleOptions, IChartSymbolDataPointStyleSpec, IChartTitleOptions, IChartTrendlineSpec, IChartWaterfallConnectorStyleSpec, IChartWaterfallPointRoleSpec, IChartWaterfallSpec, IChartWordCloudDescription, IChartWordCloudSpec, IInlineChartBuilderAdapter, IInlineChartHostPatch, IResolvedChartData, } from './chart-builder';
+export { AREA_CHART_TYPES, AXIS_CHART_TYPES, CARTESIAN_CHART_TYPES, CHART_LINEAR_GRADIENT_TYPE, ChartAggregationTarget, ChartAllSeriesStyleTarget, ChartAppearanceTarget, ChartAxisName, ChartAxisPointerTarget, ChartAxisTarget, ChartAxisTickPosition, chartLinearGradient, ChartSeriesAxis, ChartSeriesClearTarget, ChartSeriesTypeString, ChartTypeString, ChartVisualMapType, ChartWaterfallStyleTarget, ChartWordCloudShapeSource, DEFAULT_CHART_TYPE, } from './chart-builder';
+export { ChartBuilder, chartTypeToBits, clearAggregation, clearAllSeriesStyle, clearAppearance, clearAreaLineStyle, clearAxisPointer, clearAxisTitle, clearBar, clearBubbleMapping, clearCategoryField, clearCellLabel, clearCumulativeLineStyle, clearDoughnutHole, clearLegend, clearLineStyle, clearMarkLines, clearMaskImage, clearPalette, clearParetoBarStyle, clearPieLabel, clearRelationForce, clearRightYAxis, clearScatterMapping, clearSeries, clearSliceBorderColor, clearSliceStyle, clearSubtitle, clearTheme, clearTitle, clearTrendlines, clearValueFields, clearValueRange, clearValueSuffix, clearValueUnit, clearWaterfallConnector, clearWaterfallStyle, clearXAxis, clearYAxis, describeChartModel, DetachedChartBuilderAdapter, InlineChartBuilder, removeTrendline, resetAutoGradientFill, resetCircularLabelRotation, resetCombinationSeriesAxis, resetCombinationSeriesType, resetDecimalPlaces, resetEmphasisEnabled, resetExplosion, resetFunnelGap, resetHalfPie, resetIncludeZeroValues, resetInvalidValueStrategy, resetLabelLineVisible, resetPaddingAngleEnabled, resetRadarFill, resetRadarShape, resetRelationLayout, resetRelationNodeShape, resetRosePie, resetUseAbsoluteValue, resetUseDateAxis, resetUseSubtotal, resetUseValueAsSymbolSize, resetValueScale, resetVisualMapType, resetWaterfallStackType, resetWordCloudRepeat, resetWordCloudShape, resolveChartDescriptionMetadata, resolveChartModelData, resolveInlineChartDataSet, setAggregation, setAllSeriesStyle, setAppearance, setAreaLineStyle, setAutoGradientFill, setAxisPointer, setAxisTitle, setBar, setBubbleMapping, setCategoryField, setCellLabel, setCircularLabelRotation, setCombinationSeriesAxis, setCombinationSeriesType, setCumulativeLineStyle, setDecimalPlaces, setDoughnutHole, setEmphasisEnabled, setExplosion, setFunnelGap, setHalfPie, setIncludeZeroValues, setInvalidValueStrategy, setLabelLineVisible, setLegend, setLineStyle, setMarkLines, setMaskImage, setPaddingAngleEnabled, setPalette, setParetoBarStyle, setPieLabel, setRadarFill, setRadarShape, setRelationForce, setRelationLayout, setRelationNodeShape, setRightYAxis, setRosePie, setScatterMapping, setSeries, setSliceBorderColor, setSliceStyle, setSubtitle, setTheme, setTitle, setTrendline, setUseAbsoluteValue, setUseDateAxis, setUseSubtotal, setUseValueAsSymbolSize, setValueFields, setValueRange, setValueScale, setValueSuffix, setValueUnit, setVisualMapType, setWaterfallConnector, setWaterfallPointRoles, setWaterfallStackType, setWaterfallStyle, setWordCloudRepeat, setWordCloudShape, setXAxis, setYAxis, toChartModelConfig, toCompleteChartModelConfig, } from './chart-builder';
 export type { ChartPendingConfig, ChartTrendlineSelector, ChartTrendlineValue, IChartBuilderAdapter, IChartCreateConfig, } from './chart-builder';
-export { AreaLineStyle, BarShape, AxisAlignEnum, AxisValueType, CategoryType, ChartAttributeBits, ChartAxisDimension, ChartBorderDashType, ChartMarkLineLabelPosition, ChartSemanticAxis, ChartSourceDataTypeEnum, ChartTrendlineType, ChartTypeBits, ChartWaterfallPointRole, DataOrientation, InvalidValueType, IRuntimeAxisPosition, IRuntimeAxisPriority, LabelAlignEnum, LabelContentType, LegendPositionEnum, LinePointShape, ParetoSeriesIndex, ParetoSeriesPart, PieLabelPosition, RadarShape, RelationChartLayoutEnum, SelectModeEnum, SeriesLabelPosition, StackType, TextAlign, TextVerticalAlign, TitlePositionEnum, WaterfallSeriesTypeEnum, WaterfallStackTypeEnum, WordCloudShapeEnum, } from './enum';
+export { AreaLineStyle, AxisAlignEnum, AxisValueType, BarShape, CategoryType, ChartAttributeBits, ChartAxisDimension, ChartBorderDashType, ChartMarkLineLabelPosition, ChartSemanticAxis, ChartSourceDataTypeEnum, ChartTrendlineType, ChartTypeBits, ChartWaterfallPointRole, DataOrientation, InvalidValueType, IRuntimeAxisPosition, IRuntimeAxisPriority, LabelAlignEnum, LabelContentType, LegendPositionEnum, LinePointShape, ParetoSeriesIndex, ParetoSeriesPart, PieLabelPosition, RadarShape, RelationChartLayoutEnum, SelectModeEnum, SeriesLabelPosition, StackType, TextAlign, TextVerticalAlign, TitlePositionEnum, WaterfallSeriesTypeEnum, WaterfallStackTypeEnum, WordCloudShapeEnum, } from './enum';
 export { buildChartData, RelationColumnIndex } from './models/chart-data-operators/build-chart-data';
 export { CartesianPointRoleIndex, CartesianPointValueIndex } from './models/chart-data-operators/cartesian-point-data';
 export { defaultChartContextOperators, findCategoryIndexes, findCategoryOperator, findHeaderOperator, findSeriesOperator, generateChartModelContextByOperators, pieSeriesFilterOperator, } from './models/chart-data-operators/operators';

package/lib/types/models/chart-element-edit-overlay/chart-element-edit-overlay.d.ts

@@ -1,4 +1,5 @@
 import type { IChartElementBounds, IChartElementHit } from '../../types';
+import type { ECharts } from '../../utils/echarts';
 import type { ChartElementEditBorderType, IChartElementEditOverlayPalette } from './types';
 export declare class ChartElementEditOverlay {
     private readonly _getInstance;
@@ -11,7 +12,7 @@ export declare class ChartElementEditOverlay {
     private _hoverBorderHitKey;
     private _fixedBorder;
     private _fixedBorderBounds;
-    constructor(_getInstance: () => echarts.ECharts | null, _getContainer?: () => HTMLElement | null | undefined, _paletteOverride?: Partial<IChartElementEditOverlayPalette> | undefined);
+    constructor(_getInstance: () => ECharts | null, _getContainer?: () => HTMLElement | null | undefined, _paletteOverride?: Partial<IChartElementEditOverlayPalette> | undefined);
     ensure(): any;
     remove(): void;
     clearAll(): void;