niuma-ui 2.0.2 → 2.0.4

package/dist/components/fieldset/src/RsFieldset.css

@@ -1,74 +1,84 @@
 
-.rs-fieldset[data-v-b3043538] {
+.rs-fieldset[data-v-460cb31f] {
+  --rs-fieldset-line: var(--rs-fieldset-border);
   display: flex;
   flex-direction: column;
-  gap: var(--rs-fieldset-gap, var(--rs-space-md));
+  gap: var(--rs-fieldset-gap);
   box-sizing: border-box;
-  min-width: 0;
   min-inline-size: 0;
   margin: 0;
-  padding: var(--rs-space-md) var(--rs-space-lg) var(--rs-space-lg);
+  padding-block: var(--rs-space-md) var(--rs-space-lg);
+  padding-inline: var(--rs-space-lg);
   border-width: 1px;
   border-style: solid;
-  border-color: var(--rs-fieldset-border, var(--rs-border));
-  border-radius: var(--rs-fieldset-radius, var(--rs-radius-sm));
+  border-color: var(--rs-fieldset-line);
+  border-radius: var(--rs-fieldset-radius);
   background: transparent;
 }
-.rs-fieldset--sm[data-v-b3043538] {
-  gap: var(--rs-space-sm);
-  padding: var(--rs-space-sm) var(--rs-space-md) var(--rs-space-md);
+.rs-fieldset--sm[data-v-460cb31f] {
+  gap: var(--rs-fieldset-gap-sm);
+  padding-block: var(--rs-space-sm) var(--rs-space-md);
+  padding-inline: var(--rs-space-md);
 }
-.rs-fieldset--dashed[data-v-b3043538] {
+.rs-fieldset--dashed[data-v-460cb31f] {
   border-style: dashed;
 }
-.rs-fieldset--dotted[data-v-b3043538] {
+.rs-fieldset--dotted[data-v-460cb31f] {
   border-style: dotted;
 }
-.rs-fieldset--tone-subtle[data-v-b3043538] {
-  border-color: var(--rs-fieldset-border, var(--rs-border-subtle));
+.rs-fieldset--tone-subtle[data-v-460cb31f] {
+  --rs-fieldset-line: var(--rs-fieldset-border-subtle);
+}
+.rs-fieldset--tone-faded[data-v-460cb31f] {
+  --rs-fieldset-line: var(--rs-fieldset-border-faded);
 }
-.rs-fieldset--tone-faded[data-v-b3043538] {
-  border-color: color-mix(
-    in srgb,
-    var(--rs-fieldset-border, var(--rs-border)) 42%,
-    transparent
-  );
+.rs-fieldset[data-v-460cb31f]:disabled,
+.rs-fieldset--disabled[data-v-460cb31f] {
+  --rs-fieldset-line: var(--rs-fieldset-border-subtle);
 }
-.rs-fieldset__legend[data-v-b3043538] {
+.rs-fieldset--invalid[data-v-460cb31f],
+.rs-fieldset--invalid.rs-fieldset--disabled[data-v-460cb31f] {
+  --rs-fieldset-line: var(--rs-fieldset-border-invalid);
+}
+.rs-fieldset__legend[data-v-460cb31f] {
   display: inline-flex;
   align-items: center;
   gap: var(--rs-space-sm);
   float: none;
-  padding: 0 var(--rs-space-xs);
+  padding-inline: var(--rs-space-xs);
   margin: 0;
   font-size: var(--rs-fieldset-title-size, var(--rs-font-size-sm));
   font-weight: var(--rs-fieldset-title-weight, var(--rs-font-weight-semibold));
   line-height: var(--rs-line-height-tight);
-  color: var(--rs-text);
-  background: var(--rs-fieldset-legend-bg, var(--rs-surface));
+  color: var(--rs-fieldset-title);
+  background: var(--rs-fieldset-legend-bg);
 }
-.rs-fieldset__heading[data-v-b3043538] {
+.rs-fieldset__heading[data-v-460cb31f] {
   display: inline-flex;
   align-items: center;
   gap: var(--rs-space-xs);
-  min-width: 0;
+  min-inline-size: 0;
 }
-.rs-fieldset__title[data-v-b3043538] {
-  min-width: 0;
+.rs-fieldset__title[data-v-460cb31f] {
+  min-inline-size: 0;
   font-size: inherit;
   font-weight: inherit;
   color: inherit;
 }
-.rs-fieldset--title-strong .rs-fieldset__legend[data-v-b3043538] {
-  color: var(--rs-text);
+.rs-fieldset__required[data-v-460cb31f] {
+  margin-inline-start: var(--rs-label-mark-gap);
+  color: var(--rs-danger);
 }
-.rs-fieldset--title-default .rs-fieldset__legend[data-v-b3043538] {
-  color: var(--rs-text);
+.rs-fieldset--title-strong .rs-fieldset__legend[data-v-460cb31f] {
+  color: var(--rs-fieldset-title-strong);
 }
-.rs-fieldset--title-muted .rs-fieldset__legend[data-v-b3043538] {
-  color: var(--rs-muted);
+.rs-fieldset--title-default .rs-fieldset__legend[data-v-460cb31f] {
+  color: var(--rs-fieldset-title);
 }
-.rs-fieldset__extra[data-v-b3043538] {
+.rs-fieldset--title-muted .rs-fieldset__legend[data-v-460cb31f] {
+  color: var(--rs-fieldset-title-muted);
+}
+.rs-fieldset__extra[data-v-460cb31f] {
   display: inline-flex;
   align-items: center;
   gap: var(--rs-space-xs);
@@ -76,17 +86,37 @@
   font-weight: var(--rs-font-weight-regular);
   color: var(--rs-muted);
 }
-.rs-fieldset__body[data-v-b3043538] {
+.rs-fieldset__body[data-v-460cb31f] {
   display: flex;
   flex-direction: column;
-  min-width: 0;
+  min-inline-size: 0;
   gap: inherit;
 }
-.rs-fieldset[data-v-b3043538]:disabled,
-.rs-fieldset--disabled[data-v-b3043538] {
-  border-color: var(--rs-border-subtle);
+.rs-fieldset__hint[data-v-460cb31f] {
+  margin: 0;
+  font-size: var(--rs-font-size-xs);
+  font-weight: var(--rs-font-weight-regular);
+  line-height: var(--rs-line-height-normal);
+  color: var(--rs-fieldset-hint);
 }
-.rs-fieldset:disabled .rs-fieldset__legend[data-v-b3043538],
-.rs-fieldset--disabled .rs-fieldset__legend[data-v-b3043538] {
+.rs-fieldset__error[data-v-460cb31f] {
+  margin: 0;
+  font-size: var(--rs-font-size-xs);
+  line-height: var(--rs-line-height-normal);
+  color: var(--rs-fieldset-error);
+}
+.rs-fieldset:disabled .rs-fieldset__legend[data-v-460cb31f],
+.rs-fieldset--disabled .rs-fieldset__legend[data-v-460cb31f] {
   color: var(--rs-muted);
 }
+.rs-fieldset__sr[data-v-460cb31f] {
+  position: absolute;
+  inline-size: 1px;
+  block-size: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}

package/dist/components/fieldset/src/RsFieldset.d.ts

@@ -21,6 +21,19 @@ type __VLS_Props = {
     size?: RsFieldsetSize;
     /** 原生 fieldset name */
     name?: string;
+    /** 关联外部 form id（分组不嵌在 form 内时） */
+    form?: string;
+    /** 根 fieldset id */
+    id?: string;
+    /**
+     * 组必填标记。只画星号；真正 required 仍在字段上。
+     * 没有 HTML fieldset.required。
+     */
+    required?: boolean;
+    /** 组级校验失败（描边走 danger） */
+    invalid?: boolean;
+    /** 组级错误文案；有文案或 #error 时也视为 invalid */
+    error?: string;
     /** 边框线型 */
     borderStyle?: RsFieldsetBorderStyle;
     /** 边框浓度；faded 为虚化 */
@@ -32,7 +45,7 @@ type __VLS_Props = {
     /** 标题字号 */
     titleSize?: RsFieldsetTitleSize;
 };
-declare var __VLS_1: {}, __VLS_10: {}, __VLS_12: {}, __VLS_14: {};
+declare var __VLS_1: {}, __VLS_10: {}, __VLS_12: {}, __VLS_14: {}, __VLS_16: {}, __VLS_18: {};
 type __VLS_Slots = {} & {
     legend?: (props: typeof __VLS_1) => any;
 } & {
@@ -40,10 +53,16 @@ type __VLS_Slots = {} & {
 } & {
     extra?: (props: typeof __VLS_12) => any;
 } & {
-    default?: (props: typeof __VLS_14) => any;
+    tooltip?: (props: typeof __VLS_14) => any;
+} & {
+    default?: (props: typeof __VLS_16) => any;
+} & {
+    error?: (props: typeof __VLS_18) => any;
 };
 declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    required: boolean;
     size: RsFieldsetSize;
+    invalid: boolean;
     disabled: boolean;
     borderStyle: RsFieldsetBorderStyle;
     borderTone: RsFieldsetBorderTone;

package/dist/components/fieldset/src/RsFieldset.impl.js

@@ -1,10 +1,17 @@
 import { useRsI18n } from "../../../composables/useRsI18n.js";
 import { useRsFormContext } from "../../form/src/form-utils.js";
 import RsTooltip_default from "../../tooltip/src/RsTooltip.js";
-import { resolveFieldsetTitleSize, resolveFieldsetTitleWeight } from "./fieldset-utils.js";
-import { computed, createBlock, createCommentVNode, createElementBlock, createElementVNode, createSlots, defineComponent, normalizeClass, normalizeStyle, openBlock, renderSlot, toDisplayString, useSlots, withCtx } from "vue";
+import { resolveFieldsetInvalid, resolveFieldsetTitleSize, resolveFieldsetTitleWeight, resolveFieldsetTooltip } from "./fieldset-utils.js";
+import { computed, createBlock, createCommentVNode, createElementBlock, createElementVNode, createSlots, createTextVNode, defineComponent, normalizeClass, normalizeStyle, openBlock, renderSlot, toDisplayString, unref, useId, useSlots, withCtx } from "vue";
 //#region src/components/fieldset/src/RsFieldset.vue?vue&type=script&setup=true&lang.ts
-var _hoisted_1 = ["name", "disabled"];
+var _hoisted_1 = [
+	"id",
+	"name",
+	"form",
+	"disabled",
+	"aria-invalid",
+	"aria-describedby"
+];
 var _hoisted_2 = {
 	key: 0,
 	class: "rs-fieldset__legend"
@@ -12,10 +19,21 @@ var _hoisted_2 = {
 var _hoisted_3 = { class: "rs-fieldset__heading" };
 var _hoisted_4 = { class: "rs-fieldset__title" };
 var _hoisted_5 = {
+	key: 0,
+	class: "rs-fieldset__required",
+	"aria-hidden": "true"
+};
+var _hoisted_6 = {
+	key: 1,
+	class: "rs-fieldset__sr"
+};
+var _hoisted_7 = {
 	key: 0,
 	class: "rs-fieldset__extra"
 };
-var _hoisted_6 = { class: "rs-fieldset__body" };
+var _hoisted_8 = { class: "rs-fieldset__body" };
+var _hoisted_9 = ["id"];
+var _hoisted_10 = ["id"];
 var RsFieldset_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/ defineComponent({
 	name: "RsFieldset",
 	__name: "RsFieldset",
@@ -29,6 +47,17 @@ var RsFieldset_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/ defin
 		},
 		size: { default: "md" },
 		name: {},
+		form: {},
+		id: {},
+		required: {
+			type: Boolean,
+			default: false
+		},
+		invalid: {
+			type: Boolean,
+			default: false
+		},
+		error: {},
 		borderStyle: { default: "solid" },
 		borderTone: { default: "default" },
 		titleWeight: { default: "semibold" },
@@ -39,38 +68,76 @@ var RsFieldset_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/ defin
 		const props = __props;
 		const slots = useSlots();
 		const { t } = useRsI18n();
-		const form = useRsFormContext();
-		const isDisabled = computed(() => Boolean(props.disabled || form?.disabled.value));
-		const resolvedTooltip = computed(() => (props.tooltip || props.description || "").trim());
+		const formContext = useRsFormContext();
+		const autoErrorId = useId();
+		const autoHintId = useId();
+		const isDisabled = computed(() => Boolean(props.disabled || formContext?.disabled.value));
+		const resolvedTooltip = computed(() => resolveFieldsetTooltip(props.tooltip, props.description));
 		const hasTooltip = computed(() => Boolean(resolvedTooltip.value || slots.tooltip));
-		const hasLegend = computed(() => Boolean(props.legend || slots.legend || slots.extra || hasTooltip.value));
+		const hasError = computed(() => Boolean(props.error?.trim() || slots.error));
+		const isInvalid = computed(() => resolveFieldsetInvalid(props.invalid, props.error, Boolean(slots.error)));
+		const hasLegend = computed(() => Boolean(props.legend || slots.legend || slots.extra || hasTooltip.value || props.required));
+		const showDisabledHint = computed(() => isDisabled.value && hasTooltip.value);
 		const helpLabel = computed(() => t("fieldset.help", "Group help"));
+		const errorId = computed(() => hasError.value ? autoErrorId : void 0);
+		const hintId = computed(() => showDisabledHint.value ? autoHintId : void 0);
+		const describedBy = computed(() => {
+			const ids = [errorId.value, hintId.value].filter(Boolean);
+			return ids.length ? ids.join(" ") : void 0;
+		});
+		const rootClass = computed(() => [
+			"rs-fieldset",
+			`rs-fieldset--${props.size}`,
+			`rs-fieldset--${props.borderStyle}`,
+			`rs-fieldset--tone-${props.borderTone}`,
+			`rs-fieldset--title-${props.titleTone}`,
+			{
+				"rs-fieldset--disabled": isDisabled.value,
+				"rs-fieldset--invalid": isInvalid.value
+			}
+		]);
 		const rootStyle = computed(() => ({
 			"--rs-fieldset-title-size": resolveFieldsetTitleSize(props.titleSize),
 			"--rs-fieldset-title-weight": resolveFieldsetTitleWeight(props.titleWeight)
 		}));
 		return (_ctx, _cache) => {
 			return openBlock(), createElementBlock("fieldset", {
-				class: normalizeClass(["rs-fieldset", [
-					`rs-fieldset--${__props.size}`,
-					`rs-fieldset--${__props.borderStyle}`,
-					`rs-fieldset--tone-${__props.borderTone}`,
-					`rs-fieldset--title-${__props.titleTone}`,
-					{ "rs-fieldset--disabled": isDisabled.value }
-				]]),
+				id: __props.id,
+				class: normalizeClass(rootClass.value),
 				style: normalizeStyle(rootStyle.value),
 				name: __props.name,
-				disabled: isDisabled.value
-			}, [hasLegend.value ? (openBlock(), createElementBlock("legend", _hoisted_2, [createElementVNode("span", _hoisted_3, [renderSlot(_ctx.$slots, "legend", {}, () => [createElementVNode("span", _hoisted_4, toDisplayString(__props.legend), 1)], true), hasTooltip.value ? (openBlock(), createBlock(RsTooltip_default, {
-				key: 0,
-				icon: "",
-				content: resolvedTooltip.value,
-				"aria-label": helpLabel.value
-			}, createSlots({ _: 2 }, [_ctx.$slots.tooltip ? {
-				name: "content",
-				fn: withCtx(() => [renderSlot(_ctx.$slots, "tooltip", {}, void 0, true)]),
-				key: "0"
-			} : void 0]), 1032, ["content", "aria-label"])) : createCommentVNode("", true)]), _ctx.$slots.extra ? (openBlock(), createElementBlock("span", _hoisted_5, [renderSlot(_ctx.$slots, "extra", {}, void 0, true)])) : createCommentVNode("", true)])) : createCommentVNode("", true), createElementVNode("div", _hoisted_6, [renderSlot(_ctx.$slots, "default", {}, void 0, true)])], 14, _hoisted_1);
+				form: __props.form,
+				disabled: isDisabled.value,
+				"aria-invalid": isInvalid.value ? "true" : void 0,
+				"aria-describedby": describedBy.value
+			}, [hasLegend.value ? (openBlock(), createElementBlock("legend", _hoisted_2, [createElementVNode("span", _hoisted_3, [
+				renderSlot(_ctx.$slots, "legend", {}, () => [createElementVNode("span", _hoisted_4, toDisplayString(__props.legend), 1)], true),
+				__props.required ? (openBlock(), createElementBlock("span", _hoisted_5, "*")) : createCommentVNode("", true),
+				__props.required ? (openBlock(), createElementBlock("span", _hoisted_6, toDisplayString(unref(t)("label.required")), 1)) : createCommentVNode("", true),
+				hasTooltip.value && !isDisabled.value ? (openBlock(), createBlock(RsTooltip_default, {
+					key: 2,
+					icon: "",
+					content: resolvedTooltip.value,
+					"aria-label": helpLabel.value
+				}, createSlots({ _: 2 }, [_ctx.$slots.tooltip ? {
+					name: "content",
+					fn: withCtx(() => [renderSlot(_ctx.$slots, "tooltip", {}, void 0, true)]),
+					key: "0"
+				} : void 0]), 1032, ["content", "aria-label"])) : createCommentVNode("", true)
+			]), _ctx.$slots.extra ? (openBlock(), createElementBlock("span", _hoisted_7, [renderSlot(_ctx.$slots, "extra", {}, void 0, true)])) : createCommentVNode("", true)])) : createCommentVNode("", true), createElementVNode("div", _hoisted_8, [
+				showDisabledHint.value ? (openBlock(), createElementBlock("div", {
+					key: 0,
+					id: hintId.value,
+					class: "rs-fieldset__hint"
+				}, [renderSlot(_ctx.$slots, "tooltip", {}, () => [createTextVNode(toDisplayString(resolvedTooltip.value), 1)], true)], 8, _hoisted_9)) : createCommentVNode("", true),
+				renderSlot(_ctx.$slots, "default", {}, void 0, true),
+				hasError.value ? (openBlock(), createElementBlock("p", {
+					key: 1,
+					id: errorId.value,
+					class: "rs-fieldset__error",
+					role: "alert"
+				}, [renderSlot(_ctx.$slots, "error", {}, () => [createTextVNode(toDisplayString(__props.error), 1)], true)], 8, _hoisted_10)) : createCommentVNode("", true)
+			])], 14, _hoisted_1);
 		};
 	}
 });

package/dist/components/fieldset/src/RsFieldset.js

@@ -3,6 +3,6 @@ import _plugin_vue_export_helper_default from "../../../_virtual/_plugin-vue_exp
 import RsFieldset_vue_vue_type_script_setup_true_lang_default from "./RsFieldset.impl.js";
 
 //#region src/components/fieldset/src/RsFieldset.vue
-var RsFieldset_default = /*#__PURE__*/ _plugin_vue_export_helper_default(RsFieldset_vue_vue_type_script_setup_true_lang_default, [["__scopeId", "data-v-b3043538"]]);
+var RsFieldset_default = /*#__PURE__*/ _plugin_vue_export_helper_default(RsFieldset_vue_vue_type_script_setup_true_lang_default, [["__scopeId", "data-v-460cb31f"]]);
 //#endregion
 export { RsFieldset_default as default };

package/dist/components/fieldset/src/fieldset-utils.d.ts

@@ -27,3 +27,7 @@ export type RsFieldsetTitleSize = Extract<RsFontSize, 'xs' | 'sm' | 'base'>;
 export declare function resolveFieldsetTitleSize(size: RsFieldsetTitleSize): string;
 /** 解析标题字重 token。 */
 export declare function resolveFieldsetTitleWeight(weight: RsFontWeight): string;
+/** tooltip 优先；弃用的 description 仍映射到同一 tip。 */
+export declare function resolveFieldsetTooltip(tooltip: string | undefined, description: string | undefined): string;
+/** 显式 invalid，或有错误文案 / #error，都算组级失败。 */
+export declare function resolveFieldsetInvalid(invalid: boolean, error: string | undefined, hasErrorSlot: boolean): boolean;

package/dist/components/fieldset/src/fieldset-utils.js

@@ -8,5 +8,13 @@ function resolveFieldsetTitleSize(size) {
 function resolveFieldsetTitleWeight(weight) {
 	return RS_FONT_WEIGHT_CSS[weight];
 }
+/** tooltip 优先；弃用的 description 仍映射到同一 tip。 */
+function resolveFieldsetTooltip(tooltip, description) {
+	return (tooltip || description || "").trim();
+}
+/** 显式 invalid，或有错误文案 / #error，都算组级失败。 */
+function resolveFieldsetInvalid(invalid, error, hasErrorSlot) {
+	return Boolean(invalid || error?.trim() || hasErrorSlot);
+}
 //#endregion
-export { resolveFieldsetTitleSize, resolveFieldsetTitleWeight };
+export { resolveFieldsetInvalid, resolveFieldsetTitleSize, resolveFieldsetTitleWeight, resolveFieldsetTooltip };

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

@@ -1,4 +1,5 @@
 export { default as RsForm } from './src/RsForm.js';
+export type { RsFormExpose, RsFormInstance } from './src/RsForm.js';
 export { default as RsFormItem } from './src/RsFormItem.js';
 export { default as RsFormList } from './src/RsFormList.js';
 export type { RsFormContext, RsFormErrorRender, RsFormErrorRenderContext, RsFormFieldExpose, RsFormItemContext, RsFormListContext, RsFormListField, RsFormListOperations, RsFormFieldValidationResult, RsFormGap, RsFormLabelAlign, RsFormLabelPosition, RsFormMaxWidth, RsFormSize, RsFormValidateStatus, RsFormValidationResult, } from './src/form-utils';

package/dist/components/form/src/RsForm.css

@@ -1,30 +1,33 @@
 
-.rs-form[data-v-2243abc5] {
+.rs-form[data-v-0cdc7aeb] {
+  --rs-form-max-sm: 24rem;
+  --rs-form-max-md: 32rem;
+  --rs-form-max-lg: 48rem;
   display: flex;
   flex-direction: column;
   width: 100%;
 }
-.rs-form--gap-sm[data-v-2243abc5] {
+.rs-form--gap-sm[data-v-0cdc7aeb] {
   gap: var(--rs-space-sm);
 }
-.rs-form--gap-md[data-v-2243abc5] {
+.rs-form--gap-md[data-v-0cdc7aeb] {
   gap: var(--rs-space-md);
 }
-.rs-form--gap-lg[data-v-2243abc5] {
+.rs-form--gap-lg[data-v-0cdc7aeb] {
   gap: var(--rs-space-lg);
 }
-.rs-form--max-sm[data-v-2243abc5] {
-  max-width: 24rem;
+.rs-form--max-sm[data-v-0cdc7aeb] {
+  max-width: var(--rs-form-max-sm);
 }
-.rs-form--max-md[data-v-2243abc5] {
-  max-width: 32rem;
+.rs-form--max-md[data-v-0cdc7aeb] {
+  max-width: var(--rs-form-max-md);
 }
-.rs-form--max-lg[data-v-2243abc5] {
-  max-width: 48rem;
+.rs-form--max-lg[data-v-0cdc7aeb] {
+  max-width: var(--rs-form-max-lg);
 }
-.rs-form--max-full[data-v-2243abc5] {
+.rs-form--max-full[data-v-0cdc7aeb] {
   max-width: 100%;
 }
-.rs-form--max-none[data-v-2243abc5] {
+.rs-form--max-none[data-v-0cdc7aeb] {
   max-width: none;
 }

package/dist/components/form/src/RsForm.d.ts

@@ -1,6 +1,25 @@
 import type { RsFormErrorRender, RsFormFieldValidationResult, RsFormGap, RsFormLabelAlign, RsFormLabelPosition, RsFormMaxWidth, RsFormSize, RsFormValidationResult } from './form-utils';
 import type { RsFormRuleTrigger, RsFormRules, RsFormValidateMessages } from './form-rules';
 import { type RsFormNamePath } from './form-path';
+/**
+ * RsForm 模板 ref 请用此类型。
+ * 不要写 `InstanceType<typeof RsForm>`：组件实例类型过深，vue-tsc 会报 Excessive stack depth。
+ */
+export interface RsFormExpose {
+    validate: (trigger?: RsFormRuleTrigger) => Promise<RsFormValidationResult>;
+    validateField: (name: string, trigger?: RsFormRuleTrigger) => Promise<RsFormFieldValidationResult>;
+    clearValidation: (names?: string | string[]) => void;
+    resetFields: (names?: string | string[]) => void;
+    getFieldsValue: () => Record<string, unknown>;
+    setFieldsValue: (values: Record<string, unknown>) => void;
+    getFieldValue: (name: RsFormNamePath) => unknown;
+    setFieldValue: (name: RsFormNamePath, value: unknown) => void;
+    scrollToField: (name: RsFormNamePath) => void;
+}
+/** 模板 ref 实例：expose + 根 form */
+export type RsFormInstance = RsFormExpose & {
+    $el: HTMLFormElement;
+};
 type __VLS_Props = {
     disabled?: boolean;
     labelPosition?: RsFormLabelPosition;
@@ -29,32 +48,11 @@ type __VLS_Props = {
      */
     errorRender?: RsFormErrorRender;
 };
-declare function getFieldValue(name: RsFormNamePath): unknown;
-declare function setFieldValue(name: RsFormNamePath, value: unknown): void;
-declare function getFieldsValue(): Record<string, unknown>;
-declare function setFieldsValue(values: Record<string, unknown>): void;
-declare function scrollToField(name: RsFormNamePath): void;
-/** 校验全部字段；可传 trigger 过滤规则 */
-declare function validate(trigger?: RsFormRuleTrigger): Promise<RsFormValidationResult>;
-/** 按 name 校验单个字段 */
-declare function validateField(name: string, trigger?: RsFormRuleTrigger): Promise<RsFormFieldValidationResult>;
-declare function clearValidation(names?: string | string[]): void;
-declare function resetFields(names?: string | string[]): void;
 declare var __VLS_1: {};
 type __VLS_Slots = {} & {
     default?: (props: typeof __VLS_1) => any;
 };
-declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
-    validate: typeof validate;
-    validateField: typeof validateField;
-    clearValidation: typeof clearValidation;
-    resetFields: typeof resetFields;
-    getFieldsValue: typeof getFieldsValue;
-    setFieldsValue: typeof setFieldsValue;
-    getFieldValue: typeof getFieldValue;
-    setFieldValue: typeof setFieldValue;
-    scrollToField: typeof scrollToField;
-}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, RsFormExpose, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     submit: (event: Event) => any;
     validate: (result: RsFormValidationResult) => any;
 }, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{

package/dist/components/form/src/RsForm.impl.js

@@ -1,8 +1,9 @@
 import { getByNamePath, namePathKey, setByNamePath } from "./form-path.js";
-import { cloneFormFieldValue, provideRsFormContext, resolveFieldRules } from "./form-utils.js";
-import { computed, createElementBlock, defineComponent, normalizeClass, openBlock, ref, renderSlot, toRef, useSlots } from "vue";
+import { cloneFormFieldValue, normalizeRsFormNameFilter, provideRsFormContext, resolveFieldRules, scrollRsFormField } from "./form-utils.js";
+import { computed, createElementBlock, defineComponent, normalizeClass, onBeforeUnmount, openBlock, renderSlot, toRef, useSlots, useTemplateRef } from "vue";
 //#region src/components/form/src/RsForm.vue?vue&type=script&setup=true&lang.ts
 var RsForm_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/ defineComponent({
+	name: "RsForm",
 	__name: "RsForm",
 	props: {
 		disabled: {
@@ -29,7 +30,11 @@ var RsForm_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/ defineCom
 		const props = __props;
 		const emit = __emit;
 		const slots = useSlots();
+		const formEl = useTemplateRef("formEl");
 		const fields = /* @__PURE__ */ new Map();
+		const fieldsByName = /* @__PURE__ */ new Map();
+		const initialValues = /* @__PURE__ */ new Map();
+		let mounted = true;
 		const disabledRef = computed(() => props.disabled);
 		const labelPositionRef = computed(() => props.labelPosition);
 		const labelWidthRef = computed(() => props.labelWidth);
@@ -38,30 +43,33 @@ var RsForm_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/ defineCom
 		const rulesRef = toRef(props, "rules");
 		const modelRef = toRef(props, "model");
 		const validateMessagesRef = computed(() => props.validateMessages);
-		const initialValues = ref(/* @__PURE__ */ new Map());
 		function registerField(id, field) {
 			fields.set(id, field);
-			initialValues.value.set(id, cloneFormFieldValue(field.getValue()));
+			initialValues.set(id, cloneFormFieldValue(field.getValue()));
+			if (field.name && !fieldsByName.has(field.name)) fieldsByName.set(field.name, field);
 		}
 		function unregisterField(id) {
+			const field = fields.get(id);
 			fields.delete(id);
-			initialValues.value.delete(id);
+			initialValues.delete(id);
+			if (field?.name && fieldsByName.get(field.name) === field) fieldsByName.delete(field.name);
+		}
+		function findField(name) {
+			return fieldsByName.get(name);
 		}
 		function getFieldRules(name) {
 			return resolveFieldRules(props.rules, name);
 		}
 		function getFieldValue(name) {
 			if (modelRef.value) return getByNamePath(modelRef.value, name);
-			const key = namePathKey(name);
-			return Array.from(fields.values()).find((item) => item.name === key)?.getValue();
+			return findField(namePathKey(name))?.getValue();
 		}
 		function setFieldValue(name, value) {
 			if (modelRef.value) {
 				setByNamePath(modelRef.value, name, value);
 				return;
 			}
-			const key = namePathKey(name);
-			Array.from(fields.values()).find((item) => item.name === key)?.setValue(value);
+			findField(namePathKey(name))?.setValue(value);
 		}
 		function getFieldsValue() {
 			if (modelRef.value) return { ...modelRef.value };
@@ -78,13 +86,7 @@ var RsForm_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/ defineCom
 			});
 		}
 		function scrollToField(name) {
-			if (typeof document === "undefined") return;
-			const key = namePathKey(name);
-			const el = document.querySelector(`[data-rs-form-item="${CSS.escape(key)}"]`);
-			if (el instanceof HTMLElement) el.scrollIntoView({
-				block: "nearest",
-				behavior: "smooth"
-			});
+			scrollRsFormField(formEl.value, name);
 		}
 		function renderError(ctx) {
 			if (slots.error) return slots.error(ctx);
@@ -121,12 +123,13 @@ var RsForm_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/ defineCom
 				valid: true,
 				name: field.name
 			})));
+			if (!mounted) return aggregated;
 			emit("validate", aggregated);
 			return aggregated;
 		}
 		/** 按 name 校验单个字段 */
 		async function validateField(name, trigger = "submit") {
-			const field = Array.from(fields.values()).find((item) => item.name === name);
+			const field = findField(name);
 			if (!field) return {
 				valid: true,
 				name
@@ -140,17 +143,17 @@ var RsForm_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/ defineCom
 			};
 		}
 		function clearValidation(names) {
-			const nameSet = names ? new Set(Array.isArray(names) ? names : [names]) : null;
+			const nameSet = normalizeRsFormNameFilter(names);
 			fields.forEach((field) => {
 				if (nameSet && (!field.name || !nameSet.has(field.name))) return;
 				field.clearValidation?.();
 			});
 		}
 		function resetFields(names) {
-			const nameSet = names ? new Set(Array.isArray(names) ? names : [names]) : null;
+			const nameSet = normalizeRsFormNameFilter(names);
 			fields.forEach((field, id) => {
 				if (nameSet && (!field.name || !nameSet.has(field.name))) return;
-				field.setValue(cloneFormFieldValue(initialValues.value.get(id)));
+				field.setValue(cloneFormFieldValue(initialValues.get(id)));
 				field.clearValidation?.();
 			});
 		}
@@ -159,8 +162,15 @@ var RsForm_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/ defineCom
 				event.preventDefault();
 				if (!(await validate("submit")).valid) return;
 			}
+			if (!mounted) return;
 			emit("submit", event);
 		}
+		onBeforeUnmount(() => {
+			mounted = false;
+			fields.clear();
+			fieldsByName.clear();
+			initialValues.clear();
+		});
 		__expose({
 			validate,
 			validateField,
@@ -174,11 +184,14 @@ var RsForm_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/ defineCom
 		});
 		return (_ctx, _cache) => {
 			return openBlock(), createElementBlock("form", {
+				ref_key: "formEl",
+				ref: formEl,
 				class: normalizeClass(["rs-form", [
 					`rs-form--gap-${__props.gap}`,
 					`rs-form--max-${__props.maxWidth}`,
 					`rs-form--label-${__props.labelPosition}`
 				]]),
+				novalidate: "",
 				onSubmit
 			}, [renderSlot(_ctx.$slots, "default", {}, void 0, true)], 34);
 		};