@univerjs-pro/engine-chart 1.0.4 → 1.1.0

package/lib/types/models/chart-render/axes/axis-placement.d.ts

@@ -1,5 +1,6 @@
 import type { registerLayout, registerPostUpdate } from 'echarts';
 import type { IAxisOptions } from '../../../types';
+export declare const LOG_AXIS_AUTO_CROSSING = 1;
 declare const AXIS_PLACEMENT_META = "__univerAxisPlacement";
 interface IAxisPlacement {
     crossing?: IAxisOptions['crossing'];
@@ -12,6 +13,7 @@ interface IAxisOption {
 }
 /** Transient renderer metadata. The snapshot retains only the standard OOXML axis properties. */
 export declare function setAxisPlacement(axis: IAxisOption, style: Pick<IAxisOptions, 'crossing' | 'tickLabelPosition'>, perpendicularInverse?: boolean): void;
+export declare function getAxisCrossing(axis: IAxisOption): IAxisOptions['crossing'];
 export declare function getAxisOriginalPosition(axis: IAxisOption): string | undefined;
 export declare function resolveAxisLabelPosition(position: string, labelPosition: IAxisOptions['tickLabelPosition'], perpendicularInverse?: boolean): string;
 /** Run after scale/grid resolution so resizing and legend filtering use the actual Cartesian geometry. */

package/lib/types/models/chart-render/axes/chart-axis-scale.d.ts

@@ -0,0 +1,14 @@
+import type { ChartDirection, ChartStyle, IChartData } from '../../../types';
+import { ChartTypeBits } from '../../../enum';
+export interface IChartAxisScaleState {
+    effectiveScale: 'linear' | 'log';
+    requestedBase?: number;
+    effectiveBase: number;
+    positiveMin?: number;
+    positiveMax?: number;
+    skippedPoints: number;
+    diagnostics: Array<'invalid-log-base' | 'orphan-log-base' | 'invalid-scale-type' | 'invalid-log-bounds' | 'no-positive-data' | 'unsupported-percent-log' | 'unsupported-log-axis'>;
+    seriesIndexes: number[];
+    invalidPoints: Record<number, number[]>;
+}
+export declare function analyzeChartAxisScales(chartType: ChartTypeBits, data: IChartData, style: ChartStyle, direction: ChartDirection): Partial<Record<'xAxis' | 'yAxis' | 'rightYAxis', IChartAxisScaleState>>;

package/lib/types/models/chart-render/axes/log-axis-data.d.ts

@@ -0,0 +1,4 @@
+import type { EChartRenderSpecOperator } from '../../../types';
+export declare const LOG_BAR_LAYOUT_META = "__univerLogBarLayout";
+/** Only the ephemeral spec is filtered; source values and category indexes remain intact. */
+export declare const logAxisDataOperator: EChartRenderSpecOperator;

package/lib/types/models/chart-render/axes/log-axis-ticks.d.ts

@@ -0,0 +1,5 @@
+import type { registerLayout } from 'echarts';
+/** Renderer-only marker; never stored in chart configuration or OOXML. */
+export declare const LOG_AXIS_TICKS_META = "__univerLogAxisTicks";
+/** ECharts 6.1 builds axis text during Grid.resize, before registered series layouts. */
+export declare function installLogAxisTicks(register: typeof registerLayout): void;

package/lib/types/models/chart-render/axes/log-bar-layout.d.ts

@@ -0,0 +1,3 @@
+import type { registerLayout } from 'echarts';
+/** Local adapter for the ECharts internal layout contract; no persisted or public API fields. */
+export declare function installLogBarLayout(register: typeof registerLayout): void;

package/lib/types/models/chart-render/axes/value-axis-scale.d.ts

@@ -0,0 +1,13 @@
+import type { IAxisOptions } from '../../../types';
+export declare const OFFICE_AXIS_HEADROOM = 0.05;
+export declare const OFFICE_HORIZONTAL_AXIS_SPLITS = 10;
+export declare function getOfficeAutoMinimum(min: number, max: number, majorUnit: number | undefined, scatter: boolean, headroom: number, splitNumber: number): number | undefined;
+export declare function createValueAxisScale(extent: readonly [number, number], options: Readonly<Pick<IAxisOptions, 'min' | 'max' | 'majorUnit' | 'autoScale'>>, context: {
+    readonly horizontal: boolean;
+    readonly percentStacked: boolean;
+    readonly threeDimensional: boolean;
+}): {
+    readonly min: number;
+    readonly max: number;
+    readonly ticks: readonly number[];
+};

package/lib/types/models/chart-render/converter/calendar-date-axis.d.ts

@@ -3,5 +3,5 @@ interface ICalendarDateAxis {
     data: string[];
     key: (timestamp: number) => string;
 }
-export declare function resolveCalendarDateAxis(category: IChartConfig['category'], axis: Pick<IAxisOptions, 'baseTimeUnit' | 'min' | 'max'> | undefined): ICalendarDateAxis | undefined;
+export declare function resolveCalendarDateAxis(category: IChartConfig['category'], axis: Pick<IAxisOptions, 'baseTimeUnit' | 'min' | 'max'> | undefined, useDefault1900DateSystem?: boolean): ICalendarDateAxis | undefined;
 export {};

package/lib/types/models/chart-render/converter/render-spec-operators/empty-style-operator.d.ts

@@ -1,2 +1,4 @@
 import type { EChartRenderSpecOperator } from '../../../../types';
 export declare const emptyStyleOperator: EChartRenderSpecOperator;
+/** Axis-local messages must not replace the healthy series on another value axis. */
+export declare const logAxisStatusOperator: EChartRenderSpecOperator;

package/lib/types/models/chart-render/converter/render-spec-operators/legend-style.operator.d.ts

@@ -1,2 +1,12 @@
-import type { EChartRenderSpecOperator } from '../../../../types';
+import type { LegendComponentOption } from 'echarts';
+import type { ChartRuntimeStyle, EChartRenderSpecOperator } from '../../../../types';
+import { LegendPositionEnum } from '../../../../enum';
+interface IGridInfo {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}
+export declare function getLegendPosition(position: LegendPositionEnum | undefined, style: ChartRuntimeStyle, gridInfo: Pick<IGridInfo, 'top'>): LegendComponentOption;
 export declare const legendStyleOperator: EChartRenderSpecOperator;
+export {};

package/lib/types/models/chart-render/converter/render-spec-operators/log-axis-scale.d.ts

@@ -0,0 +1,7 @@
+/** Positive, non-smoothed autoZero domains only. Authored endpoints remain exact. */
+export declare function calculateLogAxisRange(dataMin: number, dataMax: number, base: number, fixedMin?: number, fixedMax?: number): {
+    min: number;
+    max: number;
+} | undefined;
+/** Integer exponent steps anchored at the actual minimum, including manual non-power minima. */
+export declare function calculateLogAxisTicks(min: number, max: number, base: number, step: number): number[];

package/lib/types/models/chart-render/converter/render-spec-operators/series-style-operator/series-fill-pattern.d.ts

@@ -0,0 +1,15 @@
+import type { IChartSeriesFillPattern } from '../../../../../types';
+export declare function createSeriesPatternStyle(pattern: IChartSeriesFillPattern, renderColor: (color: string) => string): {
+    color: string;
+    decal: null;
+} | {
+    color: string;
+    decal: {
+        symbol: string;
+        symbolSize: number;
+        dashArrayX: number[];
+        dashArrayY: number[];
+        rotation: number;
+        color: string;
+    };
+};

package/lib/types/models/chart-render/converter/render-spec-operators/tools.d.ts

@@ -23,5 +23,7 @@ export declare const getGradientColor: (color: string, gradientFill: boolean) =>
     }[];
 };
 type RenderColorFunc = (color: string) => string;
