docs: 优化 types 类型定义，使得类型注释能在 VSCode 中正确被提示

packages/types/src/assets.ts

@@ -2,34 +2,100 @@ import { NpmInfo } from './npm';
 import { PropConfig } from './prop-config';
 import { Snippet, ComponentMetadata } from './metadata';
 
-export interface Package { // 应该被编辑器默认加载，定义组件大包及external资源的信息
+/**
-  package: string; // 包名
+ * 应该被编辑器默认加载，定义组件大包及external资源的信息
-  version: string; // 包版本号
+ */
-  urls?: string[] | any; // 组件渲染态视图打包后的 CDN url 列表，包含 js 和 css
+export interface Package {
-  editUrls?: string[] | any; // 组件编辑态视图打包后的 CDN url 列表，包含 js 和 css
+  /**
-  library: string; // 作为全局变量引用时的名称，和webpack output.library字段含义一样，用来定义全局变量名
+   * 包名
-  async?: boolean,
+   */
+  package: string;
+  /**
+   * 包版本号
+   */
+  version: string;
+  /**
+   * 组件渲染态视图打包后的 CDN url 列表，包含 js 和 css
+   */
+  urls?: string[] | any;
+  /**
+   * 组件编辑态视图打包后的 CDN url 列表，包含 js 和 css
+   */
+  editUrls?: string[] | any;
+  /**
+   * 作为全局变量引用时的名称，和webpack output.library字段含义一样，用来定义全局变量名
+   */
+  library: string;
+  /**
+   * 待补充文档
+   */
+  async?: boolean;
+  /**
+   * 待补充文档
+   */
   exportName?: string;
 }
 
-export interface ComponentCategory { // 组件分类
+/**
-  title: string; // 组件分类title
+ * 组件分类
-  icon?: string; // 组件分类icon
+ */
-  children?: ComponentItem[] | ComponentCategory[]; // 可能有子分类
+export interface ComponentCategory {
+  /**
+   * 组件分类title
+   */
+  title: string;
+  /**
+   * 组件分类icon
+   */
+  icon?: string;
+  /**
+   * 可能有子分类
+   */
+  children?: ComponentItem[] | ComponentCategory[];
 }
 
-export interface ComponentItem { // 组件
+/**
-  title: string; // 组件title
+ * 组件
-  componentName?: string; // 组件名
+ */
-  icon?: string; // 组件icon
+export interface ComponentItem {
+  /**
+   * 组件title
+   */
+  title: string;
+  /**
+   * 组件名
+   */
+  componentName?: string;
+  /**
+   * 组件icon
+   */
+  icon?: string;
+  /**
+   * 待补充文档
+   */
   snippets?: Snippet[];
 }
 
+/**
+ * 本地物料描述
+ */
 export interface ComponentDescription extends ComponentMetadata {
+  /**
+   * 待补充文档
+   */
   keywords: string[];
 }
 
+/**
+ * 远程物料描述
+ */
 export interface RemoteComponentDescription {
+  /**
+   * 待补充文档
+   */
   exportName: string;
+  /**
+   * 待补充文档
+   */
   url: string;
 }

packages/types/src/field-config.ts

@@ -1,6 +1,7 @@
 import { TitleContent } from './title';
 import { SetterType, DynamicSetter } from './setter-config';
 import { SettingTarget } from './setting-target';
+import { LiveTextEditingConfig } from './metadata';
 
 export interface FieldExtraProps {
   /**
@@ -49,13 +50,8 @@ export interface FieldExtraProps {
    * compatiable vision display
    */
   display?: 'accordion' | 'inline' | 'block' | 'plain' | 'popup' | 'entry';
-  liveTextEditing?: {
+  // todo 这个 omit 是否合理？
-    selector: string;
+  liveTextEditing?: Omit<LiveTextEditingConfig, 'propTarget'>;
-    // 编辑模式 纯文本|段落编辑|文章编辑（默认纯文本，无跟随工具条）
-    mode?: 'plaintext' | 'paragraph' | 'article';
-    // 从 contentEditable 获取内容并设置到属性
-    onSaveContent?: (content: string, prop: any) => any;
-  };
 }
 
 export interface FieldConfig extends FieldExtraProps {

packages/types/src/metadata.ts

@@ -11,15 +11,25 @@ import { I18nData } from './i18n';
 
 export type NestingFilter = (testNode: any, currentNode: any) => boolean;
 export interface NestingRule {
-  // 子级白名单
+  /**
+   * 子级白名单
+   */
   childWhitelist?: string[] | string | RegExp | NestingFilter;
-  // 父级白名单
+  /**
+   * 父级白名单
+   */
   parentWhitelist?: string[] | string | RegExp | NestingFilter;
-  // 后裔白名单
+  /**
+   * 后裔白名单
+   */
   descendantWhitelist?: string[] | string | RegExp | NestingFilter;
-  // 后裔黑名单
+  /**
+   * 后裔黑名单
+   */
   descendantBlacklist?: string[] | string | RegExp | NestingFilter;
-  // 祖先白名单 可用来做区域高亮
+  /**
+   * 祖先白名单 可用来做区域高亮
+   */
   ancestorWhitelist?: string[] | string | RegExp | NestingFilter;
 }
 
@@ -33,15 +43,18 @@ export interface ComponentConfigure {
   isMinimalRenderUnit?: boolean;
 
   rootSelector?: string;
-  // copy, move, remove | *
+  /**
+   * copy, move, remove | *
+   */
   disableBehaviors?: string[] | string;
   actions?: ComponentAction[];
 }
 
 export interface Snippet {
-  screenshot: string;
+  title?: string;
-  label: string;
+  screenshot?: string;
-  schema: NodeSchema;
+  label?: string;
+  schema?: NodeSchema;
 }
 
 export interface InitialItem {
@@ -62,47 +75,65 @@ export interface Experimental {
   context?: { [contextInfoName: string]: any };
   snippets?: Snippet[];
   view?: ComponentType<any>;
-  transducers?: any; // ? should support
+  transducers?: any;
+  /**
+   * @deprecated
+   */
   initials?: InitialItem[];
   filters?: FilterItem[];
   autoruns?: AutorunItem[];
   callbacks?: Callbacks;
   initialChildren?: NodeData[] | ((target: SettingTarget) => NodeData[]);
-  isAbsoluteLayoutContainer: boolean;
+  isAbsoluteLayoutContainer?: boolean;
   hideSelectTools?: boolean;
 
-  // 样式 及 位置，handle上必须有明确的标识以便事件路由判断，或者主动设置事件独占模式
+  /**
-  // NWSE 是交给引擎计算放置位置，ReactElement 必须自己控制初始位置
+   * 样式 及 位置，handle上必须有明确的标识以便事件路由判断，或者主动设置事件独占模式
+   * NWSE 是交给引擎计算放置位置，ReactElement 必须自己控制初始位置
+   * - hover 时控制柄高亮
+   * - mousedown 时请求独占
+   * - dragstart 请求通用 resizing 控制 请求 hud 显示
+   * - drag 时 计算并设置效果，更新控制柄位置
+   */
   getResizingHandlers?: (
     currentNode: any,
-  ) =>
+  ) => (
     | Array<{
       type: 'N' | 'W' | 'S' | 'E' | 'NW' | 'NE' | 'SE' | 'SW';
       content?: ReactElement;
       propTarget?: string;
       appearOn?: 'mouse-enter' | 'mouse-hover' | 'selected' | 'always';
     }>
-  | ReactElement[];
+    | ReactElement[]
-  // hover时 控制柄高亮
+  );
-  // mousedown 时请求独占
-  // dragstart 请求 通用 resizing 控制
-  //           请求 hud 显示
-  // drag 时 计算 并 设置效果
-  //     更新控制柄位置
 
-  // 纯文本编辑：如果 children 内容是
+  /**
-  // 文本编辑：配置
+   * Live Text Editing：如果 children 内容是纯文本，支持双击直接编辑
+   */
   liveTextEditing?: LiveTextEditingConfig[];
   isTopFixed?: boolean;
 }
 
 // thinkof Array
+/**
+ * Live Text Editing（如果 children 内容是纯文本，支持双击直接编辑）的可配置项目
+ */
 export interface LiveTextEditingConfig {
+  /**
+   * 待补充文档
+   */
   propTarget: string;
+  /**
+   * 待补充文档
+   */
   selector?: string;
-  // 编辑模式 纯文本|段落编辑|文章编辑（默认纯文本，无跟随工具条）
+  /**
+   * 编辑模式 纯文本|段落编辑|文章编辑（默认纯文本，无跟随工具条）
+   */
   mode?: 'plaintext' | 'paragraph' | 'article';
-  // 从 contentEditable 获取内容并设置到属性
+  /**
+   * 从 contentEditable 获取内容并设置到属性
+   */
   onSaveContent?: (content: string, prop: any) => any;
 }
 
@@ -129,24 +160,41 @@ export interface Configure {
 }
 
 export interface ActionContentObject {
-  // 图标
+  /**
+   * 图标
+   */
   icon?: IconType;
-  // 描述
+  /**
+   * 描述
+   */
   title?: TipContent;
-  // 执行动作
+  /**
+   * 执行动作
+   */
   action?: (currentNode: any) => void;
 }
 
 export interface ComponentAction {
-  // behaviorName
+  /**
+   * behaviorName
+   */
   name: string;
-  // 菜单名称
+  /**
+   * 菜单名称
+   */
   content: string | ReactNode | ActionContentObject;
-  // 子集
+  /**
+   * 子集
+   */
   items?: ComponentAction[];
-  // 显示与否，always: 无法禁用
+  /**
+   * 显示与否
+   * always: 无法禁用
+   */
   condition?: boolean | ((currentNode: any) => boolean) | 'always';
-  // 显示在工具条上
+  /**
+   * 显示在工具条上
+   */
   important?: boolean;
 }
 
@@ -188,21 +236,32 @@ export interface TransformedComponentMetadata extends ComponentMetadata {
   configure: Configure & { combined?: FieldConfig[] };
 }
 
-// handleResizing
+/**
+ * handleResizing
+ */
 
-// hooks & events
+/**
+ * hooks & events
+ */
 export interface Callbacks {
-  // hooks
+  /**
+   * hooks
+   */
+
+
   onMouseDownHook?: (e: MouseEvent, currentNode: any) => any;
   onDblClickHook?: (e: MouseEvent, currentNode: any) => any;
   onClickHook?: (e: MouseEvent, currentNode: any) => any;
   // onLocateHook?: (e: any, currentNode: any) => any;
   // onAcceptHook?: (currentNode: any, locationData: any) => any;
-  onMoveHook?: (currentNode: any) => boolean; // thinkof 限制性拖拽
+  onMoveHook?: (currentNode: any) => boolean;
+  // thinkof 限制性拖拽
   onHoverHook?: (currentNode: any) => boolean;
   onChildMoveHook?: (childNode: any, currentNode: any) => boolean;
 
-  // events
+  /**
+   * events
+   */
   onNodeRemove?: (removedNode: any, currentNode: any) => void;
   onNodeAdd?: (addedNode: any, currentNode: any) => void;
   onSubtreeModified?: (currentNode: any, options: any) => void;

packages/types/src/schema.ts

@@ -11,20 +11,48 @@ import { I18nMap } from './i18n';
 import { UtilsMap } from './utils';
 import { AppConfig } from './app-config';
 
-// 搭建基础协议 - 单个组件树节点描述
 // 转换成一个 .jsx 文件内 React Class 类 render 函数返回的 jsx 代码
+/**
+ * 搭建基础协议 - 单个组件树节点描述
+ */
 export interface NodeSchema {
   id?: string;
-  componentName: string; // 组件名称 必填、首字母大写
+  /**
-  props?: PropsMap | PropsList; // 组件属性对象
+   * 组件名称 必填、首字母大写
+   */
+  componentName: string;
+  /**
+   * 组件属性对象
+   */
+  props?: PropsMap | PropsList;
+  /**
+   * 组件属性对象
+   */
   leadingComponents?: string;
-  condition?: CompositeValue; // 渲染条件
+  /**
-  loop?: CompositeValue; // 循环数据
+   * 渲染条件
-  loopArgs?: [string, string]; // 循环迭代对象、索引名称 ["item", "index"]
+   */
-  children?: NodeData | NodeData[]; // 子节点
+  condition?: CompositeValue;
-  isLocked?: boolean; // 是否锁定
+  /**
+   * 循环数据
+   */
+  loop?: CompositeValue;
+  /**
+   * 循环迭代对象、索引名称 ["item", "index"]
+   */
+  loopArgs?: [string, string];
+  /**
+   * 子节点
+   */
+  children?: NodeData | NodeData[];
+  /**
+   * 是否锁定
+   */
+  isLocked?: boolean;
 
-  // ------- future support -----
+  /**
+   * ------- future support -----
+   */
   conditionGroup?: string;
   title?: string;
   ignore?: boolean;
@@ -50,7 +78,10 @@ export function isDOMText(data: any): data is DOMText {
 export type DOMText = string;
 
 export interface ContainerSchema extends NodeSchema {
-  componentName: string; // 'Block' | 'Page' | 'Component';
+  /**
+   * 'Block' | 'Page' | 'Component';
+   */
+  componentName: string;
   fileName: string;
   meta?: Record<string, unknown>;
   state?: {

packages/types/src/setting-target.ts

@@ -31,31 +31,55 @@ export interface SettingTarget {
    */
   readonly top: SettingTarget;
 
-  // 父级
+  /**
+   * 父级
+   */
   readonly parent: SettingTarget;
 
 
-  // 获取当前值
+  /**
-  getValue(): any;
+   * 获取当前值
+   */
+  getValue: () => any;
 
-  // 设置当前值
+  /**
-  setValue(value: any): void;
+   * 设置当前值
+   */
+  setValue: (value: any) => void;
 
-  // 取得子项
+  /**
-  get(propName: string | number): SettingTarget | null;
+   * 取得子项
+   */
+  get: (propName: string | number) => SettingTarget | null;
 
-  // 获取子项属性值
+  /**
-  getPropValue(propName: string | number): any;
+   * 获取子项属性值
+   */
+  getPropValue: (propName: string | number) => any;
 
-  // 设置子项属性值
+  /**
-  setPropValue(propName: string | number, value: any): void;
+   * 设置子项属性值
+   */
+  setPropValue: (propName: string | number, value: any) => void;
 
-  // 清除已设置值
+  /**
-  clearPropValue(propName: string | number): void;
+   * 清除已设置值
+   */
+  clearPropValue: (propName: string | number) => void;
 
-  // 获取顶层附属属性值
+  /**
-  getExtraPropValue(propName: string): any;
+   * 获取顶层附属属性值
+   */
+  getExtraPropValue: (propName: string) => any;
 
-  // 设置顶层附属属性值
+  /**
-  setExtraPropValue(propName: string, value: any): void;
+   * 设置顶层附属属性值
+   */
+  setExtraPropValue: (propName: string, value: any) => void;
+
+  // todo 补充 node 定义
+  /**
+   * 获取 node 中的第一项
+   */
+  getNode: () => any;
 }

packages/types/src/value-type.ts

@@ -1,6 +1,8 @@
 import { NodeSchema, NodeData } from './schema';
 
-// 表达式
+/**
+ * 表达式
+ */
 export interface JSExpression {
   type: 'JSExpression';
   /**
@@ -15,7 +17,9 @@ export interface JSExpression {
   compiled?: string;
 }
 
-// 函数
+/**
+ * 函数
+ */
 export interface JSFunction {
   type: 'JSFunction';
   /**
@@ -40,7 +44,9 @@ export interface JSFunction {
   compiled?: string;
 }
 
-// 函数
+/**
+ * 函数
+ */
 export interface JSFunction {
   type: 'JSFunction';
   /**
@@ -60,7 +66,9 @@ export interface JSFunction {
 export interface JSSlot {
   type: 'JSSlot';
   title?: string;
-  // 函数的入参
+  /**
+   * 函数的入参
+   */
   params?: string[];
   value?: NodeData[] | NodeData;
   name?: string;
@@ -71,7 +79,9 @@ export interface JSBlock {
   value: NodeSchema;
 }
 
-// JSON 基本类型
+/**
+ * JSON 基本类型
+ */
 export type JSONValue =
   | boolean
   | string
@@ -85,7 +95,9 @@ export interface JSONObject {
   [key: string]: JSONValue;
 }
 
-// 复合类型
+/**
+ * 复合类型
+ */
 export type CompositeValue =
   | JSONValue
   | JSExpression