@zboson/ui 0.0.0-stage → 0.0.2

package/dist/form/FormItemInput.js

@@ -0,0 +1,162 @@
+import { FormItemPrefixContextProvider, useFormContext, useFormContextProvider } from "./context.js";
+import { getSlotPropsFnRun } from "../_util/tools.js";
+import { isRenderable } from "../_util/is.js";
+import { responsiveArrayReversed } from "../_util/responsiveObserver.js";
+import Col from "../grid/col.js";
+import ErrorList from "./ErrorList.js";
+import fallbackCmp_default from "./style/fallbackCmp.js";
+import { Fragment, computed, createVNode, defineComponent, isVNode, mergeProps, nextTick, shallowRef, watch } from "vue";
+import { clsx, get, set } from "@v-c/util";
+import { filterEmpty } from "@v-c/util/dist/props-util";
+import { omit } from "es-toolkit";
+//#region src/form/FormItemInput.tsx
+function _isSlot(s) {
+	return typeof s === "function" || Object.prototype.toString.call(s) === "[object Object]" && !isVNode(s);
+}
+const GRID_MAX = 24;
+const FormItemInput = /* @__PURE__ */ defineComponent((props, { slots }) => {
+	const baseClassName = computed(() => `${props.prefixCls}-item`);
+	const formContext = useFormContext();
+	const contextClassNames = computed(() => formContext.value?.classes ?? {});
+	const contextStyles = computed(() => formContext.value?.styles ?? {});
+	const extraRef = shallowRef();
+	const extraHeight = shallowRef(0);
+	watch(() => props.extra, async () => {
+		await nextTick();
+		if (isRenderable(props.extra) && extraRef.value) extraHeight.value = extraRef.value.clientHeight;
+		else extraHeight.value = 0;
+	}, { immediate: true });
+	useFormContextProvider(computed(() => omit(formContext.value ?? {}, ["labelCol", "wrapperCol"])));
+	return () => {
+		const { wrapperCol, labelCol, marginBottom, warnings, errors, prefixCls, status, fieldId, onErrorVisibleChanged } = props;
+		const label = getSlotPropsFnRun({}, props, "label");
+		const extra = getSlotPropsFnRun({}, props, "extra");
+		const hasExtra = isRenderable(extra);
+		const help = getSlotPropsFnRun({}, props, "help");
+		const children = filterEmpty(slots?.default?.() ?? []);
+		const mergedWrapperColFn = () => {
+			let mergedWrapper = { ...wrapperCol || formContext.value?.wrapperCol || {} };
+			if (label === null && !labelCol && !wrapperCol && formContext.value?.labelCol) [void 0, ...responsiveArrayReversed].forEach((size) => {
+				const _size = size ? [size] : [];
+				const formLabel = get(formContext?.value?.labelCol, _size);
+				const formLabelObj = typeof formLabel === "object" ? formLabel : {};
+				const wrapper = get(mergedWrapper, _size);
+				const wrapperObj = typeof wrapper === "object" ? wrapper : {};
+				if ("span" in formLabelObj && !("offset" in wrapperObj) && formLabelObj.span < GRID_MAX) mergedWrapper = set(mergedWrapper, [..._size, "offset"], formLabelObj.span);
+			});
+			return mergedWrapper;
+		};
+		const mergedWrapperCol = mergedWrapperColFn();
+		const className = clsx(`${baseClassName.value}-control`, mergedWrapperCol?.class);
+		const inputDom = createVNode("div", { "class": `${baseClassName.value}-control-input` }, [createVNode("div", {
+			"class": clsx(`${baseClassName.value}-control-input-content`, contextClassNames.value?.content),
+			"style": contextStyles.value?.content
+		}, [children])]);
+		const errorListDom = marginBottom !== null || errors.length || warnings.length ? createVNode(FormItemPrefixContextProvider, {
+			"prefixCls": prefixCls,
+			"status": status
+		}, { default: () => [createVNode(ErrorList, {
+			"fieldId": fieldId,
+			"errors": errors,
+			"warnings": warnings,
+			"help": help,
+			"helpStatus": status,
+			"class": clsx(`${baseClassName.value}-explain-connected`, contextClassNames.value?.help),
+			"helpItemClassName": contextClassNames.value?.helpItem,
+			"helpItemStyle": contextStyles.value?.helpItem,
+			"style": contextStyles.value?.help,
+			"onVisibleChanged": onErrorVisibleChanged
+		}, null)] }) : null;
+		const extraProps = {};
+		if (fieldId) extraProps.id = `${fieldId}_extra`;
+		const extraDom = hasExtra ? createVNode("div", mergeProps(extraProps, {
+			"class": clsx(`${baseClassName.value}-extra`, contextClassNames.value?.extra),
+			"style": contextStyles.value?.extra,
+			"ref": extraRef
+		}), [extra]) : null;
+		const dom = createVNode(Fragment, null, [inputDom, errorListDom || extraDom ? createVNode("div", {
+			"class": `${baseClassName.value}-additional`,
+			"style": marginBottom ? { minHeight: `${marginBottom + extraHeight.value}px` } : {}
+		}, [errorListDom, extraDom]) : null]);
+		return createVNode(Fragment, null, [createVNode(Col, mergeProps(mergedWrapperCol, { "class": className }), _isSlot(dom) ? dom : { default: () => [dom] }), createVNode(fallbackCmp_default, { "prefixCls": prefixCls }, null)]);
+	};
+}, {
+	props: {
+		labelCol: {
+			type: Object,
+			required: false
+		},
+		wrapperCol: {
+			type: Object,
+			required: false
+		},
+		extra: {
+			type: [
+				Function,
+				String,
+				Number,
+				null,
+				Object,
+				Boolean
+			],
+			required: false,
+			default: void 0
+		},
+		status: {
+			type: String,
+			required: false
+		},
+		help: {
+			type: [
+				Function,
+				String,
+				Number,
+				null,
+				Object,
+				Boolean
+			],
+			required: false,
+			default: void 0
+		},
+		fieldId: {
+			type: String,
+			required: false
+		},
+		label: {
+			type: [
+				Function,
+				String,
+				Number,
+				null,
+				Object,
+				Boolean
+			],
+			required: false,
+			default: void 0
+		},
+		prefixCls: {
+			type: String,
+			required: true
+		},
+		errors: {
+			type: Array,
+			required: true
+		},
+		warnings: {
+			type: Array,
+			required: true
+		},
+		marginBottom: {
+			type: [Number, null],
+			required: false
+		},
+		onErrorVisibleChanged: {
+			type: Function,
+			required: false
+		}
+	},
+	name: "FormItemInput",
+	inheritAttrs: false
+});
+//#endregion
+export { FormItemInput as default };

