docs: update comments for vchart

packages/vchart/src/animation/spec.ts

@@ -2,11 +2,7 @@ import type { IAnimationConfig, IStateAnimationConfig } from '@visactor/vgrammar
 import type { EasingType } from '@visactor/vrender-core';
 export type { IRunningConfig as IMorphConfig, IMorphAnimationConfig } from '@visactor/vgrammar-core';
 
-export type IStateAnimateSpec<Preset extends string> = {
-  /**
-   * 预设动画效果
-   */
-  preset?: Preset | false;
+export interface ICommonStateAnimateSpec {
   /**
    * 图表动画时长
    */
@@ -23,7 +19,14 @@ export type IStateAnimateSpec<Preset extends string> = {
    * 是否轮流执行
    */
   oneByOne?: boolean;
-};
+}
+
+export interface IStateAnimateSpec<Preset extends string> extends ICommonStateAnimateSpec {
+  /**
+   * 预设动画效果
+   */
+  preset?: Preset | false;
+}
 
 export type IMarkAnimateSpec<MarkName extends string> = Partial<
   Record<MarkName, false | IAnimationConfig | IAnimationConfig[]>
@@ -38,19 +41,19 @@ export interface IAnimationSpec<MarkName extends string, Preset extends string>
   /**
    * 数据更新 - 新增数据动画
    */
-  animationEnter?: boolean | Omit<IStateAnimateSpec<Preset>, 'preset'> | IMarkAnimateSpec<MarkName>;
+  animationEnter?: boolean | ICommonStateAnimateSpec | IMarkAnimateSpec<MarkName>;
   /**
    * 数据更新 - 数据更新动画
    */
-  animationUpdate?: boolean | Omit<IStateAnimateSpec<Preset>, 'preset'> | IMarkAnimateSpec<MarkName>;
+  animationUpdate?: boolean | ICommonStateAnimateSpec | IMarkAnimateSpec<MarkName>;
   /**
    * 数据更新 - 数据删除动画
    */
-  animationExit?: boolean | Omit<IStateAnimateSpec<Preset>, 'preset'> | IMarkAnimateSpec<MarkName>;
+  animationExit?: boolean | ICommonStateAnimateSpec | IMarkAnimateSpec<MarkName>;
   /**
    * 图表退场动画
    */
-  animationDisappear?: boolean | Omit<IStateAnimateSpec<Preset>, 'preset'> | IMarkAnimateSpec<MarkName>;
+  animationDisappear?: boolean | ICommonStateAnimateSpec | IMarkAnimateSpec<MarkName>;
   /**
    * 状态切换动画
    * @since 1.12.0

packages/vchart/src/component/legend/interface.ts

@@ -67,12 +67,24 @@ export type ILegendCommonSpec = {
    */
   visible?: boolean;
   /**
-   * 图例位置
+   * 图例的位置，相对于region区域的四个方位，
+   * left - 图例在左侧
+   * right - 图例在右侧
+   * top - 图例在上方
+   * bottom - 图例在下方
    * @default 'left'
    */
   orient?: IOrientType;
   /**
-   * 图例在当前行列的对齐方式，起始 | 居中 | 末尾
+   * 图例在当前行或者列的对齐方式，起始 | 居中 | 末尾，
+   * 对于orient为'left'或者'right'的图例，
+   * start - 图例在左侧
+   * middle - 图例居中
+   * end - 图例在右侧
+   * 对于orient为'top'或者'bottom'的图例，
+   * start - 图例在上方
+   * middle - 图例居中
+   * end - 图例在下方
    * @default 'middle'
    */
   position?: 'start' | 'middle' | 'end';

packages/vchart/src/series/area/interface.ts

@@ -8,6 +8,7 @@ import type { IDataSamping, IMarkOverlap, IMarkProgressiveConfig } from '../../m
 import type { IMultiLabelSpec, ILabelSpec } from '../../component/label/interface';
 import type { DirectionType } from '../../typings/space';
 
+type AreaMarks = 'point' | 'line' | 'area';
 export interface IAreaAnimationParams {
   direction: DirectionType;
 }
@@ -16,7 +17,7 @@ export type AreaAppearPreset = 'clipIn' | 'fadeIn' | 'grow';
 
 export interface IAreaSeriesSpec
   extends ICartesianSeriesSpec,
-    IAnimationSpec<string, AreaAppearPreset>,
+    IAnimationSpec<AreaMarks, AreaAppearPreset>,
     IMarkProgressiveConfig,
     IDataSamping,
     IMarkOverlap {

packages/vchart/src/series/box-plot/interface.ts

@@ -7,7 +7,7 @@ import type { SeriesMarkNameEnum } from '../interface/type';
 export interface IBoxPlotSeriesSpec
   extends Omit<ICartesianSeriesSpec, 'xField' | 'yField' | 'direction'>,
     // TODO: 补充动画类型 @chengda
-    IAnimationSpec<string, string>,
+    IAnimationSpec<SeriesMarkNameEnum.boxPlot, string>,
     IMarkProgressiveConfig {
   /** 系列类型 */
   type: 'boxPlot';

packages/vchart/src/series/progress/linear/interface.ts

@@ -14,7 +14,7 @@ export type LinearProgressAppearPreset = 'grow' | 'fadeIn';
 export interface ILinearProgressSeriesSpec
   extends IProgressSeriesSpec,
     // TODO: 补充MarkName类型 @liupei
-    IAnimationSpec<string, LinearProgressAppearPreset> {
+    IAnimationSpec<SeriesMarkNameEnum.progress | SeriesMarkNameEnum.track, LinearProgressAppearPreset> {
   type: 'linearProgress';
   /**
    * coordinate: 'cartesian'

packages/vchart/src/series/word-cloud/interface.ts

@@ -199,7 +199,9 @@ export type WordCloudShapeConfigType = {
   fillingRatio?: number;
 };
 
-export interface IWordCloudSeriesBaseSpec extends ISeriesSpec, IAnimationSpec<string, WordcloudAppearPreset> {
+export interface IWordCloudSeriesBaseSpec
+  extends ISeriesSpec,
+    IAnimationSpec<SeriesMarkNameEnum.word, WordcloudAppearPreset> {
   /**
    * 文本字段
    */

packages/vchart/src/typings/layout.ts

@@ -21,11 +21,11 @@ export type IPercent = `${number}%`;
 
 export type IPercentOffset = {
   /**
-   * 百分比值
+   * 百分比值，取值范围为0-1
    */
   percent?: number;
   /**
-   * 偏移量
+   * 偏移量，偏移的像素值
    */
   offset?: number;
 };

packages/vchart/src/typings/spec/common.ts

@@ -248,12 +248,7 @@ export interface IChartSpec {
   media?: IMediaQuerySpec;
 }
 
-export type IBackgroundStyleSpec = ConvertToMarkStyleSpec<Omit<IFillMarkSpec, 'width' | 'height' | 'background'>> & {
-  image?: IRectMarkSpec['background'];
-  cornerRadius?: IRectMarkSpec['cornerRadius'];
-};
-
-export type IBackgroundSpec = IColor | IBackgroundStyleSpec;
+export type IBackgroundSpec = IColor | ConvertToMarkStyleSpec<IGroupMarkSpec>;
 
 /** data */
 export type IDataType = IDataValues | DataView;
@@ -492,6 +487,29 @@ export type AdaptiveSpec<T, K extends keyof any> = {
   [key in Exclude<keyof T, K>]: T[key];
 } & { [key in K]: any };
 
+export interface IMarkStateFullSpec<T> extends Record<string, IMarkStateSpec<T> | IMarkStateStyleSpec<T>> {
+  /**
+   * 正常状态下图元的样式设置
+   */
+  normal?: IMarkStateSpec<T> | IMarkStateStyleSpec<T>;
+  /**
+   * hover状态下图元的样式设置
+   */
+  hover?: IMarkStateSpec<T> | IMarkStateStyleSpec<T>;
+  /**
+   * 没有被hover的状态下图元的样式设置
+   */
+  hover_reverse?: IMarkStateSpec<T> | IMarkStateStyleSpec<T>;
+  /**
+   * 选中状态下图元的样式设置
+   */
+  selected?: IMarkStateSpec<T> | IMarkStateStyleSpec<T>;
+  /**
+   * 没有被选中的状态下图元的样式设置
+   */
+  selected_reverse?: IMarkStateSpec<T> | IMarkStateStyleSpec<T>;
+}
+
 /** markSpec */
 export type IMarkSpec<T extends ICommonSpec = ICommonSpec> = {
   /**
@@ -518,7 +536,7 @@ export type IMarkSpec<T extends ICommonSpec = ICommonSpec> = {
   /** 默认样式设置 */
   style?: ConvertToMarkStyleSpec<T>;
   /** 不同状态下的样式配置 */
-  state?: Record<StateValue, IMarkStateSpec<T> | IMarkStateStyleSpec<T>>;
+  state?: IMarkStateFullSpec<T>;
   /**
    * 状态排序方法，默认状态都是按照添加的顺序处理的，如果有特殊的需求，需要指定状态顺序，可以通过这个方法实现
    * @since 1.9.0
@@ -561,6 +579,29 @@ export interface IMarkStateSpec<T> {
 
 export type IMarkStateStyleSpec<T> = ConvertToMarkStyleSpec<T>;
 
+export interface IMarkStateTheme<T> extends Record<string, T> {
+  /**
+   * 图元在正常状态下的主题样式设置
+   */
+  normal?: T;
+  /**
+   * 图元在 hover 状态下的主题样式设置
+   */
+  hover?: T;
+  /**
+   * 图元在 未被hover 状态下的主题样式设置
+   */
+  hover_reverse?: T;
+  /**
+   * 图元在 选中状态下的主题样式设置
+   */
+  selected?: T;
+  /**
+   * 图元在 未被选中 状态下的主题样式设置
+   */
+  selected_reverse?: T;
+}
+
 export type IMarkTheme<T> = {
   /**
    * mark 层 是否显示配置
@@ -569,7 +610,7 @@ export type IMarkTheme<T> = {
   /** 默认样式设置 */
   style?: T;
   /** 不同状态下的样式配置 */
-  state?: Record<StateValue, T>;
+  state?: IMarkStateTheme<T>;
   /**
    * 可交互的开关
    */