niuma-ui 1.1.12 → 1.2.0

package/dist/components/drawer-utils.js

@@ -0,0 +1,59 @@
+import { resolveDialogOverlayStyle, runRsDialogBeforeClose } from "./dialog-utils.js";
+//#region src/components/drawer-utils.ts
+var SIZE_INLINE = {
+	sm: "20rem",
+	md: "28rem",
+	lg: "36rem"
+};
+/** 左右抽屉默认可拖最小宽度 */
+var RS_DRAWER_MIN_SIZE_PX = 256;
+/** 相对视口的默认可拖上限比例 */
+var RS_DRAWER_MAX_VIEWPORT_RATIO = .9;
+/** 将 size 预设解析为 CSS 长度（full 由样式类处理） */
+function resolveRsDrawerSizeCss(size) {
+	if (size === "full") return void 0;
+	return SIZE_INLINE[size];
+}
+/** 将自定义 width/height 规范为 CSS 长度 */
+function resolveRsDrawerDimensionCss(value) {
+	if (value == null) return void 0;
+	if (typeof value === "number") {
+		if (!Number.isFinite(value) || value <= 0) return void 0;
+		return `${value}px`;
+	}
+	return String(value).trim() || void 0;
+}
+/**
+* 将抽屉尺寸表达式解析为像素，供拖拽缩放夹紧。
+* 无法解析时返回 fallbackPx。
+*/
+function resolveRsDrawerSizePx(value, fallbackPx, rootFontPx, viewportPx) {
+	if (value == null) return fallbackPx;
+	if (typeof value === "number") return Number.isFinite(value) && value > 0 ? value : fallbackPx;
+	const trimmed = String(value).trim();
+	const n = Number.parseFloat(trimmed);
+	if (!Number.isFinite(n)) return fallbackPx;
+	if (trimmed.endsWith("rem")) return n * rootFontPx;
+	if (trimmed.endsWith("%") || trimmed.endsWith("vw") || trimmed.endsWith("vh")) return n / 100 * viewportPx;
+	return n;
+}
+/** 将拖拽得到的尺寸夹在 min/max 之间并取整。 */
+function clampRsDrawerSize(px, minPx, maxPx) {
+	return Math.round(Math.min(Math.max(minPx, maxPx), Math.max(Math.min(minPx, maxPx), px)));
+}
+function runRsDrawerBeforeClose(beforeClose, reason) {
+	return runRsDialogBeforeClose(beforeClose, reason);
+}
+/**
+* 遮罩样式：复用 Dialog 的 opacity/blur 解析，写入抽屉专用 CSS 变量。
+*/
+function resolveDrawerOverlayStyle(options) {
+	const dialogStyle = resolveDialogOverlayStyle(options);
+	if (!dialogStyle) return void 0;
+	const style = {};
+	if (dialogStyle["--rs-dialog-overlay-bg"]) style["--rs-drawer-overlay-bg"] = dialogStyle["--rs-dialog-overlay-bg"];
+	if (dialogStyle["--rs-dialog-overlay-blur"]) style["--rs-drawer-overlay-blur"] = dialogStyle["--rs-dialog-overlay-blur"];
+	return Object.keys(style).length ? style : void 0;
+}
+//#endregion
+export { RS_DRAWER_MAX_VIEWPORT_RATIO, RS_DRAWER_MIN_SIZE_PX, clampRsDrawerSize, resolveDrawerOverlayStyle, resolveRsDrawerDimensionCss, resolveRsDrawerSizeCss, resolveRsDrawerSizePx, runRsDrawerBeforeClose };

package/dist/components/dropdown-utils.d.ts