package/dist/form/FormItemLabel.d.ts

@@ -0,0 +1,36 @@
+import { VueNode } from "../_util/type.js";
+import { ColProps } from "../grid/col.js";
+import "../grid/index.js";
+import { TooltipProps } from "../tooltip/index.js";
+import { FormLabelAlign } from "./interface.js";
+import { RequiredMark } from "./Form.js";
+//#region src/form/FormItemLabel.d.ts
+type FormTooltipProps = TooltipProps & {
+  icon?: VueNode;
+};
+type FormItemTooltipType = FormTooltipProps | VueNode;
+type ColPropsWithClass = ColProps & {
+  class?: string;
+};
+interface FormItemLabelProps {
+  colon?: boolean;
+  htmlFor?: string;
+  label?: VueNode;
+  labelAlign?: FormLabelAlign;
+  labelCol?: ColPropsWithClass;
+  /**
+   * @internal Used for pass `requiredMark` from `<Form />`
+   */
+  requiredMark?: RequiredMark;
+  tooltip?: FormItemTooltipType;
+  vertical?: boolean;
+}
+declare const FormItemLabel: import("vue").DefineSetupFnComponent<FormItemLabelProps & {
+  required?: boolean;
+  prefixCls: string;
+}, {}, {}, FormItemLabelProps & {
+  required?: boolean;
+  prefixCls: string;
+} & {}, import("vue").PublicProps>;
+//#endregion
+export { ColPropsWithClass, FormItemLabelProps, FormItemTooltipType, FormTooltipProps, FormItemLabel as default };

package/dist/form/FormItemLabel.js

