@zhencai/vue-focus-scope 1.0.1 → 1.0.4

package/index.d.ts

@@ -1,30 +1,8 @@
-// index.d.ts
-import { DefineComponent } from "vue";
+import { DefineComponent } from 'vue';
 
-type TabMode = "loop" | "loop-sentinel";
+declare const FocusScope: DefineComponent<{
+    tabMode?: 'loop' | 'soft-loop';
+}>;
 
-interface FocusScopeProps {
-    autoFocus?: "first" | "last" | false;
-    tabMode?: TabMode;
-}
+export { FocusScope };
 
-export interface FocusScopeExpose {
-    activate: () => void;
-    deactivate: () => void;
-    focusFirst: () => void;
-    focusLast: () => void;
-}
-
-declare const FocusScope: DefineComponent<
-    FocusScopeProps,
-    {},
-    {},
-    {},
-    {},
-    {},
-    {},
-    {},
-    FocusScopeExpose
->;
-
-export default FocusScope;

package/index.js

@@ -1,107 +1,71 @@
-import { createElementBlock, defineComponent, onMounted, onUnmounted, openBlock, ref, renderSlot } from "vue";
+import { createCommentVNode as e, createElementBlock as t, createElementVNode as n, defineComponent as r, openBlock as i, renderSlot as a, useTemplateRef as o } from "vue";
 //#region src/components/FocusScope.vue?vue&type=script&setup=true&lang.ts
