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

package/lib/types/models/{echart-render-model.d.ts → chart-render/echart-render-model.d.ts}

@@ -1,8 +1,7 @@
-import type { ChartElementEventHandler, ChartElementEventType, ChartImageSource, ChartStyle, EChartInstance, IChartConfig, IChartElementHit, IChartHostRect, IChartInstance, IChartRenderAsImageOptions, IChartRenderInstance, IChartRenderInstanceCreateContext, IChartRenderModel, IChartRenderModelImageExportInput, IChartRenderModelImageExportOptions, IChartRenderModelImageExportResult, IChartRenderModelStylizeInit, IChartRenderRuntimeOptions } from '../types';
-import type { EChartsOption } from '../utils/echarts';
-import type { IWordCloudRenderConfig } from '../wordcloud-chart/word-cloud-render-config';
+import type { ChartElementEventHandler, ChartElementEventType, ChartImageSource, ChartRuntimeStyle, EChartInstance, EChartSpec, IChartConfig, IChartElementHit, IChartHostRect, IChartInstance, IChartRenderAsImageOptions, IChartRenderInstance, IChartRenderInstanceCreateContext, IChartRenderModel, IChartRenderModelImageExportInput, IChartRenderModelImageExportOptions, IChartRenderModelImageExportResult, IChartRenderModelStylizeInit, IChartRenderRuntimeOptions } from '../../types';
+import type { IWordCloudRenderConfig } from '../../wordcloud-chart/word-cloud-render-config';
 import { Disposable } from '@univerjs/core';
-import { ChartHostRenderMode } from '../types';
+import { ChartHostRenderMode } from '../../types';
 export interface IEChartRenderModelOptions {
     wordCloudRenderConfig?: IWordCloudRenderConfig;
 }
@@ -15,19 +14,30 @@ export declare class EChartRenderModel extends Disposable implements IChartRende
     updateWatermark(addWatermark: boolean): void;
     private _addSpecConverters;
     private _addSpecOperators;
-    createChartInstance(): IChartInstance<EChartsOption>;
-    createChartInstance(mode: ChartHostRenderMode, context?: IChartRenderInstanceCreateContext<EChartsOption>): IChartRenderInstance;
+    createChartInstance(): IChartInstance<EChartSpec>;
+    createChartInstance(mode: ChartHostRenderMode, context?: IChartRenderInstanceCreateContext<EChartSpec>): IChartRenderInstance;
     clearRuntimeCache(chartId: string): void;
     clearAllRuntimeCache(): void;
     dispose(): void;
-    toSpec(config: IChartConfig, style: ChartStyle): EChartsOption;
-    stylizeSpec(spec: EChartsOption, stylizeInit: IChartRenderModelStylizeInit<EChartsOption>, rect: IChartHostRect): EChartsOption | {
+    toSpec(config: IChartConfig, style: ChartRuntimeStyle): import("echarts").EChartsOption;
+    /**
+     * Determine whether to show an empty state for the chart.
+     * @param chartConfig The chart configuration object.
+     * @param chartStyle The chart style object.
+     * @returns A boolean indicating whether to show an empty state.
+     */
+    private _getShowEmpty;
+    stylizeSpec(spec: EChartSpec, stylizeInit: IChartRenderModelStylizeInit<EChartSpec>, rect: IChartHostRect): import("echarts").EChartsOption | {
         backgroundColor: string;
     };
     exportImage(input: IChartRenderModelImageExportInput, options?: IChartRenderModelImageExportOptions): Promise<IChartRenderModelImageExportResult>;
 }