-export declare const getRenderColorFunc: (style: ChartRuntimeStyle) => RenderColorFunc;
+export declare const getRenderColorFunc: (style: {
+    readonly runtime: Pick<ChartRuntimeStyle["runtime"], "getRenderColor">;
+}) => RenderColorFunc;
 export {};

package/lib/types/models/chart-render/converter/render-spec-operators/watermark.operator.d.ts

@@ -1,2 +1,4 @@
+import type { GraphicComponentOption } from 'echarts';
 import type { EChartRenderSpecOperator } from '../../../../types';
 export declare const chartWaterMarkerOperator: EChartRenderSpecOperator;
+export declare function createChartWatermarkGraphics(width?: number, height?: number): GraphicComponentOption[];

package/lib/types/models/chart-render/echart-render-model/base-chart-render-instance.d.ts

@@ -1,9 +1,9 @@
 import type { IDisposable } from '@univerjs/core';
 import type { ChartElementEventHandler, ChartElementEventType, ChartRenderMode, ChartRuntimeStyle, EChartSpec, IChartHost, IChartHostRect, IChartHostStyle, IChartInstance, IChartRenderInput, IChartRenderInstance, IChartRenderInstanceCreateContext } from '../../../types';
 import type { IChartRuntimeAdaptiveSize } from '../../common/adaptive-size/chart-runtime-adaptive-size';
+import type { EChartRenderEngine } from './echart-render-engine';
 import type { EChartRenderModel } from './echart-render-model';
 import { Disposable } from '@univerjs/core';
