@univerjs-pro/engine-chart 1.0.0-alpha.3 → 1.0.0-alpha.4

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

@@ -0,0 +1,245 @@
+import type { ChartAxisTarget, IChartAxisSpec, IChartMarkLineSpec } from '@univerjs-pro/engine-chart';
+import { FChartBuilderBase } from './f-chart-builder-base';
+export declare abstract class FAxisChartBuilder extends FChartBuilderBase {
+    /**
+     * Replaces all fixed-axis mark lines.
+     *
+     * Omitted line-style fields use a 1 px solid stroke at full opacity and inherit the carrier
+     * 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`.
+     *
+     * @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;
+     * ```
+     */
+    setMarkLines(lines: readonly IChartMarkLineSpec[]): this;
+    /**
+     * Clears all fixed-axis mark lines.
+     *
+     * Read the cleared value from `builder.describe().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;
+     * ```
+     */
+    clearMarkLines(): this;
+    /**
+     * Sets the xaxis configuration and returns this builder for chaining.
+     *
+     * This method executes synchronously.
+     *
+     * @param value The semantic value to record.
+     * @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' });
+     * ```
+     */
+    setXAxis(value: IChartAxisSpec): this;
+    /**
+     * Clears the xaxis configuration and returns this builder for chaining.
+     *
+     * This method executes synchronously.
+     *
+     * @param target The configuration field to clear or reset.
+     * @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);
+     * ```
+     */
+    clearXAxis(target?: ChartAxisTarget): this;
+    /**
+     * Sets the yaxis configuration and returns this builder for chaining.
+     *
+     * This method executes synchronously.
+     *
+     * @param value The semantic value to record.
+     * @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' });
+     * ```
+     */
+    setYAxis(value: IChartAxisSpec): this;
+    /**
+     * Clears the yaxis configuration and returns this builder for chaining.
+     *
+     * This method executes synchronously.
+     *
+     * @param target The configuration field to clear or reset.
+     * @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);
+     * ```
+     */
+    clearYAxis(target?: ChartAxisTarget): this;
+    /**
+     * Sets the right yaxis configuration and returns this builder for chaining.
+     *
+     * This method executes synchronously.
+     *
+     * @param value The semantic value to record.
+     * @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' });
+     * ```
+     */
+    setRightYAxis(value: IChartAxisSpec): this;
+    /**
+     * Clears the right yaxis configuration and returns this builder for chaining.
+     *
+     * This method executes synchronously.
+     *
+     * @param target The configuration field to clear or reset.
+     * @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);
+     * ```
+     */
+    clearRightYAxis(target?: ChartAxisTarget): this;
+    /**
+     * Sets the xaxis title configuration and returns this builder for chaining.
+     *
+     * This method executes synchronously.
+     *
+     * @param value The semantic value to record.
+     * @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');
+     * ```
+     */
+    setXAxisTitle(value: string): this;
+    /**
+     * Clears the xaxis title configuration and returns this builder for chaining.
+     *
+     * 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.Line);
+     * builder.clearXAxisTitle();
+     * ```
+     */
+    clearXAxisTitle(): this;
+    /**
+     * Sets the yaxis title configuration and returns this builder for chaining.
+     *
+     * This method executes synchronously.
+     *
+     * @param value The semantic value to record.
+     * @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');
+     * ```
+     */
+    setYAxisTitle(value: string): this;
+    /**
+     * Clears the yaxis title configuration and returns this builder for chaining.
+     *
+     * 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.Line);
+     * builder.clearYAxisTitle();
+     * ```
+     */
+    clearYAxisTitle(): this;
+    /**
+     * Sets the right yaxis title configuration and returns this builder for chaining.
+     *
+     * This method executes synchronously.
+     *
+     * @param value The semantic value to record.
+     * @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');
+     * ```
+     */
+    setRightYAxisTitle(value: string): this;
+    /**
+     * Clears the right yaxis title configuration and returns this builder for chaining.
+     *
+     * 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.Line);
+     * builder.clearRightYAxisTitle();
+     * ```
+     */
+    clearRightYAxisTitle(): this;
+    /**
+     * Sets the use date axis configuration and returns this builder for chaining.
+     *
+     * This method executes synchronously.
+     *
+     * @param value The semantic value to record.
+     * @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);
+     * ```
+     */
+    setUseDateAxis(value: boolean): this;
+    /**
+     * Restores the default of using a category axis instead of a date axis and returns this builder for chaining.
+     *
+     * 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.Line);
+     * builder.resetUseDateAxis();
+     * ```
+     */
+    resetUseDateAxis(): this;
+}

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

