docs: 针对标准补完 value-type 和 seter-config 的类型

packages/editor-skeleton/src/types.ts

@@ -18,9 +18,9 @@ export interface IWidgetBaseConfig {
   name: string;
   /**
    * 停靠位置：
-   * 当 type 为 'Panel' 时自动为 'leftFloatArea'；
-   * 当 type 为 'Widget' 时自动为 'mainArea'；
-   * 其他时候自动为 'leftArea'；
+   * - 当 type 为 'Panel' 时自动为 'leftFloatArea'；
+   * - 当 type 为 'Widget' 时自动为 'mainArea'；
+   * - 其他时候自动为 'leftArea'；
    */
   area?: IWidgetConfigArea;
   props?: Record<string, any>;

packages/types/src/assets.ts

@@ -27,7 +27,7 @@ export interface Package {
    */
   library: string;
   /**
-   * @todo 待补充文档
+   * @todo 待补充文档 @jinchan
    */
   async?: boolean;
   /**
@@ -97,7 +97,7 @@ export interface ComponentItem {
  */
 export interface ComponentDescription extends ComponentMetadata {
   /**
-   * @todo 待补充文档
+   * @todo 待补充文档 @jinchan
    */
   keywords: string[];
 }

packages/types/src/field-config.ts

@@ -68,7 +68,7 @@ export interface FieldExtraProps {
  */
 export interface FieldConfig extends FieldExtraProps {
   /**
-   * @todo 待补充文档
+   * 面板配置隶属于单个 field 还是分组
    */
   type?: 'field' | 'group';
   /**
@@ -81,6 +81,8 @@ export interface FieldConfig extends FieldExtraProps {
    */
   title?: TitleContent;
   /**
+   * 单个属性的 setter 配置
+   *
    * the field body contains when .type = 'field'
    */
   setter?: SetterType | DynamicSetter;

packages/types/src/metadata.ts

@@ -86,6 +86,11 @@ export interface ComponentConfigure {
   actions?: ComponentAction[];
 }
 
+/**
+ * 可用片段
+ *
+ * 内容为组件不同状态下的低代码 schema (可以有多个)，用户从组件面板拖入组件到设计器时会向页面 schema 中插入 snippets 中定义的组件低代码 schema
+ */
 export interface Snippet {
   /**
    * 组件分类title
@@ -99,6 +104,9 @@ export interface Snippet {
    * @todo snippet 打标
    */
   label?: string;
+  /**
+   * @todo 待补充文档
+   */
   schema?: NodeSchema;
 }
 

packages/types/src/setter-config.ts

@@ -1,6 +1,7 @@
 import { ComponentClass, Component, ComponentType, ReactElement, isValidElement } from 'react';
 import { TitleContent } from './title';
 import { SettingTarget } from './setting-target';
+import { CompositeValue } from './value-type';
 
 function isReactClass(obj: any): obj is ComponentClass<any> {
   return obj && obj.prototype && (obj.prototype.isReactComponent || obj.prototype instanceof Component);
@@ -21,18 +22,48 @@ export type DynamicSetter = (target: SettingTarget) => string | SetterConfig | C
  */
 export interface SetterConfig {
   // if *string* passed must be a registered Setter Name
+  /**
+   * 配置设置器用哪一个 setter
+   */
   componentName: string | CustomView;
   /**
+   * 传递给 setter 的属性
+   *
    * the props pass to Setter Component
    */
   props?: Record<string, unknown> | DynamicProps;
+  /**
+   * @deprecated
+   */
   children?: any;
+  /**
+   * 是否必填？
+   *
+   * ArraySetter 里有个快捷预览，可以在不打开面板的情况下直接编辑
+   */
   isRequired?: boolean;
+  /**
+   * Setter 的初始值
+   *
+   * @todo initialValue 可能要和 defaultValue 二选一
+   */
   initialValue?: any | ((target: SettingTarget) => any);
   // for MixedSetter
+  /**
+   * 给 MixedSetter 时切换 Setter 展示用的
+   */
   title?: TitleContent;
   // for MixedSetter check this is available
+  /**
+   * 给 MixedSetter 用于判断优先选中哪个
+   */
   condition?: (target: SettingTarget) => boolean;
+  /**
+   * 给 MixedSetter，切换值时声明类型
+   *
+   * @todo 物料协议推进
+   */
+  valueType?: CompositeValue[];
 }
 
 // if *string* passed must be a registered Setter Name, future support blockSchema

packages/types/src/value-type.ts

@@ -1,7 +1,9 @@
 import { NodeSchema, NodeData } from './schema';
 
 /**
- * 表达式
+ * 变量表达式
+ *
+ * 表达式内通过 this 对象获取上下文
  */
 export interface JSExpression {
   type: 'JSExpression';
@@ -11,10 +13,14 @@ export interface JSExpression {
   value: string;
   /**
    * 模拟值
+   *
+   * @todo 待标准描述
    */
   mock?: any;
   /**
    * 源码
+   *
+   * @todo 待标准描述
    */
   compiled?: string;
 }
@@ -22,6 +28,8 @@ export interface JSExpression {
 /**
  * 事件函数类型
  * @see https://yuque.antfin-inc.com/mo/spec/spec-low-code-building-schema#feHTW
+ *
+ * 保留与原组件属性、生命周期( React / 小程序)一致的输入参数，并给所有事件函数 binding 统一一致的上下文（当前组件所在容器结构的 this 对象）
  */
 export interface JSFunction {
   type: 'JSFunction';
@@ -30,35 +38,58 @@ export interface JSFunction {
    */
   value: string;
 
-  /** 源码 */
+  /**
+   * 源码
+   *
+   * @todo 待标准描述
+   */
   compiled?: string;
 
   /**
    * 模拟值
+   *
+   * @todo 待标准描述
    */
   mock?: any;
 
   /**
    * 额外扩展属性，如 extType、events
+   *
+   * @todo 待标准描述
    */
   [key: string]: any;
 }
 
 /**
  * Slot 函数类型
+ *
+ * 通常用于描述组件的某一个属性为 ReactNode 或 Function return ReactNode 的场景。
  */
 export interface JSSlot {
   type: 'JSSlot';
+  /**
+   * @todo 待标准描述
+   */
   title?: string;
   /**
-   * 函数的入参
+   * 组件的某一个属性为 Function return ReactNode 时，函数的入参
+   *
+   * 其子节点可以通过this[参数名] 来获取对应的参数。
    */
   params?: string[];
+  /**
+   * 具体的值。
+   */
   value?: NodeData[] | NodeData;
+  /**
+   * @todo 待标准描述
+   */
   name?: string;
 }
 
 /**
+ * @deprecated
+ *
  * @todo 待文档描述
  */
 export interface JSBlock {