crosshook 1.0.0

package/README.md

@@ -0,0 +1,255 @@
+# crosshook
+
+> Tiny hook-first event bridge for decoupled React component
+> communication.
+
+`crosshook` lets React components communicate without prop drilling,
+context nesting, or heavyweight state managers.
+
+Perfect for UI orchestration like modals, toasts, loaders, and
+notifications.
+
+------------------------------------------------------------------------
+
+## ✨ Features
+
+✅ Hook-first API\
+✅ No providers required\
+✅ Tiny footprint\
+✅ Lifecycle-safe (auto cleanup)\
+✅ Strict Mode friendly\
+✅ TypeScript ready
+
+------------------------------------------------------------------------
+
+## 📦 Installation
+
+``` bash
+npm install crosshook
+```
+
+or
+
+``` bash
+yarn add crosshook
+```
+
+------------------------------------------------------------------------
+
+## 🚀 Quick Start
+
+### ✅ Register a Listener
+
+``` tsx
+import { useRegister } from "crosshook";
+
+function Toast() {
+  useRegister("toast.show", (payload: { message: string }) => {
+    console.log(payload.message);
+  });
+
+  return null;
+}
+```
+
+------------------------------------------------------------------------
+
+### ✅ Call an Event
+
+``` tsx
+import { useBridge } from "crosshook";
+
+function SaveButton() {
+  const { call } = useBridge();
+
+  return (
+    <button
+      onClick={() =>
+        call("toast.show", { message: "Saved successfully!" })
+      }
+    >
+      Save
+    </button>
+  );
+}
+```
+
+------------------------------------------------------------------------
+
+## 🎯 Common Use Cases
+
+### 🔔 Toast Notifications
+
+``` tsx
+useRegister("toast.show", ({ message }) => {
+  setToast(message);
+});
+
+call("toast.show", { message: "Profile updated!" });
+```
+
+------------------------------------------------------------------------
+
+### 🪟 Modal Control
+
+``` tsx
+useRegister("modal.open", () => setOpen(true));
+useRegister("modal.close", () => setOpen(false));
+
+call("modal.open");
+```
+
+------------------------------------------------------------------------
+
+### ⏳ Global Loader
+
+``` tsx
+useRegister("loader.show", () => setLoading(true));
+useRegister("loader.hide", () => setLoading(false));
+
+call("loader.show");
+call("loader.hide");
+```
+
+------------------------------------------------------------------------
+
+## 🧠 API
+
+### `useBridge()`
+
+Returns bridge actions.
+
+``` ts
+const { call } = useBridge();
+```
+
+#### `call(eventName, payload?)`
+
+Triggers all listeners registered for the event.
+
+------------------------------------------------------------------------
+
+### `useRegister(eventName, handler)`
+
+Registers a listener.
+
+``` ts
+useRegister("event.name", (payload) => {
+  ...
+});
+```
+
+✔ Automatically cleaned up on unmount\
+✔ Safe in React Strict Mode
+
+------------------------------------------------------------------------
+
+### `call(eventName, payload?)`
+
+Non-hook version (can be used outside React).
+
+``` ts
+import { call } from "crosshook";
+
+call("toast.show", { message: "Hello!" });
+```
+
+------------------------------------------------------------------------
+
+### `register(eventName, handler)`
+
+Manual registration.
+
+``` ts
+import { register } from "crosshook";
+
+const unregister = register("event", handler);
+
+// later
+unregister();
+```
+
+------------------------------------------------------------------------
+
+## ⚠️ Best Practices
+
+### ✅ Good For
+
+✔ UI interactions\
+✔ Modals\
+✔ Toasts\
+✔ Notifications\
+✔ Cross-tree communication
+
+------------------------------------------------------------------------
+
+### ❌ Avoid Using For
+
+✖ Business logic orchestration\
+✖ App state management\
+✖ Server/cache state\
+✖ Data persistence
+
+Use React state / Zustand / Redux instead.
+
+------------------------------------------------------------------------
+
+## 🔷 TypeScript Usage (Optional)
+
+You can strongly type events:
+
+``` ts
+type Events = {
+  "toast.show": { message: string };
+  "modal.open": void;
+};
+```
+
+(Advanced typed helpers coming soon)
+
+------------------------------------------------------------------------
+
+## 🧹 Cleanup Behavior
+
+Listeners automatically unsubscribe when components unmount.
+
+No memory leaks. No manual cleanup required.
+
+------------------------------------------------------------------------
+
+## 🛠 Example Pattern
+
+``` tsx
+// Listener
+useRegister("user.select", (user) => {
+  setUser(user);
+});
+
+// Caller
+call("user.select", { id: 1, name: "Manu" });
+```
+
+------------------------------------------------------------------------
+
+## 📏 Bundle Size
+
+Designed to be extremely lightweight.
+
+------------------------------------------------------------------------
+
+## 📜 License
+
+MIT
+
+------------------------------------------------------------------------
+
+## ❤️ Why crosshook?
+
+Because not every interaction needs:
+
+❌ Prop drilling\
+❌ Deep context trees\
+❌ Heavy state libraries
+
+Sometimes you just need a tiny event bridge.
+

