@zhencai/vue-focus-scope 1.0.9 → 1.0.11

package/dist/FocusScope.cjs

@@ -0,0 +1,166 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let vue = require("vue");
+//#region src/components/FocusScope.vue?vue&type=script&setup=true&lang.ts
+var _hoisted_1 = {
+	key: 0,
+	tabindex: "0"
+};
+//#endregion
+//#region src/components/FocusScope.vue
+var FocusScope_default = /* @__PURE__ */ (0, vue.defineComponent)({
+	__name: "FocusScope",
+	props: {
+		tabMode: { default: "loop" },
+		autofocus: {
+			type: Boolean,
+			default: false
+		}
+	},
+	setup(__props) {
+		const props = __props;
+		/**
+		* wrapper 容器引用
+		* 用于限定焦点作用域（Focus Scope）
+		*/
+		const wrapper = (0, vue.useTemplateRef)("wrapper");
+		/**
+		* 获取当前作用域内所有“可聚焦元素”
+		*
+		* 规则：
+		* 1. 排除 tabindex = -1（不可通过 Tab 聚焦）
+		* 2. 排除 disabled 元素
+		* 3. 排除哨兵节点（sentinel-start / sentinel-end）
+		* 4. 排除被 disabled 的 fieldset 包裹的元素
+		*/
+		function getAllTabObjects(scope) {
+			if (!scope) return [];
+			return Array.from(scope.querySelectorAll("a[href]:not([tabindex=\"-1\"]):not(.sentinel-start):not(.sentinel-end),       button:not([tabindex=\"-1\"]):not([disabled]):not(.sentinel-start):not(.sentinel-end),       input:not([tabindex=\"-1\"]):not([disabled]):not(.sentinel-start):not(.sentinel-end),       select:not([tabindex=\"-1\"]):not([disabled]):not(.sentinel-start):not(.sentinel-end),       textarea:not([tabindex=\"-1\"]):not([disabled]):not(.sentinel-start):not(.sentinel-end),       [tabindex]:not([tabindex=\"-1\"]):not(.sentinel-start):not(.sentinel-end)")).filter((el) => {
+				/**
+				* 向上查找父级
+				* 如果在 disabled 的 fieldset 内，则不可聚焦
+				*/
+				let parent = el.parentElement;
+				while (parent) {
+					if (parent.tagName === "FIELDSET") {
+						if (parent.disabled) return false;
+					}
+					parent = parent.parentElement;
+				}
+				return true;
+			});
+		}
+		/**
+		* 聚焦第一个可聚焦元素
+		*/
+		function focusFirst() {
+			try {
+				if (wrapper.value) {
+					const objects = getAllTabObjects(wrapper.value);
+					if (objects.length === 0) return;
+					objects[0].focus();
+				}
+			} catch (error) {
+				console.error("focusFirst error:", error);
+			}
+		}
+		/**
+		* 聚焦最后一个可聚焦元素
+		*/
+		function focusLast() {
+			if (wrapper.value) {
+				const objects = getAllTabObjects(wrapper.value);
+				if (objects.length === 0) return;
+				objects[objects.length - 1].focus();
+			}
+		}
+		/**
+		* 当焦点进入“起始哨兵”时触发
+		*
+		* 关键逻辑：
+		* 1. 判断焦点来源（relatedTarget）
+		* 2. 区分是：
+		*    - 从外部进入
+		*    - 从内部 Shift+Tab 回退
+		*/
+		function onFocusStart(e) {
+			if (!wrapper.value) return;
+			const from = e.relatedTarget;
+			/**
+			* 情况1：没有来源（例如浏览器初始化 / JS focus）
+			* → 默认聚焦第一个
+			*/
+			if (!(from instanceof Node)) {
+				focusFirst();
+				return;
+			}
+			/**
+			* 情况2：从作用域外进入
+			* → 正常进入，聚焦第一个
+			*/
+			if (!wrapper.value.contains(from)) focusFirst();
+			else
+ /**
+			* 情况3：从作用域内部 Shift+Tab 回来
+			* → 说明用户想“往前”，应跳到最后一个（循环）
+			*/
+			focusLast();
+		}
+		/**
+		* 当焦点进入“结束哨兵”时触发
+		*
+		* 场景：
+		* 用户在最后一个元素按 Tab
+		*
+		* 行为：
+		* → 跳回第一个（形成循环）
+		*/
+		function onFocusEnd() {
+			focusFirst();
+		}
+		/**
+		* 监听 autofocus 属性的变化
+		*
+		* 作用：
+		* 1. 当 autofocus 从 false 变为 true 时，自动聚焦第一个可聚焦元素
+		* 2. 支持动态控制自动聚焦行为（例如在模态框打开时启用）
+		* 3. 该监听的主要作用是，当一个页面有多个作用域时，为了不让后挂载的元素抢占焦点，可以先把autofocus设置为false，在挂载后有自动聚焦需求，再设置为true。比如挂载后的第二作用域可以显示或隐藏。若不是该需求，挂载自动聚焦就足够了
+		*
+		* immediate: true 的意义：
+		* - 组件创建时立即执行一次
+		* - 如果初始 autofocus 为 true，会在挂载后立即聚焦第一个元素
+		* - 避免需要手动调用 focusFirst()
+		*
+		* 使用场景：
+		* - 模态框/对话框打开时自动聚焦第一个输入框
+		* - 表单显示时自动聚焦第一个字段
+		* - 动态切换焦点作用域时重新聚焦
+		*/
+		(0, vue.watch)(() => props.autofocus, async (newValue) => {
+			if (newValue === true) {
+				await (0, vue.nextTick)();
+				focusFirst();
+			}
+		}, { immediate: true });
+		return (_ctx, _cache) => {
+			return (0, vue.openBlock)(), (0, vue.createElementBlock)("div", {
+				ref_key: "wrapper",
+				ref: wrapper
+			}, [
+				(0, vue.createElementVNode)("div", {
+					tabindex: "0",
+					class: "sentinel-start",
+					onFocus: onFocusStart
+				}, null, 32),
+				(0, vue.renderSlot)(_ctx.$slots, "default"),
+				__props.tabMode === "soft-loop" ? ((0, vue.openBlock)(), (0, vue.createElementBlock)("div", _hoisted_1)) : (0, vue.createCommentVNode)("", true),
+				(0, vue.createElementVNode)("div", {
+					tabindex: "0",
+					class: "sentinel-end",
+					onFocus: onFocusEnd
+				}, null, 32)
+			], 512);
+		};
+	}
+});
+//#endregion
+exports.FocusScope = FocusScope_default;

package/dist/{FocusScope.js → FocusScope.mjs}

@@ -1,4 +1,3 @@
-/* My Library v1.0.0 */
 import { createCommentVNode, createElementBlock, createElementVNode, defineComponent, nextTick, openBlock, renderSlot, useTemplateRef, watch } from "vue";
 //#region src/components/FocusScope.vue?vue&type=script&setup=true&lang.ts
 var _hoisted_1 = {
@@ -163,4 +162,4 @@ var FocusScope_default = /* @__PURE__ */ defineComponent({
 	}
 });
 //#endregion
-export { FocusScope_default as FocusScope, FocusScope_default as default };
+export { FocusScope_default as FocusScope };

package/package.json

@@ -1,14 +1,17 @@
 {
     "name": "@zhencai/vue-focus-scope",
-    "module": "FocusScope.js",
-    "version": "1.0.9",
+    "module": "dist/FocusScope.mjs",
+    "main": "dist/FocusScope.cjs",
+    "version": "1.0.11",
     "peerDependencies": {
         "vue": "^3.0.0"
     },
     "files": [
         "dist",
+        "index.d.ts",
         "README.md",
         "LICENSE"
     ],
+    "types": "index.d.ts",
     "license": "MIT"
 }