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

package/lib/types/chart-model-api/chart-model-api.d.ts

@@ -0,0 +1,2 @@
+import type { ChartModelApi } from './types';
+export declare const chartModelApi: ChartModelApi;

package/lib/types/chart-model-api/chart-type-manifest.d.ts

@@ -0,0 +1,128 @@
+import { ChartTypeBits } from '../enum';
+export declare enum ChartTypeCapabilityProfile {
+    Default = "default",
+    Advanced = "advanced",
+    AdvancedStyle = "advancedStyle",
+    Pareto = "pareto"
+}
+export declare enum ChartTypeDecoder {
+    Exact = "exact",
+    Pie = "pie",
+    Donut = "donut"
+}
+/**
+ * Exhaustive semantic chart-type identity declaration.
+ *
+ * Keep caller names, aliases, exact engine bits, readback discrimination, and
+ * capability profile selection together so lifecycle consumers cannot drift.
+ */
+export declare const SEMANTIC_CHART_TYPE_DECLARATIONS: readonly [{
+    readonly name: "line";
+    readonly bits: ChartTypeBits.Line;
+    readonly capabilityProfile: ChartTypeCapabilityProfile.Default;
+}, {
+    readonly name: "column";
+    readonly bits: ChartTypeBits.Column;
+    readonly capabilityProfile: ChartTypeCapabilityProfile.Default;
+}, {
+    readonly name: "columnStacked";
+    readonly bits: ChartTypeBits.ColumnStacked;
+    readonly capabilityProfile: ChartTypeCapabilityProfile.Default;
+}, {
+    readonly name: "columnPercentStacked";
+    readonly bits: ChartTypeBits.ColumnPercentStacked;
+    readonly capabilityProfile: ChartTypeCapabilityProfile.Default;
+}, {
+    readonly name: "bar";
+    readonly bits: ChartTypeBits.Bar;
+    readonly capabilityProfile: ChartTypeCapabilityProfile.Default;
+}, {
+    readonly name: "barStacked";
+    readonly bits: ChartTypeBits.BarStacked;
+    readonly capabilityProfile: ChartTypeCapabilityProfile.Default;
+}, {
+    readonly name: "barPercentStacked";
+    readonly bits: ChartTypeBits.BarPercentStacked;
+    readonly capabilityProfile: ChartTypeCapabilityProfile.Default;
+}, {
+    readonly name: "pie";
+    readonly bits: ChartTypeBits.Pie;
+    readonly decoder: ChartTypeDecoder.Pie;
+    readonly capabilityProfile: ChartTypeCapabilityProfile.Default;
+}, {
+    readonly name: "donut";
+    readonly bits: ChartTypeBits.Pie;
+    readonly aliases: readonly ["doughnut"];
+    readonly decoder: ChartTypeDecoder.Donut;
+    readonly capabilityProfile: ChartTypeCapabilityProfile.Default;
+    readonly initialStyle: "donut";
+}, {
+    readonly name: "area";
+    readonly bits: ChartTypeBits.Area;
+    readonly capabilityProfile: ChartTypeCapabilityProfile.Default;
+}, {
+    readonly name: "areaStacked";
+    readonly bits: ChartTypeBits.AreaStacked;
+    readonly capabilityProfile: ChartTypeCapabilityProfile.Default;
+}, {
+    readonly name: "areaPercentStacked";
+    readonly bits: ChartTypeBits.AreaPercentStacked;
+    readonly capabilityProfile: ChartTypeCapabilityProfile.Default;
+}, {
+    readonly name: "radar";
+    readonly bits: ChartTypeBits.Radar;
+    readonly capabilityProfile: ChartTypeCapabilityProfile.Default;
+}, {
+    readonly name: "scatter";
+    readonly bits: ChartTypeBits.Scatter;
+    readonly capabilityProfile: ChartTypeCapabilityProfile.Default;
+}, {
+    readonly name: "combination";
+    readonly bits: ChartTypeBits.Combination;
+    readonly aliases: readonly ["combo"];
+    readonly capabilityProfile: ChartTypeCapabilityProfile.Default;
+}, {
+    readonly name: "wordCloud";
+    readonly bits: ChartTypeBits.WordCloud;
+    readonly capabilityProfile: ChartTypeCapabilityProfile.Default;
+}, {
+    readonly name: "funnel";
+    readonly bits: ChartTypeBits.Funnel;
+    readonly capabilityProfile: ChartTypeCapabilityProfile.AdvancedStyle;
+}, {
+    readonly name: "bubble";
+    readonly bits: ChartTypeBits.Bubble;
+    readonly capabilityProfile: ChartTypeCapabilityProfile.Advanced;
+}, {
+    readonly name: "relation";
+    readonly bits: ChartTypeBits.Relation;
+    readonly capabilityProfile: ChartTypeCapabilityProfile.AdvancedStyle;
+}, {
+    readonly name: "waterfall";
+    readonly bits: ChartTypeBits.Waterfall;
+    readonly capabilityProfile: ChartTypeCapabilityProfile.AdvancedStyle;
+}, {
+    readonly name: "pareto";
+    readonly bits: ChartTypeBits.Pareto;
+    readonly capabilityProfile: ChartTypeCapabilityProfile.Pareto;
+}, {
+    readonly name: "sankey";
+    readonly bits: ChartTypeBits.Sankey;
+    readonly capabilityProfile: ChartTypeCapabilityProfile.Advanced;
+}, {
+    readonly name: "heatmap";
+    readonly bits: ChartTypeBits.Heatmap;
+    readonly capabilityProfile: ChartTypeCapabilityProfile.Advanced;
+}, {
+    readonly name: "boxplot";
+    readonly bits: ChartTypeBits.Boxplot;
+    readonly capabilityProfile: ChartTypeCapabilityProfile.Advanced;
+}];
+export type SemanticChartTypeDeclaration = typeof SEMANTIC_CHART_TYPE_DECLARATIONS[number];
+export type ChartCanonicalTypeName = SemanticChartTypeDeclaration['name'];
+type AliasOf<T> = T extends {
+    readonly aliases: readonly (infer TAlias extends string)[];
+} ? TAlias : never;
+export type ChartTypeAliasName = AliasOf<SemanticChartTypeDeclaration>;
+export type ChartKnownTypeName = ChartCanonicalTypeName | ChartTypeAliasName;
+export {};

