@mrchar/cumquat 0.0.0-stage → 0.1.1

package/dist/composables/index.js

@@ -0,0 +1,4135 @@
+import { computed, getCurrentInstance, inject, isRef, nextTick, onBeforeUnmount, onMounted, onScopeDispose, provide, reactive, ref, shallowRef, toValue, useId as useId$1, watch } from "vue";
+//#region src/core/useId.ts
+let fallbackCount = 0;
+/**
+* SSR 安全的组件内唯一标识，用于 label/aria 关联。
+*
+* @param prefix 标识前缀，默认 `cq`
+* @returns 形如 `cq-input-0` 的只读字符串引用
+* @internal 消费组件：FormItem、Tooltip 及全部需要 aria 关联的控件
+*/
+function useId(prefix = "cq") {
+	const raw = getCurrentInstance() ? useId$1() : `f${fallbackCount++}`;
+	return computed(() => `${prefix}-${raw.replace(/[^a-zA-Z0-9_-]/g, "")}`);
+}
+//#endregion
+//#region src/core/useControllableModel.ts
+/**
+* 受控 / 非受控统一封装。
+*
+* - 传入 `modelValue` 时为受控：读外部值，写入时通过 onChange 回发事件；
+* - 仅传入 `defaultValue` 时为非受控：内部自持状态，写入同样回发事件以便宿主监听。
+*
+* `v-model` 永远是纯同步的，本函数不做任何异步编排。
+*/
+function useControllableModel(options = {}) {
+	const { modelValue, defaultValue, onChange, fallback, equals = Object.is } = options;
+	const controlledInput = typeof modelValue === "function" || isRef(modelValue);
+	const isControlled = ref(controlledInput || modelValue !== void 0);
+	const initial = toValue(modelValue);
+	const inner = ref(initial !== void 0 ? initial : defaultValue !== void 0 ? defaultValue : fallback);
+	const value = computed({
+		get: () => isControlled.value ? toValue(modelValue) : inner.value,
+		set: (next) => {
+			const current = isControlled.value ? toValue(modelValue) : inner.value;
+			if (current !== void 0 && equals(current, next)) return;
+			if (!isControlled.value) inner.value = next;
+			onChange?.(next);
+		}
+	});
+	const setValue = (next) => {
+		value.value = next;
+	};
+	return {
+		value,
+		setValue,
+		isControlled
+	};
+}
+/** 从标准 props 形态构造受控模型的便捷方法 */
+function createControllableModel(props, fallback) {
+	return useControllableModel({
+		modelValue: props.modelValue,
+		defaultValue: props.defaultValue,
+		fallback,
+		onChange: props["onUpdate:modelValue"]
+	});
+}
+//#endregion
+//#region src/core/useToggle.ts
+/**
+* 布尔状态及取反操作。
+*
+* @param initial 初始值，默认 false
+* @internal 消费组件：Switch、Layout、FloatButton
+*/
+function useToggle(initial = false) {
+	const value = ref(initial);
+	const toggle = (next) => {
+		value.value = typeof next === "boolean" ? next : !value.value;
+	};
+	const setTrue = () => {
+		value.value = true;
+	};
+	const setFalse = () => {
+		value.value = false;
+	};
+	return {
+		value,
+		toggle,
+		setTrue,
+		setFalse
+	};
+}
+//#endregion
+//#region src/internal/dom.ts
+/** 当前是否处于浏览器环境（惰性求值，保证 SSR 安全） */
+const isClient = typeof window !== "undefined";
+/** 将目标解析为真实 DOM 元素 */
+function toElement(target) {
+	if (!target) return null;
+	return toValue(target) ?? null;
+}
+/** 可聚焦元素选择器（焦点陷阱 / roving focus 共用） */
+const FOCUSABLE_SELECTOR = [
+	"a[href]",
+	"button:not([disabled])",
+	"textarea:not([disabled])",
+	"input:not([disabled])",
+	"select:not([disabled])",
+	"[tabindex]:not([tabindex=\"-1\"])",
+	"[contenteditable=\"true\"]"
+].join(",");
+/**
+* 获取容器内所有可聚焦元素（选择器已排除 disabled）。
+* 不做 offsetParent 可见性过滤：无布局环境（jsdom）与 display 切换中的
+* 元素仍需参与焦点管理，可见性由调用方保证。
+*/
+function getFocusableList(container) {
+	if (!container || !isClient) return [];
+	return Array.from(container.querySelectorAll(FOCUSABLE_SELECTOR));
+}
+/** 事件目标是否包含节点（用于外部点击判定） */
+function isEventInside(target, ...containers) {
+	if (!(target instanceof Node)) return false;
+	return containers.some((el) => !!el && el.contains(target));
+}
+/**
+* 注册一个在作用域销毁时自动执行的清理函数；
+* 无活动作用域时返回空操作注册器，避免 SSR 报错。
+*/
+function tryOnScopeDispose(fn) {
+	try {
+		onScopeDispose(fn);
+	} catch {}
+}
+/** 下一帧执行，返回取消函数（SSR 下降级为 setTimeout） */
+function rafThrottle(fn) {
+	if (!isClient || typeof requestAnimationFrame !== "function") {
+		const id = setTimeout(fn, 16);
+		return () => clearTimeout(id);
+	}
+	let scheduled = false;
+	const wrapped = () => {
+		scheduled = false;
+		fn();
+	};
+	return () => {
+		if (scheduled) return;
+		scheduled = true;
+		requestAnimationFrame(wrapped);
+	};
+}
+//#endregion
+//#region src/core/useEventListener.ts
+/**
+* 绑定 DOM 事件并在作用域销毁时自动卸载；目标支持响应式引用，
+* 目标变化（如 Teleport 后重挂载）时自动重新绑定。
+*
+* @param target 事件目标（元素 / window / document，可为 ref 或 getter）
+* @param event 事件名
+* @param listener 处理函数
+* @param options addEventListener 选项
+* @returns 手动解绑函数
+*/
+function useEventListener(target, event, listener, options) {
+	let cleanup;
+	const bind = (el) => {
+		cleanup?.();
+		cleanup = void 0;
+		if (!isClient || !el) return;
+		el.addEventListener(event, listener, options);
+		cleanup = () => el.removeEventListener(event, listener, options);
+	};
+	watch(() => toValue(target), bind, { immediate: true });
+	const stop = () => cleanup?.();
+	tryOnScopeDispose(stop);
+	return stop;
+}
+//#endregion
+//#region src/core/useResizeObserver.ts
+/**
+* 监听元素内容盒尺寸变化。SSR 环境下尺寸恒为 0 且不报错。
+*
+* @internal 消费方：useFloating；Watermark / Typography / VirtualList 组件内联复用
+*/
+function useResizeObserver(target) {
+	const width = ref(0);
+	const height = ref(0);
+	let observer;
+	const apply = (el) => {
+		observer?.disconnect();
+		observer = void 0;
+		if (!isClient || !el) return;
+		if (typeof ResizeObserver === "undefined") {
+			width.value = el.offsetWidth;
+			height.value = el.offsetHeight;
+			return;
+		}
+		observer = new ResizeObserver((entries) => {
+			const rect = entries[0]?.contentRect;
+			if (rect) {
+				width.value = rect.width;
+				height.value = rect.height;
+			}
+		});
+		observer.observe(el);
+	};
+	watch(() => toElement(target), apply, { immediate: true });
+	const stop = () => observer?.disconnect();
+	tryOnScopeDispose(stop);
+	return {
+		width,
+		height,
+		stop
+	};
+}
+//#endregion
+//#region src/core/useIntersectionObserver.ts
+/**
+* 监听元素进出视口状态。SSR 安全，不支持 IntersectionObserver 时按可见处理。
+*
+* @internal 消费方：useImageState 懒加载；宿主可独立使用
+*/
+function useIntersectionObserver(target, options = {}) {
+	const isIntersecting = ref(false);
+	const ratio = ref(0);
+	let observer;
+	const stop = () => {
+		observer?.disconnect();
+		observer = void 0;
+	};
+	const apply = (el) => {
+		stop();
+		if (!isClient || !el) return;
+		if (typeof IntersectionObserver === "undefined") {
+			isIntersecting.value = true;
+			return;
+		}
+		observer = new IntersectionObserver((entries) => {
+			const entry = entries[0];
+			if (!entry) return;
+			isIntersecting.value = entry.isIntersecting;
+			ratio.value = entry.intersectionRatio;
+			if (entry.isIntersecting && options.once) stop();
+		}, {
+			root: toElement(options.root ?? null),
+			rootMargin: options.rootMargin,
+			threshold: options.threshold
+		});
+		observer.observe(el);
+	};
+	watch(() => toElement(target), apply, { immediate: true });
+	tryOnScopeDispose(stop);
+	return {
+		isIntersecting,
+		ratio,
+		stop
+	};
+}
+//#endregion
+//#region src/core/useTimeoutFn.ts
+/**
+* 可随时停止 / 重启的一次性定时器，作用域销毁时自动清理。
+*
+* @param cb 到时回调
+* @param ms 延迟毫秒；构造时传 null/undefined 表示不自动启动，需手动 start
+* @internal 消费方：useOpen 延迟开合、useHoverIntent、useToastQueue、useTypeahead
+*/
+function useTimeoutFn(cb, ms) {
+	const isPending = ref(false);
+	let timer;
+	const stop = () => {
+		if (timer !== void 0) {
+			clearTimeout(timer);
+			timer = void 0;
+		}
+		isPending.value = false;
+	};
+	const start = (nextMs) => {
+		if (!isClient) return;
+		stop();
+		isPending.value = true;
+		timer = setTimeout(() => {
+			timer = void 0;
+			isPending.value = false;
+			cb();
+		}, nextMs ?? ms ?? 0);
+	};
+	if (ms !== void 0) start(ms);
+	tryOnScopeDispose(stop);
+	return {
+		isPending,
+		start,
+		stop
+	};
+}
+//#endregion
+//#region src/core/useIntervalFn.ts
+/**
+* 可暂停 / 恢复的周期定时器，作用域销毁时自动清理。
+*
+* @param cb 周期回调
+* @param interval 间隔毫秒，可随 resume 动态变更
+* @internal 消费方：Carousel 自动播放；宿主可独立使用
+*/
+function useIntervalFn(cb, interval = 1e3, options = {}) {
+	const { immediate = true, immediateCallback = false } = options;
+	const isActive = ref(false);
+	let timer;
+	const pause = () => {
+		if (timer !== void 0) {
+			clearInterval(timer);
+			timer = void 0;
+		}
+		isActive.value = false;
+	};
+	const resume = (nextInterval = interval) => {
+		if (!isClient || timer !== void 0 || nextInterval <= 0) return;
+		isActive.value = true;
+		if (immediateCallback) cb();
+		timer = setInterval(cb, nextInterval);
+	};
+	const restart = () => {
+		pause();
+		resume();
+	};
+	if (immediate) resume();
+	tryOnScopeDispose(pause);
+	return {
+		isActive,
+		pause,
+		resume,
+		restart
+	};
+}
+//#endregion
+//#region src/core/useMediaQuery.ts
+/**
+* 订阅 CSS 媒体查询结果。SSR 环境下恒为 false。
+* 查询串支持响应式引用，变化时自动重新订阅。
+*
+* @internal 消费组件：Layout、Grid；断点语义由宿主基于本函数自行封装
+*/
+function useMediaQuery(query) {
+	const matches = ref(false);
+	let mql;
+	const apply = (queryString) => {
+		if (!isClient || typeof window.matchMedia !== "function") {
+			matches.value = false;
+			return;
+		}
+		mql?.removeEventListener("change", onChange);
+		mql = window.matchMedia(queryString);
+		matches.value = mql.matches;
+		mql.addEventListener("change", onChange);
+	};
+	const onChange = (ev) => {
+		matches.value = ev.matches;
+	};
+	watch(() => toValue(query), apply, { immediate: true });
+	tryOnScopeDispose(() => mql?.removeEventListener("change", onChange));
+	return matches;
+}
+//#endregion
+//#region src/core/useScroll.ts
+/**
+* 监听目标元素或窗口的滚动位置与方向，SSR 安全。
+*
+* @param target 滚动容器（window / document / 元素），可为响应式
+* @internal 消费组件：Affix、Anchor、BackTop 内联复用；宿主可独立使用
+*/
+function useScroll(target = () => isClient ? window : void 0, options = {}) {
+	const { capture = true, direction: withDirection = true, throttle = true } = options;
+	const x = ref(0);
+	const y = ref(0);
+	const directionX = ref("none");
+	const directionY = ref("none");
+	const readPosition = (el) => {
+		if (!el) return;
+		if (el === window) {
+			x.value = window.scrollX;
+			y.value = window.scrollY;
+			return;
+		}
+		const node = el;
+		if (typeof node.scrollLeft === "number") {
+			x.value = node.scrollLeft;
+			y.value = node.scrollTop;
+		}
+	};
+	const handle = (() => {
+		let prevX = 0;
+		let prevY = 0;
+		const update = () => {
+			const el = toValue(target) ?? void 0;
+			const nextX = x.value;
+			const nextY = y.value;
+			readPosition(el);
+			if (withDirection) {
+				if (x.value > prevX) directionX.value = "right";
+				else if (x.value < prevX) directionX.value = "left";
+				if (y.value > prevY) directionY.value = "down";
+				else if (y.value < prevY) directionY.value = "up";
+			}
+			prevX = nextX;
+			prevY = nextY;
+		};
+		return throttle ? rafThrottle(update) : update;
+	})();
+	watch(() => toValue(target), (raw) => {
+		const el = raw === document ? toElement(document.documentElement) ?? window : raw;
+		readPosition(el);
+		el?.addEventListener("scroll", handle, {
+			capture,
+			passive: true
+		});
+	}, { immediate: true });
+	tryOnScopeDispose(() => {
+		toValue(target)?.removeEventListener("scroll", handle, { capture });
+	});
+	return {
+		x,
+		y,
+		directionX,
+		directionY
+	};
+}
+//#endregion
+//#region src/core/useScrollLock.ts
+let lockCount = 0;
+let previousOverflow = "";
+let previousPaddingRight = "";
+/**
+* 打开浮层时锁定背景滚动。采用引用计数，支持多浮层叠加；
+* 作用域销毁时自动释放一次锁定，SSR 安全。
+*
+* @param initial 初始是否锁定，默认 false
+* @internal 消费方：useModal 及下拉浮层
+*/
+function useScrollLock(initial = false) {
+	const isLocked = ref(false);
+	const lock = () => {
+		if (!isClient || isLocked.value) return;
+		if (lockCount === 0) {
+			const body = document.body;
+			previousOverflow = body.style.overflow;
+			previousPaddingRight = body.style.paddingRight;
+			const scrollbarWidth = window.innerWidth - body.clientWidth;
+			body.style.overflow = "hidden";
+			if (scrollbarWidth > 0) body.style.paddingRight = `${scrollbarWidth}px`;
+		}
+		lockCount += 1;
+		isLocked.value = true;
+	};
+	const unlock = () => {
+		if (!isClient || !isLocked.value) return;
+		lockCount = Math.max(0, lockCount - 1);
+		if (lockCount === 0) {
+			document.body.style.overflow = previousOverflow;
+			document.body.style.paddingRight = previousPaddingRight;
+		}
+		isLocked.value = false;
+	};
+	const toggle = (next) => {
+		if (next ?? !isLocked.value) lock();
+		else unlock();
+	};
+	if (initial) lock();
+	tryOnScopeDispose(unlock);
+	return {
+		isLocked,
+		lock,
+		unlock,
+		toggle
+	};
+}
+//#endregion
+//#region src/core/useScrollIntoView.ts
+/**
+* 将目标元素平滑滚动至可视区。返回命令式方法，供 Tour/Anchor/Tabs 复用。
+*
+* @param defaultTarget 默认滚动目标（调用时可覆盖）
+*/
+function useScrollIntoView(defaultTarget) {
+	return (target = defaultTarget, options = {}) => {
+		if (!isClient) return;
+		toElement(target ?? null)?.scrollIntoView({
+			behavior: options.behavior ?? "smooth",
+			block: options.block ?? "start",
+			inline: options.inline ?? "nearest"
+		});
+	};
+}
+//#endregion
+//#region src/core/useClickOutside.ts
+/**
+* 点击目标元素外部时触发回调。SSR 安全，作用域销毁自动解绑。
+*
+* @internal 消费方：useDismiss 及各选择器组件
+*/
+function useClickOutside(target, handler, options = {}) {
+	if (!isClient) return;
+	const { enabled = true, event = "pointerdown" } = options;
+	const listener = (ev) => {
+		if (!toValue(enabled)) return;
+		const main = toElement(target);
+		if (!main) return;
+		const extras = (toValue(options.ignore ?? []) ?? []).map((item) => toElement(item)).filter((el) => !!el);
+		if (isEventInside(ev.target, main, ...extras)) return;
+		handler(ev);
+	};
+	document.addEventListener(event, listener, true);
+	tryOnScopeDispose(() => {
+		document.removeEventListener(event, listener, true);
+	});
+}
+//#endregion
+//#region src/core/useFocusTrap.ts
+/**
+* 焦点陷阱：激活期间 Tab 在容器内循环，Esc 不做处理（由 useDismiss 编排）。
+*
+* @param container 陷阱容器，可为响应式引用
+* @internal 消费方：useModal
+*/
+function useFocusTrap(container, options = {}) {
+	const { initialFocus, immediate = true } = options;
+	const isActive = ref(false);
+	const focusFirst = () => {
+		getFocusableList(toValue(container))[0]?.focus();
+	};
+	const focusLast = () => {
+		const list = getFocusableList(toValue(container));
+		list[list.length - 1]?.focus();
+	};
+	const onKeydown = (ev) => {
+		if (ev.key !== "Tab" || !isActive.value) return;
+		const el = toValue(container);
+		if (!el) return;
+		const list = getFocusableList(el);
+		if (list.length === 0) {
+			ev.preventDefault();
+			return;
+		}
+		const first = list[0];
+		const last = list[list.length - 1];
+		const active = document.activeElement;
+		if (ev.shiftKey && (active === first || !el.contains(active))) {
+			ev.preventDefault();
+			last.focus();
+		} else if (!ev.shiftKey && active === last) {
+			ev.preventDefault();
+			first.focus();
+		}
+	};
+	const trap = () => {
+		if (!isClient || isActive.value) return;
+		isActive.value = true;
+		document.addEventListener("keydown", onKeydown, true);
+		if (immediate) {
+			const el = toValue(container);
+			((initialFocus ? el?.querySelector(initialFocus) : null) ?? getFocusableList(el)[0] ?? el)?.focus();
+		}
+	};
+	const release = () => {
+		if (!isActive.value) return;
+		isActive.value = false;
+		document.removeEventListener("keydown", onKeydown, true);
+	};
+	tryOnScopeDispose(release);
+	return {
+		isActive,
+		trap,
+		release,
+		focusFirst,
+		focusLast
+	};
+}
+//#endregion
+//#region src/core/useFocusReturn.ts
+/**
+* 浮层关闭后将焦点归还至打开前的元素。
+*
+* @internal 消费方：useModal、usePopoverModel
+*/
+function useFocusReturn(options = {}) {
+	const { autoRestore = true } = options;
+	let previous = null;
+	const record = () => {
+		if (!isClient) return;
+		previous = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+	};
+	const restore = () => {
+		if (!isClient || !previous || !previous.isConnected) {
+			previous = null;
+			return;
+		}
+		previous.focus({ preventScroll: true });
+		previous = null;
+	};
+	if (autoRestore) tryOnScopeDispose(restore);
+	return {
+		record,
+		restore
+	};
+}
+//#endregion
+//#region src/core/useRovingFocus.ts
+/**
+* 列表内 roving-tabindex 焦点管理：方向键 / Home / End 移动激活项，
+* 自动跳过禁用项，可选循环。Tab 只落到当前激活项。
+*
+* @internal 消费组件：Select、Menu、Tabs、Segmented、Tree
+*/
+function useRovingFocus(options) {
+	const { count, isItemDisabled = () => false, orientation = "vertical", loop = true, initialIndex = 0, autofocus = true, container } = options;
+	const activeIndex = ref(initialIndex);
+	const getCount = () => Math.max(0, toValue(count));
+	const isEnabledIndex = (index) => index >= 0 && index < getCount() && !isItemDisabled(index);
+	const findEnabled = (from, step) => {
+		const total = getCount();
+		let cursor = from;
+		for (let i = 0; i < total; i += 1) {
+			cursor += step;
+			if (cursor < 0 || cursor >= total) {
+				if (!loop) return from;
+				cursor = cursor < 0 ? total - 1 : 0;
+			}
+			if (!isItemDisabled(cursor)) return cursor;
+		}
+		return from;
+	};
+	const setActiveIndex = (index) => {
+		if (!isEnabledIndex(index)) return;
+		activeIndex.value = index;
+		if (autofocus && isClient && container) (toElement(container)?.querySelectorAll("[data-roving-index]"))?.[index]?.focus();
+	};
+	const move = (step) => {
+		const next = findEnabled(activeIndex.value, step);
+		if (next !== activeIndex.value) setActiveIndex(next);
+	};
+	const first = () => {
+		const next = Array.from({ length: getCount() }, (_, i) => i).find((i) => !isItemDisabled(i));
+		if (next !== void 0) setActiveIndex(next);
+	};
+	const last = () => {
+		for (let i = getCount() - 1; i >= 0; i -= 1) if (!isItemDisabled(i)) {
+			setActiveIndex(i);
+			return;
+		}
+	};
+	const onKeydown = (event) => {
+		const allowVertical = orientation !== "horizontal";
+		const allowHorizontal = orientation !== "vertical";
+		switch (event.key) {
+			case "ArrowDown":
+				if (allowVertical) {
+					event.preventDefault();
+					move(1);
+				}
+				break;
+			case "ArrowUp":
+				if (allowVertical) {
+					event.preventDefault();
+					move(-1);
+				}
+				break;
+			case "ArrowRight":
+				if (allowHorizontal) {
+					event.preventDefault();
+					move(1);
+				}
+				break;
+			case "ArrowLeft":
+				if (allowHorizontal) {
+					event.preventDefault();
+					move(-1);
+				}
+				break;
+			case "Home":
+				event.preventDefault();
+				first();
+				break;
+			case "End":
+				event.preventDefault();
+				last();
+		}
+	};
+	const getTabIndex = (index) => index === activeIndex.value ? 0 : -1;
+	const onItemFocus = (index) => () => {
+		activeIndex.value = index;
+		if (!autofocus && container) {
+			const el = toElement(container);
+			if (el) getFocusableList(el)[index]?.setAttribute("tabindex", "0");
+		}
+	};
+	return {
+		activeIndex,
+		setActiveIndex,
+		onKeydown,
+		getTabIndex,
+		onItemFocus
+	};
+}
+//#endregion
+//#region src/core/useTypeahead.ts
+/**
+* 键盘输入匹配选项：在重置间隔内连续输入字符组成搜索串，
+* 按前缀匹配选项标签并跳转，单字符重复按时序循环匹配。
+*
+* @internal 消费组件：Select、Menu、Tree
+*/
+function useTypeahead(options) {
+	const { getLabels, onMatch, resetDelay = 500, loop = true } = options;
+	const startIndex = options.startIndex ?? (() => lastMatchIndex);
+	const query = ref("");
+	let lastKeyTime = 0;
+	let lastMatchIndex = -1;
+	const timer = useTimeoutFn(() => reset());
+	function reset() {
+		query.value = "";
+		lastMatchIndex = -1;
+	}
+	const onKeydown = (event) => {
+		if (event.ctrlKey || event.metaKey || event.altKey) return;
+		if (event.key.length !== 1) return;
+		const labels = getLabels();
+		if (labels.length === 0) return;
+		const now = Date.now();
+		if (now - lastKeyTime > resetDelay) reset();
+		lastKeyTime = now;
+		const char = event.key.toLowerCase();
+		const isRepeatSingle = query.value.length === 1 && query.value === char;
+		query.value = isRepeatSingle ? char : query.value + char;
+		const keyword = query.value.toLowerCase();
+		let matched = -1;
+		if (isRepeatSingle) for (let step = 1; step <= labels.length; step += 1) {
+			const idx = (lastMatchIndex + step) % labels.length;
+			if (!loop && idx <= lastMatchIndex) break;
+			if (labels[idx].toLowerCase().startsWith(char)) {
+				matched = idx;
+				break;
+			}
+		}
+		else {
+			const start = startIndex();
+			for (let step = 0; step < labels.length; step += 1) {
+				const idx = (start + 1 + step) % labels.length;
+				if (labels[idx].toLowerCase().startsWith(keyword)) {
+					matched = idx;
+					break;
+				}
+			}
+		}
+		timer.start();
+		if (matched !== -1) {
+			lastMatchIndex = matched;
+			onMatch?.(matched);
+		}
+	};
+	return {
+		query,
+		onKeydown,
+		reset
+	};
+}
+//#endregion
+//#region src/core/useDraggable.ts
+const clamp = (value, min = 0, max = 1) => Math.min(max, Math.max(min, value));
+/**
+* 基于 Pointer Events 的拖拽原语：在目标元素盒内测量归一化位置，
+* 自动处理边界钳制、指针捕获与清理。Slider / ColorPicker 共用同一份几何计算。
+*/
+function useDraggable(target, options = {}) {
+	const { handle, axis = "both", bounds, initialRatio = {
+		x: 0,
+		y: 0
+	}, disabled = false, onStart, onMove, onEnd } = options;
+	const dragging = ref(false);
+	const x = ref(0);
+	const y = ref(0);
+	const ratioX = ref(clamp(initialRatio.x));
+	const ratioY = ref(clamp(initialRatio.y));
+	let rect = null;
+	const currentPosition = () => ({
+		x: x.value,
+		y: y.value,
+		ratioX: ratioX.value,
+		ratioY: ratioY.value
+	});
+	const readPosition = (clientX, clientY) => {
+		const box = rect ?? toElement(bounds ?? target)?.getBoundingClientRect() ?? null;
+		if (!box || box.width === 0 || box.height === 0) return currentPosition();
+		const nextRatioX = clamp((clientX - box.left) / box.width);
+		const nextRatioY = clamp((clientY - box.top) / box.height);
+		if (axis === "x") ratioX.value = nextRatioX;
+		else if (axis === "y") ratioY.value = nextRatioY;
+		else {
+			ratioX.value = nextRatioX;
+			ratioY.value = nextRatioY;
+		}
+		x.value = ratioX.value * box.width;
+		y.value = ratioY.value * box.height;
+		return currentPosition();
+	};
+	const onPointerMove = (event) => {
+		if (!dragging.value) return;
+		const position = readPosition(event.clientX, event.clientY);
+		onMove?.(position, event);
+	};
+	const onPointerUp = (event) => {
+		if (!dragging.value) return;
+		dragging.value = false;
+		try {
+			toElement(handle ?? target)?.releasePointerCapture?.(event.pointerId);
+		} catch {}
+		document.removeEventListener("pointermove", onPointerMove);
+		document.removeEventListener("pointerup", onPointerUp);
+		onEnd?.(currentPosition(), event);
+	};
+	const onPointerDown = (event) => {
+		if (!isClient || toValue(disabled) || event.button !== 0) return;
+		rect = toElement(bounds ?? target)?.getBoundingClientRect() ?? null;
+		dragging.value = true;
+		try {
+			toElement(handle ?? target)?.setPointerCapture?.(event.pointerId);
+		} catch {}
+		document.addEventListener("pointermove", onPointerMove);
+		document.addEventListener("pointerup", onPointerUp);
+		const position = readPosition(event.clientX, event.clientY);
+		onStart?.(position, event);
+	};
+	watch(() => toElement(handle ?? target), (el, oldEl) => {
+		oldEl?.removeEventListener("pointerdown", onPointerDown);
+		el?.addEventListener("pointerdown", onPointerDown);
+	}, { immediate: true });
+	const moveToRatio = (nextX, nextY) => {
+		ratioX.value = axis === "y" ? ratioX.value : clamp(nextX);
+		ratioY.value = axis === "x" ? ratioY.value : clamp(nextY);
+		const box = toElement(bounds ?? target)?.getBoundingClientRect();
+		if (box) {
+			x.value = ratioX.value * box.width;
+			y.value = ratioY.value * box.height;
+		}
+	};
+	tryOnScopeDispose(() => {
+		document.removeEventListener("pointermove", onPointerMove);
+		document.removeEventListener("pointerup", onPointerUp);
+	});
+	return {
+		x,
+		y,
+		ratioX,
+		ratioY,
+		dragging,
+		moveToRatio
+	};
+}
+//#endregion
+//#region src/core/useClipboard.ts
+/**
+* 复制文本到剪贴板，自动派生短暂的成功反馈；
+* 不支持 Clipboard API 时降级为隐藏 textarea + execCommand。
+*
+* @internal 消费组件：Typography；宿主可独立使用
+*/
+function useClipboard(options = {}) {
+	const { copiedDuration = 1500, legacy = true } = options;
+	const copied = ref(false);
+	const error = ref(null);
+	const timer = useTimeoutFn(() => {
+		copied.value = false;
+	});
+	const legacyCopy = (text) => {
+		if (!isClient) return false;
+		const textarea = document.createElement("textarea");
+		textarea.value = text;
+		textarea.setAttribute("readonly", "");
+		textarea.style.position = "fixed";
+		textarea.style.opacity = "0";
+		document.body.appendChild(textarea);
+		textarea.select();
+		try {
+			return document.execCommand("copy");
+		} finally {
+			document.body.removeChild(textarea);
+		}
+	};
+	const copy = async (text) => {
+		error.value = null;
+		let succeeded = false;
+		try {
+			if (isClient && navigator.clipboard?.writeText) try {
+				await navigator.clipboard.writeText(text);
+				succeeded = true;
+			} catch (apiErr) {
+				if (legacy && legacyCopy(text)) succeeded = true;
+				else throw apiErr;
+			}
+			else if (legacy) {
+				if (!legacyCopy(text)) throw new Error("clipboard unavailable");
+				succeeded = true;
+			} else throw new Error("clipboard unavailable");
+		} catch (err) {
+			error.value = err;
+			copied.value = false;
+			return false;
+		}
+		if (succeeded) {
+			copied.value = true;
+			timer.start(copiedDuration);
+		}
+		return succeeded;
+	};
+	return {
+		copied,
+		error,
+		copy
+	};
+}
+//#endregion
+//#region src/core/useTransitionVisible.ts
+/**
+* 进出场过渡的挂载状态机：
+* - 打开时先 rendered=true（挂载），下一帧 visible=true（触发进入过渡）；
+* - 关闭时 visible=false（触发离开过渡），after-leave 后 rendered=false（卸载）。
+*
+* 组件模板用法：
+* `<Transition @after-leave="onAfterLeave"><div v-if="rendered" v-show="visible" />`
+*
+* @param isOpen 开合来源（ref / getter）
+*/
+function useTransitionVisible(isOpen) {
+	const rendered = ref(toValue(isOpen));
+	const visible = ref(false);
+	watch(() => toValue(isOpen), (open) => {
+		if (open) {
+			rendered.value = true;
+			nextTick(() => {
+				visible.value = true;
+			});
+		} else visible.value = false;
+	}, {
+		immediate: true,
+		flush: "sync"
+	});
+	const onAfterLeave = () => {
+		rendered.value = false;
+	};
+	return {
+		rendered,
+		visible,
+		onAfterLeave
+	};
+}
+//#endregion
+//#region src/core/useZIndex.ts
+const BASE_Z_INDEX = 2e3;
+let globalZIndex = BASE_Z_INDEX;
+/**
+* 全局浮层层级递增管理。Dialog/Drawer/Popover/Message/Notification
+* 共用同一序列，组件卸载无需回收（仅单调递增）。
+*/
+function useZIndex(initial) {
+	const currentZIndex = ref(initial ?? globalZIndex);
+	const nextZIndex = () => {
+		globalZIndex += 1;
+		currentZIndex.value = globalZIndex;
+		return globalZIndex;
+	};
+	return {
+		currentZIndex,
+		nextZIndex,
+		getGlobalZIndex: () => globalZIndex
+	};
+}
+/** 重置全局层级（仅供测试使用） */
+function resetGlobalZIndex(value = BASE_Z_INDEX) {
+	globalZIndex = value;
+}
+//#endregion
+//#region src/behavior/useOpen.ts
+/**
+* 开合状态机：支持受控（modelValue + update:modelValue）与非受控，
+* 可选的打开 / 关闭延迟（由 useHoverIntent 之类场景复用）。
+*
+* @internal 消费组件：Dialog/Drawer（经 useModal）、Popover、Dropdown、Select、Tooltip
+*/
+function useOpen(options = {}) {
+	const { openDelay = 0, closeDelay = 0, onChange, ...controlled } = options;
+	const { value } = useControllableModel({
+		modelValue: controlled.modelValue,
+		defaultValue: controlled.defaultValue,
+		fallback: false,
+		onChange: (next) => {
+			controlled["onUpdate:modelValue"]?.(next);
+			onChange?.(next);
+		}
+	});
+	const isOpen = value;
+	const openTimer = useTimeoutFn(() => {
+		isOpen.value = true;
+	});
+	const closeTimer = useTimeoutFn(() => {
+		isOpen.value = false;
+	});
+	const open = () => {
+		closeTimer.stop();
+		if (openDelay > 0) openTimer.start(openDelay);
+		else isOpen.value = true;
+	};
+	const close = () => {
+		openTimer.stop();
+		if (closeDelay > 0) closeTimer.start(closeDelay);
+		else isOpen.value = false;
+	};
+	const toggle = (next) => {
+		if (next ?? !isOpen.value) open();
+		else close();
+	};
+	return {
+		isOpen,
+		open,
+		close,
+		toggle
+	};
+}
+//#endregion
+//#region src/behavior/useDismiss.ts
+/**
+* ESC、外部点击、滚动失焦的统一关闭编排。仅在浮层打开时生效，
+* 监听器随作用域自动清理。
+*
+* @internal 消费组件：全部浮层（经 useModal / usePopoverModel 或直接使用）
+*/
+function useDismiss(options) {
+	const { isOpen, reference, floating, onDismiss, escapeKey = true, outsidePress = true, outsidePressEvent = "pointerdown", scroll = false, enabled = true } = options;
+	const active = () => isClient && toValue(isOpen) && toValue(enabled);
+	useEventListener(isClient ? document : null, "keydown", (event) => {
+		if (!active() || !escapeKey || event.key !== "Escape") return;
+		event.stopPropagation();
+		onDismiss("escape-key");
+	}, true);
+	useEventListener(isClient ? document : null, outsidePressEvent, (event) => {
+		if (!active() || !outsidePress) return;
+		if (isEventInside(event.target, toElement(reference ?? null), toElement(floating ?? null))) return;
+		onDismiss("outside-press");
+	}, true);
+	useEventListener(isClient ? window : null, "scroll", () => {
+		if (!active() || !scroll) return;
+		onDismiss("scroll");
+	}, true);
+}
+//#endregion
+//#region src/behavior/useFloating.ts
+const OPPOSITE_SIDE = {
+	top: "bottom",
+	bottom: "top",
+	left: "right",
+	right: "left"
+};
+function splitPlacement(placement) {
+	const [side, align] = placement.split("-");
+	return [side, align ?? "middle"];
+}
+function joinPlacement(side, align) {
+	return align === "middle" ? side : `${side}-${align}`;
+}
+/** 按方位与对齐计算未修正的基准坐标 */
+function computeBaseCoords(side, align, reference, floating, gap) {
+	let x = 0;
+	let y = 0;
+	switch (side) {
+		case "bottom":
+			y = reference.bottom + gap;
+			break;
+		case "top":
+			y = reference.top - floating.height - gap;
+			break;
+		case "right":
+			x = reference.right + gap;
+			break;
+		case "left": x = reference.left - floating.width - gap;
+	}
+	if (side === "bottom" || side === "top") {
+		if (align === "start") x = reference.left;
+		else if (align === "end") x = reference.right - floating.width;
+		else x = reference.left + (reference.width - floating.width) / 2;
+	} else if (align === "start") y = reference.top;
+	else if (align === "end") y = reference.bottom - floating.height;
+	else y = reference.top + (reference.height - floating.height) / 2;
+	return {
+		x,
+		y
+	};
+}
+/** 判定给定方位是否有足够空间（含视口留白） */
+function sideHasSpace(side, reference, floating, gap, padding) {
+	switch (side) {
+		case "top": return reference.top - gap - floating.height >= padding;
+		case "bottom": return window.innerHeight - reference.bottom - gap - floating.height >= padding;
+		case "left": return reference.left - gap - floating.width >= padding;
+		case "right": return window.innerWidth - reference.right - gap - floating.width >= padding;
+	}
+}
+/**
+* 锚点浮层定位引擎：方位、自动翻转、视口移位、间距、箭头坐标；
+* 滚动、窗口尺寸、锚点与浮层尺寸变化时自动更新。零第三方依赖。
+*
+* @internal 消费组件：Tooltip/Popover/Dropdown/Select/Cascader/DatePicker/
+* TimePicker/ColorPicker/TreeSelect/AutoComplete/Mention/Popconfirm
+*/
+function useFloating(options = {}) {
+	const { placement = "bottom", strategy = "fixed", gap = 4, shiftPadding = 4, flip = true, shift = true, arrowSize, open, onPositioned } = options;
+	const referenceRef = ref(null);
+	const floatingRef = ref(null);
+	const arrowRef = ref(null);
+	const currentPlacement = ref(toValue(placement));
+	const x = ref(0);
+	const y = ref(0);
+	const arrowX = ref(void 0);
+	const arrowY = ref(void 0);
+	const applyOffset = (coords) => {
+		if (strategy !== "absolute") return coords;
+		const offsetParent = floatingRef.value?.offsetParent;
+		if (!offsetParent || offsetParent === document.body) return coords;
+		const parent = offsetParent.getBoundingClientRect();
+		return {
+			x: coords.x - parent.left,
+			y: coords.y - parent.top
+		};
+	};
+	const update = () => {
+		if (!isClient) return;
+		const referenceEl = referenceRef.value;
+		const floatingEl = floatingRef.value;
+		if (!referenceEl || !floatingEl) return;
+		const referenceRect = referenceEl.getBoundingClientRect();
+		const floatingRect = floatingEl.getBoundingClientRect();
+		const size = {
+			width: floatingRect.width,
+			height: floatingRect.height
+		};
+		let [side, align] = splitPlacement(toValue(placement));
+		if (flip && !sideHasSpace(side, referenceRect, size, gap, shiftPadding)) {
+			const opposite = OPPOSITE_SIDE[side];
+			if (sideHasSpace(opposite, referenceRect, size, gap, shiftPadding)) side = opposite;
+		}
+		let coords = computeBaseCoords(side, align, referenceRect, size, gap);
+		if (shift) {
+			const minX = shiftPadding;
+			const maxX = window.innerWidth - size.width - shiftPadding;
+			const minY = shiftPadding;
+			const maxY = window.innerHeight - size.height - shiftPadding;
+			coords = {
+				x: Math.min(Math.max(coords.x, minX), Math.max(minX, maxX)),
+				y: Math.min(Math.max(coords.y, minY), Math.max(minY, maxY))
+			};
+		}
+		coords = applyOffset(coords);
+		x.value = coords.x;
+		y.value = coords.y;
+		currentPlacement.value = joinPlacement(side, align);
+		const arrowEl = arrowRef.value;
+		if (arrowEl) {
+			const arrow = arrowSize ?? arrowEl.offsetWidth ?? 0;
+			const referenceCenterX = (referenceRect.left + referenceRect.right) / 2 - coords.x;
+			const referenceCenterY = (referenceRect.top + referenceRect.bottom) / 2 - coords.y;
+			const min = shiftPadding;
+			const maxX = Math.max(min, size.width - arrow - shiftPadding);
+			const maxY = Math.max(min, size.height - arrow - shiftPadding);
+			if (side === "top" || side === "bottom") {
+				arrowX.value = Math.min(Math.max(referenceCenterX - arrow / 2, min), maxX);
+				arrowY.value = void 0;
+			} else {
+				arrowY.value = Math.min(Math.max(referenceCenterY - arrow / 2, min), maxY);
+				arrowX.value = void 0;
+			}
+		}
+		onPositioned?.({
+			placement: currentPlacement.value,
+			x: coords.x,
+			y: coords.y
+		});
+	};
+	const floatingStyles = computed(() => ({
+		position: strategy,
+		left: 0,
+		top: 0,
+		transform: `translate(${Math.round(x.value)}px, ${Math.round(y.value)}px)`
+	}));
+	useResizeObserver(referenceRef);
+	useResizeObserver(floatingRef);
+	useEventListener(isClient ? window : null, "resize", update);
+	useEventListener(isClient ? window : null, "scroll", update, {
+		capture: true,
+		passive: true
+	});
+	watch(() => [
+		referenceRef.value,
+		floatingRef.value,
+		toValue(placement)
+	], () => nextTick(update), {
+		immediate: true,
+		flush: "post"
+	});
+	if (open !== void 0) watch(() => toValue(open), (isOpen) => {
+		if (isOpen) nextTick(update);
+	});
+	watch(() => [floatingRef.value?.offsetWidth, floatingRef.value?.offsetHeight], () => update());
+	return {
+		referenceRef,
+		floatingRef,
+		arrowRef,
+		placement: currentPlacement,
+		x,
+		y,
+		arrowX,
+		arrowY,
+		floatingStyles,
+		update
+	};
+}
+//#endregion
+//#region src/behavior/useHoverIntent.ts
+/**
+* 悬停触发的开合延迟控制，防止抖动与误触。
+* 触发器与浮层应同时绑定返回的 enter/leave 处理器。
+*
+* @internal 消费组件：Tooltip、Dropdown(hover)、Menu
+*/
+function useHoverIntent(options = {}) {
+	const { showDelay = 100, hideDelay = 100, disabled = false } = options;
+	const isHovered = ref(false);
+	const showTimer = useTimeoutFn(() => {
+		isHovered.value = true;
+	});
+	const hideTimer = useTimeoutFn(() => {
+		isHovered.value = false;
+	});
+	const onMouseEnter = () => {
+		if (disabled) return;
+		hideTimer.stop();
+		if (showDelay <= 0) isHovered.value = true;
+		else showTimer.start(showDelay);
+	};
+	const onMouseLeave = () => {
+		if (disabled) return;
+		showTimer.stop();
+		if (hideDelay <= 0) isHovered.value = false;
+		else hideTimer.start(hideDelay);
+	};
+	const setOpen = (open) => {
+		showTimer.stop();
+		hideTimer.stop();
+		isHovered.value = open;
+	};
+	return {
+		isHovered,
+		onMouseEnter,
+		onMouseLeave,
+		setOpen
+	};
+}
+//#endregion
+//#region src/behavior/useListboxNavigation.ts
+/**
+* 选项列表键盘导航：上下移动、Home/End、回车选中、禁用项跳过、边界循环。
+* 与焦点管理解耦——本函数只维护逻辑激活索引。
+*
+* @internal 消费组件：Select、Dropdown、Menu、Cascader、AutoComplete、
+* Mention、Segmented、TreeSelect、TimePicker
+*/
+function useListboxNavigation(options) {
+	const { count, isItemDisabled = () => false, orientation = "vertical", loop = true, initialIndex = -1, onSelect, onActiveChange } = options;
+	const activeIndex = ref(initialIndex);
+	const getCount = () => Math.max(0, toValue(count));
+	const setActiveIndex = (index) => {
+		if (index !== -1 && (index < 0 || index >= getCount())) return;
+		activeIndex.value = index;
+		onActiveChange?.(index);
+	};
+	const findEnabled = (from, step) => {
+		const total = getCount();
+		if (total === 0) return -1;
+		let cursor = from;
+		for (let i = 0; i < total; i += 1) {
+			cursor += step;
+			if (cursor < 0 || cursor >= total) {
+				if (!loop) return from;
+				cursor = cursor < 0 ? total - 1 : 0;
+			}
+			if (!isItemDisabled(cursor)) return cursor;
+		}
+		return from;
+	};
+	const moveNext = () => {
+		const next = findEnabled(activeIndex.value, 1);
+		if (next !== activeIndex.value && next !== -1) setActiveIndex(next);
+	};
+	const movePrev = () => {
+		const prev = findEnabled(activeIndex.value, -1);
+		if (prev !== activeIndex.value && prev !== -1) setActiveIndex(prev);
+	};
+	const moveFirst = () => {
+		const first = findEnabled(-1, 1);
+		if (first !== -1) setActiveIndex(first);
+	};
+	const moveLast = () => {
+		for (let i = getCount() - 1; i >= 0; i -= 1) if (!isItemDisabled(i)) {
+			setActiveIndex(i);
+			return;
+		}
+	};
+	const selectActive = () => {
+		const index = activeIndex.value;
+		if (index >= 0 && !isItemDisabled(index)) onSelect?.(index);
+	};
+	const onKeydown = (event) => {
+		const allowVertical = orientation !== "horizontal";
+		const allowHorizontal = orientation !== "vertical";
+		switch (event.key) {
+			case "ArrowDown":
+				if (allowVertical) {
+					event.preventDefault();
+					moveNext();
+				}
+				break;
+			case "ArrowUp":
+				if (allowVertical) {
+					event.preventDefault();
+					movePrev();
+				}
+				break;
+			case "ArrowRight":
+				if (allowHorizontal) {
+					event.preventDefault();
+					moveNext();
+				}
+				break;
+			case "ArrowLeft":
+				if (allowHorizontal) {
+					event.preventDefault();
+					movePrev();
+				}
+				break;
+			case "Home":
+				event.preventDefault();
+				moveFirst();
+				break;
+			case "End":
+				event.preventDefault();
+				moveLast();
+				break;
+			case "Enter":
+			case " ":
+				event.preventDefault();
+				selectActive();
+		}
+	};
+	const reset = () => setActiveIndex(initialIndex);
+	return {
+		activeIndex,
+		setActiveIndex,
+		moveNext,
+		movePrev,
+		moveFirst,
+		moveLast,
+		onKeydown,
+		reset
+	};
+}
+//#endregion
+//#region src/behavior/useAsyncState.ts
+/**
+* 将外部异步函数包装为标准 AsyncStateLike：
+* 管理 pending/success/error 三态、重试与 stale 标记。
+* 函数自身不发起任何业务请求——请求函数由宿主提供。
+*
+* @param fetcher 返回 Promise 的数据获取函数
+* @internal 消费方：远程 Select/AutoComplete/Mention；Table 内联编排；宿主可独立使用
+*/
+function useAsyncState(fetcher, options = {}) {
+	const { initialData, immediate = true, immediateArgs, preserveDataOnRefresh = true, onSuccess, onError } = options;
+	const state = ref({
+		status: "pending",
+		data: initialData
+	});
+	const loading = ref(true);
+	const error = ref(void 0);
+	let lastArgs = immediateArgs;
+	let requestId = 0;
+	const run = async (...args) => {
+		const currentId = ++requestId;
+		lastArgs = args;
+		const hadSuccess = state.value.status === "success";
+		state.value = {
+			status: "pending",
+			data: hadSuccess && preserveDataOnRefresh ? state.value.data : initialData,
+			isStale: hadSuccess,
+			retry: () => retry()
+		};
+		loading.value = true;
+		error.value = void 0;
+		try {
+			const data = await fetcher(...args);
+			if (currentId !== requestId) return void 0;
+			state.value = {
+				status: "success",
+				data,
+				isStale: false,
+				retry: () => retry()
+			};
+			error.value = void 0;
+			onSuccess?.(data, ...args);
+			return data;
+		} catch (err) {
+			if (currentId !== requestId) return void 0;
+			state.value = {
+				status: "error",
+				data: state.value.data,
+				error: err,
+				isStale: false,
+				retry: () => retry()
+			};
+			error.value = err;
+			onError?.(err, ...args);
+			return;
+		} finally {
+			if (currentId === requestId) loading.value = false;
+		}
+	};
+	const retry = () => run(...lastArgs ?? []);
+	if (immediate) run(...immediateArgs ?? []);
+	else {
+		loading.value = false;
+		state.value = {
+			status: "success",
+			data: initialData,
+			retry: () => retry()
+		};
+	}
+	return {
+		state,
+		run,
+		retry,
+		loading,
+		error
+	};
+}
+//#endregion
+//#region src/behavior/useActionState.ts
+/** 归一 action 返回值：resolve 值导出错误（status 为 error 或携带 error）时返回失败信息，否则 null */
+function extractActionFailure(result) {
+	if (result !== null && typeof result === "object") {
+		const { status, error } = result;
+		if (status === "error" || error != null) return { error: error ?? result };
+	}
+	return null;
+}
+/** 把动作错误归一为可展示文案：优先 message，其次 error 字符串 / Error.message，最后回退文案 */
+function actionErrorText(error, fallback = "操作失败") {
+	if (error && typeof error === "object") {
+		const candidate = error;
+		if (typeof candidate.message === "string" && candidate.message) return candidate.message;
+		if (candidate.error != null) return actionErrorText(candidate.error, fallback);
+	}
+	if (typeof error === "string" && error) return error;
+	if (error instanceof Error && error.message) return error.message;
+	return fallback;
+}
+/**
+* 消费 ActionLike：执行期间自动派生 pending / disabled，错误归一存储。
+*
+* @internal 消费组件：Button、Switch、Popconfirm、Upload、Form 提交
+*/
+function useActionState(action, options = {}) {
+	const { disableOnPending = true, disabled, onSuccess, onError, onFinally } = options;
+	const pending = ref(false);
+	const error = ref(void 0);
+	const disabledState = computed(() => disableOnPending && pending.value || disabled?.() === true);
+	const run = async (...args) => {
+		if (pending.value || disabled?.()) return void 0;
+		pending.value = true;
+		error.value = void 0;
+		try {
+			const result = await action?.(...args);
+			const failure = extractActionFailure(result);
+			if (failure) {
+				error.value = failure.error;
+				onError?.(failure.error);
+				return result;
+			}
+			onSuccess?.(result);
+			return result;
+		} catch (err) {
+			error.value = err;
+			onError?.(err);
+			return;
+		} finally {
+			pending.value = false;
+			onFinally?.();
+		}
+	};
+	return {
+		pending,
+		disabled: disabledState,
+		error,
+		run
+	};
+}
+//#endregion
+//#region src/behavior/useActionValue.ts
+/**
+* 切换型组件的 action 消费：值变更先乐观应用，动作失败自动回退并记录错误。
+*
+* @internal 消费组件：Select、DatePicker、ColorPicker、Transfer、Rate、Segmented、Tabs 等即时变更组件
+*/
+function useActionValue() {
+	const pending = ref(false);
+	const error = ref(void 0);
+	const commit = async ({ execute, revert }) => {
+		if (pending.value) return false;
+		error.value = void 0;
+		if (!execute) return true;
+		pending.value = true;
+		try {
+			const failure = extractActionFailure(await execute());
+			if (failure) {
+				error.value = failure.error;
+				revert?.();
+				return false;
+			}
+			return true;
+		} catch (err) {
+			error.value = err;
+			revert?.();
+			return false;
+		} finally {
+			pending.value = false;
+		}
+	};
+	return {
+		pending,
+		error,
+		commit
+	};
+}
+//#endregion
+//#region src/behavior/useToastQueue.ts
+let toastId = 0;
+/**
+* 命令式浮层队列：堆叠管理、去重、自动关闭、悬停暂停、手动销毁。
+* 只管理数据与计时，不渲染任何 DOM——渲染由 Message/Notification 组件承担。
+*
+* @internal 消费方：createMessage、createNotification
+*/
+function useToastQueue(options = {}) {
+	const { duration: defaultDuration = 3e3, max = 5, dedupe = true } = options;
+	const items = ref([]);
+	const timers = /* @__PURE__ */ new Map();
+	const startedAt = /* @__PURE__ */ new Map();
+	const clearTimer = (id) => {
+		const timer = timers.get(id);
+		if (timer !== void 0) {
+			clearTimeout(timer);
+			timers.delete(id);
+		}
+	};
+	const remove = (id) => {
+		clearTimer(id);
+		startedAt.delete(id);
+		items.value = items.value.filter((item) => item.id !== id);
+	};
+	const schedule = (item, wait = item.duration) => {
+		if (wait <= 0) return;
+		startedAt.set(item.id, Date.now());
+		item.remaining = wait;
+		timers.set(item.id, setTimeout(() => remove(item.id), wait));
+	};
+	const push = (type, content, pushOptions = {}) => {
+		const duration = pushOptions.duration ?? defaultDuration;
+		if (dedupe) {
+			const existed = items.value.find((item) => item.type === type && item.content === content);
+			if (existed) return existed;
+		}
+		const item = {
+			id: ++toastId,
+			type,
+			content,
+			title: pushOptions.title,
+			duration,
+			meta: pushOptions.meta,
+			remaining: duration,
+			closable: pushOptions.closable ?? true
+		};
+		items.value = [...items.value, item];
+		schedule(item);
+		if (items.value.length > max) items.value.slice(0, items.value.length - max).forEach((old) => remove(old.id));
+		return item;
+	};
+	const clear = () => {
+		Array.from(timers.keys()).forEach(clearTimer);
+		items.value = [];
+	};
+	const pause = (id) => {
+		const item = items.value.find((entry) => entry.id === id);
+		const started = startedAt.get(id);
+		if (!item || started === void 0) return;
+		item.remaining = Math.max(0, item.remaining - (Date.now() - started));
+		clearTimer(id);
+		startedAt.delete(id);
+	};
+	const resume = (id) => {
+		const item = items.value.find((entry) => entry.id === id);
+		if (!item || timers.has(id)) return;
+		schedule(item, item.remaining);
+	};
+	return {
+		items,
+		count: computed(() => items.value.length),
+		push,
+		remove,
+		clear,
+		pause,
+		resume
+	};
+}
+//#endregion
+//#region src/behavior/useOverlayContainer.ts
+/**
+* Teleport 目标容器的 SSR 安全解析。挂载后才访问 document，
+* 选择器不存在时按策略回退到 body。
+*
+* @internal 消费组件：全部 Teleport 浮层
+*/
+function useOverlayContainer(options = {}) {
+	const { to, fallbackToBody = true } = options;
+	const container = ref(null);
+	onMounted(() => {
+		if (!isClient) return;
+		if (!to) {
+			container.value = document.body;
+			return;
+		}
+		if (typeof to === "string") {
+			const found = document.querySelector(to);
+			container.value = found ?? (fallbackToBody ? document.body : null);
+		} else container.value = to;
+	});
+	onBeforeUnmount(() => {
+		container.value = null;
+	});
+	return { container };
+}
+//#endregion
+//#region src/behavior/useFormContext.ts
+const FORM_KEY = Symbol("cumquat-form");
+const FIELD_KEY = Symbol("cumquat-form-field");
+/** useForm 注册整表上下文 */
+function provideForm(context) {
+	provide(FORM_KEY, context);
+}
+/** 表单控件 / FormItem 注入整表上下文，未处于表单中时返回 undefined */
+function injectForm() {
+	return inject(FORM_KEY, void 0);
+}
+/** FormItem 注册字段上下文（向内部控件传递错误、id 等） */
+function provideFormField(context) {
+	provide(FIELD_KEY, context);
+}
+/** 具体表单控件注入所属字段上下文 */
+function injectFormField() {
+	return inject(FIELD_KEY, void 0);
+}
+//#endregion
+//#region src/form/form-types.ts
+/** 将单条或数组规则统一为数组 */
+function normalizeRules(rule) {
+	if (!rule) return [];
+	return Array.isArray(rule) ? rule : [rule];
+}
+/** 顺序执行规则，遇到首个失败即返回错误信息；全部通过返回 undefined */
+async function runRules(value, values, rules) {
+	for (const rule of rules) {
+		const result = await Promise.resolve().then(() => rule(value, values)).catch((err) => err instanceof Error ? err.message : String(err));
+		if (result !== true) return result;
+	}
+}
+//#endregion
+//#region src/form/useForm.ts
+/**
+* 无头表单模型：字段注册/注销、整表聚合值、同步/异步规则校验、
+* 提交、重置与脏检查。组件只负责布局与错误提示渲染。
+*/
+function useForm(options = {}) {
+	const { modelValue, defaultValue, rules = {}, disabled = false, labelPosition, onChange, onSubmit, onInvalid } = options;
+	const initialSnapshot = () => ({ ...toValue(modelValue) ?? defaultValue ?? {} });
+	const values = reactive({ ...initialSnapshot() });
+	const errors = reactive({});
+	const touched = reactive({});
+	const fields = /* @__PURE__ */ new Map();
+	const submitting = ref(false);
+	const currentRules = () => toValue(rules);
+	const setFieldValue = (name, value) => {
+		const key = String(name);
+		values[key] = value;
+	};
+	const registerField = (name, controller) => {
+		const key = String(name);
+		fields.set(key, controller);
+		if (!(key in values) && controller.getValue) setFieldValue(key, controller.getValue());
+		return () => {
+			fields.delete(key);
+		};
+	};
+	const validateField = async (name) => {
+		const key = String(name);
+		let error;
+		const controller = fields.get(key);
+		if (controller) {
+			const result = await controller.validate();
+			error = result === true ? void 0 : result;
+		} else {
+			const formRules = normalizeRules(currentRules()[key]);
+			error = await runRules(values[key], values, formRules);
+		}
+		errors[key] = error;
+		return error ?? true;
+	};
+	const validate = async () => {
+		const names = /* @__PURE__ */ new Set([...fields.keys(), ...Object.keys(currentRules())]);
+		return (await Promise.all(Array.from(names).map(async (name) => [name, await validateField(name)]))).every(([, result]) => result === true);
+	};
+	const clearValidate = (name) => {
+		if (name === void 0) Object.keys(errors).forEach((key) => delete errors[key]);
+		else delete errors[String(name)];
+	};
+	const resetField = (name) => {
+		const key = String(name);
+		if (key in initialSnapshot()) setFieldValue(key, initialSnapshot()[key]);
+		delete errors[key];
+		delete touched[key];
+		fields.get(key)?.reset();
+	};
+	const reset = () => {
+		const snapshot = initialSnapshot();
+		Object.keys(values).forEach((key) => {
+			if (!(key in snapshot)) delete values[key];
+		});
+		Object.assign(values, snapshot);
+		Array.from(fields.values()).forEach((field) => field.reset());
+		Object.keys(errors).forEach((key) => delete errors[key]);
+		Object.keys(touched).forEach((key) => delete touched[key]);
+	};
+	const submit = async () => {
+		if (submitting.value) return;
+		if (!await validate()) {
+			onInvalid?.({ ...errors });
+			return;
+		}
+		submitting.value = true;
+		try {
+			await onSubmit?.({ ...values });
+		} finally {
+			submitting.value = false;
+		}
+	};
+	watch(values, (next) => {
+		onChange?.({ ...next });
+	}, { deep: true });
+	const validState = computed(() => Object.values(errors).every((error) => error === void 0));
+	const dirty = computed(() => JSON.stringify(values) !== JSON.stringify(initialSnapshot()));
+	const context = {
+		values,
+		errors,
+		registerField,
+		getFieldRules: (name) => currentRules()[String(name)],
+		submit,
+		reset,
+		setFieldValue,
+		disabled,
+		labelPosition
+	};
+	provideForm(context);
+	return {
+		values,
+		errors,
+		touched,
+		valid: validState,
+		dirty,
+		registerField,
+		validateField,
+		validate,
+		clearValidate,
+		setFieldValue,
+		resetField,
+		reset,
+		submit,
+		context
+	};
+}
+//#endregion
+//#region src/form/useFormField.ts
+/**
+* 单字段模型：值的受控/非受控统一、校验信息、touched 状态、
+* aria 注入与表单上下文联动。所有表单控件共用。
+*/
+function useFormField(options = {}) {
+	const { name, modelValue, defaultValue, onChange, rules, validateOnBlur = true, validateOnChange = true, disabled, idPrefix = "cq-field" } = options;
+	const form = injectForm();
+	const fieldId = useId(idPrefix);
+	const errorId = useId(`${idPrefix}-error`);
+	const initialValue = toValue(modelValue) ?? defaultValue;
+	const { value } = useControllableModel({
+		modelValue,
+		defaultValue,
+		onChange: (next) => {
+			onChange?.(next);
+			if (form && name !== void 0) form.setFieldValue?.(name, next);
+		}
+	});
+	const error = ref(void 0);
+	const touched = ref(false);
+	const mergedRules = () => {
+		const own = normalizeRules(rules);
+		return [...name !== void 0 ? normalizeRules(form?.getFieldRules?.(name)) : [], ...own];
+	};
+	const validate = async () => {
+		const list = mergedRules();
+		const result = list.length > 0 ? await runRules(value.value, form?.values ?? {}, list) : void 0;
+		error.value = result;
+		if (form && name !== void 0) form.errors[String(name)] = result;
+		return result ?? true;
+	};
+	const clearValidate = () => {
+		error.value = void 0;
+		if (form && name !== void 0) delete form.errors[String(name)];
+	};
+	const reset = () => {
+		value.value = initialValue;
+		touched.value = false;
+		clearValidate();
+	};
+	const handleChange = (next) => {
+		value.value = next;
+		if (validateOnChange && (touched.value || error.value !== void 0)) validate();
+	};
+	const handleBlur = () => {
+		touched.value = true;
+		if (form && name !== void 0) form.errors[String(name)] = error.value;
+		if (validateOnBlur) validate();
+	};
+	if (form && name !== void 0) {
+		form.setFieldValue?.(name, value.value);
+		watch(value, (next) => form.setFieldValue?.(name, next));
+		const unregister = form.registerField(name, {
+			validate,
+			reset,
+			clearValidate,
+			getValue: () => value.value,
+			setValue: (next) => {
+				value.value = next;
+			}
+		});
+		onBeforeUnmount(unregister);
+		error.value = form.errors[String(name)];
+	}
+	return {
+		value,
+		error,
+		touched,
+		valid: computed(() => error.value === void 0),
+		disabled: computed(() => form?.disabled === true || toValue(disabled) === true),
+		fieldId,
+		errorId,
+		aria: computed(() => ({
+			id: fieldId.value,
+			"aria-invalid": error.value ? true : void 0,
+			"aria-describedby": error.value ? errorId.value : void 0
+		})),
+		handleChange,
+		handleBlur,
+		validate,
+		reset,
+		clearValidate
+	};
+}
+//#endregion
+//#region src/form/useCheckableGroup.ts
+/**
+* 成组勾选值管理：多选数组（增删、全选、半选、数量约束）与单选互斥。
+*
+* @internal 消费组件：CheckboxGroup、RadioGroup
+*/
+function useCheckableGroup(options = {}) {
+	const { multiple = true, modelValue, defaultValue, onChange, options: getOptions, min = 0, max = Number.POSITIVE_INFINITY, isOptionDisabled = () => false } = options;
+	const { value: model } = useControllableModel({
+		modelValue,
+		defaultValue,
+		fallback: multiple ? [] : null,
+		onChange
+	});
+	const selectedList = computed(() => {
+		const current = model.value;
+		if (Array.isArray(current)) return current;
+		return current === null || current === void 0 ? [] : [current];
+	});
+	const isChecked = (value) => selectedList.value.some((item) => Object.is(item, value));
+	const select = (value, checked) => {
+		if (!multiple) {
+			if (checked !== false) model.value = value;
+			return;
+		}
+		const nextChecked = checked ?? !isChecked(value);
+		const set = new Set(selectedList.value);
+		if (nextChecked) {
+			if (set.size >= max) return;
+			set.add(value);
+		} else {
+			if (set.size <= min) return;
+			set.delete(value);
+		}
+		model.value = Array.from(set);
+	};
+	const toggle = (value) => select(value);
+	const enabledOptions = computed(() => (getOptions?.() ?? []).filter((value) => !isOptionDisabled(value)));
+	const checkedCount = computed(() => selectedList.value.length);
+	const allChecked = computed(() => {
+		const options = enabledOptions.value;
+		return options.length > 0 && options.every((value) => isChecked(value));
+	});
+	const indeterminate = computed(() => {
+		const options = enabledOptions.value;
+		const count = options.filter((value) => isChecked(value)).length;
+		return count > 0 && count < options.length;
+	});
+	const toggleAll = (checked) => {
+		if (!multiple) return;
+		if (checked ?? !allChecked.value) {
+			const merged = new Set(selectedList.value);
+			for (const value of enabledOptions.value) {
+				if (merged.size >= max) break;
+				merged.add(value);
+			}
+			model.value = Array.from(merged);
+		} else {
+			const enabledSet = new Set(enabledOptions.value);
+			model.value = selectedList.value.filter((value) => !enabledSet.has(value));
+		}
+	};
+	return {
+		model,
+		isChecked,
+		select,
+		toggle,
+		allChecked,
+		indeterminate,
+		toggleAll,
+		checkedCount
+	};
+}
+//#endregion
+//#region src/form/useSelectModel.ts
+/**
+* 选择器值模型：单选/多选值、选项标签回显、本地过滤、清除。
+* 不发请求、不管浮层开合（分别由 useAsyncState / useOpen 承担）。
+*
+* @internal 消费组件：Select、TreeSelect
+*/
+function useSelectModel(options) {
+	const { options: optionSource, modelValue, defaultValue, onChange, multiple = false, filterable = false, filterMethod, equals = Object.is } = options;
+	const { value: model } = useControllableModel({
+		modelValue,
+		defaultValue,
+		fallback: multiple ? [] : null,
+		onChange
+	});
+	const keyword = ref("");
+	const findOption = (value) => toValue(optionSource).find((option) => equals(option.value, value));
+	/**
+	* 已选快照：pick 时记下完整选项对象，独立于当前可见数据源。
+	* 分页 / 服务端搜索后选项已不在当前页时，据此仍能回显已选标签；
+	* 不从数据源中淘汰，仅随取消选中或清空移除。
+	*/
+	const pickedOptions = ref([]);
+	const findPicked = (value) => pickedOptions.value.find((option) => equals(option.value, value));
+	const remember = (option) => {
+		if (findPicked(option.value)) return;
+		pickedOptions.value = [...pickedOptions.value, option];
+	};
+	const forget = (value) => {
+		pickedOptions.value = pickedOptions.value.filter((option) => !equals(option.value, value));
+	};
+	const selectedOptions = computed(() => {
+		const current = model.value;
+		return (Array.isArray(current) ? current : current === null ? [] : [current]).map((value) => findPicked(value) ?? findOption(value)).filter((option) => !!option);
+	});
+	const selectedLabel = computed(() => selectedOptions.value[0]?.label);
+	const defaultFilter = (option, word) => String(option.label).toLowerCase().includes(word.trim().toLowerCase());
+	const filteredOptions = computed(() => {
+		const all = toValue(optionSource);
+		if (!filterable || !keyword.value) return all;
+		const matcher = filterMethod ?? defaultFilter;
+		return all.filter((option) => matcher(option, keyword.value));
+	});
+	const isSelected = (option) => {
+		const current = model.value;
+		if (Array.isArray(current)) return current.some((value) => equals(value, option.value));
+		return current !== null && equals(current, option.value);
+	};
+	const selectOption = (option, checked) => {
+		if (option.disabled) return false;
+		if (multiple) {
+			const set = new Set(Array.isArray(model.value) ? model.value : []);
+			if (checked ?? !set.has(option.value)) {
+				set.add(option.value);
+				remember(option);
+			} else {
+				set.delete(option.value);
+				forget(option.value);
+			}
+			model.value = Array.from(set);
+		} else {
+			if (checked === false) return false;
+			if (model.value !== null && equals(model.value, option.value)) return false;
+			model.value = option.value;
+			remember(option);
+		}
+		keyword.value = "";
+		return true;
+	};
+	const removeValue = (value) => {
+		if (!multiple || !Array.isArray(model.value)) return;
+		model.value = model.value.filter((item) => !equals(item, value));
+		forget(value);
+	};
+	const clear = () => {
+		model.value = multiple ? [] : null;
+		pickedOptions.value = [];
+		keyword.value = "";
+	};
+	const setKeyword = (next) => {
+		keyword.value = next;
+	};
+	return {
+		model,
+		selectedOptions,
+		selectedLabel,
+		keyword,
+		filteredOptions,
+		isSelected,
+		selectOption,
+		removeValue,
+		clear,
+		setKeyword
+	};
+}
+//#endregion
+//#region src/form/useTreeModel.ts
+const DEFAULT_FIELDS = {
+	value: "value",
+	label: "label",
+	children: "children",
+	disabled: "disabled",
+	isLeaf: "isLeaf"
+};
+/**
+* 树形数据模型：展开集合、勾选集合（级联传播与半选推导）、
+* 可见节点扁平化。不渲染任何缩进 / 连接线（由组件内联）。
+*
+* @internal 消费组件：Tree、TreeSelect
+*/
+function useTreeModel(options) {
+	const { data, fieldNames: fieldOverrides, modelValue, defaultValue, onChange, expandedKeys: expandedProp, defaultExpandedKeys, onExpandedChange, cascade = true } = options;
+	const fields = {
+		...DEFAULT_FIELDS,
+		...fieldOverrides
+	};
+	const flatNodes = computed(() => {
+		const result = [];
+		const walk = (list, depth, parentKey) => {
+			for (const raw of list) {
+				const key = raw[fields.value];
+				const childList = raw[fields.children] ?? [];
+				const childKeys = childList.map((child) => child[fields.value]);
+				const leafKeys = [];
+				if (childList.length === 0) leafKeys.push(key);
+				else {
+					const collect = (children) => {
+						for (const child of children) {
+							const grandchildren = child[fields.children] ?? [];
+							if (grandchildren.length === 0) leafKeys.push(child[fields.value]);
+							else collect(grandchildren);
+						}
+					};
+					collect(childList);
+				}
+				const leafFlag = raw[fields.isLeaf];
+				const isLeaf = leafFlag === void 0 ? childList.length === 0 : leafFlag === true;
+				result.push({
+					key,
+					label: String(raw[fields.label] ?? ""),
+					depth,
+					disabled: Boolean(raw[fields.disabled]),
+					isLeaf,
+					parentKey,
+					childKeys,
+					leafKeys,
+					raw
+				});
+				walk(childList, depth + 1, key);
+			}
+		};
+		walk(toValue(data), 0, null);
+		return result;
+	});
+	const getNode = (key) => flatNodes.value.find((node) => node.key === key);
+	const expandedKeys = useControllableModel({
+		modelValue: expandedProp,
+		defaultValue: defaultExpandedKeys,
+		fallback: [],
+		onChange: onExpandedChange
+	}).value;
+	const isExpanded = (key) => expandedKeys.value.includes(key);
+	const setExpanded = (key, expanded) => {
+		const set = new Set(expandedKeys.value);
+		if (expanded) set.add(key);
+		else set.delete(key);
+		expandedKeys.value = Array.from(set);
+	};
+	const toggleExpand = (key) => setExpanded(key, !isExpanded(key));
+	const expandAll = () => {
+		expandedKeys.value = flatNodes.value.filter((node) => !node.isLeaf).map((node) => node.key);
+	};
+	const collapseAll = () => {
+		expandedKeys.value = [];
+	};
+	const visibleNodes = computed(() => {
+		const all = flatNodes.value;
+		if (all.length === 0) return [];
+		const byParent = /* @__PURE__ */ new Map();
+		for (const node of all) {
+			const list = byParent.get(node.parentKey) ?? [];
+			list.push(node);
+			byParent.set(node.parentKey, list);
+		}
+		const visible = [];
+		const pushLevel = (parentKey) => {
+			for (const node of byParent.get(parentKey) ?? []) {
+				visible.push(node);
+				if (!node.isLeaf && isExpanded(node.key)) pushLevel(node.key);
+			}
+		};
+		pushLevel(null);
+		return visible;
+	});
+	const checkedKeys = useControllableModel({
+		modelValue,
+		defaultValue,
+		fallback: [],
+		onChange
+	}).value;
+	const checkedSet = computed(() => new Set(checkedKeys.value));
+	const isChecked = (key) => {
+		const node = getNode(key);
+		if (!node) return false;
+		if (!cascade) return checkedSet.value.has(key);
+		return node.leafKeys.every((leaf) => checkedSet.value.has(leaf));
+	};
+	const isIndeterminate = (key) => {
+		if (!cascade) return false;
+		const node = getNode(key);
+		if (!node || node.isLeaf) return false;
+		const count = node.leafKeys.filter((leaf) => checkedSet.value.has(leaf)).length;
+		return count > 0 && count < node.leafKeys.length;
+	};
+	const halfCheckedKeys = computed(() => flatNodes.value.filter((node) => !node.isLeaf && isIndeterminate(node.key)).map((node) => node.key));
+	const check = (key, checked) => {
+		const node = getNode(key);
+		if (!node || node.disabled) return;
+		const nextChecked = checked ?? !isChecked(key);
+		const affected = (cascade ? node.leafKeys : [key]).filter((k) => !getNode(k)?.disabled);
+		const set = new Set(checkedKeys.value);
+		if (nextChecked) affected.forEach((leaf) => set.add(leaf));
+		else affected.forEach((leaf) => set.delete(leaf));
+		checkedKeys.value = Array.from(set);
+	};
+	const setCheckedKeys = (keys) => {
+		checkedKeys.value = [...keys];
+	};
+	return {
+		flatNodes,
+		visibleNodes,
+		checkedKeys,
+		expandedKeys,
+		getNode,
+		isExpanded,
+		setExpanded,
+		toggleExpand,
+		expandAll,
+		collapseAll,
+		isChecked,
+		isIndeterminate,
+		halfCheckedKeys,
+		check,
+		setCheckedKeys
+	};
+}
+//#endregion
+//#region src/form/useAsyncSuggest.ts
+/**
+* 输入防抖 → 调用异步建议源 → loading/空态管理。
+* 竞态请求以最后一次为准，旧响应被丢弃。
+*
+* @internal 消费组件：AutoComplete、Mention
+*/
+function useAsyncSuggest(options) {
+	const { fetch, debounce = 300, immediate = false, minKeywordLength = 0, onSuccess, onError } = options;
+	const suggestions = ref([]);
+	const status = ref("idle");
+	const loading = ref(false);
+	const error = ref(void 0);
+	const keyword = ref("");
+	let requestId = 0;
+	const run = async (nextKeyword = keyword.value) => {
+		const currentId = ++requestId;
+		status.value = "pending";
+		loading.value = true;
+		error.value = void 0;
+		try {
+			const result = await fetch(nextKeyword);
+			if (currentId !== requestId) return;
+			suggestions.value = result;
+			status.value = "success";
+			onSuccess?.(result, nextKeyword);
+		} catch (err) {
+			if (currentId !== requestId) return;
+			error.value = err;
+			status.value = "error";
+			onError?.(err);
+		} finally {
+			if (currentId === requestId) loading.value = false;
+		}
+	};
+	const timer = useTimeoutFn(() => {
+		if (keyword.value.length < minKeywordLength) {
+			suggestions.value = [];
+			status.value = "idle";
+			return;
+		}
+		run();
+	});
+	const setKeyword = (next) => {
+		keyword.value = next;
+		if (next.length < minKeywordLength) {
+			timer.stop();
+			suggestions.value = [];
+			status.value = "idle";
+			return;
+		}
+		timer.start(debounce);
+	};
+	const clear = () => {
+		timer.stop();
+		keyword.value = "";
+		suggestions.value = [];
+		status.value = "idle";
+		error.value = void 0;
+	};
+	if (immediate) run("");
+	return {
+		suggestions,
+		status,
+		loading,
+		error,
+		keyword,
+		setKeyword,
+		run,
+		clear
+	};
+}
+//#endregion
+//#region src/form/date-utils.ts
+/**
+* 日期模型共享的纯函数工具（无响应式、无副作用）。
+*/
+const pad2 = (value) => String(value).padStart(2, "0");
+/** 解析字符串（yyyy-MM-dd / yyyy-MM/yyyy）或时间值为本地日期；非法返回 null */
+function parseDate(value) {
+	if (value === null || value === void 0 || value === "") return null;
+	if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value;
+	if (typeof value === "number") {
+		const date = new Date(value);
+		return Number.isNaN(date.getTime()) ? null : date;
+	}
+	if (typeof value !== "string") return null;
+	const trimmed = value.trim();
+	const match = /^(\d{4})(?:-(\d{1,2}))?(?:-(\d{1,2}))?/.exec(trimmed);
+	if (match) {
+		const [, year, month, day] = match;
+		const date = new Date(Number(year), Number(month ?? 1) - 1, Number(day ?? 1));
+		return Number.isNaN(date.getTime()) ? null : date;
+	}
+	const fallback = new Date(trimmed);
+	return Number.isNaN(fallback.getTime()) ? null : fallback;
+}
+/** 按 pattern（yyyy / MM / dd）格式化日期 */
+function formatDate(date, pattern = "yyyy-MM-dd") {
+	if (!date) return "";
+	return pattern.replace("yyyy", String(date.getFullYear())).replace("MM", pad2(date.getMonth() + 1)).replace("dd", pad2(date.getDate()));
+}
+function startOfDay(date) {
+	return new Date(date.getFullYear(), date.getMonth(), date.getDate());
+}
+function isSameDay(a, b) {
+	if (!a || !b) return false;
+	return a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth() && a.getDate() === b.getDate();
+}
+function isSameMonth(a, b) {
+	return a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth();
+}
+function addDays(date, amount) {
+	const next = new Date(date);
+	next.setDate(next.getDate() + amount);
+	return next;
+}
+function addMonths(date, amount) {
+	const next = new Date(date);
+	const day = next.getDate();
+	next.setDate(1);
+	next.setMonth(next.getMonth() + amount);
+	const maxDay = getDaysInMonth(next.getFullYear(), next.getMonth());
+	next.setDate(Math.min(day, maxDay));
+	return next;
+}
+function addYears(date, amount) {
+	return addMonths(date, amount * 12);
+}
+function getDaysInMonth(year, month) {
+	return new Date(year, month + 1, 0).getDate();
+}
+/** 某天所属周的第一天（firstDayOfWeek: 0=周日 1=周一） */
+function startOfWeek(date, firstDayOfWeek = 1) {
+	const diff = (date.getDay() - firstDayOfWeek + 7) % 7;
+	return addDays(startOfDay(date), -diff);
+}
+/** 比较两个日期零点的先后：a < b → -1 */
+function compareDay(a, b) {
+	const za = startOfDay(a).getTime();
+	const zb = startOfDay(b).getTime();
+	return Math.sign(za - zb);
+}
+/** 解析 HH:mm:ss / HH:mm 时间串 */
+function parseTime(value) {
+	if (!value) return null;
+	const match = /^(\d{1,2}):(\d{1,2})(?::(\d{1,2}))?$/.exec(value.trim());
+	if (!match) return null;
+	const [, hour, minute, second] = match;
+	return {
+		hour: Number(hour),
+		minute: Number(minute),
+		second: Number(second ?? 0)
+	};
+}
+function formatTime(hour, minute, second, useSeconds = true) {
+	const base = `${pad2(hour)}:${pad2(minute)}`;
+	return useSeconds ? `${base}:${pad2(second)}` : base;
+}
+/** 将时间串换算为当天秒数，便于范围比较 */
+function timeToSeconds(value) {
+	const parsed = parseTime(value);
+	if (!parsed) return null;
+	return parsed.hour * 3600 + parsed.minute * 60 + parsed.second;
+}
+//#endregion
+//#region src/form/useDateGrid.ts
+const MONTH_LABELS = [
+	"1月",
+	"2月",
+	"3月",
+	"4月",
+	"5月",
+	"6月",
+	"7月",
+	"8月",
+	"9月",
+	"10月",
+	"11月",
+	"12月"
+];
+/**
+* 日历网格纯计算：月首偏移、当月天数、外部填充、周末/禁用/选中/范围标记。
+* 同一模型驱动 DatePicker 与 Calendar；多面板由组件内创建多个实例实现。
+*/
+function useDateGrid(options = {}) {
+	const { viewDate: injected, type = "date", firstDayOfWeek = 1, disabledDate = () => false, isSelected = () => false, isInRange = () => false, isRangeStart = () => false, isRangeEnd = () => false } = options;
+	const viewDate = injected ?? ref(/* @__PURE__ */ new Date());
+	const panelType = ref(type);
+	const today = /* @__PURE__ */ new Date();
+	const weekdayOrder = computed(() => {
+		const order = [];
+		for (let i = 0; i < 7; i += 1) order.push((firstDayOfWeek + i) % 7);
+		return order;
+	});
+	const weeks = computed(() => {
+		const first = startOfWeek(new Date(viewDate.value.getFullYear(), viewDate.value.getMonth(), 1), firstDayOfWeek);
+		const rows = [];
+		for (let row = 0; row < 6; row += 1) {
+			const week = [];
+			for (let col = 0; col < 7; col += 1) {
+				const date = addDays(first, row * 7 + col);
+				const base = {
+					date,
+					inMonth: isSameMonth(date, viewDate.value),
+					isToday: isSameDay(date, today),
+					disabled: disabledDate(date),
+					isWeekend: date.getDay() === 0 || date.getDay() === 6
+				};
+				week.push({
+					...base,
+					selected: isSelected(date),
+					inRange: isInRange(date),
+					rangeStart: isRangeStart(date),
+					rangeEnd: isRangeEnd(date)
+				});
+			}
+			rows.push(week);
+		}
+		return rows;
+	});
+	const months = computed(() => MONTH_LABELS.map((label, index) => {
+		const date = new Date(viewDate.value.getFullYear(), index, 1);
+		return {
+			date,
+			label,
+			disabled: disabledDate(date),
+			inPanel: true
+		};
+	}));
+	const decadeStartYear = computed(() => Math.floor(viewDate.value.getFullYear() / 10) * 10);
+	const years = computed(() => {
+		const start = decadeStartYear.value - 1;
+		return Array.from({ length: 12 }, (_, index) => {
+			const year = start + index;
+			const date = new Date(year, 0, 1);
+			return {
+				date,
+				label: String(year),
+				disabled: disabledDate(date),
+				inPanel: year >= decadeStartYear.value && year < decadeStartYear.value + 10
+			};
+		});
+	});
+	const panelLabel = computed(() => {
+		const year = viewDate.value.getFullYear();
+		if (panelType.value === "date") return `${year}年 ${MONTH_LABELS[viewDate.value.getMonth()]}`;
+		if (panelType.value === "month") return `${year}年`;
+		return `${decadeStartYear.value} - ${decadeStartYear.value + 9}`;
+	});
+	const prevView = () => {
+		if (panelType.value === "date") viewDate.value = addMonths(viewDate.value, -1);
+		else if (panelType.value === "month") viewDate.value = addYears(viewDate.value, -1);
+		else viewDate.value = addYears(viewDate.value, -10);
+	};
+	const nextView = () => {
+		if (panelType.value === "date") viewDate.value = addMonths(viewDate.value, 1);
+		else if (panelType.value === "month") viewDate.value = addYears(viewDate.value, 1);
+		else viewDate.value = addYears(viewDate.value, 10);
+	};
+	const goToDate = (date) => {
+		viewDate.value = new Date(date);
+	};
+	const setPanelType = (next) => {
+		panelType.value = next;
+	};
+	return {
+		viewDate,
+		panelType,
+		setPanelType,
+		weekdayOrder,
+		weeks,
+		months,
+		years,
+		panelLabel,
+		prevView,
+		nextView,
+		goToDate
+	};
+}
+//#endregion
+//#region src/form/useDateModel.ts
+/**
+* 日期值模型：解析/格式化、粒度（日/月/年）、范围两段式选择、
+* 最小/最大与禁用限制、快捷选项。不负责网格计算（见 useDateGrid）。
+*
+* @internal 消费组件：DatePicker、Calendar
+*/
+function useDateModel(options = {}) {
+	const { modelValue, defaultValue, rangeModelValue, defaultRangeValue, onChange, range = false, granularity = "day", format: formatPattern = "yyyy-MM-dd", minDate, maxDate, disabledDate } = options;
+	const pattern = granularity === "year" ? "yyyy" : granularity === "month" ? "yyyy-MM" : formatPattern;
+	const min = computed(() => parseDate(minDate ?? null));
+	const max = computed(() => parseDate(maxDate ?? null));
+	const format = (date) => formatDate(date, pattern);
+	const toStored = (value) => {
+		const date = parseDate(value ?? null);
+		return date ? format(date) : null;
+	};
+	const model = useControllableModel({
+		modelValue,
+		defaultValue,
+		fallback: null
+	}).value;
+	const rawRangeModel = useControllableModel({
+		modelValue: rangeModelValue,
+		defaultValue: defaultRangeValue,
+		fallback: null
+	}).value;
+	const rangeModel = computed({
+		get: () => {
+			const current = rawRangeModel.value;
+			if (!current) return null;
+			return [toStored(current[0]), toStored(current[1])];
+		},
+		set: (next) => {
+			rawRangeModel.value = next;
+			onChange?.(next);
+		}
+	});
+	const selectedDate = computed(() => parseDate(model.value ?? null));
+	const rangeDates = computed(() => {
+		const current = rangeModel.value;
+		if (!current) return [null, null];
+		return [parseDate(current[0]), parseDate(current[1])];
+	});
+	const viewDate = ref(selectedDate.value ?? rangeDates.value[0] ?? /* @__PURE__ */ new Date());
+	const pickingStart = ref(true);
+	const hoverDate = ref(null);
+	const syncView = (date) => {
+		viewDate.value = new Date(date);
+	};
+	const isDisabled = (date) => {
+		if (min.value && compareDay(date, min.value) < 0) return true;
+		if (max.value && compareDay(date, max.value) > 0) return true;
+		return disabledDate?.(date) === true;
+	};
+	const isSelected = (date) => {
+		if (range) {
+			const [start, end] = rangeDates.value;
+			return isSameDay(date, start) || isSameDay(date, end);
+		}
+		return isSameDay(date, selectedDate.value);
+	};
+	const isRangeStart = (date) => isSameDay(date, rangeDates.value[0]);
+	const isRangeEnd = (date) => isSameDay(date, rangeDates.value[1]);
+	const isInRange = (date) => {
+		if (!range) return false;
+		const [start, end] = rangeDates.value;
+		if (start && end) return compareDay(date, start) >= 0 && compareDay(date, end) <= 0;
+		if (start && hoverDate.value && !pickingStart.value) {
+			const [lo, hi] = compareDay(start, hoverDate.value) <= 0 ? [start, hoverDate.value] : [hoverDate.value, start];
+			return compareDay(date, lo) >= 0 && compareDay(date, hi) <= 0;
+		}
+		return false;
+	};
+	const emitSingle = (date) => {
+		const stored = toStored(date);
+		model.value = stored;
+		onChange?.(stored);
+	};
+	const selectDate = (date) => {
+		if (isDisabled(date)) return;
+		syncView(date);
+		if (!range) {
+			emitSingle(date);
+			return;
+		}
+		if (pickingStart.value || !rangeModel.value?.[0]) {
+			rangeModel.value = [toStored(date), null];
+			pickingStart.value = false;
+			hoverDate.value = null;
+			return;
+		}
+		const start = rangeDates.value[0];
+		if (start && compareDay(date, start) < 0) rangeModel.value = [toStored(date), toStored(start)];
+		else rangeModel.value = [toStored(start), toStored(date)];
+		pickingStart.value = true;
+		hoverDate.value = null;
+	};
+	const setHoverDate = (date) => {
+		hoverDate.value = date;
+	};
+	const selectShortcut = (shortcut) => {
+		if (Array.isArray(shortcut.value)) {
+			const [start, end] = shortcut.value;
+			rangeModel.value = [toStored(start), toStored(end)];
+			pickingStart.value = true;
+			syncView(start);
+		} else {
+			emitSingle(shortcut.value);
+			syncView(shortcut.value);
+		}
+	};
+	const clear = () => {
+		if (range) {
+			rangeModel.value = null;
+			pickingStart.value = true;
+		} else emitSingle(null);
+		hoverDate.value = null;
+	};
+	const prevMonth = () => {
+		viewDate.value = addMonths(viewDate.value, -1);
+	};
+	const nextMonth = () => {
+		viewDate.value = addMonths(viewDate.value, 1);
+	};
+	const goToDate = (date) => syncView(date);
+	return {
+		model,
+		rangeModel,
+		selectedDate,
+		rangeDates,
+		viewDate,
+		hoverDate,
+		displayText: computed(() => {
+			if (range) {
+				const [start, end] = rangeDates.value;
+				const left = format(start);
+				const right = format(end);
+				if (!left && !right) return "";
+				return `${left} ~ ${right}`;
+			}
+			return format(selectedDate.value);
+		}),
+		isSelected,
+		isDisabled,
+		isInRange,
+		isRangeStart,
+		isRangeEnd,
+		selectDate,
+		setHoverDate,
+		selectShortcut,
+		clear,
+		prevMonth,
+		nextMonth,
+		goToDate,
+		format
+	};
+}
+//#endregion
+//#region src/form/useTimeModel.ts
+function buildStepValues(max, step) {
+	const values = [];
+	for (let value = 0; value <= max; value += 1) if (value % step === 0) values.push(value);
+	return values;
+}
+/**
+* 时间选择模型：时/分/秒三列数据与步进、范围限制、回写与回显。
+* 滚动列渲染与确认按钮编排由 TimePicker 组件承担。
+*
+* @internal 消费组件：TimePicker、DatePicker（日期时间模式）
+*/
+function useTimeModel(options = {}) {
+	const { modelValue, defaultValue, onChange, hourStep = 1, minuteStep = 1, secondStep = 1, useSeconds = true, minTime, maxTime } = options;
+	const { value: model } = useControllableModel({
+		modelValue,
+		defaultValue,
+		fallback: null
+	});
+	const typedModel = model;
+	const hour = ref(parseTime(typedModel.value)?.hour ?? null);
+	const minute = ref(parseTime(typedModel.value)?.minute ?? null);
+	const second = ref(useSeconds ? parseTime(typedModel.value)?.second ?? null : 0);
+	const minSeconds = computed(() => timeToSeconds(minTime ?? null));
+	const maxSeconds = computed(() => timeToSeconds(maxTime ?? null));
+	const isItemDisabled = (unit, value) => {
+		const h = hour.value ?? 0;
+		const m = minute.value ?? 0;
+		const s = second.value ?? 0;
+		const candidate = unit === "hour" ? value * 3600 + m * 60 + s : unit === "minute" ? h * 3600 + value * 60 + s : h * 3600 + m * 60 + value;
+		if (minSeconds.value !== null && candidate < minSeconds.value) return true;
+		if (maxSeconds.value !== null && candidate > maxSeconds.value) return true;
+		return false;
+	};
+	const hourColumn = computed(() => buildStepValues(23, hourStep).map((value) => ({
+		value,
+		label: pad2(value),
+		disabled: isItemDisabled("hour", value)
+	})));
+	const minuteColumn = computed(() => buildStepValues(59, minuteStep).map((value) => ({
+		value,
+		label: pad2(value),
+		disabled: isItemDisabled("minute", value)
+	})));
+	const secondColumn = computed(() => buildStepValues(59, secondStep).map((value) => ({
+		value,
+		label: pad2(value),
+		disabled: isItemDisabled("second", value)
+	})));
+	const displayText = computed(() => {
+		if (hour.value === null || minute.value === null) return "";
+		return formatTime(hour.value, minute.value, second.value ?? 0, useSeconds);
+	});
+	const setHour = (value) => {
+		hour.value = value;
+	};
+	const setMinute = (value) => {
+		minute.value = value;
+	};
+	const setSecond = (value) => {
+		second.value = value;
+	};
+	const setUnit = (unit, value) => {
+		if (isItemDisabled(unit, value)) return;
+		if (unit === "hour") setHour(value);
+		else if (unit === "minute") setMinute(value);
+		else setSecond(value);
+	};
+	const confirm = () => {
+		if (hour.value === null || minute.value === null) {
+			typedModel.value = null;
+			return null;
+		}
+		const text = formatTime(hour.value, minute.value, second.value ?? 0, useSeconds);
+		typedModel.value = text;
+		onChange?.(text);
+		return text;
+	};
+	const now = () => {
+		const date = /* @__PURE__ */ new Date();
+		hour.value = date.getHours();
+		minute.value = date.getMinutes();
+		second.value = date.getSeconds();
+		confirm();
+	};
+	const clear = () => {
+		hour.value = null;
+		minute.value = null;
+		second.value = useSeconds ? null : 0;
+		typedModel.value = null;
+		onChange?.(null);
+	};
+	const syncFromModel = (value) => {
+		const parsed = parseTime(value);
+		hour.value = parsed?.hour ?? null;
+		minute.value = parsed?.minute ?? null;
+		second.value = parsed ? parsed.second : useSeconds ? null : 0;
+	};
+	if (modelValue !== void 0) syncFromModel(modelValue);
+	return {
+		model: typedModel,
+		hour,
+		minute,
+		second,
+		hourColumn,
+		minuteColumn,
+		secondColumn,
+		displayText,
+		setHour,
+		setMinute,
+		setSecond,
+		setUnit,
+		now,
+		clear,
+		confirm
+	};
+}
+//#endregion
+//#region src/overlay/useModal.ts
+/**
+* 模态开合编排：useOpen + 滚动锁定 + 焦点陷阱/归还 + ESC + 层级 +
+* 进出场过渡。Dialog/Drawer 共用，差异仅在方向与尺寸（组件内联）。
+*/
+function useModal(options = {}) {
+	const { maskClosable = true, escClosable = true, lockScroll: shouldLock = true, onOpen, onClose, onChange, ...controlled } = options;
+	const { isOpen, open, close, toggle } = useOpen({
+		...controlled,
+		onChange: (next) => {
+			onChange?.(next);
+			if (next) onOpen?.();
+			else onClose?.();
+		}
+	});
+	const { rendered, visible, onAfterLeave } = useTransitionVisible(isOpen);
+	const { lock, unlock } = useScrollLock();
+	const { currentZIndex, nextZIndex } = useZIndex();
+	const { record: recordFocus, restore: restoreFocus } = useFocusReturn();
+	const contentRef = ref(null);
+	const { trap, release } = useFocusTrap(contentRef, { immediate: true });
+	watch(isOpen, (openState) => {
+		if (openState) {
+			currentZIndex.value = nextZIndex();
+			recordFocus();
+			if (shouldLock) lock();
+			trap();
+		} else {
+			release();
+			if (shouldLock) unlock();
+			restoreFocus();
+		}
+	});
+	useDismiss({
+		isOpen,
+		floating: contentRef,
+		onDismiss: (reason) => {
+			if (reason === "escape-key" && escClosable) close();
+		},
+		outsidePress: false,
+		scroll: false
+	});
+	const onMaskClick = () => {
+		if (maskClosable) close();
+	};
+	return {
+		isOpen,
+		open,
+		close,
+		toggle,
+		contentRef,
+		rendered,
+		visible,
+		onAfterLeave,
+		zIndex: currentZIndex,
+		onMaskClick
+	};
+}
+//#endregion
+//#region src/overlay/usePopoverModel.ts
+/**
+* 浮层触发模型：click / hover / focus / manual 四种触发方式与
+* 延迟开合、进出场过渡的组合编排。定位由 useFloating 独立承担。
+*
+* @internal 消费组件：Popover、Dropdown、Tooltip
+*/
+function usePopoverModel(options = {}) {
+	const { trigger = "click", openDelay = 100, closeDelay = 100, ...controlled } = options;
+	const hover = useHoverIntent({
+		showDelay: openDelay,
+		hideDelay: closeDelay,
+		disabled: trigger !== "hover"
+	});
+	const { isOpen, open, close, toggle } = useOpen({
+		...controlled,
+		openDelay: 0,
+		closeDelay: 0
+	});
+	if (trigger === "hover") watch(hover.isHovered, (hovered) => toggle(hovered));
+	const { rendered, visible, onAfterLeave } = useTransitionVisible(isOpen);
+	return {
+		isOpen,
+		open,
+		close,
+		toggle,
+		rendered,
+		visible,
+		onAfterLeave,
+		triggerProps: computed(() => {
+			const props = {};
+			if (trigger === "click") props.onClick = () => toggle();
+			else if (trigger === "hover") {
+				props.onMouseenter = hover.onMouseEnter;
+				props.onMouseleave = hover.onMouseLeave;
+			} else if (trigger === "focus") {
+				props.onFocus = open;
+				props.onBlur = close;
+			}
+			return props;
+		}),
+		floatingHoverProps: computed(() => trigger === "hover" ? {
+			onMouseenter: hover.onMouseEnter,
+			onMouseleave: hover.onMouseLeave
+		} : {})
+	};
+}
+//#endregion
+//#region src/overlay/createMessage.ts
+/**
+* 创建一套命令式消息服务。底层为共享响应式 toast 队列，
+* 渲染由 Message 组件承担；宿主也可在不引入组件的情况下调用。
+*/
+function createMessage(options = {}) {
+	const { duration = 3e3, max = 5 } = options;
+	const queue = useToastQueue({
+		duration,
+		max
+	});
+	const push = (content, pushOptions = {}) => {
+		return queue.push(pushOptions.type ?? "info", content, pushOptions).id;
+	};
+	return {
+		items: queue.items,
+		push,
+		success: (content, time) => push(content, {
+			type: "success",
+			duration: time
+		}),
+		warning: (content, time) => push(content, {
+			type: "warning",
+			duration: time
+		}),
+		info: (content, time) => push(content, {
+			type: "info",
+			duration: time
+		}),
+		error: (content, time) => push(content, {
+			type: "error",
+			duration: time ?? 5e3
+		}),
+		loading: (content) => push(content, {
+			type: "loading",
+			duration: 0
+		}),
+		remove: queue.remove,
+		clear: queue.clear,
+		pause: queue.pause,
+		resume: queue.resume
+	};
+}
+/** 全局默认单例：所有 Message 组件与宿主共享同一队列 */
+const message = createMessage();
+//#endregion
+//#region src/overlay/createNotification.ts
+/**
+* 创建命令式通知服务。消息体携带标题 / 描述 / 动作数据，
+* 角落堆叠方向由渲染组件按 placement 分组。
+*/
+function createNotification(options = {}) {
+	const { duration = 4500, max = 7 } = options;
+	const queue = useToastQueue({
+		duration,
+		max
+	});
+	const open = (type, title, description, time) => {
+		return queue.push(type, title, {
+			title,
+			duration: time,
+			meta: {
+				title,
+				description
+			}
+		}).id;
+	};
+	return {
+		items: computed(() => queue.items.value.map((item) => ({
+			id: item.id,
+			type: item.type,
+			title: item.meta.title,
+			description: item.meta.description,
+			duration: item.duration,
+			meta: item.meta
+		}))),
+		open,
+		success: (title, description) => open("success", title, description),
+		warning: (title, description) => open("warning", title, description),
+		info: (title, description) => open("info", title, description),
+		error: (title, description) => open("error", title, description, 5e3),
+		remove: queue.remove,
+		clear: queue.clear
+	};
+}
+/** 全局默认单例 */
+const notification = createNotification();
+//#endregion
+//#region src/overlay/useLoadingService.ts
+/** 创建一套隔离的计数式加载服务 */
+function createLoadingService() {
+	const count = ref(0);
+	const loading = computed(() => count.value > 0);
+	const finish = () => {
+		count.value = Math.max(0, count.value - 1);
+	};
+	const start = () => {
+		count.value += 1;
+		return finish;
+	};
+	const wrap = async (task) => {
+		count.value += 1;
+		try {
+			return await task;
+		} finally {
+			finish();
+		}
+	};
+	const clear = () => {
+		count.value = 0;
+	};
+	return {
+		loading,
+		count,
+		start,
+		finish,
+		wrap,
+		clear
+	};
+}
+const globalService = createLoadingService();
+/**
+* 局部 / 全屏加载的计数式服务（多请求合并显示一个加载态）。
+* 需要隔离实例时使用 createLoadingService。
+*
+* @internal 消费组件：Loading
+*/
+function useLoadingService() {
+	return globalService;
+}
+//#endregion
+//#region src/data/usePagination.ts
+const range = (start, end) => Array.from({ length: end - start + 1 }, (_, index) => start + index);
+/**
+* 分页模型：当前页 / 页大小、总页数、含省略号的页码序列、跳页与边界约束。
+* 组件自身不发请求，go/setPageSize 只负责状态与 onChange 通知。
+*
+* @internal 消费组件：Pagination；Table 内联复用；宿主列表可独立使用
+*/
+function usePagination(options = {}) {
+	const { currentPage, defaultCurrentPage = 1, onPageChange, pageSize: pageSizeProp, defaultPageSize = 10, onPageSizeChange, total: totalProp = 0, pageSizes = [
+		10,
+		20,
+		50,
+		100
+	], siblingCount = 1, boundaryCount = 1, onChange } = options;
+	const total = ref(totalProp);
+	const currentPageRef = useControllableModel({
+		modelValue: currentPage,
+		defaultValue: defaultCurrentPage,
+		fallback: 1,
+		onChange: (page) => {
+			onPageChange?.(page);
+			onChange?.({
+				currentPage: page,
+				pageSize: sizeModel.value.value
+			});
+		}
+	}).value;
+	const sizeModel = useControllableModel({
+		modelValue: pageSizeProp,
+		defaultValue: defaultPageSize,
+		fallback: 10,
+		onChange: (size) => {
+			onPageSizeChange?.(size);
+			onChange?.({
+				currentPage: currentPageRef.value,
+				pageSize: size
+			});
+		}
+	});
+	const pageSize = sizeModel.value;
+	const totalPages = computed(() => Math.max(1, Math.ceil(total.value / pageSize.value)));
+	watch(totalPages, (lastPage) => {
+		if (currentPageRef.value > lastPage) currentPageRef.value = lastPage;
+	});
+	const pages = computed(() => {
+		const lastPage = totalPages.value;
+		if (lastPage <= boundaryCount * 2 + siblingCount * 2 + 3) return range(1, lastPage);
+		const current = currentPageRef.value;
+		const groups = [
+			[
+				1,
+				boundaryCount,
+				"start-ellipsis"
+			],
+			[
+				Math.max(boundaryCount + 1, current - siblingCount),
+				Math.min(lastPage - boundaryCount, current + siblingCount),
+				"start-ellipsis"
+			],
+			[
+				lastPage - boundaryCount + 1,
+				lastPage,
+				"end-ellipsis"
+			]
+		];
+		const result = [];
+		let prevEnd = 0;
+		groups.forEach(([start, end, token], groupIndex) => {
+			if (start > end) return;
+			if (prevEnd > 0) {
+				const gap = start - prevEnd;
+				if (gap === 1) {} else if (gap === 2) result.push(prevEnd + 1);
+				else result.push(groupIndex === groups.length - 1 ? "end-ellipsis" : token);
+			}
+			result.push(...range(start, end));
+			prevEnd = end;
+		});
+		return result;
+	});
+	const isFirst = computed(() => currentPageRef.value <= 1);
+	const isLast = computed(() => currentPageRef.value >= totalPages.value);
+	const canPrev = computed(() => !isFirst.value);
+	const canNext = computed(() => !isLast.value);
+	const rangeStart = computed(() => total.value === 0 ? 0 : (currentPageRef.value - 1) * pageSize.value + 1);
+	const rangeEnd = computed(() => Math.min(total.value, currentPageRef.value * pageSize.value));
+	const go = (page) => {
+		const target = Math.min(Math.max(1, Math.trunc(page)), totalPages.value);
+		if (target === currentPageRef.value) return;
+		currentPageRef.value = target;
+	};
+	const prev = () => go(currentPageRef.value - 1);
+	const next = () => go(currentPageRef.value + 1);
+	const setPageSize = (size) => {
+		if (size === pageSize.value) return;
+		pageSize.value = size;
+		go(1);
+	};
+	return {
+		currentPage: currentPageRef,
+		pageSize,
+		total,
+		totalPages,
+		pageSizes,
+		pages,
+		isFirst,
+		isLast,
+		canPrev,
+		canNext,
+		rangeStart,
+		rangeEnd,
+		go,
+		prev,
+		next,
+		setPageSize
+	};
+}
+//#endregion
+//#region src/data/fetch.ts
+/** 判断是否为分页结果形态 */
+function isPagedResult(value) {
+	return !!value && typeof value === "object" && Array.isArray(value.list) && typeof value.total === "number";
+}
+/** 归一化：数组 → 列表；{ list, total } → 分页；其他 → 单值 */
+function normalizeFetchResult(raw) {
+	if (Array.isArray(raw)) return {
+		data: raw,
+		total: raw.length,
+		raw
+	};
+	if (isPagedResult(raw)) return {
+		data: raw.list,
+		total: raw.total,
+		raw
+	};
+	return {
+		data: raw,
+		raw
+	};
+}
+/**
+* 创建资源请求控制器。纯工厂、无生命周期副作用，可在组件、组合函数或测试中使用。
+* 不主动发起请求，首次调用由消费方（组件资源钩子或宿主）触发。
+*/
+function createFetchController(fetcher) {
+	const state = ref({
+		status: "pending",
+		data: void 0
+	});
+	const loading = ref(false);
+	const error = ref(void 0);
+	let requestId = 0;
+	let lastQuery = {};
+	let abortController;
+	const run = async (query) => {
+		const currentId = ++requestId;
+		lastQuery = query;
+		abortController?.abort();
+		abortController = typeof AbortController !== "undefined" ? new AbortController() : void 0;
+		const hadSuccess = state.value.status === "success";
+		state.value = {
+			status: "pending",
+			data: hadSuccess ? state.value.data : void 0,
+			isStale: hadSuccess
+		};
+		loading.value = true;
+		error.value = void 0;
+		try {
+			const raw = await fetcher({
+				...query,
+				signal: abortController?.signal
+			});
+			if (currentId !== requestId) return void 0;
+			const normalized = normalizeFetchResult(raw);
+			state.value = {
+				status: "success",
+				data: normalized,
+				isStale: false
+			};
+			error.value = void 0;
+			return normalized;
+		} catch (err) {
+			if (currentId !== requestId) return void 0;
+			state.value = {
+				status: "error",
+				data: state.value.data,
+				error: err,
+				isStale: false
+			};
+			error.value = err;
+			return;
+		} finally {
+			if (currentId === requestId) loading.value = false;
+		}
+	};
+	const refresh = () => run(lastQuery);
+	const abort = () => {
+		requestId++;
+		abortController?.abort();
+	};
+	return {
+		run,
+		refresh,
+		abort,
+		state,
+		loading,
+		error
+	};
+}
+/** useFetch 返回对象的品牌标记（内部识别用） */
+const FETCH_RESOURCE = Symbol("fetch-resource");
+/**
+* 宿主侧资源封装：把一个 Fetch 方法升级为带响应式状态的对象。
+* 不绑定组件时不会自动请求；组件接收其 `fetch` 后由组件机制驱动，
+* 状态在组件内外共享同一份。
+*/
+function useFetch(fetcher) {
+	const controller = createFetchController(fetcher);
+	const total = ref(void 0);
+	const state = computed(() => {
+		const current = controller.state.value;
+		return {
+			status: current.status,
+			data: current.data?.data,
+			error: current.error,
+			isStale: current.isStale,
+			retry: () => void controller.refresh()
+		};
+	});
+	watch(() => controller.state.value, (current) => {
+		if (current.status === "success" && current.data) total.value = current.data.total;
+	});
+	const invoke = async (query = {}) => {
+		return (await controller.run(query))?.raw;
+	};
+	return {
+		fetch: invoke,
+		state,
+		status: computed(() => controller.state.value.status),
+		data: computed(() => controller.state.value.data?.data),
+		error: controller.error,
+		loading: computed(() => controller.loading.value),
+		isStale: computed(() => controller.state.value.isStale === true),
+		total,
+		refresh: (query) => query ? invoke(query) : controller.refresh().then((r) => r?.raw),
+		[FETCH_RESOURCE]: controller
+	};
+}
+/** 判断是否为 useFetch 返回对象 */
+function isUseFetchReturn(value) {
+	return !!value && typeof value === "object" && FETCH_RESOURCE in value;
+}
+/**
+* 组件内部统一资源机制：
+* 挂载即请求；getQuery 的 deep 变化自动重取；防抖、竞态后到为准、stale 保留旧数据。
+* 所有 fetch 型组件共用此钩子，开发者只绑定 fetch 方法即可。
+*/
+function useFetchResource(source, options) {
+	const { getQuery, initialData, mapData, debounce = 0, merge } = options;
+	const hasSource = ref(false);
+	const total = ref(0);
+	const lastData = ref(initialData);
+	const controllerRef = shallowRef(void 0);
+	let internalController;
+	let timer;
+	const map = (normalized) => {
+		if (!normalized) return initialData;
+		return mapData ? mapData(normalized) : normalized.data;
+	};
+	/** 最近一次命令式查询覆盖（懒加载等），retry 时保留 */
+	let lastOverride;
+	const execute = async (override) => {
+		const controller = controllerRef.value;
+		if (!controller) return;
+		if (override !== void 0) lastOverride = override;
+		const query = {
+			...getQuery(),
+			...lastOverride
+		};
+		if (merge && query.pagination && query.pagination.currentPage <= 1) lastData.value = initialData;
+		const result = await controller.run(query);
+		if (!result || !hasSource.value) return;
+		const next = map(result);
+		lastData.value = merge ? merge(lastData.value, next, query) : next;
+		if (result.total !== void 0) total.value = result.total;
+	};
+	const state = computed(() => {
+		const current = controllerRef.value?.state.value;
+		if (!current || !controllerRef.value) return void 0;
+		return {
+			status: current.status,
+			data: current.status === "success" ? lastData.value : map(current.data),
+			error: current.error,
+			isStale: current.isStale,
+			retry: () => void execute()
+		};
+	});
+	const schedule = (immediateRun, override) => {
+		if (!controllerRef.value) return;
+		if (timer) clearTimeout(timer);
+		if (!immediateRun && debounce > 0) timer = setTimeout(() => void execute(override), debounce);
+		else execute(override);
+	};
+	const queryReady = ref(false);
+	let queryWatcherPrimed = false;
+	watch(() => queryReady.value ? getQuery() : null, () => {
+		if (!queryWatcherPrimed) {
+			queryWatcherPrimed = true;
+			return;
+		}
+		lastOverride = void 0;
+		schedule(false);
+	}, {
+		deep: true,
+		flush: "post"
+	});
+	let disposed = false;
+	function bind(raw) {
+		if (disposed) return;
+		internalController?.abort();
+		internalController = void 0;
+		if (!raw) {
+			controllerRef.value = void 0;
+			hasSource.value = false;
+			total.value = 0;
+			lastData.value = initialData;
+			lastOverride = void 0;
+			return;
+		}
+		if (isUseFetchReturn(raw)) controllerRef.value = raw[FETCH_RESOURCE];
+		else {
+			internalController = createFetchController(raw);
+			controllerRef.value = internalController;
+		}
+		hasSource.value = true;
+		total.value = 0;
+		lastData.value = initialData;
+		lastOverride = void 0;
+		queryReady.value = true;
+		schedule(true);
+	}
+	watch(() => toValue(source), bind, { flush: "post" });
+	queueMicrotask(() => bind(toValue(source)));
+	onScopeDispose(() => {
+		disposed = true;
+		if (timer) clearTimeout(timer);
+		internalController?.abort();
+	});
+	return {
+		enabled: hasSource,
+		state,
+		loading: computed(() => controllerRef.value?.loading.value ?? false),
+		error: computed(() => controllerRef.value?.error.value),
+		total,
+		refresh: async (override) => {
+			await execute(override);
+		}
+	};
+}
+//#endregion
+//#region src/data/useSubscribe.ts
+/** 归一 subscribe 返回值：导出错误（status 为 error 或携带 error）时返回失败信息，否则 null */
+function extractSubscribeFailure(result) {
+	if (result === null || typeof result !== "object") return null;
+	const { status, error } = result;
+	if (status === "error" || error != null) return { error: error ?? result };
+	return null;
+}
+/**
+* 订阅型数据消费：挂载时调用处理方法，resolve 出数据后渲染，
+* 失败时记录错误并保留旧数据（与 fetch 失败策略一致），支持 refresh 重试。
+*
+* @internal 消费组件：Table、Statistic、Tabs、Progress、Image 等所有数据展示类组件
+*/
+function useSubscribe(handler) {
+	const state = ref({
+		status: "pending",
+		data: void 0
+	});
+	const data = ref(void 0);
+	const loading = ref(false);
+	const error = ref(void 0);
+	const isStale = ref(false);
+	async function run() {
+		if (!handler) return;
+		loading.value = true;
+		isStale.value = !!data.value;
+		state.value = {
+			status: "pending",
+			data: data.value,
+			isStale: isStale.value,
+			retry: run
+		};
+		try {
+			const result = await handler();
+			const failure = extractSubscribeFailure(result);
+			if (failure) {
+				error.value = failure.error;
+				loading.value = false;
+				isStale.value = !!data.value;
+				state.value = {
+					status: "error",
+					data: data.value,
+					error: failure.error,
+					isStale: isStale.value,
+					retry: run
+				};
+				return;
+			}
+			if (result?.status === "loading") return;
+			data.value = result?.data;
+			error.value = void 0;
+			loading.value = false;
+			isStale.value = false;
+			state.value = {
+				status: "success",
+				data: data.value,
+				isStale: false,
+				retry: run
+			};
+		} catch (err) {
+			error.value = err;
+			loading.value = false;
+			isStale.value = !!data.value;
+			state.value = {
+				status: "error",
+				data: data.value,
+				error: err,
+				isStale: isStale.value,
+				retry: run
+			};
+		}
+	}
+	queueMicrotask(run);
+	return {
+		state,
+		data,
+		loading,
+		error,
+		isStale,
+		refresh: run
+	};
+}
+//#endregion
+//#region src/data/useChat.ts
+const LOCAL_PREFIX = "__local_";
+/**
+* 聊天消息模型：fetch 管历史（向上翻页前插）、subscribe 管新消息（追加去重）、
+* send 管发送（乐观上屏 + 失败保留重试）。
+*
+* @internal 消费组件：Chat
+*/
+function useChat(options) {
+	const pageSize = options.pageSize ?? 20;
+	const messages = ref([]);
+	const sending = ref(false);
+	const loadingOlder = ref(false);
+	const hasMore = ref(false);
+	const sendError = ref(void 0);
+	const historyError = ref(void 0);
+	let page = 0;
+	let historyCount = 0;
+	let seq = 0;
+	const isLocal = (message) => String(message.id).startsWith(LOCAL_PREFIX);
+	const subscription = useSubscribe(options.subscribe);
+	watch(subscription.data, (incoming) => {
+		if (incoming !== void 0 && incoming !== null) pushIncoming(incoming);
+	}, { deep: true });
+	function pushIncoming(incoming) {
+		const list = Array.isArray(incoming) ? incoming : [incoming];
+		for (const message of list) {
+			if (!message || message.id === void 0 || message.id === null) continue;
+			if (message.self) {
+				const localIndex = messages.value.findIndex((item) => isLocal(item) && item.status === "sent" && item.content === message.content);
+				if (localIndex >= 0) {
+					messages.value.splice(localIndex, 1, message);
+					continue;
+				}
+			}
+			if (messages.value.some((item) => item.id === message.id)) continue;
+			messages.value.push(message);
+		}
+	}
+	function prepend(batch) {
+		const older = batch.filter((message) => message && message.id !== void 0 && message.id !== null && !messages.value.some((item) => item.id === message.id));
+		if (older.length) messages.value.unshift(...older);
+	}
+	async function loadOlder() {
+		if (!options.fetch || loadingOlder.value) return;
+		loadingOlder.value = true;
+		historyError.value = void 0;
+		try {
+			page += 1;
+			const result = await options.fetch({ pagination: {
+				currentPage: page,
+				pageSize
+			} });
+			if (Array.isArray(result)) {
+				prepend(result);
+				historyCount += result.length;
+				hasMore.value = result.length >= pageSize;
+			} else if (result && Array.isArray(result.list)) {
+				const { list, total } = result;
+				prepend(list);
+				historyCount += list.length;
+				hasMore.value = typeof total === "number" ? historyCount < total : list.length >= pageSize;
+			} else hasMore.value = false;
+		} catch (err) {
+			page -= 1;
+			historyError.value = err instanceof Error ? err.message : String(err);
+		} finally {
+			loadingOlder.value = false;
+		}
+	}
+	async function send(content) {
+		const text = content.trim();
+		if (!text || !options.send || sending.value) return void 0;
+		sendError.value = void 0;
+		sending.value = true;
+		messages.value.push({
+			id: `${LOCAL_PREFIX}${++seq}`,
+			content: text,
+			self: true,
+			time: Date.now(),
+			status: "sending"
+		});
+		const temp = messages.value[messages.value.length - 1];
+		try {
+			const failure = extractActionFailure(await options.send(text));
+			if (failure) {
+				temp.status = "failed";
+				sendError.value = actionErrorText(failure.error, "发送失败");
+				return;
+			}
+			temp.status = "sent";
+			return temp;
+		} catch (err) {
+			temp.status = "failed";
+			sendError.value = actionErrorText(err, "发送失败");
+			return;
+		} finally {
+			sending.value = false;
+		}
+	}
+	async function retry(message) {
+		if (!options.send || !isLocal(message)) return void 0;
+		const index = messages.value.findIndex((item) => item.id === message.id);
+		if (index >= 0) messages.value.splice(index, 1);
+		return send(message.content);
+	}
+	if (options.fetch) queueMicrotask(() => void loadOlder());
+	return {
+		messages,
+		sending,
+		loadingOlder,
+		hasMore,
+		sendError,
+		historyError,
+		send,
+		retry,
+		loadOlder
+	};
+}
+//#endregion
+//#region src/resources/create-fetch-adapter.ts
+/** 内置适配器的 HTTP 错误：携带状态码与解析后的响应体 */
+var ResourceHttpError = class extends Error {
+	constructor(method, url, status, body) {
+		super(`${method} ${url} 请求失败（${status}）`);
+		this.name = "ResourceHttpError";
+		this.status = status;
+		this.body = body;
+	}
+};
+/** 拼装 query 参数：undefined 值整体省略 */
+function buildUrl(url, query) {
+	if (!query) return url;
+	const search = new URLSearchParams();
+	for (const [key, value] of Object.entries(query)) {
+		if (value === void 0) continue;
+		search.append(key, String(value));
+	}
+	const qs = search.toString();
+	if (!qs) return url;
+	return `${url}${url.includes("?") ? "&" : "?"}${qs}`;
+}
+/**
+* 基于 fetch 的内置传输适配器。
+* GET 以 query 拼装 URL，写操作以 JSON 提交 body；非 2xx 状态拒绝为
+* ResourceHttpError（携带状态码与响应体）；响应体自动 JSON 解析，空体为 undefined。
+*/
+function createFetchAdapter() {
+	return async (request) => {
+		const headers = { ...request.headers };
+		let body;
+		if (request.body !== void 0) {
+			headers["Content-Type"] ??= "application/json";
+			body = typeof request.body === "string" ? request.body : JSON.stringify(request.body);
+		}
+		const response = await fetch(buildUrl(request.url, request.query), {
+			method: request.method,
+			headers,
+			body,
+			signal: request.signal
+		});
+		const text = await response.text();
+		let parsed;
+		try {
+			parsed = text === "" ? void 0 : JSON.parse(text);
+		} catch {
+			parsed = text;
+		}
+		if (!response.ok) throw new ResourceHttpError(request.method, request.url, response.status, parsed);
+		return parsed;
+	};
+}
+//#endregion
+//#region src/resources/parse-open-api.ts
+/** 分页 / 关键词 / 排序参数的常见命名（识别统一查询片段，不作为筛选项） */
+const PAGE_NAME = /^(page|pageno|pageindex|pagenum|current)$/i;
+const PAGE_SIZE_NAME = /^(pagesize|size|limit|perpage|per_page)$/i;
+const KEYWORD_NAME = /^(keyword|kw|q|search)$/i;
+const SORTER_NAME = /^(sort|sorter|sortby|sort_by|order|orderby|order_by)$/i;
+const TOTAL_NAME = /^(total|totalcount|totalelements|total_items|count)$/i;
+const HTTP_METHODS = [
+	"get",
+	"post",
+	"put",
+	"patch",
+	"delete"
+];
+/** 按 $ref 指针（#/a/b/c）在文档中查找目标 */
+function lookupRef(doc, ref) {
+	if (!ref.startsWith("#/")) return void 0;
+	let current = doc;
+	for (const segment of ref.slice(2).split("/")) {
+		if (current === null || typeof current !== "object") return void 0;
+		current = current[segment.replace(/~1/g, "/").replace(/~0/g, "~")];
+	}
+	return current;
+}
+/** 解引用（含引用链），带深度保护 */
+function resolve(doc, schema, depth = 0) {
+	if (depth > 10 || schema === null || typeof schema !== "object") return void 0;
+	const ref = schema.$ref;
+	if (typeof ref === "string") {
+		const target = lookupRef(doc, ref);
+		return target ? resolve(doc, target, depth + 1) : void 0;
+	}
+	return schema;
+}
+/** 操作的 2xx 响应 schema：3.x 取 content，2.0 直接取 schema */
+function responseSchema(op) {
+	const responses = op.responses;
+	if (!responses) return void 0;
+	const ok = responses["200"] ?? responses["201"] ?? responses.default;
+	if (!ok) return void 0;
+	const content = ok.content;
+	if (content) return (content["application/json"] ?? Object.values(content)[0])?.schema;
+	return ok.schema;
+}
+/** 操作的请求体 schema：3.x 取 requestBody，2.0 取 in:body 参数 */
+function requestBodySchema(doc, op) {
+	const requestBody = op.requestBody;
+	if (requestBody) {
+		const content = (typeof requestBody.$ref === "string" ? lookupRef(doc, requestBody.$ref) : requestBody)?.content;
+		if (!content) return void 0;
+		return (content["application/json"] ?? Object.values(content)[0])?.schema;
+	}
+	return op.parameters?.find((param) => param.in === "body")?.schema;
+}
+/** schema 的元数据字段类型；object / array 等非原始类型返回 null（不进入元数据） */
+function fieldType(schema) {
+	if (Array.isArray(schema.enum) && schema.enum.length > 0 && (schema.type === "string" || schema.type === "integer" || schema.type === "number")) return "enum";
+	switch (schema.type) {
+		case "integer":
+		case "number": return "number";
+		case "boolean": return "boolean";
+		case "string":
+			if (schema.format === "date-time") return "datetime";
+			if (schema.format === "date") return "date";
+			return "string";
+		default: return null;
+	}
+}
+function fieldOptions(schema) {
+	if (!Array.isArray(schema.enum)) return void 0;
+	return schema.enum.map((value) => ({
+		label: String(value),
+		value
+	}));
+}
+/** 文档声明的内容格式：仅透传字符串形式的 format，其余忽略 */
+function fieldFormat(schema) {
+	return typeof schema.format === "string" && schema.format !== "" ? schema.format : void 0;
+}
+/** 从对象 schema 的 properties 提取字段描述（仅原始类型） */
+function extractFields(doc, schema) {
+	const resolved = resolve(doc, schema);
+	const properties = resolved?.properties;
+	if (!properties) return [];
+	const requiredList = Array.isArray(resolved?.required) ? resolved.required : [];
+	const fields = [];
+	for (const [name, prop] of Object.entries(properties)) {
+		const resolvedProp = resolve(doc, prop);
+		if (!resolvedProp) continue;
+		const type = fieldType(resolvedProp);
+		if (!type) continue;
+		fields.push({
+			name,
+			label: resolvedProp.description ?? resolvedProp.title ?? name,
+			type,
+			format: fieldFormat(resolvedProp),
+			options: type === "enum" ? fieldOptions(resolvedProp) : void 0,
+			required: requiredList.includes(name) || void 0
+		});
+	}
+	return fields;
+}
+/** 识别列表响应形状：裸数组或「数组属性 + 总数属性」的信封结构 */
+function listShape(doc, schema) {
+	const resolved = resolve(doc, schema);
+	if (!resolved) return null;
+	if (resolved.type === "array") return { itemSchema: resolved.items };
+	const properties = resolved.properties;
+	if (!properties) return null;
+	let listPath;
+	let totalPath;
+	let itemSchema;
+	for (const [name, prop] of Object.entries(properties)) {
+		const resolvedProp = resolve(doc, prop);
+		if (!resolvedProp) continue;
+		if (resolvedProp.type === "array" && listPath === void 0) {
+			listPath = name;
+			itemSchema = resolvedProp.items;
+		} else if (TOTAL_NAME.test(name) && resolvedProp.type === "integer" && totalPath === void 0) totalPath = name;
+	}
+	return listPath === void 0 ? null : {
+		itemSchema,
+		listPath,
+		totalPath
+	};
+}
+/** 把提取的字段合并进资源：已存在则追加场景标记，否则新建 */
+function mergeField(definition, partial, scopeKey) {
+	const fields = definition.fields ??= [];
+	let field = fields.find((item) => item.name === partial.name);
+	if (!field) {
+		field = {
+			name: partial.name,
+			label: partial.label,
+			type: partial.type,
+			scope: {}
+		};
+		if (partial.options) field.options = partial.options;
+		if (partial.format) field.format = partial.format;
+		fields.push(field);
+	} else if (partial.format) field.format ??= partial.format;
+	field.scope = {
+		...field.scope,
+		[scopeKey]: true
+	};
+	if (partial.required) field.required = true;
+}
+/** 操作归类：路径占位符区分集合与单项 */
+function classify(method, hasPlaceholder) {
+	switch (method) {
+		case "get": return hasPlaceholder ? "detail" : "list";
+		case "post": return hasPlaceholder ? null : "create";
+		case "put":
+		case "patch": return hasPlaceholder ? "update" : null;
+		case "delete": return hasPlaceholder ? "remove" : null;
+		default: return null;
+	}
+}
+/** 资源名：首个 tag，回落路径首个非占位段 */
+function resourceName(op, path) {
+	const tag = op.tags?.[0];
+	if (tag) return tag;
+	return path.split("/").find((part) => part !== "" && !part.startsWith("{")) ?? "root";
+}
+/** 从列表操作的查询参数识别统一查询片段命名 */
+function applyQueryNames(definition, params) {
+	const queryNames = {};
+	for (const param of params) {
+		const name = param.name;
+		if (!name || param.in !== "query") continue;
+		if (PAGE_NAME.test(name)) queryNames.currentPage = name;
+		else if (PAGE_SIZE_NAME.test(name)) queryNames.pageSize = name;
+		else if (KEYWORD_NAME.test(name)) queryNames.keyword = name;
+		else if (SORTER_NAME.test(name)) queryNames.sorter = name;
+	}
+	if (Object.keys(queryNames).length > 0) definition.queryNames = queryNames;
+}
+/** 非分页 / 关键词 / 排序的查询参数标记为筛选项；不存在的字段新建 */
+function applyFilterScopes(doc, definition, params) {
+	const fields = definition.fields ??= [];
+	for (const param of params) {
+		const name = param.name;
+		if (!name || param.in !== "query") continue;
+		if (PAGE_NAME.test(name) || PAGE_SIZE_NAME.test(name) || KEYWORD_NAME.test(name) || SORTER_NAME.test(name)) continue;
+		const schema = resolve(doc, param.schema ?? param);
+		const type = (schema && fieldType(schema)) ?? "string";
+		const existing = fields.find((field) => field.name === name);
+		if (existing) existing.scope = {
+			...existing.scope,
+			filter: true
+		};
+		else {
+			const field = {
+				name,
+				label: param.description ?? param.summary ?? name,
+				type,
+				scope: { filter: true }
+			};
+			if (schema) {
+				const format = fieldFormat(schema);
+				if (format) field.format = format;
+				if (fieldType(schema) === "enum") field.options = fieldOptions(schema);
+			}
+			fields.push(field);
+		}
+	}
+}
+/**
+* OpenAPI（Swagger）解析器。
+* 支持路径级 + 操作级参数合并（Swagger 2.0 常见）、$ref 引用、
+* 信封响应（数组属性 + 总数属性）与裸数组响应。
+*/
+const parseOpenApi = (rawDoc) => {
+	const doc = rawDoc;
+	const paths = doc?.paths;
+	if (!paths || typeof paths !== "object") throw new Error("无法解析元数据文档：缺少 paths 定义");
+	const resources = {};
+	const ensureResource = (name) => resources[name] ??= { fields: [] };
+	for (const [path, rawItem] of Object.entries(paths)) {
+		const item = rawItem;
+		const sharedParams = item.parameters ?? [];
+		for (const method of HTTP_METHODS) {
+			const op = item[method];
+			if (!op) continue;
+			const key = classify(method, path.includes("{"));
+			if (!key) continue;
+			const definition = ensureResource(resourceName(op, path));
+			definition[key] = {
+				method: method.toUpperCase(),
+				path
+			};
+			const params = [...sharedParams, ...op.parameters ?? []];
+			if (key === "list") {
+				applyQueryNames(definition, params);
+				const shape = listShape(doc, responseSchema(op));
+				if (shape) {
+					if (shape.listPath) definition.response = {
+						list: shape.listPath,
+						total: shape.totalPath
+					};
+					for (const field of extractFields(doc, shape.itemSchema)) mergeField(definition, field, "list");
+					applyFilterScopes(doc, definition, params);
+				}
+			} else if (key === "create" || key === "update") for (const field of extractFields(doc, requestBodySchema(doc, op))) mergeField(definition, field, key);
+		}
+	}
+	return { resources };
+};
+//#endregion
+//#region src/resources/use-resources.ts
+const EMPTY_SCHEMA = { resources: {} };
+/** 拼接服务器根地址与路径；路径为绝对 URL 时直接使用 */
+function resolveUrl(server, path) {
+	if (/^[a-z][a-z\d+\-.]*:\/\//i.test(path)) return path;
+	return `${server.replace(/\/+$/, "")}/${path.replace(/^\/+/, "")}`;
+}
+/** 按点分路径从响应体中取值 */
+function pickPath(body, path) {
+	let current = body;
+	for (const segment of path.split(".")) {
+		if (current === null || typeof current !== "object") return void 0;
+		current = current[segment];
+	}
+	return current;
+}
+/** 统一查询片段 → 请求 query 参数（参数名按资源表映射，缺省回落默认名） */
+function buildListQuery(definition, query) {
+	const names = {
+		keyword: "keyword",
+		currentPage: "page",
+		pageSize: "pageSize",
+		sorter: "sorter",
+		...definition.queryNames
+	};
+	const params = {};
+	if (!query) return params;
+	if (query.keyword !== void 0 && query.keyword !== null && query.keyword !== "") params[names.keyword] = query.keyword;
+	if (query.pagination) {
+		params[names.currentPage] = query.pagination.currentPage;
+		params[names.pageSize] = query.pagination.pageSize;
+	}
+	if (query.sorter && query.sorter.order) params[names.sorter] = `${query.sorter.key},${query.sorter.order}`;
+	if (query.filters && typeof query.filters === "object") {
+		if (names.filters) params[names.filters] = JSON.stringify(query.filters);
+		else for (const [key, value] of Object.entries(query.filters)) {
+			if (value === void 0 || value === null || value === "") continue;
+			params[key] = Array.isArray(value) ? value.map(String).join(",") : typeof value === "object" ? JSON.stringify(value) : value;
+		}
+	}
+	return params;
+}
+/** 按资源表的列表响应映射归一化：信封取数组与总数，裸数组直传 */
+function normalizeListResult(definition, body) {
+	const mapping = definition.response;
+	if (!mapping?.list) return body;
+	const list = pickPath(body, mapping.list);
+	if (!Array.isArray(list)) return body;
+	const total = mapping.total ? pickPath(body, mapping.total) : void 0;
+	return total === void 0 ? list : {
+		list,
+		total: Number(total)
+	};
+}
+/**
+* 元数据驱动的资源池：声明一次「服务器地址 + 元数据解析方式」，
+* 按资源名取客户端，请求方法与 fetch / action 协议同形，
+* 字段元数据（columns / filters / properties）按组件属性形状导出。
+*
+* 池初始化时开始加载元数据；client() 无需等待就绪，方法调用时内部自动等待。
+*/
+function useResources(options) {
+	const adapter = options.request ?? createFetchAdapter();
+	const schemaRef = shallowRef(null);
+	const statusRef = shallowRef("pending");
+	const errorRef = shallowRef(void 0);
+	let loadPromise = null;
+	const resolveHeaders = async () => typeof options.headers === "function" ? options.headers() : options.headers;
+	async function load() {
+		statusRef.value = "pending";
+		errorRef.value = void 0;
+		try {
+			let raw;
+			if (options.schema !== void 0) raw = typeof options.schema === "function" ? await options.schema() : options.schema;
+			else if (options.doc) {
+				const doc = await adapter({
+					method: "GET",
+					url: resolveUrl(options.server, options.doc),
+					headers: await resolveHeaders()
+				});
+				raw = await (options.parse ?? parseOpenApi)(doc, { server: options.server });
+			} else throw new Error("useResources 需要提供 doc（元数据文档）或 schema（资源表）之一");
+			schemaRef.value = options.refine ? await options.refine(raw) : raw;
+			statusRef.value = "success";
+		} catch (error) {
+			errorRef.value = error;
+			statusRef.value = "error";
+		}
+	}
+	/** 等待资源表就绪；加载失败时抛出错误，由调用方决定如何呈现 */
+	function ensureLoaded() {
+		if (!loadPromise) loadPromise = load();
+		return loadPromise.then(() => {
+			if (statusRef.value === "error") throw errorRef.value;
+			return schemaRef.value;
+		});
+	}
+	ensureLoaded().catch(() => {});
+	function client(name) {
+		const loaded = schemaRef.value;
+		if (loaded && !loaded.resources[name]) throw new Error(`资源池中不存在资源「${name}」`);
+		const requireDefinition = async () => {
+			const definition = (await ensureLoaded()).resources[name];
+			if (!definition) throw new Error(`资源池中不存在资源「${name}」`);
+			return definition;
+		};
+		const requireOp = (definition, key) => {
+			const op = definition[key];
+			if (!op) throw new Error(`资源「${name}」未声明 ${key} 操作`);
+			return op;
+		};
+		const collectionUrl = (op) => resolveUrl(options.server, op.path);
+		const itemUrl = (op, id) => resolveUrl(options.server, op.path).replace(/\{id\}/g, encodeURIComponent(String(id)));
+		const fieldsOf = () => schemaRef.value?.resources[name]?.fields ?? [];
+		const columnsOf = () => fieldsOf().filter((field) => field.scope?.list).map((field) => {
+			const column = {
+				key: field.name,
+				title: field.label,
+				type: field.type
+			};
+			if (field.format) column.format = field.format;
+			if (field.type === "enum" && field.options && field.options.length > 0) column.filters = field.options;
+			return column;
+		});
+		return {
+			name,
+			async list(query) {
+				const definition = await requireDefinition();
+				const op = requireOp(definition, "list");
+				return normalizeListResult(definition, await adapter({
+					method: op.method,
+					url: collectionUrl(op),
+					query: buildListQuery(definition, query),
+					headers: await resolveHeaders(),
+					signal: query?.signal
+				}));
+			},
+			async detail(id) {
+				const definition = await requireDefinition();
+				const op = requireOp(definition, "detail");
+				return await adapter({
+					method: op.method,
+					url: itemUrl(op, id),
+					headers: await resolveHeaders()
+				});
+			},
+			async create(payload) {
+				const definition = await requireDefinition();
+				const op = requireOp(definition, "create");
+				return await adapter({
+					method: op.method,
+					url: collectionUrl(op),
+					body: payload,
+					headers: await resolveHeaders()
+				});
+			},
+			async update(id, payload) {
+				const definition = await requireDefinition();
+				const op = requireOp(definition, "update");
+				return await adapter({
+					method: op.method,
+					url: itemUrl(op, id),
+					body: payload,
+					headers: await resolveHeaders()
+				});
+			},
+			async remove(id) {
+				const definition = await requireDefinition();
+				const op = requireOp(definition, "remove");
+				return await adapter({
+					method: op.method,
+					url: itemUrl(op, id),
+					headers: await resolveHeaders()
+				});
+			},
+			get fields() {
+				return fieldsOf();
+			},
+			get columns() {
+				return columnsOf();
+			},
+			get filters() {
+				return fieldsOf().filter((field) => field.scope?.filter);
+			},
+			get properties() {
+				return fieldsOf().filter((field) => field.scope?.create === true || field.scope?.update === true);
+			}
+		};
+	}
+	return {
+		state: {
+			get status() {
+				return statusRef.value;
+			},
+			get data() {
+				return schemaRef.value ?? EMPTY_SCHEMA;
+			},
+			get error() {
+				return errorRef.value;
+			},
+			retry: () => {
+				loadPromise = null;
+				ensureLoaded().catch(() => {});
+			}
+		},
+		client,
+		has: (target) => schemaRef.value?.resources[target] !== void 0,
+		get names() {
+			return Object.keys(schemaRef.value?.resources ?? {});
+		}
+	};
+}
+//#endregion
+//#region src/media/useImageState.ts
+/**
+* 图片加载状态机：loading / loaded / error，可选视口感知懒加载。
+* 不创建 DOM，组件把返回的事件绑定到 <img> 即可。
+*
+* @internal 消费组件：Image、Avatar
+*/
+function useImageState(src, options = {}) {
+	const { lazy = false, target, root, rootMargin, onLoad, onError } = options;
+	const status = ref("idle");
+	const shouldLoad = ref(!lazy);
+	if (lazy && target) {
+		const { isIntersecting } = useIntersectionObserver(target, {
+			root,
+			rootMargin,
+			once: true
+		});
+		watch(isIntersecting, (visible) => {
+			if (visible) shouldLoad.value = true;
+		});
+	} else if (lazy) shouldLoad.value = true;
+	const isLoading = ref(false);
+	const isLoaded = ref(false);
+	const isError = ref(false);
+	const setStatus = (next) => {
+		status.value = next;
+		isLoading.value = next === "loading";
+		isLoaded.value = next === "loaded";
+		isError.value = next === "error";
+	};
+	watch(() => [toValue(src), shouldLoad.value], ([nextSrc, allowed]) => {
+		if (!allowed || !nextSrc) {
+			setStatus(nextSrc ? "loading" : "idle");
+			return;
+		}
+		setStatus("loading");
+	}, { immediate: true });
+	const handleLoad = (event) => {
+		setStatus("loaded");
+		onLoad?.(event);
+	};
+	const handleError = (event) => {
+		setStatus("error");
+		onError?.(event);
+	};
+	const reload = () => {
+		setStatus("loading");
+	};
+	return {
+		status,
+		isLoading,
+		isLoaded,
+		isError,
+		onLoad: handleLoad,
+		onError: handleError,
+		reload,
+		shouldLoad
+	};
+}
+//#endregion
+export { FETCH_RESOURCE, ResourceHttpError, actionErrorText, actionErrorText as subscribeErrorText, createControllableModel, createFetchAdapter, createFetchController, createLoadingService, createMessage, createNotification, extractActionFailure, extractSubscribeFailure, injectForm, injectFormField, isPagedResult, isUseFetchReturn, message, normalizeFetchResult, notification, parseOpenApi, provideForm, provideFormField, resetGlobalZIndex, useActionState, useActionValue, useAsyncState, useAsyncSuggest, useChat, useCheckableGroup, useClickOutside, useClipboard, useControllableModel, useDateGrid, useDateModel, useDismiss, useDraggable, useEventListener, useFetch, useFetchResource, useFloating, useFocusReturn, useFocusTrap, useForm, useFormField, useHoverIntent, useId, useImageState, useIntersectionObserver, useIntervalFn, useListboxNavigation, useLoadingService, useMediaQuery, useModal, useOpen, useOverlayContainer, usePagination, usePopoverModel, useResizeObserver, useResources, useRovingFocus, useScroll, useScrollIntoView, useScrollLock, useSelectModel, useSubscribe, useTimeModel, useTimeoutFn, useToastQueue, useToggle, useTransitionVisible, useTreeModel, useTypeahead, useZIndex };