-var selector = "a[href],button:not([disabled]),textarea:not([disabled]),input:not([disabled]),select:not([disabled]),[tabindex]:not([tabindex='-1']),[contenteditable='true']";
-var FocusScope_vue_vue_type_script_setup_true_lang_default = /* @__PURE__ */ defineComponent({
+var s = {
+	key: 0,
+	tabindex: "0"
+}, c = /* @__PURE__ */ r({
 	__name: "FocusScope",
-	props: {
-		autoFocus: {
-			type: [String, Boolean],
-			default: "first"
-		},
-		tabMode: { default: "loop" }
-	},
-	setup(__props) {
-		const props = __props;
-		const scopeRef = ref(null);
-		let active = false;
-		let previous = null;
-		const getFocusable = () => {
-			if (!scopeRef.value) return [];
-			return [...scopeRef.value.querySelectorAll(selector)];
-		};
-		const focusFirst = () => {
-			getFocusable()[0]?.focus();
-		};
-		const focusLast = () => {
-			const list = getFocusable();
-			list[list.length - 1]?.focus();
-		};
-		const handleMouseDown = () => {
-			scopeRef.value?.focus();
-		};
-		const handleKeydown = (e) => {
-			if (!active) return;
-			if (e.key !== "Tab") return;
-			if (!scopeRef.value) return;
-			const list = getFocusable();
-			if (!list.length) return;
-			const first = list[0];
-			const last = list[list.length - 1];
-			const current = document.activeElement;
-			if (e.shiftKey) {
-				if (current === first) {
-					e.preventDefault();
-					if (props.tabMode === "loop") last.focus();
-					else scopeRef.value.focus();
-				} else if (current === scopeRef.value) {
-					e.preventDefault();
-					last.focus();
+	props: { tabMode: { default: "loop" } },
+	setup(r) {
+		let c = o("wrapper");
+		function l(e) {
+			return e ? Array.from(e.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((e) => {
+				let t = e.parentElement;
+				for (; t;) {
+					if (t.tagName === "FIELDSET" && t.disabled) return !1;
+					t = t.parentElement;
 				}
-			} else if (current === last) {
-				e.preventDefault();
-				if (props.tabMode === "loop") first.focus();
-				else scopeRef.value.focus();
-			} else if (current === scopeRef.value) {
-				e.preventDefault();
-				first.focus();
+				return !0;
+			}) : [];
+		}
+		function u() {
+			try {
+				if (c.value) {
+					let e = l(c.value);
+					if (e.length === 0) return;
+					e[0].focus();
+				}
+			} catch (e) {
+				console.error("focusFirst error:", e);
+			}
+		}
+		function d() {
+			if (c.value) {
+				let e = l(c.value);
+				if (e.length === 0) return;
+				e[e.length - 1].focus();
+			}
+		}
+		function f(e) {
+			if (!c.value) return;
+			let t = e.relatedTarget;
+			if (!(t instanceof Node)) {
+				u();
+				return;
 			}
-		};
-		const activate = () => {
-			if (!scopeRef.value) return;
-			active = true;
-			previous = document.activeElement;
-			if (props.autoFocus === "first") focusFirst();
-			if (props.autoFocus === "last") focusLast();
-		};
-		const deactivate = () => {
-			active = false;
-			if (previous && document.body.contains(previous)) previous.focus();
-			previous = null;
-		};
-		onMounted(() => {
-			document.addEventListener("keydown", handleKeydown);
-			activate();
-		});
-		onUnmounted(() => {
-			document.removeEventListener("keydown", handleKeydown);
-			deactivate();
-		});
-		return (_ctx, _cache) => {
-			return openBlock(), createElementBlock("div", {
-				ref_key: "scopeRef",
-				ref: scopeRef,
-				tabindex: "-1",
-				onMousedown: handleMouseDown,
-				"data-focus-scope": ""
-			}, [renderSlot(_ctx.$slots, "default", {}, void 0, true)], 544);
-		};
+			c.value.contains(t) ? d() : u();
+		}
+		function p() {
+			u();
+		}
+		return (o, l) => (i(), t("div", {
+			ref_key: "wrapper",
+			ref: c
+		}, [
+			n("div", {
+				tabindex: "0",
+				class: "sentinel-start",
+				onFocus: f
+			}, null, 32),
+			a(o.$slots, "default"),
+			r.tabMode === "soft-loop" ? (i(), t("div", s)) : e("", !0),
+			n("div", {
+				tabindex: "0",
+				class: "sentinel-end",
+				onFocus: p
+			}, null, 32)
+		], 512));
 	}
 });
 //#endregion
-//#region \0plugin-vue:export-helper
-var _plugin_vue_export_helper_default = (sfc, props) => {
-	const target = sfc.__vccOpts || sfc;
-	for (const [key, val] of props) target[key] = val;
-	return target;
-};
-//#endregion
-//#region src/components/FocusScope.vue
-var FocusScope_default = /* @__PURE__ */ _plugin_vue_export_helper_default(FocusScope_vue_vue_type_script_setup_true_lang_default, [["__scopeId", "data-v-5ffda61b"]]);
-//#endregion
-//#region src/index.ts
-var src_default = FocusScope_default;
-
-//#endregion
-export { FocusScope_default as FocusScope, src_default as default };
-
-//# sourceMappingURL=index.js.map
+export { c as FocusScope };

package/package.json

@@ -1,22 +1,9 @@
 {
     "name": "@zhencai/vue-focus-scope",
-    "version": "1.0.1",
     "main": "index.js",
-    "types": "index.d.ts",
-    "files": [
-        "index.js",
-        "index.d.ts",
-        "vue-focus-scope.css"
-    ],
-    "keywords": [
-        "vue",
-        "focus",
-        "ui",
-        "component"
-    ],
-    "author": "严硕",
-    "license": "MIT",
+    "version": "1.0.4",
+    "module": "index.js",
     "peerDependencies": {
-        "vue": "^3.2.0"
+        "vue": "^3.0.0"
     }
 }

package/readme.md

@@ -0,0 +1,107 @@
+# 焦点管理组件
+
+一个基于 Vue 3 的焦点循环管理组件。它通过"哨兵节点"（Sentinel Nodes）技术，在指定的 DOM 作用域内实现键盘 Tab 键的无缝循环导航。
+
+适用于模态框（Modal）、下拉菜单、自定义表单或任何需要限制用户焦点范围的场景，符合 WAI-ARIA 无障碍最佳实践。
+
+## 功能特性
+
+- **自动循环导航**
+  - 按 `Tab` 到达最后一个元素时，自动跳回第一个
+  - 按 `Shift + Tab` 到达第一个元素时，自动跳到最后一个
+
+- **智能作用域限制**
+  - 自动过滤不可聚焦元素（`tabindex="-1"`, `disabled`）
+  - 自动忽略被 `<fieldset disabled>` 包裹的元素
+  - 排除内部哨兵节点，防止干扰正常流程
+
+- **双模式支持**
+  - **`loop` (默认)**：强循环模式。焦点被严格限制在组件内部，无法通过 Tab 键移出
+  - **`soft-loop`**：软循环模式。在首尾之间提供缓冲，允许特定的交互逻辑（防止单元素死循环）
+
+- **无障碍友好**：原生支持键盘导航，无需额外配置
+
+## 安装与使用
+
+将组件代码保存为 `FocusLoop.vue`，然后在你的项目中引入。
+
+### 基础用法
+
+```vue
+<template>
+  <FocusLoop>
+    <h3>用户登录</h3>
+    <input type="text" placeholder="用户名" />
+    <input type="password" placeholder="密码" />
+    <button @click="submit">登录</button>
+    <a href="/forgot">忘记密码？</a>
+  </FocusLoop>
+</template>
+
+<script setup lang="ts">
+import FocusLoop from "./components/FocusLoop.vue";
+</script>
+```
+
+### 模式切换
+
+通过 tabMode 属性控制循环行为：
+
+```vue
+<template>
+  <!-- 强循环：焦点永远无法逃出此区域 -->
+  <FocusLoop tab-mode="loop">
+    <!-- 内容 -->
+  </FocusLoop>
+
+  <!-- 软循环：适合只有一个输入框或需要特殊逃逸逻辑的场景 -->
+  <FocusLoop tab-mode="soft-loop">
+    <input type="text" placeholder="唯一输入框" />
+  </FocusLoop>
+</template>
+```
+
+## API 文档
+
+### Props
+
+| 属性名    | 类型                    | 默认值   | 说明                                                                                                            |
+| :-------- | :---------------------- | :------- | :-------------------------------------------------------------------------------------------------------------- |
+| `tabMode` | `'loop' \| 'soft-loop'` | `'loop'` | 循环模式：<br>- `loop`: 严格限制焦点在插槽内<br>- `soft-loop`: 允许一定程度的外部交互，主要用于防止单元素死循环 |
+
+### Slots
+
+| 名称      | 说明                                                     |
+| :-------- | :------------------------------------------------------- |
+| `default` | 放置需要被管理焦点的子元素（如 input, button, a 标签等） |
+
+## 工作原理
+
+该组件利用 **Focus Sentinel（焦点哨兵）** 技术：
+
+### 起始哨兵 (sentinel-start)
+
+- 位于插槽内容之前
+- 当用户按 `Shift + Tab` 从第一个元素回退时，焦点会落在此处
+- 组件拦截该事件，立即将焦点重定向到最后一个可聚焦元素
+
+### 结束哨兵 (sentinel-end)
+
+- 位于插槽内容之后
+- 当用户按 `Tab` 从最后一个元素前进时，焦点会落在此处
+- 组件拦截该事件，立即将焦点重定向到第一个可聚焦元素
+
+### 可聚焦元素检测
+
+- 内部使用 `querySelectorAll` 动态计算当前作用域内的有效焦点元素
+- 自动排除 `tabindex="-1"`、`disabled` 状态以及被禁用的 `fieldset`
+
+## 注意事项
+
+- **子元素要求**：确保插槽内的元素是原生的可聚焦元素（如 `<input>`, `<button>`, `<a href>`）或具有有效的 `tabindex`
+
+- **CSS 样式**：哨兵节点默认带有 `tabindex="0"` 但无视觉样式。如果需要，可以通过 CSS 类 `.sentinel-start` 或 `.sentinel-end` 进行调试（例如添加红色边框），但在生产环境中通常保持隐藏
+
+## 许可证
+
+MIT

package/vue-focus-scope.css

@@ -1,5 +0,0 @@
-
-[data-focus-scope][data-v-5ffda61b]:focus {
-  outline: none;
-}
-/*$vite$:1*/