package/lib/types/chart-model-api/chart-type-registry.d.ts

@@ -0,0 +1,56 @@
+import type { ChartStyle } from '../types';
+import type { ChartCanonicalTypeName } from './chart-type-manifest';
+import type { IChartModelTypeCapabilityRegistration } from './constants';
+import type { ChartModelDiagnostic } from './types';
+import { ChartTypeBits } from '../enum';
+import { ChartTypeDecoder } from './chart-type-manifest';
+type ChartTypeRegistryDeclaration = Readonly<{
+    readonly name: string;
+    readonly bits: ChartTypeBits;
+    readonly aliases?: readonly string[];
+    readonly capabilities: IChartModelTypeCapabilityRegistration;
+    readonly initialStyle?: ChartStyle;
+    readonly decoder?: ChartTypeDecoder;
+}>;
+export type ChartTypeResolutionSuccess = Readonly<{
+    readonly ok: true;
+    readonly name: ChartCanonicalTypeName;
+    readonly bits: ChartTypeBits;
+    readonly capabilities: IChartModelTypeCapabilityRegistration;
+    readonly initialStyle?: ChartStyle;
+}>;
+export type ChartTypeResolutionFailure = Readonly<{
+    readonly ok: false;
+    readonly diagnostic: ChartModelDiagnostic;
+}>;
+export type ChartTypeResolution = ChartTypeResolutionSuccess | ChartTypeResolutionFailure;
+export type ChartTypeIdentification = Readonly<{
+    readonly name: ChartCanonicalTypeName | typeof UNSUPPORTED_CHART_TYPE_NAME;
+    readonly capabilities?: IChartModelTypeCapabilityRegistration;
+    readonly rawType?: number;
+}>;
+export type ChartTypeCapabilityCatalog = Readonly<{
+    readonly chartTypes: readonly ChartCanonicalTypeName[];
+    readonly allowedValues: readonly string[];
+    readonly aliases: Readonly<Record<string, ChartCanonicalTypeName>>;
+    readonly capabilities: Readonly<Record<ChartCanonicalTypeName, IChartModelTypeCapabilityRegistration>>;
+}>;
+export type SemanticChartTypeRegistry = Readonly<{
+    resolve(input: unknown, path?: string): ChartTypeResolution;
+    identify(raw: {
+        bits: ChartTypeBits;
+        style?: ChartStyle;
+    }): ChartTypeIdentification;
+    catalog(): ChartTypeCapabilityCatalog;
+}>;
+export declare const UNSUPPORTED_CHART_TYPE_NAME = "unsupported";
+export declare const chartTypeRegistry: Readonly<{
+    resolve(input: unknown, path?: string): ChartTypeResolution;
+    identify(raw: {
+        bits: ChartTypeBits;
+        style?: ChartStyle;
+    }): ChartTypeIdentification;
+    catalog(): ChartTypeCapabilityCatalog;
+}>;
+export declare function createChartTypeRegistry(declarations: readonly ChartTypeRegistryDeclaration[]): SemanticChartTypeRegistry;
+export {};