@@ -0,0 +1,13 @@
+export interface RsDropdownItem {
+    label: string;
+    value: string;
+    icon?: string;
+    disabled?: boolean;
+}
+export interface RsDropdownItemGroup {
+    label: string;
+    options: RsDropdownItem[];
+}
+export type RsDropdownItems = RsDropdownItem[] | RsDropdownItemGroup[];
+export declare function isDropdownItemGroup(item: RsDropdownItem | RsDropdownItemGroup): item is RsDropdownItemGroup;
+export declare function flattenDropdownItems(items: RsDropdownItems): RsDropdownItem[];

package/dist/components/dropdown-utils.js

@@ -0,0 +1,12 @@
+//#region src/components/dropdown-utils.ts
+function isDropdownItemGroup(item) {
+	return "options" in item && Array.isArray(item.options);
+}
+function flattenDropdownItems(items) {
+	const result = [];
+	for (const item of items) if (isDropdownItemGroup(item)) result.push(...item.options);
+	else result.push(item);
+	return result;
+}
+//#endregion
+export { flattenDropdownItems, isDropdownItemGroup };

package/dist/components/form-item-control.d.ts

@@ -0,0 +1,7 @@
+import { type VNode } from 'vue';
+/**
+ * 把 Form.Item 的 id / aria / invalid / v-model 注入到默认插槽的第一个控件（对齐 Ant cloneElement）。
+ * 只有这个直接子节点跟 Item 的 error；子孙里的搜索框不吃 invalid。
+ * 子节点已绑定 v-model 时不覆盖（switch Y/N、select 类型映射等）。
+ */
+export declare function bindFormItemControl(children: VNode[] | undefined, extra: Record<string, unknown>): VNode[] | undefined;

package/dist/components/form-item-control.js

@@ -0,0 +1,46 @@
+import { Comment, Fragment, Text, cloneVNode, isVNode } from "vue";
+//#region src/components/form-item-control.ts
+function flattenVNodes(nodes, out = []) {
+	for (const node of nodes) {
+		if (node == null || typeof node === "boolean") continue;
+		if (Array.isArray(node)) {
+			flattenVNodes(node, out);
+			continue;
+		}
+		if (!isVNode(node)) continue;
+		if (node.type === Fragment && Array.isArray(node.children)) {
+			flattenVNodes(node.children, out);
+			continue;
+		}
+		out.push(node);
+	}
+	return out;
+}
+function isControlVNode(node) {
+	if (node.type === Comment || node.type === Text) return false;
+	return true;
+}
+/**
+* 把 Form.Item 的 id / aria / invalid / v-model 注入到默认插槽的第一个控件（对齐 Ant cloneElement）。
+* 只有这个直接子节点跟 Item 的 error；子孙里的搜索框不吃 invalid。
+* 子节点已绑定 v-model 时不覆盖（switch Y/N、select 类型映射等）。
+*/
+function bindFormItemControl(children, extra) {
+	if (!children?.length) return children;
+	const flat = flattenVNodes(children);
+	const index = flat.findIndex(isControlVNode);
+	if (index < 0) return children;
+	const target = flat[index];
+	if (!target) return children;
+	const next = flat.slice();
+	next[index] = cloneVNode(target, pickControlInject(target, extra), true);
+	return next;
+}
+function pickControlInject(node, extra) {
+	const props = node.props;
+	if (!props || !("modelValue" in props || "onUpdate:modelValue" in props)) return extra;
+	const { modelValue: _model, "onUpdate:modelValue": _update, ...rest } = extra;
+	return rest;
+}
+//#endregion
+export { bindFormItemControl };

package/dist/components/form-path.d.ts

