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

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

@@ -0,0 +1,19 @@
+import type { registerLayout, registerPostUpdate } from 'echarts';
+import type { IAxisOptions } from '../../../types';
+declare const AXIS_PLACEMENT_META = "__univerAxisPlacement";
+interface IAxisPlacement {
+    crossing?: IAxisOptions['crossing'];
+    tickLabelPosition?: IAxisOptions['tickLabelPosition'];
+    position: string;
+}
+interface IAxisOption {
+    position?: string;
+    [AXIS_PLACEMENT_META]?: IAxisPlacement;
+}
+/** 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 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. */
+export declare function installAxisPlacementLayout(register: typeof registerLayout, afterUpdate: typeof registerPostUpdate): void;
+export {};

package/lib/types/models/chart-render/chart-field-button-layout.d.ts

@@ -0,0 +1,51 @@
+import type { ECharts, graphic } from 'echarts';
+import type { ChartRuntimeStyle, EChartSpec, IChartElementHit, IChartFieldButton } from '../../types';
+export declare const CHART_FIELD_BUTTON_GROUP_NAME = "__chart_field_button__";
+interface IFieldButtonLayout {
+    gap: number;
+    inset: number;
+    isRtl: boolean;
+}
+interface IFieldButtonOption {
+    id: string;
+    type?: string;
+    info?: {
+        chartElementHit?: IChartElementHit;
+        fieldButtonLayout?: IFieldButtonLayout;
+    };
+}
+interface IChartLayoutComponent {
+    option: {
+        elements?: IFieldButtonOption[];
+    };
+    get(path: string): unknown;
+    coordinateSystem?: {
+        getRect(): {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    };
+}
+export interface IChartLayoutInstance {
+    getModel?(): {
+        getComponent(mainType: string): IChartLayoutComponent | undefined;
+    };
+    getViewOfComponentModel(model: IChartLayoutComponent): {
+        group: graphic.Group;
+    };
+    getWidth(): number;
+    getHeight(): number;
+}
+export declare function getChartFieldButtonSize(style: ChartRuntimeStyle): {
+    height: number;
+    gap: number;
+};
+export declare function getChartFieldButtonWidth(button: IChartFieldButton, style: ChartRuntimeStyle): number;
+/** Reserve UI bands before ECharts lays out its axes and legend; ordinary charts are unchanged. */
+export declare function reserveChartFieldButtonSpace(spec: EChartSpec, style: ChartRuntimeStyle): void;
+export declare function resolveChartFieldButtonVisibleCount(widths: number[], availableWidth: number, overflowWidth: number, gap: number): number;
+/** Graphic anchors use final component bounds, including containLabel, wrapping, and RTL axis layout. */
+export declare function layoutChartFieldButtons(chart: ECharts): void;
+export {};

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

@@ -0,0 +1,7 @@
+import type { IAxisOptions, IChartConfig } from '../../../types';
+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 {};

package/lib/types/models/chart-render/converter/render-spec-operators/date-axis-label-layout.d.ts

@@ -1,8 +1,13 @@
 interface IDateAxisLabelSize {
     height: number;
     width: number;
+    fontHeight?: number;
 }
 type DateAxisLabelMeasurer = (text: string, font: string) => IDateAxisLabelSize;
+export declare function calculateCalendarAxisInterval(labels: readonly string[], font: string, fontSize: number, rotate: number, axisWidth: number, measureText: DateAxisLabelMeasurer): number | undefined;
+export declare function calculateCalendarYearTicks(dates: readonly number[], maxLabels: number, fixedMin?: number, fixedMax?: number, fixedRotation?: boolean): number[] | undefined;
 export declare function formatDateAxisLabel(value: number, pattern?: string): string;
+export declare function calculateDateAxisMajorTicks(dates: readonly number[], step: number | undefined, unit?: 'days' | 'months' | 'years', fixedMin?: number, fixedMax?: number): number[] | undefined;
 export declare function calculateDateAxisLabelRotate(labels: readonly string[], font: string, labelSlotWidth: number, measureText: DateAxisLabelMeasurer): number;
+export declare function calculateDateAxisSplitNumber(labels: readonly string[], font: string, rotate: number, axisWidth: number, measureText: DateAxisLabelMeasurer): number | undefined;
 export {};

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

@@ -0,0 +1,3 @@
+import type { EChartRenderSpecOperator } from '../../../../types';
+/** OOXML error amounts use the same series/data fields in every document host. */
+export declare const errorBarsOperator: EChartRenderSpecOperator;

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

@@ -1,4 +1,5 @@
 import type { ChartRuntimeStyle, ChartStyle, EChartRenderSpecOperator, IChartConfig, IChartPlotArea } from '../../../../types';
+import type { IChartRuntimeAdaptiveSize } from '../../../common/adaptive-size/chart-runtime-adaptive-size';
 export interface IResolvedCartesianGrid {
     left: number;
     right: number;
@@ -7,6 +8,8 @@ export interface IResolvedCartesianGrid {
     containLabel: boolean;
 }
 export declare function resolveAutomaticCartesianGrid(style: ChartRuntimeStyle, config: IChartConfig): IResolvedCartesianGrid;
+/** Best-fit labels need the available plot rectangle, not the historical canvas-centered 55% pie. */
+export declare function resolveBestFitPiePlotArea(style: ChartStyle, config: IChartConfig, chartLayoutPadding?: number, adaptiveSize?: IChartRuntimeAdaptiveSize): IChartPlotArea | undefined;
 /** Returns authored automatic geometry as a stable manual-editing seed. */
 export declare function resolveChartPlotAreaForEditing(style: ChartStyle, config: IChartConfig): IChartPlotArea;
 export declare const gridStyleOperator: EChartRenderSpecOperator;

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

@@ -1,4 +1,27 @@
+import type { ChartStyle, IChartDataSeries, ILegendStyle } from '../../../../types';
 import type { IChartRuntimeAdaptiveSize } from '../../../common/adaptive-size/chart-runtime-adaptive-size';
 export declare const LEGEND_ICON_WIDTH: number;
+export declare const LEGEND_ITEM_HEIGHT: number;
+export declare const LEGEND_ITEM_GAP = 12;
+export declare const LEGEND_COMPONENT_PADDING = 4;
+export declare const LEGEND_ICON_TEXT_GAP = 5;
 export declare const MinLegendTextWidth = 48;
-export declare function getLegendTextWidthLimit(width?: number, layoutPadding?: number, adaptiveSize?: IChartRuntimeAdaptiveSize): number;
+export declare function resolveLegendKeySize(size?: number): number | undefined;
+export declare function resolveLegendItemMetrics(legend?: Pick<ILegendStyle, 'layout' | 'keyWidth' | 'keySize'>, adaptiveSize?: IChartRuntimeAdaptiveSize): {
+    itemWidth: number;
+    itemHeight: number;
+    itemGap: number;
+};
+export declare function getUniformLegendLayout(itemWidths: readonly number[], availableWidth: number, gap: number): {
+    itemWidth: number;
+    columns: number;
+    rows: number;
+};
+export declare function resolveHorizontalLegendLayout(textWidths: readonly number[], style: ChartStyle, layoutPadding: number, adaptiveSize?: IChartRuntimeAdaptiveSize): {
+    itemWidth: number;
+    columns: number;
+    rows: number;
+};
+export declare function getLegendSeries(series: IChartDataSeries[], order?: readonly number[]): IChartDataSeries[];
+export declare function getLegendRowCount(itemWidths: readonly number[], availableWidth: number, gap: number): number;
+export declare function getLegendTextWidthLimit(width?: number, layoutPadding?: number, adaptiveSize?: IChartRuntimeAdaptiveSize, isHorizontal?: boolean, keySize?: number): number;

package/lib/types/models/chart-render/converter/render-spec-operators/multi-level-category-axis-layout.d.ts

@@ -1,5 +1,5 @@
 import type { ChartRuntimeStyle, EChartSpec, IChartConfig } from '../../../../types';
-export type MultiLevelCategoryAxisSide = 'bottom' | 'left' | 'right';
+export type MultiLevelCategoryAxisSide = 'bottom' | 'top' | 'left' | 'right';
 export interface IMultiLevelCategoryAxis {
     type?: string;
     position?: string;
@@ -16,6 +16,7 @@ export interface IMultiLevelCategoryAxis {
 }
 export interface IMultiLevelCategoryAxisLayout {
     axis: IMultiLevelCategoryAxis;
+    axisStyle?: ChartRuntimeStyle['xAxis'];
     levelInnerDepths: number[];
     levelSizes: number[];
     side: MultiLevelCategoryAxisSide;

package/lib/types/models/chart-render/converter/render-spec-operators/pie-auto-label-layout.d.ts

@@ -0,0 +1,4 @@
+import type { PieSeriesOption } from 'echarts';
+import type { ChartRuntimeStyle } from '../../../../types';
+/** Office bestFit: keep a complete label inside only when its rectangle fits the sector. */
+export declare function applyAutoPieLabelLayout(series: PieSeriesOption, style: ChartRuntimeStyle): void;

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

@@ -0,0 +1,10 @@
+import type { ChartStyle } from '../../../../types';
+interface ITitleTextLayout {
+    font: string;
+    width: number;
+    height: number;
+    lineHeight: number;
+    wrapWidth?: number;
+}
+export declare function getHorizontalTitleLayout(style: ChartStyle, fontSize: number, layoutPadding: number, kind?: 'title' | 'subtitle'): ITitleTextLayout;
+export {};

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

@@ -13,12 +13,14 @@ interface ITooltipFormatterDataContext {
     invalidValueType: InvalidValueType;
     localeText: IChartLocaleTexts;
     isDateAxis: boolean | undefined;
+    isCalendarDateAxis: boolean;
     allSeriesStyle: ChartStyle['allSeriesStyle'];
     seriesStyleMap: ChartStyle['seriesStyleMap'];
     runtimeThemeColors: string[];
     relationNodeMap: Map<string, string>;
     negativeMap: Map<string, boolean>;
     sourceLabelMap: Map<string | number, string[]>;
+    categoryLabelMap: Map<string, string> | undefined;
     getRenderColor: (color: string) => string;
 }
 interface ITooltipFormatters {

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

@@ -1,11 +1,14 @@
 import type { ChartRuntimeStyle, EChartSeriesItem, EChartSpec, ILabelStyle } from '../../../../types';
 import type { ISpecGrid } from './operator-types';
-type PartialLabelStyle = Partial<Pick<ILabelStyle, 'visible' | 'color' | 'fontSize' | 'family' | 'italic' | 'bold' | 'underline' | 'strikethrough' | 'showMaxLabel' | 'showMinLabel'>>;
-export declare function applyLabelStyle(spec: Record<string, any>, path: string, labelStyle: PartialLabelStyle): void;
+type PartialLabelStyle = Partial<Pick<ILabelStyle, 'visible' | 'color' | 'backgroundColor' | 'fontSize' | 'family' | 'italic' | 'bold' | 'underline' | 'strikethrough' | 'showMaxLabel' | 'showMinLabel'>>;
+export declare function applyLabelStyle(spec: Record<string, any>, path: string, labelStyle: PartialLabelStyle, runtimeStyle?: ChartRuntimeStyle): void;
+export declare function resolveLabelBackground(background: ILabelStyle['backgroundColor'], style?: ChartRuntimeStyle): import("./chart-color").ChartRenderColor | undefined;
 export declare function applyLineStyle(spec: Record<string, any>, path: string, labelStyle: PartialLabelStyle): void;
+export declare function getDataLabelOffset(offset: ReadonlyArray<number | undefined> | undefined, style: ChartRuntimeStyle): [number, number] | undefined;
+export declare function applyDataLabelOffsets(series: EChartSeriesItem): void;
 export declare function toArray<T = unknown>(value: T | T[]): T[];
 export declare function seriesForEach(series: EChartSpec['series'], func: (item: EChartSeriesItem, index: number) => void): void;
-export declare const getCategoryLabelVertical: (gridInfo: ISpecGrid, style: ChartRuntimeStyle) => number;
+export declare const getCategoryLabelVertical: (gridInfo: ISpecGrid, style: ChartRuntimeStyle, fontSize: number) => number;
 export declare const getCategoryLabelHorizontal: (gridInfo: ISpecGrid, style: ChartRuntimeStyle, seriesCount: number, axisLabelMaxWidth?: number) => number;
 export declare const getIntegerValue: (value: number, digit?: number) => number;
 export declare const getGradientColor: (color: string, gradientFill: boolean) => string | {

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

@@ -0,0 +1,9 @@
+import type { EChartSpec } from '../../../../types';
+interface IValueAxisScale {
+    min: number;
+    max: number;
+    interval: number;
+}
+export declare function calculateValueAxisScale(dataMin: number, dataMax: number, fixedMin?: number, fixedMax?: number, fixedInterval?: number): IValueAxisScale | undefined;
+export declare function getValueAxisExtent(spec: EChartSpec, dimension: 'x' | 'y', axisIndex: number): [number, number];
+export {};

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

@@ -21,6 +21,7 @@ export declare class EChartRenderEngine extends Disposable implements EChartInst
     private _editOverlay;
     private readonly _emittedElementEventKeys;
     private _emittedElementEventKeysClearQueued;
+    private readonly _fieldButtonLayoutHandler;
     constructor();
     mount(id: string | HTMLElement): void;
     resize(echartsProviderOrOptions?: any | IChartRenderRuntimeOptions): void;

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

@@ -0,0 +1,9 @@
+export interface IPieDataLabelParams {
+    name?: string;
+    value: number;
+    percent: number;
+    data?: {
+        formattedValue?: string;
+    };
+}
+export declare function formatPieDataLabel(params: IPieDataLabelParams, contentType: number, valueScale: number, valueFormat?: string): string;

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

@@ -1,7 +1,8 @@
-import type { ChartRuntimeStyle, ChartStyle } from '../../../types';
+import type { ChartRuntimeStyle, ChartStyle, ILabelStyle } from '../../../types';
 import { ChartTypeBits } from '../../../enum';
 export declare const MIN_CHART_RUNTIME_FONT_SIZE = 10;
 export declare const MIN_CHART_RUNTIME_LINE_WIDTH = 1;
+export declare function resolveChartFontFamily(style: Pick<ChartStyle, 'fontFamily' | 'eastAsiaFontFamily'>, label?: Partial<Pick<ILabelStyle, 'family' | 'eastAsiaFontFamily'>>): string;
 /**
  * Converts persisted semantic chart style buckets into transient render buckets.
  *

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

@@ -1,5 +1,6 @@
 import type { ChartStyle, IChartGaugeSpec } from '../../../types';
-import { AreaLineStyle, AxisAlignEnum, BarShape, ChartBorderDashType, ChartTypeBits, InvalidValueType, LabelContentType, LegendPositionEnum, LinePointShape, PieLabelPosition, RadarShape, SelectModeEnum, SeriesLabelPosition, TextAlign, TitlePositionEnum, WaterfallStackTypeEnum, WordCloudShapeEnum } from '../../../enum';
+import { AreaLineStyle, AxisAlignEnum, BarShape, ChartBorderDashType, ChartTypeBits, InvalidValueType, LabelContentType, LegendPositionEnum, LinePointShape, PieLabelPosition, RadarShape, ScatterLineType, SelectModeEnum, SeriesLabelPosition, TextAlign, TitlePositionEnum, WaterfallStackTypeEnum, WordCloudShapeEnum } from '../../../enum';
+export declare const DEFAULT_SCATTER_LINE_TYPE = ScatterLineType.None;
 export declare const MODERN_GAUGE_STYLE: {
     readonly mode: "modern";
     readonly scale: {

package/lib/types/types.d.ts

@@ -4,13 +4,13 @@ import type { Observable } from 'rxjs';
 import type { ChartColor, IChartLinearGradient } from './chart-builder/chart-color';
 import type { IChartPieCompositeSpec, PieCompositeMarkRole, PieCompositePlot } from './chart-builder/chart-types';
 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, SelectModeEnum, SeriesLabelPosition, TitlePositionEnum, TreemapParentLabelLayout, WaterfallSeriesTypeEnum, WaterfallStackTypeEnum, WordCloudShapeEnum } from './enum';
+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 { 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 ? T : T extends Record<string, any> ? T extends any[] ? T : {
+export type DeepPartial<T> = T extends IChartLinearGradient | IChartLabelPattern ? 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. */
@@ -53,6 +53,8 @@ export interface IUniverDataSet {
     sourceLabels?: string[][];
     /** Runtime indexes of hidden `source` fields; omission means every field is visible. */
     hiddenFieldIndexes?: number[];
+    /** Runtime item offsets hidden by the worksheet, indexed by physical source field. Not persisted. */
+    hiddenItemIndexes?: number[][];
     /**
      * Explicit category grouping topology. Absence enables adjacent path-prefix inference;
      * an empty array explicitly keeps repeated adjacent values as separate groups.
@@ -128,6 +130,7 @@ export interface IChartValueLabelSpec {
 }
 /** Persisted leaf-label style supported by Treemap charts. */
 export interface IChartTreemapLabelSpec extends IChartValueLabelSpec {
+    backgroundColor?: ILabelStyle['backgroundColor'];
     visible?: boolean;
     contentType?: LabelContentType;
     color?: string;
@@ -143,6 +146,7 @@ export interface IChartTreemapSpec {
 }
 /** Persisted semantic label style supported by Sunburst charts. */
 export interface IChartSunburstLabelSpec extends IChartValueLabelSpec {
+    backgroundColor?: ILabelStyle['backgroundColor'];
     visible?: boolean;
     contentType?: LabelContentType;
     position?: ChartSunburstLabelPosition;
@@ -378,11 +382,21 @@ export interface IChartSunburstData {
  * Consumers derive labels from the current dataset, so title updates do not require a context rebuild.
  */
 export interface IChartContext {
+    /** Plot only visible worksheet data. Absence preserves the historical true default. */
+    plotVisibleOnly?: boolean;
     categoryType?: CategoryType;
     /** Ordered selected Label field indexes. */
     categoryIndexes?: number[];
+    /** Ordered category fields per series value-field index; omitted series inherit the shared category. */
+    seriesToCategory?: Record<number, number[]>;
     /** Whether ordered category indexes should render as one root-to-leaf category axis. */
     multiLevelCategoryAxis?: boolean;
+    /** Runtime-only opt-in for category hierarchy hit targets and expand/collapse controls. */
+    categoryHierarchyInteraction?: boolean;
+    /** Runtime-only visibility of the global category hierarchy expand/collapse controls. */
+    categoryHierarchyControls?: boolean;
+    /** Runtime-only interactive field buttons supplied by a host integration. */
+    fieldButtons?: IChartFieldButton[];
     /**
      * the flag to indicate whether the chart use date axis, only all category data is date type, the chart will use date axis, if there are some string type data, the chart will use category axis even the flag is true.
      */
@@ -523,9 +537,12 @@ export interface IChartDataCategorySegment {
     endIndex: number;
 }
 export interface IChartDataSeries {
+    /** Stable identity derived from the source dimension when one is available. */
+    id?: string;
     index: number;
     name: string;
     items: IChartDataItem[];
+    category?: IChartDataCategory;
 }
 export interface IChartDataItem {
     value: OptionDataValue;
@@ -548,6 +565,12 @@ export interface IChartRuntimeContext {
     addWatermark?: boolean;
     /** Runtime-only extra inset reserved by host adapters around chart content. */
     layoutInset?: number;
+    /** Runtime-only opt-in for category hierarchy hit targets and expand/collapse controls. */
+    categoryHierarchyInteraction?: boolean;
+    /** Runtime-only visibility of the global category hierarchy expand/collapse controls. */
+    categoryHierarchyControls?: boolean;
+    /** Runtime-only interactive field buttons supplied by a host integration. */
+    fieldButtons?: IChartFieldButton[];
     /**
      * The function to transform the color to the render color with considering the system theme is dark mode or not.
      * @param {string} color - The color to be rendered.
@@ -562,14 +585,25 @@ export interface IChartRuntimeContext {
     localeTexts: IChartLocaleTexts;
     updateAdaptiveSizeFromDomRender?(chartWidth: number): void;
 }
+export interface IChartLabelPattern {
+    type: 'pattern';
+    /** OOXML ST_PresetPatternVal token. */
+    preset: string;
+    foregroundColor: string;
+    backgroundColor: string;
+}
 export interface ILabelStyle {
     visible: boolean;
     content: string;
     fontSize: number;
     color: string;
+    /** DrawingML label shape fill, independent of the text color. Absent keeps the host default. */
+    backgroundColor?: ChartColor | IChartLabelPattern;
     align: LabelAlignEnum;
     bold: boolean;
     family: string;
+    /** Explicit East Asian fallback, separate from the Latin font family. */
+    eastAsiaFontFamily?: string;
     strikethrough: boolean;
     italic: boolean;
     underline: boolean;
@@ -578,9 +612,11 @@ export interface ILabelStyle {
     showMaxLabel?: boolean;
     showMinLabel?: boolean;
     rotate?: number;
+    /** Fit category-axis labels by rotating before reducing their display frequency. */
+    autoRotate?: boolean;
 }
 export interface IChartTitleStyle extends Omit<ILabelStyle, 'visible'> {
-    /** PowerPoint manual title anchor, as chart-relative edge coordinates. */
+    /** Authored title anchor, as chart-relative edge coordinates. */
     manualLayout?: {
         left: number;
         top: number;
@@ -590,8 +626,22 @@ export interface ILegendStyle {
     position?: LegendPositionEnum;
     label?: Omit<ILabelStyle, 'visible' | 'align' | 'content'>;
     selectMode?: SelectModeEnum;
-    /** Allow a horizontal legend to flow onto multiple rows instead of using pagination. */
+    /** Allow a horizontal legend to wrap into column-aligned rows instead of using pagination. */
     wrap?: boolean;
+    /** Authored legend-key height and default width in CSS pixels; absent keeps native dimensions. */
+    keySize?: number;
+    /** Explicit key width for rectangular or line keys; absent keeps square authored keys. */
+    keyWidth?: number;
+    /** Combination legend-only series indexes; unlisted series retain their relative order after these entries. */
+    seriesOrder?: number[];
+    /** Authored legend metrics; omitted values retain the adaptive defaults. */
+    layout?: {
+        itemWidth?: number;
+        itemHeight?: number;
+        itemGap?: number;
+        /** Align multi-row horizontal entries in equally sized columns; single rows keep natural spacing. */
+        uniformColumns?: boolean;
+    };
 }
 export interface IGridLineStyle {
     visible: boolean;
@@ -600,6 +650,15 @@ export interface IGridLineStyle {
     dashType?: ChartBorderDashType;
 }
 export interface IAxisOptions {
+    /** Axis visibility (inverse of OOXML c:delete); authored gridlines and titles remain independent. */
+    visible?: boolean;
+    /**
+     * Where this axis crosses the perpendicular axis (OOXML crosses / crossesAt).
+     * Numbers use the crossed axis's value units, date serial days, or one-based categories (MS-OI29500).
+     */
+    crossing?: 'autoZero' | 'min' | 'max' | number;
+    /** OOXML tickLblPos; independent of axis-line visibility and crossing. */
+    tickLabelPosition?: 'nextTo' | 'low' | 'high' | 'none';
     lineVisible: boolean;
     label: Omit<ILabelStyle, 'align' | 'content'>;
     lineStyle: IGridLineStyle;
@@ -614,38 +673,67 @@ export interface IAxisOptions {
     reverse?: boolean;
     min?: number | null;
     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. */
+    autoScale?: 'office';
+    /** Calendar granularity of an imported date axis; absent retains elapsed-time behavior. */
+    baseTimeUnit?: 'days' | 'months' | 'years';
+    /** OOXML majorTimeUnit; distinct from the date axis's base granularity. */
+    majorTimeUnit?: 'days' | 'months' | 'years';
     format?: string;
 }
 export interface ISeriesLabelStyle extends ILabelStyle {
     contentType: number;
     position: SeriesLabelPosition;
     format?: string;
+    /** Numeric format overrides keyed by zero-based category index. */
+    pointFormats?: Record<number, string>;
     /** Per-category text imported from OOXML data-label ranges. */
     customValues?: Record<number, string>;
+    /** Allow a leader line when a point label has been moved from its default position. */
+    showLabelLine?: boolean;
+    labelLineStyle?: Partial<Pick<ISeriesStyle['border'], 'color' | 'width' | 'opacity'>>;
 }
 export interface IPieLabelStyle extends Omit<ILabelStyle, 'align' | 'content'> {
     contentType: number;
     position: PieLabelPosition;
     format?: string;
+    /** Numeric format overrides keyed by zero-based source category index. */
+    pointFormats?: Record<number, string>;
 }
 export interface IPointStyle {
+    /** Hide an unpainted imported marker without discarding its shape or size. */
+    visible?: boolean;
     shape: LinePointShape;
     size: number;
     color: Nullable<string>;
 }
 export interface IDataPointStyle extends Omit<IPointStyle, 'color'> {
+    /** Per-point stroke overrides; absent properties inherit the series border. */
+    border?: Partial<ISeriesStyle['border']>;
+    /** Per-point label overrides; omitted fields inherit the series or chart label. */
+    label?: Partial<ISeriesLabelStyle> & {
+        /** Displacement from the default label position, as chart width/height fractions. */
+        offset?: [number, number];
+    };
     color: Nullable<ChartColor>;
     /** Fill opacity for this data point, from 0 (transparent) to 1 (opaque). */
     fillOpacity?: number;
 }
 export interface ISeriesStyle {
-    chartType?: ChartTypeBits.Line | ChartTypeBits.Column | ChartTypeBits.ColumnStacked | ChartTypeBits.Area | ChartTypeBits.AreaStacked;
+    scatterLine?: ScatterLineType;
+    chartType?: ChartTypeBits.Line | ChartTypeBits.Scatter | ChartTypeBits.Bar | ChartTypeBits.BarStacked | ChartTypeBits.Column | ChartTypeBits.ColumnStacked | ChartTypeBits.Area | ChartTypeBits.AreaStacked;
     /** Compatibility switch for placing this series on the secondary vertical axis. It does not change the yAxis/rightYAxis option bucket semantics. */
     rightYAxis?: boolean;
+    /** Explicit line-series smoothing; overrides chart-level smoothing when present. */
+    smooth?: boolean;
     color: Nullable<ChartColor>;
     /** Fill opacity for this series, from 0 (transparent) to 1 (opaque). */
     fillOpacity: number;
     border: {
+        /** Hides the series stroke without discarding its authored width or color. */
+        visible?: boolean;
         opacity: number;
         color: Nullable<string>;
         width: number;
@@ -669,9 +757,11 @@ export interface ISeriesStyle {
     };
 }
 export type RightYAxisOptions = Omit<IAxisOptions, 'reverse'>;
-export interface IAllSeriesStyle extends Pick<ISeriesStyle, 'border' | 'label' | 'rightYAxis' | 'point' | 'color' | 'fillOpacity' | 'waterfall'> {
+export interface IAllSeriesStyle extends Pick<ISeriesStyle, 'border' | 'label' | 'rightYAxis' | 'point' | 'color' | 'fillOpacity' | 'waterfall' | 'scatterLine'> {
 }
 export interface ITrendLine {
+    /** Stable source identity. `seriesIndex` remains the fallback for legacy snapshots. */
+    seriesId?: string;
     seriesIndex: number;
     type: ChartTrendlineType;
     name: string;
@@ -748,6 +838,25 @@ export interface IChartPlotArea {
     width: number;
     height: number;
 }
+export interface IChartErrorBars {
+    /** Data-source field index of the owning value series, not its display order. */
+    seriesIndex: number;
+    direction: 'x' | 'y';
+    type: 'both' | 'plus' | 'minus';
+    valueType: 'fixedVal' | 'percentage' | 'stdDev' | 'stdErr' | 'cust';
+    value?: number;
+    noEndCap?: boolean;
+    /** Custom error amounts remain editable data-source fields. */
+    plusIndex?: number;
+    minusIndex?: number;
+    line?: {
+        color?: string;
+        width?: number;
+        opacity?: number;
+        visible?: boolean;
+        dashType?: ChartBorderDashType;
+    };
+}
 export interface IChartStyle {
     width: number;
     height: number;
@@ -761,18 +870,21 @@ export interface IChartStyle {
     fontSize: number;
     fontColor: string;
     fontFamily: string;
+    eastAsiaFontFamily?: string;
     borderColor: Nullable<string>;
     borderWidth: number;
     /** Omission keeps renderer-owned automatic layout. */
     plotArea?: IChartPlotArea;
+    /** Imported PowerPoint Cartesian edge/label spacing; the inner plot remains automatic. */
+    automaticLayout?: 'powerpoint';
     titles: {
         title: IChartTitleStyle;
         subtitle: IChartTitleStyle;
-        xAxisTitle: Omit<ILabelStyle, 'visible'>;
+        xAxisTitle: IChartTitleStyle;
         /** Primary vertical axis title. RTL may render it on the physical right, but it is still persisted here. */
-        yAxisTitle: Omit<ILabelStyle, 'visible'>;
+        yAxisTitle: IChartTitleStyle;
         /** Secondary vertical axis title. */
-        rightYAxisTitle: Omit<ILabelStyle, 'visible'>;
+        rightYAxisTitle: IChartTitleStyle;
         titlePosition: TitlePositionEnum;
     };
     legend: ILegendStyle;
@@ -788,6 +900,7 @@ export interface IChartStyle {
     bar: IBarStyle;
     bubble: IChartBubbleStyle;
     trendlines: ITrendLine[];
+    errorBars?: IChartErrorBars[];
     pie: {
         composite?: IChartPieCompositeSpec;
         /** Clockwise degrees from 12 o'clock, matching the authored chart semantic. */
@@ -803,6 +916,8 @@ export interface IChartStyle {
         isHalfPie: boolean;
         rosePie: boolean;
         showLabelLine: boolean;
+        /** Authored leader-line appearance; visibility remains owned by showLabelLine. */
+        labelLineStyle?: Partial<Pick<ISeriesStyle['border'], 'color' | 'width' | 'opacity'>>;
         valueScale: number;
         /** Persisted sparse slice overrides. Slice data remains owned by the chart data source. */
         sliceStyles: {
@@ -893,7 +1008,9 @@ export interface IChartSnapshot {
     dataAggregation?: IChartDataAggregation;
 }
 /** Persisted chart field selection accepted by the snapshot reader. */
-export interface IChartSnapshotContext extends Pick<IChartContext, 'categoryIndexes' | 'multiLevelCategoryAxis' | 'seriesIndexes' | 'useDateAxis' | 'histogram'> {
+export interface IChartSnapshotContext extends Pick<IChartContext, 'categoryIndexes' | 'seriesToCategory' | 'multiLevelCategoryAxis' | 'seriesIndexes' | 'useDateAxis' | 'histogram' | 'plotVisibleOnly'> {
+    /** Historical binding name accepted only at the context compatibility boundary. */
+    seriesCategoryIndexes?: Record<number, number[]>;
     /** Historical snapshot field decoded only when `categoryIndexes` is absent. */
     categoryIndex?: number;
 }
@@ -1052,7 +1169,14 @@ export interface IChartRenderRuntimeOptions {
     width?: number;
     height?: number;
 }
-export type ChartElementKind = 'blank' | 'chartArea' | 'title' | 'subtitle' | 'xAxisTitle' | 'yAxisTitle' | 'rightYAxisTitle' | 'xAxisLabel' | 'yAxisLabel' | 'rightYAxisLabel' | 'xAxisLine' | 'yAxisLine' | 'rightYAxisLine' | 'gridLine' | 'tick' | 'legend' | 'legendItem' | 'mark' | 'series' | 'dataPoint' | 'dataLabel';
+export type ChartElementKind = 'blank' | 'chartArea' | 'title' | 'subtitle' | 'xAxisTitle' | 'yAxisTitle' | 'rightYAxisTitle' | 'xAxisLabel' | 'yAxisLabel' | 'rightYAxisLabel' | 'xAxisLine' | 'yAxisLine' | 'rightYAxisLine' | 'gridLine' | 'tick' | 'legend' | 'legendItem' | 'mark' | 'series' | 'dataPoint' | 'dataLabel' | 'categoryHierarchyExpandControl' | 'categoryHierarchyCollapseControl' | 'fieldButton' | 'fieldButtonOverflow';
+export type ChartFieldButtonRole = 'filter' | 'series' | 'category';
+export interface IChartFieldButton {
+    fieldId: string;
+    label: string;
+    role: ChartFieldButtonRole;
+    filtered?: boolean;
+}
 export interface IChartElementBounds {
     left: number;
     top: number;
@@ -1079,6 +1203,11 @@ export interface IChartElementHit {
     seriesId?: string;
     seriesName?: string;
     dataIndex?: number;
+    categoryLevel?: number;
+    categoryStartIndex?: number;
+    categoryEndIndex?: number;
+    fieldId?: string;
+    fieldRole?: ChartFieldButtonRole;
     /** Stable runtime identity for an aggregated semantic mark. Renderer indexes are intentionally omitted. */
     semanticId?: string;
     semanticKind?: 'node' | 'link';
@@ -1126,6 +1255,8 @@ export type EChartSpec = EChartsOption;
 export type EChartSeriesItem = ExtractArrayItem<EChartSpec['series']> & {
     formattedData?: string[];
     rawData?: number[];
+    /** Source indexes after date-axis filtering and sorting, for point-level styles and labels. */
+    sourceDataIndices?: number[];
     seriesId: string;
 };
 export type EChartInstance = IChartInstance<EChartSpec>;