docs: 参照协议规范，完善所有 schema 和 asset 相关描述

packages/types/src/assets.ts

@@ -1,6 +1,7 @@
 import { NpmInfo } from './npm';
 import { PropConfig } from './prop-config';
 import { Snippet, ComponentMetadata } from './metadata';
+import { I18nData } from './i18n';
 
 /**
  * 定义组件大包及external资源的信息，应该被编辑器默认加载
@@ -27,7 +28,7 @@ export interface Package {
    */
   library: string;
   /**
-   * todo 待补充文档
+   * @todo 待补充文档
    */
   async?: boolean;
   /**
@@ -77,11 +78,13 @@ export interface ComponentItem {
   /**
    * 一级分组
    */
-  group?: string;
+  group?: string | I18nData;
+
   /**
    * 二级分组
    */
-  category?: string;
+  category?: string | I18nData;
+
   /**
    * 组件优先级排序
    */
@@ -93,7 +96,7 @@ export interface ComponentItem {
  */
 export interface ComponentDescription extends ComponentMetadata {
   /**
-   * todo 待补充文档
+   * @todo 待补充文档
    */
   keywords: string[];
 }

packages/types/src/field-config.ts

@@ -50,11 +50,20 @@ export interface FieldExtraProps {
    * compatiable vision display
    */
   display?: 'accordion' | 'inline' | 'block' | 'plain' | 'popup' | 'entry';
-  // todo 这个 omit 是否合理？
+  // @todo 这个 omit 是否合理？
+  /**
+   * @todo 待补充文档
+   */
   liveTextEditing?: Omit<LiveTextEditingConfig, 'propTarget'>;
 }
 
+/**
+ * 属性面板配置
+ */
 export interface FieldConfig extends FieldExtraProps {
+  /**
+   * @todo 待补充文档
+   */
   type?: 'field' | 'group';
   /**
    * the name of this setting field, which used in quickEditor
@@ -78,11 +87,11 @@ export interface FieldConfig extends FieldExtraProps {
    */
   extraProps?: FieldExtraProps;
   /**
-   * todo 待补充文档
+   * @todo 待补充文档
    */
   description?: TitleContent;
   /**
-   * todo 待补充文档
+   * @todo 待补充文档
    */
   isExtends?: boolean;
 }

packages/types/src/metadata.ts

@@ -9,7 +9,14 @@ import { NodeSchema, NodeData, ComponentSchema } from './schema';
 import { SettingTarget } from './setting-target';
 import { I18nData } from './i18n';
 
+/**
+ * 嵌套控制函数
+ */
 export type NestingFilter = (testNode: any, currentNode: any) => boolean;
+/**
+ * 嵌套控制
+ * 防止错误的节点嵌套，比如 a 嵌套 a, FormField 只能在 Form 容器下，Column 只能在 Table 下等
+ */
 export interface NestingRule {
   /**
    * 子级白名单
@@ -33,26 +40,64 @@ export interface NestingRule {
   ancestorWhitelist?: string[] | string | RegExp | NestingFilter;
 }
 
+/**
+ * 组件能力配置
+ */
 export interface ComponentConfigure {
+  /**
+   * 是否容器组件
+   */
   isContainer?: boolean;
+  /**
+   * 组件是否带浮层，浮层组件拖入设计器时会遮挡画布区域，此时应当辅助一些交互以防止阻挡
+   */
   isModal?: boolean;
+  /**
+   * 是否存在渲染的根节点
+   */
   isNullNode?: boolean;
+  /**
+   * 组件树描述信息
+   */
   descriptor?: string;
+  /**
+   * 嵌套控制：防止错误的节点嵌套
+   * 比如 a 嵌套 a, FormField 只能在 Form 容器下，Column 只能在 Table 下等
+   */
   nestingRule?: NestingRule;
 
+  /**
+   * 是否是最小渲染单元
+   * 最小渲染单元下的组件渲染和更新都从单元的根节点开始渲染和更新。如果嵌套了多层最小渲染单元，渲染会从最外层的最小渲染单元开始渲染。
+   */
   isMinimalRenderUnit?: boolean;
 
+  /**
+   * 组件选中框的 cssSelector
+   */
   rootSelector?: string;
   /**
-   * copy, move, remove | *
+   * 禁用的行为，可以为 `'copy'`, `'move'`, `'remove'` 或它们组成的数组
    */
   disableBehaviors?: string[] | string;
+  /**
+   * 用于详细配置上述操作项的内容
+   */
   actions?: ComponentAction[];
 }
 
 export interface Snippet {
+  /**
+   * 组件分类title
+   */
   title?: string;
+  /**
+   * snippet 截图
+   */
   screenshot?: string;
+  /**
+   * @todo snippet 打标
+   */
   label?: string;
   schema?: NodeSchema;
 }
@@ -70,26 +115,61 @@ export interface AutorunItem {
   autorun: (target: SettingTarget) => any;
 }
 
-
+/**
+ * 试验特性配置
+ */
 export interface Experimental {
+  /**
+   * @todo 待补充文档
+   */
   context?: { [contextInfoName: string]: any };
+  /**
+   * @todo 待补充文档
+   */
   snippets?: Snippet[];
+  /**
+   * @todo 待补充文档
+   */
   view?: ComponentType<any>;
+  /**
+   * @todo 待补充文档
+   */
   transducers?: any;
   /**
-   * @deprecated
+   * @deprecated 用于动态初始化拖拽到设计器里的组件的 prop 的值
    */
   initials?: InitialItem[];
+  /**
+   * @todo 待补充文档
+   */
   filters?: FilterItem[];
+  /**
+   * @todo 待补充文档
+   */
   autoruns?: AutorunItem[];
+  /**
+   * 配置 callbacks 可捕获引擎抛出的一些事件，例如 onNodeAdd、onResize 等
+   */
   callbacks?: Callbacks;
+  /**
+   * @todo 待补充文档
+   */
   initialChildren?: NodeData[] | ((target: SettingTarget) => NodeData[]);
+  /**
+   * @todo 待补充文档
+   */
   isAbsoluteLayoutContainer?: boolean;
+  /**
+   * @todo 待补充文档
+   */
   hideSelectTools?: boolean;
 
   /**
    * 样式 及 位置，handle上必须有明确的标识以便事件路由判断，或者主动设置事件独占模式
    * NWSE 是交给引擎计算放置位置，ReactElement 必须自己控制初始位置
+   */
+  /**
+   * 用于配置设计器中组件 resize 操作工具的样式和内容
    * - hover 时控制柄高亮
    * - mousedown 时请求独占
    * - dragstart 请求通用 resizing 控制 请求 hud 显示
@@ -111,6 +191,10 @@ export interface Experimental {
    * Live Text Editing：如果 children 内容是纯文本，支持双击直接编辑
    */
   liveTextEditing?: LiveTextEditingConfig[];
+
+  /**
+   * @todo 待补充文档
+   */
   isTopFixed?: boolean;
 }
 
@@ -120,11 +204,11 @@ export interface Experimental {
  */
 export interface LiveTextEditingConfig {
   /**
-   * todo 待补充文档
+   * @todo 待补充文档
    */
   propTarget: string;
   /**
-   * todo 待补充文档
+   * @todo 待补充文档
    */
   selector?: string;
   /**
@@ -144,22 +228,58 @@ export type ConfigureSupportEvent = string | {
   description?: string;
 };
 
-export type ConfigureSupport = {
+/**
+ * 通用扩展面板支持性配置
+ */
+export interface ConfigureSupport {
+  /**
+   * 支持事件列表
+   */
   events?: ConfigureSupportEvent[];
+  /**
+   * 支持 className 设置
+   */
   className?: boolean;
+  /**
+   * 支持样式设置
+   */
   style?: boolean;
+  /**
+   * 支持生命周期设置
+   */
   lifecycles?: any[];
   // general?: boolean;
+  /**
+   * 支持循环设置
+   */
   loop?: boolean;
+  /**
+   * 支持条件式渲染设置
+   */
   condition?: boolean;
-};
+}
 
+/**
+ * 编辑体验配置
+ */
 export interface Configure {
+  /**
+   * 属性面板配置
+   */
   props?: FieldConfig[];
+  /**
+   * 组件能力配置
+   */
   component?: ComponentConfigure;
+  /**
+   * 通用扩展面板支持性配置
+   */
   supports?: ConfigureSupport;
 }
 
+/**
+ * 动作描述
+ */
 export interface ActionContentObject {
   /**
    * 图标
@@ -175,6 +295,9 @@ export interface ActionContentObject {
   action?: (currentNode: any) => void;
 }
 
+/**
+ * @todo 工具条动作
+ */
 export interface ComponentAction {
   /**
    * behaviorName
@@ -203,7 +326,13 @@ export function isActionContentObject(obj: any): obj is ActionContentObject {
   return obj && typeof obj === 'object';
 }
 
+/**
+ * 组件 meta 配置
+ */
 export interface ComponentMetadata {
+  /**
+   * 组件名
+   */
   componentName: string;
   /**
    * unique id
@@ -217,22 +346,67 @@ export interface ComponentMetadata {
    * svg icon for component
    */
   icon?: IconType;
+  /**
+   * 组件标签
+   */
   tags?: string[];
+  /**
+   * 组件描述
+   */
   description?: string;
+  /**
+   * 组件文档链接
+   */
   docUrl?: string;
+  /**
+   * 组件快照
+   */
   screenshot?: string;
+  /**
+   * 组件研发模式
+   */
   devMode?: 'procode' | 'lowcode';
+  /**
+   * npm 源引入完整描述对象
+   */
   npm?: NpmInfo;
+  /**
+   * 组件属性信息
+   */
   props?: PropConfig[];
+  /**
+   * 编辑体验增强
+   */
   configure?: FieldConfig[] | Configure;
+  /**
+   * 试验特性配置
+   */
   experimental?: Experimental;
+  /**
+   * @todo 待补充文档
+   */
   schema?: ComponentSchema;
+  /**
+   * 可用片段
+   */
   snippets?: Snippet[];
+  /**
+   * 一级分组
+   */
   group?: string | I18nData;
+  /**
+   * 二级分组
+   */
   category?: string | I18nData;
+  /**
+   * 组件优先级排序
+   */
   priority?: number;
 }
 
+/**
+ * @todo 待补充文档
+ */
 export interface TransformedComponentMetadata extends ComponentMetadata {
   configure: Configure & { combined?: FieldConfig[] };
 }
@@ -242,12 +416,10 @@ export interface TransformedComponentMetadata extends ComponentMetadata {
  */
 
 /**
- * hooks & events
+ * 配置 callbacks 可捕获引擎抛出的一些事件，例如 onNodeAdd、onResize 等
  */
 export interface Callbacks {
-  /**
+  // hooks
-   * hooks
-   */
   onMouseDownHook?: (e: MouseEvent, currentNode: any) => any;
   onDblClickHook?: (e: MouseEvent, currentNode: any) => any;
   onClickHook?: (e: MouseEvent, currentNode: any) => any;
@@ -258,9 +430,7 @@ export interface Callbacks {
   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/npm.ts

@@ -1,10 +1,34 @@
+/**
+ * npm 源引入完整描述对象
+ */
 export interface NpmInfo {
+  /**
+   * 源码组件名称
+   */
   componentName?: string;
+  /**
+   * 源码组件库名
+   */
   package: string;
+  /**
+   * 源码组件版本号
+   */
   version?: string;
+  /**
+   * 是否解构
+   */
   destructuring?: boolean;
+  /**
+   * 源码组件名称
+   */
   exportName?: string;
+  /**
+   * 子组件名
+   */
   subName?: string;
+  /**
+   * 组件路径
+   */
   main?: string;
 }
 

packages/types/src/prop-config.ts

@@ -38,10 +38,28 @@ export interface Exact {
   isRequired?: boolean;
 }
 
+/**
+ * 组件属性信息
+ */
 export interface PropConfig {
+  /**
+   * 属性名称
+   */
   name: string;
+  /**
+   * 属性类型
+   */
   propType: PropType;
+  /**
+   * 属性描述
+   */
   description?: string;
+  /**
+   * 属性默认值
+   */
   defaultValue?: any;
+  /**
+   * @todo 待补充文档
+   */
   setter?: any;
 }

packages/types/src/schema.ts

@@ -12,6 +12,7 @@ import { UtilsMap } from './utils';
 import { AppConfig } from './app-config';
 
 // 转换成一个 .jsx 文件内 React Class 类 render 函数返回的 jsx 代码
+
 /**
  * 搭建基础协议 - 单个组件树节点描述
  */
@@ -50,9 +51,7 @@ export interface NodeSchema {
    */
   isLocked?: boolean;
 
-  /**
+  // ------- future support -----
-   * ------- future support -----
-   */
   conditionGroup?: string;
   title?: string;
   ignore?: boolean;
@@ -77,25 +76,53 @@ export function isDOMText(data: any): data is DOMText {
 
 export type DOMText = string;
 
+/**
+ * 容器结构描述
+ */
 export interface ContainerSchema extends NodeSchema {
   /**
    * 'Block' | 'Page' | 'Component';
    */
   componentName: string;
+  /**
+   * 文件名称
+   */
   fileName: string;
+  /**
+   * @todo 待文档定义
+   */
   meta?: Record<string, unknown>;
+  /**
+   * 容器初始数据
+   */
   state?: {
     [key: string]: CompositeValue;
   };
+  /**
+   * 自定义方法设置
+   */
   methods?: {
     [key: string]: JSExpression | JSFunction;
   };
+  /**
+   * 生命周期对象
+   */
   lifeCycles?: {
     [key: string]: JSExpression | JSFunction;
   };
+  /**
+   * 样式文件
+   */
   css?: string;
+  /**
+   * 异步数据源配置
+   */
   dataSource?: DataSource;
+  /**
+   * 低代码业务组件默认属性
+   */
   defaultProps?: CompositeObject;
+  // @todo propDefinitions
 }
 
 /**
@@ -122,25 +149,69 @@ export interface BlockSchema extends ContainerSchema {
   componentName: 'Block';
 }
 
+/**
+ * @todo
+ */
 export type RootSchema = PageSchema | ComponentSchema | BlockSchema;
 
+/**
+ * Slot schema 描述
+ */
 export interface SlotSchema extends NodeSchema {
   componentName: 'Slot';
   name?: string;
   params?: string[];
 }
 
+/**
+ * 应用描述
+ */
 export interface ProjectSchema {
+  /**
+   * 当前应用协议版本号
+   */
   version: string;
+  /**
+   * 当前应用所有组件映射关系
+   */
   componentsMap: ComponentsMap;
+  /**
+   * 描述应用所有页面、低代码组件的组件树
+   * 低代码业务组件树描述
+   * 是长度固定为1的数组, 即数组内仅包含根容器的描述（低代码业务组件容器类型）
+   */
   componentsTree: RootSchema[];
+  /**
+   * 国际化语料
+   */
   i18n?: I18nMap;
+  /**
+   * 应用范围内的全局自定义函数或第三方工具类扩展
+   */
   utils?: UtilsMap;
+  /**
+   * @todo 待文档定义
+   */
   constants?: JSONObject;
+  /**
+   * 应用范围内的全局样式
+   */
   css?: string;
+  /**
+   * 当前应用的公共数据源
+   */
   dataSource?: DataSource;
+  /**
+   * 当前应用配置信息
+   */
   config?: AppConfig | Record<string, any>;
+  /**
+   * @todo 待补充文档
+   */
   id?: string;
+  /**
+   * 当前应用元数据信息
+   */
   meta?: Record<string, any>;
 }
 

packages/types/src/setting-target.ts

@@ -77,7 +77,7 @@ export interface SettingTarget {
    */
   setExtraPropValue: (propName: string, value: any) => void;
 
-  // todo 补充 node 定义
+  // @todo 补充 node 定义
   /**
    * 获取 node 中的第一项
    */

packages/types/src/value-type.ts

@@ -17,24 +17,12 @@ export interface JSExpression {
   compiled?: string;
 }
 
-/**
- * 函数
- */
-export interface JSFunction {
-  type: 'JSFunction';
-  /**
-   * 表达式字符串
-   */
-  value: string;
-}
-
 /**
  * 事件函数类型
  * @see https://yuque.antfin-inc.com/mo/spec/spec-low-code-building-schema#feHTW
  */
 export interface JSFunction {
   type: 'JSFunction';
-
   /**
    * 函数定义，或直接函数表达式
    */
@@ -42,27 +30,21 @@ export interface JSFunction {
 
   /** 源码 */
   compiled?: string;
-}
 
-/**
- * 函数
- */
-export interface JSFunction {
-  type: 'JSFunction';
-  /**
-   * 函数字符串
-   */
-  value: string;
   /**
    * 模拟值
    */
   mock?: any;
+
   /**
    * 额外扩展属性，如 extType、events
    */
   [key: string]: any;
 }
 
+/**
+ * Slot 函数类型
+ */
 export interface JSSlot {
   type: 'JSSlot';
   title?: string;
@@ -74,6 +56,9 @@ export interface JSSlot {
   name?: string;
 }
 
+/**
+ * @todo 待文档描述
+ */
 export interface JSBlock {
   type: 'JSBlock';
   value: NodeSchema;