@neeloong/form 0.10.0 → 0.12.0

package/README.md

@@ -14,7 +14,7 @@ const template = `
 	<li !value="list" !enum>
 		<input !bind="b" />
 		<ul !value="c" +x="0">
-			<li !enum +b=alias$length +a=2 +k="++x">
+			<li !enum +b=alias$size +a=2 +k="++x">
 				<div !fragment !text="k"></div>
 				<button @click="a+=1">a+1:<span !fragment !text="a"></span></button>
 				<button @click="b+=1">b+1:<span !fragment !text="b"></span></button>
@@ -24,7 +24,7 @@ const template = `
 				<button @click="$upMove" :disabled="!$upMovable">上移</button>
 				<button @click="$downMove()" :disabled="!$downMovable">下移</button>
 			</li>
-			<li><button @click="$add(0)">添加</button><button @click="$add( - $length - 1)">添加(<span !fragment !text=" - $length - 1"></span>)</button></li>
+			<li><button @click="$add(0)">添加</button><button @click="$add( - $size - 1)">添加(<span !fragment !text=" - $size - 1"></span>)</button></li>
 		</ul>
 	</li>
 </ul>
@@ -127,7 +127,7 @@ render(store, layouts, app);
 - **别名（`*alias`）**：  
   为复杂表达式或字段设置别名，简化引用。  
   ```html
-  <div *len="array$length" !text="len"></div> <!-- 别名 len 指向当前数组长度 -->
+  <div *len="array$size" !text="len"></div> <!-- 别名 len 指向当前数组长度 -->
   ```
 
 - **计算值（`*computed`）**：  
@@ -144,8 +144,7 @@ render(store, layouts, app);
 
 #### **2.2 变量优先级**
 变量优先级从高到低：  
-1. **显式变量（`+var`）**  
-2. **别名（`*alias`）**  
+1. **显式变量（`+var`）与别名（`*alias`）**  
 3. **计算值（`*computed`）**  
 4. **字段变量（`field$value`）**  
 5. **全局变量（通过 `render` 的 `global` 参数传入）**  
@@ -180,9 +179,9 @@ render(store, layouts, app);
 #### 嵌套循环
 
 ```html
-<div !enum="outerArray" *outerLen="$length">
+<div !enum="outerArray" *outerLen="$size">
   <div !enum="innerArray">
-    <span !text="outerLen + ' + ' + $length"></span> <!-- 外层长度 + 内层长度 -->
+    <span !text="outerLen + ' + ' + $size"></span> <!-- 外层长度 + 内层长度 -->
   </div>
 </div>
 ```
@@ -286,8 +285,7 @@ render(store, layouts, app);
 1. 条件: `!if` `!else`
 1. 子属性: `!value`
 1. 枚举: `!enum`
-1. 别名与计算名: `*别名` `*计算名`
-1. 显式变量: `+变量`
+1. 别名、计算名与显式变量: `*别名` `*计算名` `+变量`
 1. 片段与模板调用: `!fragment` 
 1. 属性与事件: `:绑定属性` `@事件` `普通属性` `!bind`
 1. 子内容: `!text` `!html`
@@ -302,7 +300,7 @@ render(store, layouts, app);
    - `$null` 只读 是否为空元素
    - `$index` 只读 当前项的索引
    - `$no` 只读 数组项目的序号
-   - `$length` 只读 数组的长度、对象的成员数
+   - `$size` 只读 数组的长度、对象的成员数
    - `$creatable` 只读 值是否可创建（`$new` 为 `true` 时，字段只读）
    - `$immutable` 只读 值是否不可改变（`$new` 为 `false` 时，字段只读）
    - `$new` 只读 是否新建项
@@ -345,8 +343,13 @@ render(store, layouts, app);
    - `$upMove()` 上移当前项
    - `$downMove()` 下移当前项
 1. 上下文隐式变量
-   - '$store' 只读 当前表单存储实例。
-   - '$root' 只读 根上下文对象。
+   - `$store` 只读 当前表单存储实例。
+   - `$root` 只读 根上下文对象。
+1. `enum` 上下文新增的变量
+   - `$$count` 枚举上下文的数量
+   - `$$key` 枚举上下文的当前项的键
+   - `$$index` 枚举上下文当前项的索引
+   - `$$item` 枚举上下文当前项
 1. 当前范围及组件范围的所有字段（数组字段的成员除外，因为数组字段成员索引为数字，不符合标识符命名规则）都存在 `field$value` 及 `field$$value` 形式的变量
 1. 如果别名为字段的别名（如 `*alias="v"`），则也存在 `alias$value` 形式的变量
 1. 当存在同名变量时，则会按照变量来源类型决定优先级，从高到低依次为：
