@dazhicheng/ui 1.5.156 → 1.5.159

package/dist/components/tt-form/index.d.ts

@@ -1,5 +1,5 @@
 import { Component } from 'vue';
-import { BaseFormComponentMap, BaseFormComponentType, ExtendedFormApi, FormRenderProps, FormSchema, FormSlotSchema, InferredComponentPropsType, TtFormProps } from './src/types';
+import { BaseFormComponentType, ExtendedFormApi, FormRenderProps, FormSchema, TtFormProps } from './src/types';
 import { COMPONENT_MAP } from './src/config';
 import { useForm } from './src/useForm';
 declare function setConfig(rules?: Record<string, (value: any, params: any, ctx: Record<string, any>) => boolean | string>, modelPropNameMap?: Partial<Record<BaseFormComponentType, string>>): void;
@@ -9,7 +9,9 @@ export { COMPONENT_MAP, useForm };
 type TtFormSchema = FormSchema<BaseFormComponentType>;
 type TtFormRenderProps = FormRenderProps<BaseFormComponentType>;
 type TtExtendedFormApi = ExtendedFormApi;
-export type { BaseFormComponentMap, BaseFormComponentType, FormSlotSchema, InferredComponentPropsType, TtExtendedFormApi, TtFormProps, TtFormRenderProps, TtFormSchema, };
+export type { ArraySchemaContext, BaseFormComponentMap, BaseFormComponentType, FormArrayActions, FormSlotSchema, InferredComponentPropsType, NestedArrayHandle, } from './src/types';
+export type { FieldArrayContext, FieldEntry, ResolvedFieldArrayContext } from './src/types/forms';
+export type { TtExtendedFormApi, TtFormProps, TtFormRenderProps, TtFormSchema };
 export * as z from 'zod';
 export { useGroupForm } from './src/group-form';
 export type { FormGroupSchema, GroupFormNavAnchorProps, GroupFormSchema, UseGroupFormNavAnchorProps, UseGroupFormOptions, UseGroupFormOptionsWithGroupSchema, UseGroupFormOptionsWithLegacySchema, } from './src/group-form';

package/dist/components/tt-form/src/form-render/FormArrayRegister.d.ts

@@ -1,8 +1,8 @@
 import { PropType } from 'vue';
 import { Recordable } from '../../../../../../utils/src';
 import { FieldEntry } from '../types/forms';
-import { FormSchema } from '../types';
-type ArraySchemaProp = FormSchema[] | ((entry: FieldEntry<Recordable>, currentIndex: number) => FormSchema[]);
+import { ArraySchemaContext, FormSchema } from '../types';
+type ArraySchemaProp = FormSchema[] | ((entry: FieldEntry<Recordable>, currentIndex: number, ctx?: ArraySchemaContext) => FormSchema[]);
 declare const FormArrayRegister: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
     fieldName: {
         type: PropType<string>;
@@ -24,9 +24,14 @@ declare const FormArrayRegister: import('vue').DefineComponent<import('vue').Ext
         type: BooleanConstructor;
         default: boolean;
     };
