react-ui-sound-events 1.0.0

package/README.md

@@ -0,0 +1,240 @@
+# 🎶 react-ui-sound-events
+
+A lightweight and powerful sound-feedback system for **React & Next.js**
+applications.\
+Easily play different sounds for **login, logout, success, error, toast
+notifications, and UI events** to enhance user experience and
+accessibility.
+
+------------------------------------------------------------------------
+
+## 🚀 Why react-ui-sound-events?
+
+Modern web apps rely heavily on visual feedback, but **audio feedback
+adds clarity, delight, and accessibility**.
+
+This package helps you: - Avoid rewriting sound logic in every project -
+Centralize UI sound management - Improve UX with minimal effort - Add
+premium, app-like interactions
+
+------------------------------------------------------------------------
+
+## ✨ Features
+
+-   🎵 Event-based sound playback
+-   ⚛️ Works with React & Next.js
+-   🔔 Toastify sound integration
+-   🧠 Centralized sound manager
+-   🔊 Volume control
+-   ♻️ Sound reuse & preload
+-   🚫 Browser autoplay-safe
+-   🪶 Lightweight & dependency-free
+
+------------------------------------------------------------------------
+
+## 📦 Installation
+
+``` bash
+npm install react-ui-sound-events
+```
+
+or
+
+``` bash
+yarn add react-ui-sound-events
+```
+
+------------------------------------------------------------------------
+
+## ⚙️ Basic Setup (React)
+
+Wrap your application once using `SoundProvider`.
+
+``` jsx
+import { SoundProvider } from "react-ui-sound-events";
+
+<SoundProvider
+  sounds={{
+    login: "/sounds/login.mp3",
+    logout: "/sounds/logout.mp3",
+    success: "/sounds/success.mp3",
+    error: "/sounds/error.mp3",
+    info: "/sounds/info.mp3",
+  }}
+  volume={0.8}
+>
+  <App />
+</SoundProvider>
+```
+
+------------------------------------------------------------------------
+
+## 🎮 Play Sounds Anywhere
+
+Use the `useSound` hook inside any component.
+
+``` jsx
+import { useSound } from "react-ui-sound-events";
+
+const LoginButton = () => {
+  const { play } = useSound();
+
+  return (
+    <button onClick={() => play("login")}>
+      Login
+    </button>
+  );
+};
+
+export default LoginButton;
+```
+
+------------------------------------------------------------------------
+
+## 🔔 Toastify Integration (Auto Sound)
+
+Automatically play sounds when using `react-toastify`.
+
+``` jsx
+import { useSoundToast } from "react-ui-sound-events";
+
+const Example = () => {
+  const toast = useSoundToast();
+
+  return (
+    <>
+      <button onClick={() => toast.success("Login successful!")}>
+        Success
+      </button>
+
+      <button onClick={() => toast.error("Something went wrong!")}>
+        Error
+      </button>
+    </>
+  );
+};
+```
+
+------------------------------------------------------------------------
+
+## ⚛️ Next.js Usage
+
+### App Router (`app/layout.js`)
+
+``` jsx
+"use client";
+
+import { SoundProvider } from "react-ui-sound-events";
+
+export default function RootLayout({ children }) {
+  return (
+    <SoundProvider
+      sounds={{
+        success: "/success.mp3",
+        error: "/error.mp3",
+      }}
+    >
+      {children}
+    </SoundProvider>
+  );
+}
+```
+
+### Pages Router (`pages/_app.js`)
+
+``` jsx
+import { SoundProvider } from "react-ui-sound-events";
+
+function MyApp({ Component, pageProps }) {
+  return (
+    <SoundProvider sounds={{ success: "/success.mp3" }}>
+      <Component {...pageProps} />
+    </SoundProvider>
+  );
+}
+
+export default MyApp;
+```
+
+------------------------------------------------------------------------
+
+## 🧠 Supported Events
+
+You can name sounds anything you want:
+
+-   login
+-   logout
+-   signup
+-   success
+-   error
+-   warning
+-   info
+-   click
+-   notification
+
+``` js
+play("success");
+play("error");
+```
+
+------------------------------------------------------------------------
+
+## 🔊 Volume Control
+
+``` jsx
+<SoundProvider volume={0.5}>
+  <App />
+</SoundProvider>
+```
+
+Range: `0.0` -- `1.0`
+
+------------------------------------------------------------------------
+
+## 🚫 Browser Autoplay Policy
+
+Due to browser security rules: - Sounds play **only after user
+interaction** - First click enables sound playback - Mobile browsers may
+restrict autoplay
+
+This package safely follows these rules.
+
+------------------------------------------------------------------------
+
+## 🛠️ Roadmap
+
+-   🔕 Global mute toggle
+-   🎨 Sound themes (minimal, game, iOS-style)
+-   💾 Persist user preferences
+-   ♿ Accessibility mode
+
+------------------------------------------------------------------------
+
+## 💡 Use Cases
+
+-   Login / Logout flows
+-   Admin dashboards
+-   Fintech & SaaS apps
+-   Toast notifications
+-   Games & kids apps
+-   Accessibility-focused UIs
+
+------------------------------------------------------------------------
+
+## 🧑‍💻 Author
+
+**Uttam Kumar**\
+Frontend / MERN Stack Developer
+
+------------------------------------------------------------------------
+
+## ⭐ Support
+
+If you like this project: - ⭐ Star it on GitHub - 📦 Use it in your
+projects - 🐛 Report issues & suggest features
+
+------------------------------------------------------------------------
+
+## 📄 License
+
+MIT License

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "react-ui-sound-events",
+  "version": "1.0.0",
+  "description": "Event based sound system for React & Next.js UI",
+  "main": "src/index.js",
+  "keywords": [
+    "react",
+    "nextjs",
+    "sound",
+    "toast",
+    "ui",
+    "ux"
+  ],
+  "author": "Uttam Kumar",
+  "license": "MIT",
+  "peerDependencies": {
+    "react": ">=16"
+  }
+}

package/src/SoundAutoToast.jsx

@@ -0,0 +1,21 @@
+import { toast } from "react-toastify";
+import { useSound } from "./SoundProvider";
+
+export const useSoundToast = () => {
+  const { play } = useSound();
+
+  return {
+    success: (msg) => {
+      play("success");
+      toast.success(msg);
+    },
+    error: (msg) => {
+      play("error");
+      toast.error(msg);
+    },
+    info: (msg) => {
+      play("info");
+      toast.info(msg);
+    }
+  };
+};

package/src/SoundProvider.jsx

@@ -0,0 +1,27 @@
+import React, { createContext, useContext, useRef } from "react";
+
+const SoundContext = createContext();
+
+export const SoundProvider = ({ sounds = {}, volume = 1, children }) => {
+  const audioMap = useRef({});
+
+  const play = (name) => {
+    if (!sounds[name]) return;
+
+    if (!audioMap.current[name]) {
+      audioMap.current[name] = new Audio(sounds[name]);
+    }
+
+    audioMap.current[name].volume = volume;
+    audioMap.current[name].currentTime = 0;
+    audioMap.current[name].play().catch(() => {});
+  };
+
+  return (
+    <SoundContext.Provider value={{ play }}>
+      {children}
+    </SoundContext.Provider>
+  );
+};
+
+export const useSound = () => useContext(SoundContext);

package/src/index.js

@@ -0,0 +1,3 @@
+export { SoundProvider } from "./SoundProvider";
+export { useSound } from "./useSound";
+export { useSoundToast } from "./SoundAutoToast";

package/src/useSound.js

@@ -0,0 +1 @@
+export { useSound } from "./SoundProvider";