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

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

@@ -0,0 +1,393 @@
+import type { ChartBorderDashType, ChartStyle, IChartDataCategory, IChartDataSeries, IEchartTheme, LabelContentType, LinePointShape, RadarShape, WordCloudShapeEnum } 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 type ChartRangeSpec = string | IRange;
+export type ChartSourceSpec = ChartRangeSpec | {
+    range: ChartRangeSpec;
+    sheetName?: string;
+    sheetId?: string;
+    unitId?: string;
+    orientation?: ChartSourceOrientation;
+};
+export type ChartAnchorSpec = string | {
+    row: number;
+    column: number;
+    rowOffset?: number;
+    columnOffset?: number;
+};
+export interface IChartSizeSpec {
+    width?: number;
+    height?: number;
+}
+export type ChartSizeSpec = IChartSizeSpec;
+export interface IChartLayoutPatch {
+    anchor?: ChartAnchorSpec;
+    position?: {
+        x: number;
+        y: number;
+    };
+    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;
+    source: ChartSourceSpec;
+    anchor?: ChartAnchorSpec;
+    position?: {
+        x: number;
+        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;
+    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 interface IChartDiagnostic {
+    code: ChartDiagnosticCode;
+    severity: 'error' | 'warning';
+    message: string;
+    path?: string;
+    details?: unknown;
+    allowedValues?: readonly unknown[];
+    suggestion?: string;
+}
+export type ChartDiagnostic = IChartDiagnostic;
+export interface IChartValidationResult<TNormalized = unknown> {
+    ok: boolean;
+    diagnostics: ChartDiagnostic[];
+    normalized?: DeepReadonly<TNormalized>;
+}
+export type ChartValidationResult<TNormalized = unknown> = IChartValidationResult<TNormalized>;
+export interface IChartUpdateResult {
+    ok: boolean;
+    chart: FChart | null;
+    diagnostics: ChartDiagnostic[];
+    changed: Array<'source' | 'type' | 'style' | 'data' | 'layout'>;
+}
+export type ChartUpdateResult = IChartUpdateResult;
+export interface IChartSuggestion {
+    type: ChartKnownTypeName;
+    orientation: 'rows' | 'columns';
+    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 type ChartCapabilities = IChartCapabilities;
+export interface IChartInstanceCapabilities extends IChartCapabilities {
+    chartId: string;
+    type: ChartTypeName;
+    rawType?: number;
+    unsupportedGroups: readonly string[];
+}
+export type ChartInstanceCapabilities = IChartInstanceCapabilities;
+export interface IChartSourceDescription {
+    range: IRange;
+    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 type ChartSeriesDescription = IChartSeriesDescription;
+export interface IChartLayoutDescription {
+    position?: {
+        x: number;
+        y: number;
+    };
+    size?: ChartSizeSpec;
+    anchor?: {
+        row: number;
+        column: number;
+        rowOffset?: number;
+        columnOffset?: number;
+    };
+}
+export type ChartLayoutDescription = IChartLayoutDescription;
+export interface IChartDescription {
+    id: string;
+    type: ChartTypeName;
+    rawType?: number;
+    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,7 +1,9 @@
 import type { 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 { FChartBuilderBase } from './chart-builder/chart-builder-base';
+import { ChartUpdateBuilder } from './chart-facade-builders';
 /**
  * The facade class for the chart.
  * @hideconstructor
@@ -129,4 +131,13 @@ export declare class FChart {
      * @returns {FChartBuilderBase} The new FChartBuilderBase instance.
      */
     modify(): FChartBuilderBase;
+    describe(): ChartDescription | null;
+    getCapabilities(): ChartInstanceCapabilities | null;
+    validateUpdate(patch: ChartUpdatePatch): ChartValidationResult<ChartUpdatePatch>;
+    newUpdateBuilder(): ChartUpdateBuilder;
+    update(patch: ChartUpdatePatch): Promise<ChartUpdateResult>;
+    setSource(source: ChartSourceSpec): Promise<ChartUpdateResult>;
+    setType(type: ChartKnownTypeName): Promise<ChartUpdateResult>;
+    setLayout(layout: ChartLayoutPatch): Promise<ChartUpdateResult>;
+    remove(): Promise<boolean>;
 }

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

@@ -0,0 +1,28 @@
+import type { ChartCapabilities, ChartCreateSpec, ChartSourceSpec, ChartSuggestion, ChartUpdatePatch, ChartUpdateResult, ChartValidationResult } from './chart-facade-types';
+import { FWorksheet } from '@univerjs/sheets/facade';
+import { ChartCreateBuilder } from './chart-facade-builders';
+import { FChart } from './f-chart';
+export declare class FWorksheetCharts {
+    private readonly _worksheet;
+    constructor(_worksheet: FWorksheet);
+    create(spec: ChartCreateSpec): Promise<FChart>;
+    update(chart: FChart | string, patch: ChartUpdatePatch): Promise<ChartUpdateResult>;
+    remove(chart: FChart | string): Promise<boolean>;
+    list(): FChart[];
+    get(chartId: string): FChart | null;
+    validateCreate(spec: ChartCreateSpec): ChartValidationResult<ChartCreateSpec>;
+    getCapabilities(): ChartCapabilities;
+    newBuilder(): ChartCreateBuilder;
+    suggest(source: ChartSourceSpec): ChartSuggestion[];
+    private _sourceContext;
+}
+export interface IFWorksheetChartsMixin {
+    readonly charts: FWorksheetCharts;
+}
+export declare class FWorksheetChartsMixin extends FWorksheet implements IFWorksheetChartsMixin {
+    get charts(): FWorksheetCharts;
+}
+declare module '@univerjs/sheets/facade' {
+    interface FWorksheet extends IFWorksheetChartsMixin {
+    }
+}

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

@@ -1,14 +1,19 @@
 import type { ILineChartBuilderMixin, IPieChartBuilderInfo, IPieChartBuilderMixin, IRadarChartBuilderMixin } from './chart-builder/types';
 import './f-worksheet';
+import './f-worksheet-charts';
 import './f-enum';
 export { FChartBuilderBase } from './chart-builder/chart-builder-base';
 export type * from './chart-builder/chart-builder-base';
 export { LineChartBuilder } from './chart-builder/line-chart-builder';
 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 type * from './chart-facade-types';
 export { FChart } from './f-chart';
 export type * from './f-chart';
 export type * from './f-worksheet';
+export { FWorksheetCharts } from './f-worksheet-charts';
 /**
  * @ignore
  */

package/lib/types/index.d.ts

@@ -12,7 +12,7 @@ export type { IChartUpdateConfigMutationParams } from './commands/mutations/shee
 export { InsertSheetsChartMutation, RemoveSheetsChartMutation } 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 { SHEETS_CHART_PLUGIN_CONFIG_KEY } from './config/config';
+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';

package/lib/types/services/sheets-chart.service.d.ts

@@ -34,6 +34,8 @@ export declare class SheetsChartService extends Disposable {
         orient: DataOrientation;
         chartType: ChartTypeBits;
     };
+    private _normalizeInitialRangeInfo;
+    private _hasNonNumberCellInSingleRow;
     ensureChartModelCollection(unitId: string, subUnitId: string): Set<string>;
     getChartDataSource(id: string): ISheetChartDataSource | undefined;
     setChartDataSource(id: string, dataSource: ISheetChartDataSource): void;