+    /** useArraySchema 时：每一行数组项的外层容器 class（边框、间距等） */
+    wrapperClass: {
+        type: PropType<NonNullable<FormSchema["wrapperClass"]>>;
+        default: undefined;
+    };
 }>, () => (import('vue').VNode<import('vue').RendererNode, import('vue').RendererElement, {
     [key: string]: any;
-}>[] | undefined)[], {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{
+}>[] | import("vue/jsx-runtime").JSX.Element | undefined)[], {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{
     fieldName: {
         type: PropType<string>;
         required: true;
@@ -47,7 +52,13 @@ declare const FormArrayRegister: import('vue').DefineComponent<import('vue').Ext
         type: BooleanConstructor;
         default: boolean;
     };
+    /** useArraySchema 时：每一行数组项的外层容器 class（边框、间距等） */
+    wrapperClass: {
+        type: PropType<NonNullable<FormSchema["wrapperClass"]>>;
+        default: undefined;
+    };
 }>> & Readonly<{}>, {
+    wrapperClass: string;
     rules: import('../types').FormSchemaRuleType | undefined;
     arraySchema: ArraySchemaProp;
     formItemClass: NonNullable<string | (() => string) | undefined>;

package/dist/components/tt-form/src/formApi.d.ts

@@ -2,10 +2,10 @@ import { FormState, GenericObject, ResetFormOpts, ValidationOptions } from 'vee-
 import { ComponentPublicInstance } from 'vue';
 import { Recordable, StateHandler } from '../../../../../utils/src';
 import { FormActions, FormArrayActions, FormSchema, NestedArrayHandle, TtFormProps } from './types';
-import { FieldArrayContext } from './types/forms';
+import { FieldArrayContext, ResolvedFieldArrayContext } from './types/forms';
 import { Store } from './shared/store';
 export type { ArrayPathSegment } from './utils/array-path';
-export { buildArrayFieldPath } from './utils/array-path';
+export { buildArrayFieldPath, collectArrayFieldPathAliases, normalizeArrayFieldPath } from './utils/array-path';
 export declare class FormApi {
     form: FormActions;
     isMounted: boolean;
@@ -40,6 +40,10 @@ export declare class FormApi {
     isFieldValid(fieldName: string): Promise<boolean>;
     merge(formApi: FormApi): any;
     mount(formActions: FormActions, componentRefMap: Map<string, unknown>): void;
+    /**
+     * @description 为 appendFields 新增的字段写入初始值（与 useFormInitial 规则一致，不覆盖已有数据）
+     */
+    protected seedDefaultsForAppendedFields(fields: FormSchema[]): Promise<void>;
     /**
      * @description 增量追加字段到 schema 中，支持通过 position 指定插入位置
      * @param {FormSchema[]} fields - 要插入的字段 schema 数组
@@ -143,7 +147,7 @@ export declare class FormApi {
      * @param name 需要注册的数组字段
      * @param actions 操作方法
      */
-    registerArrayField(name: string, actions: FieldArrayContext): void;
+    registerArrayField(name: string, actions: ResolvedFieldArrayContext): void;
     unregisterArrayField(name: string): void;
     /** @description 数组字段操作集合 */
     get arrayAction(): {
@@ -158,27 +162,27 @@ export declare class FormApi {
          * @param name 数组字段名（例如 `fieldName的值 数组下才生效`）
          * @param value 要追加的数组项值
          */
-        push: <TValue = unknown>(name: string, value: TValue) => void | undefined;
+        push: <TValue = unknown>(name: string, value: TValue) => void;
         /**
          * @description 删除指定索引的项
          * @param name 数组字段名（例如 `fieldName的值 数组下才生效`）
          * @param idx 要删除的索引位置
          */
-        remove: (name: string, idx: number) => void | undefined;
+        remove: (name: string, idx: number) => void;
         /**
          * @description 整体替换数组值
          * @template TValue 数组项类型
          * @param name 数组字段名（例如 `fieldName的值 数组下才生效`）
          * @param values 新的完整数组字段
          */
-        replace: <TValue = unknown>(name: string, values: TValue[]) => void | undefined;
+        replace: <TValue = unknown>(name: string, values: TValue[]) => void;
         /**
          * @description更新指定索引的项
          * @param name 数组字段名（例如 `fieldName的值 数组下才生效`）
          * @param idx 要更新的索引位置
          * @param value 更新后的数组项值
          */
-        update: <TValue = unknown>(name: string, idx: number, value: TValue) => void | undefined;
+        update: <TValue = unknown>(name: string, idx: number, value: TValue) => void;
         /**
          * @description 在指定索引插入一项
          * @template TValue 数组项类型
@@ -186,28 +190,28 @@ export declare class FormApi {
          * @param idx 插入位置索引
          * @param value 要插入的数组项值
          */
-        insert: <TValue = unknown>(name: string, idx: number, value: TValue) => void | undefined;
+        insert: <TValue = unknown>(name: string, idx: number, value: TValue) => void;
         /**
          * @description 在数组头部新增一项
          * @template TValue 数组项类型
          * @param name 数组字段名（例如 `fieldName的值 数组下才生效`）
          * @param value 要插入到头部的数组项值
          */
-        prepend: <TValue = unknown>(name: string, value: TValue) => void | undefined;
+        prepend: <TValue = unknown>(name: string, value: TValue) => void;
         /**
          * @description 将项从旧索引移动到新索引
          * @param name 数组字段名（例如 `fieldName的值 数组下才生效`）
          * @param oldIdx 原索引位置
          * @param newIdx 新索引位置
          */
-        move: (name: string, oldIdx: number, newIdx: number) => void | undefined;
+        move: (name: string, oldIdx: number, newIdx: number) => void;
         /**
          * @description 交换两个索引位置的项
          * @param name 数组字段名（例如 `fieldName的值 数组下才生效`）
          * @param indexA 第一个索引位置
          * @param indexB 第二个索引位置
          */
-        swap: (name: string, indexA: number, indexB: number) => void | undefined;
+        swap: (name: string, indexA: number, indexB: number) => void;
         /**
          * @description 获取嵌套数组路径下的操作器
          * @param parentPath 父数组路径（如 actions.data），或完整路径（仅传 path）
@@ -216,7 +220,17 @@ export declare class FormApi {
          */
         at: FormArrayActions["at"];
     };
+    /**
+     * @description 将业务传入路径规范化为数组注册表键
+     */
+    protected _resolveArrayFieldPath(name: string): string;
+    private _getRegisteredArrayField;
     private _getArrayFieldActions;
+    /**
+     * @description 开发环境：数组字段未注册时输出告警与相近路径提示
+     */
+    private _warnUnregisteredArrayField;
+    private _mutateArrayField;
     /**
      * @description 创建嵌套数组操作器（在原 inline 实现基础上支持链式 `.at`）
      */

package/dist/components/tt-form/src/group-form/groupFormApi.d.ts

@@ -271,7 +271,7 @@ export declare class GroupFormApi extends FormApi {
      * @description 卸载分组表单时恢复初始schema
      */
     get arrayAction(): {
-        get: <TValue = unknown>(name: string) => Readonly<import('../types').FieldArrayContext<TValue>> | undefined;
+        get: <TValue = unknown>(name: string) => Readonly<import('../..').FieldArrayContext<TValue>> | undefined;
         push: <TValue = unknown>(name: string, value: TValue) => void;
         remove: (name: string, idx: number) => void;
         replace: <TValue = unknown>(name: string, values: TValue[]) => void;

package/dist/components/tt-form/src/hooks/useArrayRegistry.d.ts

@@ -1,2 +1,2 @@
-import { FieldArrayContext } from '../types/forms';
-export declare function useArrayRegistry(name: string): readonly [(actions?: FieldArrayContext) => void, () => void];
+import { ResolvedFieldArrayContext } from '../types/forms';
+export declare function useArrayRegistry(name: string): readonly [(actions?: ResolvedFieldArrayContext) => void, () => void];

package/dist/components/tt-form/src/hooks/useFieldArray.d.ts

@@ -1,7 +1,7 @@
 import { MaybeRefOrGetter } from 'vue';
-import { FieldArrayContext } from '../types/forms';
+import { ResolvedFieldArrayContext } from '../types/forms';
 /**
  * 与 vee-validate `useFieldArray` API 对齐：稳定 `key`、`entry.value` 可写（支持 v-model），
  * 外部 `resetForm` / `setValues` 时同步行列表；不使用官方 `computedDeep` 与易递归的深拷贝双向 watch。
  */
-export declare function useFieldArray<TValue extends Record<string, unknown> = Record<string, unknown>>(arrayPath: MaybeRefOrGetter<string>): FieldArrayContext<TValue>;
+export declare function useFieldArray<TValue extends Record<string, unknown> = Record<string, unknown>>(arrayPath: MaybeRefOrGetter<string>): ResolvedFieldArrayContext<TValue>;

package/dist/components/tt-form/src/index.vue.d.ts

@@ -26,9 +26,9 @@ declare function __VLS_template(): {
                 readonly componentBindEventMap?: Partial<Record<import('./types').BaseFormComponentType, string>> | undefined;
                 readonly componentMap: Record<import('./types').BaseFormComponentType, import('vue').Component>;
                 readonly fieldMappingTime?: import('./types').FieldMappingTime | undefined;
-                readonly form?: import('vee-validate').FormContext<import('vee-validate').GenericObject> | undefined;
+                readonly form?: import('./types').FormActions | undefined;
                 readonly layout?: import('./types').FormLayout | undefined;
-                readonly schema?: (import('./types').FormSlotSchema | FormSchema<keyof import('./types').BaseFormComponentMap>)[] | undefined;
+                readonly schema?: (FormSchema<keyof import('./types').BaseFormComponentMap> | import('./types').FormSlotSchema)[] | undefined;
                 readonly showCollapseButton?: boolean | undefined;
                 readonly wrapperClass?: import('./types').WrapperClassType | undefined;
                 readonly globalCommonConfig?: import('./types').FormCommonConfig | undefined;
@@ -113,9 +113,9 @@ declare const __VLS_component: import('vue').DefineComponent<Props, {}, {}, {},
             readonly componentBindEventMap?: Partial<Record<import('./types').BaseFormComponentType, string>> | undefined;
             readonly componentMap: Record<import('./types').BaseFormComponentType, import('vue').Component>;
             readonly fieldMappingTime?: import('./types').FieldMappingTime | undefined;
-            readonly form?: import('vee-validate').FormContext<import('vee-validate').GenericObject> | undefined;
+            readonly form?: import('./types').FormActions | undefined;
             readonly layout?: import('./types').FormLayout | undefined;
-            readonly schema?: (import('./types').FormSlotSchema | FormSchema<keyof import('./types').BaseFormComponentMap>)[] | undefined;
+            readonly schema?: (FormSchema<keyof import('./types').BaseFormComponentMap> | import('./types').FormSlotSchema)[] | undefined;
             readonly showCollapseButton?: boolean | undefined;
             readonly wrapperClass?: import('./types').WrapperClassType | undefined;
             readonly globalCommonConfig?: import('./types').FormCommonConfig | undefined;

package/dist/components/tt-form/src/types/forms.d.ts

@@ -1,10 +1,10 @@
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { PartialDeep } from 'type-fest';
-import { ComputedRef, MaybeRef, MaybeRefOrGetter, Ref } from 'vue';
+import { ComputedRef, MaybeRef, MaybeRefOrGetter, Ref, UnwrapRef } from 'vue';
 import { FlattenAndSetPathsType, GenericObject, MapValuesPathsToRefs, MaybeArray, MaybePromise } from './common';
 import { Path, PathValue } from './paths';
 import { FieldValidationMetaInfo } from './shared';
-import { Recordable } from '../../../../../../utils/src';
+import { FieldArrayContext as VeeFieldArrayContext, FieldEntry } from 'vee-validate';
 export type ValidationResult<TValue = unknown> = {
     errors: string[];
     valid: boolean;
@@ -87,27 +87,25 @@ export type PathState<TInput = unknown, TOutput = TInput> = {
     };
     validate?: FieldValidator<TOutput>;
 };
-export type FieldEntry<TValue = Recordable> = {
-    value: TValue;
-    key: string | number;
-    isFirst: boolean;
-    isLast: boolean;
-};
-export type FieldArrayContext<TValue = Recordable> = {
-    fields: Ref<FieldEntry<TValue>[]>;
-    remove: (idx: number) => void;
-    replace: (newArray: TValue[]) => void;
-    update: (idx: number, value: TValue) => void;
-    push: (value: TValue) => void;
-    swap: (indexA: number, indexB: number) => void;
-    insert: (idx: number, value: TValue) => void;
-    prepend: (value: TValue) => void;
-    move: (oldIdx: number, newIdx: number) => void;
+export type { FieldEntry };
+/** vee-validate 原始数组上下文（`fields` 为 Ref，用于 `useFieldArray` / 注册表） */
+export type ResolvedFieldArrayContext<TValue = unknown> = VeeFieldArrayContext<TValue>;
+/**
+ * 经 FormApi `reactive(Map)` 读取时的数组上下文。
+ * `fields` 在运行时由 Vue reactive 自动解包，用法与 vee-validate `<FieldArray>` 插槽一致（`fields.length` / `v-for`）。
+ */
+export type FieldArrayContext<TValue = unknown> = Omit<ResolvedFieldArrayContext<TValue>, "fields"> & {
+    fields: UnwrapRef<ResolvedFieldArrayContext<TValue>["fields"]>;
 };
+/**
+ * 将注册表中的 `ResolvedFieldArrayContext` 转为对外 `FieldArrayContext`。
+ * 注册表为 `reactive(Map)`，运行时 `fields` 已自动解包，需经 `unknown` 断言以匹配类型。
+ */
+export declare function asFieldArrayContext<TValue = unknown>(ctx: ResolvedFieldArrayContext): Readonly<FieldArrayContext<TValue>>;
 export type PrivateFieldArrayContext<TValue = unknown> = {
     reset: () => void;
     path: MaybeRefOrGetter<string>;
-} & FieldArrayContext<TValue>;
+} & ResolvedFieldArrayContext<TValue>;
 export type PrivateFieldContext<TInput = unknown, TOutput = TInput> = {
     id: number;
     name: MaybeRef<string>;
@@ -278,4 +276,3 @@ export interface FormContext<TValues extends GenericObject = GenericObject, TOut
     handleReset: () => void;
     submitForm: (e?: unknown) => Promise<void>;
 }
-export {};

package/dist/components/tt-form/src/types.d.ts

@@ -99,7 +99,26 @@ export type NestedArrayHandle<TValue = unknown> = {
     at: (index: number, childField: string) => NestedArrayHandle<TValue>;
 };
 export type { ArrayPathSegment } from './utils/array-path';
-export { buildArrayFieldPath } from './utils/array-path';
+export { buildArrayFieldPath, collectArrayFieldPathAliases, normalizeArrayFieldPath } from './utils/array-path';
+/**
+ * `useArraySchema` 的 `arraySchema` 回调第三参数：当前数组上下文
+ */
+export interface ArraySchemaContext {
+    /** 当前数组字段完整路径（已规范化，与 arrayAction 注册键一致） */
+    arrayPath: string;
+    /** 当前行路径，如 `feeTickets[0]` */
+    itemPath: string;
+    /** 当前行索引 */
+    index: number;
+    /** 当前行 entry */
+    entry: FieldEntry<Recordable>;
+    /** 表单 arrayAction API */
+    arrayAction?: FormArrayActions;
+    /** 绑定 {@link arrayPath} 的操作器，可直接 `.push()` / `.remove()` */
+    arrayHandle?: NestedArrayHandle;
+    /** 表单值代理） */
+    form?: Record<string, unknown>;
+}
 export type FormActions = FormContext<GenericObject> & {
     arrayAction?: FormArrayActions;
 };
@@ -272,8 +291,11 @@ export interface FormSchema<T extends BaseFormComponentType = BaseFormComponentT
      * @description 支持直接传入配置数组 或 动态函数生成
      * @example arraySchema: []
      * @example arraySchema: (entry, index) => []
+     * @example arraySchema: (entry, index, ctx) => { ctx.arrayHandle?.push({}); return []; }
      */
-    arraySchema?: FormSchema[] | ((entry: FieldEntry<Recordable>, currentIndex: number) => FormSchema[]);
+    arraySchema?: FormSchema[] | ((entry: FieldEntry<Recordable>, currentIndex: number, 
+    /** 第三参数由 FormArrayRegister 注入；旧写法可忽略 */
+    ctx: ArraySchemaContext) => FormSchema[]);
 }
 /** 插槽 scope 参数，传递给渲染函数或具名插槽 */
 export interface FormSlotScope {
@@ -286,8 +308,10 @@ export interface FormSlotScope {
  * Extra slot props exposed for `useArraySchema: true` fields.
  */
 export interface FormArraySlotScope extends FormSlotScope {
-    arrayEntry?: unknown;
-    arrayAction?: unknown;
+    arrayEntry?: FieldEntry<Recordable>;
+    arrayAction?: FormArrayActions;
+    arrayHandle?: NestedArrayHandle;
+    arrayPath?: string;
     arrayIndex?: number;
     fieldName?: string;
 }
@@ -356,9 +380,9 @@ export interface FormRenderProps<T extends BaseFormComponentType = BaseFormCompo
      */
     fieldMappingTime?: FieldMappingTime;
     /**
-     * 表单实例
+     * 表单实例（vee-validate FormContext；数组操作请使用 injectFormProps 中的 formApi.arrayAction）
      */
-    form?: FormContext<GenericObject>;
+    form?: FormActions;
     /**
      * 表单项布局
      */

package/dist/components/tt-form/src/useFormContext.d.ts

@@ -3,6 +3,7 @@ import { FormSchema, ExtendedFormApi, FormActions, TtFormProps } from './types';
 type ExtendFormProps = TtFormProps & {
     formApi?: ExtendedFormApi;
 };
+export declare function isFormSchema(schema: unknown): schema is FormSchema;
 export declare const injectFormProps: <T extends [ExtendFormProps | ComputedRef<ExtendFormProps>, FormActions] | null | undefined = [ExtendFormProps | ComputedRef<ExtendFormProps>, FormActions]>(fallback?: T | undefined) => T extends null ? [ExtendFormProps | ComputedRef<ExtendFormProps>, FormActions] | null : [ExtendFormProps | ComputedRef<ExtendFormProps>, FormActions], provideFormProps: (contextValue: [ExtendFormProps | ComputedRef<ExtendFormProps>, FormActions]) => [ExtendFormProps | ComputedRef<ExtendFormProps>, FormActions];
 export declare const injectComponentRefMap: <T extends Map<string, unknown> | null | undefined = Map<string, unknown>>(fallback?: T | undefined) => T extends null ? Map<string, unknown> | null : Map<string, unknown>, provideComponentRefMap: (contextValue: Map<string, unknown>) => Map<string, unknown>;
 /** 提取单个字段默认值：defaultValue 优先，其次 Zod rules */
@@ -15,6 +16,14 @@ export declare function resolveSchemaItemDefaultValue(item: FormSchema): unknown
  * - 父行合并后会对嵌套数组递归补全（空嵌套数组、部分行缺字段）
  */
 export declare function resolveArrayFieldInitialValue(item: FormSchema): unknown;
+/**
+ * @description 解析单个字段的初始值（与 useFormInitial.generateInitialValues 单字段逻辑一致）
+ */
+export declare function resolveSchemaFieldInitialValue(item: FormSchema): unknown | undefined;
+/**
+ * @description appendFields 时判断是否需要为新字段写入初始值（不覆盖已有非空数据）
+ */
+export declare function shouldSeedAppendedFieldValue(values: Record<string, unknown>, item: FormSchema): boolean;
 export declare function useFormInitial(props: ComputedRef<TtFormProps> | TtFormProps): {
     delegatedSlots: ComputedRef<string[]>;
     form: import('vee-validate').FormContext<Record<string, unknown>, Record<string, unknown>>;

package/dist/components/tt-form/src/utils/array-path.d.ts

@@ -1,7 +1,17 @@
 /** 一层嵌套：父路径 + 行索引 + 子字段名 */
 export type ArrayPathSegment = readonly [index: number, field: string];
 /**
- * 拼接数组子路径；仅传 parentPath 时原样返回（完整路径）
+ * 规范化为数组字段注册键：将标识符后的 `.[数字]` 折叠为 `[数字]`。
+ * 与 {@link FormArrayRegister} 中 `fieldName[index]` 的拼接方式对齐。
+ * @example normalizeArrayFieldPath('feeTickets.[0].feeDetails') => 'feeTickets[0].feeDetails'
+ */
+export declare function normalizeArrayFieldPath(path: string): string;
+/**
+ * 生成同一数组字段的等价路径别名（注册 / 查找时共用）
+ */
+export declare function collectArrayFieldPathAliases(path: string): string[];
+/**
+ * 拼接数组子路径；仅传 parentPath 时原样返回（完整路径，会规范化）
  * @returns 如 `actions.data[0].skills`
  */
 export declare function childArrayPath(parentPath: string, index?: number, childField?: string): string;