@@ -0,0 +1,134 @@
+import { useFormContext } from "./context.js";
+import { getSlotPropsFnRun } from "../_util/tools.js";
+import InternalTooltip from "../tooltip/index.js";
+import { isRenderable } from "../_util/is.js";
+import localeValues from "../locale/en_US.js";
+import useLocale from "../locale/useLocale.js";
+import Col from "../grid/col.js";
+import convertToTooltipProps from "../_util/convertToTooltipProps.js";
+import { Fragment, createVNode, defineComponent, mergeProps } from "vue";
+import { clsx } from "@v-c/util";
+import { QuestionCircleOutlined } from "@zboson/icons";
+import { omit } from "es-toolkit";
+//#region src/form/FormItemLabel.tsx
+const FormItemLabel = /* @__PURE__ */ defineComponent((props, { slots }) => {
+	const [formLocale] = useLocale("Form");
+	const formContext = useFormContext();
+	return () => {
+		const { labelCol, labelAlign, prefixCls, required, colon, vertical, tooltip, requiredMark, htmlFor } = props;
+		const { labelAlign: contextLabelAlign, labelCol: contextLabelCol, labelWrap, colon: contextColon, classes: contextClassNames, styles: contextStyles, tooltip: contextTooltip } = formContext.value;
+		const label = getSlotPropsFnRun(slots, props, "label");
+		if (!isRenderable(label)) return null;
+		const mergedLabelCol = labelCol || contextLabelCol || {};
+		const mergedLabelAlign = labelAlign || contextLabelAlign;
+		const labelClsBasic = `${prefixCls}-item-label`;
+		const labelColClassName = clsx(labelClsBasic, mergedLabelAlign === "left" && `${labelClsBasic}-left`, mergedLabelCol.class, { [`${labelClsBasic}-wrap`]: !!labelWrap });
+		let labelChildren = label;
+		const computedColon = colon === true || contextColon !== false && colon !== false;
+		if (computedColon && !vertical && typeof label === "string" && label.trim()) labelChildren = label.replace(/[:：]\s*$/, "");
+		const tooltipProps = convertToTooltipProps(tooltip, contextTooltip);
+		if (tooltipProps) {
+			const { ...restTooltipProps } = tooltipProps;
+			const icon = getSlotPropsFnRun({}, tooltipProps, "icon") ?? createVNode(QuestionCircleOutlined, null, null);
+			const tooltipNode = createVNode(InternalTooltip, omit(restTooltipProps, ["icon"]), { default: () => [createVNode("span", {
+				"class": `${prefixCls}-item-tooltip`,
+				"onClick": (e) => {
+					e.preventDefault();
+				},
+				"tabindex": -1
+			}, [icon])] });
+			labelChildren = createVNode(Fragment, null, [labelChildren, tooltipNode]);
+		}
+		const isOptionalMark = requiredMark === "optional";
+		const isRenderMark = typeof requiredMark === "function";
+		const hideRequiredMark = requiredMark === false;
+		if (isRenderMark) labelChildren = requiredMark(labelChildren, { required: !!required });
+		else if (isOptionalMark && !required) labelChildren = createVNode(Fragment, null, [labelChildren, createVNode("span", {
+			"class": `${prefixCls}-item-optional`,
+			"title": ""
+		}, [formLocale?.value?.optional || localeValues.Form?.optional])]);
+		let markType;
+		if (hideRequiredMark) markType = "hidden";
+		else if (isOptionalMark || isRenderMark) markType = "optional";
+		const labelClassName = clsx(contextClassNames?.label, {
+			[`${prefixCls}-item-required`]: required,
+			[`${prefixCls}-item-required-mark-${markType}`]: markType,
+			[`${prefixCls}-item-no-colon`]: !computedColon
+		});
+		return createVNode(Col, mergeProps(mergedLabelCol, { "class": labelColClassName }), { default: () => [createVNode("label", mergeProps(htmlFor ? { htmlFor } : {}, labelClassName ? { class: labelClassName } : {}, {
+			"style": contextStyles?.label,
+			"title": typeof label === "string" ? label : ""
+		}), [labelChildren])] });
+	};
+}, {
+	props: {
+		colon: {
+			type: Boolean,
+			required: false,
+			default: void 0
+		},
+		htmlFor: {
+			type: String,
+			required: false
+		},
+		label: {
+			type: [
+				Function,
+				String,
+				Number,
+				null,
+				Object,
+				Boolean
+			],
+			required: false,
+			default: void 0
+		},
+		labelAlign: {
+			type: String,
+			required: false
+		},
+		labelCol: {
+			type: Object,
+			required: false
+		},
+		requiredMark: {
+			type: [
+				Boolean,
+				String,
+				Function
+			],
+			required: false,
+			default: void 0
+		},
+		tooltip: {
+			type: [
+				Object,
+				Function,
+				String,
+				Number,
+				null,
+				Boolean
+			],
+			required: false,
+			default: void 0
+		},
+		vertical: {
+			type: Boolean,
+			required: false,
+			default: void 0
+		},
+		required: {
+			type: Boolean,
+			required: false,
+			default: void 0
+		},
+		prefixCls: {
+			type: String,
+			required: true
+		}
+	},
+	name: "FormItemLabel",
+	inheritAttrs: false
+});
+//#endregion
+export { FormItemLabel as default };