-import { EChartRenderEngine } from './echart-render-engine';
 interface IPreparedRenderFrame {
     hostStyle: IChartHostStyle;
     renderRect: IChartHostRect;

package/lib/types/models/chart-render/echart-render-model/chart-dimension-render-instance.d.ts

@@ -0,0 +1,28 @@
+import type { IDisposable } from '@univerjs/core';
+import type { ChartElementEventHandler, ChartElementEventType, IChartHost, IChartRenderInput, IChartRenderInstance, IChartRenderInstanceCreateContext, IChartRenderTransitionOptions } from '../../../types';
+import type { EChartRenderModel } from './echart-render-model';
+import { Disposable } from '@univerjs/core';
+import { ChartRenderMode } from '../../../types';
+export declare class ChartDimensionRenderInstance extends Disposable implements IChartRenderInstance {
+    readonly mode: ChartRenderMode;
+    private readonly _model;
+    private readonly _context?;
+    private readonly _addWatermark;
+    private _host?;
+    private _instance?;
+    private _factory?;
+    private _editing;
+    private _closed;
+    private readonly _listeners;
+    constructor(mode: ChartRenderMode, _model: EChartRenderModel, _context?: IChartRenderInstanceCreateContext | undefined, _addWatermark?: () => boolean);
+    bind(host: IChartHost): void;
+    private _clearInstance;
+    private _getInstance;
+    render(input: IChartRenderInput): Promise<void>;
+    renderTransition(previous: IChartRenderInput, input: IChartRenderInput, options: IChartRenderTransitionOptions): Promise<void>;
+    exportImg(): Promise<string | undefined>;
+    resize(): void;
+    setElementEditMode(enabled: boolean): void;
+    on(type: ChartElementEventType, handler: ChartElementEventHandler): IDisposable;
+    dispose(): void;
+}

package/lib/types/models/chart-render/echart-render-model/dom-chart-instance.d.ts

@@ -3,6 +3,7 @@ import type { ChartElementEventHandler, ChartElementEventType, EChartSpec, IChar
 import type { EChartRenderModel } from './echart-render-model';
 import { BaseChartRenderInstance } from './base-chart-render-instance';
 export declare class DomChartInstance extends BaseChartRenderInstance {
+    private _renderVersion;
     private _chartInstance;
     constructor(renderModel: EChartRenderModel, context?: IChartRenderInstanceCreateContext<EChartSpec>);
     render(input: IChartRenderInput): Promise<void>;

package/lib/types/models/chart-render/echart-render-model/echart-render-engine.d.ts

@@ -1,4 +1,6 @@
+import type { IDisposable } from '@univerjs/core';
 import type { ChartElementEventHandler, ChartElementEventType, ChartImageSource, EChartInstance, EChartSpec, IChartElementHit, IChartRenderAsImageOptions, IChartRenderRuntimeOptions, IChartRenderTransitionOptions } from '../../../types';
+import type { IEChartsRenderHooks } from './echarts-render-hooks';
 import { Disposable } from '@univerjs/core';
 /** 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;
@@ -22,10 +24,14 @@ export declare class EChartRenderEngine extends Disposable implements EChartInst
     private readonly _emittedElementEventKeys;
     private _emittedElementEventKeysClearQueued;
     private readonly _fieldButtonLayoutHandler;
-    constructor();
+    private readonly _renderHooks;
+    constructor(renderHooks?: Iterable<IEChartsRenderHooks>);
     mount(id: string | HTMLElement): void;
     resize(echartsProviderOrOptions?: any | IChartRenderRuntimeOptions): void;
     private _ensureChartInstance;
+    registerRenderHook(hooks: IEChartsRenderHooks): IDisposable;
+    private _getRenderHooks;
+    private _runWithContext;
     get containerElement(): HTMLElement | null;
     render(spec: EChartSpec, echartsProviderOrOptions?: any | IChartRenderRuntimeOptions): void;
     renderTransition(previousSpec: EChartSpec, spec: EChartSpec, options: IChartRenderRuntimeOptions & IChartRenderTransitionOptions): Promise<void>;

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

@@ -1,24 +1,37 @@
-import type { ChartRuntimeStyle, EChartSpec, IChartConfig, IChartHostRect, IChartInstance, IChartRenderInstance, IChartRenderInstanceCreateContext, IChartRenderModel, IChartRenderModelImageExportInput, IChartRenderModelImageExportOptions, IChartRenderModelImageExportResult, IChartRenderModelStylizeInit } from '../../../types';
-import type { IWordCloudRenderConfig } from '../../../wordcloud-chart/word-cloud-render-config';
+import type { IDisposable } from '@univerjs/core';
+import type { ChartRenderEvent, ChartRenderMode, ChartRuntimeStyle, EChartSpec, IChartConfig, IChartHostRect, IChartInstance, IChartRenderInstance, IChartRenderInstanceCreateContext, IChartRenderModel, IChartRenderModelImageExportInput, IChartRenderModelImageExportOptions, IChartRenderModelImageExportResult, IChartRenderModelStylizeInit, IChartRenderSpecConverter } from '../../../types';
 import { Disposable } from '@univerjs/core';
-import { ChartRenderMode } from '../../../types';
-export interface IEChartRenderModelOptions {
-    wordCloudRenderConfig?: IWordCloudRenderConfig;
+import { EChartRenderEngine } from './echart-render-engine';
+export interface IChartInstanceFactory {
+    canRender(config: IChartConfig): boolean;
+    create(mode: ChartRenderMode, context: IChartRenderInstanceCreateContext | undefined, addWatermark: () => boolean): IChartRenderInstance;
+}
+export interface IChartImageExporter {
+    canExport(input: IChartRenderModelImageExportInput): boolean;
+    exportImage(input: IChartRenderModelImageExportInput, options: IChartRenderModelImageExportOptions, addWatermark: boolean): Promise<IChartRenderModelImageExportResult>;
+}
+export interface IChartRenderExtension {
+    readonly name: string;
+    specConverter?: IChartRenderSpecConverter<EChartSpec>;
+    instanceFactory?: IChartInstanceFactory;
+    imageExporter?: IChartImageExporter;
+    onEvent?(event: ChartRenderEvent): void;
 }
 export declare class EChartRenderModel extends Disposable implements IChartRenderModel {
     private _specConverters;
     private _specOperators;
     private _addWatermark;
-    private readonly _wordCloudRenderConfig?;
-    constructor(_addWatermark: boolean, options?: IEChartRenderModelOptions);
+    private readonly _extensions;
+    constructor(_addWatermark: boolean);
+    registerExtension(extension: IChartRenderExtension): IDisposable;
+    emitChartEvent(event: ChartRenderEvent): void;
+    findInstanceFactory(config: IChartConfig): IChartInstanceFactory | undefined;
+    createRenderEngine(): EChartRenderEngine;
     updateWatermark(addWatermark: boolean): void;
     private _addSpecConverters;
     private _addSpecOperators;
     createChartInstance(): IChartInstance<EChartSpec>;
     createChartInstance(mode: ChartRenderMode, context?: IChartRenderInstanceCreateContext<EChartSpec>): IChartRenderInstance;
-    clearRuntimeCache(chartId: string): void;
-    clearAllRuntimeCache(): void;
-    dispose(): void;
     toSpec(config: IChartConfig, style: ChartRuntimeStyle): import("echarts").EChartsOption;
     private _getShowEmpty;
     stylizeSpec(spec: EChartSpec, stylizeInit: IChartRenderModelStylizeInit<EChartSpec>, rect: IChartHostRect): EChartSpec;

package/lib/types/models/chart-render/echart-render-model/echarts-render-hooks.d.ts

@@ -0,0 +1,7 @@
+import type { EChartSpec } from '../../../types';
+export declare const CHART_IMAGE_RENDER_SETTLE_TIMEOUT = 1000;
+/** Synchronous layout context and resources required before image capture. */
+export interface IEChartsRenderHooks {
+    runWithContext<T>(chartId: string | undefined, action: () => T): T;
+    waitForResources(spec: EChartSpec): Promise<void>;
+}

package/lib/types/models/chart-render/echart-render-model/index.d.ts

@@ -1,3 +1,2 @@
 export { EChartRenderEngine, resolveEChartChordHit, resolveEChartPieCompositeHit, resolveEChartSeriesIdentity, } from './echart-render-engine';
 export { EChartRenderModel } from './echart-render-model';
-export type { IEChartRenderModelOptions } from './echart-render-model';

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

@@ -0,0 +1,3 @@
+import { ChartTypeBits } from '../../../enum';
+/** Preserve authored flags while adapting display content to the chart's capabilities. */
+export declare function getRenderedLabelContentType(contentType: number | undefined, chartType: ChartTypeBits): number | undefined;

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

@@ -1,4 +1,11 @@
 export interface IChartLocaleTexts {
+    projectionInvalid: string;
+    projectionUnavailable: string;
+    projectionRetry: string;
+    projectionPngOnly: string;
+    logUnsupported: string;
+    logNoPositive: string;
+    logPercent: string;
     seriesDefaultName: string;
     blank: string;
     boxplotMin: string;

package/lib/types/models/common/constants/default-chart-style.d.ts

@@ -614,6 +614,11 @@ export declare const defaultChartConfig: {
     };
     backgroundColor: string;
     axis: {
+        logarithmic: {
+            base: number;
+            minBase: number;
+            maxBase: number;
+        };
         lineVisible: boolean;
         labelVisible: boolean;
         reverse: boolean;
@@ -652,10 +657,7 @@ export declare const defaultChartConfig: {
         lineStyle: AreaLineStyle;
     };
     bar: {
-        is3D: boolean;
         shape: BarShape;
-        rotX: number;
-        rotY: number;
     };
     bubble: {
         scale: number;
@@ -671,7 +673,6 @@ export declare const defaultChartConfig: {
         borderColor: string;
         labelPosition: PieLabelPosition;
         hasPaddingAngle: boolean;
-        is3D: boolean;
     };
     combination: {
         firstChartType: ChartTypeBits;

package/lib/types/models/common/theme/build-in-theme/theme-util.d.ts

@@ -1,4 +1,6 @@
+import type { DeepReadonly } from '@univerjs/core';
+import type { DeepPartial } from '../../../../types';
 import type { IEchartTheme, IEchartThemeContent } from './types';
 export type axesType = 'category' | 'value' | 'time' | 'log' | 'all' | undefined;
-export declare function getThemeAxesByType(themeInfo: IEchartTheme, axesType: axesType): import("./types").IEchartThemeAxisConfig | undefined;
+export declare function getThemeAxesByType(themeInfo: DeepReadonly<DeepPartial<IEchartTheme>> | undefined, axesType: axesType): DeepReadonly<import("./types").IEchartThemeAxisConfig> | undefined;
 export declare function getThemeProps<K extends keyof IEchartThemeContent>(themeInfo: IEchartTheme | undefined, key: K): IEchartThemeContent[K];

package/lib/types/types.d.ts

@@ -1,4 +1,4 @@
-import type { IDisposable, Nullable } from '@univerjs/core';
+import type { DateSystem, IDisposable, Nullable } from '@univerjs/core';
 import type { BarSeriesOption, EChartsOption } from 'echarts';
 import type { Observable } from 'rxjs';
 import type { ChartColor, IChartLinearGradient } from './chart-builder/chart-color';
@@ -6,11 +6,12 @@ import type { IChartPieCompositeSpec, PieCompositeMarkRole, PieCompositePlot } f
 import type { IChartDataAggregation } from './chart-data-aggregation';
 import type { AreaLineStyle, AxisAlignEnum, AxisValueType, BarShape, CategoryType, ChartAxisDimension, ChartBorderDashType, ChartChordFocusMode, ChartChordLabelPosition, ChartChordRibbonColorMode, ChartGaugeMode, ChartGaugePointerShape, ChartHistogramBinKind, ChartMarkLineLabelPosition, ChartSemanticAxis, ChartSourceDataTypeEnum, ChartSunburstLabelPosition, ChartTrendlineType, ChartTypeBits, ChartWaterfallPointRole, DataOrientation, HistogramBinningMode, InvalidValueType, IRuntimeAxisPosition, IRuntimeAxisPriority, LabelAlignEnum, LabelContentType, LegendPositionEnum, LinePointShape, PieLabelPosition, RadarShape, RelationChartLayoutEnum, ScatterLineType, SelectModeEnum, SeriesLabelPosition, TitlePositionEnum, TreemapParentLabelLayout, WaterfallSeriesTypeEnum, WaterfallStackTypeEnum, WordCloudShapeEnum } from './enum';
 import type { ICartesianPointData } from './models/chart-data/internal/cartesian-point-data';
+import type { analyzeChartAxisScales } from './models/chart-render/axes/chart-axis-scale';
 import type { IChartRuntimeAdaptiveSize } from './models/common/adaptive-size/chart-runtime-adaptive-size';
 import type { IChartLocaleTexts } from './models/common/chart-locale-texts';
 import type { IEchartTheme } from './models/common/theme/build-in-theme/types';
-import type { IWordCloudRenderConfig } from './wordcloud-chart/word-cloud-render-config';
-export type DeepPartial<T> = T extends IChartLinearGradient | IChartLabelPattern ? T : T extends Record<string, any> ? T extends any[] ? T : {
+import type { IWordCloudRenderConfig } from './wordcloud';
+export type DeepPartial<T> = T extends IChartLinearGradient | IChartLabelPattern | IChartSeriesFillPattern ? T : T extends Record<string, any> ? T extends any[] ? T : {
     [key in keyof T]+?: DeepPartial<T[key]>;
 } : T;
 /** Recursive patch shape that permits `null` at every field and treats arrays as atomic values. */
@@ -47,6 +48,8 @@ export interface IUniverDataSetCategorySpan {
  * used as a fallback category vector.
  */
 export interface IUniverDataSet {
+    /** Runtime date-system owner for authored serial bounds; never persisted in chart resources. */
+    dateSystem?: DateSystem;
     source: OptionDataValue[][];
     dimensions: Array<DimensionDefinitionLoose>;
     sourceType?: ChartSourceDataTypeEnum[][];
@@ -554,6 +557,9 @@ export interface IRuntimeAxis {
     type: AxisValueType;
 }
 export interface IChartRuntimeContext {
+    /** Effective projection policy; never persisted into authored chart style. */
+    threeDRightAngleAxes?: boolean;
+    axisScaleStates?: ReturnType<typeof analyzeChartAxisScales>;
     adaptiveSize?: IChartRuntimeAdaptiveSize;
     /** Runtime-only host policy that opts chart rendering into width-based adaptive sizing. */
     enableAdaptiveSize?: boolean;
@@ -650,6 +656,8 @@ export interface IGridLineStyle {
     dashType?: ChartBorderDashType;
 }
 export interface IAxisOptions {
+    scaleType?: 'linear' | 'log';
+    logBase?: number;
     /** Axis visibility (inverse of OOXML c:delete); authored gridlines and titles remain independent. */
     visible?: boolean;
     /**
@@ -675,7 +683,7 @@ export interface IAxisOptions {
     max?: number | null;
     /** Positive interval between major ticks on a numeric value axis; absent means automatic. */
     majorUnit?: number;
-    /** Office-imported value-axis bounds; omitted keeps the native range-focused defaults. */
+    /** Office-imported value-axis bounds for the three-dimensional scene scale. */
     autoScale?: 'office';
     /** Calendar granularity of an imported date axis; absent retains elapsed-time behavior. */
     baseTimeUnit?: 'days' | 'months' | 'years';
@@ -709,6 +717,12 @@ export interface IPointStyle {
     size: number;
     color: Nullable<string>;
 }
+/** Imported DrawingML series/point fill. Omission inherits; null clears the pattern. */
+export interface IChartSeriesFillPattern {
+    preset: string;
+    foregroundColor: string;
+    backgroundColor: string;
+}
 export interface IDataPointStyle extends Omit<IPointStyle, 'color'> {
     /** Per-point stroke overrides; absent properties inherit the series border. */
     border?: Partial<ISeriesStyle['border']>;
@@ -718,6 +732,7 @@ export interface IDataPointStyle extends Omit<IPointStyle, 'color'> {
         offset?: [number, number];
     };
     color: Nullable<ChartColor>;
+    fillPattern?: IChartSeriesFillPattern | null;
     /** Fill opacity for this data point, from 0 (transparent) to 1 (opaque). */
     fillOpacity?: number;
 }
@@ -729,6 +744,7 @@ export interface ISeriesStyle {
     /** Explicit line-series smoothing; overrides chart-level smoothing when present. */
     smooth?: boolean;
     color: Nullable<ChartColor>;
+    fillPattern?: IChartSeriesFillPattern | null;
     /** Fill opacity for this series, from 0 (transparent) to 1 (opaque). */
     fillOpacity: number;
     border: {
@@ -757,7 +773,7 @@ export interface ISeriesStyle {
     };
 }
 export type RightYAxisOptions = Omit<IAxisOptions, 'reverse'>;
-export interface IAllSeriesStyle extends Pick<ISeriesStyle, 'border' | 'label' | 'rightYAxis' | 'point' | 'color' | 'fillOpacity' | 'waterfall' | 'scatterLine'> {
+export interface IAllSeriesStyle extends Pick<ISeriesStyle, 'border' | 'label' | 'rightYAxis' | 'point' | 'color' | 'fillOpacity' | 'fillPattern' | 'waterfall' | 'scatterLine'> {
 }
 export interface ITrendLine {
     /** Stable source identity. `seriesIndex` remains the fallback for legacy snapshots. */
@@ -817,13 +833,7 @@ export interface IBarStyle {
     gapWidth?: number;
     /** Series overlap from -100 (separated) through 100 (fully overlapped). */
     overlap?: number;
-    /** Exchange metadata. Renderers without 3D support may ignore these fields. */
-    is3D: boolean;
     shape: BarShape;
-    /** OOXML view rotation around the horizontal axis, in degrees. */
-    rotX: number;
-    /** OOXML view rotation around the vertical axis, in degrees. */
-    rotY: number;
 }
 export interface IChartBubbleStyle {
     /** Maximum bubble size as an OOXML-compatible percentage. */
@@ -838,6 +848,26 @@ export interface IChartPlotArea {
     width: number;
     height: number;
 }
+/** Authored OOXML-compatible view semantics; camera matrices are renderer-owned. */
+export interface IChart3DView {
+    rotX?: number;
+    rotY?: number;
+    rightAngleAxes?: boolean;
+    /** OOXML perspective value, not a camera field of view. */
+    perspective?: number;
+    /** Omission preserves automatic height. */
+    heightPercent?: number;
+    depthPercent?: number;
+}
+export interface IChart3DStyle {
+    view?: IChart3DView;
+    /** Only applies to non-stacked Column and Bar charts. */
+    grouping?: 'standard' | 'clustered';
+    /** Series depth gap as a percentage; independent of category gapWidth. */
+    gapDepth?: number;
+}
+export interface IChartDepthAxisStyle extends Pick<IAxisOptions, 'lineVisible' | 'lineStyle' | 'label' | 'gridLine' | 'tick' | 'reverse'> {
+}
 export interface IChartErrorBars {
     /** Data-source field index of the owning value series, not its display order. */
     seriesIndex: number;
@@ -858,6 +888,9 @@ export interface IChartErrorBars {
     };
 }
 export interface IChartStyle {
+    /** Retained while inactive in 2D; the ThreeD chart type bit alone enables 3D. */
+    threeD?: IChart3DStyle;
+    depthAxis?: IChartDepthAxisStyle;
     width: number;
     height: number;
     theme: string;
@@ -878,6 +911,7 @@ export interface IChartStyle {
     /** Imported PowerPoint Cartesian edge/label spacing; the inner plot remains automatic. */
     automaticLayout?: 'powerpoint';
     titles: {
+        depthAxisTitle?: IChartTitleStyle;
         title: IChartTitleStyle;
         subtitle: IChartTitleStyle;
         xAxisTitle: IChartTitleStyle;
@@ -911,8 +945,6 @@ export interface IChartStyle {
         labelStyle: IPieLabelStyle;
         borderColor: string;
         hasPaddingAngle: boolean;
-        /** Exchange metadata. Renderers without 3D support may ignore this field. */
-        is3D: boolean;
         isHalfPie: boolean;
         rosePie: boolean;
         showLabelLine: boolean;
@@ -923,7 +955,10 @@ export interface IChartStyle {
         sliceStyles: {
             [index: number]: {
                 color: Nullable<ChartColor>;
+                fillPattern?: IChartSeriesFillPattern | null;
                 fillOpacity?: number;
+                /** Radius ratio; explicit zero overrides overall pie explosion. */
+                explosion?: number;
             };
         };
     };
@@ -991,7 +1026,7 @@ export interface IRelationForceOptions {
     gravity?: number;
 }
 export type ChartStyle = DeepPartial<IChartStyle>;
-export type ChartRenderRuntimeContext = Omit<DeepPartial<IChartRuntimeContext>, 'adaptiveSize' | 'localeTexts' | 'updateAdaptiveSizeFromDomRender'> & Pick<IChartRuntimeContext, 'localeTexts'> & Partial<Pick<IChartRuntimeContext, 'adaptiveSize' | 'updateAdaptiveSizeFromDomRender'>>;
+export type ChartRenderRuntimeContext = Omit<DeepPartial<IChartRuntimeContext>, 'axisScaleStates' | 'adaptiveSize' | 'localeTexts' | 'updateAdaptiveSizeFromDomRender'> & Pick<IChartRuntimeContext, 'localeTexts'> & Partial<Pick<IChartRuntimeContext, 'axisScaleStates' | 'adaptiveSize' | 'updateAdaptiveSizeFromDomRender'>>;
 export type ChartRuntimeStyle = ChartStyle & {
     direction: ChartDirection;
     runtime: ChartRenderRuntimeContext;
@@ -1124,6 +1159,13 @@ export interface IChartRenderModelStylizeInit<Spec> {
     chartConfig: IChartConfig;
     chartInstance?: IChartInstance<Spec>;
 }
+/** Renderer lifecycle notifications; these are runtime events, not persisted commands. */
+export type ChartRenderEvent = {
+    type: 'render' | 'remove' | 'detach';
+    chartId: string;
+} | {
+    type: 'dispose';
+};
 export interface IChartRenderModel<Spec extends Record<string, any> = Record<string, any>> extends IDisposable {
     toSpec(chartConfig: IChartConfig, style: ChartRuntimeStyle): Spec;
     stylizeSpec(spec: Spec, stylizeInit: IChartRenderModelStylizeInit<Spec>, rect: IChartHostRect): Spec;
@@ -1131,8 +1173,7 @@ export interface IChartRenderModel<Spec extends Record<string, any> = Record<str
     updateWatermark(addWatermark: boolean): void;
     createChartInstance(): IChartInstance<Spec>;
     createChartInstance(mode: ChartRenderMode, context?: IChartRenderInstanceCreateContext<Spec>): IChartRenderInstance;
-    clearRuntimeCache?(chartId: string): void;
-    clearAllRuntimeCache?(): void;
+    emitChartEvent?(event: ChartRenderEvent): void;
     dispose(): void;
 }
 export interface IChartThemeOptions {

package/lib/types/util.d.ts

@@ -3,7 +3,7 @@ export declare const chartBitsUtils: {
     has(bit: number, attribute: number): boolean;
     baseOn(bit: number, base: number): boolean;
     remove(bit: number, attribute: number): number;
-    chartBitToString(bit: ChartTypeBits): "" | "line" | "bar" | "pie" | "radar" | "scatter" | "combination" | "wordCloud" | "funnel" | "sankey" | "heatmap" | "boxplot" | "candlestick" | "treemap" | "sunburst" | "gauge" | "chord" | "graph";
+    chartBitToString(bit: ChartTypeBits): "" | "line" | "bar" | "pie" | "radar" | "scatter" | "combination" | "wordCloud" | "funnel" | "sankey" | "heatmap" | "boxplot" | "candlestick" | "treemap" | "sunburst" | "gauge" | "chord" | "graph" | undefined;
 };
 export declare function mergeChartConfig<T extends object>(current: T | undefined, update: Partial<T>): T;
 export declare const setProperty: (data: Record<string, any>, propertyPath: string, value: any) => void;

package/lib/types/{models/chart-render/converter/converters/word-cloud-converter.d.ts → wordcloud/adapters/chart-spec-adapter.d.ts}

@@ -1,2 +1,2 @@
-import type { EChartSpec, IChartRenderSpecConverter } from '../../../../types';
+import type { EChartSpec, IChartRenderSpecConverter } from '../../types';
 export declare const wordCloudChartConverter: IChartRenderSpecConverter<EChartSpec>;

package/lib/types/{wordcloud-chart/adapters/echarts/install.d.ts → wordcloud/adapters/echarts-adapter.d.ts}

@@ -1,5 +1,5 @@
-import type { echarts } from '../../../utils/echarts';
-import type { IWordCloudEChartsSeriesOption } from '../../types';
-export declare function registerWordCloudChart(echartsInstance: typeof echarts): typeof echarts;
+import type { IWordCloudEChartsApi } from '../echarts-api';
+import type { IWordCloudEChartsSeriesOption } from '../types';
+export declare function registerWordCloudChart(echartsInstance: IWordCloudEChartsApi): IWordCloudEChartsApi;
 export declare function waitForWordCloudImageResourcesReady(spec: unknown, timeout?: number): Promise<void>;
 export type { IWordCloudEChartsSeriesOption };

package/lib/types/{wordcloud-chart/adapters/echarts → wordcloud}/chart-view.d.ts

@@ -1,5 +1,5 @@
-import type { echarts } from '../../../utils/echarts';
+import type { IWordCloudEChartsApi } from './echarts-api';
 export interface IRegisterWordCloudChartViewContext {
     createTextElement(layout: any, data: any, dataIndex: number, seriesModel: any): unknown;
 }
-export declare function registerWordCloudChartView(echartsInstance: typeof echarts, context: IRegisterWordCloudChartViewContext): void;
+export declare function registerWordCloudChartView(echartsInstance: IWordCloudEChartsApi, context: IRegisterWordCloudChartViewContext): void;

package/lib/types/{wordcloud-chart → wordcloud}/core/collision/box-shape-engine.d.ts

@@ -16,7 +16,7 @@ export declare class BoxShapeEngine implements ICollisionEngine<IBoxFootprint> {
     private _lastShapeCheck;
     constructor(_grid: IWordCloudLayoutGrid, _shapeGrid: Uint8Array);
     createFootprint(_word: IWordCloudEncodedWord, style: ICollisionTextStyle, rotation: number): IBoxFootprint;
-    getBounds(footprint: IBoxFootprint, candidate: ICollisionCandidate): import("../../types").IWordCloudBounds;
+    getBounds(footprint: IBoxFootprint, candidate: ICollisionCandidate): import("../..").IWordCloudBounds;
     isInsideLayout(footprint: IBoxFootprint, candidate: ICollisionCandidate, width: number, height: number): boolean;
     canPlace(footprint: IBoxFootprint, candidate: ICollisionCandidate): boolean;
     isShapeBlocked(footprint: IBoxFootprint, candidate: ICollisionCandidate): boolean;

package/lib/types/wordcloud/echarts-api.d.ts

@@ -0,0 +1,3 @@
+import type * as echarts from 'echarts';
+export interface IWordCloudEChartsApi extends Pick<typeof echarts, 'extendChartView' | 'extendSeriesModel' | 'format' | 'getInstanceByDom' | 'graphic' | 'helper' | 'init' | 'List' | 'number' | 'registerAction' | 'registerLayout' | 'registerPreprocessor' | 'util'> {
+}

package/lib/types/{wordcloud-chart/adapters/echarts → wordcloud}/echarts-options.d.ts

@@ -1,7 +1,7 @@
 export declare const WORD_CLOUD_SERIES_TYPE = "wordCloud";
 export declare const WORD_CLOUD_DEFAULT_OPTION: {
     readonly z: 2;
-    readonly maskSource: import("../../types").IWordCloudEChartsMaskSource;
+    readonly maskSource: import("./types").IWordCloudEChartsMaskSource;
     readonly colorBy: "data";
     readonly keepAspect: false;
     readonly left: "center";

package/lib/types/wordcloud/index.d.ts

@@ -0,0 +1,16 @@
+export { registerWordCloudChart } from './adapters/echarts-adapter';
+export { layoutWordCloudChart, resolveLayoutOptions, } from './canvas';
+export type { CallbackOption, IFieldOption, IWordCloudFontSizeMeta } from './core/layout/font-scale';
+export { createWordCloudFontSizeAccessor, extent, generateWordCloudSqrtScale, normalizeWordCloudFontSizeRange, signedSqrt, WORD_CLOUD_DEFAULT_FONT_SIZE_RANGE, } from './core/layout/font-scale';
+export { createBuiltinMaskGrid, createMaskGridFromShape, createTextMaskGrid, normalizeMaskGrid, segmentMaskGrid, } from './core/shape/built-in-shapes';
+export { encodeWordCloudWords } from './core/text/formatter';
+export { normalizeWordCloudData } from './core/text/normalize';
+export { DEFAULT_WORD_CLOUD_CHART_SPEC, resolveWordCloudSpec, } from './defaults';
+export { WORD_CLOUD_DEFAULT_OPTION, WORD_CLOUD_SERIES_TYPE } from './echarts-options';
+export { registerWordCloudRendering } from './register-word-cloud-rendering';
+export { WordCloudMaskImageOptions, WordCloudResourceConfig } from './resources/word-cloud-resource-config';
+export type { INormalizedWordCloudDatum, IResolvedWordCloudSpec, IWordCloudBounds, IWordCloudChartSpec, IWordCloudDataSource, IWordCloudEChartsMaskSource, IWordCloudEChartsSeriesDataItem, IWordCloudEChartsSeriesOption, IWordCloudEncodedWord, IWordCloudEncoding, IWordCloudFieldMapping, IWordCloudLayoutMask, IWordCloudLayoutOptions, IWordCloudLayoutResult, IWordCloudMaskGrid, IWordCloudMaskShapeSpec, IWordCloudPlacedWord, IWordCloudProtocolSpec, IWordCloudSegmentationRegion, IWordCloudSegmentationResult, IWordCloudTextMarkAttrs, IWordCloudTextMarkSpec, IWordCloudTextMeasurer, IWordCloudTextSprite, WordCloudFontSizeRange, WordCloudShape, } from './types';
+export { DEFAULT_WORD_CLOUD_SHAPE, normalizeWordCloudShape, SUPPORTED_WORD_CLOUD_SHAPES, } from './types';
+export { WordCloudExtension } from './word-cloud-extension';
+export { DEFAULT_WORD_CLOUD_RENDER_CONFIG, resolveWordCloudRenderConfig, STATIC_CHART_WORD_CLOUD_RENDER_CONFIG, } from './word-cloud-render-config';
+export type { IResolvedWordCloudRenderConfig, IWordCloudRenderConfig, } from './word-cloud-render-config';

package/lib/types/{wordcloud-chart/adapters/echarts → wordcloud}/layout-register.d.ts

@@ -1,3 +1,3 @@
-import type { echarts } from '../../../utils/echarts';
+import type { IWordCloudEChartsApi } from './echarts-api';
 export type PerformWordCloudSeriesLayout = (seriesModel: unknown, ecModel: unknown, api: unknown) => void;
-export declare function registerWordCloudLayout(echartsInstance: typeof echarts, performSeriesLayout: PerformWordCloudSeriesLayout): void;
+export declare function registerWordCloudLayout(echartsInstance: IWordCloudEChartsApi, performSeriesLayout: PerformWordCloudSeriesLayout): void;