-/** Normalizes renderer-private marks, including Treemap residual leaves, to their semantic identity. */
-export declare function resolveEChartSeriesIdentity(spec: EChartsOption | null, seriesIndex: number | undefined, params?: any): Pick<IChartElementHit, 'seriesId' | 'seriesName' | 'baseSeriesIndex' | 'waterfallSeriesType'>;
+/** Converts materialized composite Pie marks back to their authored source identity. */
+export declare function resolveEChartPieCompositeHit(spec: EChartSpec | null, seriesIndex: number | undefined, params?: any, dataIndex?: number): Pick<IChartElementHit, 'pieCompositeRole' | 'pieCompositePlot' | 'pieSourcePointIndex' | 'pieAggregateMemberSourcePointIndexes'> | undefined;
+/** Converts native Chord node/link events to stable semantic graph identities. */
+export declare function resolveEChartChordHit(spec: EChartSpec | null, seriesIndex: number | undefined, params?: any, dataIndex?: number): Pick<IChartElementHit, 'semanticId' | 'semanticKind' | 'semanticValue' | 'semanticFormattedValue' | 'semanticEndpointAName' | 'semanticEndpointBName'> | undefined;
+/** Normalizes renderer-private marks, including hierarchy residual leaves, to their semantic identity. */
+export declare function resolveEChartSeriesIdentity(spec: EChartSpec | null, seriesIndex: number | undefined, params?: any): Pick<IChartElementHit, 'seriesId' | 'seriesName' | 'baseSeriesIndex' | 'waterfallSeriesType'>;
 export declare class EChartRenderEngine extends Disposable implements EChartInstance {
     static engineName: string;
     private _instance;
@@ -50,8 +60,8 @@ export declare class EChartRenderEngine extends Disposable implements EChartInst
     resize(echartsProviderOrOptions?: any | IChartRenderRuntimeOptions): void;
     private _ensureChartInstance;
     get containerElement(): HTMLElement | null;
-    render(spec: EChartsOption, echartsProviderOrOptions?: any | IChartRenderRuntimeOptions): void;
-    renderAsImage(spec: EChartsOption, options: IChartRenderAsImageOptions): Promise<ChartImageSource>;
+    render(spec: EChartSpec, echartsProviderOrOptions?: any | IChartRenderRuntimeOptions): void;
+    renderAsImage(spec: EChartSpec, options: IChartRenderAsImageOptions): Promise<ChartImageSource>;
     on(type: ChartElementEventType, handler: ChartElementEventHandler): {
         dispose: () => void;
     };

package/lib/types/models/{chart-element-edit-overlay → chart-render/edit-overlay}/chart-element-edit-overlay.d.ts

@@ -1,5 +1,5 @@
-import type { IChartElementBounds, IChartElementHit } from '../../types';
-import type { ECharts } from '../../utils/echarts';
+import type { ECharts } from 'echarts';
+import type { IChartElementBounds, IChartElementHit } from '../../../types';
 import type { ChartElementEditBorderType, IChartElementEditOverlayPalette } from './types';
 export declare class ChartElementEditOverlay {
     private readonly _getInstance;

package/lib/types/models/{chart-element-edit-overlay → chart-render/edit-overlay}/resolve-chart-element-hit-layout.d.ts

@@ -1,5 +1,5 @@
-import type { IChartElementBounds, IChartElementHit } from '../../types';
-import type { ECharts } from '../../utils/echarts';
+import type { ECharts } from 'echarts';
+import type { IChartElementBounds, IChartElementHit } from '../../../types';
 import type { IChartElementHitLayout, IResolvedChartElementOverlay } from './types';
 export declare function toChartElementFiniteNumber(value: unknown): number | undefined;
 export declare function getChartElementTarget(params: any): any;

package/lib/types/models/{chart-element-edit-overlay → chart-render/edit-overlay}/types.d.ts

@@ -1,4 +1,4 @@
-import type { IChartElementBounds, IChartElementOverlay } from '../../types';
+import type { IChartElementBounds, IChartElementOverlay } from '../../../types';
 export type ChartElementEditBorderType = 'hover' | 'fixed';
 export interface IChartElementEditOverlayPalette {
     hoverStroke: string;

package/lib/types/models/chart-render/format/chart-value-format.d.ts

@@ -0,0 +1,16 @@
+/** Canonical authored formats shared by chart editors and Facade consumers. */
+export declare const CHART_VALUE_FORMAT_PRESETS: {
+    readonly source: null;
+    readonly number: "#,##0.00";
+    readonly percentage: "0.00%";
+    readonly currency: "$#,##0.00";
+    readonly scientific: "0.00E+00";
+};
+/** Stable representative value used only for editor previews. */
+export declare const CHART_VALUE_FORMAT_PREVIEW_VALUE = 1234.5;
+/**
+ * Formats one semantic chart value without exposing renderer formatter contracts.
+ * Invalid authored patterns fall back to the source display text.
+ */
+export declare function formatChartValue(value: number, sourceFormattedValue: string, format?: string): string;
+export declare function toPercentage(value: number, fractionDigits?: number): string;

package/lib/types/models/{chart-runtime-style.d.ts → chart-render/style/chart-runtime-style.d.ts}

@@ -1,5 +1,5 @@
-import type { ChartStyle } from '../types';
-import { ChartTypeBits } from '../enum';
+import type { ChartRuntimeStyle, ChartStyle } from '../../../types';
+import { ChartTypeBits } from '../../../enum';
 /**
  * Converts persisted semantic chart style buckets into transient render buckets.
  *
@@ -9,5 +9,5 @@ import { ChartTypeBits } from '../enum';
  * saved field names. This resolver swaps y-axis option/title buckets only in
  * the runtime render style consumed by physical-position operators.
  */
-export declare function resolveChartRuntimeStyle(style: ChartStyle, chartType?: ChartTypeBits): ChartStyle;
+export declare function resolveChartRuntimeStyle(style: ChartRuntimeStyle, chartType?: ChartTypeBits): ChartRuntimeStyle;
 export declare function resolveChartStyleBackgroundColor(style?: Pick<ChartStyle, 'backgroundColor'> | null): string;

package/lib/types/models/common/chart-field-diagnostic.d.ts

@@ -0,0 +1,14 @@
+import type { ChartTypeBits } from '../../enum';
+export declare enum ChartFieldDiagnosticCode {
+    MissingCategoryFields = "chart-field.missing-category-fields",
+    MissingSeriesFields = "chart-field.missing-series-fields",
+    InvalidFieldIndex = "chart-field.invalid-field-index",
+    InvalidValueFieldType = "chart-field.invalid-value-field-type",
+    InvalidDataStructure = "chart-field.invalid-data-structure",
+    UnsupportedChartType = "chart-field.unsupported-chart-type"
+}
+export interface IChartFieldDiagnostic {
+    code: ChartFieldDiagnosticCode;
+    chartType: ChartTypeBits;
+    details?: Readonly<Record<string, number | string>>;
+}

package/lib/types/models/common/chart-field-role.d.ts

@@ -0,0 +1,53 @@
+export declare const ChartFieldRoleIndex: {
+    readonly CategoryValue: {
+        readonly Category: 0;
+        readonly Value: 0;
+    };
+    readonly Point: {
+        readonly Label: 0;
+        readonly X: 0;
+        readonly Y: 1;
+    };
+    readonly Bubble: {
+        readonly Label: 0;
+        readonly Group: 1;
+        readonly X: 0;
+        readonly Y: 1;
+        readonly Size: 2;
+    };
+    readonly Hierarchy: {
+        readonly Value: 0;
+    };
+    readonly Candlestick: {
+        readonly Category: 0;
+        readonly Open: 0;
+        readonly High: 1;
+        readonly Low: 2;
+        readonly Close: 3;
+    };
+    readonly Edge: {
+        readonly Source: 0;
+        readonly Target: 1;
+        readonly Value: 0;
+    };
+};
+export declare const ChartFieldRoleCount: {
+    readonly None: 0;
+    readonly CategoryValue: {
+        readonly Category: 1;
+        readonly Value: 1;
+    };
+    readonly Point: {
+        readonly XY: 2;
+    };
+    readonly Bubble: {
+        readonly Labels: 2;
+        readonly Values: 3;
+    };
+    readonly Edge: {
+        readonly Endpoints: 2;
+    };
+    readonly Candlestick: {
+        readonly OHLC: 4;
+    };
+};

package/lib/types/models/common/chart-locale-texts.d.ts

@@ -0,0 +1,44 @@
+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;
+    pieAggregateOther: string;
+    pieAggregateMembers: string;
+    relationEmptyTips: string;
+    waterfallPositive: string;
+    waterfallNegative: string;
+    waterfallSubtotal: string;
+    candlestickSeries: string;
+    candlestickCategory: string;
+    candlestickOpen: string;
+    candlestickHigh: string;
+    candlestickLow: string;
+    candlestickClose: string;
+    histogramFrequency: string;
+    treemapEmptyTips: string;
+    treemapOwnValue: string;
+    treemapChildren: string;
+    sunburstEmptyTips: string;
+    sunburstOwnValue: string;
+    sunburstChildren: string;
+    gaugeEmptyTips: string;
+    gaugeInvalidMapping: string;
+    gaugeInvalidConfig: string;
+    chordEmptyTips: string;
+    chordInvalidMapping: string;
+    chordInvalidConfig: string;
+    chordCount: string;
+    chordAssociatedValue: string;
+}
+export declare function replaceLocaleParams(text: string, ...args: string[]): string;

package/lib/types/models/common/constants/chord.d.ts

@@ -0,0 +1,5 @@
+import type { IChartChordMappingSpec } from '../../../types';
+export declare const DEFAULT_CHORD_SOURCE_INDEX = 0;
+export declare const DEFAULT_CHORD_TARGET_INDEX = 1;
+export declare const DEFAULT_CHORD_VALUE_INDEX = 2;
+export declare const DEFAULT_CHORD_MAPPING: Readonly<IChartChordMappingSpec>;