package/dist/form/context.d.ts

@@ -0,0 +1,129 @@
+import { SemanticClassNames, SemanticStyles } from "../_util/hooks/useMergeSemantic.js";
+import "../_util/hooks/index.js";
+import { FormLabelAlign } from "./interface.js";
+import { ColPropsWithClass, FormTooltipProps } from "./FormItemLabel.js";
+import { InternalNamePath, Meta, NamePath, Rule, RulesMap, ValidateMessages } from "./types.js";
+import { FormLayout, FormSemanticName, RequiredMark } from "./Form.js";
+import { FeedbackIcons, ValidateStatus } from "./FormItem/index.js";
+import { Variant } from "../config-provider/context.js";
+import { Ref } from "vue";
+import { Key } from "@v-c/util/dist/type";
+//#region src/form/context.d.ts
+/** Form Context. Set top form style and pass to Form Item usage. */
+interface FormFieldRegister {
+  namePath: () => InternalNamePath;
+  getValue: () => any;
+  getMeta: () => Meta;
+  rules?: () => Rule[];
+  isFieldDirty?: () => boolean;
+  validateRules: (options?: Record<string, any>) => Promise<void>;
+  resetField: () => void;
+  clearValidate: () => void;
+  setFieldState?: (state: Partial<Meta> & {
+    errors?: any[];
+    warnings?: any[];
+    value?: any;
+  }) => void;
+}
+interface FormContextProps {
+  classes?: SemanticClassNames<FormSemanticName>;
+  styles?: SemanticStyles<FormSemanticName>;
+  layout: FormLayout;
+  name?: string;
+  colon?: boolean;
+  labelAlign?: FormLabelAlign;
+  labelWrap?: boolean;
+  labelCol?: ColPropsWithClass;
+  wrapperCol?: ColPropsWithClass;
+  requiredMark?: RequiredMark;
+  feedbackIcons?: FeedbackIcons;
+  model?: Record<string, any>;
+  rules?: RulesMap;
+  validateTrigger?: string | string[] | false;
+  validateMessages?: ValidateMessages;
+  preserve?: boolean;
+  clearOnDestroy?: boolean;
+  addField?: (eventKey: string, field: FormFieldRegister) => void;
+  removeField?: (eventKey: string, field?: FormFieldRegister) => void;
+  addItem?: (namePathStr: string, instance: any) => void;
+  removeItem?: (namePathStr: string) => void;
+  onValidate?: (name: InternalNamePath, status: boolean, errors: any[] | null) => void;
+  triggerValuesChange?: (namePath: InternalNamePath, value: any) => void;
+  triggerFieldsChange?: (namePathList?: InternalNamePath[]) => void;
+  getFieldValue?: (namePath: InternalNamePath) => any;
+  getFieldsValue?: (nameList?: InternalNamePath[] | true) => any;
+  tooltip?: FormTooltipProps;
+}
+declare function useFormContextProvider(value: Ref<FormContextProps>): void;
+declare function useFormContext(): Ref<FormContextProps>;
+/** Used for ErrorList only */
+interface FormItemPrefixContextProps {
+  prefixCls: string;
+  status?: ValidateStatus;
+}
+declare function useFormItemPrefixContextProvider(value: Ref<FormItemPrefixContextProps>): void;
+declare const FormItemPrefixContextProvider: import("vue").DefineSetupFnComponent<FormItemPrefixContextProps, {}, {}, FormItemPrefixContextProps & {}, import("vue").PublicProps>;
+declare function useFormItemPrefixContext(): Ref<{
+  prefixCls: string;
+}, {
+  prefixCls: string;
+} | {
+  prefixCls: string;
+}>;
+declare function useVariantContextProvider(variant: Ref<Variant | undefined>): void;
+declare function useVariantContext(): Ref<"filled" | "outlined" | "borderless" | "underlined" | undefined, "filled" | "outlined" | "borderless" | "underlined" | undefined>;
+interface FormItemStatusContextProps {
+  isFormItemInput?: boolean;
+  status?: ValidateStatus;
+  errors?: any[];
+  warnings?: any[];
+  hasFeedback?: boolean;
+  feedbackIcon?: any;
+  name?: NamePath;
+}
+declare function useFormItemInputContextProvider(value: Ref<FormItemStatusContextProps>): void;
+declare function useFormItemInputContext(): Ref<{
+  isFormItemInput?: boolean | undefined;
+  status?: ValidateStatus | undefined;
+  errors?: any[] | undefined;
+  warnings?: any[] | undefined;
+  hasFeedback?: boolean | undefined;
+  feedbackIcon?: any;
+  name?: NamePath;
+}, FormItemStatusContextProps | {
+  isFormItemInput?: boolean | undefined;
+  status?: ValidateStatus | undefined;
+  errors?: any[] | undefined;
+  warnings?: any[] | undefined;
+  hasFeedback?: boolean | undefined;
+  feedbackIcon?: any;
+  name?: NamePath;
+}>;
+/** `noStyle` Form Item Context. Used for error collection */
+type ReportMetaChange = (meta: Meta, uniqueKeys: Key[]) => void;
+declare function useNoStyleItemContextProvider(value: ReportMetaChange): void;
+declare const NoStyleItemContextProvider: import("vue").DefineSetupFnComponent<{
+  value: ReportMetaChange;
+}, {}, {}, {
+  value: ReportMetaChange;
+} & {}, import("vue").PublicProps>;
+declare function useNoStyleItemContext(): ReportMetaChange | null;
+declare const NoFormStyle: import("vue").DefineSetupFnComponent<{
+  override?: boolean;
+  status?: boolean;
+}, {}, {}, {
+  override?: boolean;
+  status?: boolean;
+} & {}, import("vue").PublicProps>;
+interface FormItemProviderProps {
+  fieldId: Ref<string | undefined>;
+  triggerChange: () => void;
+  triggerBlur: () => void;
+  triggerFocus: () => void;
+  clearValidate: () => void;
+}
+declare function useFormItemProvider(value: FormItemProviderProps): void;
+declare function useFormItemContext(rest?: boolean): FormItemProviderProps | undefined;
+declare function useFormItemProviderRest(): void;
+//#endregion
+export { FormContextProps, FormFieldRegister, FormItemPrefixContextProps, FormItemPrefixContextProvider, FormItemProviderProps, FormItemStatusContextProps, NoFormStyle, NoStyleItemContextProvider, ReportMetaChange, useFormContext, useFormContextProvider, useFormItemContext, useFormItemInputContext, useFormItemInputContextProvider, useFormItemPrefixContext, useFormItemPrefixContextProvider, useFormItemProvider, useFormItemProviderRest, useNoStyleItemContext, useNoStyleItemContextProvider, useVariantContext, useVariantContextProvider };

