@univerjs-pro/sheets-chart 1.0.0-alpha.2 → 1.0.0-alpha.3

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

@@ -1,23 +1,64 @@
-import type { ChartBorderDashType, ChartStyle, IChartDataCategory, IChartDataSeries, IEchartTheme, LabelContentType, LinePointShape, RadarShape, WordCloudShapeEnum } from '@univerjs-pro/engine-chart';
+import type { ChartKnownTypeName, ChartModelCapabilities, ChartModelChangedGroup, ChartModelCreateSpec, ChartModelDescription, ChartModelPatch, ChartModelPatchGroup, ChartTypeName, DeepReadonly, FChartDescription, FChartUpdateResult, IChartRenderModelImageExportOptions, IChartRenderModelImageExportResult, IEchartTheme } from '@univerjs-pro/engine-chart';
 import type { IRange } from '@univerjs/core';
 import type { FChart } from './f-chart';
-export type DeepReadonly<T> = T extends (...args: any[]) => unknown ? T : T extends readonly (infer U)[] ? readonly DeepReadonly<U>[] : T extends object ? {
-    readonly [K in keyof T]: DeepReadonly<T[K]>;
-} : T;
-export type DeepPartial<T> = T extends (...args: any[]) => unknown ? T : T extends readonly (infer U)[] ? DeepPartial<U>[] : T extends object ? {
-    [K in keyof T]?: DeepPartial<T[K]>;
-} : T;
-export type ChartKnownTypeName = 'line' | 'column' | 'bar' | 'pie' | 'donut' | 'doughnut' | 'area' | 'radar' | 'scatter' | 'combo' | 'combination' | 'wordCloud';
-export type ChartTypeName = ChartKnownTypeName | 'unsupported';
-export type ChartSourceOrientation = 'auto' | 'row' | 'column' | 'rows' | 'columns' | 'rowsAsSeries' | 'columnsAsSeries';
+export declare const ChartSourceOrientation: {
+    readonly Auto: "auto";
+    readonly Row: "row";
+    readonly Column: "column";
+    readonly Rows: "rows";
+    readonly Columns: "columns";
+    readonly RowsAsSeries: "rowsAsSeries";
+    readonly ColumnsAsSeries: "columnsAsSeries";
+};
+export type ChartSourceOrientation = typeof ChartSourceOrientation[keyof typeof ChartSourceOrientation];
+export declare enum ChartSourceKind {
+    Range = "range",
+    Ranges = "ranges"
+}
 export type ChartRangeSpec = string | IRange;
