{"_id":"@amirafa/xevent","_rev":"7-8e4ea0ce05a8803b2576a01b4d2dfeb9","name":"@amirafa/xevent","dist-tags":{"latest":"1.0.3"},"versions":{"1.0.1":{"name":"@amirafa/xevent","version":"1.0.1","keywords":["events","dom-events","custom-events","event-listener","dom-utils","typescript","xevent"],"author":{"name":"Amirafa","email":"amir.h.rafati@gmail.com"},"license":"MIT","_id":"@amirafa/xevent@1.0.1","maintainers":[{"name":"amirafa","email":"amir.h.rafati@gmail.com"}],"dist":{"shasum":"88a06dc2b0e80d8a96f6413642f9a1f24af2206c","tarball":"https://registry.npmjs.org/@amirafa/xevent/-/xevent-1.0.1.tgz","fileCount":10,"integrity":"sha512-EgH4lmGyBoyK30THtcA6uOqB+rszyAtJChx+zFcb2jPpZsh91snKX2trAc1s9TPLGgMwXo+X6D6yXdqsVlesyw==","signatures":[{"sig":"MEYCIQCL8D9JCK38qBVVwTJnMpqr/5qkcUG/VA/0XP6jocFimAIhAMeYKhHSlsL/fFqxmn5EbPTyZReA+M9hutiDRFe9rr6L","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":21793},"main":"dist/index.cjs","types":"dist/index.d.ts","module":"dist/index.js","browser":"dist/umd.js","exports":{".":"./dist/index.js","./auto":"./dist/auto.js"},"gitHead":"f06ba998b4805386dd85cb412d5b8e4468d5336c","scripts":{"build":"tsup"},"_npmUser":{"name":"amirafa","email":"amir.h.rafati@gmail.com"},"_npmVersion":"10.9.4","description":"DOM-native event extensions","directories":{},"_nodeVersion":"22.21.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1","typescript":"^5.9.3"},"_npmOperationalInternal":{"tmp":"tmp/xevent_1.0.1_1764074144506_0.6925031340622119","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@amirafa/xevent","version":"1.0.2","keywords":["events","dom-events","custom-events","event-listener","dom-utils","typescript","xevent"],"author":{"name":"Amirafa","email":"amir.h.rafati@gmail.com"},"license":"MIT","_id":"@amirafa/xevent@1.0.2","maintainers":[{"name":"amirafa","email":"amir.h.rafati@gmail.com"}],"dist":{"shasum":"52d6e50c317a20dcc0cee0016482cbedf64e855b","tarball":"https://registry.npmjs.org/@amirafa/xevent/-/xevent-1.0.2.tgz","fileCount":10,"integrity":"sha512-6wBMSvEadigzmn6krOBgOKXaJWCx6uT5moWhvHUjNADA5yr08PSs599PGoCeFf2Z1ZmSN6NS0DyQRFSWOj/L3w==","signatures":[{"sig":"MEUCIDCHnbiNayx6x5zfZMNTntf37YEETvyU9qdDZ94n+ybgAiEAiSzONdf52sHhr8UYvfmKJvnwNx1+HpKbcD3O5ntZJkA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":22143},"main":"dist/index.cjs","types":"dist/index.d.ts","module":"dist/index.js","browser":"dist/umd.js","exports":{".":"./dist/index.js","./auto":"./dist/auto.js"},"gitHead":"cf95566198e1bc32f979565b849e6e1bfdca0fda","scripts":{"build":"tsup"},"_npmUser":{"name":"amirafa","email":"amir.h.rafati@gmail.com"},"_npmVersion":"10.9.4","description":"DOM-native event extensions","directories":{},"_nodeVersion":"22.21.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1","typescript":"^5.9.3"},"_npmOperationalInternal":{"tmp":"tmp/xevent_1.0.2_1764074521859_0.7693250062633441","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@amirafa/xevent","version":"1.0.3","description":"DOM-native event extensions","license":"MIT","author":{"name":"Amirafa","email":"amir.h.rafati@gmail.com"},"keywords":["events","dom-events","custom-events","event-listener","dom-utils","typescript","xevent"],"repository":{"type":"git","url":"git+https://github.com/amirafa/xevent.git"},"publishConfig":{"access":"public"},"main":"dist/index.cjs","module":"dist/index.js","browser":"dist/umd.js","types":"dist/index.d.ts","exports":{".":"./dist/index.js","./auto":"./dist/auto.js"},"scripts":{"build":"tsup"},"devDependencies":{"tsup":"^8.5.1","typescript":"^5.9.3"},"_id":"@amirafa/xevent@1.0.3","gitHead":"ac3ae50e804e64807057d127f83f7751044bb73f","bugs":{"url":"https://github.com/amirafa/xevent/issues"},"homepage":"https://github.com/amirafa/xevent#readme","_nodeVersion":"22.21.1","_npmVersion":"10.9.4","dist":{"integrity":"sha512-nv5n32LFZYDw5YPJrEa2dOBy/fESVAYfIEAX1ebVImOzJ2WuFPho13WjdlozeApnECugKOY6kvax60/s6J8fWA==","shasum":"dd229dc1976e8a44eaa6f72de3ca74db7cebfffe","tarball":"https://registry.npmjs.org/@amirafa/xevent/-/xevent-1.0.3.tgz","fileCount":10,"unpackedSize":22327,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGh25Yi2www29jGzzsi36tOcnd1PSBXoO8fV13NMvNutAiEAo9Tpdwl8BH0vY/HTkBgr0+zuPcT7m2zvJgSGwfFH92M="}]},"_npmUser":{"name":"amirafa","email":"amir.h.rafati@gmail.com"},"directories":{},"maintainers":[{"name":"amirafa","email":"amir.h.rafati@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/xevent_1.0.3_1780904318911_0.04947613577236387"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-25T12:35:44.366Z","modified":"2026-06-08T07:38:39.136Z","1.0.6":"2025-11-25T11:54:55.280Z","1.0.0":"2025-11-25T12:33:12.199Z","1.0.1":"2025-11-25T12:35:44.680Z","1.0.2":"2025-11-25T12:42:02.056Z","1.0.3":"2026-06-08T07:38:39.043Z"},"author":{"name":"Amirafa","email":"amir.h.rafati@gmail.com"},"license":"MIT","keywords":["events","dom-events","custom-events","event-listener","dom-utils","typescript","xevent"],"description":"DOM-native event extensions","maintainers":[{"name":"amirafa","email":"amir.h.rafati@gmail.com"}],"readme":"# @amirafa/xevent\n\n**xevent** is a lightweight, DOM-first utility library that adds extra browser-like events that you can listen to using the native `addEventListener` API — fully typed in TypeScript.\n\nNo dependencies.  \nJust plug it into any JS environment and events behave like native browser events.\n\n---\n\n# 🚀 Features\n\n- 🔌 **DOM-native custom events**  \n  Listen using `window.addEventListener(\"event\", handler)` — no imports needed.\n\n- 🎯 **Full TypeScript support**  \n  Events extend `WindowEventMap` automatically.\n\n- 🧩 **Modular & extensible architecture**  \n  Add custom events in a clean, scalable pattern.\n\n- 🔄 **Single initialization**  \n  Each event bootstrap runs only once.\n\n- 🌐 **SSR-safe**  \n  No errors on server-side rendering environments.\n\n- 🌲 **Tree-shaking friendly**  \n  Optional auto-init or manual init — your choice.\n\n---\n\n# 📦 Installation\n\n```bash\nnpm install @amirafa/xevent\n```\n\n---\n\n# 🧠 Usage Example\n\n## 📦 Option 0 — CDN (Browser Global Script)\n\nInclude the CDN script in your HTML:\n\n```html\n<script src=\"https://cdn.jsdelivr.net/npm/@amirafa/xevent/dist/umd.global.js\"></script>\n<script>\n  // Option A — enable ALL events\n  XEvent.setupAllEvents();\n\n  // Option B — enable a single event\n  // XEvent.setupExternalLinkEvent();\n</script>\n```\n\n## Option 1 — **Manual Initialization (Tree-shaking Friendly)**\n\n```ts\nimport { setupAllEvents } from \"@amirafa/xevent\";\n\nsetupAllEvents(); // enables all events\n```\n\n## Option 2 — **Auto Initialization (Simple Mode)**\n\n```ts\nimport \"@amirafa/xevent/auto\"; // initializes all events automatically\n```\n\n## Option 3 — **Single Event Only**\n\n```ts\nimport { setupExternalLinkEvent } from \"@amirafa/xevent\";\n\nsetupExternalLinkEvent();\n```\n\n---\n\n# 🎧 Listening to Events\n\n### `\"external-link\"`\n\n```ts\nwindow.addEventListener(\"external-link\", (e) => {\n  console.log(\"External link:\", e.detail.href);\n});\n```\n\n### `\"page-leave\"`\n\n```ts\nwindow.addEventListener(\"page-leave\", (e) => {\n  console.log(\"Leaving page:\", e.detail.reason);\n});\n```\n\n---\n\n# 📜 Current Events\n\n### 1. `external-link`\n\nFires when the user clicks a link pointing **outside the current domain**.\n\n```ts\n{\n  href: string;\n  target: string | null;\n  originalEvent: MouseEvent;\n}\n```\n\n---\n\n### 2. `page-leave`\n\nFires when the user:\n\n- closes the tab  \n- refreshes  \n- switches tabs  \n- navigates away  \n\n```ts\n{\n  reason: \"unload\" | \"visibility-hidden\";\n  originalEvent: Event;\n}\n```\n\n---\n\n# ➕ Adding New Events\n\nAdding a new event is easy thanks to the shared initializer system.\n\n---\n\n## 1️⃣ Step 1 — Create a new event file\n\nCreate:\n\n```\nsrc/events/<yourEvent>.ts\n```\n\nExample:\n\n```ts\nimport { registerEvent } from \"../core/utilsRegistry\";\nimport { createEventInitializer } from \"../core/createEventInitializer\";\n\nexport const SCROLL_END_EVENT = \"scroll-end\" as const;\n\nexport interface ScrollEndEventDetail {\n  lastScrollY: number;\n}\n\nexport const setupScrollEndEvent = createEventInitializer(\n  SCROLL_END_EVENT,\n  () => {\n    let timeout: any;\n\n    window.addEventListener(\"scroll\", () => {\n      clearTimeout(timeout);\n\n      timeout = setTimeout(() => {\n        window.dispatchEvent(\n          new CustomEvent<ScrollEndEventDetail>(SCROLL_END_EVENT, {\n            detail: { lastScrollY: window.scrollY }\n          })\n        );\n      }, 120);\n    });\n  }\n);\n\nregisterEvent(SCROLL_END_EVENT, setupScrollEndEvent);\n```\n\n---\n\n## 2️⃣ Step 2 — Add Type Support\n\nEdit:\n\n```\nsrc/types/global.d.ts\n```\n\nAdd:\n\n```ts\nimport { ScrollEndEventDetail } from \"../events/scrollEnd\";\n\ndeclare global {\n  interface WindowEventMap {\n    \"scroll-end\": CustomEvent<ScrollEndEventDetail>;\n  }\n}\n```\n\n---\n\n## 3️⃣ Step 3 — Export It\n\nIn:\n\n```\nsrc/index.ts\n```\n\nAdd:\n\n```ts\nexport * from \"./events/scrollEnd\";\n```\n\n---\n\n## 4️⃣ Step 4 — Document It (README)\n\n```md\n### 3. `scroll-end`\nFires when scrolling stops.\n\nEvent detail:\n```ts\n{\n  lastScrollY: number;\n}\n```\n\n---\n\n# 🤝 Contributing\n\n1. Add your event under `src/events/`\n2. Register it with `registerEvent`\n3. Add typings in `global.d.ts`\n4. Export it from `index.ts`\n5. Update README\n\n---\n\n# 📜 License\n\nMIT\n\n---\n![GitHub Stars](https://img.shields.io/github/stars/amirafa/xevent?style=social)\n","readmeFilename":"README.md","homepage":"https://github.com/amirafa/xevent#readme","repository":{"type":"git","url":"git+https://github.com/amirafa/xevent.git"},"bugs":{"url":"https://github.com/amirafa/xevent/issues"}}