@univerjs-pro/engine-chart 1.0.3 → 1.1.0

package/lib/types/chart-3d/core/types.d.ts

@@ -0,0 +1,74 @@
+import type { ChartRuntimeStyle, IChart3DView, IChartConfig, IChartSnapshot } from '../../types';
+export type ProjectionReadonly<T> = T extends (...args: never[]) => unknown ? T : T extends object ? {
+    readonly [K in keyof T]: ProjectionReadonly<T[K]>;
+} : T;
+/** One render borrows read-only product data/style; the host rebuilds input after every model update. */
+export interface IProjectionChartInput<TSnapshot extends IChartSnapshot = IChartSnapshot> {
+    readonly scene: IProjectionSceneOptions;
+    readonly snapshot: ProjectionReadonly<TSnapshot>;
+    readonly config: ProjectionReadonly<IChartConfig>;
+    readonly style: ProjectionReadonly<ChartRuntimeStyle>;
+    readonly width: number;
+    readonly height: number;
+}
+export interface IProjectionSemanticTarget {
+    readonly chartId: string;
+    readonly seriesId?: string;
+    readonly seriesIndex: number;
+    readonly dataIndex: number;
+}
+export interface IProjectionPoint {
+    readonly x: number;
+    readonly y: number;
+}
+export type ProjectionDecoration = 'floor' | 'plot:boundary' | `${'axis' | 'tick' | 'grid'}:${'category' | 'value' | 'depth'}`;
+export interface IProjectionPrimitive {
+    readonly decoration?: ProjectionDecoration;
+    readonly kind: 'polygon' | 'polyline' | 'text';
+    readonly points: readonly IProjectionPoint[];
+    readonly fill?: string;
+    /** Multiply the host-resolved base color by this normal/light factor. */
+    readonly shade?: number;
+    readonly stroke?: string;
+    readonly strokeWidth?: number;
+    readonly text?: string;
+    readonly target?: IProjectionSemanticTarget;
+}
+export interface IProjectionDiagnostic {
+    readonly code: 'unsupported-chart-combination' | 'invalid-view-parameter' | 'invalid-size' | 'model-type-mismatch' | 'projection-calibration-unverified';
+    readonly field: string;
+}
+export interface IProjectionFrame {
+    /** Painter order, back to front. Targets carry source identity, never generated face IDs. */
+    readonly primitives: readonly IProjectionPrimitive[];
+    readonly diagnostics: readonly IProjectionDiagnostic[];
+}
+/** Adapter-owned dates projected onto the category domain without reordering source indices. */
+export interface IProjectionCategoryAxisLayout {
+    readonly positions: readonly (number | undefined)[];
+    readonly bandWidth: number;
+    readonly ticks: readonly {
+        readonly position: number;
+        readonly value: number;
+        readonly label: string;
+    }[];
+}
+/** Active scene controls only; inactive authored values remain in the snapshot. */
+export interface IProjectionSceneOptions {
+    readonly dimension: 2 | 3;
+    readonly view?: ProjectionReadonly<IChart3DView>;
+    readonly seriesLayout?: 'clustered' | 'depth';
+    readonly categoryAxis?: IProjectionCategoryAxisLayout;
+    readonly gapWidth?: number;
+    readonly gapDepth?: number;
+    readonly reverse: {
+        readonly category: boolean;
+        readonly value: boolean;
+        readonly depth: boolean;
+    };
+    readonly pie: {
+        readonly rotation?: number;
+        readonly explosion?: number;
+        readonly sliceExplosions: Readonly<Record<number, number>>;
+    };
+}

package/lib/types/chart-3d/index.d.ts

@@ -0,0 +1 @@
+export { Chart3DExtension } from './chart-3d-extension';

package/lib/types/chart-3d/view-defaults.d.ts

@@ -0,0 +1,3 @@
+import type { IChart3DStyle } from '../types';
+import { ChartTypeBits } from '../enum';
+export declare function getThreeDRightAngleAxes(chartType: ChartTypeBits, threeD?: IChart3DStyle | null): boolean;

