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

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

@@ -1,27 +1,97 @@
+import type { IChartInfo, IChartSeriesPatch, IChartSeriesStyleSpec } from '@univerjs-pro/engine-chart';
 import { FCartesianChartBuilder } from '../f-cartesian-chart-builder';
 /**
  * Fluent builder for a one-field raw-sample Histogram.
  *
+ * Select exactly one numeric field containing individual observations. The renderer
+ * computes bins from those raw samples; do not pass pre-binned ranges or frequencies.
+ *
  * Histogram settings are persisted as authored. Rendering uses Scott Auto when explicit
  * binning is ineffective, never emits more than 1000 visible bins, and falls back to a
  * zero visual gap for ineffective gap values.
  *
- * @example
- * const chart = worksheet.charts.create()
- *   .setType(univerAPI.Enum.ChartTypeString.Histogram)
+ * @example Sheet
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+ * const chartInfo = fWorksheet
+ *   .newChart(univerAPI.Enum.ChartTypeString.Histogram)
+ *   .setSource('A1:A100')
+ *   .setHistogramField(0)
+ *   .setBinCount(12)
+ *   .setUnderflowThreshold(0)
+ *   .setOverflowThreshold(100)
+ *   .setBinGap(0.1)
+ *   .build();
+ * await fWorksheet.insertChart(chartInfo);
+ * ```
+ *
+ * @example Doc
+ * ```ts
+ * const fDocument = univerAPI.getActiveDocument();
+ * const chartInfo = fDocument
+ *   .newChart(univerAPI.Enum.ChartTypeString.Histogram)
+ *   .setSource([['Duration'], [12], [18], [19], [25], [31], [35]])
+ *   .setHistogramField(0)
+ *   .setBinCount(12)
+ *   .setUnderflowThreshold(0)
+ *   .setOverflowThreshold(100)
+ *   .setBinGap(0.1)
+ *   .build();
+ * await fDocument.insertChart(chartInfo);
+ * ```
+ *
+ * @example Slide
+ * ```ts
+ * const fPresentation = univerAPI.getActivePresentation();
+ * const fSlide = fPresentation.getSlideByIndex(0);
+ * const chartInfo = fSlide
+ *   .newChart(univerAPI.Enum.ChartTypeString.Histogram)
+ *   .setSource([['Duration'], [12], [18], [19], [25], [31], [35]])
  *   .setHistogramField(0)
  *   .setBinCount(12)
- *   .setBinGap(0.1);
+ *   .setUnderflowThreshold(0)
+ *   .setOverflowThreshold(100)
+ *   .setBinGap(0.1)
+ *   .build();
+ * await fSlide.insertChart(chartInfo);
+ * ```
+ *
+ * @example Board
+ * ```ts
+ * const fBoard = univerAPI.getActiveBoard();
+ * const chartInfo = fBoard
+ *   .newChart(univerAPI.Enum.ChartTypeString.Histogram)
+ *   .setSource([['Duration'], [12], [18], [19], [25], [31], [35]])
+ *   .setHistogramField(0)
+ *   .setBinCount(12)
+ *   .setUnderflowThreshold(0)
+ *   .setOverflowThreshold(100)
+ *   .setBinGap(0.1)
+ *   .build();
+ * await fBoard.insertChart(chartInfo);
+ * ```
  */
