vue-intercept-plugin 1.0.0 → 1.0.1

package/README.md

@@ -1,28 +1,39 @@
 # vue-intercept-plugin
 
-[中文](README_ZH.md) | English
+<div align="center">
 
-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.
+[中文](README_ZH.md) | **English**
 
-> The plugin does not handle permission checking — it does one thing: intercepts an event and passes it to your function.
+**Intercept DOM events with a single directive — clean and non-intrusive.**
 
-## How It Works
+> The plugin does **one thing only**: it catches an event and calls your function. Permission checking, validation, or any interception logic? That's entirely up to you.
 
-### 🎯 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
+</div>
+
+---
+
+## The Problem
+
+You have a delete button. You want to check permissions before allowing the delete. The typical approach is:
+
+```html
+<el-button @click="handleDelete">Delete</el-button>
+```
+
+```js
+const handleDelete = () => {
+  if (!checkPermission('delete')) {
+    ElMessage.warning('No permission')
+    return
+  }
+  deleteApi()
+}
+```
 
-### 📋 Directive Format Reference
+What if there are dozens of buttons, selects, and switches across your app? You end up repeating permission checks everywhere. This plugin lets you **signal visually** which actions need interception, and keeps your handler logic clean.
 
-| 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
 
@@ -30,18 +41,18 @@ A lightweight Vue plugin providing the `v-intercept` custom directive for interc
 npm install vue-intercept-plugin
 ```
 
-## Quick Start
+## Register the Plugin
 
-```typescript
+```ts
+// Vue 3
 import { createApp } from 'vue'
 import VueInterceptPlugin from 'vue-intercept-plugin'
 
-// Register plugin (no configuration needed)
 const app = createApp(App)
 app.use(VueInterceptPlugin)
 ```
 
-```typescript
+```ts
 // Vue 2
 import Vue from 'vue'
 import VueInterceptPlugin from 'vue-intercept-plugin'
@@ -49,17 +60,25 @@ import VueInterceptPlugin from 'vue-intercept-plugin'
 Vue.use(VueInterceptPlugin)
 ```
 
-```vue
+That's it. No configuration needed.
+
+---
+
+## Quick Start
+
+Here's a complete example with both template and script:
+
+```html
 <template>
-  <!-- No arguments: pass function directly -->
+  <!-- ① Direct function: intercepts click by default -->
   <el-button v-intercept="handleDelete" type="danger">Delete</el-button>
 
-  <!-- Array syntax: [function, arg1, arg2, ...] -->
+  <!-- ② Array syntax: extra arguments, event auto-appended -->
   <el-button v-intercept="[handleDeleteById, 1001]" type="warning">
     Delete Order #1001
   </el-button>
 
-  <!-- Custom event type via directive argument -->
+  <!-- ③ Custom event type: intercepts "change" instead of "click" -->
   <select v-intercept:change="handleChange">
     <option value="">Select...</option>
     <option value="1">Option 1</option>
@@ -68,95 +87,126 @@ Vue.use(VueInterceptPlugin)
 </template>
 
 <script setup lang="ts">
-const handleDelete = () => {
-  if (!hasPermission) {
+// ① Called as: handleDelete(event)
+// You check permission inside — if not allowed, just return
+const handleDelete = (event: MouseEvent) => {
+  if (!checkPermission('delete')) {
     ElMessage.warning('No permission')
-    return  // Intercept
+    return   // ← intercepted
   }
-  // Execute delete logic
+  deleteApi()
 }
 
+// ② Called as: handleDeleteById(1001, event)
+// The plugin appends the event object as the last argument automatically
 const handleDeleteById = (id: number, event: MouseEvent) => {
-  if (!hasPermission) return
+  if (!checkPermission('delete')) return
   deleteApi(id)
 }
 
+// ③ Called as: handleChange(event)
 const handleChange = (event: Event) => {
-  if (!canChange) return
+  if (!checkPermission('change')) return
   const value = (event.target as HTMLSelectElement).value
-  // Handle selection logic
+  // handle selection...
 }
 </script>
 ```
 
