@neeloong/form 0.25.0 → 0.27.0

package/index.full.js

@@ -1,5 +1,5 @@
 /*!
-* @neeloong/form v0.25.0
+* @neeloong/form v0.27.0
 * (c) 2024-2026 Fierflame
 * @license Apache-2.0
 */
@@ -723,7 +723,8 @@
   let TypeStores = Object.create(null);
   /**
    * @template [M=any]
-   * @param {Schema.Field<M>} schema
+   * @template {Object.<string, Schema.State>} [S=Object.<string, Schema.State>]
+   * @param {Schema.Field<M, S>} schema
    * @param {object} [options] 
    * @param {Store?} [options.parent]
    * @param {string | number | null} [options.index] 
@@ -877,6 +878,7 @@
    * 管理单个表单字段的状态和行为
    * @template [T=any]
    * @template [M=any]
+   * @template {Object.<string, Schema.State>} [S=Object.<string, Schema.State>]
    */
   class Store {
   	/** @type {Map<string, Set<(value: any, store: any) => void | boolean | null>>} */
@@ -919,7 +921,8 @@
   	/**
   	 * 从数据结构模式创建存储
   	 * @template [M=any]
-  	 * @param {Schema<M>} schema 数据结构模式
+  	 * @template {Object.<string, Schema.State>} [S=Object.<string, Schema.State>]
+  	 * @param {Schema<M, S>} schema 数据结构模式
   	 * @param {object} [options] 选项
   	 * @param {boolean} [options.new] 是否为新建环境
   	 */
@@ -943,9 +946,10 @@
   	#ref = null;
   	get ref() { return this.#ref || createRef(this); }
   	/**
-  	 * @param {Schema.Field<M>} schema 字段的 Schema 定义
+  	 * @param {Schema.Field<M, S>} schema 字段的 Schema 定义
   	 * @param {object} [options] 可选配置
   	 * @param {Store?} [options.parent] 
+  	 * @param {Partial<S>?} [options.states] 
   	 * @param {((store: Store, value?: any) => any) | object | number | string | boolean | null | undefined} [options.default]
   	 * @param {number | string | null} [options.index] 
   	 * @param {number | Signal.State<number> | Signal.Computed<number>} [options.size] 
@@ -980,7 +984,7 @@
   	 */
   	constructor(schema, {
   		null: isNull, ref, default: defaultValue,
-  		setValue, convert, onUpdate,
+  		setValue, convert, onUpdate, states,
   		validator, validators,
   		index, size, new: isNew, parent: parentNode,
   		hidden, clearable, required, disabled, readonly, removable,
@@ -1058,6 +1062,22 @@
 
   		const validatorResult = createValidator(this, schema.validator, validator);
 
+
+  		const schemaStates = schema.states;
+  		this.#states = schemaStates ? Object.defineProperties(Object.create(null),
+  			Object.fromEntries(
+  				Object.entries(schemaStates).map(([k, { get, set, toState }]) => {
+  					const state = new exports.Signal.State(toState?.(states?.[k]));
+  					const computed = new exports.Signal.Computed(() => get(this, state));
+  					return [k, {
+  						configurable: true,
+  						enumerable: true,
+  						get() { return computed.get(); },
+  						set(v) { return set?.(this, state, v); },
+  					}];
+  				})
+  			)) : null;
+
   		const [changed, changedResult, cancelChange] = createAsyncValidator(this, schema.validators?.change, validators?.change);
   		const [blurred, blurredResult, cancelBlur] = createAsyncValidator(this, schema.validators?.blur, validators?.blur);
   		this.listen('change', () => { changed(); });
@@ -1092,8 +1112,11 @@
   			this.listen(k, f);
   		}
   	}
+  	/** @type {S?} */
+  	#states;
+  	get states() { return this.#states; }
   	/** @type {StoreLayout.Field<any>} */
-  	#layout
+  	#layout;
   	get layout() { return this.#layout; }
   	#createDefault;
   	/** @param {any} [value] @returns {any} */
@@ -1269,9 +1292,10 @@
   	#selfMin;
   	/** @readonly @type {Signal.Computed<number?>} */
   	#min;
+  	/** @deprecated */
   	get selfMin() { return this.#selfMin.get(); }
   	set selfMin(v) { this.#selfMin.set(number(v)); }
-  	/** 数值字段的最小值限制 */
+  	/** @deprecated 数值字段的最小值限制 */
   	get min() { return this.#min.get(); }
   	set min(v) { this.#selfMin.set(number(v)); }
 
@@ -1280,9 +1304,10 @@
   	#selfMax;
   	/** @readonly @type {Signal.Computed<number?>} */
   	#max;
+  	/** @deprecated */
   	get selfMax() { return this.#selfMax.get(); }
   	set selfMax(v) { this.#selfMax.set(number(v)); }
-  	/** 数值字段的最大值限制 */
+  	/** @deprecated 数值字段的最大值限制 */
   	get max() { return this.#max.get(); }
   	set max(v) { this.#selfMax.set(number(v)); }
 
@@ -1291,9 +1316,10 @@
   	#selfStep;
   	/** @readonly @type {Signal.Computed<number?>} */
   	#step;
+  	/** @deprecated */
   	get selfStep() { return this.#selfStep.get(); }
   	set selfStep(v) { this.#selfStep.set(number(v)); }
-  	/** 数值字段的步长 */
+  	/** @deprecated 数值字段的步长 */
   	get step() { return this.#step.get(); }
   	set step(v) { this.#selfStep.set(number(v)); }
 
@@ -1301,9 +1327,10 @@
   	#selfMinLength;
   	/** @readonly @type {Signal.Computed<number?>} */
   	#minLength;
+  	/** @deprecated */
   	get selfMinLength() { return this.#selfMinLength.get(); }
   	set selfMinLength(v) { this.#selfMinLength.set(number(v)); }
-  	/** 最小长度 */
+  	/** @deprecated 最小长度 */
   	get minLength() { return this.#minLength.get(); }
   	set minLength(v) { this.#selfMinLength.set(number(v)); }
 
@@ -1311,9 +1338,10 @@
   	#selfMaxLength;
   	/** @readonly @type {Signal.Computed<number?>} */
   	#maxLength;
+  	/** @deprecated */
   	get selfMaxLength() { return this.#selfMaxLength.get(); }
   	set selfMaxLength(v) { this.#selfMaxLength.set(number(v)); }
-  	/** 最大长度 */
+  	/** @deprecated 最大长度 */
   	get maxLength() { return this.#maxLength.get(); }
   	set maxLength(v) { this.#selfMaxLength.set(number(v)); }
 
@@ -1321,9 +1349,10 @@
   	#selfPattern;
   	/** @readonly @type {Signal.Computed<RegExp?>} */
   	#pattern;
+  	/** @deprecated */
   	get selfPattern() { return this.#selfPattern.get(); }
   	set selfPattern(v) { this.#selfPattern.set(regex(v)); }
-  	/** 模式 */
+  	/** @deprecated 模式 */
   	get pattern() { return this.#pattern.get(); }
   	set pattern(v) { this.#selfPattern.set(regex(v)); }
 
@@ -1332,9 +1361,10 @@
   	#selfValues;
   	/** @readonly @type {Signal.Computed<(Schema.Value.Group | Schema.Value)[] | null>} */
   	#values;
+  	/** @deprecated */
   	get selfValues() { return this.#selfValues.get(); }
   	set selfValues(v) { this.#selfValues.set(values(v)); }
-  	/** 可选值列表 */
+  	/** @deprecated 可选值列表 */
   	get values() { return this.#values.get(); }
   	set values(v) { this.#selfValues.set(values(v)); }
 
@@ -1369,6 +1399,40 @@
   	#initValue = new exports.Signal.State(/** @type {T?} */(null));
   	#value = new exports.Signal.State(this.#initValue.get());
 
+  	/**
+  	 * @template [M=any]
+  	 * @template {Object.<string, Schema.State>} [S=Object.<string, Schema.State>]
+  	 * @param {Schema<M, S>} schema 数据结构模式
+  	 */
+  	bindObject(schema) {
+  		const bindStores = this.#bindStores;
+  		/** @type {Store[]} */
+  		const list = [];
+  		for (const [index, field] of Object.entries(schema)) {
+  			const bindStore = create(field, {
+  				index, parent: this,
+  				/** @param {*} value @param {*} currentIndex @param {Store} store */
+  				onUpdate: (value, currentIndex, store) => {
+  					if (index !== currentIndex) { return; }
+  					if (bindStores.has(store)) { return; }
+  					const val = this.#value ?? null;
+  					if (typeof val !== 'object' || Array.isArray(val)) { return }
+  					// @ts-ignore
+  					this.value = { ...val, [currentIndex]: value };
+  				},
+  			});
+  			list.push(bindStore);
+  			bindStores.set(bindStore, index);
+  		}
+  		this.#requestUpdate();
+  		return () => {
+  			for (const bindStore of list) {
+  				bindStores.delete(bindStore);
+  			}
+  		};
+  	}
+  	/** @type {Map<Store, string>} */
+  	#bindStores = new Map();
 
   	/** 内容是否已改变 */
   	get changed() { return !Object.is(this.#value.get(), this.#initValue.get()); }
@@ -1415,6 +1479,9 @@
   			for (const [, field] of this) {
   				field.#reset(null, false);
   			}
+  			for (const [field] of this.#bindStores) {
+  				field.#reset(null, false);
+  			}
   			this.#value.set(value);
   			this.#initValue.set(value);
   			this.#onUpdate?.(value, this.#index.get(), this);
@@ -1425,6 +1492,9 @@
   		for (const [key, field] of this) {
   			newValues[key] = field.#reset(Object.hasOwn(newValues, key) ? newValues[key] : undefined, false);
   		}
+  		for (const [field, key] of this.#bindStores) {
+  			newValues[key] = field.#reset(Object.hasOwn(newValues, key) ? newValues[key] : undefined, false);
+  		}
   		this.#value.set(newValues);
   		this.#initValue.set(newValues);
   		this.#onUpdate?.(newValues, this.#index.get(), this);
@@ -1466,6 +1536,15 @@
   				newValues[key] = newData;
   				updated = true;
   			}
+  			for (const [field, key] of this.#bindStores) {
+  				// @ts-ignore
+  				const data = Object.hasOwn(val, key) ? val[key] : undefined;
+  				const newData = field.#toUpdate(data);
+  				if (Object.is(data, newData)) { continue; }
+  				// @ts-ignore
+  				newValues[key] = newData;
+  				updated = true;
+  			}
   			if (updated) {
   				val = newValues;
   				initValue = val;
@@ -1513,6 +1592,9 @@
   		for (const [key, field] of this) {
   			list.push(field.validate([...selfPath, key]));
   		}
+  		for (const [field, key] of this.#bindStores) {
+  			list.push(field.validate([...selfPath, key]));
+  		}
   		return Promise.all(list).then(v => v.flat());
   	}
   }
@@ -1522,7 +1604,8 @@
   /**
    * @template {Record<string, any>} [T=Record<string, any>]
    * @template [M=any]
-   * @extends {Store<T, M>}
+   * @template {Object.<string, Schema.State>} [S=Object.<string, Schema.State>]
+   * @extends {Store<T, M, S>}
    */
   class ObjectStore extends Store {
   	get kind() { return 'object'; }
@@ -1536,7 +1619,7 @@
   	 */
   	child(key) { return this.#children[key] || null; }
   	/**
-  	 * @param {Schema.Object<M> & Schema.Attr<M>} schema
+  	 * @param {Schema.Object<M, S> & Schema.Attr<M, S>} schema
   	 * @param {object} [options] 
   	 * @param {Store?} [options.parent] 
   	 * @param {number | string | null} [options.index] 
@@ -1588,7 +1671,8 @@
   /**
    * @template [T=any]
    * @template [M=any]
-   * @extends {Store<(T | null)[], M>}
+   * @template {Object.<string, Schema.State>} [S=Object.<string, Schema.State>]
+   * @extends {Store<(T | null)[], M, S>}
    */
   class ArrayStore extends Store {
   	/** @type {(index: number, isNew?: boolean) => Store} */
@@ -1611,7 +1695,7 @@
   	}
   	get kind() { return 'array'; }
   	/**
-  	 * @param {Schema.Field<M>} schema
+  	 * @param {Schema.Field<M, S>} schema
   	 * @param {object} [options] 
   	 * @param {Store?} [options.parent]
   	 * @param {string | number | null} [options.index] 
@@ -1680,6 +1764,8 @@
   			return child;
   		};
   	}
+  	/** @returns {never} */
+  	bindObject() { throw new Error(`ArrayStore 不支持 bindObject()方法`); }
 
 
   	/** @readonly @type {Signal.State<boolean?>} */
@@ -4797,7 +4883,7 @@
   	const children = [];
   	const childStores = [...store];
   	const count = childStores.length;
-  	/** @type {[string, Store<any, any>, number][]} */
+  	/** @type {[string, Store<any, any, any>, number][]} */
   	const stores = sort
   	? childStores
   		.map(([k,v]) => [k,v,env.setStore(v, store).exec(sort)])
@@ -5344,7 +5430,7 @@
    * @param {StoreLayout.Options?} options
    * @param {StoreLayout<T>} layout 
    * @param {Node} [anchor]
-   * @param {(child?: Store<any, any> | undefined) => void} [dragenter]
+   * @param {(child?: Store<any, any, any> | undefined) => void} [dragenter]
    * @returns {void}
    */
   function renderHtml(store, fieldRenderer, node, options, layout, anchor, dragenter) {
@@ -5355,29 +5441,53 @@
   		if (tagName === 'nl-form-field') {
   			const field = node.getAttribute('name') || '';
   			const mode = node.getAttribute('mode') || '';
+  			const renderer = node.getAttribute('renderer') || '';
+  			const editable = options?.editable && !node.hasAttribute('non-editable');
   			const fieldStore = field ? store.child(field) : store;
   			if (!fieldStore) { return; }
-  			const fieldLayout = field
-  				? layout?.fields?.find(createFieldFilter(field)) || fieldStore.layout
-  				: { ...layout, html: '' };
+  			/** @type {HTMLElement?} */
+  			let el = null;
   			switch (mode) {
   				case 'grid': {
-  					const el = Form(store, fieldRenderer, fieldLayout, options);
-  					if (el) { node.replaceWith(el); }
-  					return;
+  					const fieldLayout = field
+  						? layout?.fields?.find(createFieldFilter(field)) || fieldStore.layout
+  						: { ...layout, html: '' };
+  					el = Form(fieldStore, fieldRenderer, fieldLayout, {...options, editable});
+  					break;
+  				}
+  				default: {
+  					el = fieldRenderer(fieldStore, renderer || layout.renderer, {...options, editable});
+  					break;
   				}
   			}
-  			const res = fieldRenderer(fieldStore, layout.renderer, options);
-  			if (res) {
-  				node.replaceWith(res);
+  			if (!el) {
+  				const value = node.getAttribute('placeholder') || '';
+  				node.replaceWith(document.createTextNode(value));
   				return;
   			}
-  			const value = node.getAttribute('placeholder') || '';
-  			node.replaceWith(document.createTextNode(value));
+  			const className = node.getAttribute('class') || '';
+  			if (className) {
+  				el.setAttribute('class', [
+  					el.getAttribute('class') || '',
+  					className,
+  				].filter(Boolean).join(' '));
+  			}
+  			const style = node.getAttribute('style') || '';
+  			if (style) {
+  				el.setAttribute('style', [
+  					el.getAttribute('style') || '',
+  					style,
+  				].filter(Boolean).join(' '));
+  			}
+  			node.replaceWith(el);
   			return;
   		}
   		if (tagName === 'nl-form-button') {
   			const button = document.createElement('button');
+  			const className = node.getAttribute('class') || '';
+  			const style = node.getAttribute('style') || '';
+  			if (className) { button.setAttribute('class', className); }
+  			if (style) { button.setAttribute('style', style); }
   			button.classList.add('NeeloongForm-item-button');
   			const click = node.getAttribute('click') || '';
   			const call = options?.call;
@@ -5548,9 +5658,10 @@
   /**
    * 
    * @param {string | ParentNode | null} [html] 
+   * @param {function(string): string} [sanitize] 
    * @returns {ParentNode}
    */
-  function getHtmlContent(html) {
+  function getHtmlContent(html, sanitize) {
   	if (!html) {
   		return document.createElement('template').content;
   	}
@@ -5558,14 +5669,14 @@
   		return /** @type {ParentNode} */(html.cloneNode(true));
   	}
   	const template = document.createElement('template');
-  	template.innerHTML = html;
+  	template.innerHTML = sanitize ? sanitize(html) : html;
   	return template.content;
   }
 
   /**
    * 
    * @template T
-   * @param {Store<any, any>} store 
+   * @param {Store<any, any, any>} store 
    * @param {StoreLayout.Renderer<T>} fieldRenderer 
    * @param {StoreLayout<T>} layout
    * @param {StoreLayout.Options?} options
@@ -5575,7 +5686,7 @@
   	if (options?.signal?.aborted) { return null; }
   	const html = layout.html;
   	if (html) {
-  		const content = getHtmlContent(html);
+  		const content = getHtmlContent(html, options?.sanitizeHtml);
   		renderHtml(store, fieldRenderer, content, options, layout);
   		return content;
   	}
@@ -5588,7 +5699,7 @@
   /**
    * 
    * @template T
-   * @param {Store<any, any>} store 
+   * @param {Store<any, any, any>} store 
    * @param {StoreLayout.Renderer<T>} fieldRenderer 
    * @param {StoreLayout.Field<T>} layout
    * @param {object} option 
@@ -5667,12 +5778,12 @@
   	}
 
   	for (const column of columns) {
-  		const { actions, field, pattern } = column;
+  		const { actions, field, pattern, editable } = column;
   		if (!actions?.length) {
   			const td = head.appendChild(document.createElement('td'));
   			const child = field && store.child(field);
   			if (child) {
-  				const el = FormFieldInline(child, fieldRenderer, column, options);
+  				const el = FormFieldInline(child, fieldRenderer, column, {...options, editable: options?.editable && (editable !== false)});
   				if (el) { td.appendChild(el); }
   			}
   			continue;
@@ -5729,7 +5840,7 @@
    * @param {ArrayStore} store
    * @param {StoreLayout.Field<T>} layout
    * @param {StoreLayout.Action[]} actionOptions
-   * @param {(fields: { field: string; width: any; label: any; }[]) => StoreLayout.Column<T>[]} createDefault
+   * @param {(fields: { field: string; width: any; label: any; editable?: boolean? }[]) => StoreLayout.Column<T>[]} createDefault
    * @returns {StoreLayout.Column<T>[]}
    */
   function getColumns(store, layout, actionOptions, createDefault) {
@@ -5752,23 +5863,23 @@
   				if (!actions) { return null; }
   				return { actions };
   			}
-  			const { action, actions, field, placeholder, pattern, width, label } = v;
+  			const { action, actions, field, placeholder, pattern, width, label, editable } = v;
   			if (field) {
   				const define = map.get(field);
   				if (define) {
-  					return { field, placeholder, width, label: label || define.label };
+  					return { field, placeholder, width, label: label || define.label, editable };
   				}
   			}
   			const options = new Set(actionOptions);
   			const allActions = [action, actions].flat().filter(v => v && options.delete(v));
   			if (allActions.length) {
-  				return { actions: /** @type {StoreLayout.Action[]} */(allActions), width, label };
+  				return { actions: /** @type {StoreLayout.Action[]} */(allActions), width, label, editable };
   			}
   			if (pattern) {
-  				return { pattern, placeholder, width, label };
+  				return { pattern, placeholder, width, label, editable };
   			}
   			if (placeholder || width) {
-  				return { placeholder, width, label };
+  				return { placeholder, width, label, editable };
   			}
   			return null;
   		});
@@ -6073,8 +6184,8 @@
   /**
    * 
    * @template T
-   * @param {Store<any, any>} store 
-   * @param {Signal.State<Store<any, any>?>} currentStore 
+   * @param {Store<any, any, any>} store 
+   * @param {Signal.State<Store<any, any, any>?>} currentStore 
    * @param {StoreLayout.Renderer<T>} fieldRenderer 
    * @param {StoreLayout.Field<T>} layout
    * @param {Signal.State<State>} state
@@ -6088,7 +6199,7 @@
    * @param {() => void} option.dragend 
    * @param {{get(): boolean}} option.deletable 
    * @param {() => void} option.addNode 
-   * @param {(store: Store<any, any>) => () => void} option.createDetails 
+   * @param {(store: Store<any, any, any>) => () => void} option.createDetails 
    * @param {StoreLayout.Options?} options
    * @returns {HTMLElement}
    */
@@ -6490,10 +6601,10 @@
 
   	/** @type {AbortController?} */
   	let detailAbortController = null;
-  	const detailsStore = new exports.Signal.State(/** @type{Store<any, any>?}*/(null));
+  	const detailsStore = new exports.Signal.State(/** @type{Store<any, any, any>?}*/(null));
   	/**
   	 * 
-  	 * @param {Store<any, any>} store 
+  	 * @param {Store<any, any, any>} store 
   	 * @returns 
   	 */
   	function createDetails(store) {
@@ -6745,14 +6856,14 @@
    * 
    * @template T
    * @param {string | ParentNode} html 
-   * @param {Store<any, any>} store 
+   * @param {Store<any, any, any>} store 
    * @param {StoreLayout.Renderer<T>} fieldRenderer 
    * @param {StoreLayout.Options?} options
    * @param {StoreLayout.Field<T>} layout
    * @returns {ParentNode}
    */
   function Html(html, store, fieldRenderer, options, layout) {
-  	const htmlContent = getHtmlContent(html);
+  	const htmlContent = getHtmlContent(html, options?.sanitizeHtml);
   	renderHtml(store, fieldRenderer, htmlContent, options, layout);
   	return htmlContent;
   }
@@ -6777,7 +6888,7 @@
   /**
    * 
    * @template T
-   * @param {Store<any, any>} store 
+   * @param {Store<any, any, any>} store 
    * @param {StoreLayout.Renderer<T>} fieldRenderer 
    * @param {StoreLayout.Field<T>} layout
    * @param {StoreLayout.Options?} options
@@ -6811,7 +6922,7 @@
 
   /**
    *
-   * @param {Store<any, any>} store
+   * @param {Store<any, any, any>} store
    * @param {StoreLayout.Button} layout
    * @param {StoreLayout.Options?} options
    * @returns {ParentNode}
@@ -6849,7 +6960,7 @@
   /**
    *
    * @template T
-   * @param {Store<any, any>} store
+   * @param {Store<any, any, any>} store
    * @param {StoreLayout.Renderer<T>} fieldRenderer 
    * @param {StoreLayout.Html} layout
    * @param {StoreLayout.Options?} options
@@ -6859,7 +6970,7 @@
   	const html = layout.html;
   	if (!html) { return null; }
   	const [root, content] = createCell(options?.signal, layout, store);
-  	const htmlContent = getHtmlContent(html);
+  	const htmlContent = getHtmlContent(html, options?.sanitizeHtml);
   	renderHtml(store, fieldRenderer, htmlContent, options, layout);
   	content.appendChild(htmlContent);
   	return root;
@@ -6871,7 +6982,7 @@
   /**
    * 
    * @template T
-   * @param {Store<any, any>} store 
+   * @param {Store<any, any, any>} store 
    * @param {StoreLayout.Renderer<T>} fieldRenderer 
    * @param {StoreLayout.Item<T>} item
    * @param {StoreLayout.Options?} options
@@ -6896,7 +7007,7 @@
   /**
    * 
    * @template T
-   * @param {Store<any, any>} store 
+   * @param {Store<any, any, any>} store 
    * @param {StoreLayout.Renderer<T>} fieldRenderer 
    * @param {StoreLayout<T>} layout
    * @param {StoreLayout.Options?} options
@@ -6945,7 +7056,7 @@
   		Form(store, fieldRenderer, storeLayout, options || null, root);
   		return;
   	}
-  	const content = getHtmlContent(html);
+  	const content = getHtmlContent(html, options?.sanitizeHtml);
   	renderHtml(store, fieldRenderer, content, options || null, storeLayout);
   	root.appendChild(content);
   	options?.signal?.addEventListener('abort', () => {