@xdy-npm/react-particle-backgrounds 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present ruofeng
+
+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

@@ -0,0 +1,177 @@
+# react-particle-backgrounds
+
+A React component library that provides **7 beautiful particle background themes** powered by [tsparticles](https://particles.js.org/) and [Three.js](https://threejs.org/).
+
+## Themes
+
+| Theme | ID | Description |
+|-------|----|-------------|
+| ✨ Star Links | `starline` | Classic particle linking effect |
+| ❄️ Snowfall | `snow` | Romantic falling snowflakes |
+| 🫧 Bubbles | `bubble` | Dreamy rising bubbles |
+| ⭐ Twinkling Stars | `stars` | Sparkling starry sky |
+| 🪲 Fireflies | `firefly` | Warm glowing firefly effect |
+| 🔷 Geometry | `geometry` | Floating abstract geometric shapes |
+| 🌊 Particle Ocean | `wave` | 3D particle wave (Three.js) |
+| 🚫 None | `none` | Disable effects |
+
+## Installation
+
+```bash
+npm install @xdy-npm/react-particle-backgrounds
+# or
+pnpm add @xdy-npm/react-particle-backgrounds
+```
+
+For the **Particle Ocean** (wave) theme, you also need Three.js:
+
+```bash
+npm install three
+```
+
+## Quick Start
+
+### Simple Usage (Props)
+
+```tsx
+import { ParticlesBackground } from '@xdy-npm/react-particle-backgrounds';
+
+function App() {
+  return (
+    <div>
+      <ParticlesBackground theme="starline" isDark />
+      <main style={{ position: 'relative', zIndex: 1 }}>
+        <h1>My App</h1>
+      </main>
+    </div>
+  );
+}
+```
+
+### With Theme Selector (Context)
+
+```tsx
+import {
+  ParticleProvider,
+  ParticlesBackground,
+  ThemeSelector,
+} from '@xdy-npm/react-particle-backgrounds';
+
+function App() {
+  return (
+    <ParticleProvider defaultTheme="snow" isDark>
+      <ParticlesBackground />
+      <ThemeSelector position="bottom-right" accentColor="#3b82f6" />
+      <main style={{ position: 'relative', zIndex: 1 }}>
+        <h1>My App</h1>
+      </main>
+    </ParticleProvider>
+  );
+}
+```
+
+### Programmatic Theme Switching
+
+```tsx
+import {
+  ParticleProvider,
+  ParticlesBackground,
+  useParticleTheme,
+} from '@xdy-npm/react-particle-backgrounds';
+
+function ThemeButton() {
+  const { themeId, setTheme } = useParticleTheme();
+
+  return (
+    <button onClick={() => setTheme('firefly')}>
+      Current: {themeId} — Switch to Firefly
+    </button>
+  );
+}
+
+function App() {
+  return (
+    <ParticleProvider>
+      <ParticlesBackground />
+      <ThemeButton />
+    </ParticleProvider>
+  );
+}
+```
+
+## API
+
+### `<ParticlesBackground />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `theme` | `ThemeId \| string` | `'starline'` | Theme ID (overrides provider) |
+| `isDark` | `boolean` | `true` | Dark mode toggle |
+| `onLoaded` | `(container?) => void` | — | Callback when particles load |
+| `className` | `string` | — | CSS class |
+| `style` | `CSSProperties` | — | Inline styles |
+
+### `<ParticleProvider />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `defaultTheme` | `ThemeId \| string` | `'starline'` | Initial theme |
+| `isDark` | `boolean` | `true` | Dark mode state |
+| `persist` | `boolean` | `true` | Save to localStorage |
+| `children` | `ReactNode` | — | Child components |
+
+### `<ThemeSelector />`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | `'bottom-right'` | Button position |
+| `accentColor` | `string` | `'#3b82f6'` | Active state color |
+
+### `useParticleTheme()`
+
+Hook to access theme state (must be within `<ParticleProvider>`).
+
+```ts
+const { themeId, isDark, setTheme, setDark } = useParticleTheme();
+```
+
+### Theme Objects
+
+Access individual theme configs:
+
+```ts
+import { starlineTheme, particleThemes, getThemeById } from '@xdy-npm/react-particle-backgrounds';
+
+const theme = getThemeById('snow');
+const options = theme.options(true); // get tsparticles config for dark mode
+```
+
+## Custom Themes
+
+You can create your own theme and pass it directly:
+
+```tsx
+import type { ParticleTheme } from '@xdy-npm/react-particle-backgrounds';
+import { baseConfig } from '@xdy-npm/react-particle-backgrounds';
+
+const myTheme: ParticleTheme = {
+  id: 'custom',
+  name: 'My Theme',
+  icon: '🎨',
+  description: 'A custom particle theme',
+  options: (isDark) => ({
+    ...baseConfig,
+    particles: {
+      color: { value: isDark ? '#ffffff' : '#000000' },
+      number: { value: 50 },
+      move: { enable: true, speed: 2 },
+      shape: { type: 'circle' },
+      size: { value: 3 },
+    },
+  }),
+};
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,131 @@
+import React from 'react';
+import { ISourceOptions, Container } from '@tsparticles/engine';
+
+interface ParticleTheme {
+    id: string;
+    name: string;
+    icon: string;
+    description: string;
+    /** Whether this theme uses Three.js instead of tsparticles */
+    isThreeJS?: boolean;
+    /** Returns tsparticles config for the given dark mode state */
+    options: (isDark: boolean) => ISourceOptions;
+    /** Solid background color */
+    backgroundColor?: string;
+    /** CSS gradient background */
+    backgroundGradient?: string;
+}
+type ThemeId = 'starline' | 'snow' | 'bubble' | 'stars' | 'firefly' | 'geometry' | 'wave' | 'none';
+
+interface ParticlesBackgroundProps {
+    /**
+     * Theme ID to display. If used inside a `<ParticleProvider>`,
+     * this is optional and the provider's theme will be used.
+     */
+    theme?: ThemeId | string;
+    /** Dark mode toggle — affects particle colors for supported themes */
+    isDark?: boolean;
+    /** Callback when particles finish loading */
+    onLoaded?: (container?: Container) => void;
+    /** Custom CSS class */
+    className?: string;
+    /** Custom inline styles */
+    style?: React.CSSProperties;
+}
+/**
+ * Renders a full-screen particle background.
+ *
+ * Can be used standalone with props:
+ * ```tsx
+ * <ParticlesBackground theme="starline" isDark />
+ * ```
+ *
+ * Or inside a `<ParticleProvider>` for shared state:
+ * ```tsx
+ * <ParticleProvider defaultTheme="snow">
+ *   <ParticlesBackground />
+ * </ParticleProvider>
+ * ```
+ */
+declare const ParticlesBackground: React.FC<ParticlesBackgroundProps>;
+
+interface ThemeSelectorProps {
+    /** Position on screen */
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    /** Accent color for active states */
+    accentColor?: string;
+}
+/**
+ * A floating theme selector button + drawer panel.
+ * Must be used inside a `<ParticleProvider>`.
+ *
+ * ```tsx
+ * <ParticleProvider>
+ *   <ParticlesBackground />
+ *   <ThemeSelector />
+ * </ParticleProvider>
+ * ```
+ */
+declare const ThemeSelector: React.FC<ThemeSelectorProps>;
+
+interface ParticleWaveProps {
+    /** CSS gradient or solid background behind the wave */
+    background?: string;
+    className?: string;
+    style?: React.CSSProperties;
+}
+/**
+ * 3D particle ocean wave rendered with Three.js.
+ * Three.js is loaded dynamically — if not installed, this component renders nothing.
+ */
+declare const ParticleWave: React.FC<ParticleWaveProps>;
+
+interface ParticleContextValue {
+    themeId: string;
+    isDark: boolean;
+    setTheme: (id: string) => void;
+    setDark: (dark: boolean) => void;
+}
+interface ParticleProviderProps {
+    /** Initial/default theme ID */
+    defaultTheme?: ThemeId | string;
+    /** Whether to use dark mode particle colors */
+    isDark?: boolean;
+    /** Persist theme selection to localStorage */
+    persist?: boolean;
+    children: React.ReactNode;
+}
+/**
+ * Provides particle theme state to child components.
+ * Wrap your app (or a subtree) with this provider to use
+ * `<ParticlesBackground />` and `<ThemeSelector />` without explicit props.
+ */
+declare const ParticleProvider: React.FC<ParticleProviderProps>;
+/** Access the current particle theme context. Must be used within a `<ParticleProvider>`. */
+declare const useParticleTheme: () => ParticleContextValue;
+
+declare const baseConfig: Partial<ISourceOptions>;
+/** Default accent colors used by themes that support multi-color particles */
+declare const DEFAULT_COLORS: string[];
+
+declare const starlineTheme: ParticleTheme;
+
+declare const snowTheme: ParticleTheme;
+
+declare const bubbleTheme: ParticleTheme;
+
+declare const starsTheme: ParticleTheme;
+
+declare const fireflyTheme: ParticleTheme;
+
+declare const geometryTheme: ParticleTheme;
+
+declare const waveTheme: ParticleTheme;
+
+/** All built-in particle themes (excludes "none") */
+declare const particleThemes: ParticleTheme[];
+/** Get a theme by its ID. Falls back to starline if not found. */
+declare const getThemeById: (id: string) => ParticleTheme;
+declare const DEFAULT_THEME_ID = "starline";
+
+export { DEFAULT_COLORS, DEFAULT_THEME_ID, ParticleProvider, type ParticleProviderProps, type ParticleTheme, ParticleWave, ParticlesBackground, type ParticlesBackgroundProps, type ThemeId, ThemeSelector, type ThemeSelectorProps, baseConfig, bubbleTheme, fireflyTheme, geometryTheme, getThemeById, particleThemes, snowTheme, starlineTheme, starsTheme, useParticleTheme, waveTheme };

package/dist/index.d.ts

@@ -0,0 +1,131 @@
+import React from 'react';
+import { ISourceOptions, Container } from '@tsparticles/engine';
+
+interface ParticleTheme {
+    id: string;
+    name: string;
+    icon: string;
+    description: string;
+    /** Whether this theme uses Three.js instead of tsparticles */
+    isThreeJS?: boolean;
+    /** Returns tsparticles config for the given dark mode state */
+    options: (isDark: boolean) => ISourceOptions;
+    /** Solid background color */
+    backgroundColor?: string;
+    /** CSS gradient background */
+    backgroundGradient?: string;
+}
+type ThemeId = 'starline' | 'snow' | 'bubble' | 'stars' | 'firefly' | 'geometry' | 'wave' | 'none';
+
+interface ParticlesBackgroundProps {
+    /**
+     * Theme ID to display. If used inside a `<ParticleProvider>`,
+     * this is optional and the provider's theme will be used.
+     */
+    theme?: ThemeId | string;
+    /** Dark mode toggle — affects particle colors for supported themes */
+    isDark?: boolean;
+    /** Callback when particles finish loading */
+    onLoaded?: (container?: Container) => void;
+    /** Custom CSS class */
+    className?: string;
+    /** Custom inline styles */
+    style?: React.CSSProperties;
+}
+/**
+ * Renders a full-screen particle background.
+ *
+ * Can be used standalone with props:
+ * ```tsx
+ * <ParticlesBackground theme="starline" isDark />
+ * ```
+ *
+ * Or inside a `<ParticleProvider>` for shared state:
+ * ```tsx
+ * <ParticleProvider defaultTheme="snow">
+ *   <ParticlesBackground />
+ * </ParticleProvider>
+ * ```
+ */
+declare const ParticlesBackground: React.FC<ParticlesBackgroundProps>;
+
+interface ThemeSelectorProps {
+    /** Position on screen */
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    /** Accent color for active states */
+    accentColor?: string;
+}
+/**
+ * A floating theme selector button + drawer panel.
+ * Must be used inside a `<ParticleProvider>`.
+ *
+ * ```tsx
+ * <ParticleProvider>
+ *   <ParticlesBackground />
+ *   <ThemeSelector />
+ * </ParticleProvider>
+ * ```
+ */
+declare const ThemeSelector: React.FC<ThemeSelectorProps>;
+
+interface ParticleWaveProps {
+    /** CSS gradient or solid background behind the wave */
+    background?: string;
+    className?: string;
+    style?: React.CSSProperties;
+}
+/**
+ * 3D particle ocean wave rendered with Three.js.
+ * Three.js is loaded dynamically — if not installed, this component renders nothing.
+ */
+declare const ParticleWave: React.FC<ParticleWaveProps>;
+
+interface ParticleContextValue {
+    themeId: string;
+    isDark: boolean;
+    setTheme: (id: string) => void;
+    setDark: (dark: boolean) => void;
+}
+interface ParticleProviderProps {
+    /** Initial/default theme ID */
+    defaultTheme?: ThemeId | string;
+    /** Whether to use dark mode particle colors */
+    isDark?: boolean;
+    /** Persist theme selection to localStorage */
+    persist?: boolean;
+    children: React.ReactNode;
+}
+/**
+ * Provides particle theme state to child components.
+ * Wrap your app (or a subtree) with this provider to use
+ * `<ParticlesBackground />` and `<ThemeSelector />` without explicit props.
+ */
+declare const ParticleProvider: React.FC<ParticleProviderProps>;
+/** Access the current particle theme context. Must be used within a `<ParticleProvider>`. */
+declare const useParticleTheme: () => ParticleContextValue;
+
+declare const baseConfig: Partial<ISourceOptions>;
+/** Default accent colors used by themes that support multi-color particles */
+declare const DEFAULT_COLORS: string[];
+
+declare const starlineTheme: ParticleTheme;
+
+declare const snowTheme: ParticleTheme;
+
+declare const bubbleTheme: ParticleTheme;
+
+declare const starsTheme: ParticleTheme;
+
+declare const fireflyTheme: ParticleTheme;
+
+declare const geometryTheme: ParticleTheme;
+
+declare const waveTheme: ParticleTheme;
+
+/** All built-in particle themes (excludes "none") */
+declare const particleThemes: ParticleTheme[];
+/** Get a theme by its ID. Falls back to starline if not found. */
+declare const getThemeById: (id: string) => ParticleTheme;
+declare const DEFAULT_THEME_ID = "starline";
+
+export { DEFAULT_COLORS, DEFAULT_THEME_ID, ParticleProvider, type ParticleProviderProps, type ParticleTheme, ParticleWave, ParticlesBackground, type ParticlesBackgroundProps, type ThemeId, ThemeSelector, type ThemeSelectorProps, baseConfig, bubbleTheme, fireflyTheme, geometryTheme, getThemeById, particleThemes, snowTheme, starlineTheme, starsTheme, useParticleTheme, waveTheme };