package/dist/form/context.js

@@ -0,0 +1,117 @@
+import { computed, defineComponent, inject, provide, ref } from "vue";
+//#region src/form/context.tsx
+/** Form Context. Set top form style and pass to Form Item usage. */
+const FormContextKey = Symbol("FormContextKey");
+function useFormContextProvider(value) {
+	provide(FormContextKey, value);
+}
+function useFormContext() {
+	return inject(FormContextKey, ref({
+		labelAlign: "right",
+		layout: "horizontal"
+	}));
+}
+const FormItemPrefixContextKey = Symbol("FormItemPrefixContextKey");
+/** Used for ErrorList only */
+function useFormItemPrefixContextProvider(value) {
+	provide(FormItemPrefixContextKey, value);
+}
+const FormItemPrefixContextProvider = /* @__PURE__ */ defineComponent((props, { slots }) => {
+	useFormItemPrefixContextProvider(computed(() => props));
+	return () => {
+		return slots?.default?.();
+	};
+}, { props: {
+	prefixCls: {
+		type: String,
+		required: true
+	},
+	status: {
+		type: String,
+		required: false
+	}
+} });
+function useFormItemPrefixContext() {
+	return inject(FormItemPrefixContextKey, ref({ prefixCls: "" }));
+}
+const VariantContextKey = Symbol("VariantContextKey");
+function useVariantContextProvider(variant) {
+	provide(VariantContextKey, variant);
+}
+function useVariantContext() {
+	return inject(VariantContextKey, ref(void 0));
+}
+const FormItemInputContextKey = Symbol("FormItemInputContextKey");
+function useFormItemInputContextProvider(value) {
+	provide(FormItemInputContextKey, value);
+}
+function useFormItemInputContext() {
+	return inject(FormItemInputContextKey, ref({}));
+}
+/** `noStyle` Form Item Context. Used for error collection */
+const NoStyleItemContextKey = Symbol("NoStyleItemContextKey");
+function useNoStyleItemContextProvider(value) {
+	provide(NoStyleItemContextKey, value);
+}
+const NoStyleItemContextProvider = /* @__PURE__ */ defineComponent((props, { slots }) => {
+	useNoStyleItemContextProvider(props.value);
+	return () => {
+		return slots?.default?.();
+	};
+}, {
+	props: { value: {
+		type: Function,
+		required: true
+	} },
+	name: "NoStyleItemContext"
+});
+function useNoStyleItemContext() {
+	return inject(NoStyleItemContextKey, null);
+}
+const NoFormStyle = /* @__PURE__ */ defineComponent((props, { slots }) => {
+	const formItemInputContext = useFormItemInputContext();
+	useFormItemInputContextProvider(computed(() => {
+		const { override, status } = props;
+		const newContext = { ...formItemInputContext.value };
+		if (override) delete newContext.isFormItemInput;
+		if (status) {
+			delete newContext.status;
+			delete newContext.hasFeedback;
+			delete newContext.feedbackIcon;
+		}
+		return newContext;
+	}));
+	return () => {
+		return slots?.default?.();
+	};
+}, { props: {
+	override: {
+		type: Boolean,
+		required: false,
+		default: void 0
+	},
+	status: {
+		type: Boolean,
+		required: false,
+		default: void 0
+	}
+} });
+const FormItemProviderContextKey = Symbol("FormItemProviderContextKey");
+function useFormItemProvider(value) {
+	provide(FormItemProviderContextKey, value);
+}
+function useFormItemContext(rest = false) {
+	if (rest) useFormItemProviderRest();
+	return inject(FormItemProviderContextKey, void 0);
+}
+function useFormItemProviderRest() {
+	return provide(FormItemProviderContextKey, {
+		fieldId: ref(void 0),
+		triggerChange: () => {},
+		triggerBlur: () => {},
+		clearValidate: () => {},
+		triggerFocus: () => {}
+	});
+}
+//#endregion
+export { FormItemPrefixContextProvider, NoFormStyle, NoStyleItemContextProvider, useFormContext, useFormContextProvider, useFormItemContext, useFormItemInputContext, useFormItemInputContextProvider, useFormItemPrefixContext, useFormItemPrefixContextProvider, useFormItemProvider, useFormItemProviderRest, useNoStyleItemContext, useNoStyleItemContextProvider, useVariantContext, useVariantContextProvider };

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

