refactor: type define (#5468)

* chore: add 3d sphere file

* test: add createDeterministicRandom for 3d test data

* chore: simplify type define

* fix: create webgl instance

* chore: remove sphere

packages/g6/__tests__/mock/create.ts

@@ -1,6 +1,8 @@
 import type { IRenderer } from '@antv/g';
 import { resetEntityCounter } from '@antv/g';
 import { Renderer as CanvasRenderer } from '@antv/g-canvas';
+import { Plugin as Plugin3D } from '@antv/g-plugin-3d';
+import { Plugin as PluginControl } from '@antv/g-plugin-control';
 import { Plugin as DragAndDropPlugin } from '@antv/g-plugin-dragndrop';
 import { Renderer as SVGRenderer } from '@antv/g-svg';
 import { Renderer as WebGLRenderer } from '@antv/g-webgl';
@@ -27,8 +29,12 @@ export function createGraph(options: G6Spec, graphCanvas?: Canvas) {
 
 function getRenderer(renderer: string) {
   switch (renderer) {
-    case 'webgl':
-      return new WebGLRenderer();
+    case 'webgl': {
+      const instance = new WebGLRenderer();
+      instance.registerPlugin(new Plugin3D());
+      instance.registerPlugin(new PluginControl());
+      return instance;
+    }
     case 'svg':
       return new SVGRenderer();
     case 'canvas':

packages/g6/__tests__/mock/index.ts

@@ -1,2 +1,3 @@
 export { createGraph, createGraphCanvas } from './create';
 export { Graph } from './graph';
+export { createDeterministicRandom } from './random';

packages/g6/__tests__/mock/random.ts

@@ -0,0 +1,11 @@
+/**
+ * Get random number(0 - 1) generator, with deterministic random number.
+ * @returns Random number
+ */
+export function createDeterministicRandom() {
+  let i = 0;
+  return () => {
+    i++;
+    return (Math.E * i) % 1;
+  };
+}

packages/g6/__tests__/unit/utils/random.spec.ts

@@ -0,0 +1,12 @@
+import { createDeterministicRandom } from '../../mock/random';
+
+describe('createDeterministicRandom', () => {
+  it('should generate a random number between 0 and 1', () => {
+    const r1 = createDeterministicRandom();
+    const r2 = createDeterministicRandom();
+
+    expect(new Array(100).fill(0).map(r1)).toEqual(new Array(100).fill(0).map(r2));
+    expect(r1()).toBeGreaterThanOrEqual(0);
+    expect(r1()).toBeLessThan(1);
+  });
+});

packages/g6/src/elements/edges/base-edge.ts

@@ -76,7 +76,7 @@ export type ParsedBaseEdgeStyleProps<KT> = Required<BaseEdgeStyleProps<KT>>;
 
 export type BaseEdgeOptions<KT> = DisplayObjectConfig<BaseEdgeStyleProps<KT>>;
 
-export abstract class BaseEdge<KT extends BaseEdgeProps<object>> extends BaseShape<BaseEdgeStyleProps<KT>> {
+export abstract class BaseEdge<KT extends BaseEdgeProps> extends BaseShape<BaseEdgeStyleProps<KT>> {
   static defaultStyleProps: Partial<BaseEdgeStyleProps<any>> = {
     isBillboard: true,
     label: true,

packages/g6/src/elements/edges/cubic-horizontal.ts

@@ -4,7 +4,7 @@ import type { BaseEdgeProps, Point } from '../../types';
 import type { BaseEdgeStyleProps } from './base-edge';
 import { Cubic } from './cubic';
 
-type CubicHorizontalKeyStyleProps = BaseEdgeProps<{
+type CubicHorizontalKeyStyleProps = BaseEdgeProps & {
   /**
    * <zh/> 控制点在两端点连线上的相对位置，范围为`0-1`
    * <en/> The relative position of the control point on the line, ranging from `0-1`
@@ -15,7 +15,7 @@ type CubicHorizontalKeyStyleProps = BaseEdgeProps<{
    * <en/> The distance of the control point from the line
    */
   curveOffset?: number | [number, number];
-}>;
+};
 export type CubicHorizontalStyleProps = BaseEdgeStyleProps<CubicHorizontalKeyStyleProps>;
 type CubicHorizontalOptions = DisplayObjectConfig<CubicHorizontalStyleProps>;
 

packages/g6/src/elements/edges/cubic-vertical.ts

@@ -4,7 +4,7 @@ import type { BaseEdgeProps, Point } from '../../types';
 import type { BaseEdgeStyleProps } from './base-edge';
 import { Cubic } from './cubic';
 
-type CubicVerticalKeyStyleProps = BaseEdgeProps<{
+type CubicVerticalKeyStyleProps = BaseEdgeProps & {
   /**
    * <zh/> 控制点在两端点连线上的相对位置，范围为`0-1`
    * <en/> The relative position of the control point on the line, ranging from `0-1`
@@ -15,7 +15,7 @@ type CubicVerticalKeyStyleProps = BaseEdgeProps<{
    * <en/> The distance of the control point from the line
    */
   curveOffset?: number | [number, number];
-}>;
+};
 export type CubicVerticalStyleProps = BaseEdgeStyleProps<CubicVerticalKeyStyleProps>;
 type CubicVerticalOptions = DisplayObjectConfig<CubicVerticalStyleProps>;
 

packages/g6/src/elements/edges/cubic.ts

@@ -6,7 +6,7 @@ import { getCubicPath, getCurveControlPoint, parseCurveOffset, parseCurvePositio
 import type { BaseEdgeStyleProps } from './base-edge';
 import { BaseEdge } from './base-edge';
 
-type CubicKeyStyleProps = BaseEdgeProps<{
+type CubicKeyStyleProps = BaseEdgeProps & {
   /**
    * <zh/> 控制点数组，用于定义曲线的形状。如果不指定，将会通过`curveOffset`和`curvePosition`来计算控制点
    * <en/> Control points. Used to define the shape of the curve. If not specified, it will be calculated using `curveOffset` and `curvePosition`.
@@ -22,7 +22,7 @@ type CubicKeyStyleProps = BaseEdgeProps<{
    * <en/> The distance of the control point from the line
    */
   curveOffset?: number | [number, number];
-}>;
+};
 export type CubicStyleProps = BaseEdgeStyleProps<CubicKeyStyleProps>;
 type CubicOptions = DisplayObjectConfig<CubicStyleProps>;
 

packages/g6/src/elements/edges/polyline.ts

@@ -10,7 +10,7 @@ import { orth } from '../../utils/router/orth';
 import type { BaseEdgeStyleProps, LoopStyleProps, ParsedBaseEdgeStyleProps } from './base-edge';
 import { BaseEdge } from './base-edge';
 
-type PolylineKeyStyleProps = BaseEdgeProps<{
+type PolylineKeyStyleProps = BaseEdgeProps & {
   /**
    * <zh/> 圆角半径
    * <en/> The radius of the rounded corner
@@ -36,7 +36,7 @@ type PolylineKeyStyleProps = BaseEdgeProps<{
    * <en/> Padding for routing calculation
    */
   routerPadding?: Padding;
-}>;
+};
 export type PolylineStyleProps = BaseEdgeStyleProps<PolylineKeyStyleProps>;
 type ParsedPolylineStyleProps = ParsedBaseEdgeStyleProps<PolylineKeyStyleProps>;
 type PolylineOptions = DisplayObjectConfig<PolylineStyleProps>;

packages/g6/src/elements/edges/quadratic.ts

@@ -6,7 +6,7 @@ import { getCurveControlPoint, getQuadraticPath } from '../../utils/edge';
 import type { BaseEdgeStyleProps, ParsedBaseEdgeStyleProps } from './base-edge';
 import { BaseEdge } from './base-edge';
 
-type QuadraticKeyStyleProps = BaseEdgeProps<{
+type QuadraticKeyStyleProps = BaseEdgeProps & {
   /**
    * <zh/> 控制点，用于定义曲线的形状。如果不指定，将会通过`curveOffset`和`curvePosition`来计算控制点
    * <en/> Control point. Used to define the shape of the curve. If not specified, it will be calculated using `curveOffset` and `curvePosition`.
@@ -22,7 +22,7 @@ type QuadraticKeyStyleProps = BaseEdgeProps<{
    * <en/> The distance of the control point from the line
    */
   curveOffset?: number;
-}>;
+};
 export type QuadraticStyleProps = BaseEdgeStyleProps<QuadraticKeyStyleProps>;
 type QuadraticOptions = DisplayObjectConfig<QuadraticStyleProps>;
 

packages/g6/src/elements/nodes/base-node.ts

@@ -4,7 +4,6 @@ import { deepMix, isEmpty } from '@antv/util';
 import type {
   BadgePosition,
   BaseNodeProps,
-  ExtractGShapeStyleProps,
   Keyframe,
   LabelPosition,
   Point,
@@ -20,15 +19,39 @@ import { getWordWrapWidthByBox } from '../../utils/text';
 import type { BadgeStyleProps, BaseShapeStyleProps, IconStyleProps, LabelStyleProps } from '../shapes';
 import { Badge, BaseShape, Icon, Label } from '../shapes';
 
-type NodeLabelStyleProps = LabelStyleProps & { position?: LabelPosition; maxWidth?: string | number };
+type NodeLabelStyleProps = LabelStyleProps & {
+  /**
+   * Position relative to the node (keyShape).
+   */
+  position?: LabelPosition;
+  /**
+   * The max width of the label, relative to the node width. The value can be a number or a percentage string:
+   * If the value is a number, it will be treated as the pixel value.
+   * If the value is a percentage string, it will be treated as the percentage of the node width.
+   */
+  maxWidth?: string | number;
+};
 
-type NodeBadgeStyleProps = BadgeStyleProps & { position?: BadgePosition };
+type NodeBadgeStyleProps = BadgeStyleProps & {
+  /**
+   * Position relative to the node (keyShape).
+   */
+  position?: BadgePosition;
+};
 type NodeBadgesStyleProps = {
   badges?: NodeBadgeStyleProps[];
 } & PrefixObject<BadgeStyleProps, 'badge'>;
 
 export type NodePortStyleProps = Partial<PortStyleProps> & {
+  /**
+   * The key of the port. Default is the index of the port.
+   */
   key?: string;
+  /**
+   * The position of the port relative to the node (keyShape). The value can be a string or a tuple of two numbers.
+   * If the value is a string, it will be treated as the position direction.
+   * If the value is a tuple of two numbers, it will be treated as the position coordinates(0 ~ 1).
+   */
   position: string | [number, number];
 };
 type NodePortsStyleProps = {
@@ -37,8 +60,9 @@ type NodePortsStyleProps = {
 
 type NodeIconStyleProps = IconStyleProps;
 
-export type BaseNodeStyleProps<P extends object> = BaseShapeStyleProps &
-  P & {
+// K is the StyleProps of Key Shape.
+export type BaseNodeStyleProps<K extends BaseNodeProps> = BaseShapeStyleProps &
+  K & {
     // Whether to show the blocGShape.
     label?: boolean;
     halo?: boolean;
@@ -47,31 +71,27 @@ export type BaseNodeStyleProps<P extends object> = BaseShapeStyleProps &
     port?: boolean;
   } & PrefixObject<NodeLabelStyleProps, 'label'> & // Label
   // Halo
-  PrefixObject<P, 'halo'> &
+  PrefixObject<K, 'halo'> &
   // Icon
   PrefixObject<NodeIconStyleProps, 'icon'> &
   // Badges
   NodeBadgesStyleProps &
   // Ports
   NodePortsStyleProps;
 
-export type ParsedBaseNodeStyleProps<P extends object> = Required<BaseNodeStyleProps<P>>;
+export type ParsedBaseNodeStyleProps<K extends BaseNodeProps> = Required<BaseNodeStyleProps<K>>;
 
-type BaseNodeOptions<P extends object> = DisplayObjectConfig<BaseNodeStyleProps<P>>;
+type BaseNodeOptions<K extends BaseNodeProps> = DisplayObjectConfig<BaseNodeStyleProps<K>>;
 
 /**
  * Design document: https://www.yuque.com/antv/g6/gl1iof1xpzg6ed98
- * - key [default]
- * - halo
- * - icon
- * - badges
- * - label, background included
- * - ports
+ *
+ * The P is the StyleProps of Key Shape.
+ * The GSHAPE is the type of the key shape.
  */
-export abstract class BaseNode<
-  P extends BaseNodeProps<object>,
-  GSHAPE extends DisplayObject<any, any>,
-> extends BaseShape<BaseNodeStyleProps<P>> {
+export abstract class BaseNode<P extends BaseNodeProps, GSHAPE extends DisplayObject> extends BaseShape<
+  BaseNodeStyleProps<P>
+> {
   static defaultStyleProps: BaseNodeStyleProps<any> = {
     x: 0,
     y: 0,
@@ -105,13 +125,13 @@ export abstract class BaseNode<
     super(deepMix({}, { style: BaseNode.defaultStyleProps }, options));
   }
 
-  protected getKeyStyle(attributes: ParsedBaseNodeStyleProps<P>): ExtractGShapeStyleProps<GSHAPE> {
+  protected getKeyStyle(attributes: ParsedBaseNodeStyleProps<P>): P {
     const { color, fill, ...style } = this.getGraphicStyle(attributes);
 
-    return {
-      ...omitStyleProps(style, ['label', 'halo', 'icon', 'badge', 'port']),
-      fill: color || fill,
-    } as ExtractGShapeStyleProps<GSHAPE>;
+    return Object.assign(
+      { fill: color || fill },
+      omitStyleProps(style, ['label', 'halo', 'icon', 'badge', 'port']),
+    ) as unknown as P;
   }
 
   protected getLabelStyle(attributes: ParsedBaseNodeStyleProps<P>): false | LabelStyleProps {

packages/g6/src/elements/nodes/circle.ts

@@ -8,14 +8,15 @@ import type { IconStyleProps } from '../shapes';
 import type { BaseNodeStyleProps } from './base-node';
 import { BaseNode } from './base-node';
 
-export type CircleStyleProps = BaseNodeStyleProps<BaseNodeProps>;
+type CircleKeyStyleProps = BaseNodeProps & GCircleStyleProps;
+export type CircleStyleProps = BaseNodeStyleProps<CircleKeyStyleProps>;
 type ParsedCircleStyleProps = Required<CircleStyleProps>;
 type CircleOptions = DisplayObjectConfig<CircleStyleProps>;
 
 /**
  * Draw circle based on BaseNode, override drawKeyShape.
  */
-export class Circle extends BaseNode<BaseNodeProps, GCircle> {
+export class Circle extends BaseNode<CircleKeyStyleProps, GCircle> {
   static defaultStyleProps: Partial<CircleStyleProps> = {
     width: 50,
     height: 50,
@@ -29,14 +30,14 @@ export class Circle extends BaseNode<BaseNodeProps, GCircle> {
     return this.upsert('key', GCircle, this.getKeyStyle(attributes), container);
   }
 
-  protected getKeyStyle(attributes: ParsedCircleStyleProps): GCircleStyleProps {
-    const { x, y, z, width, height, ...keyStyle } = super.getKeyStyle(attributes) as unknown as ParsedCircleStyleProps;
+  protected getKeyStyle(attributes: ParsedCircleStyleProps): CircleKeyStyleProps {
+    const { x, y, z, width, height, ...keyStyle } = super.getKeyStyle(attributes);
     return {
       ...keyStyle,
       cx: x,
       cy: y,
       cz: z,
-      r: Math.min(width, height) / 2,
+      r: Math.min(width as number, height as number) / 2,
     };
   }
 

packages/g6/src/elements/nodes/ellipse.ts

@@ -8,11 +8,12 @@ import type { IconStyleProps } from '../shapes';
 import type { BaseNodeStyleProps } from './base-node';
 import { BaseNode } from './base-node';
 
-export type EllipseStyleProps = BaseNodeStyleProps<BaseNodeProps>;
+type EllipseKeyStyleProps = BaseNodeProps & GEllipseStyleProps;
+export type EllipseStyleProps = BaseNodeStyleProps<EllipseKeyStyleProps>;
 type ParsedEllipseStyleProps = Required<EllipseStyleProps>;
 type EllipseOptions = DisplayObjectConfig<EllipseStyleProps>;
 
-export class Ellipse extends BaseNode<BaseNodeProps, GEllipse> {
+export class Ellipse extends BaseNode<EllipseKeyStyleProps, GEllipse> {
   static defaultStyleProps: Partial<EllipseStyleProps> = {
     width: 80,
     height: 40,
@@ -27,14 +28,14 @@ export class Ellipse extends BaseNode<BaseNodeProps, GEllipse> {
   }
 
   protected getKeyStyle(attributes: ParsedEllipseStyleProps): GEllipseStyleProps {
-    const { x, y, z, width, height, ...keyStyle } = super.getKeyStyle(attributes) as unknown as ParsedEllipseStyleProps;
+    const { x, y, z, width, height, ...keyStyle } = super.getKeyStyle(attributes);
     return {
       ...keyStyle,
       cx: x,
       cy: y,
       cz: z,
-      rx: width / 2,
-      ry: height / 2,
+      rx: (width as number) / 2,
+      ry: (height as number) / 2,
     };
   }
 

packages/g6/src/elements/nodes/image.ts

@@ -1,19 +1,20 @@
-import type { DisplayObjectConfig, Group } from '@antv/g';
+import type { DisplayObjectConfig, RectStyleProps as GRectStyleProps, Group } from '@antv/g';
 import { Image as GImage, ImageStyleProps as GImageStyleProps, Rect as GRect } from '@antv/g';
 import { deepMix } from '@antv/util';
 import { ICON_SIZE_RATIO } from '../../constants/element';
-import type { BaseNodeProps } from '../../types';
+import type { BaseNodeProps, PrefixObject } from '../../types';
 import { subStyleProps } from '../../utils/prefix';
 import type { IconStyleProps } from '../shapes';
 import type { BaseNodeStyleProps } from './base-node';
 import { BaseNode } from './base-node';
-import { PolygonKeyStyleProps, PolygonStyleProps } from './polygon';
 
-type ImageKeyStyleProps = BaseNodeProps<BaseNodeProps & GImageStyleProps>;
-export type ImageStyleProps = BaseNodeStyleProps<ImageKeyStyleProps>;
+type ImageKeyStyleProps = BaseNodeProps & GImageStyleProps;
+type HaloStyleProps = GRectStyleProps;
+export type ImageStyleProps = BaseNodeStyleProps<ImageKeyStyleProps> &
+  // Halo
+  PrefixObject<HaloStyleProps, 'halo'>;
 type ParsedImageStyleProps = Required<ImageStyleProps>;
 type ImageOptions = DisplayObjectConfig<ImageStyleProps>;
-type HaloStyleProps = Required<PolygonStyleProps<PolygonKeyStyleProps>>;
 
 export class Image extends BaseNode<ImageKeyStyleProps, GImage> {
   static defaultStyleProps: Partial<ImageStyleProps> = {
@@ -25,14 +26,15 @@ export class Image extends BaseNode<ImageKeyStyleProps, GImage> {
     super(deepMix({}, { style: Image.defaultStyleProps }, options));
   }
 
-  protected getKeyStyle(attributes: ParsedImageStyleProps): GImageStyleProps {
+  protected getKeyStyle(attributes: ParsedImageStyleProps): ImageKeyStyleProps {
     const keyStyle = super.getKeyStyle(attributes) as unknown as ParsedImageStyleProps;
     return {
       ...keyStyle,
       anchor: [0.5, 0.5] as [number, number],
     };
   }
 
+  // @ts-expect-error The return type of this method is not compatible with the return type of its overridden method.
   protected getHaloStyle(attributes: ParsedImageStyleProps): false | HaloStyleProps {
     if (attributes.halo === false) return false;
 
@@ -43,7 +45,7 @@ export class Image extends BaseNode<ImageKeyStyleProps, GImage> {
     const height = Number(attributes.height) + haloLineWidth;
     const fill = 'transparent';
 
-    return { ...keyStyle, ...haloStyle, width, height, fill } as HaloStyleProps;
+    return { ...keyStyle, ...haloStyle, width, height, fill } as unknown as HaloStyleProps;
   }
 
   protected getIconStyle(attributes: ParsedImageStyleProps): false | IconStyleProps {