package/lib/types/chart-model-api/chart-type.d.ts

@@ -0,0 +1,7 @@
+import type { ChartTypeBits } from '../enum';
+import type { ChartStyle } from '../types';
+import type { ChartKnownTypeName, ChartModelDiagnostic, ChartTypeName } from './types';
+export declare function chartTypeNameToBits(type: unknown, diagnostics: ChartModelDiagnostic[], path?: string): ChartTypeBits | null;
+export declare function chartTypeBitsToName(type: ChartTypeBits, style?: ChartStyle): ChartTypeName;
+export declare function normalizeChartTypeName(type: ChartKnownTypeName): ChartKnownTypeName;
+export declare function buildDonutStyle(type: ChartKnownTypeName | undefined): ChartStyle | undefined;

package/lib/types/chart-model-api/constants.d.ts

@@ -0,0 +1,99 @@
+import type { ChartLegendSpec, ChartSeriesPatch, ChartTitleSpec } from './types';
+import { ChartTypeBits, LabelAlignEnum, LegendPositionEnum, SelectModeEnum, SeriesLabelPosition, TitlePositionEnum } from '../enum';
+export declare enum ChartModelChangedGroup {
+    Type = "type",
+    Style = "style",
+    Data = "data"
+}
+export declare enum ChartModelDiagnosticCode {
+    SeriesNotFound = "SERIES_NOT_FOUND",
+    AmbiguousSeriesSelector = "AMBIGUOUS_SERIES_SELECTOR",
+    UnknownChartType = "UNKNOWN_CHART_TYPE",
+    UnsupportedChartType = "UNSUPPORTED_CHART_TYPE",
+    InvalidColor = "INVALID_COLOR",
+    InvalidRange = "INVALID_RANGE",
+    InvalidSize = "INVALID_SIZE",
+    UnknownOption = "UNKNOWN_OPTION"
+}
+export declare enum ChartModelPatchGroup {
+    Type = "type",
+    Mapping = "mapping",
+    Aggregation = "aggregation",
+    Title = "title",
+    Legend = "legend",
+    Axes = "axes",
+    Series = "series",
+    Pie = "pie",
+    Radar = "radar",
+    Pareto = "pareto",
+    WordCloud = "wordCloud",
+    Appearance = "appearance",
+    AdvancedStyle = "advancedStyle",
+    Theme = "theme"
+}
+export declare enum ChartModelPatchSemantic {
+    NoChange = "noChange",
+    ClearWhereSupported = "clearWhereSupported",
+    SemanticMerge = "semanticMerge",
+    ReplaceUnlessSelectorMerge = "replaceUnlessSelectorMerge",
+    ValidationError = "validationError"
+}
+export declare const CHART_MODEL_API_CAPABILITIES_VERSION = "2026-07-10.v2";
+export declare const CHART_MODEL_DEFAULT_DONUT_HOLE = 0.5;
+export declare const CHART_MODEL_UNSUPPORTED_TYPE_SUGGESTION = "Use one of the supported chart types from chartModelApi.getCapabilities().";
+export declare const CHART_MODEL_PATCH_SEMANTICS: Readonly<{
+    omitted: ChartModelPatchSemantic.NoChange;
+    undefined: ChartModelPatchSemantic.NoChange;
+    null: ChartModelPatchSemantic.ClearWhereSupported;
+    object: ChartModelPatchSemantic.SemanticMerge;
+    array: ChartModelPatchSemantic.ReplaceUnlessSelectorMerge;
+    unknownField: ChartModelPatchSemantic.ValidationError;
+}>;
+export declare const CHART_MODEL_CREATE_SPEC_KEYS: Set<ChartModelPatchGroup>;
+export declare const CHART_MODEL_UPDATE_PATCH_KEYS: Set<ChartModelPatchGroup>;
+export declare const CHART_MODEL_WORD_CLOUD_KEYS: Set<string>;
+export declare const CHART_MODEL_APPEARANCE_KEYS: Set<string>;
+export declare const CHART_MODEL_APPEARANCE_BACKGROUND_KEYS: Set<string>;
+export declare const CHART_MODEL_APPEARANCE_BORDER_KEYS: Set<string>;
+export declare const CHART_MODEL_APPEARANCE_FONT_KEYS: Set<string>;
+export declare const CHART_MODEL_MAPPING_KEYS: Set<string>;
+export declare const CHART_MODEL_MAPPING_SCATTER_KEYS: Set<string>;
+export declare const CHART_MODEL_MAPPING_BUBBLE_KEYS: Set<string>;
+export declare const CHART_MODEL_AGGREGATION_KEYS: Set<string>;
+export declare const CHART_MODEL_PIE_KEYS: Set<string>;
+export declare const CHART_MODEL_PIE_LABEL_KEYS: Set<string>;
+export declare const CHART_MODEL_RADAR_KEYS: Set<string>;
+export declare const CHART_MODEL_PARETO_KEYS: Set<string>;
+export declare const CHART_MODEL_ADVANCED_STYLE_KEYS: Set<string>;
+export declare const CHART_MODEL_TITLE_KEYS: Set<string>;
+export declare const CHART_MODEL_LEGEND_KEYS: Set<string>;
+export declare const CHART_MODEL_AXES_KEYS: Set<string>;
+export declare const CHART_MODEL_AXIS_KEYS: Set<string>;
+export declare const CHART_MODEL_RIGHT_AXIS_KEYS: Set<string>;
+export declare const CHART_MODEL_AXIS_LINE_KEYS: Set<string>;
+export declare const CHART_MODEL_AXIS_TICK_KEYS: Set<string>;
+export declare const CHART_MODEL_AXIS_TITLE_STYLE_KEYS: Set<string>;
+export declare const CHART_MODEL_AXIS_LABEL_KEYS: Set<string>;
+export declare const CHART_MODEL_AXIS_GRID_LINE_KEYS: Set<string>;
+export declare const CHART_MODEL_SERIES_PATCH_KEYS: Set<string>;
+export declare const CHART_MODEL_SERIES_SELECTOR_KEYS: Set<string>;
+export declare const CHART_MODEL_SERIES_BORDER_KEYS: Set<string>;
+export declare const CHART_MODEL_SERIES_POINT_KEYS: Set<string>;
+export declare const CHART_MODEL_SERIES_LABEL_KEYS: Set<string>;
+export declare const CHART_MODEL_SERIES_DATA_POINT_KEYS: Set<string>;
+export declare const CHART_MODEL_DEFAULT_CREATE_GROUPS: readonly ChartModelPatchGroup[];
+export declare const CHART_MODEL_DEFAULT_UPDATE_GROUPS: readonly ChartModelPatchGroup[];
+export declare const CHART_MODEL_DEFAULT_STYLE_GROUPS: readonly ChartModelPatchGroup[];
+export declare const CHART_MODEL_COMMON_SAFE_UPDATE_GROUPS: readonly ChartModelPatchGroup[];
+export interface IChartModelTypeCapabilityRegistration {
+    createGroups: readonly ChartModelPatchGroup[];
+    updateGroups: readonly ChartModelPatchGroup[];
+    styleGroups: readonly ChartModelPatchGroup[];
+}
+export declare const CHART_MODEL_SERIES_TYPE_TO_BITS: Record<NonNullable<ChartSeriesPatch['type']>, ChartTypeBits>;
+export declare const CHART_MODEL_TITLE_POSITION: Record<NonNullable<Exclude<ChartTitleSpec, string>['position']>, TitlePositionEnum>;
+export declare const CHART_MODEL_LEGEND_POSITION: Record<NonNullable<Exclude<ChartLegendSpec, boolean>['position']>, LegendPositionEnum>;
+export declare const CHART_MODEL_LEGEND_SELECT_MODE: Record<NonNullable<Exclude<ChartLegendSpec, boolean>['selectMode']>, SelectModeEnum>;
+export declare const CHART_MODEL_TITLE_ALIGN: Record<NonNullable<Exclude<ChartTitleSpec, string>['alignment']>, LabelAlignEnum>;
+export declare const CHART_MODEL_SERIES_LABEL_POSITION: Record<NonNullable<NonNullable<ChartSeriesPatch['label']>['position']>, SeriesLabelPosition>;
+export declare const CHART_MODEL_CSS_COLOR_RE: RegExp;