@@ -0,0 +1,38 @@
+import { NamePath } from "../types.js";
+import { FormInstance } from "../Form.js";
+import { InjectionKey, ShallowRef } from "vue";
+//#region src/form/hooks/useForm.d.ts
+declare function toNamePathStr(name: NamePath): string;
+interface FormHookEntry {
+  name?: string;
+  instanceRef: ShallowRef<FormInstance | undefined>;
+  /** Current owner of this entry: a Form component uid, or 'explicit' for template ref binding */
+  boundBy?: number | 'explicit';
+}
+interface FormHookRegistry {
+  entries: FormHookEntry[];
+}
+declare const FormHookRegistryKey: InjectionKey<FormHookRegistry>;
+declare const FormInstanceContextKey: InjectionKey<FormInstance>;
+type FormHookInstance = FormInstance & ((instance: any) => void);
+/**
+ * Create a form instance proxy before the Form component mounts.
+ *
+ * Binding (priority order):
+ * 1. Explicit: pass it as a template ref — `<Form :ref="form">`.
+ * 2. By name: `useForm('login')` connects to `<Form name="login">`.
+ * 3. Single/ordered fallback: unnamed instances connect to descendant Forms in declaration order.
+ *
+ * ⚠️ Do NOT destructure the returned value. The result is a lazy Proxy that
+ * resolves methods off the real instance on each access — destructuring
+ * (`const { validateFields } = useForm()`) snapshots the method before the
+ * Form mounts, capturing a no-op and losing connection to the instance.
+ * Always keep the whole reference: `const form = useForm()` then `form.xxx()`.
+ */
+declare function useForm(name?: string): FormHookInstance;
+/**
+ * Get the closest Form instance from context. Only usable inside a Form.
+ */
+declare function useFormInstance(): FormInstance;
+//#endregion
+export { FormHookEntry, FormHookInstance, FormHookRegistry, FormHookRegistryKey, FormInstanceContextKey, toNamePathStr, useForm, useFormInstance };