package/lib/types/chart-3d/webgl/draw-data.d.ts

@@ -0,0 +1,6 @@
+import type { IFace3, ISurfaceEdge } from '../core/geometry';
+import type { IWebGLDrawInput, IWebGLDrawItem } from './types';
+/** Shader RGB stays straight; blending creates the premultiplied drawing buffer expected by the browser. */
+export declare function createFragmentColor(color: string, opacity: number, shade: number): [number, number, number, number];
+export declare function isSurfaceEdgeVisible(edge: ISurfaceEdge, frontFaces: ReadonlySet<IFace3>, translucentFaces?: ReadonlySet<IFace3>): boolean;
+export declare function buildDrawData(input: IWebGLDrawInput): IWebGLDrawItem[];

package/lib/types/chart-3d/webgl/draw-queue.d.ts

@@ -0,0 +1,10 @@
+import type { IWebGLDrawItem } from './types';
+/** Embedded color alpha participates in classification; equal depths preserve input order. */
+export declare function createDrawQueue(items: readonly IWebGLDrawItem[]): IWebGLDrawItem[];
+export interface IWebGLDrawPacket {
+    readonly item: IWebGLDrawItem;
+    /** Homogeneous clip coordinates, four components per vertex. */
+    readonly vertices: Float32Array;
+}
+/** Split crossing transparent polygons before painter traversal; opaque geometry still uses GPU depth. */
+export declare function orderTransparentDraws(packets: readonly IWebGLDrawPacket[]): IWebGLDrawPacket[];

package/lib/types/chart-3d/webgl/gradient.d.ts

@@ -0,0 +1,3 @@
+import type { IWebGLDrawItem, IWebGLGradient } from './types';
+export declare function createGradientRamp(gradient: IWebGLGradient): Uint8Array;
+export declare function isTransparentDraw(item: IWebGLDrawItem): boolean;

package/lib/types/chart-3d/webgl/line-segments.d.ts

@@ -0,0 +1,8 @@
+import type { IVector3 } from '../core/geometry';
+export interface IProjectedLinePoint {
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+}
+/** Dash lengths are CSS pixels. Interpolate world positions with homogeneous depth, not screen t. */
+export declare function splitDashedLine(start: IVector3, end: IVector3, a: IProjectedLinePoint, b: IProjectedLinePoint, pattern?: readonly number[]): IVector3[][];

package/lib/types/chart-3d/webgl/program.d.ts

@@ -0,0 +1,16 @@
+import { Disposable } from '@univerjs/core';
+export declare class WebGLDrawProgram extends Disposable {
+    private readonly _gl;
+    readonly program: WebGLProgram;
+    readonly camera: WebGLUniformLocation | null;
+    readonly clipSpace: WebGLUniformLocation | null;
+    readonly color: WebGLUniformLocation | null;
+    readonly position: number;
+    readonly hasGradient: WebGLUniformLocation | null;
+    readonly gradientRamp: WebGLUniformLocation | null;
+    readonly gradientVector: WebGLUniformLocation | null;
+    readonly viewport: WebGLUniformLocation | null;
+    private _closed;
+    constructor(_gl: WebGLRenderingContext);
+    dispose(): void;
+}

package/lib/types/chart-3d/webgl/renderer.d.ts

@@ -0,0 +1,19 @@
+import type { IWebGLDrawItem } from './types';
+import { Disposable } from '@univerjs/core';
+/** Owns GPU resources on a dedicated canvas; DOM ownership stays with the caller. */
+export declare class WebGLRenderer extends Disposable {
+    readonly canvas: HTMLCanvasElement;
+    private readonly _gl;
+    private _program;
+    private _buffer;
+    private readonly _textures;
+    private _closed;
+    private _frame?;
+    private readonly _onContextLost;
+    private readonly _onContextRestored;
+    constructor(canvas: HTMLCanvasElement);
+    getLineWidth(width: number): number;
+    clear(): void;
+    render(items: readonly IWebGLDrawItem[], matrix: Float32Array, ratio: number): void;
+    dispose(): void;
+}

