@schemx/vue 0.1.20

package/README.md

@@ -0,0 +1,136 @@
+# @schemx/vue
+
+Vue 3 adapter for schemx.
+
+`@schemx/vue` 将 `@schemx/core` 的表单实例和 ViewSchemas 渲染为 Vue 组件树。它不绑定具体 UI 组件库，适合接入业务组件、设计系统或新的 UI adapter。
+
+如果项目使用 Vant，推荐直接安装 [`@schemx/vant`](../vant)。该包已经注册好常用移动端表单 renderer。
+
+## 特性
+
+- 提供 Vue 3 表单组件和 Composition API。
+- 通过 `rendererRegistry` 注册自定义 renderer。
+- 支持 `v-model`、`initialValues`、表单级事件和实例方法。
+- 复用 `@schemx/core` 的字段依赖、校验、运行时 schema node 和 ViewSchemas。
+- 直接导出 `@schemx/core` 的公开类型与工具。
+
+## 安装
+
+```bash
+pnpm add @schemx/vue vue
+```
+
+## 快速开始
+
+`@schemx/vue` 默认不提供具体输入控件。使用前需要注册 renderer：
+
+```ts
+import { markRaw } from "vue"
+
+import { rendererRegistry } from "@schemx/vue"
+
+import InputRenderer from "./components/InputRenderer.vue"
+
+rendererRegistry.register("input", markRaw(InputRenderer))
+```
+
+然后通过默认导出的 `Schemx` 组件渲染表单：
+
+```vue
+<script setup lang="ts">
+  import { ref } from "vue"
+
+  import Schemx from "@schemx/vue"
+
+  import type { SchemxField } from "@schemx/vue"
+
+  type ProfileValues = {
+    nickname: string
+  }
+
+  const formData = ref<ProfileValues>({
+    nickname: "",
+  })
+
+  const schemas: SchemxField<ProfileValues>[] = [
+    {
+      name: "nickname",
+      label: "昵称",
+      componentType: "input",
+      rules: "required",
+      placeholder: "请输入昵称",
+    },
+  ]
+</script>
+
+<template>
+  <Schemx v-model="formData" :schemas="schemas" />
+</template>
+```
+
+## 自定义 Renderer
+
+renderer 会接收到 `value`、`onUpdate:value`、`onChange`、`onBlur`、`readonly`、`disabled` 和 `placeholder` 等公共属性。可以使用标准 Vue 事件更新字段值：
+
+```vue
+<script setup lang="ts">
+  defineProps<{
+    value?: string
+    readonly?: boolean
+    disabled?: boolean
+    placeholder?: string
+  }>()
+
+  const emit = defineEmits<{
+    "update:value": [value: string]
+    change: [value: string]
+    blur: [value: string]
+  }>()
+</script>
+
+<template>
+  <input
+    :value="value"
+    :readonly="readonly"
+    :disabled="disabled"
+    :placeholder="placeholder"
+    @input="emit('update:value', ($event.target as HTMLInputElement).value)"
+    @change="emit('change', ($event.target as HTMLInputElement).value)"
+    @blur="emit('blur', ($event.target as HTMLInputElement).value)"
+  />
+</template>
+```
+
+也可以为单个表单实例传入独立的 registry：
+
+```ts
+import { createRendererRegistry } from "@schemx/vue"
+
+const rendererRegistry = createRendererRegistry("input")
+
+rendererRegistry.register("input", InputRenderer)
+```
+
+```vue
+<Schemx :schemas="schemas" :renderer-registry="rendererRegistry" />
+```
+
+## Composition API
+
+| API                 | 说明                                          |
+| ------------------- | --------------------------------------------- |
+| `useForm()`         | 创建表单实例，并通过 Vue context 提供给子组件 |
+| `useField()`        | 获取字段级读写、校验和状态能力                |
+| `useWatch()`        | 监听字段变化                                  |
+| `useWatchField()`   | 监听单个字段                                  |
+| `useWatchFields()`  | 监听多个字段                                  |
+| `useWatchAll()`     | 监听整张表单                                  |
+| `useDictionary()`   | 管理依赖字段的远程或本地选项                  |
+| `useEffect()`       | 创建字段依赖追踪 effect                       |
+| `useFieldContext()` | 获取当前字段上下文                            |
+
+## Adapter 边界
+
+Vue 适配层只负责将 core 输出的 ViewSchemas 映射为 Vue 组件树。descriptor 编译、dependency 执行、validation、scheduler 和 node 生命周期由 `@schemx/core` 管理。
+
+自定义 adapter 应优先使用 `form.getViewSchemas()`、`form.subscribeViewSchemas()` 和 `form.registerRenderer()` 等公开 API，避免依赖 core 内部目录。