@@ -0,0 +1,29 @@
+/** 字段路径：`'user.email'` 或 `['user', 'email']`（对齐 Ant Design NamePath） */
+export type RsFormNamePath = string | Array<string | number>;
+/** 路径段是否为数组下标（Form.List 相对 name 的第一段）。 */
+export declare function isIndexSegment(seg: string | number): boolean;
+/**
+ * 将 NamePath 规范为路径段。字符串按 `.` 拆分。
+ */
+export declare function normalizeNamePath(name?: RsFormNamePath | null): Array<string | number>;
+/**
+ * 拼接多段 NamePath（List 前缀 + Item name）。
+ */
+export declare function concatNamePath(...parts: Array<RsFormNamePath | undefined | null>): Array<string | number>;
+/**
+ * 路径转 rules / DOM 使用的稳定键。
+ */
+export declare function namePathKey(name?: RsFormNamePath | null): string;
+/**
+ * 路径是否已存在于对象树上（含值为 null / undefined 的叶子）。
+ */
+export declare function hasByNamePath(source: unknown, name?: RsFormNamePath | null): boolean;
+/**
+ * 按 NamePath 读取对象字段。
+ */
+export declare function getByNamePath(source: unknown, name?: RsFormNamePath | null): unknown;
+/**
+ * 按 NamePath 写入对象字段。
+ * 中间缺失的容器按下一段是否为下标补 `[]` 或 `{}`，已有数组不会被覆盖成对象。
+ */
+export declare function setByNamePath(target: Record<string, unknown>, name: RsFormNamePath, value: unknown): void;

package/dist/components/form-path.js

@@ -0,0 +1,78 @@
+//#region src/components/form-path.ts
+/** 路径段是否为数组下标（Form.List 相对 name 的第一段）。 */
+function isIndexSegment(seg) {
+	if (typeof seg === "number") return Number.isInteger(seg) && seg >= 0;
+	return /^\d+$/.test(seg);
+}
+/**
+* 将 NamePath 规范为路径段。字符串按 `.` 拆分。
+*/
+function normalizeNamePath(name) {
+	if (name == null || name === "") return [];
+	if (Array.isArray(name)) return name.filter((seg) => seg !== "");
+	return String(name).split(".").filter((seg) => seg !== "");
+}
+/**
+* 拼接多段 NamePath（List 前缀 + Item name）。
+*/
+function concatNamePath(...parts) {
+	return parts.flatMap((part) => normalizeNamePath(part));
+}
+/**
+* 路径转 rules / DOM 使用的稳定键。
+*/
+function namePathKey(name) {
+	return normalizeNamePath(name).map(String).join(".");
+}
+/**
+* 路径是否已存在于对象树上（含值为 null / undefined 的叶子）。
+*/
+function hasByNamePath(source, name) {
+	const keys = normalizeNamePath(name);
+	if (!keys.length) return false;
+	let current = source;
+	for (const key of keys) {
+		if (current == null || typeof current !== "object") return false;
+		if (!Object.prototype.hasOwnProperty.call(current, String(key))) return false;
+		current = current[String(key)];
+	}
+	return true;
+}
+/**
+* 按 NamePath 读取对象字段。
+*/
+function getByNamePath(source, name) {
+	const keys = normalizeNamePath(name);
+	if (!keys.length) return void 0;
+	let current = source;
+	for (const key of keys) {
+		if (current == null || typeof current !== "object") return void 0;
+		current = current[String(key)];
+	}
+	return current;
+}
+/**
+* 按 NamePath 写入对象字段。
+* 中间缺失的容器按下一段是否为下标补 `[]` 或 `{}`，已有数组不会被覆盖成对象。
+*/
+function setByNamePath(target, name, value) {
+	const keys = normalizeNamePath(name);
+	if (!keys.length) return;
+	let current = target;
+	for (let i = 0; i < keys.length - 1; i += 1) {
+		if (current == null || typeof current !== "object") return;
+		const obj = current;
+		const key = String(keys[i]);
+		const nextKey = keys[i + 1];
+		let next = obj[key];
+		if (next == null || typeof next !== "object") {
+			next = isIndexSegment(nextKey) ? [] : {};
+			obj[key] = next;
+		}
+		current = next;
+	}
+	if (current == null || typeof current !== "object") return;
+	current[String(keys[keys.length - 1])] = value;
+}
+//#endregion
+export { concatNamePath, getByNamePath, hasByNamePath, isIndexSegment, namePathKey, normalizeNamePath, setByNamePath };