package/lib/types/chart-3d/webgl/stroke.d.ts

@@ -0,0 +1,13 @@
+import type { IVector3 } from '../core/geometry';
+import type { IWebGLDrawItem } from './types';
+interface IStrokeNeighbors {
+    start?: IVector3;
+    end?: IVector3;
+    startBranches?: readonly IVector3[];
+    endBranches?: readonly IVector3[];
+}
+/** Connect only boundaries of the same semantic mark and appearance. */
+export declare function findStrokeNeighbors(items: readonly IWebGLDrawItem[]): Map<IWebGLDrawItem, IStrokeNeighbors>;
+/** Expand a segment after depth clipping; offset scales with w to preserve pixel width under perspective. */
+export declare function buildStrokeVertices(vertices: readonly IVector3[], matrix: Float32Array, width: number, viewportWidth: number, viewportHeight: number, neighbors?: IStrokeNeighbors, supportingFaces?: readonly (readonly IVector3[])[]): Float32Array;
+export {};

package/lib/types/chart-3d/webgl/types.d.ts

@@ -0,0 +1,71 @@
+import type { IFace3, ISurfaceEdge, IVector3 } from '../core/geometry';
+import type { IProjectionSemanticTarget } from '../core/types';
+export interface IWebGLGradient {
+    readonly start: {
+        x: number;
+        y: number;
+    };
+    readonly end: {
+        x: number;
+        y: number;
+    };
+    readonly stops: readonly {
+        offset: number;
+        color: [number, number, number, number];
+    }[];
+}
+export interface IWebGLAppearance {
+    /** Optional adapter-calibrated diffuse factor; independent of opacity and projection. */
+    readonly shade?: number;
+    /** Mark-local normalized endpoints; draw-data converts them to CSS pixels. */
+    readonly gradient?: IWebGLGradient;
+    readonly gradientGroup?: string;
+    readonly color?: string;
+    readonly opacity: number;
+    readonly border?: {
+        readonly surfaceShading?: boolean;
+        readonly silhouetteOnly?: boolean;
+        readonly color?: string;
+        readonly width?: number;
+        readonly opacity?: number;
+        readonly dashPattern?: readonly number[];
+    };
+}
+export interface IWebGLSurface {
+    readonly face: IFace3;
+    readonly cameraVertices: readonly IVector3[];
+    readonly appearance: IWebGLAppearance;
+}
+export interface IWebGLDrawInput {
+    readonly surfaces: readonly IWebGLSurface[];
+    readonly edges: readonly ISurfaceEdge[];
+    readonly lines: readonly {
+        start: IVector3;
+        end: IVector3;
+        color: string;
+        width: number;
+        dashPattern?: readonly number[];
+    }[];
+    readonly perspective: boolean;
+    readonly light: IVector3;
+    readonly ambientLight: number;
+    readonly diffuseLight: number;
+    readonly foreground: string;
+    readonly project: (point: IVector3) => {
+        x: number;
+        y: number;
+        w: number;
+    } | undefined;
+    readonly toCamera: (point: IVector3) => IVector3;
+}
+export interface IWebGLDrawItem {
+    readonly target?: IProjectionSemanticTarget;
+    readonly vertices: readonly IVector3[];
+    readonly color: [number, number, number, number];
+    readonly gradient?: IWebGLGradient;
+    /** Adjacent visible faces used to keep expanded borders on the surface. */
+    readonly supportingFaces?: readonly (readonly IVector3[])[];
+    readonly kind: 'face' | 'line';
+    readonly width: number;
+    readonly depth: number;
+}

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