package/lib/types/chart-model-api/describe.d.ts

@@ -0,0 +1,3 @@
+import type { ChartModel } from '../models/chart-model';
+import type { ChartModelDescription } from './types';
+export declare function describeChartModel(chartModel: ChartModel): ChartModelDescription;

package/lib/types/chart-model-api/index.d.ts

@@ -0,0 +1,8 @@
+export { chartModelApi, } from './chart-model-api';
+export { buildDonutStyle, chartTypeBitsToName, chartTypeNameToBits, } from './chart-type';
+export { UNSUPPORTED_CHART_TYPE_NAME } from './chart-type-registry';
+export { CHART_MODEL_API_CAPABILITIES_VERSION, CHART_MODEL_DEFAULT_DONUT_HOLE, CHART_MODEL_PATCH_SEMANTICS, CHART_MODEL_UNSUPPORTED_TYPE_SUGGESTION, ChartModelChangedGroup, ChartModelDiagnosticCode, ChartModelPatchGroup, ChartModelPatchSemantic, } from './constants';
+export { buildChartModelConfigPatch, buildCreateChartModelConfigPatch } from './patch-builder';
+export type { ChartAdvancedStylePatch, ChartAggregationSpec, ChartAppearanceSpec, ChartAxesSpec, ChartAxisSpec, ChartKnownTypeName, ChartLegendSpec, ChartMappingSpec, ChartModelApi, ChartModelCapabilities, ChartModelConfigPatch, ChartModelCreateSpec, ChartModelDescription, ChartModelDiagnostic, ChartModelInstanceCapabilities, ChartModelPatch, ChartModelPatchSemantics, ChartModelUpdateResult, ChartParetoSpec, ChartPieSpec, ChartRadarSpec, ChartSeriesDescription, ChartSeriesPatch, ChartSeriesSelector, ChartTitleSpec, ChartTypeName, ChartValidationResult, ChartWordCloudDescription, ChartWordCloudSpec, DeepPartial, DeepReadonly, } from './types';
+export { createChartModelDiagnostic, hasChartModelDiagnosticError, } from './utils';
+export { validateChartModelCreateSpec, validateChartModelPatch, } from './validate';