package/dist/components/form-rules.d.ts

@@ -0,0 +1,82 @@
+import { type RsTranslateFn } from '../locale/interpolate';
+import type { RsFormNamePath } from './form-path';
+import { type RsInputRule } from './input-rules';
+/** 校验触发时机（对齐 Ant Design Form） */
+export type RsFormRuleTrigger = 'blur' | 'change' | 'submit';
+/**
+ * validator 第二参：读取整表数据，供跨字段校验（B 依赖 A）。
+ */
+export interface RsFormValidatorContext {
+    name?: string;
+    getFieldValue: (name: RsFormNamePath) => unknown;
+    getFieldsValue: () => Record<string, unknown>;
+}
+/**
+ * 单条表单规则（声明式 + 自定义校验）。
+ * 对标 Ant Design / Element Plus Form rules 的常用子集。
+ */
+/** 规则文案：静态字符串，或按当前值动态生成（对齐 Ant Design message 函数能力） */
+export type RsFormRuleMessage = string | ((ctx: {
+    value: unknown;
+    rule: RsFormRuleItem;
+}) => string);
+export interface RsFormRuleItem {
+    required?: boolean;
+    /**
+     * 错误文案；未传时使用内置 i18n。
+     * 可传函数按当前值动态生成文案。
+     */
+    message?: RsFormRuleMessage;
+    /** 字符串长度下限 / 数值下限 */
+    min?: number;
+    /** 字符串长度上限 / 数值上限 */
+    max?: number;
+    /** 字符串精确长度 */
+    len?: number;
+    pattern?: RegExp;
+    /** 内置类型：email/phone 等，或 string/number/array */
+    type?: RsInputRule | 'string' | 'number' | 'array';
+    /**
+     * 自定义校验。返回 true 通过；false / 字符串为失败；支持 Promise。
+     * 第二参可读取其它字段（`getFieldValue` / `getFieldsValue`）。
+     */
+    validator?: (value: unknown, ctx: RsFormValidatorContext) => boolean | string | void | Promise<boolean | string | void>;
+    trigger?: RsFormRuleTrigger | RsFormRuleTrigger[];
+}
+/** 字段名 → 规则（单条或数组） */
+export type RsFormRules = Record<string, RsFormRuleItem | RsFormRuleItem[]>;
+export interface RsFormRuleValidateResult {
+    valid: boolean;
+    message?: string;
+}
+/**
+ * Form.validateMessages 模板（`{label}` 插值）。
+ * 对标 Ant Design Form.validateMessages。
+ */
+export interface RsFormValidateMessages {
+    required?: string;
+}
+export interface RsFormFieldRulesOptions {
+    trigger?: RsFormRuleTrigger;
+    t?: RsTranslateFn;
+    label?: string;
+    name?: string;
+    validateMessages?: RsFormValidateMessages;
+    getFieldValue?: (name: RsFormNamePath) => unknown;
+    getFieldsValue?: () => Record<string, unknown>;
+}
+export declare function normalizeFormRules(rules?: RsFormRuleItem | RsFormRuleItem[] | null): RsFormRuleItem[];
+export declare function matchFormRuleTrigger(rule: RsFormRuleItem, trigger?: RsFormRuleTrigger): boolean;
+/** 解析规则 message（字符串或函数） */
+export declare function resolveRuleMessage(rule: RsFormRuleItem, value: unknown, fallback: string): string;
+/**
+ * 按顺序执行字段规则，首条失败即返回。
+ */
+export declare function runFormFieldRules(value: unknown, rules: RsFormRuleItem[], options?: RsFormFieldRulesOptions): Promise<RsFormRuleValidateResult>;
+/** 将 Input 局部 props 转为规则列表，便于与 Form rules 合并 */
+export declare function buildLocalInputRules(options: {
+    required?: boolean;
+    rule?: RsInputRule;
+    validator?: (value: string) => boolean | string;
+    requiredMessage?: string;
+}): RsFormRuleItem[];