-export type ChartSourceSpec = ChartRangeSpec | {
+export interface IChartSourceVectorSpec {
+    /** One row or one column of values. All vectors are aligned by position. */
     range: ChartRangeSpec;
+    /** Optional single-cell display name. It never consumes a value from `range`. */
+    header?: ChartRangeSpec;
+}
+export type ChartSourceVectorSpec = IChartSourceVectorSpec;
+interface IChartSourceLocationSpec {
     sheetName?: string;
     sheetId?: string;
     unitId?: string;
     orientation?: ChartSourceOrientation;
-};
+}
+/**
+ * Chart data from either one rectangular table or explicit positional vectors.
+ * Exactly one of `range` and `ranges` may be provided.
+ *
+ * @example Single rectangular table
+ * ```ts
+ * { sheetName: 'Sales', range: 'A1:C7', orientation: 'columns' }
+ * ```
+ *
+ * @example Equal-length positional vectors with optional single-cell headers
+ * ```ts
+ * {
+ *   sheetName: 'Sales',
+ *   orientation: 'columns',
+ *   ranges: [
+ *     { header: 'A1', range: 'A2:A7' },
+ *     { header: 'C1', range: 'C2:C7' },
+ *   ],
+ * }
+ * ```
+ * Vector array order defines mapping indexes. Vectors must have equal lengths
+ * and a common row-or-column orientation; no join or padding is performed.
+ */
+export type ChartSourceSpec = ChartRangeSpec | (IChartSourceLocationSpec & {
+    range: ChartRangeSpec;
+    ranges?: never;
+}) | (IChartSourceLocationSpec & {
+    range?: never;
+    ranges: readonly ChartSourceVectorSpec[];
+});
 export type ChartAnchorSpec = string | {
     row: number;
     column: number;
@@ -38,197 +79,7 @@ export interface IChartLayoutPatch {
     size?: ChartSizeSpec;
 }
 export type ChartLayoutPatch = IChartLayoutPatch;
-export type ChartTitleSpec = string | {
-    text?: string;
-    visible?: boolean;
-    position?: 'top' | 'bottom' | 'left' | 'right';
-    alignment?: 'left' | 'center' | 'right';
-    fontSize?: number;
-    color?: string;
-    bold?: boolean;
-};
-export type ChartLegendSpec = boolean | {
-    visible?: boolean;
-    position?: 'top' | 'bottom' | 'left' | 'right';
-    selectMode?: 'single' | 'multiple' | 'close';
-    fontSize?: number;
-    color?: string;
-    bold?: boolean;
-    italic?: boolean;
-};
-export interface IChartAxisSpec {
-    title?: string;
-    min?: number | null;
-    max?: number | null;
-    reverse?: boolean;
-    line?: {
-        visible?: boolean;
-        color?: string;
-        width?: number;
-    };
-    tick?: {
-        visible?: boolean;
-        color?: string;
-        width?: number;
-        length?: number;
-        position?: 'inside' | 'outside';
-    };
-    format?: string | null;
-    titleStyle?: {
-        color?: string;
-        fontSize?: number;
-        bold?: boolean;
-        italic?: boolean;
-        family?: string;
-    };
-    label?: {
-        visible?: boolean;
-        color?: string;
-        fontSize?: number;
-        rotate?: number;
-    };
-    gridLine?: {
-        visible?: boolean;
-        color?: string;
-        width?: number;
-    };
-}
-export type ChartAxisSpec = IChartAxisSpec;
-export interface IChartAxesSpec {
-    x?: ChartAxisSpec;
-    y?: ChartAxisSpec;
-    rightY?: Omit<ChartAxisSpec, 'reverse'>;
-}
-export type ChartAxesSpec = IChartAxesSpec;
-export type ChartSeriesSelector = {
-    index: number;
-} | {
-    name: string;
-};
-export interface IChartSeriesPatch {
-    selector: ChartSeriesSelector;
-    name?: string;
-    type?: 'column' | 'line' | 'area';
-    color?: string;
-    fillOpacity?: number;
-    border?: {
-        color?: string | null;
-        width?: number;
-        opacity?: number;
-        dashType?: ChartBorderDashType;
-    };
-    point?: {
-        shape?: LinePointShape;
-        size?: number;
-        color?: string | null;
-    };
-    rightAxis?: boolean;
-    label?: {
-        visible?: boolean;
-        position?: 'top' | 'bottom' | 'inside' | 'outside';
-        contentType?: LabelContentType;
-        color?: string;
-        fontSize?: number;
-        bold?: boolean;
-        italic?: boolean;
-    };
-    dataPoints?: Record<number, {
-        shape?: LinePointShape;
-        size?: number;
-        color?: string | null;
-        fillOpacity?: number;
-    }>;
-}
-export type ChartSeriesPatch = IChartSeriesPatch;
-export interface IChartWordCloudSpec {
-    shape?: WordCloudShapeEnum;
-    /**
-     * Stable wordcloud mask resource id/key known to the runtime.
-     *
-     * The public facade intentionally does not recommend arbitrary URL/data URL
-     * input in v1. Legacy URL/data URL values may still appear through rawStyle
-     * for expert/debug compatibility, but normal callers should use registered
-     * mask resource ids.
-     *
-     * Patch semantics:
-     * - omitted/undefined: keep the current mask image setting.
-     * - null: clear the persisted mask image and fall back to shape.
-     * - string: set the mask image id; the mask image takes precedence over shape.
-     */
-    maskImageId?: string | null;
-    repeat?: boolean;
-}
-export type ChartWordCloudSpec = IChartWordCloudSpec;
-export interface IChartWordCloudDescription {
-    shape?: WordCloudShapeEnum;
-    maskImageId?: string;
-    repeat?: boolean;
-    effectiveShapeSource: 'shape' | 'maskImage';
-}
-export type ChartWordCloudDescription = IChartWordCloudDescription;
-export interface IChartAppearanceSpec {
-    background?: {
-        color?: string | null;
-        gradient?: boolean;
-    };
-    border?: {
-        color?: string | null;
-        width?: number;
-    };
-    font?: {
-        color?: string;
-        size?: number;
-        family?: string;
-    };
-}
-export type ChartAppearanceSpec = IChartAppearanceSpec;
-export interface IChartMappingSpec {
-    categoryIndex?: number | null;
-    seriesIndexes?: number[] | null;
-    useDateAxis?: boolean | null;
-    bubble?: {
-        sizeSeriesIndex?: number | null;
-        xAxisIndex?: number | null;
-        yAxisIndex?: number | null;
-        labelIndex?: number | null;
-        seriesIndex?: number | null;
-    };
-}
-export type ChartMappingSpec = IChartMappingSpec;
-export interface IChartAggregationSpec {
-    aggregate?: boolean;
-    topN?: number | null;
-}
-export type ChartAggregationSpec = IChartAggregationSpec;
-export interface IChartPieSpec {
-    doughnutHole?: number | null;
-    borderColor?: string;
-    hasPaddingAngle?: boolean;
-    isHalfPie?: boolean;
-    rosePie?: boolean;
-    showLabelLine?: boolean;
-    valueScale?: number;
-    valueSuffix?: string;
-    digitalFixed?: number;
-    label?: {
-        visible?: boolean;
-        position?: 'inside' | 'outside';
-        contentType?: LabelContentType;
-        color?: string;
-        fontSize?: number;
-        bold?: boolean;
-        italic?: boolean;
-    };
-}
-export type ChartPieSpec = IChartPieSpec;
-export interface IChartRadarSpec {
-    shape?: RadarShape;
-    fill?: boolean;
-}
-export type ChartRadarSpec = IChartRadarSpec;
-export type ChartAdvancedStylePatch = DeepPartial<Pick<ChartStyle, 'tooltip' | 'area' | 'funnel' | 'relation' | 'waterfall'>>;
-export interface IChartCreateSpec {
-    type: ChartKnownTypeName;
+export interface IChartCreateSpec extends ChartModelCreateSpec {
     source: ChartSourceSpec;
     anchor?: ChartAnchorSpec;
     position?: {
@@ -236,39 +87,40 @@ export interface IChartCreateSpec {
         y: number;
     };
     size?: ChartSizeSpec;
-    title?: ChartTitleSpec;
-    legend?: ChartLegendSpec;
-    axes?: ChartAxesSpec;
-    series?: ChartSeriesPatch[];
-    wordCloud?: ChartWordCloudSpec;
-    appearance?: ChartAppearanceSpec;
-    mapping?: ChartMappingSpec;
-    aggregation?: ChartAggregationSpec;
-    pie?: ChartPieSpec;
-    radar?: ChartRadarSpec;
-    advancedStyle?: ChartAdvancedStylePatch;
-    theme?: string;
 }
 export type ChartCreateSpec = IChartCreateSpec;
-export interface IChartUpdatePatch {
-    type?: ChartKnownTypeName;
+export interface IChartUpdatePatch extends ChartModelPatch {
     source?: ChartSourceSpec;
-    title?: ChartTitleSpec;
-    legend?: ChartLegendSpec;
-    axes?: ChartAxesSpec;
-    series?: ChartSeriesPatch[];
-    wordCloud?: ChartWordCloudSpec;
-    appearance?: ChartAppearanceSpec;
-    mapping?: ChartMappingSpec;
-    aggregation?: ChartAggregationSpec;
-    pie?: ChartPieSpec;
-    radar?: ChartRadarSpec;
-    advancedStyle?: ChartAdvancedStylePatch;
-    theme?: string;
     layout?: ChartLayoutPatch;
 }
 export type ChartUpdatePatch = IChartUpdatePatch;
-export type ChartDiagnosticCode = 'CHART_NOT_FOUND' | 'SERIES_NOT_FOUND' | 'AMBIGUOUS_SERIES_SELECTOR' | 'INVALID_RANGE' | 'SINGLE_CELL_SOURCE' | 'NO_NUMERIC_SERIES' | 'UNKNOWN_CHART_TYPE' | 'UNSUPPORTED_CHART_TYPE' | 'INVALID_SIZE' | 'INVALID_COLOR' | 'COMMAND_FAILED' | 'UNKNOWN_OPTION';
+export declare const ChartDiagnosticCode: {
+    readonly ChartNotFound: "CHART_NOT_FOUND";
+    readonly SeriesNotFound: "SERIES_NOT_FOUND";
+    readonly AmbiguousSeriesSelector: "AMBIGUOUS_SERIES_SELECTOR";
+    readonly InvalidRange: "INVALID_RANGE";
+    readonly SingleCellSource: "SINGLE_CELL_SOURCE";
+    readonly NoNumericSeries: "NO_NUMERIC_SERIES";
+    readonly NoPositiveParetoValues: "NO_POSITIVE_PARETO_VALUES";
+    readonly UnknownChartType: "UNKNOWN_CHART_TYPE";
+    readonly UnsupportedChartType: "UNSUPPORTED_CHART_TYPE";
+    readonly InvalidSize: "INVALID_SIZE";
+    readonly InvalidColor: "INVALID_COLOR";
+    readonly CommandFailed: "COMMAND_FAILED";
+    readonly UnknownOption: "UNKNOWN_OPTION";
+};
+export type ChartDiagnosticCode = typeof ChartDiagnosticCode[keyof typeof ChartDiagnosticCode];
+export declare enum ChartFacadeHostGroup {
+    Source = "source",
+    Layout = "layout"
+}
+export declare enum ChartFacadeCreateLayoutKey {
+    Anchor = "anchor",
+    Position = "position",
+    Size = "size"
+}
+export type ChartFacadeCapabilityGroup = ChartModelPatchGroup | ChartFacadeHostGroup;
+export type ChartChangedGroup = ChartModelChangedGroup | ChartFacadeHostGroup;
 export interface IChartDiagnostic {
     code: ChartDiagnosticCode;
     severity: 'error' | 'warning';
@@ -285,11 +137,11 @@ export interface IChartValidationResult<TNormalized = unknown> {
     normalized?: DeepReadonly<TNormalized>;
 }
 export type ChartValidationResult<TNormalized = unknown> = IChartValidationResult<TNormalized>;
-export interface IChartUpdateResult {
+export interface IChartUpdateResult extends FChartUpdateResult<FChart, ChartChangedGroup, ChartDiagnostic> {
     ok: boolean;
     chart: FChart | null;
     diagnostics: ChartDiagnostic[];
-    changed: Array<'source' | 'type' | 'style' | 'data' | 'layout'>;
+    changed: ChartChangedGroup[];
 }
 export type ChartUpdateResult = IChartUpdateResult;
 export interface IChartSuggestion {
@@ -298,62 +150,38 @@ export interface IChartSuggestion {
     reason?: string;
 }
 export type ChartSuggestion = IChartSuggestion;
-export interface IChartCapabilities {
-    version: string;
-    chartTypes: readonly ChartKnownTypeName[];
-    patchSemantics: {
-        omitted: 'noChange';
-        undefined: 'noChange';
-        null: 'clearWhereSupported';
-        object: 'semanticMerge';
-        array: 'replaceUnlessSelectorMerge';
-        unknownField: 'validationError';
-    };
-    createGroups: readonly string[];
-    updateGroups: readonly string[];
-    styleGroups: readonly string[];
-    advancedStyle: {
-        supported: boolean;
-    };
+export interface IChartCapabilities extends Omit<ChartModelCapabilities, 'createGroups' | 'updateGroups'> {
+    createGroups: readonly ChartFacadeCapabilityGroup[];
+    updateGroups: readonly ChartFacadeCapabilityGroup[];
 }
 export type ChartCapabilities = IChartCapabilities;
 export interface IChartInstanceCapabilities extends IChartCapabilities {
     chartId: string;
     type: ChartTypeName;
     rawType?: number;
-    unsupportedGroups: readonly string[];
+    unsupportedGroups: readonly ChartFacadeCapabilityGroup[];
 }
 export type ChartInstanceCapabilities = IChartInstanceCapabilities;
-export interface IChartSourceDescription {
+export type ChartExportImageOptions = IChartRenderModelImageExportOptions;
+export type ChartExportImageResult = IChartRenderModelImageExportResult;
+export interface IChartRangeSourceDescription {
     range: IRange;
+    ranges?: never;
     sheetName?: string;
     sheetId: string;
     unitId: string;
     orientation: ChartSourceOrientation;
 }
-export type ChartSourceDescription = IChartSourceDescription;
-export interface IChartSeriesDescription {
-    index: number;
-    name: string;
-    type?: 'column' | 'line' | 'area';
-    color?: string | null;
-    fillOpacity?: number;
-    border?: ChartSeriesPatch['border'];
-    point?: ChartSeriesPatch['point'];
-    rightAxis?: boolean;
-    label?: {
-        visible?: boolean;
-        position?: 'top' | 'bottom' | 'inside' | 'outside';
-        contentType?: LabelContentType;
-        color?: string;
-        fontSize?: number;
-        bold?: boolean;
-        italic?: boolean;
-    };
-    dataPoints?: ChartSeriesPatch['dataPoints'];
-    data?: DeepReadonly<IChartDataSeries>;
+export interface IChartSourceVectorDescription {
+    range: IChartRangeSourceDescription;
+    header?: IChartRangeSourceDescription;
+}
+export interface IChartMultiRangeSourceDescription {
+    range?: never;
+    ranges: IChartSourceVectorDescription[];
+    orientation: 'rows' | 'columns';
 }
-export type ChartSeriesDescription = IChartSeriesDescription;
+export type ChartSourceDescription = IChartRangeSourceDescription | IChartMultiRangeSourceDescription;
 export interface IChartLayoutDescription {
     position?: {
         x: number;
@@ -368,26 +196,17 @@ export interface IChartLayoutDescription {
     };
 }
 export type ChartLayoutDescription = IChartLayoutDescription;
-export interface IChartDescription {
-    id: string;
-    type: ChartTypeName;
-    rawType?: number;
+export interface IChartDescription extends Omit<ChartModelDescription, 'diagnostics'>, FChartDescription<{
+    unitId: string;
+    subUnitId: string;
+    chartId: string;
+}, {
+    kind: ChartSourceKind;
+    source: ChartSourceDescription | null;
+}> {
     diagnostics?: ChartDiagnostic[];
     source: ChartSourceDescription | null;
-    title?: ChartTitleSpec;
-    legend?: ChartLegendSpec;
-    axes?: ChartAxesSpec;
-    wordCloud?: ChartWordCloudDescription;
-    appearance?: ChartAppearanceSpec;
-    mapping?: ChartMappingSpec;
-    aggregation?: ChartAggregationSpec;
-    pie?: ChartPieSpec;
-    radar?: ChartRadarSpec;
-    series: ChartSeriesDescription[];
-    category?: DeepReadonly<IChartDataCategory>;
-    theme?: string;
     layout?: ChartLayoutDescription;
-    rawStyle?: DeepReadonly<ChartStyle>;
 }
 export type ChartDescription = IChartDescription;
 export type { IEchartTheme };

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

@@ -1,14 +1,15 @@
-import type { IChartDataCategory, IChartDataSeries } from '@univerjs-pro/engine-chart';
+import type { ChartKnownTypeName, IChartDataCategory, IChartDataSeries } from '@univerjs-pro/engine-chart';
 import type { ISheetChartSourceSingleRange } from '@univerjs-pro/sheets-chart';
 import type { Injector } from '@univerjs/core';
-import type { ChartDescription, ChartInstanceCapabilities, ChartKnownTypeName, ChartLayoutPatch, ChartSourceSpec, ChartUpdatePatch, ChartUpdateResult, ChartValidationResult } from './chart-facade-types';
+import type { ChartDescription, ChartExportImageOptions, ChartExportImageResult, ChartInstanceCapabilities, ChartLayoutPatch, ChartSourceSpec, ChartUpdatePatch, ChartUpdateResult, ChartValidationResult } from './chart-facade-types';
+import { FBaseChart } from '@univerjs-pro/engine-chart';
 import { FChartBuilderBase } from './chart-builder/chart-builder-base';
 import { ChartUpdateBuilder } from './chart-facade-builders';
 /**
  * The facade class for the chart.
  * @hideconstructor
  */
-export declare class FChart {
+export declare class FChart extends FBaseChart<ChartDescription, ChartUpdateResult> {
     /**
      * @ignore
      */
@@ -37,6 +38,7 @@ export declare class FChart {
      * ```
      */
     getChartId(): string;
+    getId(): string;
     /**
      * Get the range of the chart.
      * @returns {ISheetChartSourceSingleRange|undefined} The range of the chart.
@@ -129,12 +131,33 @@ export declare class FChart {
     /**
      * Returns a new FChartBuilderBase instance that modifies this chart.
      * @returns {FChartBuilderBase} The new FChartBuilderBase instance.
+     * @see {@link update} for structured semantic patches and diagnostics.
      */
     modify(): FChartBuilderBase;
+    /**
+     * Returns a frozen semantic snapshot of this chart, or null if it no longer exists.
+     * `rawStyle` is read-only debug information and is not accepted as update input.
+     */
     describe(): ChartDescription | null;
+    /** Returns verified patch groups for this chart's concrete type. */
     getCapabilities(): ChartInstanceCapabilities | null;
+    /**
+     * Renders this chart through the shared engine-chart image export Seam.
+     * Returns data URL metadata, or null when the chart/drawing input is unavailable.
+     * The promise rejects when no render model is registered or rendering fails.
+     */
+    exportImage(options?: ChartExportImageOptions): Promise<ChartExportImageResult | null>;
+    /** Validates and normalizes a semantic patch without executing commands. */
     validateUpdate(patch: ChartUpdatePatch): ChartValidationResult<ChartUpdatePatch>;
+    /** Returns a convenience adapter that builds the same JSON patch accepted by `update()`. */
     newUpdateBuilder(): ChartUpdateBuilder;
+    /**
+     * Applies a semantic merge patch.
+     *
+     * Omitted/undefined fields are unchanged; null clears fields that explicitly
+     * support clearing. The result contains diagnostics and changed groups rather
+     * than throwing for validation or command failures.
+     */
     update(patch: ChartUpdatePatch): Promise<ChartUpdateResult>;
     setSource(source: ChartSourceSpec): Promise<ChartUpdateResult>;
     setType(type: ChartKnownTypeName): Promise<ChartUpdateResult>;

package/lib/types/facade/f-worksheet-charts.d.ts

@@ -1,25 +1,90 @@
 import type { ChartCapabilities, ChartCreateSpec, ChartSourceSpec, ChartSuggestion, ChartUpdatePatch, ChartUpdateResult, ChartValidationResult } from './chart-facade-types';
+import { FBaseCharts } from '@univerjs-pro/engine-chart';
 import { FWorksheet } from '@univerjs/sheets/facade';
 import { ChartCreateBuilder } from './chart-facade-builders';
 import { FChart } from './f-chart';
-export declare class FWorksheetCharts {
+/**
+ * Structured chart authoring for a worksheet.
+ *
+ * JSON create/update specs are the canonical Interface. Builders returned by
+ * `newBuilder()` compile to the same specs and are optional convenience adapters.
+ */
+export declare class FWorksheetCharts extends FBaseCharts<FChart, ChartCreateSpec, ChartCapabilities> {
     private readonly _worksheet;
     constructor(_worksheet: FWorksheet);
+    /**
+     * Creates a chart from a serializable semantic spec.
+     *
+     * Call `validateCreate()` for a side-effect-free preflight. Validation or
+     * command failure throws `ChartFacadeError`, whose `diagnostics` explain the
+     * rejected fields.
+     */
     create(spec: ChartCreateSpec): Promise<FChart>;
+    /** Applies a semantic merge patch and returns diagnostics plus changed groups. */
     update(chart: FChart | string, patch: ChartUpdatePatch): Promise<ChartUpdateResult>;
     remove(chart: FChart | string): Promise<boolean>;
+    /** Returns chart handles owned by this worksheet. */
     list(): FChart[];
+    /** Returns the worksheet chart with `chartId`, or null when it is absent. */
     get(chartId: string): FChart | null;
+    /** Validates and normalizes a create spec without executing commands. */
     validateCreate(spec: ChartCreateSpec): ChartValidationResult<ChartCreateSpec>;
+    /** Describes runtime chart types, patch semantics, and available groups. */
     getCapabilities(): ChartCapabilities;
+    /** Returns a convenience adapter that builds the same JSON spec accepted by `create()`. */
     newBuilder(): ChartCreateBuilder;
     suggest(source: ChartSourceSpec): ChartSuggestion[];
     private _sourceContext;
 }
 export interface IFWorksheetChartsMixin {
+    /**
+     * Structured chart authoring, inspection, repair, and image export.
+     *
+     * @example
+     * ```ts
+     * const worksheet = univerAPI.getActiveWorkbook()?.getActiveSheet();
+     * if (!worksheet) return;
+     *
+     * const chart = await worksheet.charts.create({
+     *   type: 'pareto',
+     *   source: 'A1:B8',
+     *   pareto: {
+     *     barColor: '#1677ff',
+     *     cumulativeLineColor: '#f5222d',
+     *   },
+     * });
+     * const before = chart.describe();
+     * const result = await chart.update({
+     *   pareto: { cumulativeLineColor: '#722ed1' },
+     * });
+     * if (!result.ok) console.log(result.diagnostics);
+     * const after = chart.describe();
+     * const image = await chart.exportImage({ pixelRatio: 2 });
+     * console.log({ before, after, image });
+     * ```
+     */
     readonly charts: FWorksheetCharts;
 }
 export declare class FWorksheetChartsMixin extends FWorksheet implements IFWorksheetChartsMixin {
+    /**
+     * Structured chart authoring, inspection, repair, capabilities, and image export.
+     * Prefer serializable create/update specs; use `describe()` before repairing an
+     * existing chart and inspect update diagnostics before reading it back.
+     *
+     * @example
+     * ```ts
+     * const chart = await worksheet.charts.create({
+     *   type: 'pareto',
+     *   source: 'A1:B8',
+     *   pareto: { barColor: '#1677ff', cumulativeLineColor: '#f5222d' },
+     * });
+     * const before = chart.describe();
+     * const result = await chart.update({ pareto: { barColor: '#722ed1' } });
+     * if (!result.ok) console.log(result.diagnostics);
+     * const after = chart.describe();
+     * const image = await chart.exportImage({ pixelRatio: 2 });
+     * ```
+     */
     get charts(): FWorksheetCharts;
 }
 declare module '@univerjs/sheets/facade' {

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

@@ -27,6 +27,7 @@ export interface IFWorksheetChartMixin {
      *   .build();
      * await fWorksheet.insertChart(chartInfo);
      * ```
+     * @see {@link FWorksheetCharts.create} for structured specs and validation diagnostics.
      */
     insertChart(chartBuildInfo: IChartBuilderInfo): Promise<FChart>;
     /**
@@ -60,6 +61,7 @@ export interface IFWorksheetChartMixin {
      *   fWorksheet.updateChart(newChartInfo);
      * }, 3000);
      * ```
+     * @see {@link FChart.update} for semantic merge patches and structured diagnostics.
      */
     updateChart(chartBuildInfo: IChartBuilderInfo): void;
     /**
@@ -86,6 +88,7 @@ export interface IFWorksheetChartMixin {
      *   .build();
      * await fWorksheet.insertChart(chartInfo);
      * ```
+     * @see {@link FWorksheetCharts} for the canonical structured chart Interface.
      */
     newChart(fChart?: FChart): FChartBuilderBase;
     /**

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

@@ -9,6 +9,7 @@ export { PieChartBuilder } from './chart-builder/pie-chart-builder';
 export { RadarChartBuilder } from './chart-builder/radar-chart-builder';
 export { ChartFacadeError } from './chart-facade-adapter';
 export { ChartCreateBuilder, ChartUpdateBuilder } from './chart-facade-builders';
+export { ChartSourceKind, ChartSourceOrientation } from './chart-facade-types';
 export type * from './chart-facade-types';
 export { FChart } from './f-chart';
 export type * from './f-chart';

package/lib/types/index.d.ts

@@ -1,4 +1,3 @@
-export { ChartDataSourceMulti, ChartDataSourceSingle, createChartDataSource, getCategoryData, } from './chart-source/chart-source';
 export { ChartUpdateConfigCommand } from './commands/commands/sheets-chart-update-config.command';
 export type { IChartUpdateConfigCommandParams } from './commands/commands/sheets-chart-update-config.command';
 export { ChartUpdateSourceCommand } from './commands/commands/sheets-chart-update-source.command';
@@ -9,13 +8,13 @@ export { ChartUpdateSourceConfigMutation } from './commands/mutations/sheet-char
 export type { IChartUpdateSourceConfigMutationParams } from './commands/mutations/sheet-chart-update-source.mutation';
 export { ChartUpdateConfigMutation } from './commands/mutations/sheets-chart-update-config.mutation';
 export type { IChartUpdateConfigMutationParams } from './commands/mutations/sheets-chart-update-config.mutation';
-export { InsertSheetsChartMutation, RemoveSheetsChartMutation } from './commands/mutations/sheets-chart.mutation';
+export { InsertSheetsChartMutation, RemoveSheetsChartMutation, toInsertChartMutationSource, } from './commands/mutations/sheets-chart.mutation';
 export type { IInsertSheetsChartMutationParams, IRemoveSheetsChartMutationParams, } from './commands/mutations/sheets-chart.mutation';
-export { calcPosition, getAllowedChartTypes, setGraphicToSpec, setProperty, translateAngleToRadian, } from './common/util';
-export { ChartRenderMode, SHEETS_CHART_PLUGIN_CONFIG_KEY } from './config/config';
+export { getAllowedChartTypes, setProperty, } from './common/util';
+export { ChartRenderMode, SHEETS_CHART_PLUGIN_CONFIG_KEY, } from './config/config';
 export type { IUniverSheetsChartConfig } from './config/config';
 export { SheetChartModel } from './models/chart-model';
-export type { IChartSourceMultiRangeItem, IChartSourceRangeItem, ISheetChartSourceSingleRange } from './models/types';
-export { SHEETS_CHART_PLUGIN_NAME, UniverSheetsChartPlugin } from './plugin';
+export type { IChartSourceMultiRangeItem, IChartSourceRangeItem, ISheetChartSourceSingleRange, } from './models/types';
+export { SHEETS_CHART_PLUGIN_NAME, UniverSheetsChartPlugin, } from './plugin';
 export { ChartModelService } from './services/chart-model.service';
 export { SheetsChartService } from './services/sheets-chart.service';