-## API
+> **Key idea**: The plugin does not block anything. It simply calls your function. **You** decide whether to proceed or return early.
 
-### `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).
+## Directive Syntax Reference
 
-### v-intercept Directive
+### Event Type (default: `click`)
 
-**Directive Argument (Event Type):**
+| Syntax | Fires on |
+|--------|----------|
+| `v-intercept="handler"` | `click` (default) |
+| `v-intercept:click="handler"` | click |
+| `v-intercept:change="handler"` | change |
+| `v-intercept:submit="handler"` | form submit |
+| `v-intercept:contextmenu="handler"` | right-click |
+| `v-intercept:dblclick="handler"` | double-click |
+| `v-intercept:dragstart="handler"` | drag start |
+| `v-intercept:copy="handler"` | copy |
+| `v-intercept:<any-event>="handler"` | any native DOM event |
 
-| 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 |
+### Handler Value
 
-**Directive Value (Handler):**
+| Format | Example | Your function receives |
+|--------|---------|----------------------|
+| `handler` | `v-intercept="handleDelete"` | `handleDelete(event)` |
+| `[handler, ...args]` | `v-intercept="[handleDelete, 1001]"` | `handleDelete(1001, event)` |
+| `[handler, ...args]` | `v-intercept="[handleDelete, 1001, 'abc']"` | `handleDelete(1001, 'abc', event)` |
+| `[handler]` | `v-intercept="[handleDelete]"` | `handleDelete(event)` (same as direct) |
 
-| 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 |
+> **Rule**: The event object is **always appended as the last argument** when using array syntax.
 
-**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)` |
+## Common Scenarios
 
-## Advanced Usage
+> Examples below use **Element Plus** components (`el-button`, `el-select`, `el-switch`, etc.). This plugin has no UI library dependency — native `<button>`, `<select>`, etc. work just as well.
 
-### Permission-Guarded Buttons
+### Permission-Guarded Button
 
-```vue
-<el-button v-intercept="handleDelete" type="danger">Delete</el-button>
-<el-button v-intercept="[handleApprove, 'order_001']" type="primary">Approve</el-button>
+```html
+<!-- Element Plus component -->
+<el-button v-intercept="handleApprove" type="primary">Approve</el-button>
 ```
 
-```typescript
-const handleDelete = () => {
-  if (!userHasPermission('delete')) {
-    ElMessage.warning('No permission to delete')
+```ts
+const handleApprove = (event: MouseEvent) => {
+  if (!userHasRole('admin')) {
+    ElMessage.warning('Admins only')
     return
   }
-  deleteApi()
+  approveApi()
+}
+```
+
+### Permission-Guarded Button with Extra Params
+
+```html
+<el-button v-intercept="[handleApproveById, orderId]" type="primary">
+  Approve
+</el-button>
+<!-- Element Plus component, same as above -->
+```
+
+```ts
+const handleApproveById = (id: string, event: MouseEvent) => {
+  if (!userHasRole('admin')) return
+  approveApi(id)
+}
+```
+
+### Double-Click Edit Guard
+
+```html
+<div v-intercept:dblclick="[handleEdit, item.id]">
+  {{ item.name }}
+</div>
+```
+
+```ts
+const handleEdit = (id: number, event: MouseEvent) => {
+  if (!canEdit) return
+  enterEditMode(id)
 }
 ```
 
 ### Right-Click Menu Guard
 
-```vue
-<div v-intercept:contextmenu="handleContextMenu" class="table-row">
-  Right-click this area
+```html
+<div v-intercept:contextmenu="handleContextMenu">
+  Right-click here
 </div>
 ```
 