package/dist/components/FormGroup/index.d.ts

@@ -0,0 +1,17 @@
+import { SchemxViewGroupSchema, Values } from '@schemx/core';
+
+/**
+ * FormGroup Props
+ *
+ * @typeParam T - 表单值类型
+ */
+export interface SchemxGroupProps<T extends Values = Values> {
+    schema: SchemxViewGroupSchema<T>;
+}
+declare const FormGroup: import('vue').DefineSetupFnComponent<{
+    schema: SchemxViewGroupSchema;
+}, {}, {}, {
+    schema: SchemxViewGroupSchema;
+} & {}, import('vue').PublicProps>;
+export default FormGroup;
+//# sourceMappingURL=index.d.ts.map

package/dist/components/FormGroup/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/FormGroup/index.tsx"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AASH,OAAO,KAAK,EAAE,qBAAqB,EAAoB,MAAM,EAAE,MAAM,cAAc,CAAA;AAEnF;;;;GAIG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IACzD,MAAM,EAAE,qBAAqB,CAAC,CAAC,CAAC,CAAA;CACjC;AAED,QAAA,MAAM,SAAS;;;;kCAyEd,CAAA;AAED,eAAe,SAAS,CAAA"}

package/dist/components/FormItem/index.d.ts

@@ -0,0 +1,17 @@
+import { SchemxViewSchema, Values } from '@schemx/core';
+
+/**
+ * FormItem 属性。
+ *
+ * @typeParam T - 表单值类型
+ */
+export interface SchemxItemProps<T extends Values = Values> {
+    schema: SchemxViewSchema<T>;
+}
+declare const FormItem: import('vue').DefineSetupFnComponent<{
+    schema: SchemxViewSchema;
+}, {}, {}, {
+    schema: SchemxViewSchema;
+} & {}, import('vue').PublicProps>;
+export default FormItem;
+//# sourceMappingURL=index.d.ts.map

package/dist/components/FormItem/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/FormItem/index.tsx"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAkBH,OAAO,KAAK,EAOV,gBAAgB,EAChB,MAAM,EACP,MAAM,cAAc,CAAA;AAErB;;;;GAIG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IACxD,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAA;CAC5B;AAED,QAAA,MAAM,QAAQ;;;;kCAyPb,CAAA;AAED,eAAe,QAAQ,CAAA"}

package/dist/form.d.ts

@@ -0,0 +1,34 @@
+import { App, DefineComponent } from 'vue';
+import { default as FormItem } from './components/FormItem';
+import { SchemxFormProps } from './types';
+
+/**
+ * SchemxForm 插件安装选项
+ *
+ * 在 `app.use(SchemxForm, options)` 时传入，用于配置全局默认行为。
+ *
+ * @example
+ * ```ts
+ * import SchemxForm from '@schemx/vue'
+ *
+ * app.use(SchemxForm, {
+ *   request: (url) => fetch(url).then(r => r.json()),
+ * })
+ * ```
+ */
+export interface SchemxInstallOptions {
+}
+/**
+ * 为组件挂载静态属性并保留原始类型
+ *
+ * @param comp - 原始组件
+ * @param extra - 要挂载的静态属性
+ */
+export declare function withInstall<T extends object, E extends Record<string, unknown>>(comp: T, extra: E): T & E;
+export type SchemxFormPlugin = DefineComponent<SchemxFormProps> & {
+    install: (app: App, options?: SchemxInstallOptions) => void;
+    FormItem: typeof FormItem;
+};
+declare const SchemxFormExport: SchemxFormPlugin;
+export default SchemxFormExport;
+//# sourceMappingURL=form.d.ts.map

