celebrate-js 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License Copyright (c) 2025 akshaywritescode
+
+Permission is hereby granted,
+free of charge, to any person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice
+(including the next paragraph) shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
+ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,170 @@
+# celebrate-js 🎉
+
+A lightweight, zero-dependency JavaScript library to add beautiful celebration effects to your website — confetti, fireworks, balloons, emoji rain, and more.
+
+Perfect for success screens, onboarding, achievements, or fun UI moments.
+
+---
+
+## Features
+
+- Multiple celebration effects
+- Customizable colors 🎨
+- Lightweight and fast
+- Simple API
+- Tree-shakable
+- TypeScript support
+- Optional reduced-motion support
+
+---
+
+## Installation
+
+```bash
+npm install celebrate-js
+```
+
+or
+
+```bash
+yarn add celebrate-js
+```
+
+---
+
+## Usage
+
+```js
+import { celebrate } from "celebrate-js";
+
+// Default effect (confetti)
+celebrate();
+
+// Specific effects
+celebrate.confetti();
+celebrate.fireworks({ count: 6 });
+celebrate.balloons({ particleCount: 20 });
+```
+
+---
+
+## Custom Colors
+
+You can customize colors for supported effects by passing a `colors` array.
+
+Example:
+
+```js
+celebrate.confetti({
+  colors: ["#ff1744", "#2979ff", "#00e676"],
+});
+```
+
+Supported effects:
+
+- confetti
+- balloons
+- popper
+- fireworks
+- stars
+
+Color behavior:
+
+- Confetti → per particle
+- Balloons → per balloon
+- Fireworks → per burst
+- Popper → per particle
+
+---
+
+## Available Effects
+
+- confetti
+- balloons
+- popper
+- fireworks
+- bubbles
+- emojis
+- stars
+- snowfall
+
+---
+
+## API
+
+### celebrate(options?)
+
+```js
+celebrate({
+  effect: "confetti",
+  duration: 5000,
+  particleCount: 100,
+  colors: ["#ff0", "#0ff"],
+});
+```
+
+---
+
+## Effect Shortcuts
+
+```js
+celebrate.confetti(options);
+celebrate.balloons(options);
+celebrate.popper(options);
+celebrate.fireworks(options);
+celebrate.bubbles(options);
+celebrate.emojis(options);
+celebrate.stars(options);
+celebrate.snowfall(options);
+```
+
+---
+
+## Options
+
+```ts
+type CelebrateOptions = {
+  effect?: "confetti" | "balloons" | "popper" | "fireworks" | "bubbles" | "emojis" | "stars" | "snowfall";
+  duration?: number;
+  particleCount?: number;
+
+  /**
+   * Colors used by supported effects (confetti, balloons, fireworks, popper, stars)
+   */
+  colors?: string[];
+
+  respectReducedMotion?: boolean;
+
+  // Fireworks only
+  count?: number;
+  interval?: number;
+
+  // Emoji rain only
+  emojis?: string[];
+};
+```
+
+---
+
+## Reduced Motion
+
+If `respectReducedMotion` is enabled and the user has `prefers-reduced-motion` set,
+animations will be skipped.
+
+```js
+celebrate({
+  respectReducedMotion: true
+});
+```
+
+---
+
+## Demo
+
+A demo is available in the repository under the `demo/` directory.
+
+---
+
+## License
+
+MIT © Akshay Yadav