@neeloong/form 0.25.0 → 0.27.0

package/index.d.mts

@@ -1,5 +1,5 @@
 /*!
-* @neeloong/form v0.25.0
+* @neeloong/form v0.27.0
 * (c) 2024-2026 Fierflame
 * @license Apache-2.0
 */
@@ -73,6 +73,7 @@ declare namespace StoreLayout {
         html?: string | ParentNode | null | undefined;
         fields?: StoreLayout.Item<T_1>[] | null | undefined;
         renderer?: T_1 | undefined;
+        editable?: boolean | null | undefined;
     };
     type Field<T_1 = unknown> = {
         type?: "field" | undefined;
@@ -105,9 +106,9 @@ declare namespace StoreLayout {
         required?: boolean | undefined;
         label?: string | undefined;
         description?: string | undefined;
-        disabled?: ((store: Store<any, any>, options?: StoreLayout.Options | null) => boolean) | undefined;
-        text?: string | ((store: Store<any, any>, options?: StoreLayout.Options | null) => string) | undefined;
-        click?: string | ((event: Event, store: Store<any, any>, options?: StoreLayout.Options | null) => void) | undefined;
+        disabled?: ((store: Store<any, any, any>, options?: StoreLayout.Options | null) => boolean) | undefined;
+        text?: string | ((store: Store<any, any, any>, options?: StoreLayout.Options | null) => string) | undefined;
+        click?: string | ((event: Event, store: Store<any, any, any>, options?: StoreLayout.Options | null) => void) | undefined;
     };
     type Html = {
         type: "html";
@@ -128,12 +129,17 @@ declare namespace StoreLayout {
         relate?: ((store: Store, el: Element | StoreLayout.Relatedness) => () => void) | undefined;
         editable?: boolean | undefined;
         signal?: AbortSignal | undefined;
-        call?: ((name: string, event: Event, store: Store<any, any>, options?: StoreLayout.Options | null) => void) | undefined;
+        sanitizeHtml?: ((arg0: string) => string) | undefined;
+        call?: ((name: string, event: Event, store: Store<any, any, any>, options?: StoreLayout.Options | null) => void) | undefined;
     };
-    type Renderer<T_1 = unknown> = (store: Store<any, any>, renderer?: T_1, options?: StoreLayout.Options | null) => HTMLElement | null;
+    type Renderer<T_1 = unknown> = (store: Store<any, any, any>, renderer?: T_1 | string, options?: StoreLayout.Options | null) => HTMLElement | null;
 }
 
-type Schema<M = any> = Record<string, Schema.Field<M>>;
+type Schema<M = any, S extends {
+    [x: string]: Schema.State;
+} = {
+    [x: string]: Schema.State;
+}> = Record<string, Schema.Field<M, S>>;
 declare namespace Schema {
     /**
      * 同步验证器
@@ -146,7 +152,11 @@ declare namespace Schema {
     /**
      * 字段定义
      */
-    type Field<M_1 = any> = (Schema.Object<M_1> | Schema.Type) & Schema.Attr<M_1>;
+    type Field<M_1 = any, S_1 extends {
+        [x: string]: Schema.State;
+    } = {
+        [x: string]: State;
+    }> = (Schema.Object<M_1, S_1> | Schema.Type) & Schema.Attr<M_1, S_1>;
     /**
      * 可选值
      */
@@ -205,11 +215,15 @@ declare namespace Schema {
     /**
      * 对象类型定义
      */
-    type Object<M_1 = any> = {
+    type Object<M_1 = any, S_1 extends {
+        [x: string]: Schema.State;
+    } = {
+        [x: string]: State;
+    }> = {
         /**
          * 字段定义
          */
-        type: Record<string, Schema.Field<M_1>>;
+        type: Record<string, Schema.Field<M_1, S_1>>;
         /**
          * 是否为数组
          */
@@ -253,11 +267,21 @@ declare namespace Schema {
          */
         blur: Event;
     };
-    type Attr<M_1 = any> = {
+    type Stater<T, S_1 = any> = {
+        get: (arg0: Store, arg1: Signal.State<S_1>) => T;
+        set: (arg0: Store, arg1: Signal.State<S_1>, arg2: any) => void;
+        toState: (arg0: any) => S_1;
+    };
+    type Attr<M_1 = any, S_1 extends {
+        [x: string]: Schema.State;
+    } = {
+        [x: string]: State;
+    }> = {
         /**
          * 元信息
          */
         meta?: M_1 | undefined;
+        states?: { [k in keyof S_1]: Schema.Stater<S_1[k], any>; } | undefined;
         default?: ((store: Store) => any) | any;
         /**
          * 自定义组件
@@ -377,6 +401,7 @@ declare namespace Schema {
         } | undefined;
         layout?: StoreLayout.Field<any> | undefined;
     };
+    type State = string | boolean | number | Object | null;
 }
 
 declare const ref: unique symbol;
@@ -392,18 +417,30 @@ type Ref = {
  * 管理单个表单字段的状态和行为
  * @template [T=any]
  * @template [M=any]
+ * @template {Object.<string, Schema.State>} [S=Object.<string, Schema.State>]
  */
-declare class Store<T = any, M = any> {
+declare class Store<T = any, M = any, S extends {
+    [x: string]: Schema.State;
+} = {
+    [x: string]: Schema.State;
+}> {
     /**
      * 从数据结构模式创建存储
      * @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] 是否为新建环境
      */
-    static create<M_1 = any>(schema: Schema<M_1>, options?: {
+    static create<M_1 = any, S_1 extends {
+        [x: string]: Schema.State;
+    } = {
+        [x: string]: Schema.State;
+    }>(schema: Schema<M_1, S_1>, options?: {
         new?: boolean | undefined;
-    }): Store<any, any>;
+    }): Store<any, any, {
+        [x: string]: Schema.State;
+    }>;
     /**
      * 设置自定义类型的存储类
      * @param {string} type
@@ -413,9 +450,10 @@ declare class Store<T = any, M = any> {
         new (...p: ConstructorParameters<typeof Store>): Store;
     }): void;
     /**
-     * @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]
@@ -448,8 +486,11 @@ declare class Store<T = any, M = any> {
      *
      * @param {((value: T?, index: any, store: Store) => void)?} [options.onUpdate]
      */
-    constructor(schema: Schema.Field<M>, { null: isNull, ref, default: defaultValue, setValue, convert, onUpdate, validator, validators, index, size, new: isNew, parent: parentNode, hidden, clearable, required, disabled, readonly, removable, label, description, placeholder, min, max, step, minLength, maxLength, pattern, values }?: {
-        parent?: Store<any, any> | null | undefined;
+    constructor(schema: Schema.Field<M, S>, { null: isNull, ref, default: defaultValue, setValue, convert, onUpdate, states, validator, validators, index, size, new: isNew, parent: parentNode, hidden, clearable, required, disabled, readonly, removable, label, description, placeholder, min, max, step, minLength, maxLength, pattern, values }?: {
+        parent?: Store<any, any, {
+            [x: string]: Schema.State;
+        }> | null | undefined;
+        states?: Partial<S> | null | undefined;
         default?: ((store: Store, value?: any) => any) | object | number | string | boolean | null | undefined;
         index?: string | number | null | undefined;
         size?: number | Signal.State<number> | Signal.Computed<number> | undefined;
@@ -519,7 +560,8 @@ declare class Store<T = any, M = any> {
     /** 存储类类别，继承的自定义类需要设置自定义的此只读属性 */
     get kind(): string;
     get ref(): Ref;
-    schema: Schema.Field<M>;
+    schema: Schema.Field<M, S>;
+    get states(): S | null;
     get layout(): StoreLayout.Field<any>;
     /** @param {any} [value] @returns {any} */
     createDefault(value?: any): any;
@@ -528,9 +570,13 @@ declare class Store<T = any, M = any> {
     /** 存储对象自身 */
     get store(): this;
     /** 父级存储对象 */
-    get parent(): Store<any, any> | null;
+    get parent(): Store<any, any, {
+        [x: string]: Schema.State;
+    }> | null;
     /** 根节点的存储对象 */
-    get root(): Store<any, any>;
+    get root(): Store<any, any, {
+        [x: string]: Schema.State;
+    }>;
     /** 字段类型 */
     get type(): any;
     /** 字段元信息 */
@@ -599,39 +645,46 @@ declare class Store<T = any, M = any> {
     /** 字段的占位符信息 */
     get placeholder(): string | null;
     set selfMin(v: number | null);
+    /** @deprecated */
     get selfMin(): number | null;
     set min(v: number | null);
-    /** 数值字段的最小值限制 */
+    /** @deprecated 数值字段的最小值限制 */
     get min(): number | null;
     set selfMax(v: number | null);
+    /** @deprecated */
     get selfMax(): number | null;
     set max(v: number | null);
-    /** 数值字段的最大值限制 */
+    /** @deprecated 数值字段的最大值限制 */
     get max(): number | null;
     set selfStep(v: number | null);
+    /** @deprecated */
     get selfStep(): number | null;
     set step(v: number | null);
-    /** 数值字段的步长 */
+    /** @deprecated 数值字段的步长 */
     get step(): number | null;
     set selfMinLength(v: number | null);
+    /** @deprecated */
     get selfMinLength(): number | null;
     set minLength(v: number | null);
-    /** 最小长度 */
+    /** @deprecated 最小长度 */
     get minLength(): number | null;
     set selfMaxLength(v: number | null);
+    /** @deprecated */
     get selfMaxLength(): number | null;
     set maxLength(v: number | null);
-    /** 最大长度 */
+    /** @deprecated 最大长度 */
     get maxLength(): number | null;
     set selfPattern(v: RegExp | null);
+    /** @deprecated */
     get selfPattern(): RegExp | null;
     set pattern(v: RegExp | null);
-    /** 模式 */
+    /** @deprecated 模式 */
     get pattern(): RegExp | null;
     set selfValues(v: (Schema.Value | Schema.Value.Group)[] | null);
+    /** @deprecated */
     get selfValues(): (Schema.Value | Schema.Value.Group)[] | null;
     set values(v: (Schema.Value | Schema.Value.Group)[] | null);
-    /** 可选值列表 */
+    /** @deprecated 可选值列表 */
     get values(): (Schema.Value | Schema.Value.Group)[] | null;
     /** 所有校验错误列表 */
     get errors(): string[];
@@ -643,11 +696,21 @@ declare class Store<T = any, M = any> {
      * @returns {Store?}
      */
     child(key: string | number): Store | null;
-    /** 内容是否已改变 */
-    get changed(): boolean;
+    /**
+     * @template [M=any]
+     * @template {Object.<string, Schema.State>} [S=Object.<string, Schema.State>]
+     * @param {Schema<M, S>} schema 数据结构模式
+     */
+    bindObject<M_1 = any, S_1 extends {
+        [x: string]: Schema.State;
+    } = {
+        [x: string]: Schema.State;
+    }>(schema: Schema<M_1, S_1>): () => void;
     set value(v: T | null);
     /** 字段当前值 */
     get value(): T | null;
+    /** 内容是否已改变 */
+    get changed(): boolean;
     /** 重置数据 */
     reset(value?: unknown, isNew?: boolean): void;
     /**
@@ -677,24 +740,33 @@ declare class Store<T = any, M = any> {
 /**
  * @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>}
  */
-declare class ObjectStore<T extends Record<string, any> = Record<string, any>, M = any> extends Store<T, M> {
+declare class ObjectStore<T extends Record<string, any> = Record<string, any>, M = any, S extends {
+    [x: string]: Schema.State;
+} = {
+    [x: string]: Schema.State;
+}> extends Store<T, M, S> {
     /**
-     * @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]
      * @param {boolean} [options.new]
      * @param {((value: T?, index: any, store: Store) => void)?} [options.onUpdate]
      */
-    constructor(schema: Schema.Object<M> & Schema.Attr<M>, { parent, index, new: isNew, onUpdate }?: {
-        parent?: Store<any, any> | null | undefined;
+    constructor(schema: Schema.Object<M, S> & Schema.Attr<M, S>, { parent, index, new: isNew, onUpdate }?: {
+        parent?: Store<any, any, {
+            [x: string]: Schema.State;
+        }> | null | undefined;
         index?: string | number | null | undefined;
         new?: boolean | undefined;
         onUpdate?: ((value: T | null, index: any, store: Store) => void) | null | undefined;
     });
-    [Symbol.iterator](): Generator<[string, Store<any, any>], void, unknown>;
+    [Symbol.iterator](): Generator<[string, Store<any, any, {
+        [x: string]: Schema.State;
+    }>], void, unknown>;
     #private;
 }
 
@@ -702,11 +774,16 @@ declare class ObjectStore<T extends Record<string, any> = Record<string, any>, M
 /**
  * @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>}
  */
-declare class ArrayStore<T = any, M = any> extends Store<(T | null)[], M> {
+declare class ArrayStore<T = any, M = any, S extends {
+    [x: string]: Schema.State;
+} = {
+    [x: string]: Schema.State;
+}> extends Store<(T | null)[], M, S> {
     /**
-     * @param {Schema.Field<M>} schema
+     * @param {Schema.Field<M, S>} schema
      * @param {object} [options]
      * @param {Store?} [options.parent]
      * @param {string | number | null} [options.index]
@@ -714,14 +791,20 @@ declare class ArrayStore<T = any, M = any> extends Store<(T | null)[], M> {
      * @param {boolean} [options.addable]
      * @param {(value: any, index: any, store: Store) => void} [options.onUpdate]
      */
-    constructor(schema: Schema.Field<M>, { parent, onUpdate, index, new: isNew, addable }?: {
-        parent?: Store<any, any> | null | undefined;
+    constructor(schema: Schema.Field<M, S>, { parent, onUpdate, index, new: isNew, addable }?: {
+        parent?: Store<any, any, {
+            [x: string]: Schema.State;
+        }> | null | undefined;
         index?: string | number | null | undefined;
         new?: boolean | undefined;
         addable?: boolean | undefined;
         onUpdate?: ((value: any, index: any, store: Store) => void) | undefined;
     });
-    get children(): Store<any, any>[];
+    get children(): Store<any, any, {
+        [x: string]: Schema.State;
+    }>[];
+    /** @returns {never} */
+    bindObject(): never;
     set selfAddable(v: boolean | null);
     get selfAddable(): boolean | null;
     set addable(v: boolean);
@@ -762,7 +845,9 @@ declare class ArrayStore<T = any, M = any> extends Store<(T | null)[], M> {
      * @returns
      */
     exchange(a: number, b: number): boolean;
-    [Symbol.iterator](): Generator<[number, Store<any, any>], undefined, unknown>;
+    [Symbol.iterator](): Generator<[number, Store<any, any, {
+        [x: string]: Schema.State;
+    }>], undefined, unknown>;
     #private;
 }
 
@@ -1287,7 +1372,9 @@ declare namespace Enhancement {
  * @returns {() => void}
  */
 declare function render(store: Store, layouts: Child[], parent: Element, { component, global, relate, enhancements }?: {
-    global?: Record<string, Store<any, any> | {
+    global?: Record<string, Store<any, any, {
+        [x: string]: Schema.State;
+    }> | {
         get?(): any;
         set?(v: any): void;
         exec?(...p: any[]): any;