refactor: adjust element types (#5693)

* refactor: adjust types

* docs: add comments

* refactor: reorganize api directory structure

* docs: refine element docs

packages/g6-extension-3d/src/elements/base-node-3d.ts

@@ -2,21 +2,18 @@ import type { BaseStyleProps, DisplayObjectConfig, Group } from '@antv/g';
 import type { ProceduralGeometry as GGeometry, Material as GMaterial } from '@antv/g-plugin-3d';
 import { Mesh } from '@antv/g-plugin-3d';
 import type { IMaterial, Plugin } from '@antv/g-plugin-device-renderer';
-import type { BaseNodeStyleProps } from '@antv/g6';
+import type { BaseNodeStyleProps, Prefix } from '@antv/g6';
 import { BaseNode, omitStyleProps, subStyleProps } from '@antv/g6';
-import { PrefixObject } from '@antv/g6/lib/types';
 import { deepMix } from '@antv/util';
 import { Material } from '../types';
 import { createMaterial } from '../utils/material';
 
-export type BaseNode3DStyleProps = BaseNodeStyleProps<
-  {
-    geometry?: GGeometry<any>;
-    material?: GMaterial<any>;
-    texture?: string | TexImageSource;
-    materialType?: Material['type'];
-  } & PrefixObject<IMaterial, 'material'>
->;
+export interface BaseNode3DStyleProps extends BaseNodeStyleProps, Prefix<'material', IMaterial> {
+  geometry?: GGeometry<any>;
+  material?: GMaterial<any>;
+  texture?: string | TexImageSource;
+  materialType?: Material['type'];
+}
 
 export abstract class BaseNode3D<S extends BaseNode3DStyleProps> extends BaseNode<S> {
   static defaultStyleProps: Partial<BaseNode3DStyleProps> = {

packages/g6-extension-react/src/elements/g/node.tsx

@@ -5,7 +5,14 @@ import { Rect } from '@antv/g6';
 import { render } from '@antv/react-g';
 import type { FC, ReactNode } from 'react';
 
-export type GNodeStyleProps = BaseNodeStyleProps<{ component: FC }>;
+export interface GNodeStyleProps extends BaseNodeStyleProps {
+  /**
+   * <zh/> React 组件
+   *
+   * <en/> React component
+   */
+  component: FC;
+}
 
 export class GNode extends Rect {
   static defaultStyleProps: Partial<GNodeStyleProps> = {

packages/g6-extension-react/src/elements/react/node.tsx

@@ -5,7 +5,14 @@ import type { FC, ReactNode as IReactNode } from 'react';
 import type { Root } from 'react-dom/client';
 import { createRoot } from 'react-dom/client';
 
-export type ReactNodeStyleProps = BaseNodeStyleProps<{ component: FC }>;
+export interface ReactNodeStyleProps extends BaseNodeStyleProps {
+  /**
+   * <zh/> React 组件
+   *
+   * <en/> React component
+   */
+  component: FC;
+}
 
 export class ReactNode extends HTML {
   private root!: Root;

packages/g6/src/behaviors/drag-element.ts

@@ -3,15 +3,15 @@ import { Rect } from '@antv/g';
 import { isFunction } from '@antv/util';
 import { COMBO_KEY, CommonEvent } from '../constants';
 import type { RuntimeContext } from '../runtime/types';
-import type { EdgeDirection, Element, ID, IDragEvent, Point, PrefixObject } from '../types';
+import type { EdgeDirection, Element, ID, IDragEvent, Point, Prefix } from '../types';
 import { getBBoxSize, getCombinedBBox } from '../utils/bbox';
 import { idOf } from '../utils/id';
 import { subStyleProps } from '../utils/prefix';
 import { divide, subtract } from '../utils/vector';
 import type { BaseBehaviorOptions } from './base-behavior';
 import { BaseBehavior } from './base-behavior';
 
-export interface DragElementOptions extends BaseBehaviorOptions, PrefixObject<BaseStyleProps, 'shadow'> {
+export interface DragElementOptions extends BaseBehaviorOptions, Prefix<'shadow', BaseStyleProps> {
   /**
    * <zh/> 是否启用拖拽动画
    *

packages/g6/src/constants/element.ts

@@ -1,5 +1,6 @@
 /**
  * <zh/> 根据不同的 node，自动计算 icon 的大小之后，乘以一下缩放系数，防止贴的太紧密。
+ *
  * <en/> According to the different nodes, the size of the icon is automatically calculated, and then multiplied by the following scaling factor to prevent it from being too close.
  */
 export const ICON_SIZE_RATIO = 0.8;

packages/g6/src/elements/combos/base-combo.ts

@@ -1,15 +1,15 @@
-import type { AABB, DisplayObject, DisplayObjectConfig, Group } from '@antv/g';
+import type { AABB, BaseStyleProps, DisplayObject, DisplayObjectConfig, Group } from '@antv/g';
 import { deepMix, isEmpty, isFunction } from '@antv/util';
 import { COMBO_KEY } from '../../constants';
 import type {
-  BaseElementStyleProps,
+  CollapsedMarkerStyleProps,
   Combo,
   Node,
   NodeLikeData,
   Padding,
   Placement,
   Position,
-  PrefixObject,
+  Prefix,
   STDSize,
   Size,
 } from '../../types';
@@ -25,65 +25,72 @@ import type { BaseNodeStyleProps } from '../nodes';
 import { BaseNode } from '../nodes';
 import { Icon, IconStyleProps } from '../shapes';
 
-export type BaseComboStyleProps<T extends Record<string, unknown> = Record<string, any>> = T &
-  BaseElementStyleProps &
-  BaseNodeStyleProps<T> &
-  PrefixObject<T, 'collapsed'> &
-  PrefixObject<CollapsedMarkerStyleProps, 'collapsedMarker'> & {
-    /**
-     * <zh/> Combo 展开后的默认大小
-     *
-     * <en/> The default size of combo when expanded
-     */
-    size?: Size;
-    /**
-     * <zh/> Combo 收起后的默认大小
-     *
-     * <en/> The default size of combo when collapsed
-     */
-    collapsedSize?: Size;
-    /**
-     * <zh/> Combo 收起时的原点
-     * <en/> The origin of combo when collapsed
-     */
-    collapsedOrigin?: Placement | [number, number];
-    /**
-     * <zh/> Combo 的子元素，可以是节点或者 Combo
-     *
-     * <en/> The children of combo, which can be nodes or combos
-     */
-    childrenNode?: (Node | Combo)[];
-    /**
-     * <zh/> Combo 的子元素数据
-     *
-     * <en/> The data of the children of combo
-     * @remarks
-     * <zh/> 如果 combo 是收起状态，children 可能为空，通过 childrenData 能够获取完整的子元素数据
-     *
-     * <en/> If the combo is collapsed, children may be empty, and the complete child element data can be obtained through childrenData
-     */
-    childrenData?: NodeLikeData[];
-    /**
-     * <zh/> Combo 的内边距，只在展开状态下生效
-     * <en/> The padding of combo, only effective when expanded
-     */
-    padding?: Padding;
-    collapsedMarker?: boolean;
-  };
-
-export type CollapsedMarkerStyleProps = IconStyleProps & {
+/**
+ * <zh/> 组合通用样式配置项
+ *
+ * <en/> Common style props for combo
+ */
+export interface BaseComboStyleProps
+  extends BaseNodeStyleProps,
+    Prefix<'collapsed', BaseStyleProps>,
+    Prefix<'collapsedMarker', CollapsedMarkerStyleProps> {
+  /**
+   * <zh/> 组合展开后的默认大小
+   *
+   * <en/> The default size of combo when expanded
+   */
+  size?: Size;
+  /**
+   * <zh/> 组合收起后的默认大小
+   *
+   * <en/> The default size of combo when collapsed
+   */
+  collapsedSize?: Size;
+  /**
+   * <zh/> 组合收起时的原点
+   *
+   * <en/> The origin of combo when collapsed
+   */
+  collapsedOrigin?: Placement;
   /**
-   * <zh/> 标记类型
-   * <en/> Marker type
+   * <zh/> 组合的子元素，可以是节点或者组合
    *
-   * - 'child-count': Number of child elements
-   * - 'descendant-count': Number of descendant elements (including Nodes and Combos)
-   * - 'node-count': Number of descendant elements (only Nodes)
-   * - (children: NodeLikeData[]) => string: Custom function
+   * <en/> The children of combo, which can be nodes or combos
    */
-  type?: 'child-count' | 'descendant-count' | 'node-count' | ((children: NodeLikeData[]) => string);
-};
+  childrenNode?: (Node | Combo)[];
+  /**
+   * <zh/> 组合的子元素数据
+   *
+   * <en/> The data of the children of combo
+   * @remarks
+   * <zh/> 如果组合是收起状态，children 可能为空，通过 childrenData 能够获取完整的子元素数据
+   *
+   * <en/> If the combo is collapsed, children may be empty, and the complete child element data can be obtained through childrenData
+   */
+  childrenData?: NodeLikeData[];
+  /**
+   * <zh/> 组合的内边距，只在展开状态下生效
+   *
+   * <en/> The padding of combo, only effective when expanded
+   */
+  padding?: Padding;
+  /**
+   * <zh/> 组合收起时是否显示标记
+   *
+   * <en/> Whether to show the marker when the combo is collapsed
+   */
+  collapsedMarker?: boolean;
+}
 
+/**
+ * <zh/> 组合元素的基类
+ *
+ * <en/> Base class of combo
+ * @remarks
+ * <zh/> 自定义组合时，推荐使用这个类作为基类。这样，用户只需要专注于实现 keyShape 的绘制逻辑
+ *
+ * <en/> When customizing a combo, it is recommended to use this class as the base class. In this way, users only need to focus on the logic of drawing keyShape
+ */
 export abstract class BaseCombo<S extends BaseComboStyleProps = BaseComboStyleProps> extends BaseNode<S> {
   public type = 'combo';
 

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

@@ -9,8 +9,20 @@ import { parseSize } from '../../utils/size';
 import type { BaseComboStyleProps } from './base-combo';
 import { BaseCombo } from './base-combo';
 
-export type CircleComboStyleProps = BaseComboStyleProps;
+/**
+ * <zh/> 圆形组合样式配置项
+ *
+ * <en/> Circle combo style props
+ */
+export interface CircleComboStyleProps extends BaseComboStyleProps {}
 
+/**
+ * <zh/> 圆形组合
+ *
+ * <en/> Circle combo
+ * @remarks
+ * <img width="300" src="https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*WJhpRJCcFLAAAAAAAAAAAAAADmJ7AQ/original" />
+ */
 export class CircleCombo extends BaseCombo<CircleComboStyleProps> {
   constructor(options: DisplayObjectConfig<CircleComboStyleProps>) {
     super(options);

packages/g6/src/elements/combos/rect.ts

@@ -5,8 +5,18 @@ import { subStyleProps } from '../../utils/prefix';
 import type { BaseComboStyleProps } from './base-combo';
 import { BaseCombo } from './base-combo';
 
-export type RectComboStyleProps = BaseComboStyleProps;
+/**
+ * <zh/> 矩形组合样式配置项
+ *
+ * <en/> Rect combo style props
+ */
+export interface RectComboStyleProps extends BaseComboStyleProps {}
 
+/**
+ * <zh/> 矩形组合
+ *
+ * <en/> Rect combo
+ */
 export class RectCombo extends BaseCombo<RectComboStyleProps> {
   static defaultStyleProps: Partial<RectComboStyleProps> = {
     anchor: [0.5, 0.5],