@univerjs-pro/engine-chart 1.0.0-rc.0 → 1.0.0

package/lib/types/chart-text-measure-canvas.d.ts

@@ -1,6 +1,7 @@
 interface ISize {
     width: number;
     height: number;
+    fontHeight?: number;
 }
 export declare const calcPosition: (text: string, font: string) => ISize;
 export {};

package/lib/types/enum.d.ts

@@ -202,6 +202,12 @@ export declare enum AxisValueType {
     Numeric = 2,
     Date = 3
 }
+/** Persisted Scatter geometry; absent fields retain historical marker-only rendering. */
+export declare enum ScatterLineType {
+    None = "none",
+    Straight = "straight",
+    Smooth = "smooth"
+}
 export declare enum InvalidValueType {
     Zero = "zero",
     Break = "break",
@@ -300,9 +306,12 @@ export declare enum SeriesLabelPosition {
     Left = "left",
     Right = "right",
     Inside = "inside",
+    InsideBase = "insideBase",
+    InsideEnd = "insideEnd",
     Outside = "outside"
 }
 export declare enum PieLabelPosition {
+    Auto = "auto",
     Inside = "inside",
     Outside = "outside"
 }
@@ -418,7 +427,8 @@ export declare enum LabelContentType {
     CategoryName = 2,
     SeriesName = 4,
     Value = 8,
-    Percentage = 16
+    Percentage = 16,
+    BubbleSize = 32
 }
 export declare enum TextAlign {
     Left = "left",

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

@@ -5,6 +5,30 @@ import { FCartesianChartBuilder } from '../f-cartesian-chart-builder';
  *
  * Scatter uses the ordinary Cartesian category/value mapping. Select the optional X-axis
  * field with `setCategoryField()` and every Y/value series with `setValueFields()`.
+ * Use `setSeriesToCategory()` when a Y series has its own X field. The mapping uses
+ * dataset field indexes after source orientation, not positions in the selected series list.
+ * Independent X data can share the same visual X axis.
+ *
+ * @example Independent X fields in Sheets
+ * ```ts
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * fWorksheet.getRange('A1:D4').setValues([
+ *   ['Shared X', 'First Y', 'Other X', 'Second Y'],
+ *   [1, 10, 5, 30],
+ *   [2, 20, 9, 40],
+ *   [3, 25, 12, 50],
+ * ]);
+ * const info = fWorksheet.newChart(univerAPI.Enum.ChartTypeString.Scatter)
+ *   .setSource({ range: 'A1:D4', orientation: univerAPI.Enum.ChartSourceOrientation.Columns })
+ *   .setCategoryField(0)
+ *   .setValueFields([1, 3])
+ *   .setSeriesToCategory({ 3: [2] })
+ *   .build();
+ * await fWorksheet.insertChart(info);
+ * // First Y inherits Shared X: (1,10), (2,20), (3,25).
+ * // Second Y uses Other X: (5,30), (9,40), (12,50).
+ * // Calling setSeriesToCategory({}) restores Shared X for both Y series.
+ * ```
  *
  * @example Sheet
  * ```ts

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

@@ -426,6 +426,28 @@ export declare class FChartBuilderBase<TSource = never[], TDataSource = TSource,
      * ```
      */
     setCategoryField(index: number): this;
+    /**
+     * Replaces all per-series category/X bindings. An empty object restores shared categories.
+     * Keys are dataset value-field indexes, not series positions or visual axis IDs.
+     * Values are ordered dataset category-field indexes. Scatter requires one X field;
+     * Combination supports root-to-leaf fields when multi-level categories are enabled.
+     * Omitted series retain the shared category selection; this does not create extra axes.
+     * Input arrays are copied. Repeated calls replace this map without changing other selections.
+     * @param {Record<number, number[]>} mapping Complete independent category mapping.
+     * @returns {this} This chart API for chaining.
+     * @example
+     * ```ts
+     * // Columns A/B/C/D become dataset fields 0/1/2/3.
+     * // A = shared X, B = first Y, C = independent X, D = second Y.
+     * builder.setCategoryField(0).setValueFields([1, 3]);
+     * builder.setSeriesToCategory({ 3: [2] }); // B uses A; D uses C.
+     * builder.setSeriesToCategory({ 1: [0], 3: [0] }); // Both explicitly use A.
+     * builder.setSeriesToCategory({}); // Both inherit the shared category again.
+     * // Combination with multi-level categories enabled:
+     * builder.setSeriesToCategory({ 2: [0, 1] }); // Series 2 uses root field 0, leaf field 1.
+     * ```
+     */
+    setSeriesToCategory(mapping: Record<number, number[]>): this;
     /**
      * Sets the ordered category fields used by a multi-level category axis.
      *

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

@@ -489,6 +489,28 @@ export declare class FChart<TSource, TDataSource = TSource, TInfo extends IChart
      * ```
      */
     setCategoryField(index: number): this;
+    /**
+     * Replaces all per-series category/X bindings. An empty object restores shared categories.
+     * Keys are dataset value-field indexes, not series positions or visual axis IDs.
+     * Values are ordered dataset category-field indexes. Scatter requires one X field;
+     * Combination supports root-to-leaf fields when multi-level categories are enabled.
+     * Omitted series retain the shared category selection; this does not create extra axes.
+     * Input arrays are copied. Repeated calls replace this map without changing other selections.
+     * @param {Record<number, number[]>} mapping Complete independent category mapping.
+     * @returns {this} This chart API for chaining.
+     * @example
+     * ```ts
+     * // Columns A/B/C/D become dataset fields 0/1/2/3.
+     * // A = shared X, B = first Y, C = independent X, D = second Y.
+     * fChart.setCategoryField(0).setValueFields([1, 3]);
+     * fChart.setSeriesToCategory({ 3: [2] }); // B uses A; D uses C.
+     * fChart.setSeriesToCategory({ 1: [0], 3: [0] }); // Both explicitly use A.
+     * fChart.setSeriesToCategory({}); // Both inherit the shared category again.
+     * // Combination with multi-level categories enabled:
+     * fChart.setSeriesToCategory({ 2: [0, 1] }); // Series 2 uses root field 0, leaf field 1.
+     * ```
+     */
+    setSeriesToCategory(mapping: Record<number, number[]>): this;
     /**
      * Sets the ordered category fields used by this live Chart's multi-level category axis.
      * @param {readonly number[]} indexes The zero-based source field indexes in root-to-leaf order.

package/lib/types/index.d.ts

@@ -64,7 +64,7 @@ export type { IBuildOrientedChartDataSetOptions, IChartHostConfigAdapter, IChart
 export { buildOrientedChartDataSet, } from './chart-builder/internal/chart-host-config-adapter';
 export type { IChartDataAggregation, IChartTopNSpec } from './chart-data-aggregation';
 export type { IUniverChartConfig } from './config/config';
-export { AreaLineStyle, AxisAlignEnum, AxisValueType, BarShape, CategoryType, ChartAttributeBits, ChartAxisDimension, ChartBorderDashType, ChartCandlestickState, ChartChordFocusMode, ChartChordLabelPosition, ChartChordRibbonColorMode, ChartGaugeMode, ChartGaugePointerShape, ChartHistogramBinKind, ChartMarkLineLabelPosition, ChartSemanticAxis, ChartSourceDataTypeEnum, ChartSunburstLabelPosition, ChartTrendlineType, ChartTypeBits, ChartWaterfallPointRole, DataOrientation, HistogramBinningMode, InvalidValueType, IRuntimeAxisPosition, IRuntimeAxisPriority, LabelAlignEnum, LabelContentType, LegendPositionEnum, LinePointShape, ParetoSeriesIndex, ParetoSeriesPart, PieLabelPosition, RadarShape, RelationChartLayoutEnum, SelectModeEnum, SeriesLabelPosition, StackType, TextAlign, TextVerticalAlign, TitlePositionEnum, TreemapParentLabelLayout, WaterfallSeriesTypeEnum, WaterfallStackTypeEnum, WordCloudShapeEnum, } from './enum';
+export { AreaLineStyle, AxisAlignEnum, AxisValueType, BarShape, CategoryType, ChartAttributeBits, ChartAxisDimension, ChartBorderDashType, ChartCandlestickState, ChartChordFocusMode, ChartChordLabelPosition, ChartChordRibbonColorMode, ChartGaugeMode, ChartGaugePointerShape, ChartHistogramBinKind, ChartMarkLineLabelPosition, ChartSemanticAxis, ChartSourceDataTypeEnum, ChartSunburstLabelPosition, ChartTrendlineType, ChartTypeBits, ChartWaterfallPointRole, DataOrientation, HistogramBinningMode, InvalidValueType, IRuntimeAxisPosition, IRuntimeAxisPriority, LabelAlignEnum, LabelContentType, LegendPositionEnum, LinePointShape, ParetoSeriesIndex, ParetoSeriesPart, PieLabelPosition, RadarShape, RelationChartLayoutEnum, ScatterLineType, SelectModeEnum, SeriesLabelPosition, StackType, TextAlign, TextVerticalAlign, TitlePositionEnum, TreemapParentLabelLayout, WaterfallSeriesTypeEnum, WaterfallStackTypeEnum, WordCloudShapeEnum, } from './enum';
 export { generateChartContext, reconcileChartContext } from './models/chart-context/resolve-chart-context';
 export { MAX_HISTOGRAM_BIN_COUNT } from './models/chart-data/internal/histogram-bins';
 export { PIE_CONNECTOR_COLOR_DEFAULT, PIE_CONNECTOR_DASH_TYPE_DEFAULT, PIE_CONNECTOR_OPACITY_DEFAULT, PIE_CONNECTOR_VISIBLE_DEFAULT, PIE_CONNECTOR_WIDTH_DEFAULT, PIE_PERCENTAGE_SPLIT_LESS_THAN_DEFAULT, PIE_POSITION_SPLIT_COUNT_DEFAULT, PIE_POSITION_SPLIT_COUNT_MIN, PIE_SECONDARY_GAP_WIDTH_DEFAULT, PIE_SECONDARY_GAP_WIDTH_MAX, PIE_SECONDARY_GAP_WIDTH_MIN, PIE_SECONDARY_SIZE_DEFAULT, PIE_SECONDARY_SIZE_MAX, PIE_SECONDARY_SIZE_MIN, PIE_VALUE_SPLIT_LESS_THAN_DEFAULT, } from './models/chart-data/pie-composite/pie-composite-spec';
@@ -109,7 +109,7 @@ export type { IChartLocaleTexts } from './models/common/chart-locale-texts';
 export { replaceLocaleParams } from './models/common/chart-locale-texts';
 export { DEFAULT_CHORD_MAPPING } from './models/common/constants/chord';
 export { defaultChartHeight, defaultChartWidth, EChartRenderEngineName } from './models/common/constants/default';
-export { defaultChartConfig, resolveGaugeStyle, RTLChartStyle } from './models/common/constants/default-chart-style';
+export { DEFAULT_SCATTER_LINE_TYPE, defaultChartConfig, resolveGaugeStyle, RTLChartStyle } from './models/common/constants/default-chart-style';
 export { DEFAULT_HISTOGRAM_BIN_COUNT, DEFAULT_HISTOGRAM_BIN_WIDTH, MAX_HISTOGRAM_BIN_GAP, } from './models/common/constants/histogram-defaults';
 export { resolveChordStyle, resolveSunburstCenterLabelStyle, resolveSunburstLabelStyle, } from './models/common/style/chart-specific-default-style';
 export type { IEchartTheme } from './models/common/theme/build-in-theme/types';
@@ -136,7 +136,7 @@ export type { IChartSourceHeader, IChartSourceHeaderTitle } from './source/chart
 export { StaticChartSource } from './source/static-chart-source';
 export type { IChartCandlestickMappingSpec, IChartCandlestickSpec, IChartCandlestickStateStyleSpec, IChartChordEmphasisSpec, IChartChordLabelSpec, IChartChordLayoutSpec, IChartChordMappingSpec, IChartChordNodeStyleSpec, IChartChordRibbonStyleSpec, IChartChordSpec, IChartGaugeAnchorSpec, IChartGaugeAnglesSpec, IChartGaugeAxisLabelSpec, IChartGaugeAxisLineSpec, IChartGaugeAxisTickSpec, IChartGaugeDetailSpec, IChartGaugeFontSpec, IChartGaugePointerSpec, IChartGaugeProgressSpec, IChartGaugeRangeSpec, IChartGaugeScaleSpec, IChartGaugeSpec, IChartGaugeSplitLineSpec, IChartGaugeTitleSpec, IChartHistogramBinningSpec, IChartHistogramDataSpec, IChartHistogramSpec, IChartHistogramStyleSpec, IChartSunburstCenterLabelSpec, IChartSunburstLabelSpec, IChartSunburstSpec, IChartTreemapLabelSpec, IChartTreemapSpec, IChartValueLabelSpec, } from './types';
 export { ChartImageExportFormat, ChartImageSourceType, ChartRenderMode } from './types';
-export type { ChartDataSourceValues, ChartDirection, ChartElementEventHandler, ChartElementEventType, ChartElementKind, ChartImageSource, ChartRenderRuntimeContext, ChartRuntimeStyle, ChartStyle, DeepNullish, DeepPartial, DimensionDefinitionLoose, IAllSeriesStyle, IAxisOptions, IBarStyle, IChartBubbleStyle, IChartCandlestickData, IChartCandlestickPoint, IChartChordData, IChartChordLink, IChartChordNode, IChartConfig, IChartContext, IChartData, IChartDataCategory, IChartDataCategoryLevel, IChartDataCategorySegment, IChartDataSeries, IChartDataSource, IChartElementBounds, IChartElementEvent, IChartElementHit, IChartElementOverlay, IChartGaugeData, IChartGaugeItem, IChartHistogramBin, IChartHistogramData, IChartHost, IChartHostBorderStyle, IChartHostLease, IChartHostRect, IChartHostStyle, IChartInstance, IChartPlotArea, IChartRenderAsImageOptions, IChartRenderInput, IChartRenderInstance, IChartRenderInstanceCreateContext, IChartRenderInstanceSpecInput, IChartRenderInstanceStyleInput, IChartRenderModel, IChartRenderModelImageExportInput, IChartRenderModelImageExportOptions, IChartRenderModelImageExportResult, IChartRenderTransitionOptions, IChartSnapshot, IChartStyle, IChartSunburstData, IChartSunburstNode, IChartTreemapData, IChartTreemapNode, IDimensionDefinition, IDomChartHost, IGridLineStyle, IImageChartHost, ILabelStyle, ILegendStyle, IPieLabelStyle, IPointStyle, IRelationForceOptions, IRuntimeAxis, ISeriesLabelStyle, ISeriesStyle, ITrendLine, IUniverDataSet, IUniverDataSetCategorySpan, OptionDataValue, RightYAxisOptions, } from './types';
+export type { ChartDataSourceValues, ChartDirection, ChartElementEventHandler, ChartElementEventType, ChartElementKind, ChartFieldButtonRole, ChartImageSource, ChartRenderRuntimeContext, ChartRuntimeStyle, ChartStyle, DeepNullish, DeepPartial, DimensionDefinitionLoose, IAllSeriesStyle, IAxisOptions, IBarStyle, IChartBubbleStyle, IChartCandlestickData, IChartCandlestickPoint, IChartChordData, IChartChordLink, IChartChordNode, IChartConfig, IChartContext, IChartData, IChartDataCategory, IChartDataCategoryLevel, IChartDataCategorySegment, IChartDataSeries, IChartDataSource, IChartElementBounds, IChartElementEvent, IChartElementHit, IChartElementOverlay, IChartFieldButton, IChartGaugeData, IChartGaugeItem, IChartHistogramBin, IChartHistogramData, IChartHost, IChartHostBorderStyle, IChartHostLease, IChartHostRect, IChartHostStyle, IChartInstance, IChartPlotArea, IChartRenderAsImageOptions, IChartRenderInput, IChartRenderInstance, IChartRenderInstanceCreateContext, IChartRenderInstanceSpecInput, IChartRenderInstanceStyleInput, IChartRenderModel, IChartRenderModelImageExportInput, IChartRenderModelImageExportOptions, IChartRenderModelImageExportResult, IChartRenderTransitionOptions, IChartSnapshot, IChartStyle, IChartSunburstData, IChartSunburstNode, IChartTreemapData, IChartTreemapNode, IDimensionDefinition, IDomChartHost, IGridLineStyle, IImageChartHost, ILabelStyle, ILegendStyle, IPieLabelStyle, IPointStyle, IRelationForceOptions, IRuntimeAxis, ISeriesLabelStyle, ISeriesStyle, ITrendLine, IUniverDataSet, IUniverDataSetCategorySpan, OptionDataValue, RightYAxisOptions, } from './types';
 export { CHART_DATA_UPDATE_ANIMATION_DURATION } from './types';
 export { chartBitsUtils, chartTypeCanUseTrendLine, mergeChartConfig, } from './util';
 export { omitUndefinedFields, } from './utils/compact';

package/lib/types/model/chart-data-operators/build-chart-data.d.ts

@@ -0,0 +1,4 @@
+import type { IChartContext, IChartData, IUniverDataSet } from '../../types';
+import type { IChartLocaleTexts } from '../chart-locale-texts';
+import { ChartTypeBits } from '../../enum';
+export declare function buildChartData(dataSource: IUniverDataSet, chartContext: IChartContext, chartType: ChartTypeBits, isRowDirection: boolean, localeTexts: IChartLocaleTexts): IChartData;

package/lib/types/model/chart-data-operators/index.d.ts

@@ -0,0 +1,2 @@
+export * from './build-chart-data';
+export * from './operators';

package/lib/types/model/chart-data-operators/operators.d.ts

@@ -0,0 +1,25 @@
+import type { ChartDataSource } from '../../source/chart-source';
+import type { ChartDataSourceValue, ChartDataSourceValues, IChartContext, IChartDataAggregation, OptionDataValue } from '../../types';
+import type { ChartModel } from '../chart-model';
+export type IChartContextOperator = (dataSource: ChartDataSource, context: IChartContext, model: ChartModel) => IChartContext;
+export type IChartDataAggregateOperator = (dataSource: ChartDataSourceValues, context: IChartContext, dataAggregation: IChartDataAggregation) => ChartDataSourceValues | void;
+type Nil = null | undefined;
+export declare function isNil(value: any): value is Nil;
+export declare function countTypesFromArray(arrayData: OptionDataValue[]): {
+    numbers: number;
+    strings: number;
+};
+export declare function toString(value: ChartDataSourceValue): string;
+export declare function toNumber(value: ChartDataSourceValue): number;
+export declare function toColumnOrient<T = any>(dataSource: T[][]): T[][];
+export declare function findCategoryIndexes(dataSource: ChartDataSource): number[];
+export declare function groupByToArray<T = any>(ary: T[], selector: (item: T, index: number) => string): {
+    name: string;
+    values: T[];
+}[];
+export declare function sumArray(ary: ChartDataSourceValue[]): number;
+export declare const findHeaderOperator: IChartContextOperator;
+export declare const findCategoryOperator: IChartContextOperator;
+export declare const findSeriesOperator: IChartContextOperator;
+export declare const pieSeriesFilterOperator: IChartContextOperator;
+export {};

package/lib/types/model/chart-locale-texts.d.ts

@@ -0,0 +1,22 @@
+export interface IChartLocaleTexts {
+    seriesDefaultName: string;
+    categoryDefaultName: string;
+    blank: string;
+    boxplotMin: string;
+    boxplotQ1: string;
+    boxplotMedian: string;
+    boxplotQ3: string;
+    boxplotMax: string;
+    bubbleEmptyTips: string;
+    cloudWord: string;
+    cloudFrequency: string;
+    msgEmptyTips: string;
+    msgSankeyCircularTips: string;
+    paretoLineName: string;
+    relationEmptyTips: string;
+    waterfallPositive: string;
+    waterfallNegative: string;
+    waterfallSubtotal: string;
+}
+export declare function replaceLocaleParams(text: string, ...args: string[]): string;
+export declare function getDefaultChartLocaleTexts(): IChartLocaleTexts;