vuse-directive 0.0.3

package/README.md

@@ -0,0 +1,114 @@
+# vue-directive
+
+A collection of Vue 3 custom directives
+
+## Installation
+
+```bash
+npm install vuse-directive
+# or
+pnpm add vuse-directive
+# or
+yarn add vuse-directive
+```
+
+## Getting Started
+
+### Global Registration
+
+```ts
+import { createApp } from 'vue'
+import App from './App.vue'
+import { throttleClick } from 'vuse-directive'
+
+const app = createApp(App)
+app.directive('throttle-click', throttleClick)
+app.mount('#app')
+```
+
+### On-demand Import
+
+```ts
+import { throttleClick } from 'vuse-directive'
+```
+
+---
+
+## Directives
+
+### `v-throttle-click` — Throttled Click
+
+Throttles click events to prevent repeated triggers within a short period. Supports custom delay, async lock, trailing call, and Vue modifier pass-through.
+
+#### Basic Usage
+
+```vue
+<!-- Default throttle interval: 300ms -->
+<button v-throttle-click="handleClick">Submit</button>
+
+<!-- Custom interval (in ms) -->
+<button v-throttle-click:500="handleClick">Submit</button>
+
+<!-- Interval 0: no throttle, modifiers still apply -->
+<button v-throttle-click:0="handleClick">Submit</button>
+```
+
+#### Modifiers
+
+| Modifier | Description |
+|----------|-------------|
+| `.once` | Fire only once; all subsequent clicks are ignored |
+| `.trailing` | If a click is blocked during cooldown, it fires once after the cooldown ends |
+| `.async` | Async mode: new clicks are blocked until the previous callback's Promise resolves/rejects |
+| `.right` | Listen to `contextmenu` (right-click) instead of `click` |
+| `.capture` | Use capture phase for the event listener |
+| `.passive` | Use passive listener mode for better scroll performance |
+| `.stop` | Stop event propagation (passed to Vue's `withModifiers`) |
+| `.prevent` | Prevent default behavior (passed to Vue's `withModifiers`) |
+| `.self` | Only trigger when the event target is the element itself |
+
+#### Examples
+
+```vue
+<script setup lang="ts">
+async function submitForm() {
+  await fetch('/api/submit', { method: 'POST' })
+}
+</script>
+
+<template>
+  <!-- Async + trailing: blocks repeated clicks during async call,
+       fires the last blocked click after the call completes -->
+  <button v-throttle-click:1000.async.trailing="submitForm">
+    Submit
+  </button>
+
+  <!-- Fire once only -->
+  <button v-throttle-click.once="handleClick">Click once</button>
+
+  <!-- Throttle right-click -->
+  <div v-throttle-click.right="openMenu">Right-click area</div>
+</template>
+```
+
+#### Callback Signature
+
+```ts
+type ClickHandler = (event: MouseEvent, ...args: unknown[]) => any
+```
+
+The binding value receives a `MouseEvent` as the first argument:
+
+```ts
+function handleClick(e: MouseEvent) {
+  console.log('clicked', e)
+}
+```
+
+In async mode, return a `Promise` to activate the async lock:
+
+```ts
+async function handleAsync(e: MouseEvent) {
+  await fetch('/api/submit', { method: 'POST' })
+}
+```

package/dist/directives/ThrottleClick.d.ts

@@ -0,0 +1,4 @@
+import { Directive } from 'vue';
+
+declare const throttleClick: Directive;
+export default throttleClick;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import { default as throttleClick } from './directives/ThrottleClick';
+
+export { throttleClick };

package/dist/vue-directive.js

@@ -0,0 +1,63 @@
+import { withModifiers as d } from "vue";
+const f = {
+  mounted(t, e) {
+    t._latestBinding = e, t._throttleTimer = null, t._hasCalledOnce = !1, t._trailingEvent = null, t._asyncPending = !1, t._unmounted = !1;
+    const s = Object.getOwnPropertyNames(
+      e.modifiers
+    );
+    t._throttleHandler = d((i) => {
+      const { modifiers: n, value: r } = t._latestBinding;
+      if (n.once && t._hasCalledOnce)
+        return;
+      if (n.async && t._asyncPending) {
+        n.trailing && (t._trailingEvent = i);
+        return;
+      }
+      const a = typeof t._latestBinding.arg > "u" ? 300 : Number(t._latestBinding.arg);
+      if (a > 0 && t._throttleTimer) {
+        n.trailing && (t._trailingEvent = i);
+        return;
+      }
+      const o = (_) => {
+        t._hasCalledOnce = !0, t._trailingEvent = null, n.async ? (t._asyncPending = !0, Promise.resolve(r == null ? void 0 : r(_)).finally(() => {
+          t._unmounted || (t._asyncPending = !1, n.trailing && t._trailingEvent && t._throttleHandler(t._trailingEvent));
+        })) : r == null || r(_);
+      };
+      if (a === 0) {
+        o(i);
+        return;
+      }
+      o(i), t._throttleTimer = setTimeout(() => {
+        t._throttleTimer = null, !n.async && n.trailing && t._trailingEvent && (t._throttleHandler(t._trailingEvent), t._trailingEvent = null);
+      }, a);
+    }, s), t._eventName = e.modifiers.right ? "contextmenu" : "click", t._listenerOptions = {
+      capture: e.modifiers.capture ?? !1,
+      passive: e.modifiers.passive ?? !1
+    }, t.addEventListener(
+      t._eventName,
+      t._throttleHandler,
+      t._listenerOptions
+    );
+  },
+  updated(t, e) {
+    const s = e.modifiers.capture ?? !1, i = e.modifiers.passive ?? !1, n = t._listenerOptions;
+    (s !== n.capture || i !== n.passive) && (t.removeEventListener(t._eventName, t._throttleHandler, n), t._listenerOptions = {
+      capture: s,
+      passive: i
+    }, t.addEventListener(
+      t._eventName,
+      t._throttleHandler,
+      t._listenerOptions
+    )), t._latestBinding = e;
+  },
+  unmounted(t) {
+    t.removeEventListener(
+      t._eventName,
+      t._throttleHandler,
+      t._listenerOptions
+    ), t._throttleTimer && clearTimeout(t._throttleTimer), t._unmounted = !0, t._trailingEvent = null;
+  }
+};
+export {
+  f as throttleClick
+};

package/dist/vue-directive.umd.cjs

@@ -0,0 +1 @@
+(function(i,a){typeof exports=="object"&&typeof module<"u"?a(exports,require("vue")):typeof define=="function"&&define.amd?define(["exports","vue"],a):(i=typeof globalThis<"u"?globalThis:i||self,a(i.VueDirective={},i.Vue))})(this,function(i,a){"use strict";const f={mounted(t,n){t._latestBinding=n,t._throttleTimer=null,t._hasCalledOnce=!1,t._trailingEvent=null,t._asyncPending=!1,t._unmounted=!1;const o=Object.getOwnPropertyNames(n.modifiers);t._throttleHandler=a.withModifiers(r=>{const{modifiers:e,value:s}=t._latestBinding;if(e.once&&t._hasCalledOnce)return;if(e.async&&t._asyncPending){e.trailing&&(t._trailingEvent=r);return}const d=typeof t._latestBinding.arg>"u"?300:Number(t._latestBinding.arg);if(d>0&&t._throttleTimer){e.trailing&&(t._trailingEvent=r);return}const _=u=>{t._hasCalledOnce=!0,t._trailingEvent=null,e.async?(t._asyncPending=!0,Promise.resolve(s==null?void 0:s(u)).finally(()=>{t._unmounted||(t._asyncPending=!1,e.trailing&&t._trailingEvent&&t._throttleHandler(t._trailingEvent))})):s==null||s(u)};if(d===0){_(r);return}_(r),t._throttleTimer=setTimeout(()=>{t._throttleTimer=null,!e.async&&e.trailing&&t._trailingEvent&&(t._throttleHandler(t._trailingEvent),t._trailingEvent=null)},d)},o),t._eventName=n.modifiers.right?"contextmenu":"click",t._listenerOptions={capture:n.modifiers.capture??!1,passive:n.modifiers.passive??!1},t.addEventListener(t._eventName,t._throttleHandler,t._listenerOptions)},updated(t,n){const o=n.modifiers.capture??!1,r=n.modifiers.passive??!1,e=t._listenerOptions;(o!==e.capture||r!==e.passive)&&(t.removeEventListener(t._eventName,t._throttleHandler,e),t._listenerOptions={capture:o,passive:r},t.addEventListener(t._eventName,t._throttleHandler,t._listenerOptions)),t._latestBinding=n},unmounted(t){t.removeEventListener(t._eventName,t._throttleHandler,t._listenerOptions),t._throttleTimer&&clearTimeout(t._throttleTimer),t._unmounted=!0,t._trailingEvent=null}};i.throttleClick=f,Object.defineProperty(i,Symbol.toStringTag,{value:"Module"})});

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "vuse-directive",
+  "version": "0.0.3",
+  "description": "Vue 3 directives collection",
+  "type": "module",
+  "main": "./dist/vue-directive.umd.cjs",
+  "module": "./dist/vue-directive.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/vue-directive.js",
+      "require": "./dist/vue-directive.umd.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "test": "jest",
+    "build": "vite build",
+    "dev": "vite",
+    "format": "biome format --write .",
+    "format:check": "biome format .",
+    "prepublishOnly": "npm run build",
+    "release": "node scripts/publish.js"
+  },
+  "peerDependencies": {
+    "vue": "^3.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.0.0",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25.3.0",
+    "@vue/test-utils": "^2.4.6",
+    "jest": "^30.2.0",
+    "jest-environment-jsdom": "^30.2.0",
+    "ts-jest": "^29.4.6",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.3",
+    "vite": "^5.0.0",
+    "vite-plugin-dts": "^3.6.0",
+    "vue": "^3.4.0",
+    "vue-tsc": "^1.8.0"
+  },
+  "keywords": [
+    "vue",
+    "vue3",
+    "directive",
+    "directives"
+  ],
+  "sideEffects": false,
+  "author": "Stafan Hulk",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/stafanhulk/vue-directive.git"
+  },
+  "homepage": "https://github.com/stafanhulk/vue-directive#readme",
+  "bugs": {
+    "url": "https://github.com/stafanhulk/vue-directive/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}