package/dist/form.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"form.d.ts","sourceRoot":"","sources":["../src/form.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,eAAe,EAAE,MAAM,KAAK,CAAA;AAE/C,OAAO,QAAQ,MAAM,uBAAuB,CAAA;AAG5C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,oBAAoB;CAAG;AAExC;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7E,IAAI,EAAE,CAAC,EACP,KAAK,EAAE,CAAC,GAE6B,CAAC,GAAG,CAAC,CAC3C;AAED,MAAM,MAAM,gBAAgB,GAAG,eAAe,CAAC,eAAe,CAAC,GAAG;IAChE,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,oBAAoB,KAAK,IAAI,CAAA;IAC3D,QAAQ,EAAE,OAAO,QAAQ,CAAA;CAC1B,CAAA;AAED,QAAA,MAAM,gBAAgB,EAOL,gBAAgB,CAAA;AAEjC,eAAe,gBAAgB,CAAA"}

package/dist/hocs/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 高阶组件（HOC）模块
+ *
+ * 提供用于增强渲染器组件能力的高阶组件函数。
+ *
+ * @module hocs
+ */
+export { WithRemoteOptions } from './withRemoteOptions';
+export type { SchemxDictionary, SchemxWithDictionary } from './withRemoteOptions';
+//# sourceMappingURL=index.d.ts.map

package/dist/hocs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hocs/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAEvD,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA"}

package/dist/hocs/withRemoteOptions.d.ts