@@ -355,7 +358,6 @@ render(store, layouts, app);
    1. 全局变量，此部分由 `render` 的参数传入
    1. 字段声明，包括 `field$value` 及 `field$$value` 形式的变量
 1. 在同一来源类型重复的变量名，再按照作用域处理
-1. 同一作用域下的别名（或计算名）与显式变量重名时，由于会先处理别名，所以，显式变量会覆盖别名。
 
 ### 示例代码
 

package/index.d.mts

@@ -1,5 +1,5 @@
 /*!
-* @neeloong/form v0.10.0
+* @neeloong/form v0.12.0
 * (c) 2024-2025 Fierflame
 * @license Apache-2.0
 */
@@ -11,17 +11,9 @@ export { Signal } from 'signal-polyfill';
  * 解析模板内容
  * @param {string} source 输入源字符串
  * @param {Layout.Options} [options] 解析选项
- * @returns {(Layout.Node | string)[]}
+ * @returns {Layout.Child[]}
  */
-declare function parse(source: string, { createCalc, createInit, createEvent, simpleTag, enableHTML, }?: Options): (Node | string)[];
-
-/**
- * 将模板转为字符串
- * @param {Layout.Node | (Layout.Node |string)[]} value 要转换的节点或节点数组
- * @param {boolean} [formable] 是否对代码进行格式化
- * @returns {string}
- */
-declare function stringify(value: Node | (Node | string)[], formable?: boolean): string;
+declare function parse(source: string, { createCalc, createInit, createEvent, simpleTag, enableHTML, }?: Options): Child[];
 
 /**
  * 增强信息
@@ -73,6 +65,12 @@ type Options = {
  * 布局节点
  */
 type Node = {
+    /**
+     * 局部变量/别名/计算名
+     */
+    vars?: Variable<unknown>[] | null | undefined;
+    templates?: Record<string, Template> | undefined;
+    type?: null | undefined;
     /**
      * 标签名
      */
@@ -83,10 +81,6 @@ type Node = {
      * 属性
      */
     attrs: Record<string, Node.Name | Node.Calc | Node.Value>;
-    /**
-     * 模板参数定义
-     */
-    params: Record<string, Node.Name | Node.Calc | Node.Value>;
     /**
      * 类名
      */
@@ -99,54 +93,14 @@ type Node = {
      * 事件
      */
     events: Record<string, Node.Name | Node.Event>;
-    /**
-     * 局部变量
-     */
-    vars: Record<string, Node.Name | Node.Calc | Node.Value>;
-    /**
-     * 别名/计算名
-     */
-    aliases: Record<string, Node.Name | Node.Calc | Node.Value>;
     /**
      * 增强
      */
     enhancements: Record<string, Enhancement$1>;
-    /**
-     * 模板定义的名称
-     */
-    template?: string | undefined;
-    /**
-     * 是否为片段或模板调用
-     */
-    fragment?: string | boolean | undefined;
-    /**
-     * 分歧条件
-     */
-    if?: Node.Name | Node.Calc | Node.Value<any> | undefined;
-    /**
-     * 否定
-     */
-    else?: boolean | undefined;
-    /**
-     * 值关联
-     */
-    value?: string | undefined;
-    /**
-     * 列表属性枚举
-     */
-    enum?: Node.Name | Node.Calc | Node.Value<any> | undefined;
     /**
      * 绑定内容
      */
     bind?: string | boolean | undefined;
-    /**
-     * 文本渲染
-     */
-    text?: Node.Name | Node.Calc | Node.Value<any> | undefined;
-    /**
-     * HTML 渲染
-     */
-    html?: Node.Name | Node.Calc | Node.Value<any> | undefined;
     /**
      * 注释
      */
@@ -154,7 +108,7 @@ type Node = {
     /**
      * 子元素
      */
-    children: (Node | string)[];
+    children: Child[];
 };
 declare namespace Node {
     /**
@@ -194,6 +148,187 @@ declare namespace Node {
         event?: undefined;
     };
 }
+/**
+ * 分歧
+ */
+type Child = Divergent | Select | Enum | Content | CallTemplate | Fragment | Node | string;
+/**
+ * 变量定义
+ */
+type Variable<T = unknown> = {
+    variable: string;
+    name?: string | undefined;
+    calc?: Calc | undefined;
+    value?: T | undefined;
+    /**
+     * 是否普通变量
+     */
+    init?: boolean | undefined;
+    /**
+     * 注释
+     */
+    comment?: string | undefined;
+};
+type Template = {
+    /**
+     * 局部变量/别名/计算名
+     */
+    vars?: Variable<unknown>[] | null | undefined;
+    templates?: Record<string, Template> | undefined;
+    /**
+     * 模板参数定义
+     */
+    params: Record<string, Node.Name | Node.Calc | Node.Value>;
+    /**
+     * 子元素
+     */
+    children: Child[];
+    /**
+     * 注释
+     */
+    comment?: string | undefined;
+};
+/**
+ * 分歧项
+ */
+type DivergentChildren = {
+    /**
+     * 局部变量/别名/计算名
+     */
+    vars?: Variable<unknown>[] | null | undefined;
+    templates?: Record<string, Template> | undefined;
+    /**
+     * 子元素
+     */
+    children: Child[];
+    /**
+     * 注释
+     */
+    comment?: string | undefined;
+};
+/**
+ * 分歧
+ */
+type Divergent = {
+    /**
+     * 局部变量/别名/计算名
+     */
+    vars?: Variable<unknown>[] | null | undefined;
+    templates?: Record<string, Template> | undefined;
+    type: "divergent";
+    children: [children: DivergentChildren, condition?: Node.Name | Node.Calc | Node.Value | null][];
+    /**
+     * 注释
+     */
+    comment?: string | undefined;
+};
+/**
+ * 选值
+ */
+type Select = {
+    /**
+     * 局部变量/别名/计算名
+     */
+    vars?: Variable<unknown>[] | null | undefined;
+    templates?: Record<string, Template> | undefined;
+    type: "value";
+    name: string;
+    /**
+     * 子元素
+     */
+    children: Child[];
+    /**
+     * 注释
+     */
+    comment?: string | undefined;
+};
+/**
+ * 枚举
+ */
+type Enum = {
+    /**
+     * 局部变量/别名/计算名
+     */
+    vars?: Variable<unknown>[] | null | undefined;
+    templates?: Record<string, Template> | undefined;
+    type: "enum";
+    value: Node.Name | Node.Calc | Node.Value;
+    /**
+     * 子元素
+     */
+    children: Child[];
+    /**
+     * 注释
+     */
+    comment?: string | undefined;
+};
+/**
+ * 内容填充
+ */
+type Content = {
+    /**
+     * 局部变量/别名/计算名
+     */
+    vars?: Variable<unknown>[] | null | undefined;
+    templates?: Record<string, Template> | undefined;
+    type: "content";
+    value: Node.Name | Node.Calc | Node.Value;
+    html?: boolean | undefined;
+    /**
+     * 注释
+     */
+    comment?: string | undefined;
+};
+/**
+ * 模板调用
+ */
+type CallTemplate = {
+    /**
+     * 局部变量/别名/计算名
+     */
+    vars?: Variable<unknown>[] | null | undefined;
+    templates?: Record<string, Template> | undefined;
+    type: "template";
+    /**
+     * 模板名
+     */
+    template: string;
+    /**
+     * 属性
+     */
+    attrs: Record<string, Node.Name | Node.Calc | Node.Value>;
+    /**
+     * 绑定内容
+     */
+    bind?: string | boolean | undefined;
+    /**
+     * 子元素
+     */
+    children: Child[];
+    /**
+     * 注释
+     */
+    comment?: string | undefined;
+};
+/**
+ * 片段
+ */
+type Fragment = {
+    /**
+     * 局部变量/别名/计算名
+     */
+    vars?: Variable<unknown>[] | null | undefined;
+    templates?: Record<string, Template> | undefined;
+    type: "fragment";
+    /**
+     * 子元素
+     */
+    children: Child[];
+    /**
+     * 注释
+     */
+    comment?: string | undefined;
+};
 /**
  * 计算函数
  */
@@ -204,13 +339,22 @@ type Calc = (env: Record<string, any>) => any;
 type EventListener = ($event: any, env: Record<string, any>) => void;
 
 type index_d_Calc = Calc;
+type index_d_CallTemplate = CallTemplate;
+type index_d_Child = Child;
+type index_d_Content = Content;
+type index_d_Divergent = Divergent;
+type index_d_DivergentChildren = DivergentChildren;
+type index_d_Enum = Enum;
 type index_d_EventListener = EventListener;
+type index_d_Fragment = Fragment;
 declare const index_d_Node: typeof Node;
 type index_d_Options = Options;
+type index_d_Select = Select;
+type index_d_Template = Template;
+type index_d_Variable<T = unknown> = Variable<T>;
 declare const index_d_parse: typeof parse;
-declare const index_d_stringify: typeof stringify;
 declare namespace index_d {
-  export { type index_d_Calc as Calc, type Enhancement$1 as Enhancement, type index_d_EventListener as EventListener, index_d_Node as Node, type index_d_Options as Options, index_d_parse as parse, index_d_stringify as stringify };
+  export { type index_d_Calc as Calc, type index_d_CallTemplate as CallTemplate, type index_d_Child as Child, type index_d_Content as Content, type index_d_Divergent as Divergent, type index_d_DivergentChildren as DivergentChildren, type Enhancement$1 as Enhancement, type index_d_Enum as Enum, type index_d_EventListener as EventListener, type index_d_Fragment as Fragment, index_d_Node as Node, type index_d_Options as Options, type index_d_Select as Select, type index_d_Template as Template, type index_d_Variable as Variable, index_d_parse as parse };
 }
 
 type VerifyError = any;
@@ -324,12 +468,12 @@ declare namespace Component {
      */
     type Getter = (path: string[], next?: ((path: string[]) => Component | null) | undefined) => Component | null;
 }
-type Schema = Record<string, Schema.Field>;
+type Schema<M = any> = Record<string, Schema.Field<M>>;
 declare namespace Schema {
     /**
      * 字段定义
      */
-    type Field = (Schema.Object | Schema.Type) & Schema.Attr;
+    type Field<M_1 = any> = (Schema.Object<M_1> | Schema.Type) & Schema.Attr<M_1>;
     /**
      * 可选值
      */
@@ -388,11 +532,11 @@ declare namespace Schema {
     /**
      * 对象类型定义
      */
-    type Object = {
+    type Object<M_1 = any> = {
         /**
          * 字段定义
          */
-        type: Record<string, Schema.Field>;
+        type: Record<string, Schema.Field<M_1>>;
         /**
          * 是否为数组
          */
@@ -436,11 +580,11 @@ declare namespace Schema {
          */
         blur: Event;
     };
-    type Attr = {
+    type Attr<M_1 = any> = {
         /**
          * 元信息
          */
-        meta?: any;
+        meta?: M_1 | undefined;
         /**
          * 自定义组件
          */
@@ -512,7 +656,7 @@ declare namespace Schema {
         /**
          * 可选值
          */
-        values?: (Schema.Value.Define | Schema.Value.Group.Define)[] | undefined;
+        values?: (Schema.Value.Define | Schema.Value.Group.Define)[] | ((store: Store) => (Schema.Value.Group.Define | Schema.Value.Define)[]) | undefined;
         /**
          * 监听函数
          */
@@ -636,17 +780,19 @@ type Ref = {
 /**
  * 管理单个表单字段的状态和行为
  * @template [T=any]
+ * @template [M=any]
  */
-declare class Store<T = any> {
+declare class Store<T = any, M = any> {
     /**
      * 从数据结构模式创建存储
-     * @param {Schema} schema 数据结构模式
+     * @template [M=any]
+     * @param {Schema<M>} schema 数据结构模式
      * @param {object} [options] 选项
      * @param {boolean} [options.new] 是否为新建环境
      */
-    static create(schema: Schema, options?: {
+    static create<M_1 = any>(schema: Schema<M_1>, options?: {
         new?: boolean | undefined;
-    }): Store<any>;
+    }): Store<any, any>;
     /**
      * 设置自定义类型的存储类
      * @param {string} type
@@ -656,12 +802,12 @@ declare class Store<T = any> {
         new (...p: ConstructorParameters<typeof Store>): Store;
     }): void;
     /**
-     * @param {Schema.Field} schema 字段的 Schema 定义
+     * @param {Schema.Field<M>} schema 字段的 Schema 定义
      * @param {object} [options] 可选配置
      * @param {*} [options.parent]
      * @param {*} [options.state]
      * @param {number | string | null} [options.index]
-     * @param {number | Signal.State<number> | Signal.Computed<number>} [options.length]
+     * @param {number | Signal.State<number> | Signal.Computed<number>} [options.size]
      * @param {boolean} [options.null]
      * @param {boolean} [options.new]
      * @param {boolean} [options.hidden]
@@ -692,11 +838,11 @@ declare class Store<T = any> {
      * @param {((value: T?, index: any, store: Store) => void)?} [options.onUpdate]
      * @param {((value: T?, index: any, store: Store) => void)?} [options.onUpdateState]
      */
-    constructor(schema: Schema.Field, { null: isNull, state, ref, setValue, setState, convert, onUpdate, onUpdateState, validator, validators, index, length, new: isNew, parent: parentNode, hidden, clearable, required, disabled, readonly, label, description, placeholder, min, max, step, minLength, maxLength, pattern, values }?: {
+    constructor(schema: Schema.Field<M>, { null: isNull, state, ref, setValue, setState, convert, onUpdate, onUpdateState, validator, validators, index, size, new: isNew, parent: parentNode, hidden, clearable, required, disabled, readonly, label, description, placeholder, min, max, step, minLength, maxLength, pattern, values }?: {
         parent?: any;
         state?: any;
         index?: string | number | null | undefined;
-        length?: number | Signal.State<number> | Signal.Computed<number> | undefined;
+        size?: number | Signal.State<number> | Signal.Computed<number> | undefined;
         null?: boolean | undefined;
         new?: boolean | undefined;
         hidden?: boolean | undefined;
@@ -764,21 +910,21 @@ declare class Store<T = any> {
     /** 存储类类别，继承的自定义类需要设置自定义的此只读属性 */
     get kind(): string;
     get ref(): Ref;
-    schema: Schema.Field;
+    schema: Schema.Field<M>;
     /** 存储对象自身 */
     get store(): this;
     /** 父级存储对象 */
-    get parent(): Store<any> | null;
+    get parent(): Store<any, any> | null;
     /** 根节点的存储对象 */
-    get root(): Store<any>;
+    get root(): Store<any, any>;
     /** 字段类型 */
     get type(): any;
     /** 字段元信息 */
-    get meta(): any;
+    get meta(): void | M;
     /** 自定义渲染组件信息 */
     get component(): any;
     /** 长度信息 */
-    get length(): number;
+    get size(): number;
     set index(v: string | number);
     /** 索引信息 */
     get index(): string | number;
@@ -913,7 +1059,7 @@ declare class Store<T = any> {
 
 /**
  * @param {Store} store 存储实例
- * @param {(Layout.Node | string)[]} layouts 布局信息
+ * @param {Layout.Child[]} layouts 布局信息
  * @param {Element} parent 渲染节点
  * @param {object} [options] 选项
  * @param {Record<string, Store | {get?(): any; set?(v: any): void; exec?(...p: any[]): any; calc?(...p: any[]): any }>} [options.global] 全局数据
@@ -922,8 +1068,8 @@ declare class Store<T = any> {
  * @param {Record<string, Enhancement>} [options.enhancements] 增强信息
  * @returns {() => void}
  */
-declare function _default(store: Store, layouts: (Node | string)[], parent: Element, { component, global, relate, enhancements }?: {
-    global?: Record<string, Store<any> | {
+declare function render(store: Store, layouts: Child[], parent: Element, { component, global, relate, enhancements }?: {
+    global?: Record<string, Store<any, any> | {
         get?(): any;
         set?(v: any): void;
         exec?(...p: any[]): any;
@@ -951,4 +1097,4 @@ declare function watch<T>(getter: () => T, callback: (value: T) => void, immedia
  */
 declare function effect(fn: () => void): () => void;
 
-export { type AsyncValidator, Component, Enhancement, index_d as Layout, type Ref, type Relatedness, Schema, Store, type Validator, type VerifyError, effect, _default as render, watch };
+export { type AsyncValidator, Component, Enhancement, index_d as Layout, type Ref, type Relatedness, Schema, Store, type Validator, type VerifyError, effect, render, watch };