package/dist/form/hooks/useForm.js

@@ -0,0 +1,72 @@
+import { toArray } from "../util.js";
+import { getCurrentInstance, inject, provide, shallowRef } from "vue";
+import { warning } from "@v-c/util/dist/warning";
+//#region src/form/hooks/useForm.ts
+function toNamePathStr(name) {
+	return toArray(name).join("_");
+}
+const FormHookRegistryKey = Symbol("AFormHookRegistry");
+const FormInstanceContextKey = Symbol("AFormInstance");
+const registryMap = /* @__PURE__ */ new WeakMap();
+function useFormHookRegistry() {
+	const vm = getCurrentInstance();
+	if (!vm) return { entries: [] };
+	let registry = registryMap.get(vm);
+	if (!registry) {
+		registry = { entries: [] };
+		registryMap.set(vm, registry);
+		provide(FormHookRegistryKey, registry);
+	}
+	return registry;
+}
+/**
+* Create a form instance proxy before the Form component mounts.
+*
+* Binding (priority order):
+* 1. Explicit: pass it as a template ref — `<Form :ref="form">`.
+* 2. By name: `useForm('login')` connects to `<Form name="login">`.
+* 3. Single/ordered fallback: unnamed instances connect to descendant Forms in declaration order.
+*
+* ⚠️ Do NOT destructure the returned value. The result is a lazy Proxy that
+* resolves methods off the real instance on each access — destructuring
+* (`const { validateFields } = useForm()`) snapshots the method before the
+* Form mounts, capturing a no-op and losing connection to the instance.
+* Always keep the whole reference: `const form = useForm()` then `form.xxx()`.
+*/
+function useForm(name) {
+	const instanceRef = shallowRef();
+	const registry = useFormHookRegistry();
+	const entry = {
+		name,
+		instanceRef
+	};
+	registry.entries.push(entry);
+	const bindTemplateRef = (exposed) => {
+		if (exposed) {
+			entry.boundBy = "explicit";
+			instanceRef.value = exposed;
+		} else if (entry.boundBy === "explicit") {
+			entry.boundBy = void 0;
+			instanceRef.value = void 0;
+		}
+	};
+	return new Proxy(bindTemplateRef, { get(_target, key) {
+		if (key === "__instanceRef") return instanceRef;
+		if (typeof key === "symbol" || key === "then" || key.startsWith("__v_")) return;
+		const instance = instanceRef.value;
+		if (!instance) {
+			warning(false, "Instance created by `useForm` is not connected to any Form element. Forget to bind it via template ref or a matching `name`?");
+			return () => void 0;
+		}
+		const value = instance[key];
+		return typeof value === "function" ? value.bind(instance) : value;
+	} });
+}
+/**
+* Get the closest Form instance from context. Only usable inside a Form.
+*/
+function useFormInstance() {
+	return inject(FormInstanceContextKey, void 0);
+}
+//#endregion
+export { FormHookRegistryKey, FormInstanceContextKey, toNamePathStr, useForm, useFormInstance };