-export declare class FHistogramChartBuilder extends FCartesianChartBuilder {
+export declare class FHistogramChartBuilder<TSource = never[], TDataSource = TSource, TInfo extends IChartInfo<TDataSource> = IChartInfo<TDataSource>> extends FCartesianChartBuilder<Omit<IChartSeriesPatch, 'selector'>, IChartSeriesStyleSpec, TSource, TDataSource, TInfo> {
     /**
      * Selects the only active Histogram value field by zero-based source index.
-     * @example `builder.setHistogramField(2)`
+     *
+     * @param index Zero-based source field index.
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * builder.setHistogramField(2);
+     * ```
      */
     setHistogramField(index: number): this;
     /**
      * Clears the active Histogram value field.
-     * @example `builder.clearHistogramField()`
+     *
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * builder.clearHistogramField();
+     * ```
      */
     clearHistogramField(): this;
     /**
@@ -29,46 +99,102 @@ export declare class FHistogramChartBuilder extends FCartesianChartBuilder {
      * when enabled edge bins still leave room for a regular bin. Other finite values remain
      * persisted and visible through `describe()` but render with Scott Auto. Non-finite calls
      * produce no Pending change.
-     * @example `builder.setBinCount(20)`
+     *
+     * @param count Total visible-bin count.
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * builder.setBinCount(20);
+     * ```
      */
     setBinCount(count: number): this;
     /**
      * Stores an explicit width. A positive finite width is effective only when the current
      * range produces at most 1000 visible bins; otherwise rendering uses Scott Auto without
      * rewriting the stored value. Non-finite calls produce no Pending change.
-     * @example `builder.setBinWidth(2.5)`
+     *
+     * @param width Bin width in source-value units.
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * builder.setBinWidth(2.5);
+     * ```
      */
     setBinWidth(width: number): this;
     /**
      * Removes explicit binning and restores runtime-only Scott Auto.
-     * @example `builder.resetBinning()`
+     *
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * builder.resetBinning();
+     * ```
      */
     resetBinning(): this;
     /**
      * Enables the inclusive `x <= threshold` Underflow bin. If both thresholds are present,
      * they are effective only when Underflow is less than Overflow. Non-finite calls are no-op.
-     * @example `builder.setUnderflowThreshold(0)`
+     *
+     * @param value Inclusive Underflow threshold.
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * builder.setUnderflowThreshold(0);
+     * ```
      */
     setUnderflowThreshold(value: number): this;
-    /** Disables Underflow. @example `builder.clearUnderflowThreshold()` */
+    /**
+     * Disables Underflow.
+     *
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * builder.clearUnderflowThreshold();
+     * ```
+     */
     clearUnderflowThreshold(): this;
     /**
      * Enables the exclusive `x > threshold` Overflow bin. An ineffective finite threshold
      * pair remains persisted but both thresholds are ignored for rendering. Non-finite calls are no-op.
-     * @example `builder.setOverflowThreshold(100)`
+     *
+     * @param value Exclusive Overflow threshold.
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * builder.setOverflowThreshold(100);
+     * ```
      */
     setOverflowThreshold(value: number): this;
-    /** Disables Overflow. @example `builder.clearOverflowThreshold()` */
+    /**
+     * Disables Overflow.
+     *
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * builder.clearOverflowThreshold();
+     * ```
+     */
     clearOverflowThreshold(): this;
     /**
      * Stores the visual gap ratio. Values from 0 through 0.9 are effective; other finite values
      * remain persisted but render with the 0.007-gap default. Non-finite calls are no-op.
-     * @example `builder.setBinGap(0.15)`
+     *
+     * @param value Gap ratio between adjacent bins.
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * builder.setBinGap(0.15);
+     * ```
      */
     setBinGap(value: number): this;
     /**
      * Removes the explicit gap and restores the 0.007 runtime default.
-     * @example `builder.resetBinGap()`
+     *
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * builder.resetBinGap();
+     * ```
      */
     resetBinGap(): this;
 }

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

@@ -1,6 +1,55 @@
-import type { IChartLineSeriesPatch, IChartSeriesBorderSpec } from '@univerjs-pro/engine-chart';
+import type { IChartInfo, IChartLineSeriesPatch, IChartSeriesBorderSpec, IChartSeriesStyleSpec } from '@univerjs-pro/engine-chart';
 import { FCartesianChartBuilder } from '../f-cartesian-chart-builder';
-export declare class FLineChartBuilder extends FCartesianChartBuilder<Omit<IChartLineSeriesPatch, 'selector'>> {
+/**
+ * Fluent, type-specific Builder for Line Charts.
+ *
+ * @example Sheet
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+ * const chartInfo = fWorksheet
+ *   .newChart(univerAPI.Enum.ChartTypeString.Line)
+ *   .setSource('A1:D8')
+ *   .setLineStyle({ width: 2 })
+ *   .build();
+ * await fWorksheet.insertChart(chartInfo);
+ * ```
+ *
+ * @example Doc
+ * ```ts
+ * const fDocument = univerAPI.getActiveDocument();
+ * const chartInfo = fDocument
+ *   .newChart(univerAPI.Enum.ChartTypeString.Line)
+ *   .setSource([['Month', 'Sales'], ['Jan', 120], ['Feb', 180]])
+ *   .setLineStyle({ width: 2 })
+ *   .build();
+ * await fDocument.insertChart(chartInfo);
+ * ```
+ *
+ * @example Slide
+ * ```ts
+ * const fPresentation = univerAPI.getActivePresentation();
+ * const fSlide = fPresentation.getSlideByIndex(0);
+ * const chartInfo = fSlide
+ *   .newChart(univerAPI.Enum.ChartTypeString.Line)
+ *   .setSource([['Month', 'Sales'], ['Jan', 120], ['Feb', 180]])
+ *   .setLineStyle({ width: 2 })
+ *   .build();
+ * await fSlide.insertChart(chartInfo);
+ * ```
+ *
+ * @example Board
+ * ```ts
+ * const fBoard = univerAPI.getActiveBoard();
+ * const chartInfo = fBoard
+ *   .newChart(univerAPI.Enum.ChartTypeString.Line)
+ *   .setSource([['Month', 'Sales'], ['Jan', 120], ['Feb', 180]])
+ *   .setLineStyle({ width: 2 })
+ *   .build();
+ * await fBoard.insertChart(chartInfo);
+ * ```
+ */
+export declare class FLineChartBuilder<TSource = never[], TDataSource = TSource, TInfo extends IChartInfo<TDataSource> = IChartInfo<TDataSource>> extends FCartesianChartBuilder<Omit<IChartLineSeriesPatch, 'selector'>, IChartSeriesStyleSpec, TSource, TDataSource, TInfo> {
     /**
      * Sets the line style configuration and returns this builder for chaining.
      *
@@ -13,8 +62,6 @@ export declare class FLineChartBuilder extends FCartesianChartBuilder<Omit<IChar
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Line);
      * builder.setLineStyle({ width: 2, color: '#1677ff' });
      * ```
      */
@@ -27,8 +74,6 @@ export declare class FLineChartBuilder extends FCartesianChartBuilder<Omit<IChar
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Line);
      * builder.clearLineStyle();
      * ```
      */

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

@@ -1,6 +1,81 @@
-import type { IChartParetoBarStyleSpec, IChartParetoLineStyleSpec } from '@univerjs-pro/engine-chart';
+import type { IChartInfo, IChartParetoBarStyleSpec, IChartParetoLineStyleSpec, IChartSeriesPatch, IChartSeriesStyleSpec } from '@univerjs-pro/engine-chart';
 import { FCartesianChartBuilder } from '../f-cartesian-chart-builder';
-export declare class FParetoChartBuilder extends FCartesianChartBuilder {
+/**
+ * Fluent, type-specific Builder for Pareto Charts.
+ *
+ * Select one category field with `setCategoryField()` and one numeric value field with
+ * `setValueFields([index])`. Field indexes are zero-based in the normalized data source.
+ * Explicit mapping is necessary when the source shape is ambiguous, such as a Sheet range
+ * containing only numeric values; without both roles, the Chart has no renderable series.
+ *
+ * Rows with the same category are aggregated. By default, zero and negative totals are
+ * excluded, the remaining categories are sorted from largest to smallest, and the renderer
+ * derives the cumulative-percentage line from the selected value field. Use
+ * `setIncludeZeroValues(true)` to retain zero totals; negative totals remain excluded.
+ *
+ * @example Sheet
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+ * const chartInfo = fWorksheet
+ *   .newChart(univerAPI.Enum.ChartTypeString.Pareto)
+ *   .setSource('A1:B8')
+ *   .setCategoryField(0)
+ *   .setValueFields([1])
+ *   .setBarStyle({ color: '#2563eb', opacity: 0.8 })
+ *   .setCumulativeLineStyle({ color: '#dc2626', width: 2 })
+ *   .setIncludeZeroValues(false)
+ *   .build();
+ * await fWorksheet.insertChart(chartInfo);
+ * ```
+ *
+ * @example Doc
+ * ```ts
+ * const fDocument = univerAPI.getActiveDocument();
+ * const chartInfo = fDocument
+ *   .newChart(univerAPI.Enum.ChartTypeString.Pareto)
+ *   .setSource([['Cause', 'Count'], ['A', 42], ['B', 28], ['C', 15]])
+ *   .setCategoryField(0)
+ *   .setValueFields([1])
+ *   .setBarStyle({ color: '#2563eb', opacity: 0.8 })
+ *   .setCumulativeLineStyle({ color: '#dc2626', width: 2 })
+ *   .setIncludeZeroValues(false)
+ *   .build();
+ * await fDocument.insertChart(chartInfo);
+ * ```
+ *
+ * @example Slide
+ * ```ts
+ * const fPresentation = univerAPI.getActivePresentation();
+ * const fSlide = fPresentation.getSlideByIndex(0);
+ * const chartInfo = fSlide
+ *   .newChart(univerAPI.Enum.ChartTypeString.Pareto)
+ *   .setSource([['Cause', 'Count'], ['A', 42], ['B', 28], ['C', 15]])
+ *   .setCategoryField(0)
+ *   .setValueFields([1])
+ *   .setBarStyle({ color: '#2563eb', opacity: 0.8 })
+ *   .setCumulativeLineStyle({ color: '#dc2626', width: 2 })
+ *   .setIncludeZeroValues(false)
+ *   .build();
+ * await fSlide.insertChart(chartInfo);
+ * ```
+ *
+ * @example Board
+ * ```ts
+ * const fBoard = univerAPI.getActiveBoard();
+ * const chartInfo = fBoard
+ *   .newChart(univerAPI.Enum.ChartTypeString.Pareto)
+ *   .setSource([['Cause', 'Count'], ['A', 42], ['B', 28], ['C', 15]])
+ *   .setCategoryField(0)
+ *   .setValueFields([1])
+ *   .setBarStyle({ color: '#2563eb', opacity: 0.8 })
+ *   .setCumulativeLineStyle({ color: '#dc2626', width: 2 })
+ *   .setIncludeZeroValues(false)
+ *   .build();
+ * await fBoard.insertChart(chartInfo);
+ * ```
+ */
+export declare class FParetoChartBuilder<TSource = never[], TDataSource = TSource, TInfo extends IChartInfo<TDataSource> = IChartInfo<TDataSource>> extends FCartesianChartBuilder<Omit<IChartSeriesPatch, 'selector'>, IChartSeriesStyleSpec, TSource, TDataSource, TInfo> {
     /**
      * Deep-merges supported Pareto bar appearance.
      *
@@ -9,16 +84,14 @@ export declare class FParetoChartBuilder extends FCartesianChartBuilder {
      *
      * This method executes synchronously.
      *
-     * Read the current value from `builder.describe().pareto?.barStyle`.
+     * Read the current value from `builder.build().config.pareto?.barStyle`.
      *
      * @param value Supported bar appearance fields.
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Pareto);
      * builder.setBarStyle({ color: '#1677ff', opacity: 0.8 });
-     * const barStyle = builder.describe().pareto?.barStyle;
+     * const barStyle = builder.build().config.pareto?.barStyle;
      * ```
      */
     setBarStyle(value: IChartParetoBarStyleSpec): this;
@@ -33,10 +106,8 @@ export declare class FParetoChartBuilder extends FCartesianChartBuilder {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Pareto);
      * builder.clearBarStyle();
-     * const barStyle = builder.describe().pareto?.barStyle;
+     * const barStyle = builder.build().config.pareto?.barStyle;
      * ```
      */
     clearBarStyle(): this;
@@ -49,16 +120,14 @@ export declare class FParetoChartBuilder extends FCartesianChartBuilder {
      * This method executes synchronously.
      *
      * Non-positive widths are ignored because the cumulative line remains part of Pareto.
-     * Read the current value from `builder.describe().pareto?.cumulativeLineStyle`.
+     * Read the current value from `builder.build().config.pareto?.cumulativeLineStyle`.
      *
      * @param value Supported cumulative-line appearance fields.
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Pareto);
      * builder.setCumulativeLineStyle({ color: '#f5222d', width: 2 });
-     * const lineStyle = builder.describe().pareto?.cumulativeLineStyle;
+     * const lineStyle = builder.build().config.pareto?.cumulativeLineStyle;
      * ```
      */
     setCumulativeLineStyle(value: IChartParetoLineStyleSpec): this;
@@ -73,10 +142,8 @@ export declare class FParetoChartBuilder extends FCartesianChartBuilder {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Pareto);
      * builder.clearCumulativeLineStyle();
-     * const lineStyle = builder.describe().pareto?.cumulativeLineStyle;
+     * const lineStyle = builder.build().config.pareto?.cumulativeLineStyle;
      * ```
      */
     clearCumulativeLineStyle(): this;
@@ -89,8 +156,6 @@ export declare class FParetoChartBuilder extends FCartesianChartBuilder {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Pareto);
      * builder.setIncludeZeroValues(true);
      * ```
      */
@@ -103,8 +168,6 @@ export declare class FParetoChartBuilder extends FCartesianChartBuilder {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Pareto);
      * builder.resetIncludeZeroValues();
      * ```
      */