package/dist/components/form-rules.js

@@ -0,0 +1,130 @@
+import { interpolateRsMessage } from "../locale/interpolate.js";
+import "../locale/types.js";
+import { createTranslator } from "../composables/useRsI18n.js";
+import { getInputRuleMessage, validateInputRule } from "./input-rules.js";
+//#region src/components/form-rules.ts
+function normalizeFormRules(rules) {
+	if (!rules) return [];
+	return Array.isArray(rules) ? rules : [rules];
+}
+function matchFormRuleTrigger(rule, trigger) {
+	if (!trigger || trigger === "submit") return true;
+	const ruleTrigger = rule.trigger;
+	if (!ruleTrigger) return true;
+	return (Array.isArray(ruleTrigger) ? ruleTrigger : [ruleTrigger]).includes(trigger);
+}
+function isEmptyValue(value) {
+	if (value == null) return true;
+	if (typeof value === "string") return value.trim() === "";
+	if (Array.isArray(value)) return value.length === 0;
+	if (typeof value === "object") {
+		const record = value;
+		if ("start" in record || "end" in record) return isEmptyValue(record.start) && isEmptyValue(record.end);
+	}
+	return false;
+}
+function valueLength(value) {
+	if (typeof value === "string") return value.trim().length;
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (Array.isArray(value)) return value.length;
+	return null;
+}
+function fail(message) {
+	return {
+		valid: false,
+		message
+	};
+}
+/** 解析规则 message（字符串或函数） */
+function resolveRuleMessage(rule, value, fallback) {
+	const message = rule.message;
+	if (typeof message === "function") return message({
+		value,
+		rule
+	});
+	if (typeof message === "string") return message;
+	return fallback;
+}
+function formatInvalid(rule, value, tr) {
+	return resolveRuleMessage(rule, value, tr("input.formatInvalid"));
+}
+/** 类型规则：string/number/array 或内置 email/phone 等 */
+function checkTypeRule(value, rule, tr) {
+	const type = rule.type;
+	if (!type) return null;
+	if (type === "string" && typeof value !== "string") return fail(formatInvalid(rule, value, tr));
+	if (type === "number" && typeof value !== "number") return fail(formatInvalid(rule, value, tr));
+	if (type === "array" && !Array.isArray(value)) return fail(formatInvalid(rule, value, tr));
+	if (type !== "string" && type !== "number" && type !== "array" && typeof value === "string" && !validateInputRule(value, type)) return fail(resolveRuleMessage(rule, value, getInputRuleMessage(type, tr)));
+	return null;
+}
+function checkPatternRule(value, rule, tr) {
+	if (!rule.pattern || typeof value !== "string") return null;
+	if (rule.pattern.test(value)) return null;
+	return fail(formatInvalid(rule, value, tr));
+}
+function checkLengthRule(value, rule, tr) {
+	const length = valueLength(value);
+	if (length == null) return null;
+	if (rule.len != null && length !== rule.len) return fail(formatInvalid(rule, value, tr));
+	if (rule.min != null && length < rule.min) return fail(formatInvalid(rule, value, tr));
+	if (rule.max != null && length > rule.max) return fail(formatInvalid(rule, value, tr));
+	return null;
+}
+async function checkValidatorRule(value, rule, tr, options) {
+	if (!rule.validator) return null;
+	const ctx = {
+		name: options?.name,
+		getFieldValue: options?.getFieldValue ?? (() => void 0),
+		getFieldsValue: options?.getFieldsValue ?? (() => ({}))
+	};
+	let result;
+	try {
+		result = await rule.validator(value, ctx);
+	} catch (err) {
+		return fail(err instanceof Error && err.message ? err.message : formatInvalid(rule, value, tr));
+	}
+	if (result === true || result === void 0 || result === null) return null;
+	if (result === false) return fail(formatInvalid(rule, value, tr));
+	if (typeof result === "string") return fail(result);
+	if (result instanceof Error) return fail(result.message || formatInvalid(rule, value, tr));
+	return null;
+}
+/**
+* 执行单条规则；通过返回 null，失败返回结果。
+* 空值且非必填时跳过格式类规则。
+*/
+async function evaluateFormRule(value, rule, tr, options) {
+	if (rule.required && isEmptyValue(value)) {
+		const label = options?.label?.trim();
+		return fail(resolveRuleMessage(rule, value, interpolateRsMessage(options?.validateMessages?.required ?? (label ? tr("form.validate.required") : tr("input.required")), { label: label || tr("form.field") })));
+	}
+	if (isEmptyValue(value)) return checkValidatorRule(value, rule, tr, options);
+	return checkTypeRule(value, rule, tr) ?? checkPatternRule(value, rule, tr) ?? checkLengthRule(value, rule, tr) ?? await checkValidatorRule(value, rule, tr, options);
+}
+/**
+* 按顺序执行字段规则，首条失败即返回。
+*/
+async function runFormFieldRules(value, rules, options) {
+	const tr = options?.t ?? createTranslator("zh-CN");
+	const trigger = options?.trigger;
+	for (const rule of rules) {
+		if (!matchFormRuleTrigger(rule, trigger)) continue;
+		const failed = await evaluateFormRule(value, rule, tr, options);
+		if (failed) return failed;
+	}
+	return { valid: true };
+}
+/** 将 Input 局部 props 转为规则列表，便于与 Form rules 合并 */
+function buildLocalInputRules(options) {
+	const list = [];
+	if (options.required) list.push({
+		required: true,
+		message: options.requiredMessage
+	});
+	if (options.rule) list.push({ type: options.rule });
+	if (options.validator) list.push({ validator: (value) => options.validator(String(value ?? "")) });
+	return list;
+}
+//#endregion
+export { buildLocalInputRules, matchFormRuleTrigger, normalizeFormRules, resolveRuleMessage, runFormFieldRules };