package/dist/index.d.mts

@@ -0,0 +1,10 @@
+type Handler<T = any> = (payload: T) => void;
+declare function register<T = any>(event: string, handler: Handler<T>): () => void;
+declare function call<T = any>(event: string, payload?: T): void;
+
+declare function useRegister<T = any>(event: string, handler: Handler<T>): void;
+declare function useBridge(): {
+    call: typeof call;
+};
+
+export { type Handler, call, register, useBridge, useRegister };

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+type Handler<T = any> = (payload: T) => void;
+declare function register<T = any>(event: string, handler: Handler<T>): () => void;
+declare function call<T = any>(event: string, payload?: T): void;
+
+declare function useRegister<T = any>(event: string, handler: Handler<T>): void;
+declare function useBridge(): {
+    call: typeof call;
+};
+
+export { type Handler, call, register, useBridge, useRegister };

package/dist/index.js

@@ -0,0 +1,2 @@
+"use strict";var l=Object.defineProperty;var f=Object.getOwnPropertyDescriptor;var p=Object.getOwnPropertyNames;var u=Object.prototype.hasOwnProperty;var x=(r,e)=>{for(var t in e)l(r,t,{get:e[t],enumerable:!0})},y=(r,e,t,s)=>{if(e&&typeof e=="object"||typeof e=="function")for(let o of p(e))!u.call(r,o)&&o!==t&&l(r,o,{get:()=>e[o],enumerable:!(s=f(e,o))||s.enumerable});return r};var H=r=>y(l({},"__esModule",{value:!0}),r);var T={};x(T,{call:()=>a,register:()=>i,useBridge:()=>c,useRegister:()=>g});module.exports=H(T);var d=require("react");var n=new Map;function i(r,e){return n.has(r)||n.set(r,new Set),n.get(r).add(e),()=>{n.get(r)?.delete(e),n.get(r)?.size===0&&n.delete(r)}}function a(r,e){let t=n.get(r);if(!t){process.env.NODE_ENV!=="production"&&console.warn(`[Bridge] No listeners for event "${r}"`);return}t.forEach(s=>{try{s(e)}catch(o){console.error(`[Bridge] Error in handler for "${r}"`,o)}})}function g(r,e){(0,d.useEffect)(()=>i(r,e),[r,e])}function c(){return{call:a}}0&&(module.exports={call,register,useBridge,useRegister});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/hooks.ts","../src/bridge.ts"],"sourcesContent":["export { useBridge, useRegister } from \"./hooks\";\nexport { call, register } from \"./bridge\";\nexport type { Handler } from \"./bridge\";","import { useEffect } from \"react\";\nimport { register, call, Handler } from \"./bridge\";\n\nexport function useRegister<T = any>(\n    event: string,\n    handler: Handler<T>\n) {\n    useEffect(() => {\n        const unregister = register(event, handler);\n        return unregister;\n    }, [event, handler]);\n}\n\nexport function useBridge() {\n    return { call };\n}","export type Handler<T = any> = (payload: T) => void;\n\nconst listeners = new Map<string, Set<Handler>>();\n\nexport function register<T = any>(\n    event: string,\n    handler: Handler<T>\n) {\n    if (!listeners.has(event)) {\n        listeners.set(event, new Set());\n    }\n\n    listeners.get(event)!.add(handler as Handler);\n\n    return () => {\n        listeners.get(event)?.delete(handler as Handler);\n\n        if (listeners.get(event)?.size === 0) {\n            listeners.delete(event);\n        }\n    };\n}\n\nexport function call<T = any>(event: string, payload?: T) {\n    const handlers = listeners.get(event);\n\n    if (!handlers) {\n        if (process.env.NODE_ENV !== \"production\") {\n            console.warn(\n                `[Bridge] No listeners for event \"${event}\"`\n            );\n        }\n        return;\n    }\n\n    handlers.forEach((handler) => {\n        try {\n            handler(payload);\n        } catch (err) {\n            console.error(\n                `[Bridge] Error in handler for \"${event}\"`,\n                err\n            );\n        }\n    });\n}"],"mappings":"yaAAA,IAAAA,EAAA,GAAAC,EAAAD,EAAA,UAAAE,EAAA,aAAAC,EAAA,cAAAC,EAAA,gBAAAC,IAAA,eAAAC,EAAAN,GCAA,IAAAO,EAA0B,iBCE1B,IAAMC,EAAY,IAAI,IAEf,SAASC,EACZC,EACAC,EACF,CACE,OAAKH,EAAU,IAAIE,CAAK,GACpBF,EAAU,IAAIE,EAAO,IAAI,GAAK,EAGlCF,EAAU,IAAIE,CAAK,EAAG,IAAIC,CAAkB,EAErC,IAAM,CACTH,EAAU,IAAIE,CAAK,GAAG,OAAOC,CAAkB,EAE3CH,EAAU,IAAIE,CAAK,GAAG,OAAS,GAC/BF,EAAU,OAAOE,CAAK,CAE9B,CACJ,CAEO,SAASE,EAAcF,EAAeG,EAAa,CACtD,IAAMC,EAAWN,EAAU,IAAIE,CAAK,EAEpC,GAAI,CAACI,EAAU,CACP,QAAQ,IAAI,WAAa,cACzB,QAAQ,KACJ,oCAAoCJ,CAAK,GAC7C,EAEJ,MACJ,CAEAI,EAAS,QAASH,GAAY,CAC1B,GAAI,CACAA,EAAQE,CAAO,CACnB,OAASE,EAAK,CACV,QAAQ,MACJ,kCAAkCL,CAAK,IACvCK,CACJ,CACJ,CACJ,CAAC,CACL,CD1CO,SAASC,EACZC,EACAC,EACF,IACE,aAAU,IACaC,EAASF,EAAOC,CAAO,EAE3C,CAACD,EAAOC,CAAO,CAAC,CACvB,CAEO,SAASE,GAAY,CACxB,MAAO,CAAE,KAAAC,CAAK,CAClB","names":["index_exports","__export","call","register","useBridge","useRegister","__toCommonJS","import_react","listeners","register","event","handler","call","payload","handlers","err","useRegister","event","handler","register","useBridge","call"]}

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import{useEffect as l}from"react";var t=new Map;function n(r,e){return t.has(r)||t.set(r,new Set),t.get(r).add(e),()=>{t.get(r)?.delete(e),t.get(r)?.size===0&&t.delete(r)}}function s(r,e){let o=t.get(r);if(!o){process.env.NODE_ENV!=="production"&&console.warn(`[Bridge] No listeners for event "${r}"`);return}o.forEach(i=>{try{i(e)}catch(a){console.error(`[Bridge] Error in handler for "${r}"`,a)}})}function d(r,e){l(()=>n(r,e),[r,e])}function g(){return{call:s}}export{s as call,n as register,g as useBridge,d as useRegister};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/hooks.ts","../src/bridge.ts"],"sourcesContent":["import { useEffect } from \"react\";\nimport { register, call, Handler } from \"./bridge\";\n\nexport function useRegister<T = any>(\n    event: string,\n    handler: Handler<T>\n) {\n    useEffect(() => {\n        const unregister = register(event, handler);\n        return unregister;\n    }, [event, handler]);\n}\n\nexport function useBridge() {\n    return { call };\n}","export type Handler<T = any> = (payload: T) => void;\n\nconst listeners = new Map<string, Set<Handler>>();\n\nexport function register<T = any>(\n    event: string,\n    handler: Handler<T>\n) {\n    if (!listeners.has(event)) {\n        listeners.set(event, new Set());\n    }\n\n    listeners.get(event)!.add(handler as Handler);\n\n    return () => {\n        listeners.get(event)?.delete(handler as Handler);\n\n        if (listeners.get(event)?.size === 0) {\n            listeners.delete(event);\n        }\n    };\n}\n\nexport function call<T = any>(event: string, payload?: T) {\n    const handlers = listeners.get(event);\n\n    if (!handlers) {\n        if (process.env.NODE_ENV !== \"production\") {\n            console.warn(\n                `[Bridge] No listeners for event \"${event}\"`\n            );\n        }\n        return;\n    }\n\n    handlers.forEach((handler) => {\n        try {\n            handler(payload);\n        } catch (err) {\n            console.error(\n                `[Bridge] Error in handler for \"${event}\"`,\n                err\n            );\n        }\n    });\n}"],"mappings":"AAAA,OAAS,aAAAA,MAAiB,QCE1B,IAAMC,EAAY,IAAI,IAEf,SAASC,EACZC,EACAC,EACF,CACE,OAAKH,EAAU,IAAIE,CAAK,GACpBF,EAAU,IAAIE,EAAO,IAAI,GAAK,EAGlCF,EAAU,IAAIE,CAAK,EAAG,IAAIC,CAAkB,EAErC,IAAM,CACTH,EAAU,IAAIE,CAAK,GAAG,OAAOC,CAAkB,EAE3CH,EAAU,IAAIE,CAAK,GAAG,OAAS,GAC/BF,EAAU,OAAOE,CAAK,CAE9B,CACJ,CAEO,SAASE,EAAcF,EAAeG,EAAa,CACtD,IAAMC,EAAWN,EAAU,IAAIE,CAAK,EAEpC,GAAI,CAACI,EAAU,CACP,QAAQ,IAAI,WAAa,cACzB,QAAQ,KACJ,oCAAoCJ,CAAK,GAC7C,EAEJ,MACJ,CAEAI,EAAS,QAASH,GAAY,CAC1B,GAAI,CACAA,EAAQE,CAAO,CACnB,OAASE,EAAK,CACV,QAAQ,MACJ,kCAAkCL,CAAK,IACvCK,CACJ,CACJ,CACJ,CAAC,CACL,CD1CO,SAASC,EACZC,EACAC,EACF,CACEC,EAAU,IACaC,EAASH,EAAOC,CAAO,EAE3C,CAACD,EAAOC,CAAO,CAAC,CACvB,CAEO,SAASG,GAAY,CACxB,MAAO,CAAE,KAAAC,CAAK,CAClB","names":["useEffect","listeners","register","event","handler","call","payload","handlers","err","useRegister","event","handler","useEffect","register","useBridge","call"]}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "crosshook",
+  "version": "1.0.0",
+  "description": "Tiny hook-based event bridge for React",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  },
+  "peerDependencies": {
+    "react": ">=17"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "@types/react": "^19.2.14",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  }
+}