@@ -0,0 +1,74 @@
+import { Component, PropType } from 'vue';
+import { NamePath, SchemxDictionary } from '@schemx/core';
+
+export type { SchemxDictionary, SchemxWithDictionary } from '@schemx/core';
+/**
+ * WithRemoteOptions 注入给被包装组件的额外 Props
+ */
+export interface RemoteOptionsInjectedProps {
+    /** 加载的选项列表 */
+    options: any[];
+    /** 加载状态 */
+    loading: boolean;
+}
+/**
+ * 选项高阶组件
+ *
+ * 包装一个渲染器组件，当 dict prop 存在时，
+ * 调用 useDictionary 加载选项，并将结果作为 options prop 注入。
+ *
+ * 当组件自身已传入非空 options 且无 dict 时，优先使用静态 options。
+ *
+ * @param WrappedComponent - 被包装的渲染器组件
+ * @returns 增强后的组件，自动具备选项加载能力
+ *
+ * @example
+ * ```ts
+ * import { WithRemoteOptions } from '@schemx/vue'
+ * import MySelect from './MySelect.vue'
+ *
+ * const RemoteSelect = WithRemoteOptions(MySelect)
+ *
+ * // 在 schema 中使用
+ * const schema = {
+ *   name: 'city',
+ *   label: '城市',
+ *   componentType: 'select',
+ *   componentProps: {
+ *     dict: {
+ *       api: async (values) => fetchCities(values.province),
+ *       dependsOn: ['province'],
+ *       shouldFetch: (values) => !!values.province,
+ *       resetOnDepsChange: true,
+ *       immediate: false,
+ *     },
+ *   },
+ * }
+ * ```
+ */
+export declare function WithRemoteOptions(WrappedComponent: Component): import('vue').DefineComponent<import('vue').ExtractPropTypes<{
+    dict: {
+        type: PropType<SchemxDictionary>;
+        default: undefined;
+    };
+    fieldName: {
+        type: PropType<NamePath>;
+        default: undefined;
+    };
+}>, () => import('vue').VNode<import('vue').RendererNode, import('vue').RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{
+    dict: {
+        type: PropType<SchemxDictionary>;
+        default: undefined;
+    };
+    fieldName: {
+        type: PropType<NamePath>;
+        default: undefined;
+    };
+}>> & Readonly<{}>, {
+    dict: SchemxDictionary<import('@schemx/core').Values, any>;
+    fieldName: string;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;
+export default WithRemoteOptions;
+//# sourceMappingURL=withRemoteOptions.d.ts.map

package/dist/hocs/withRemoteOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"withRemoteOptions.d.ts","sourceRoot":"","sources":["../../src/hocs/withRemoteOptions.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAgC,QAAQ,EAAgB,MAAM,KAAK,CAAA;AAIrF,OAAO,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAE9D,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AAE1E;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,cAAc;IACd,OAAO,EAAE,GAAG,EAAE,CAAA;IACd,WAAW;IACX,OAAO,EAAE,OAAO,CAAA;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,iBAAiB,CAAC,gBAAgB,EAAE,SAAS;;cAMrC,QAAQ,CAAC,gBAAgB,CAAC;;;;cAIjB,QAAQ,CAAC,QAAQ,CAAC;;;;;;;cAJ3B,QAAQ,CAAC,gBAAgB,CAAC;;;;cAIjB,QAAQ,CAAC,QAAQ,CAAC;;;;;;6EAoBlD;AAED,eAAe,iBAAiB,CAAA"}

package/dist/hooks/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Hooks 统一导出
+ *
+ * @module hooks
+ */
+/** useForm - 表单状态管理 */
+export { useForm } from './useForm';
+/** useField - 单字段控制 */
+export { useField } from './useField';
+/** useWatch - 字段变化监听 */
+export { useWatch, useWatchField, useWatchFields, useWatchAll } from './useWatch';
+/** useEffect - 通用 Signal effect */
+export { useEffect } from './useEffect';
+/** useDictionary - 字典选项加载 */
+export { useDictionary, type SchemxDictionary, type SchemxWithDictionary, type UseDictOptionsReturn, } from './useDictionary';
+/** useContext - 表单上下文注入与消费 */
+export { type FormContextProps, useContext } from './useContext';
+/** useStableRef - 引用稳定化的 shallowRef */
+export { useStableRef } from './useStableRef';
+/** useViewSchemas - ViewSchemas Vue 桥接 */
+export { useViewSchemas } from './useViewSchemas';
+/** useFieldContext - 字段上下文注入与消费 */
+export { useFieldContext } from './useFieldContext';
+//# sourceMappingURL=index.d.ts.map

package/dist/hooks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,uBAAuB;AACvB,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAEnC,uBAAuB;AACvB,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAErC,wBAAwB;AACxB,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAEjF,mCAAmC;AACnC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAEvC,6BAA6B;AAC7B,OAAO,EACL,aAAa,EACb,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,GAC1B,MAAM,iBAAiB,CAAA;AAExB,8BAA8B;AAC9B,OAAO,EAAE,KAAK,gBAAgB,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAEhE,uCAAuC;AACvC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAE7C,0CAA0C;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAEjD,mCAAmC;AACnC,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/hooks/useContext.d.ts

@@ -0,0 +1,40 @@
+import { SchemxFormProps } from '../types';
+import { Values } from '@schemx/core';
+
+/** FormContext 注入 key */
+export declare const FORM_CONTEXT_KEY: unique symbol;
+/**
+ * 表单上下文属性
+ *
+ * 由 schemx 组件注入，包含表单级别的全局配置。
+ *
+ * @typeParam T - 表单值类型
+ */
+export interface FormContextProps<T extends Values = Values> extends Omit<SchemxFormProps<T>, "form" | "modelValue" | "rendererRegistry" | "defaultRendererType" | "rulesRegistery" | "onFinish" | "onFinishFailed" | "onValuesChange" | "onFieldsChange"> {
+}
+/**
+ * 创建并注入表单上下文
+ *
+ * 在 schemx 的 setup 中调用，将表单级别配置注入到子组件树中。
+ *
+ * @typeParam T - 表单值类型
+ * @param props - 表单上下文属性
+ */
+export declare const createContext: <T extends Values = Values>(props: FormContextProps<T>) => void;
+/**
+ * 获取表单上下文配置
+ *
+ * 在子组件中获取 schemx 注入的全局配置（readonly、disabled、labelAlign 等）。
+ *
+ * @returns 表单上下文属性
+ *
+ * @throws Error 如果不在 schemx 提供的上下文中调用
+ *
+ * @example
+ * ```ts
+ * const context = useContext()
+ * console.log(context.readonly, context.disabled)
+ * ```
+ */
+export declare function useContext(): FormContextProps;
+//# sourceMappingURL=useContext.d.ts.map

package/dist/hooks/useContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useContext.d.ts","sourceRoot":"","sources":["../../src/hooks/useContext.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAE1C,yBAAyB;AACzB,eAAO,MAAM,gBAAgB,eAAwB,CAAA;AAErD;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,CAAE,SAAQ,IAAI,CACvE,eAAe,CAAC,CAAC,CAAC,EAChB,MAAM,GACN,YAAY,GACZ,kBAAkB,GAClB,qBAAqB,GACrB,gBAAgB,GAChB,UAAU,GACV,gBAAgB,GAChB,gBAAgB,GAChB,gBAAgB,CACnB;CAAG;AAEJ;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,GAAI,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,OAAO,gBAAgB,CAAC,CAAC,CAAC,SAElF,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,IAAI,gBAAgB,CAQ7C"}

package/dist/hooks/useDictionary.d.ts

@@ -0,0 +1,63 @@
+import { Ref } from 'vue';
+import { FieldValue, NamePath, SchemxDictionary, Values } from '@schemx/core';
+
+export type { SchemxDictionary, SchemxWithDictionary } from '@schemx/core';
+/**
+ * useDictionary 返回值
+ */
+export interface UseDictOptionsReturn {
+    /** 远程加载的字典选项列表（响应式） */
+    list: Ref<any[]>;
+    /** 请求加载状态（响应式） */
+    loading: Ref<boolean>;
+    /** 请求错误信息（响应式） */
+    error: Ref<Error | undefined>;
+    /** 触发字典选项加载 */
+    loadDict: () => Promise<void>;
+    /** 使用当前配置重新执行 api */
+    refresh: () => Promise<void>;
+    /** 直接修改 list 的值，不触发 api 调用 */
+    mutate: (data: any[]) => void;
+}
+/**
+ * 将未知抛出值规范化为 `Error` 实例
+ *
+ * @param err - 捕获的值（可能是任意类型）
+ * @returns 包装原始值的 `Error` 对象
+ */
+export declare function normalizeError(err: unknown): Error;
+/**
+ * 加载字典选项
+ *
+ * 通过 api 函数获取数据，支持完整的表单值泛型推导。
+ * 自动在组件挂载时加载，支持依赖字段联动、竞态控制、
+ * 重试、错误处理等能力。
+ *
+ * @typeParam TValues - 表单值类型
+ * @param options - 字典配置选项
+ * @param fieldName - 当前字段名，用于 resetOnDepsChange 时清空字段值
+ * @returns 响应式选项列表、loading/error 状态及控制方法
+ *
+ * @example
+ * ```ts
+ * // 基础用法
+ * const { list } = useDictionary({
+ *   api: async () => {
+ *     const res = await fetch('/api/options')
+ *     return res.json()
+ *   },
+ * })
+ *
+ * // 依赖联动（带泛型）
+ * const { list } = useDictionary<MyFormValues>({
+ *   api: async (values) => fetchCities(values.province),
+ *   dependsOn: ['province'],
+ *   shouldFetch: (values) => !!values.province,
+ *   resetOnDepsChange: true,
+ *   immediate: false,
+ * }, 'city')
+ * ```
+ */
+export declare const useDictionary: <TValues extends Values = Values, TName extends NamePath<TValues> = NamePath<TValues>, TValue = FieldValue<TValues, TName>>(options: SchemxDictionary<TValues>, fieldName?: TName) => UseDictOptionsReturn;
+export default useDictionary;
+//# sourceMappingURL=useDictionary.d.ts.map

package/dist/hooks/useDictionary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDictionary.d.ts","sourceRoot":"","sources":["../../src/hooks/useDictionary.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAa,GAAG,EAAO,MAAM,KAAK,CAAA;AAKzC,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAElF,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AAE1E;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,uBAAuB;IACvB,IAAI,EAAE,GAAG,CAAC,GAAG,EAAE,CAAC,CAAA;IAChB,kBAAkB;IAClB,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,CAAA;IACrB,kBAAkB;IAClB,KAAK,EAAE,GAAG,CAAC,KAAK,GAAG,SAAS,CAAC,CAAA;IAC7B,eAAe;IACf,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7B,qBAAqB;IACrB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5B,8BAA8B;IAC9B,MAAM,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;CAC9B;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,KAAK,CAIlD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,aAAa,GACxB,OAAO,SAAS,MAAM,GAAG,MAAM,EAC/B,KAAK,SAAS,QAAQ,CAAC,OAAO,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,EACnD,MAAM,GAAG,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,EAEnC,SAAS,gBAAgB,CAAC,OAAO,CAAC,EAClC,YAAY,KAAK,KAChB,oBAmIF,CAAA;AAED,eAAe,aAAa,CAAA"}

package/dist/hooks/useEffect.d.ts

@@ -0,0 +1,34 @@
+import { CreateEffectReturn, EffectCallback } from '@schemx/core';
+
+/**
+ * 创建 Signal effect 并在组件卸载时自动取消。
+ *
+ * 在 effect 回调中访问任何 Signal 值时自动追踪依赖，
+ * 依赖变化时自动重新执行回调。
+ * 回调可返回一个清理函数，在 effect 重新执行前或被 dispose 时调用。
+ *
+ * @param callback - effect 回调函数，可选返回清理函数
+ *
+ * @returns 取消 effect 的 dispose 函数（通常无需手动调用，组件卸载时自动取消）
+ *
+ * @example
+ * ```ts
+ * // 监听字段值变化
+ * useEffect(() => {
+ *   const name = form.getFieldValue('name')
+ *   console.log('name changed:', name)
+ * })
+ *
+ * // 带清理函数
+ * useEffect(() => {
+ *   const timer = setInterval(() => {
+ *     console.log('value:', form.getFieldValue('count'))
+ *   }, 1000)
+ *
+ *   return () => clearInterval(timer)
+ * })
+ * ```
+ */
+export declare function useEffect(callback: EffectCallback): CreateEffectReturn;
+export default useEffect;
+//# sourceMappingURL=useEffect.d.ts.map

package/dist/hooks/useEffect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useEffect.d.ts","sourceRoot":"","sources":["../../src/hooks/useEffect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAMH,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAEtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,cAAc,GAAG,kBAAkB,CAMtE;AAED,eAAe,SAAS,CAAA"}

package/dist/hooks/useField.d.ts

@@ -0,0 +1,38 @@
+import { FieldInstance } from '../types/field';
+import { NamePath, Values } from '@schemx/core';
+
+/**
+ * 获取单个字段的控制能力
+ *
+ * 通过 core 层 createField 提供字段操作方法，
+ * 通过 subscribe 回调桥接 Signal 变化到 Vue shallowRef。
+ *
+ * @param name - 字段名（支持嵌套路径，如 'user.address.city'）
+ * @returns 字段状态和操作方法
+ *
+ * @example
+ * ```typescript
+ * const field = useField('username')
+ *
+ * // 响应式值（在 computed/watchEffect/template 中自动追踪）
+ * field.getValue()
+ *
+ * // 响应式错误
+ * field.error.value   // string[] | undefined
+ *
+ * // 响应式脏状态
+ * field.dirty.value   // boolean
+ *
+ * // 响应式操作中状态
+ * field.pending.value  // boolean
+ *
+ * // 写入值
+ * field.setValue('new value')
+ *
+ * // 校验
+ * const result = await field.validate()
+ * ```
+ */
+export declare const useField: <TValues extends Values = Values>(name: NamePath<TValues>) => FieldInstance<TValues>;
+export default useField;
+//# sourceMappingURL=useField.d.ts.map

package/dist/hooks/useField.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useField.d.ts","sourceRoot":"","sources":["../../src/hooks/useField.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAI7C,OAAO,KAAK,EAAE,QAAQ,EAAkB,MAAM,EAAE,MAAM,cAAc,CAAA;AAoEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,QAAQ,GAAI,OAAO,SAAS,MAAM,GAAG,MAAM,EACtD,MAAM,QAAQ,CAAC,OAAO,CAAC,KACtB,aAAa,CAAC,OAAO,CAuCvB,CAAA;AAED,eAAe,QAAQ,CAAA"}

package/dist/hooks/useFieldContext.d.ts

@@ -0,0 +1,23 @@
+import { Values } from '@schemx/core';
+import { FieldInstance } from '../types/field';
+import { useField } from './useField';
+
+/**
+ * 向子组件树注入当前字段上下文。
+ *
+ * 应在 FormItem（或任何创建了 useField 的组件）的 setup 中调用。
+ *
+ * @param field - useField 返回的字段实例
+ */
+export declare function provideFieldContext<TValues extends Values = Values>(field: FieldInstance<TValues>): void;
+/**
+ * 从最近的 FormItem 获取当前字段上下文。
+ *
+ * 必须在 FormItem 的组件子树内调用，否则抛出错误。
+ *
+ * @returns useField 返回的字段实例
+ *
+ * @throws 当不在 FormItem 子树内时抛出
+ */
+export declare function useFieldContext(): ReturnType<typeof useField>;
+//# sourceMappingURL=useFieldContext.d.ts.map

package/dist/hooks/useFieldContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFieldContext.d.ts","sourceRoot":"","sources":["../../src/hooks/useFieldContext.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAErC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAE7C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAK1C;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,EACjE,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,GAC5B,IAAI,CAEN;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,IAAI,UAAU,CAAC,OAAO,QAAQ,CAAC,CAQ7D"}

package/dist/hooks/useForm.d.ts

@@ -0,0 +1,59 @@
+import { CreateFormOptions, NamePath, SchemxInstance, Values } from '@schemx/core';
+
+/** SchemxInstance 在 Vue provide/inject 中的注入 key */
+export declare const SCHEMX_INSTANCE_KEY: unique symbol;
+/** @deprecated 请使用 SCHEMX_INSTANCE_KEY。保留给旧测试和旧适配代码兼容。 */
+export declare const FORM_INSTANCE_KEY: symbol;
+/**
+ * useForm 配置选项
+ *
+ * 扩展 core 层的 CreateFormOptions，增加 Vue 层特有的 request 配置。
+ *
+ * @typeParam TValues - 表单值类型
+ */
+export interface UseFormOptions<TValues extends Values> extends CreateFormOptions<TValues, NamePath<TValues>> {
+}
+/**
+ * 表单组合式函数
+ *
+ * 创建 SchemxInstance 并通过 Vue provide 注入到子组件树中，
+ * 组件卸载时自动销毁实例。
+ *
+ * @typeParam TValues - 表单值类型
+ *
+ * @param options - 表单配置选项
+ * @returns 表单实例（SchemxInstance 接口）
+ *
+ * @example
+ * ```typescript
+ * // 在 setup 中使用
+ * const form = useForm({
+ *   initialValues: { name: '', email: '' },
+ *   onFinish: async (values) => {
+ *     await api.submit(values)
+ *   },
+ * })
+ *
+ * form.setFieldValue('name', 'John')
+ * ```
+ */
+export declare function useForm<TValues extends Values = Values>(options: UseFormOptions<TValues>): SchemxInstance<TValues>;
+/**
+ * 获取表单实例
+ *
+ * 在子组件中获取 useForm 创建的 SchemxInstance，
+ * 可用于读写字段值、校验、订阅等操作。
+ *
+ * @typeParam TValues - 表单值类型
+ * @returns 表单实例
+ *
+ * @throws Error 如果不在 schemx 提供的上下文中调用
+ *
+ * @example
+ * ```ts
+ * const form = useFormInstance()
+ * form.setFieldValue('name', 'hello')
+ * ```
+ */
+export declare function useFormInstance<TValues extends Values = Values>(): SchemxInstance<TValues>;
+//# sourceMappingURL=useForm.d.ts.map

package/dist/hooks/useForm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useForm.d.ts","sourceRoot":"","sources":["../../src/hooks/useForm.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,iBAAiB,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAEvF,mDAAmD;AACnD,eAAO,MAAM,mBAAmB,eAA4B,CAAA;AAC5D,0DAA0D;AAC1D,eAAO,MAAM,iBAAiB,QAAsB,CAAA;AAEpD;;;;;;GAMG;AACH,MAAM,WAAW,cAAc,CAAC,OAAO,SAAS,MAAM,CAAE,SAAQ,iBAAiB,CAC/E,OAAO,EACP,QAAQ,CAAC,OAAO,CAAC,CAClB;CAAG;AAEJ;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,OAAO,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,EACrD,OAAO,EAAE,cAAc,CAAC,OAAO,CAAC,GAC/B,cAAc,CAAC,OAAO,CAAC,CAkBzB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAC7B,OAAO,SAAS,MAAM,GAAG,MAAM,KAC5B,cAAc,CAAC,OAAO,CAAC,CAQ3B"}

package/dist/hooks/useStableRef.d.ts

@@ -0,0 +1,28 @@
+import { ShallowRef } from 'vue';
+
+/**
+ * 创建一个引用稳定的 shallowRef。
+ *
+ * 在 watchEffect 中执行工厂函数，自动追踪响应式依赖。
+ * 仅当新旧值浅比较不相等时才替换 `.value`，保持引用稳定。
+ *
+ * @typeParam T - 对象类型
+ *
+ * @param factory - 返回目标对象的工厂函数，在 watchEffect 内执行
+ *
+ * @returns 只读的 ShallowRef，引用仅在属性值真正变化时更新
+ *
+ * @example
+ * ```ts
+ * const props = useStableRef(() => ({
+ *   value: field.getValue(),
+ *   onChange: handleChange,
+ * }))
+ *
+ * // props.value 的引用在属性值未变时保持不变
+ * h(Component, props.value)
+ * ```
+ */
+export declare function useStableRef<T extends Record<string, any>>(factory: () => T): Readonly<ShallowRef<T>>;
+export default useStableRef;
+//# sourceMappingURL=useStableRef.d.ts.map

package/dist/hooks/useStableRef.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useStableRef.d.ts","sourceRoot":"","sources":["../../src/hooks/useStableRef.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,KAAK,UAAU,EAA2B,MAAM,KAAK,CAAA;AAI9D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACxD,OAAO,EAAE,MAAM,CAAC,GACf,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAYzB;AAED,eAAe,YAAY,CAAA"}