package/lib/types/chart-model-api/patch-builder.d.ts

@@ -0,0 +1,9 @@
+import type { IChartContext, IChartDataSeries } from '../types';
+import type { ChartModelConfigPatch, ChartModelCreateSpec, ChartModelDiagnostic, ChartModelPatch } from './types';
+/**
+ * Create-time adapter helper. It converts a model-only create spec into the same
+ * config patch shape used by update(), appending diagnostics into the provided
+ * array so the sheet/slide adapter can combine model and host validation.
+ */
+export declare function buildCreateChartModelConfigPatch(spec: ChartModelCreateSpec, diagnostics: ChartModelDiagnostic[], series?: IChartDataSeries[], currentContext?: IChartContext): ChartModelConfigPatch;
+export declare function buildChartModelConfigPatch(patch: ChartModelCreateSpec | ChartModelPatch, diagnostics: ChartModelDiagnostic[], series?: IChartDataSeries[], currentContext?: IChartContext): ChartModelConfigPatch;

package/lib/types/chart-model-api/series-selector.d.ts

@@ -0,0 +1,3 @@
+import type { IChartDataSeries } from '../types';
+import type { ChartModelDiagnostic, ChartSeriesPatch } from './types';
+export declare function resolveSeriesSelector(patch: ChartSeriesPatch, diagnostics: ChartModelDiagnostic[], path: string, series?: IChartDataSeries[]): number | null;