-```typescript
+```ts
 const handleContextMenu = (event: MouseEvent) => {
   event.preventDefault()
   if (!hasRightClickPermission) return
@@ -166,18 +216,18 @@ const handleContextMenu = (event: MouseEvent) => {
 
 ### Select Change Guard
 
-```vue
-<el-select v-intercept:change="[handleRoleChange, 'User Management']" placeholder="Select role">
+```html
+<!-- Element Plus components -->
+<el-select v-intercept:change="[handleRoleChange, 'User Mgmt']">
   <el-option label="Admin" value="admin" />
   <el-option label="Editor" value="editor" />
-  <el-option label="Guest" value="guest" />
 </el-select>
 ```
 
-```typescript
+```ts
 const handleRoleChange = (section: string, event: Event) => {
   if (!canChangeRole) {
-    ElMessage.warning(`Cannot change role for 「${section}」`)
+    ElMessage.warning(`Cannot change role for ${section}`)
     return
   }
   updateRole()
@@ -186,108 +236,76 @@ const handleRoleChange = (section: string, event: Event) => {
 
 ### Toggle Switch Guard
 
-```vue
-<el-switch v-intercept:change="[handleFeatureToggle, 'Export']" />
+```html
+<!-- Element Plus component -->
+<el-switch v-intercept:change="[handleToggle, 'Export']" />
 ```
 
-```typescript
-const handleFeatureToggle = (feature: string, event: Event) => {
+```ts
+const handleToggle = (feature: string, event: Event) => {
   const checked = (event.target as HTMLInputElement).checked
   if (checked && !canEnableFeature(feature)) {
-    ElMessage.warning(`Cannot enable 「${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">
+```html
+<div v-intercept:dragstart="[handleDrag, file.name]" draggable="true">
   {{ file.name }}
 </div>
 ```
 
-```typescript
-const handleDragStart = (fileName: string, event: DragEvent) => {
+```ts
+const handleDrag = (name: string, event: DragEvent) => {
   if (!canDrag) {
     event.preventDefault()
     return
   }
-  event.dataTransfer?.setData('text/plain', fileName)
+  event.dataTransfer?.setData('text/plain', name)
 }
 ```
 
-## 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?
+### Why a Directive, Not a Wrapper Component?
 
-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
+If you wrap `el-button` into a `<PermissionButton>`, you have to:
+- Forward every prop (size, type, icon, loading, disabled, ...)
+- Do the same for `<el-select>`, `<el-switch>`, `<el-input>`, etc.
+- Repeat the work for every UI library
 
-Vue custom directives operate directly on native DOM events — zero component wrapping, one line of code.
+A **Vue custom directive** hooks directly into the native DOM event — zero wrapping, one line of code.
 
-### Vue 2 / Vue 3 Compatibility
+### Vue 2 / Vue 3 Auto-Detection
 
-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 | 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
+- Old listeners are removed before re-binding (prevents duplicates)
+- Listeners are cleaned up on component unmount
+- Different event types use separate storage (isolated, no collisions)
 
-# Build
-npm run build
+---
 
-# Run tests
-npm test
-```
-
-## Testing
+## Build Artifacts
 
-Uses Vitest + jsdom with 28 test cases covering:
+| File | Format |
+|------|--------|
+| `dist/vue-intercept-plugin.cjs.js` | CommonJS |
+| `dist/vue-intercept-plugin.esm.js` | ES Module (tree-shakable) |
 
-- `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
+MIT

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vue-intercept-plugin",
-  "version": "1.0.0",
-  "description": "v-intercept 自定义指令，纯点击拦截，兼容 Vue 2 & Vue 3。",
+  "version": "1.0.1",
+  "description": "A lightweight Vue plugin providing v-intercept custom directive — intercept DOM events with a single line of code, supports any event type, compatible with Vue 2 & Vue 3.",
   "main": "dist/vue-intercept-plugin.cjs.js",
   "module": "dist/vue-intercept-plugin.esm.js",
   "files": [