@neeloong/form 0.11.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`）**：  
@@ -179,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>
 ```
@@ -300,7 +300,7 @@ render(store, layouts, app);
    - `$null` 只读 是否为空元素
    - `$index` 只读 当前项的索引
    - `$no` 只读 数组项目的序号
-   - `$length` 只读 数组的长度、对象的成员数
+   - `$size` 只读 数组的长度、对象的成员数
    - `$creatable` 只读 值是否可创建（`$new` 为 `true` 时，字段只读）
    - `$immutable` 只读 值是否不可改变（`$new` 为 `false` 时，字段只读）
    - `$new` 只读 是否新建项
@@ -343,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. 当存在同名变量时，则会按照变量来源类型决定优先级，从高到低依次为：
@@ -353,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.11.0
+* @neeloong/form v0.12.0
 * (c) 2024-2025 Fierflame
 * @license Apache-2.0
 */
@@ -468,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>;
     /**
      * 可选值
      */
@@ -532,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>>;
         /**
          * 是否为数组
          */
@@ -580,11 +580,11 @@ declare namespace Schema {
          */
         blur: Event;
     };
-    type Attr = {
+    type Attr<M_1 = any> = {
         /**
          * 元信息
          */
-        meta?: any;
+        meta?: M_1 | undefined;
         /**
          * 自定义组件
          */
@@ -656,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;
         /**
          * 监听函数
          */
@@ -780,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
@@ -800,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]
@@ -836,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;
@@ -908,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;
@@ -1067,7 +1069,7 @@ declare class Store<T = any> {
  * @returns {() => void}
  */
 declare function render(store: Store, layouts: Child[], parent: Element, { component, global, relate, enhancements }?: {
-    global?: Record<string, Store<any> | {
+    global?: Record<string, Store<any, any> | {
         get?(): any;
         set?(v: any): void;
         exec?(...p: any[]): any;

package/index.js

@@ -1,5 +1,5 @@
 /*!
-* @neeloong/form v0.11.0
+* @neeloong/form v0.12.0
 * (c) 2024-2025 Fierflame
 * @license Apache-2.0
 */
@@ -726,7 +726,8 @@
   /** @type {Record<string, {new(...p: ConstructorParameters<typeof Store>): Store}?>} */
   let TypeStores = Object.create(null);
   /**
-   * @param {Schema.Field} schema
+   * @template [M=any]
+   * @param {Schema.Field<M>} schema
    * @param {object} [options] 
    * @param {Store?} [options.parent]
    * @param {string | number | null} [options.index] 
@@ -863,6 +864,7 @@
   /**
    * 管理单个表单字段的状态和行为
    * @template [T=any]
+   * @template [M=any]
    */
   class Store {
   	/** @type {Map<string, Set<(value: any, store: any) => void | boolean | null>>} */
@@ -904,7 +906,8 @@
   	}
   	/**
   	 * 从数据结构模式创建存储
-  	 * @param {Schema} schema 数据结构模式
+  	 * @template [M=any]
+  	 * @param {Schema<M>} schema 数据结构模式
   	 * @param {object} [options] 选项
   	 * @param {boolean} [options.new] 是否为新建环境
   	 */
@@ -928,12 +931,12 @@
   	#ref = null;
   	get ref() { return this.#ref || createRef(this); }
   	/**
-  	 * @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] 
@@ -968,7 +971,7 @@
   		null: isNull, state, ref,
   		setValue, setState, convert, onUpdate, onUpdateState,
   		validator, validators,
-  		index, length, new: isNew, parent: parentNode,
+  		index, size, new: isNew, parent: parentNode,
   		hidden, clearable, required, disabled, readonly,
   		label, description, placeholder, min, max, step, minLength, maxLength, pattern, values: values$1
   	} = {}) {
@@ -1048,10 +1051,10 @@
   		this.#cancelChange = cancelChange;
   		this.#cancelBlur = cancelBlur;
   		
-  		if (length instanceof exports.Signal.State || length instanceof exports.Signal.Computed) {
-  			this.#length = length;
+  		if (size instanceof exports.Signal.State || size instanceof exports.Signal.Computed) {
+  			this.#size = size;
   		} else {
-  			this.#length = new exports.Signal.State(length || 0);
+  			this.#size = new exports.Signal.State(size || 0);
   		}
 
   		if (isNull) {
@@ -1089,7 +1092,7 @@
   	#root = this;
   	/** @readonly @type {any} */
   	#type;
-  	/** @readonly @type {any} */
+  	/** @readonly @type {M | void} */
   	#meta;
   	/** @readonly @type {any} */
   	#component;
@@ -1107,9 +1110,9 @@
   	get component() { return this.#component; }
 
   	/** @type {Signal.State<number> | Signal.Computed<number>} */
-  	#length;
+  	#size;
   	/** 长度信息 */
-  	get length() { return this.#length.get(); }
+  	get size() { return this.#size.get(); }
   	#index = new exports.Signal.State(/** @type {string | number} */(''));
   	/** 索引信息 */
   	get index() { return this.#index.get(); }
@@ -1496,7 +1499,8 @@
 
   /**
    * @template {Record<string, any>} [T=Record<string, any>]
-   * @extends {Store<T>}
+   * @template [M=any]
+   * @extends {Store<T, M>}
    */
   class ObjectStore extends Store {
   	get kind() { return 'object'; }
@@ -1510,7 +1514,7 @@
   	 */
   	child(key) { return this.#children[key] || null; }
   	/**
-  	 * @param {Schema.Object & Schema.Attr} schema
+  	 * @param {Schema.Object<M> & Schema.Attr<M>} schema
   	 * @param {object} [options] 
   	 * @param {Store?} [options.parent] 
   	 * @param {number | string | null} [options.index] 
@@ -1522,7 +1526,7 @@
   		const childrenTypes = Object.entries(schema.type);
   		super(schema, {
   			parent, index, new: isNew, onUpdate, onUpdateState,
-  			length: childrenTypes.length,
+  			size: childrenTypes.length,
   			setValue(v) { return typeof v === 'object' ? v : null; },
   			setState(v) { return typeof v === 'object' ? v : null; },
   			convert(v, state) {
@@ -1563,7 +1567,8 @@
 
   /**
    * @template [T=any]
-   * @extends {Store<(T | null)[]>}
+   * @template [M=any]
+   * @extends {Store<(T | null)[], M>}
    */
   class ArrayStore extends Store {
   	/** @type {(index: number, isNew?: boolean) => Store} */
@@ -1586,7 +1591,7 @@
   	}
   	get kind() { return 'array'; }
   	/**
-  	 * @param {Schema.Field} schema
+  	 * @param {Schema.Field<M>} schema
   	 * @param {object} [options] 
   	 * @param {Store?} [options.parent]
   	 * @param {string | number | null} [options.index] 
@@ -1604,6 +1609,7 @@
   			for (let i = children.length; i < length; i++) {
   					children.push(this.#create(i));
   			}
+  			children.length = length;
   			if (oldLength !== length) {
   				childrenState.set(children);
   			}
@@ -1611,7 +1617,7 @@
   		};
   		super(schema, {
   			index, new: isNew, parent,
-  			length: new exports.Signal.Computed(() => childrenState.get().length),
+  			size: new exports.Signal.Computed(() => childrenState.get().length),
   			state: [],
   			setValue(v) { return Array.isArray(v) ? v : v == null ? null : [v] },
   			setState(v) { return Array.isArray(v) ? v : v == null ? null : [v] },
@@ -2970,7 +2976,7 @@
   	null: true,
   	index: true,
   	no: true,
-  	length: true,
+  	size: true,
 
   	error: true,
   	errors: true,
@@ -3029,7 +3035,7 @@
   	yield [`${key}${sign}downMovable`, {get: () => {
   		const s = val.index;
   		if (typeof s !== 'number') { return false; }
-  		if (s >= parent.length - 1) { return false; }
+  		if (s >= parent.size - 1) { return false; }
   		return true;
   	}}];
   	yield [`${key}${sign}remove`, {exec: () => parent.remove(Number(val.index))}];
@@ -3042,7 +3048,7 @@
   	yield [`${key}${sign}downMove`, {exec: () => {
   		const s = val.index;
   		if (typeof s !== 'number') { return; }
-  		if (s >= parent.length - 1) { return; }
+  		if (s >= parent.size - 1) { return; }
   		parent.move(s, s + 1);
   	}}];
   }
@@ -3194,10 +3200,9 @@
   	watch(value, cb) { return watch(() => this.exec(value), cb, true); }
 
   	/**
-  	 * @param {Layout.Node.Name | Layout.Node.Calc | Layout.Node.Value | null} [en]
+  	 * @param {Layout.Node.Name | Layout.Node.Calc | Layout.Node.Value} en
   	 */
   	enum(en) {
-  		if (!en) { return true; }
   		const {name, calc} = en;
   		if (typeof calc === 'function') { return () => calc(this.getters); }
   		if (typeof name === 'string') {
@@ -3383,17 +3388,16 @@
   		const store = this.store;
   		const parent = this.#parent;
   		const object = this.#object;
+  		for (const [key, item] of toItem(store)) {
+  			ais[key] = item;
+  		}
+  		for (const [key, item] of toParentItem(parent, store)) {
+  			ais[key] = item;
+  		}
   		if (object) {
   			for (const k of Object.keys(object)) {
   				ais[`$${k}`] = {get: () => object[k]};
   			}
-  		} else {
-  			for (const [key, item] of toItem(store)) {
-  				ais[key] = item;
-  			}
-  			for (const [key, item] of toParentItem(parent, store)) {
-  				ais[key] = item;
-  			}
   		}
   		this.#allItems = ais;
   		return ais;
@@ -3402,11 +3406,13 @@
   	 * 
   	 * @param {Store} store 
   	 * @param {Store} parent 
+  	 * @param {Record<string, any>} [object] 
   	 */
-  	setStore(store, parent) {
+  	setStore(store, parent, object) {
   		const cloned = new Environment(store, this);
   		if (parent) { cloned.#parent = parent; }
   		setStore(cloned.#schemaItems, store);
+  		if (object) { cloned.#object = object; }
   		return cloned;
   	}
   	/**
@@ -4541,17 +4547,24 @@
   		}
 
   	}
+  	const count = new exports.Signal.State(0);
   	const childrenResult = watch(() => store.children, function render(children) {
   		if (!start.parentNode) { return; }
   		let nextNode = start.nextSibling;
   		const oldSeMap = seMap;
   		seMap = new Map();
+  		count.set(children.length);
   		for (let child of children) {
   			const old = oldSeMap.get(child);
   			if (!old) {
   				const ItemStart = parent.insertBefore(document.createComment(''), nextNode);
   				const itemEnd = parent.insertBefore(document.createComment(''), nextNode);
-  				const d = renderItem(itemEnd, env.setStore(child, store));
+  				const d = renderItem(itemEnd, env.setStore(child, store, {
+  					get count() { return count.get() },
+  					get key() { return child.index; },
+  					get index() { return child.index; },
+  					get item() { return child.value; },
+  				}));
   				seMap.set(child, [ItemStart, itemEnd, d]);
   				continue;
   			}
@@ -4637,7 +4650,7 @@
   	};
   }
 
-  /** @import { ObjectStore } from '../Store/index.mjs' */
+  /** @import { ObjectStore, Store } from '../Store/index.mjs' */
 
   /**
    *
@@ -4650,8 +4663,16 @@
   function renderObject(parent, next, store, env, renderItem) {
   	/** @type {(() => void)[]} */
   	const children = [];
-  	for (const [k, child] of [...store]) {
-  	children.push(renderItem(next, env.setStore(child, store)));
+  	/** @type {[string, Store<any, any>, number][]} */
+  	const childStores = [...store].map(([k,v], i) => [k,v,i]);
+  	const count = childStores.length;
+  	for (const [key, child, index] of childStores) {
+  	children.push(renderItem(next, env.setStore(child, store, {
+  		get count() { return count; },
+  		get key() { return key; },
+  		get index() { return index; },
+  		get item() { return child.value; },
+  	})));
   	}
 
   	return () => {
@@ -4697,11 +4718,13 @@
   			e.remove();
   		}
   	}
+  	const count = new exports.Signal.State(0);
   	const childrenResult = watch(() => list.get(), function render(children) {
   		if (!start.parentNode) { return; }
   		let nextNode = start.nextSibling;
   		const oldSeMap = seMap;
   		seMap = [];
+  		count.set(children.length);
   		for (const [value, index, key] of children) {
   			const index2 = oldSeMap.findIndex((v) => v[3] === key);
   			const [old] = index2 >= 0 ? oldSeMap.splice(index2, 1) : [];
@@ -4711,8 +4734,9 @@
   				const valueState = new exports.Signal.State(value);
   				const indexState = new exports.Signal.State(index);
   				const d = renderItem(itemEnd, env.setObject({
+  					get count() { return count.get() },
   					get key() { return key; },
-  					get value() { return valueState.get(); },
+  					get item() { return valueState.get(); },
   					get index() { return indexState.get(); },
   				}));
   				seMap.push([ItemStart, itemEnd, d, key, valueState, indexState]);
@@ -5065,9 +5089,6 @@
   		const list = env.enum(layout.value);
   		/** @type {(next: Node | null, env: any) => () => void} */
   		const r = (next, env) => renderChildren(layout.children, parent, next, env, templates, componentPath, enhancements, relate, getComponent);
-  		if (list === true) {
-  			return r(next, env);
-  		}
   		if (list instanceof ArrayStore) {
   			return renderArray(parent, next, list, env, r);
   		}