@@ -0,0 +1,146 @@
+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 {
+    readonly __seriesPatchType?: TSeriesPatch;
+    setBar(value: IChartBarSpec): this;
+    clearBar(): this;
+    /**
+     * Sets the series configuration and returns this builder for chaining.
+     *
+     * This method executes synchronously.
+     *
+     * @param selector The target series selector.
+     * @param patch The semantic configuration patch owned by this method.
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
+     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Line);
+     * builder.setSeries(0, { color: '#1677ff' });
+     * ```
+     */
+    setSeries(selector: ChartPublicSeriesSelector, patch: TSeriesPatch): this;
+    /**
+     * Clears the series configuration and returns this builder for chaining.
+     *
+     * This method executes synchronously.
+     *
+     * @param selector The target series selector.
+     * @param target The configuration field to clear or reset.
+     * @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;
+    /**
+     * Sets persistent defaults inherited by every current and future series.
+     *
+     * This method executes synchronously.
+     *
+     * @param style The global series style defaults.
+     * @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: IChartSeriesStyleSpec): this;
+    /**
+     * Clears persistent defaults inherited by every series.
+     *
+     * This method executes synchronously.
+     *
+     * @param target The global series style field to clear, or omit it to clear all defaults.
+     * @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);
+     * ```
+     */
+    clearAllSeriesStyle(target?: ChartAllSeriesStyleTarget): this;
+    /**
+     * Sets the trendline configuration and returns this builder for chaining.
+     *
+     * This method executes synchronously.
+     *
+     * @param selector The target series selector.
+     * @param value The semantic value to record.
+     * @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 });
+     * ```
+     */
+    setTrendline(selector: ChartSeriesTrendlineSelector, value: ChartTrendlineValue): this;
+    /**
+     * Remove trendline.
+     *
+     * This method executes synchronously.
+     *
+     * @param selector The target series selector.
+     * @param trendline The trendline configuration to append.
+     * @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);
+     * ```
+     */
+    removeTrendline(selector: ChartSeriesTrendlineSelector, trendline: ChartTrendlineSelector): this;
+    /**
+     * Clears the trendlines configuration and returns this builder for chaining.
+     *
+     * This method executes synchronously.
+     *
+     * @param selector The target series selector.
+     * @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);
+     * ```
+     */
+    clearTrendlines(selector?: ChartSeriesTrendlineSelector): this;
+    /**
+     * Sets the axis pointer configuration and returns this builder for chaining.
+     *
+     * This method executes synchronously.
+     *
+     * @param value The semantic value to record.
+     * @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' });
+     * ```
+     */
+    setAxisPointer(value: IChartAxisPointerSpec): this;
+    /**
+     * Clears the axis pointer configuration and returns this builder for chaining.
+     *
+     * This method executes synchronously.
+     *
+     * @param target The configuration field to clear or reset.
+     * @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);
+     * ```
+     */
+    clearAxisPointer(target?: ChartAxisPointerTarget): this;
+}

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

@@ -0,0 +1,82 @@
+import type { ChartBuilder, ChartDescription, IChartRenderModelImageExportOptions, IChartRenderModelImageExportResult, IResolvedChartData } from '@univerjs-pro/engine-chart';
+import type { DeepReadonly } from '@univerjs/core';
+import type { IChartBuilderFacadeContext, IChartBuilderFacadeContextAccess } from './internal/chart-builder-facade-context';
+export declare abstract class FChartBase<TDescription extends ChartDescription = ChartDescription, TBuilder extends ChartBuilder = ChartBuilder> implements IChartBuilderFacadeContextAccess {
+    protected readonly _context: IChartBuilderFacadeContext<TBuilder>;
+    protected readonly _builder: TBuilder;
+    constructor(_context: IChartBuilderFacadeContext<TBuilder>);
+    /**
+     * Returns the current id value.
+     *
+     * This method executes synchronously.
+     *
+     * @returns The host-owned chart ID.
+     * @example
+     * ```ts
+     * const chart = univerAPI.getActiveWorkbook().getActiveSheet().charts.list()[0];
+     * chart.getId();
+     * ```
+     */
+    getId(): string;
+    /**
+     * Returns a detached read-only description including pending builder changes.
+     *
+     * This method executes synchronously.
+     *
+     * @returns An immutable description including pending builder changes.
+     * @example
+     * ```ts
+     * const chart = univerAPI.getActiveWorkbook().getActiveSheet().charts.list()[0];
+     * chart.describe();
+     * ```
+     */
+    describe(): DeepReadonly<TDescription>;
+    /**
+     * Resolves fresh, read-only chart data from the latest host data and pending builder changes.
+     *
+     * This method executes synchronously and does not commit pending changes. It is available
+     * only after the builder is hosted; for a newly created builder, call it on the value returned
+     * by `charts.insert(builder)`.
+     *
+     * @returns Fresh immutable category and series data for the effective chart configuration.
+     * @throws If the builder has not been inserted into a host.
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
+     * const chart = fWorksheet.charts.list()[0];
+     * chart.setValueFields([1, 2]);
+     * const data = chart.resolveData();
+     * console.log(data.series);
+     * ```
+     */
+    resolveData(): DeepReadonly<IResolvedChartData>;
+    /**
+     * Commits all pending builder changes synchronously.
+     *
+     * This method executes synchronously.
+     *
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * const chart = univerAPI.getActiveWorkbook().getActiveSheet().charts.list()[0];
+     * chart.commit();
+     * ```
+     */
+    commit(): this;
+    /**
+     * Renders the current chart as an image.
+     *
+     * This method completes asynchronously.
+     *
+     * @param options The image export options.
+     * @returns A promise resolving to the exported image, or null when unavailable.
+     * @example
+     * ```ts
+     * const chart = univerAPI.getActiveWorkbook().getActiveSheet().charts.list()[0];
+     * const image = await chart.exportImage({ pixelRatio: 2 });
+     * ```
+     */
+    exportImage(options?: IChartRenderModelImageExportOptions): Promise<IChartRenderModelImageExportResult | null>;
+}