package/dist/components/form-utils.d.ts

@@ -0,0 +1,120 @@
+import { type ComputedRef, type InjectionKey, type Ref, type VNodeChild } from 'vue';
+import type { RsFormRuleItem, RsFormRuleTrigger, RsFormRules, RsFormValidateMessages } from './form-rules';
+import { type RsFormNamePath } from './form-path';
+/** 自定义错误渲染上下文（Form / 字段共用） */
+export interface RsFormErrorRenderContext {
+    name?: string;
+    message: string;
+    value: unknown;
+}
+/**
+ * 自定义错误渲染（对齐 Ant Design Form.Item help / Element #error）。
+ * 返回 VNode / 字符串；返回 null/undefined 时回退默认文案。
+ */
+export type RsFormErrorRender = (ctx: RsFormErrorRenderContext) => VNodeChild | null | undefined;
+export type RsFormLabelPosition = 'top' | 'left';
+export type RsFormLabelAlign = 'start' | 'end';
+export type RsFormSize = 'ssm' | 'sm' | 'md' | 'lg';
+export type RsFormGap = 'sm' | 'md' | 'lg';
+export type RsFormMaxWidth = 'sm' | 'md' | 'lg' | 'full' | 'none';
+/** Form.Item 校验态（对齐 Ant Design validateStatus） */
+export type RsFormValidateStatus = 'success' | 'warning' | 'error' | 'validating' | '';
+/** 整表校验结果（含按字段名聚合的错误） */
+export interface RsFormValidationResult {
+    valid: boolean;
+    /** 字段名 → 首条错误文案；无 name 的字段不计入 */
+    errors: Record<string, string>;
+}
+export interface RsFormFieldValidationResult {
+    valid: boolean;
+    message?: string;
+    name?: string;
+}
+export interface RsFormFieldExpose {
+    /** 字段名，用于匹配 Form.rules */
+    name?: string;
+    getValue: () => unknown;
+    setValue: (value: unknown) => void;
+    validate?: (trigger?: RsFormRuleTrigger) => RsFormFieldValidationResult | Promise<RsFormFieldValidationResult>;
+    clearValidation?: () => void;
+    /** 由 Form 或外部写入错误态 */
+    setError?: (message: string) => void;
+}
+export interface RsFormContext {
+    disabled: Readonly<Ref<boolean>>;
+    labelPosition: ComputedRef<RsFormLabelPosition>;
+    labelWidth: Readonly<Ref<string>>;
+    labelAlign: Readonly<Ref<RsFormLabelAlign>>;
+    size: Readonly<Ref<RsFormSize>>;
+    /** 当前 Form 上的 rules（响应式读取） */
+    rules: Readonly<Ref<RsFormRules | undefined>>;
+    getFieldRules: (name?: string) => RsFormRuleItem[];
+    /** Form 级自定义错误渲染；字段无 #error 时使用 */
+    renderError?: RsFormErrorRender;
+    registerField: (id: symbol, field: RsFormFieldExpose) => void;
+    unregisterField: (id: symbol) => void;
+    /** 可选数据中枢（Form.model） */
+    model: Readonly<Ref<Record<string, unknown> | undefined>>;
+    validateMessages: ComputedRef<RsFormValidateMessages | undefined>;
+    getFieldValue: (name: RsFormNamePath) => unknown;
+    setFieldValue: (name: RsFormNamePath, value: unknown) => void;
+    getFieldsValue: () => Record<string, unknown>;
+}
+export declare const RS_FORM_INJECTION_KEY: InjectionKey<RsFormContext>;
+export declare function cloneFormFieldValue(value: unknown): unknown;
+/**
+ * Form.Item 上下文（对齐 Element `elFormItem` / Ant Design Form.Item）。
+ * invalid 只属于绑定控件：Item 通过 cloneElement 打到直接子节点，
+ * 子孙里的搜索框等应先用 isRsFormItemBoundControl 判断，不要一律跟 Item 变红。
+ */
+export interface RsFormItemContext {
+    name: ComputedRef<string | undefined>;
+    /** 已声明 name 时 Item 拥有字段，内置控件不再向 Form 注册 */
+    ownsField: ComputedRef<boolean>;
+    invalid: ComputedRef<boolean>;
+    message: ComputedRef<string>;
+    status: ComputedRef<RsFormValidateStatus>;
+    fieldId: ComputedRef<string>;
+    errorId: ComputedRef<string>;
+    describedBy: ComputedRef<string | undefined>;
+}
+export declare const RS_FORM_ITEM_INJECTION_KEY: InjectionKey<RsFormItemContext>;
+export declare function provideRsFormItemContext(context: RsFormItemContext): void;
+export declare function useRsFormItemContext(): RsFormItemContext | null;
+/**
+ * Form.List 上下文：子 Item 的 name 会拼上 List 前缀（users + [0, 'name'] → users.0.name）。
+ */
+export interface RsFormListContext {
+    prefix: ComputedRef<Array<string | number>>;
+}
+/** Form.List 默认插槽中的一行 */
+export interface RsFormListField {
+    /** 稳定行键，用于 v-for */
+    key: number;
+    /** 当前下标，作为子 Item name 的第一段 */
+    name: number;
+    index: number;
+}
+/** Form.List 增删改操作 */
+export interface RsFormListOperations {
+    add: (defaultValue?: unknown) => void;
+    remove: (index: number) => void;
+    move: (from: number, to: number) => void;
+}
+export declare const RS_FORM_LIST_INJECTION_KEY: InjectionKey<RsFormListContext>;
+export declare function provideRsFormListContext(context: RsFormListContext): void;
+export declare function useRsFormListContext(): RsFormListContext | null;
+export declare function provideRsFormContext(context: RsFormContext): void;
+export declare function useRsFormContext(): RsFormContext | null;
+/**
+ * 是否为 Form.Item 的绑定控件（对齐 Ant Design cloneElement）。
+ * name 与 Item 相同，或 id 等于 Item 注入的 fieldId。
+ */
+export declare function isRsFormItemBoundControl(item: RsFormItemContext | null | undefined, control: {
+    id?: string;
+    name?: string;
+}): boolean;
+export declare function useRsFormField(getExpose: () => RsFormFieldExpose | undefined): void;
+export declare function resolveRsFormSize(size?: RsFormSize, form?: RsFormContext | null): ComputedRef<RsFormSize>;
+/** 供 Form 内部解析某字段 rules */
+export declare function resolveFieldRules(rules: RsFormRules | undefined, name?: string): RsFormRuleItem[];

