@meijie/react-fireworks 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 meijie
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,139 @@
1
- # Temporary Holding Version
1
+ # @meijie/react-fireworks
2
2
 
3
- 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.
3
+ [![npm version](https://img.shields.io/npm/v/@meijie/react-fireworks.svg)](https://www.npmjs.com/package/@meijie/react-fireworks)
4
+ [![license](https://img.shields.io/npm/l/@meijie/react-fireworks.svg)](./LICENSE)
5
+
6
+ A canvas-based fireworks component for **React 16.8+** (hooks). Configurable particles, colors, shapes, burst position, trails, glow, multi-burst sequences, looping, and realistic launch physics.
7
+
8
+ The particle engine is shared with [`@meijie/vue-fireworks`](https://www.npmjs.com/package/@meijie/vue-fireworks) — this package is a thin React wrapper, so bug fixes and engine improvements apply to both.
9
+
10
+ ## Installation
11
+
12
+ ```bash
13
+ npm i @meijie/react-fireworks
14
+ ```
15
+
16
+ `react` (>=16.8) is a peer dependency. The engine is pulled in via `@meijie/vue-fireworks` as a runtime dependency — Vue itself is **not** required.
17
+
18
+ ## Quick start
19
+
20
+ ### Controlled with `show`
21
+
22
+ ```jsx
23
+ import { useState } from 'react'
24
+ import ReactFireworks from '@meijie/react-fireworks'
25
+
26
+ function App () {
27
+ const [show, setShow] = useState(false)
28
+
29
+ return (
30
+ <>
31
+ <ReactFireworks
32
+ show={show}
33
+ onShowChange={setShow}
34
+ shape="star"
35
+ glow
36
+ trail
37
+ />
38
+ <button onClick={() => setShow(true)}>Launch</button>
39
+ </>
40
+ )
41
+ }
42
+ ```
43
+
44
+ Playback automatically calls `onShowChange(false)` when finished, so the component can be triggered again. This mirrors Vue's `v-model:show` / `update:show`.
45
+
46
+ ### Imperative with `ref`
47
+
48
+ ```jsx
49
+ import { useRef } from 'react'
50
+ import ReactFireworks from '@meijie/react-fireworks'
51
+
52
+ function App () {
53
+ const fw = useRef(null)
54
+
55
+ return (
56
+ <>
57
+ <ReactFireworks ref={fw} count={120} />
58
+ <button onClick={() => fw.current.fire({ origin: { x: 300, y: 200 } })}>
59
+ Launch at position
60
+ </button>
61
+ <button onClick={() => fw.current.stop()}>Stop</button>
62
+ </>
63
+ )
64
+ }
65
+ ```
66
+
67
+ ## Props
68
+
69
+ All props are optional.
70
+
71
+ | Prop | Type | Default | Description |
72
+ |---|---|---|---|
73
+ | `show` | boolean | `false` | Controlled trigger. Set to `true` to launch. Reset via `onShowChange(false)`. |
74
+ | `count` | number | `60` | Number of particles per burst |
75
+ | `colors` | string[] | `['#FF8201','#2DA6E0','#FF262B']` | Particle color pool (one picked at random per particle) |
76
+ | `shape` | `'rect' \| 'circle' \| 'star'` | `'rect'` | Particle shape |
77
+ | `origin` | `'center' \| {x,y}` | `'center'` | Burst origin (CSS pixels inside canvas) |
78
+ | `followMouse` | boolean | `false` | Burst at mouse position; takes precedence over `origin` |
79
+ | `bursts` | number | `1` | Number of consecutive bursts per trigger (`1` = single, max `50`) |
80
+ | `burstInterval` | number | `280` | Interval between adjacent bursts, in ms |
81
+ | `loop` | boolean | `false` | Keep launching until `stop()` or `show=false` |
82
+ | `launch` | boolean | `false` | Show the launch phase (rocket rises, then bursts) |
83
+ | `launchDuration` | number | `1200` | Rocket ascent time, in ms |
84
+ | `launchFrom` | `'below' \| 'center' \| {x,y}` | `'below'` | Launch origin |
85
+ | `gravity` | number | `0.12` | Gravity acceleration |
86
+ | `friction` | number | `0.985` | Air drag |
87
+ | `spread` | number | `5` | Max initial explosion speed |
88
+ | `size` | number | `4` | Particle size in px |
89
+ | `duration` | number | `90` | Max particle lifetime in frames |
90
+ | `trail` | boolean | `false` | Motion trail |
91
+ | `glow` | boolean | `false` | Glow effect |
92
+ | `fps` | number | `60` | Render frame rate |
93
+ | `className` | string | — | Class on the wrapper element |
94
+ | `style` | CSSProperties | — | Inline style on the wrapper (merged with defaults) |
95
+
96
+ Any other props (e.g. `data-*`, `aria-*`) are forwarded to the wrapper `<div>`.
97
+
98
+ ## Events
99
+
100
+ | Callback | Description |
101
+ |---|---|
102
+ | `onStart` | Fired when playback starts |
103
+ | `onEnd` | Fired when playback ends |
104
+ | `onShowChange(show)` | Fired with `false` when playback ends, to reset controlled `show` |
105
+
106
+ ## Ref API
107
+
108
+ | Method | Description |
109
+ |---|---|
110
+ | `fire(overrides?)` | Trigger a round, optionally with temporary config overrides |
111
+ | `stop()` | Stop immediately and clear all particles / timers |
112
+
113
+ Calling `ref.fire({ origin })` with an explicit origin forces a **single** burst (multi-burst and looping are ignored), so "click here, burst here" stays deterministic.
114
+
115
+ ## Using the engine directly
116
+
117
+ The engine has no React or Vue dependency and can be used standalone:
118
+
119
+ ```js
120
+ import { FireworksEngine } from '@meijie/react-fireworks/engine'
121
+
122
+ const engine = new FireworksEngine(canvasEl, { count: 80, glow: true })
123
+ engine.onEnd = () => console.log('done')
124
+ engine.fire()
125
+ // engine.setOptions({ shape: 'star' }); engine.stop(); engine.destroy()
126
+ ```
127
+
128
+ ## Development
129
+
130
+ ```bash
131
+ npm install
132
+ npm test # Vitest unit tests
133
+ npm run build # build dist/ (ESM + CJS + type declarations)
134
+ npm run dev # interactive demo at http://127.0.0.1:5193
135
+ ```
136
+
137
+ ## License
138
+
139
+ MIT
@@ -0,0 +1,5 @@
1
+ // Re-export engine types from the shared core package.
2
+ // The runtime is provided by @meijie/vue-fireworks/engine (see package.json exports).
3
+ export { FireworksEngine } from '@meijie/vue-fireworks/engine'
4
+ export type { FireworksOptions, FireworksShape, FireworksOrigin } from '@meijie/vue-fireworks'
5
+ export { default } from '@meijie/vue-fireworks/engine'
package/dist/index.cjs ADDED
@@ -0,0 +1 @@
1
+ "use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const y=require("react/jsx-runtime"),t=require("react"),b=require("@meijie/vue-fireworks/engine"),f=["count","colors","shape","gravity","friction","spread","size","trail","glow","duration","origin","followMouse","bursts","burstInterval","loop","launch","launchDuration","launchFrom","fps"];function R(c){const n={};for(const r of f)c[r]!==void 0&&(n[r]=c[r]);return n}function x(c){const n=new Set([...f,"show","onStart","onEnd","onShowChange","className","style"]),r={};for(const s of Object.keys(c))n.has(s)||(r[s]=c[s]);return r}const M=t.forwardRef(function(n,r){const{show:s=!1,onStart:d,onEnd:h,onShowChange:w,className:v,style:E}=n,k=x(n),g=t.useRef(null),u=t.useRef(null),o=t.useRef({onStart:d,onEnd:h,onShowChange:w});o.current={onStart:d,onEnd:h,onShowChange:w};const S=t.useRef(R(n));S.current=R(n),t.useEffect(()=>{const e=new b.FireworksEngine(g.current,S.current);return u.current=e,e.onEnd=()=>{o.current.onShowChange&&o.current.onShowChange(!1),o.current.onEnd&&o.current.onEnd()},()=>{e.destroy(),u.current=null}},[]),t.useEffect(()=>{const e=u.current;if(!e)return;const i={};for(const l of f)n[l]!==void 0&&(i[l]=n[l]);e.setOptions(i)},f.map(e=>n[e]));const a=t.useRef(!1);t.useEffect(()=>{const e=u.current;e&&(s&&!a.current?(o.current.onStart&&o.current.onStart(),e.fire()):!s&&a.current&&e.stop(),a.current=s)},[s]),t.useImperativeHandle(r,()=>({fire(e){const i=u.current;i&&(o.current.onStart&&o.current.onStart(),i.fire(e))},stop(){const e=u.current;e&&e.stop()}}),[]);const m={position:"fixed",inset:0,zIndex:11,pointerEvents:n.followMouse?"none":"auto",...E};return y.jsx("div",{className:v,style:m,...k,children:y.jsx("canvas",{ref:g,style:{width:"100%",height:"100%",display:"block"}})})});exports.default=M;
@@ -0,0 +1,77 @@
1
+ import * as React from 'react'
2
+
3
+ /** 粒子形状 */
4
+ export type FireworksShape = 'rect' | 'circle' | 'star'
5
+
6
+ /** 绽放原点:'center' 或 canvas 内的 CSS 像素坐标 */
7
+ export type FireworksOrigin = 'center' | { x: number; y: number }
8
+
9
+ /** 所有可配置项 */
10
+ export interface FireworksOptions {
11
+ /** 每轮粒子数,默认 60 */
12
+ count?: number
13
+ /** 颜色池,默认 ['#FF8201','#2DA6E0','#FF262B'] */
14
+ colors?: string[]
15
+ /** 粒子形状,默认 'rect' */
16
+ shape?: FireworksShape
17
+ /** 重力加速度(px/frame²),默认 0.12 */
18
+ gravity?: number
19
+ /** 空气阻力(速度衰减系数),默认 0.985 */
20
+ friction?: number
21
+ /** 爆炸初速度上限,默认 5 */
22
+ spread?: number
23
+ /** 粒子尺寸(px),默认 4 */
24
+ size?: number
25
+ /** 拖尾残影,默认 false */
26
+ trail?: boolean
27
+ /** 发光,默认 false */
28
+ glow?: boolean
29
+ /** 粒子最大寿命(帧),默认 90 */
30
+ duration?: number
31
+ /** 绽放原点,默认 'center' */
32
+ origin?: FireworksOrigin
33
+ /** 跟随鼠标(优先级高于 origin),默认 false */
34
+ followMouse?: boolean
35
+ /** 一次触发连续绽放几朵(1 = 单朵),默认 1,最大 50 */
36
+ bursts?: number
37
+ /** 相邻两朵的间隔(ms),默认 280 */
38
+ burstInterval?: number
39
+ /** 循环连放,直到 stop()/show=false,默认 false */
40
+ loop?: boolean
41
+ /** 是否显示发射过程(弹丸升空后绽放),默认 false */
42
+ launch?: boolean
43
+ /** 弹丸升空时长(ms),默认 1200 */
44
+ launchDuration?: number
45
+ /** 发射起点:'below'(绽放点正下方底边) | 'center' | {x,y},默认 'below' */
46
+ launchFrom?: 'below' | 'center' | { x: number; y: number }
47
+ /** 帧率,默认 60 */
48
+ fps?: number
49
+ }
50
+
51
+ /** ref 暴露的命令式方法 */
52
+ export interface FireworksHandle {
53
+ /** 手动触发一轮,可临时覆盖配置 */
54
+ fire(overrides?: FireworksOptions): void
55
+ /** 立即停止并清空 */
56
+ stop(): void
57
+ }
58
+
59
+ /** 组件 props */
60
+ export interface ReactFireworksProps extends FireworksOptions {
61
+ /** 受控触发:置 true 触发一轮,播放结束由 onShowChange(false) 通知复位 */
62
+ show?: boolean
63
+ /** 开始播放时触发 */
64
+ onStart?: () => void
65
+ /** 播放结束时触发 */
66
+ onEnd?: () => void
67
+ /** 播放结束时请求把 show 置回 false(对齐 Vue 的 update:show) */
68
+ onShowChange?: (show: boolean) => void
69
+ className?: string
70
+ style?: React.CSSProperties
71
+ }
72
+
73
+ declare const ReactFireworks: React.ForwardRefExoticComponent<
74
+ ReactFireworksProps & React.RefAttributes<FireworksHandle>
75
+ >
76
+
77
+ export default ReactFireworks
package/dist/index.js ADDED
@@ -0,0 +1,103 @@
1
+ import { jsx as y } from "react/jsx-runtime";
2
+ import { forwardRef as b, useRef as u, useEffect as d, useImperativeHandle as x } from "react";
3
+ import { FireworksEngine as C } from "@meijie/vue-fireworks/engine";
4
+ const f = [
5
+ "count",
6
+ "colors",
7
+ "shape",
8
+ "gravity",
9
+ "friction",
10
+ "spread",
11
+ "size",
12
+ "trail",
13
+ "glow",
14
+ "duration",
15
+ "origin",
16
+ "followMouse",
17
+ "bursts",
18
+ "burstInterval",
19
+ "loop",
20
+ "launch",
21
+ "launchDuration",
22
+ "launchFrom",
23
+ "fps"
24
+ ];
25
+ function k(c) {
26
+ const e = {};
27
+ for (const o of f)
28
+ c[o] !== void 0 && (e[o] = c[o]);
29
+ return e;
30
+ }
31
+ function F(c) {
32
+ const e = /* @__PURE__ */ new Set([
33
+ ...f,
34
+ "show",
35
+ "onStart",
36
+ "onEnd",
37
+ "onShowChange",
38
+ "className",
39
+ "style"
40
+ ]), o = {};
41
+ for (const r of Object.keys(c))
42
+ e.has(r) || (o[r] = c[r]);
43
+ return o;
44
+ }
45
+ const j = b(function(e, o) {
46
+ const {
47
+ show: r = !1,
48
+ onStart: h,
49
+ onEnd: w,
50
+ onShowChange: g,
51
+ className: v,
52
+ style: E
53
+ } = e, R = F(e), S = u(null), s = u(null), t = u({ onStart: h, onEnd: w, onShowChange: g });
54
+ t.current = { onStart: h, onEnd: w, onShowChange: g };
55
+ const m = u(k(e));
56
+ m.current = k(e), d(() => {
57
+ const n = new C(S.current, m.current);
58
+ return s.current = n, n.onEnd = () => {
59
+ t.current.onShowChange && t.current.onShowChange(!1), t.current.onEnd && t.current.onEnd();
60
+ }, () => {
61
+ n.destroy(), s.current = null;
62
+ };
63
+ }, []), d(() => {
64
+ const n = s.current;
65
+ if (!n)
66
+ return;
67
+ const i = {};
68
+ for (const l of f)
69
+ e[l] !== void 0 && (i[l] = e[l]);
70
+ n.setOptions(i);
71
+ }, f.map((n) => e[n]));
72
+ const a = u(!1);
73
+ d(() => {
74
+ const n = s.current;
75
+ n && (r && !a.current ? (t.current.onStart && t.current.onStart(), n.fire()) : !r && a.current && n.stop(), a.current = r);
76
+ }, [r]), x(o, () => ({
77
+ fire(n) {
78
+ const i = s.current;
79
+ i && (t.current.onStart && t.current.onStart(), i.fire(n));
80
+ },
81
+ stop() {
82
+ const n = s.current;
83
+ n && n.stop();
84
+ }
85
+ }), []);
86
+ const p = {
87
+ position: "fixed",
88
+ inset: 0,
89
+ zIndex: 11,
90
+ pointerEvents: e.followMouse ? "none" : "auto",
91
+ ...E
92
+ };
93
+ return /* @__PURE__ */ y("div", { className: v, style: p, ...R, children: /* @__PURE__ */ y(
94
+ "canvas",
95
+ {
96
+ ref: S,
97
+ style: { width: "100%", height: "100%", display: "block" }
98
+ }
99
+ ) });
100
+ });
101
+ export {
102
+ j as default
103
+ };
package/package.json CHANGED
@@ -1,6 +1,61 @@
1
1
  {
2
2
  "name": "@meijie/react-fireworks",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "Canvas fireworks component for React, with configurable particles, colors, shapes, multi-burst, looping and realistic launch physics.",
5
+ "main": "./dist/index.cjs",
6
+ "module": "./dist/index.js",
7
+ "types": "./dist/index.d.ts",
8
+ "exports": {
9
+ ".": {
10
+ "types": "./dist/index.d.ts",
11
+ "import": "./dist/index.js",
12
+ "require": "./dist/index.cjs"
13
+ },
14
+ "./engine": {
15
+ "types": "./dist/engine.d.ts",
16
+ "import": "@meijie/vue-fireworks/engine",
17
+ "require": "@meijie/vue-fireworks/engine"
18
+ }
19
+ },
20
+ "files": [
21
+ "dist"
22
+ ],
23
+ "sideEffects": false,
24
+ "keywords": [
25
+ "react",
26
+ "fireworks",
27
+ "canvas",
28
+ "animation",
29
+ "particle",
30
+ "烟花",
31
+ "礼花"
32
+ ],
33
+ "scripts": {
34
+ "build": "FORMAT=es vite build && FORMAT=cjs vite build && cp types/*.d.ts dist/",
35
+ "test": "vitest run",
36
+ "dev": "vite --config demo/vite.config.js"
37
+ },
38
+ "dependencies": {
39
+ "@meijie/vue-fireworks": "^0.4.1"
40
+ },
41
+ "peerDependencies": {
42
+ "react": ">=16.8.0"
43
+ },
44
+ "repository": {
45
+ "type": "git",
46
+ "url": "git+https://github.com/meijie9412/react-fireworks.git"
47
+ },
48
+ "homepage": "https://github.com/meijie9412/react-fireworks#readme",
49
+ "bugs": {
50
+ "url": "https://github.com/meijie9412/react-fireworks/issues"
51
+ },
52
+ "author": "meijie",
53
+ "license": "MIT",
54
+ "devDependencies": {
55
+ "@testing-library/react": "^16.1.0",
56
+ "@vitejs/plugin-react": "^4.3.4",
57
+ "jsdom": "^25.0.1",
58
+ "vite": "^4.5.14",
59
+ "vitest": "^2.1.9"
60
+ }
61
+ }