vue-intercept-plugin 1.0.0

package/README.md

@@ -0,0 +1,293 @@
+# vue-intercept-plugin
+
+[中文](README_ZH.md) | English
+
+A lightweight Vue plugin providing the `v-intercept` custom directive for intercepting DOM events. Defaults to click, with support for any event type via directive arguments.
+
+> The plugin does not handle permission checking — it does one thing: intercepts an event and passes it to your function.
+
+## How It Works
+
+### 🎯 Event Interception Mechanism
+
+1. **Directive Parsing**: Resolves the `v-intercept` value at runtime, supporting both function and array formats
+2. **Auto Binding**: Uses `addEventListener` to bind to the specified event type (default: click)
+3. **Parameter Forwarding**: When using array syntax, the event object is automatically appended as the last argument
+4. **Auto Cleanup**: Removes event listeners via `removeEventListener` on component unmount to prevent memory leaks
+
+### 📋 Directive Format Reference
+
+| Syntax | Description |
+|--------|-------------|
+| `v-intercept="handleFn"` | Pass a function directly. Receives the event object automatically |
+| `v-intercept="[handleFn, arg1, arg2]"` | Array syntax. First item is the function, rest are arguments. **Event object auto-appended to the end** |
+| `v-intercept:change="handleFn"` | Specify event type via directive argument. Defaults to `click` |
+| `v-intercept:change="[handleFn, arg1]"` | Custom event + array arguments, work together |
+
+## Installation
+
+```bash
+npm install vue-intercept-plugin
+```
+
+## Quick Start
+
+```typescript
+import { createApp } from 'vue'
+import VueInterceptPlugin from 'vue-intercept-plugin'
+
+// Register plugin (no configuration needed)
+const app = createApp(App)
+app.use(VueInterceptPlugin)
+```
+
+```typescript
+// Vue 2
+import Vue from 'vue'
+import VueInterceptPlugin from 'vue-intercept-plugin'
+
+Vue.use(VueInterceptPlugin)
+```
+
+```vue
+<template>
+  <!-- No arguments: pass function directly -->
+  <el-button v-intercept="handleDelete" type="danger">Delete</el-button>
+
+  <!-- Array syntax: [function, arg1, arg2, ...] -->
+  <el-button v-intercept="[handleDeleteById, 1001]" type="warning">
+    Delete Order #1001
+  </el-button>
+
+  <!-- Custom event type via directive argument -->
+  <select v-intercept:change="handleChange">
+    <option value="">Select...</option>
+    <option value="1">Option 1</option>
+    <option value="2">Option 2</option>
+  </select>
+</template>
+
+<script setup lang="ts">
+const handleDelete = () => {
+  if (!hasPermission) {
+    ElMessage.warning('No permission')
+    return  // Intercept
+  }
+  // Execute delete logic
+}
+
+const handleDeleteById = (id: number, event: MouseEvent) => {
+  if (!hasPermission) return
+  deleteApi(id)
+}
+
+const handleChange = (event: Event) => {
+  if (!canChange) return
+  const value = (event.target as HTMLSelectElement).value
+  // Handle selection logic
+}
+</script>
+```
+
+## API
+
+### `app.use(VueInterceptPlugin)`
+
+Registers the plugin. No arguments required. Internally auto-detects the Vue version (Vue 3 uses `mounted`/`updated`/`unmounted` hooks; Vue 2 uses `bind`/`update`/`unbind` hooks).
+
+### v-intercept Directive
+
+**Directive Argument (Event Type):**
+
+| Syntax | Description |
+|--------|-------------|
+| `v-intercept="handler"` | Default: click |
+| `v-intercept:click="handler"` | Explicit click |
+| `v-intercept:change="handler"` | change event |
+| `v-intercept:submit="handler"` | Form submit |
+| `v-intercept:contextmenu="handler"` | Right-click menu |
+| `v-intercept:dblclick="handler"` | Double-click |
+| `v-intercept:dragstart="handler"` | Drag start |
+| `v-intercept:copy="handler"` | Copy |
+| `...` | Any native DOM event |
+
+**Directive Value (Handler):**
+
+| Format | Example | Description |
+|--------|---------|-------------|
+| `handler` | `v-intercept="handleDelete"` | Pass function directly. Receives event object |
+| `[handler, ...args]` | `v-intercept="[handleDelete, 1001]"` | Array syntax. **Event object auto-appended to arguments** |
+| `[handler]` | `v-intercept="[handleDelete]"` | Function only, no extra args. Equivalent to passing function directly |
+
+**Function Signature Reference:**
+
+| Template Syntax | Actual Arguments Received |
+|----------------|-------------------------|
+| `v-intercept="handle"` | `handle(event)` |
+| `v-intercept="[handle, id]"` | `handle(id, event)` |
+| `v-intercept="[handle, id, name]"` | `handle(id, name, event)` |
+| `v-intercept:change="handle"` | `handle(event)` |
+| `v-intercept:change="[handle, id]"` | `handle(id, event)` |
+
+## Advanced Usage
+
+### Permission-Guarded Buttons
+
+```vue
+<el-button v-intercept="handleDelete" type="danger">Delete</el-button>
+<el-button v-intercept="[handleApprove, 'order_001']" type="primary">Approve</el-button>
+```
+
+```typescript
+const handleDelete = () => {
+  if (!userHasPermission('delete')) {
+    ElMessage.warning('No permission to delete')
+    return
+  }
+  deleteApi()
+}
+```
+
+### Right-Click Menu Guard
+
+```vue
+<div v-intercept:contextmenu="handleContextMenu" class="table-row">
+  Right-click this area
+</div>
+```
+
+```typescript
+const handleContextMenu = (event: MouseEvent) => {
+  event.preventDefault()
+  if (!hasRightClickPermission) return
+  showContextMenu(event.clientX, event.clientY)
+}
+```
+
+### Select Change Guard
+
+```vue
+<el-select v-intercept:change="[handleRoleChange, 'User Management']" placeholder="Select role">
+  <el-option label="Admin" value="admin" />
+  <el-option label="Editor" value="editor" />
+  <el-option label="Guest" value="guest" />
+</el-select>
+```
+
+```typescript
+const handleRoleChange = (section: string, event: Event) => {
+  if (!canChangeRole) {
+    ElMessage.warning(`Cannot change role for 「${section}」`)
+    return
+  }
+  updateRole()
+}
+```
+
+### Toggle Switch Guard
+
+```vue
+<el-switch v-intercept:change="[handleFeatureToggle, 'Export']" />
+```
+
+```typescript
+const handleFeatureToggle = (feature: string, event: Event) => {
+  const checked = (event.target as HTMLInputElement).checked
+  if (checked && !canEnableFeature(feature)) {
+    ElMessage.warning(`Cannot enable 「${feature}」`)
+    return
+  }
+  toggleFeature(feature, checked)
+}
+```
+
+### Double-Click Edit Guard
+
+```vue
+<div v-intercept:dblclick="[handleDoubleClick, item.id]">
+  {{ item.name }}
+</div>
+```
+
+```typescript
+const handleDoubleClick = (id: number, event: MouseEvent) => {
+  if (!canEdit) return
+  enterEditMode(id)
+}
+```
+
+### Drag Guard
+
+```vue
+<div v-intercept:dragstart="[handleDragStart, file.name]" draggable="true">
+  {{ file.name }}
+</div>
+```
+
+```typescript
+const handleDragStart = (fileName: string, event: DragEvent) => {
+  if (!canDrag) {
+    event.preventDefault()
+    return
+  }
+  event.dataTransfer?.setData('text/plain', fileName)
+}
+```
+
+## Build Artifacts
+
+| File | Format | Description |
+|------|--------|-------------|
+| `dist/vue-intercept-plugin.cjs.js` | CJS | CommonJS for Node.js require |
+| `dist/vue-intercept-plugin.esm.js` | ESM | ES Module, Tree-shakable |
+
+## Technical Details
+
+### Why Not Wrap Components?
+
+When using third-party UI libraries like Element Plus, wrapping every permission-sensitive component (e.g., `PermissionButton`) leads to:
+- High wrapping cost — requires handling extensive prop forwarding
+- Poor coverage — hard to cover all UI components that need permission control (buttons, selects, switches, etc.)
+- Duplicated effort — different UI libraries need separate wrappers
+
+Vue custom directives operate directly on native DOM events — zero component wrapping, one line of code.
+
+### Vue 2 / Vue 3 Compatibility
+
+The plugin auto-detects the Vue version via `app.version` and selects the appropriate directive hooks:
+
+| Vue Version | Bind Hook | Update Hook | Unbind Hook |
+|-------------|-----------|-------------|-------------|
+| Vue 3 | `mounted` | `updated` | `unmounted` |
+| Vue 2 | `bind` | `update` | `unbind` |
+
+### Memory Safety
+
+- Old listeners are removed before re-binding to prevent duplicate handlers
+- Listeners are automatically removed on component unmount, references are cleaned up
+- Different event types use separate storage keys (`_intcpt_click` / `_intcpt_change`), keeping them isolated
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+```
+
+## Testing
+
+Uses Vitest + jsdom with 28 test cases covering:
+
+- `resolveHandler` — direct function passthrough, array argument forwarding with event auto-append, multiple arguments, invalid value warnings, null/undefined edge cases
+- `bindHandler / unbindHandler` — click binding, change binding, auto-replacement on re-bind, unbind cleanup, event type isolation, contextmenu/dblclick special events
+- Plugin install — Vue3/Vue2 directive registration, correct hook names, mounted event binding, custom event types, array arguments with event auto-append, unmounted cleanup, graceful handling of invalid values
+
+## License
+
+MIT

package/dist/__tests__/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 解析指令值，生成实际的事件处理函数
+ * 支持两种格式：
+ *   1. 函数：v-intercept="handleDelete"
+ *   2. 数组：v-intercept="[handleDelete, 1001]"
+ */
+declare function resolveHandler(value: unknown): EventListener | null;
+/**
+ * 在元素上绑定事件
+ */
+declare function bindHandler(el: HTMLElement, eventType: string, handler: EventListener): void;
+/**
+ * 移除元素上的事件监听
+ */
+declare function unbindHandler(el: HTMLElement, eventType: string): void;
+/**
+ * Vue 事件拦截插件
+ *
+ * 提供 v-intercept 自定义指令，用于拦截事件。
+ * 默认拦截 click 事件，可通过指令参数指定其他事件类型。
+ * 开发者在使用时，在函数内部自行判断权限并决定是否放行。
+ */
+declare const VueInterceptPlugin: {
+    install(app: any): void;
+};
+export default VueInterceptPlugin;
+export { resolveHandler, bindHandler, unbindHandler };

package/dist/vue-intercept-plugin.cjs.js

@@ -0,0 +1,115 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+/**
+ * 用 WeakMap 存储元素 → 事件类型 → 监听函数的映射
+ * 避免在 DOM 元素上挂载自定义属性（el._intcpt_xxx）
+ */
+const handlerMap = new WeakMap();
+/**
+ * 获取元素上指定事件类型的监听函数
+ */
+function getHandler(el, eventType) {
+    var _a;
+    return (_a = handlerMap.get(el)) === null || _a === void 0 ? void 0 : _a.get(eventType);
+}
+/**
+ * 设置元素上指定事件类型的监听函数
+ */
+function setHandler(el, eventType, handler) {
+    let typeMap = handlerMap.get(el);
+    if (!typeMap) {
+        typeMap = new Map();
+        handlerMap.set(el, typeMap);
+    }
+    typeMap.set(eventType, handler);
+}
+/**
+ * 删除元素上指定事件类型的监听函数
+ */
+function deleteHandler(el, eventType) {
+    var _a, _b;
+    (_a = handlerMap.get(el)) === null || _a === void 0 ? void 0 : _a.delete(eventType);
+    if (((_b = handlerMap.get(el)) === null || _b === void 0 ? void 0 : _b.size) === 0) {
+        handlerMap.delete(el);
+    }
+}
+/**
+ * 解析指令值，生成实际的事件处理函数
+ * 支持两种格式：
+ *   1. 函数：v-intercept="handleDelete"
+ *   2. 数组：v-intercept="[handleDelete, 1001]"
+ */
+function resolveHandler(value) {
+    if (typeof value === 'function') {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        const [fn, ...args] = value;
+        if (typeof fn !== 'function') {
+            console.warn('[vue-intercept-plugin] 数组第一项必须是一个函数');
+            return null;
+        }
+        return (event) => { fn(...args, event); };
+    }
+    console.warn('[vue-intercept-plugin] v-intercept 的值必须是函数或 [函数, ...参数] 数组');
+    return null;
+}
+/**
+ * 在元素上绑定事件
+ */
+function bindHandler(el, eventType, handler) {
+    const oldHandler = getHandler(el, eventType);
+    if (oldHandler) {
+        el.removeEventListener(eventType, oldHandler);
+    }
+    el.addEventListener(eventType, handler);
+    setHandler(el, eventType, handler);
+}
+/**
+ * 移除元素上的事件监听
+ */
+function unbindHandler(el, eventType) {
+    const handler = getHandler(el, eventType);
+    if (handler) {
+        el.removeEventListener(eventType, handler);
+        deleteHandler(el, eventType);
+    }
+}
+/**
+ * Vue 事件拦截插件
+ *
+ * 提供 v-intercept 自定义指令，用于拦截事件。
+ * 默认拦截 click 事件，可通过指令参数指定其他事件类型。
+ * 开发者在使用时，在函数内部自行判断权限并决定是否放行。
+ */
+const VueInterceptPlugin = {
+    install(app) {
+        // SSR 安全：非浏览器环境直接跳过
+        if (typeof window === 'undefined') {
+            return;
+        }
+        const isVue3 = typeof app.version === 'string';
+        function bind(el, binding) {
+            const handler = resolveHandler(binding.value);
+            if (!handler)
+                return;
+            const eventType = binding.arg || 'click';
+            bindHandler(el, eventType, handler);
+        }
+        function unbind(el, binding) {
+            const eventType = binding.arg || 'click';
+            unbindHandler(el, eventType);
+        }
+        const directive = isVue3
+            ? { mounted: bind, updated: bind, unmounted: unbind }
+            : { bind, update: bind, unbind };
+        app.directive('intercept', directive);
+    },
+};
+
+exports.bindHandler = bindHandler;
+exports.default = VueInterceptPlugin;
+exports.resolveHandler = resolveHandler;
+exports.unbindHandler = unbindHandler;

package/dist/vue-intercept-plugin.esm.js

@@ -0,0 +1,108 @@
+/**
+ * 用 WeakMap 存储元素 → 事件类型 → 监听函数的映射
+ * 避免在 DOM 元素上挂载自定义属性（el._intcpt_xxx）
+ */
+const handlerMap = new WeakMap();
+/**
+ * 获取元素上指定事件类型的监听函数
+ */
+function getHandler(el, eventType) {
+    var _a;
+    return (_a = handlerMap.get(el)) === null || _a === void 0 ? void 0 : _a.get(eventType);
+}
+/**
+ * 设置元素上指定事件类型的监听函数
+ */
+function setHandler(el, eventType, handler) {
+    let typeMap = handlerMap.get(el);
+    if (!typeMap) {
+        typeMap = new Map();
+        handlerMap.set(el, typeMap);
+    }
+    typeMap.set(eventType, handler);
+}
+/**
+ * 删除元素上指定事件类型的监听函数
+ */
+function deleteHandler(el, eventType) {
+    var _a, _b;
+    (_a = handlerMap.get(el)) === null || _a === void 0 ? void 0 : _a.delete(eventType);
+    if (((_b = handlerMap.get(el)) === null || _b === void 0 ? void 0 : _b.size) === 0) {
+        handlerMap.delete(el);
+    }
+}
+/**
+ * 解析指令值，生成实际的事件处理函数
+ * 支持两种格式：
+ *   1. 函数：v-intercept="handleDelete"
+ *   2. 数组：v-intercept="[handleDelete, 1001]"
+ */
+function resolveHandler(value) {
+    if (typeof value === 'function') {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        const [fn, ...args] = value;
+        if (typeof fn !== 'function') {
+            console.warn('[vue-intercept-plugin] 数组第一项必须是一个函数');
+            return null;
+        }
+        return (event) => { fn(...args, event); };
+    }
+    console.warn('[vue-intercept-plugin] v-intercept 的值必须是函数或 [函数, ...参数] 数组');
+    return null;
+}
+/**
+ * 在元素上绑定事件
+ */
+function bindHandler(el, eventType, handler) {
+    const oldHandler = getHandler(el, eventType);
+    if (oldHandler) {
+        el.removeEventListener(eventType, oldHandler);
+    }
+    el.addEventListener(eventType, handler);
+    setHandler(el, eventType, handler);
+}
+/**
+ * 移除元素上的事件监听
+ */
+function unbindHandler(el, eventType) {
+    const handler = getHandler(el, eventType);
+    if (handler) {
+        el.removeEventListener(eventType, handler);
+        deleteHandler(el, eventType);
+    }
+}
+/**
+ * Vue 事件拦截插件
+ *
+ * 提供 v-intercept 自定义指令，用于拦截事件。
+ * 默认拦截 click 事件，可通过指令参数指定其他事件类型。
+ * 开发者在使用时，在函数内部自行判断权限并决定是否放行。
+ */
+const VueInterceptPlugin = {
+    install(app) {
+        // SSR 安全：非浏览器环境直接跳过
+        if (typeof window === 'undefined') {
+            return;
+        }
+        const isVue3 = typeof app.version === 'string';
+        function bind(el, binding) {
+            const handler = resolveHandler(binding.value);
+            if (!handler)
+                return;
+            const eventType = binding.arg || 'click';
+            bindHandler(el, eventType, handler);
+        }
+        function unbind(el, binding) {
+            const eventType = binding.arg || 'click';
+            unbindHandler(el, eventType);
+        }
+        const directive = isVue3
+            ? { mounted: bind, updated: bind, unmounted: unbind }
+            : { bind, update: bind, unbind };
+        app.directive('intercept', directive);
+    },
+};
+
+export { bindHandler, VueInterceptPlugin as default, resolveHandler, unbindHandler };

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "vue-intercept-plugin",
+  "version": "1.0.0",
+  "description": "v-intercept 自定义指令，纯点击拦截，兼容 Vue 2 & Vue 3。",
+  "main": "dist/vue-intercept-plugin.cjs.js",
+  "module": "dist/vue-intercept-plugin.esm.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rollup -c rollup.config.mjs",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "vue",
+    "vue2",
+    "vue3",
+    "intercept",
+    "directive",
+    "plugin"
+  ],
+  "sideEffects": false,
+  "homepage": "https://github.com/wangkai000/vue-intercept-plugin",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wangkai000/vue-intercept-plugin.git"
+  },
+  "author": "wangkai000",
+  "license": "MIT",
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^25.0.0",
+    "@rollup/plugin-node-resolve": "^15.0.0",
+    "@rollup/plugin-typescript": "^11.0.0",
+    "jsdom": "^29.1.1",
+    "rollup": "^4.0.0",
+    "tslib": "^2.6.0",
+    "typescript": "^5.3.0",
+    "vitest": "^4.1.6"
+  }
+}