@konfetti-js/react 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Andrea Bettich
+
+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 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

@@ -1,3 +1,31 @@
-# Temporary Holding Version
+# @konfetti-js/react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React hook and component for [konfetti.js](https://andreabettich.github.io/konfetti.js/). Installs `@konfetti-js/core` for you.
+
+```bash
+npm install @konfetti-js/react
+```
+
+```tsx
+import { useState } from 'react';
+import { useKonfetti, Konfetti } from '@konfetti-js/react';
+
+function SaveButton() {
+  const { cannon } = useKonfetti();
+  return <button onClick={() => cannon()}>Save</button>;
+}
+
+function Celebration() {
+  const [done, setDone] = useState(false);
+  return (
+    <>
+      <button onClick={() => setDone(true)}>Finish</button>
+      <Konfetti fire={done} preset="fireworks" onFired={() => setDone(false)} />
+    </>
+  );
+}
+```
+
+`useKonfetti()` returns stable functions and stops its `continuous()` stream on unmount. `<Konfetti>` accepts every core option as a prop and fires once each time `fire` turns true. See the [full documentation](https://github.com/andreabettich/konfetti.js#readme).
+
+MIT licensed.

package/dist/index.cjs

@@ -0,0 +1,94 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Konfetti: () => Konfetti,
+  useKonfetti: () => useKonfetti
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/Konfetti.tsx
+var import_core = require("@konfetti-js/core");
+var import_react = require("react");
+function Konfetti({ fire: shouldFire = false, preset, onFired, ...options }) {
+  const latest = (0, import_react.useRef)({ preset, onFired, options });
+  latest.current = { preset, onFired, options };
+  const firedRef = (0, import_react.useRef)(false);
+  (0, import_react.useEffect)(() => {
+    if (!shouldFire) {
+      firedRef.current = false;
+      return;
+    }
+    if (firedRef.current) return;
+    firedRef.current = true;
+    const { preset: preset2, onFired: onFired2, options: options2 } = latest.current;
+    if (preset2) {
+      (0, import_core.firePreset)(preset2, options2);
+    } else {
+      (0, import_core.fire)(options2);
+    }
+    onFired2?.();
+  }, [shouldFire]);
+  return null;
+}
+
+// src/useKonfetti.ts
+var import_core2 = require("@konfetti-js/core");
+var import_react2 = require("react");
+function useKonfetti() {
+  const stopRef = (0, import_react2.useRef)(null);
+  (0, import_react2.useEffect)(
+    () => () => {
+      stopRef.current?.();
+      stopRef.current = null;
+    },
+    []
+  );
+  return (0, import_react2.useMemo)(
+    () => ({
+      fire: import_core2.fire,
+      cannon: import_core2.cannon,
+      explosion: import_core2.explosion,
+      fireworks: import_core2.fireworks,
+      rain: import_core2.rain,
+      snow: import_core2.snow,
+      sideCannons: import_core2.sideCannons,
+      pride: import_core2.pride,
+      continuous: (options, interval) => {
+        stopRef.current?.();
+        const stop = (0, import_core2.continuous)(options, interval);
+        stopRef.current = stop;
+        return stop;
+      },
+      reset: () => {
+        stopRef.current?.();
+        stopRef.current = null;
+        (0, import_core2.reset)();
+      }
+    }),
+    []
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Konfetti,
+  useKonfetti
+});

package/dist/index.d.cts

@@ -0,0 +1,71 @@
+import { KonfettiOptions, PresetName } from '@konfetti-js/core';
+
+interface KonfettiProps extends KonfettiOptions {
+    /** Fire when this turns true */
+    fire?: boolean;
+    /** Preset to fire; other props override the preset's values */
+    preset?: PresetName;
+    /** Called right after firing, for example to set your `fire` state back to false */
+    onFired?: () => void;
+}
+/**
+ * Declarative Konfetti component. Fires once each time `fire` turns true.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const [celebrate, setCelebrate] = useState(false);
+ *
+ *   return (
+ *     <>
+ *       <button onClick={() => setCelebrate(true)}>Celebrate!</button>
+ *       <Konfetti fire={celebrate} preset="fireworks" onFired={() => setCelebrate(false)} />
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+declare function Konfetti({ fire: shouldFire, preset, onFired, ...options }: KonfettiProps): null;
+
+type FireFn = (options?: KonfettiOptions) => void;
+interface UseKonfettiReturn {
+    /** Fire konfetti with optional options */
+    fire: FireFn;
+    /** Fire cannon preset */
+    cannon: FireFn;
+    /** Fire explosion preset */
+    explosion: FireFn;
+    /** Fire fireworks preset */
+    fireworks: FireFn;
+    /** Fire rain preset */
+    rain: FireFn;
+    /** Fire snow preset */
+    snow: FireFn;
+    /** Fire side cannons preset */
+    sideCannons: FireFn;
+    /** Fire pride preset */
+    pride: FireFn;
+    /** Start a stream (stopped automatically on unmount); returns a stop function */
+    continuous: (options?: KonfettiOptions, interval?: number) => () => void;
+    /** Clear all konfetti and stop streams */
+    reset: () => void;
+}
+/**
+ * React hook for konfetti.js. The returned functions are stable across renders.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const { fire, cannon } = useKonfetti();
+ *
+ *   return (
+ *     <button onClick={() => fire({ particleCount: 100 })}>
+ *       Celebrate!
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useKonfetti(): UseKonfettiReturn;
+
+export { Konfetti, type KonfettiProps, type UseKonfettiReturn, useKonfetti };

package/dist/index.d.ts

@@ -0,0 +1,71 @@
+import { KonfettiOptions, PresetName } from '@konfetti-js/core';
+
+interface KonfettiProps extends KonfettiOptions {
+    /** Fire when this turns true */
+    fire?: boolean;
+    /** Preset to fire; other props override the preset's values */
+    preset?: PresetName;
+    /** Called right after firing, for example to set your `fire` state back to false */
+    onFired?: () => void;
+}
+/**
+ * Declarative Konfetti component. Fires once each time `fire` turns true.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const [celebrate, setCelebrate] = useState(false);
+ *
+ *   return (
+ *     <>
+ *       <button onClick={() => setCelebrate(true)}>Celebrate!</button>
+ *       <Konfetti fire={celebrate} preset="fireworks" onFired={() => setCelebrate(false)} />
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+declare function Konfetti({ fire: shouldFire, preset, onFired, ...options }: KonfettiProps): null;
+
+type FireFn = (options?: KonfettiOptions) => void;
+interface UseKonfettiReturn {
+    /** Fire konfetti with optional options */
+    fire: FireFn;
+    /** Fire cannon preset */
+    cannon: FireFn;
+    /** Fire explosion preset */
+    explosion: FireFn;
+    /** Fire fireworks preset */
+    fireworks: FireFn;
+    /** Fire rain preset */
+    rain: FireFn;
+    /** Fire snow preset */
+    snow: FireFn;
+    /** Fire side cannons preset */
+    sideCannons: FireFn;
+    /** Fire pride preset */
+    pride: FireFn;
+    /** Start a stream (stopped automatically on unmount); returns a stop function */
+    continuous: (options?: KonfettiOptions, interval?: number) => () => void;
+    /** Clear all konfetti and stop streams */
+    reset: () => void;
+}
+/**
+ * React hook for konfetti.js. The returned functions are stable across renders.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const { fire, cannon } = useKonfetti();
+ *
+ *   return (
+ *     <button onClick={() => fire({ particleCount: 100 })}>
+ *       Celebrate!
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useKonfetti(): UseKonfettiReturn;
+
+export { Konfetti, type KonfettiProps, type UseKonfettiReturn, useKonfetti };

package/dist/index.js

@@ -0,0 +1,77 @@
+// src/Konfetti.tsx
+import { fire, firePreset } from "@konfetti-js/core";
+import { useEffect, useRef } from "react";
+function Konfetti({ fire: shouldFire = false, preset, onFired, ...options }) {
+  const latest = useRef({ preset, onFired, options });
+  latest.current = { preset, onFired, options };
+  const firedRef = useRef(false);
+  useEffect(() => {
+    if (!shouldFire) {
+      firedRef.current = false;
+      return;
+    }
+    if (firedRef.current) return;
+    firedRef.current = true;
+    const { preset: preset2, onFired: onFired2, options: options2 } = latest.current;
+    if (preset2) {
+      firePreset(preset2, options2);
+    } else {
+      fire(options2);
+    }
+    onFired2?.();
+  }, [shouldFire]);
+  return null;
+}
+
+// src/useKonfetti.ts
+import {
+  cannon,
+  continuous as coreContinuous,
+  reset as coreReset,
+  explosion,
+  fire as fire2,
+  fireworks,
+  pride,
+  rain,
+  sideCannons,
+  snow
+} from "@konfetti-js/core";
+import { useEffect as useEffect2, useMemo, useRef as useRef2 } from "react";
+function useKonfetti() {
+  const stopRef = useRef2(null);
+  useEffect2(
+    () => () => {
+      stopRef.current?.();
+      stopRef.current = null;
+    },
+    []
+  );
+  return useMemo(
+    () => ({
+      fire: fire2,
+      cannon,
+      explosion,
+      fireworks,
+      rain,
+      snow,
+      sideCannons,
+      pride,
+      continuous: (options, interval) => {
+        stopRef.current?.();
+        const stop = coreContinuous(options, interval);
+        stopRef.current = stop;
+        return stop;
+      },
+      reset: () => {
+        stopRef.current?.();
+        stopRef.current = null;
+        coreReset();
+      }
+    }),
+    []
+  );
+}
+export {
+  Konfetti,
+  useKonfetti
+};

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "@konfetti-js/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.3.0",
+  "description": "React wrapper for konfetti.js",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "keywords": [
+    "konfetti",
+    "confetti",
+    "react",
+    "animation"
+  ],
+  "author": "Andrea Bettich",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/andreabettich/konfetti.js.git",
+    "directory": "packages/react"
+  },
+  "homepage": "https://andreabettich.github.io/konfetti.js/",
+  "bugs": {
+    "url": "https://github.com/andreabettich/konfetti.js/issues"
+  },
+  "dependencies": {
+    "@konfetti-js/core": "^0.3.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.10",
+    "jsdom": "^30.1.2",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.9.3",
+    "vitest": "^5.0.3"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome lint src",
+    "check": "biome check src --write"
+  }
 }