package/dist/components/form-utils.js

@@ -0,0 +1,67 @@
+import { normalizeFormRules } from "./form-rules.js";
+import { namePathKey } from "./form-path.js";
+import { inject, onMounted, onUnmounted, provide } from "vue";
+//#region src/components/form-utils.ts
+var RS_FORM_INJECTION_KEY = Symbol("RsForm");
+function cloneFormFieldValue(value) {
+	if (value === void 0 || value === null) return value;
+	if (typeof value !== "object") return value;
+	try {
+		return structuredClone(value);
+	} catch {
+		return value;
+	}
+}
+var RS_FORM_ITEM_INJECTION_KEY = Symbol("RsFormItem");
+function provideRsFormItemContext(context) {
+	provide(RS_FORM_ITEM_INJECTION_KEY, context);
+}
+function useRsFormItemContext() {
+	return inject(RS_FORM_ITEM_INJECTION_KEY, null);
+}
+var RS_FORM_LIST_INJECTION_KEY = Symbol("RsFormList");
+function provideRsFormListContext(context) {
+	provide(RS_FORM_LIST_INJECTION_KEY, context);
+}
+function useRsFormListContext() {
+	return inject(RS_FORM_LIST_INJECTION_KEY, null);
+}
+function provideRsFormContext(context) {
+	provide(RS_FORM_INJECTION_KEY, context);
+}
+function useRsFormContext() {
+	return inject(RS_FORM_INJECTION_KEY, null);
+}
+/**
+* 是否为 Form.Item 的绑定控件（对齐 Ant Design cloneElement）。
+* name 与 Item 相同，或 id 等于 Item 注入的 fieldId。
+*/
+function isRsFormItemBoundControl(item, control) {
+	if (!item?.ownsField.value) return false;
+	const itemName = item.name.value;
+	if (control.name && itemName && namePathKey(control.name) === itemName) return true;
+	if (control.id && control.id === item.fieldId.value) return true;
+	return false;
+}
+function useRsFormField(getExpose) {
+	const form = useRsFormContext();
+	const item = useRsFormItemContext();
+	if (!form) return;
+	const fieldId = Symbol("rs-form-field");
+	onMounted(() => {
+		if (item?.ownsField.value) return;
+		const expose = getExpose();
+		if (!expose?.name) return;
+		form.registerField(fieldId, expose);
+	});
+	onUnmounted(() => {
+		form.unregisterField(fieldId);
+	});
+}
+/** 供 Form 内部解析某字段 rules */
+function resolveFieldRules(rules, name) {
+	if (!name || !rules) return [];
+	return normalizeFormRules(rules[name]);
+}
+//#endregion
+export { RS_FORM_INJECTION_KEY, RS_FORM_ITEM_INJECTION_KEY, RS_FORM_LIST_INJECTION_KEY, cloneFormFieldValue, isRsFormItemBoundControl, provideRsFormContext, provideRsFormItemContext, provideRsFormListContext, resolveFieldRules, useRsFormContext, useRsFormField, useRsFormItemContext, useRsFormListContext };