@zhencai/vue-focus-scope 1.0.3 → 1.0.5

package/index.d.ts

@@ -0,0 +1,8 @@
+import { DefineComponent } from 'vue';
+
+declare const FocusScope: DefineComponent<{
+    tabMode?: 'loop' | 'soft-loop';
+}>;
+
+export { FocusScope };
+

package/index.js

@@ -9,23 +9,21 @@ var s = {
 	setup(r) {
 		let c = o("wrapper");
 		function l(e) {
-			if (!e) return [];
-			let t = 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) => {
+			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;
 				}
 				return !0;
-			});
-			return console.log("当前可聚焦元素：", t), t;
+			}) : [];
 		}
 		function u() {
 			try {
 				if (c.value) {
 					let e = l(c.value);
 					if (e.length === 0) return;
-					console.log("执行聚焦第一个：", e[0]), e[0].focus();
+					e[0].focus();
 				}
 			} catch (e) {
 				console.error("focusFirst error:", e);

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@zhencai/vue-focus-scope",
     "main": "index.js",
-    "version": "1.0.3",
+    "version": "1.0.5",
     "module": "index.js",
     "peerDependencies": {
         "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`**：软循环模式。在首尾之间提供缓冲，允许特定的交互逻辑（防止单元素死循环）
+
+- **无障碍友好**：原生支持键盘导航，无需额外配置
+
+## 安装与使用
+
+```vue
+npm install @zhencai/vue-focus-scope
+```
+
+### 基础用法
+
+```vue
+<template>
+  <FocusScope>
+    <h3>用户登录</h3>
+    <input type="text" placeholder="用户名" />
+    <input type="password" placeholder="密码" />
+    <button @click="submit">登录</button>
+    <a href="/forgot">忘记密码？</a>
+  </FocusScope>
+</template>
+
+<script setup lang="ts">
+import FocusScope from "@zhencai/vue-focus-scope";
+</script>
+```
+
+### 模式切换
+
+通过 tabMode 属性控制循环行为：
+
+```vue
+<template>
+  <!-- 强循环：焦点永远无法逃出此区域 -->
+  <FocusScope tab-mode="loop">
+    <!-- 内容 -->
+  </FocusScope>
+
+  <!-- 软循环：适合只有一个输入框或需要特殊逃逸逻辑的场景 -->
+  <FocusScope tab-mode="soft-loop">
+    <input type="text" placeholder="唯一输入框" />
+  </FocusScope>
+</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`
+
+## 许可证
+
+MIT