@@ -1,9 +1,20 @@
 import type { IChartTopNSpec } from '../chart-data-aggregation';
 import type { AreaLineStyle, AxisAlignEnum, BarShape, ChartAxisDimension, ChartBorderDashType, ChartMarkLineLabelPosition, ChartSemanticAxis, ChartTrendlineType, ChartWaterfallPointRole, InvalidValueType, IRuntimeAxisPosition, LabelAlignEnum, LabelContentType, LegendPositionEnum, LinePointShape, PieLabelPosition, RadarShape, RelationChartLayoutEnum, ScatterLineType, SelectModeEnum, SeriesLabelPosition, TitlePositionEnum, WaterfallStackTypeEnum, WordCloudShapeEnum } from '../enum';
-import type { DeepNullish, IChartCandlestickMappingSpec, IChartCandlestickSpec, IChartChordMappingSpec, IChartChordSpec, IChartGaugeSpec, IChartHistogramSpec, IChartSunburstSpec, IChartTreemapSpec, IChartValueLabelSpec } from '../types';
+import type { DeepNullish, IAxisOptions, IChart3DStyle, IChartCandlestickMappingSpec, IChartCandlestickSpec, IChartChordMappingSpec, IChartChordSpec, IChartGaugeSpec, IChartHistogramSpec, IChartSeriesFillPattern, IChartSunburstSpec, IChartTreemapSpec, IChartValueLabelSpec } from '../types';
 import type { ChartColor } from './chart-color';
 /** Canonical semantic chart type names exposed by the chart facade. */
 export declare enum ChartTypeString {
+    Line3D = "line3D",
+    Column3D = "column3D",
+    ColumnStacked3D = "columnStacked3D",
+    ColumnPercentStacked3D = "columnPercentStacked3D",
+    Bar3D = "bar3D",
+    BarStacked3D = "barStacked3D",
+    BarPercentStacked3D = "barPercentStacked3D",
+    Pie3D = "pie3D",
+    Area3D = "area3D",
+    AreaStacked3D = "areaStacked3D",
+    AreaPercentStacked3D = "areaPercentStacked3D",
     Line = "line",
     Column = "column",
     ColumnStacked = "columnStacked",
@@ -99,6 +110,8 @@ export interface IChartAxisLabelSpec extends IChartFontSpec {
     rotate?: number;
 }
 export interface IChartAxisSpec {
+    scaleType?: IAxisOptions['scaleType'];
+    logBase?: IAxisOptions['logBase'];
     title?: string;
     titleAlignment?: AxisAlignEnum;
     min?: number;
@@ -126,6 +139,9 @@ export interface IChartAxisSpec {
         dashType?: ChartBorderDashType;
     };
 }
+/** Series-depth axis does not carry a numeric scale. */
+export interface IChartDepthAxisSpec extends Omit<IChartAxisSpec, 'scaleType' | 'logBase' | 'min' | 'max' | 'format'> {
+}
 export interface IChartAxesSpec {
     x?: IChartAxisSpec;
     y?: IChartAxisSpec;
@@ -200,6 +216,7 @@ export interface IChartSeriesStyleSpec {
     scatterLine?: ScatterLineType;
     color?: ChartColor;
     fillOpacity?: number;
+    fillPattern?: IChartSeriesFillPattern | null;
     border?: IChartSeriesBorderSpec;
     point?: IChartSeriesPointSpec;
     rightAxis?: boolean;
@@ -212,6 +229,7 @@ export interface IChartSeriesDataPointStyleSpec {
     size?: number;
     color?: ChartColor;
     fillOpacity?: number;
+    fillPattern?: IChartSeriesFillPattern | null;
 }
 /** Style fields accepted by symbol data points, whose color remains solid-only. */
 export interface IChartSymbolDataPointStyleSpec extends Omit<IChartSeriesDataPointStyleSpec, 'color'> {
@@ -330,6 +348,7 @@ export interface IChartPieLabelSpec extends IChartFontSpec, IChartValueLabelSpec
 }
 /** Authored style for one materialized Pie or Donut slice. */
 export interface IChartSliceStyleSpec {
+    explosion?: number;
     color?: ChartColor;
     fillOpacity?: number;
 }
@@ -470,10 +489,7 @@ export interface IChartAreaSpec {
 export interface IChartBarSpec {
     gapWidth?: number;
     overlap?: number;
-    is3D?: boolean;
     shape?: BarShape;
-    rotX?: number;
-    rotY?: number;
 }
 export interface IChartBubbleSpec {
     scale?: number;
@@ -539,6 +555,8 @@ interface IChartSemanticConfig {
     invalidValueStrategy?: InvalidValueType;
     legend?: ChartLegendSpec;
     axes?: IChartAxesSpec;
+    threeD?: IChart3DStyle;
+    depthAxis?: IChartDepthAxisSpec;
     allSeriesStyle?: IChartSeriesStyleSpec;
     series?: IChartSeriesPatch[];
     wordCloud?: IChartWordCloudSpec;

package/lib/types/chart-builder/configuration/chart-config-group.d.ts

@@ -15,6 +15,8 @@ export declare enum ChartConfigGroup {
     Chord = "chord",
     Axes = "axes",
     Bar = "bar",
+    ThreeD = "threeD",
+    DepthAxis = "depthAxis",
     Bubble = "bubble",
     Heatmap = "heatmap",
     Funnel = "funnel",

package/lib/types/chart-builder/configuration/three-d.d.ts

@@ -0,0 +1,7 @@
+import type { DeepNullish, IChart3DStyle } from '../../types';
+import type { IChartDepthAxisSpec } from '../chart-types';
+/** Authored 3D settings are retained independently of the chart type. */
+export declare const setThreeD: (value: DeepNullish<IChart3DStyle>) => import("./chart-config-operation").IChartConfigOperation;
+export declare const clearThreeD: () => import("./chart-config-operation").IChartConfigOperation;
+export declare const setDepthAxis: (value: DeepNullish<IChartDepthAxisSpec>) => import("./chart-config-operation").IChartConfigOperation;
+export declare const clearDepthAxis: () => import("./chart-config-operation").IChartConfigOperation;

package/lib/types/chart-builder/conversion/chart-model-fields.d.ts

@@ -3,6 +3,8 @@ export declare enum ChartStyleField {
     AllSeriesStyle = "allSeriesStyle",
     Area = "area",
     Bar = "bar",
+    ThreeD = "threeD",
+    DepthAxis = "depthAxis",
     Bubble = "bubble",
     BackgroundColor = "backgroundColor",
     BorderColor = "borderColor",
@@ -71,10 +73,13 @@ export declare enum ChartDataAggregationField {
 }
 export declare enum ChartAxisTitleField {
     RightYAxisTitle = "rightYAxisTitle",
+    DepthAxisTitle = "depthAxisTitle",
     XAxisTitle = "xAxisTitle",
     YAxisTitle = "yAxisTitle"
 }
 export declare enum ChartAxisStyleField {
+    ScaleType = "scaleType",
+    LogBase = "logBase",
     AxisTitleAlignment = "label.axisTitleAlign",
     Format = "format",
     GridLineColor = "gridLine.color",
@@ -124,6 +129,7 @@ export declare enum ChartSeriesStyleField {
     Color = "color",
     DataPoints = "dataPoints",
     FillOpacity = "fillOpacity",
+    FillPattern = "fillPattern",
     LabelBold = "label.bold",
     LabelColor = "label.color",
     LabelContentType = "label.contentType",
@@ -139,8 +145,10 @@ export declare enum ChartSeriesStyleField {
     RightYAxis = "rightYAxis"
 }
 export declare enum ChartDataPointStyleField {
+    Explosion = "explosion",
     Color = "color",
     FillOpacity = "fillOpacity",
+    FillPattern = "fillPattern",
     Shape = "shape",
     Size = "size"
 }