jl-particle-interactive 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,192 @@
+# jl-particle-interactive
+
+Particle animations for React — text that comes alive and backgrounds that react to your cursor.
+
+---
+
+## Installation
+
+```bash
+npm install jl-particle-interactive
+```
+
+> Requires React 18+. No global CSS. No extra dependencies.
+
+---
+
+## What it offers
+
+| Feature | Description |
+|---|---|
+| **Text particles** | Thousands of particles that form any text string |
+| **Magnetic hover** | Particles are attracted to the cursor on hover |
+| **Click interactions** | Attract or repel particles on click/tap |
+| **Animated backgrounds** | NET, JELLYFISH, and FOLLOW_POINTER modes |
+| **Customizable** | Colors, shapes, density, speed, and more |
+
+---
+
+## Quick start
+
+```tsx
+import { ParticleCanvas, TextParticleEngine } from 'jl-particle-interactive';
+
+export default function App() {
+  return (
+    <ParticleCanvas height="60vh">
+      <TextParticleEngine text="Hello" />
+    </ParticleCanvas>
+  );
+}
+```
+
+---
+
+## Examples
+
+### Text with a color palette
+
+Assign multiple colors and each particle picks one at random.
+
+```tsx
+<ParticleCanvas height="60vh">
+  <TextParticleEngine
+    text="React"
+    particleColor={['#ff6b6b', '#feca57', '#48dbfb']}
+    particleSize={1.5}
+  />
+</ParticleCanvas>
+```
+
+---
+
+### Repel on click
+
+Particles flee from the cursor while the mouse button is held down.
+
+```tsx
+<ParticleCanvas height="60vh">
+  <TextParticleEngine
+    text="Boom"
+    clickMode="repel"
+    particleEase={2}
+  />
+</ParticleCanvas>
+```
+
+---
+
+### Attract on click
+
+The opposite — particles swarm toward the cursor on press.
+
+```tsx
+<ParticleCanvas height="60vh">
+  <TextParticleEngine
+    text="Pull"
+    clickMode="attract"
+    isMagnet={false}
+  />
+</ParticleCanvas>
+```
+
+---
+
+### Animated NET background
+
+A connected particle network moves behind your content.
+
+```tsx
+<ParticleCanvas
+  height="80vh"
+  background={{
+    name: 'NET',
+    color: '#4ecdc4',
+    lineDistance: 120,
+    density: 0.8,
+  }}
+>
+  <TextParticleEngine text="Network" particleColor="#ffffff" />
+</ParticleCanvas>
+```
+
+---
+
+### Jellyfish background
+
+Smooth, organic blobs that drift across the canvas.
+
+```tsx
+<ParticleCanvas
+  height="80vh"
+  background={{
+    name: 'JELLYFISH',
+    colors: ['#ff6b6b', '#a29bfe', '#00cec9'],
+    colorMode: 'wave',
+  }}
+>
+  <TextParticleEngine text="Fluid" particleColor="#ffffff" />
+</ParticleCanvas>
+```
+
+---
+
+### Dynamic text
+
+Change the `text` prop and the particles re-form automatically.
+
+```tsx
+const words = ['Hello', 'World', 'React'];
+
+export default function Carousel() {
+  const [index, setIndex] = useState(0);
+
+  useEffect(() => {
+    const id = setInterval(() => setIndex(i => (i + 1) % words.length), 2000);
+    return () => clearInterval(id);
+  }, []);
+
+  return (
+    <ParticleCanvas height="60vh">
+      <TextParticleEngine text={words[index]} />
+    </ParticleCanvas>
+  );
+}
+```
+
+---
+
+## API reference
+
+### `<ParticleCanvas>`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `width` | `string \| number` | `'100%'` | Container width |
+| `height` | `string \| number` | `'60vh'` | Container height |
+| `backgroundColor` | `string` | `'#050505'` | Background color |
+| `background` | `BackgroundCanvas` | `{ name: 'NONE' }` | Animated background config |
+| `className` | `string` | `''` | Additional CSS class |
+| `style` | `CSSProperties` | — | Inline style overrides |
+
+### `<TextParticleEngine>`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `text` | `string` | **required** | Text the particles form |
+| `particleColor` | `string \| string[]` | `'255, 255, 255'` | RGB string or array of hex colors |
+| `particleSize` | `number` | `1` | Size multiplier |
+| `particleDensity` | `number` | `1` | Particle count multiplier |
+| `particleEase` | `number` | `1` | Return speed multiplier |
+| `isMagnet` | `boolean` | `true` | Hover attraction effect |
+| `clickMode` | `'none' \| 'attract' \| 'repel'` | `'none'` | Click/tap interaction |
+| `particleShape` | `'circle' \| 'square' \| 'bean'` | `'circle'` | Particle shape |
+| `backgroundColor` | `string` | `'#050505'` | Canvas background (hex) |
+
+> **Color note:** `particleColor` accepts `'R, G, B'` strings (e.g. `'255, 100, 50'`) or hex strings in an array (e.g. `['#ff0000', '#00ff00']`). Alpha is handled internally.
+
+---
+
+## License
+
+MIT

package/dist/components/ParticleCanvas.d.ts

@@ -1,4 +1,5 @@
 import { ReactNode, CSSProperties } from 'react';
+import { BackgroundCanvas } from '../types/background';
 export interface ParticleCanvasProps {
     children?: ReactNode;
     width?: string | number;
@@ -6,5 +7,6 @@ export interface ParticleCanvasProps {
     backgroundColor?: string;
     className?: string;
     style?: CSSProperties;
+    background?: BackgroundCanvas;
 }
-export default function ParticleCanvas({ children, width, height, backgroundColor, className, style, }: ParticleCanvasProps): import("react/jsx-runtime").JSX.Element;
+export default function ParticleCanvas({ children, width, height, backgroundColor, className, style, background, }: ParticleCanvasProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/background/BackgroundParticleEngine.d.ts

@@ -0,0 +1,6 @@
+import { BackgroundCanvas } from '../../types/background';
+export interface BackgroundParticleEngineProps {
+    config: BackgroundCanvas;
+    backgroundColor: string;
+}
+export default function BackgroundParticleEngine({ config, backgroundColor }: BackgroundParticleEngineProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/components/background/FollowPointerParticle.d.ts

@@ -0,0 +1,23 @@
+import { ParticleOrientation } from '../../types/background';
+export declare class FollowPointerParticle {
+    x: number;
+    y: number;
+    baseX: number;
+    baseY: number;
+    z: number;
+    vx: number;
+    vy: number;
+    color: string;
+    targetColor: string | null;
+    colorDelay: number;
+    angleTarget: number;
+    randomSpeed: number;
+    sizeBias: number;
+    scale: number;
+    dirX: number;
+    dirY: number;
+    initialized: boolean;
+    constructor(relX: number, relY: number, color: string);
+    update(mouseX: number | null, mouseY: number | null, swarmX: number, swarmY: number, screenW: number, screenH: number, time: number, orientation?: ParticleOrientation): void;
+    draw(ctx: CanvasRenderingContext2D, time: number, shape?: 'circle' | 'square' | 'bean'): void;
+}

package/dist/components/background/JellyfishParticleEngine.d.ts

@@ -0,0 +1,6 @@
+import { BackgroundCanvas } from '../../types/background';
+export interface JellyfishParticleEngineProps {
+    config: BackgroundCanvas;
+    backgroundColor: string;
+}
+export default function JellyfishParticleEngine({ config, backgroundColor }: JellyfishParticleEngineProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/background/NetParticleEngine.d.ts

@@ -0,0 +1,6 @@
+import { BackgroundCanvas } from '../../types/background';
+export interface NetParticleEngineProps {
+    config: BackgroundCanvas;
+    backgroundColor: string;
+}
+export default function NetParticleEngine({ config, backgroundColor }: NetParticleEngineProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/{Particle.d.ts → text/Particle.d.ts}

@@ -1,4 +1,5 @@
-import { ClickMode } from '../hooks/useParticleInteraction';
+import { ClickMode } from '../../hooks/useParticleInteraction';
+import { ParticleShape } from '../../types';
 export declare class Particle {
     x: number;
     y: number;
@@ -15,7 +16,8 @@ export declare class Particle {
     easeMultiplier: number;
     floatSpeed: number;
     floatOffset: number;
+    randomSpeed: number;
     constructor(w: number, h: number, color?: string | string[]);
     update(time: number, isActive: boolean, mx?: number | null, my?: number | null, isMouseDown?: boolean, isMagnet?: boolean, clickMode?: ClickMode): void;
-    draw(ctx: CanvasRenderingContext2D, shape?: 'circle' | 'square'): void;
+    draw(ctx: CanvasRenderingContext2D, shape?: ParticleShape, time?: number): void;
 }

package/dist/components/{TextParticleEngine.d.ts → text/TextParticleEngine.d.ts}

@@ -1,5 +1,5 @@
-import { ClickMode } from '../hooks/useParticleInteraction';
-import { ParticleShape } from '../types';
+import { ClickMode } from '../../hooks/useParticleInteraction';
+import { ParticleShape } from '../../types';
 export interface TextParticleEngineProps {
     text: string;
     particleColor?: string | string[];
@@ -11,4 +11,4 @@ export interface TextParticleEngineProps {
     particleShape?: ParticleShape;
     backgroundColor?: string;
 }
-export default function TextParticleEngine({ text, particleColor, particleSize, particleDensity, particleEase, isMagnet, clickMode, particleShape, backgroundColor }: TextParticleEngineProps): import("react/jsx-runtime").JSX.Element;
+export default function TextParticleEngine({ text, particleColor, particleSize, particleDensity, particleEase, isMagnet, clickMode, particleShape, backgroundColor, }: TextParticleEngineProps): import("react/jsx-runtime").JSX.Element;

package/dist/hooks/background/useParticleMovement.d.ts

@@ -0,0 +1,5 @@
+import { FollowPointerParticle } from '../../components/background/FollowPointerParticle';
+export declare function useParticleMovement(particle: FollowPointerParticle, swarmX: number, swarmY: number, time: number): {
+    forceX: number;
+    forceY: number;
+};

package/dist/hooks/background/useParticleOrientation.d.ts

@@ -0,0 +1,3 @@
+import { FollowPointerParticle } from '../../components/background/FollowPointerParticle';
+import { ParticleOrientation } from '../../types/background';
+export declare function useParticleOrientation(particle: FollowPointerParticle, dxCenter: number, dyCenter: number, distToCenter: number, orientation: ParticleOrientation, time: number): void;

package/dist/hooks/background/useParticleScaling.d.ts

@@ -0,0 +1,2 @@
+import { FollowPointerParticle } from '../../components/background/FollowPointerParticle';
+export declare function useParticleScaling(particle: FollowPointerParticle, distToCenter: number): void;

package/dist/hooks/background/usePointerTracking.d.ts

@@ -0,0 +1,8 @@
+import { FollowPointerParticle } from '../../components/background/FollowPointerParticle';
+export declare function usePointerTracking(particle: FollowPointerParticle, mouseX: number | null, mouseY: number | null, swarmX: number, swarmY: number, time: number): {
+    forceX: number;
+    forceY: number;
+    dxCenter: number;
+    dyCenter: number;
+    distToCenter: number;
+};

package/dist/hooks/{useTextParticles.d.ts → text/useTextParticles.d.ts}

@@ -1,5 +1,5 @@
 import { default as React } from 'react';
-import { Particle } from '../components/Particle';
+import { Particle } from '../../components/text/Particle';
 declare function getPixelsForText(text: string, width: number, height: number): {
     x: number;
     y: number;

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 export { default as ParticleCanvas } from './components/ParticleCanvas';
 export type { ParticleCanvasProps } from './components/ParticleCanvas';
-export { default as TextParticleEngine } from './components/TextParticleEngine';
-export type { TextParticleEngineProps } from './components/TextParticleEngine';
+export { default as TextParticleEngine } from './components/text/TextParticleEngine';
+export type { TextParticleEngineProps } from './components/text/TextParticleEngine';
 export { useParticleInteraction, getMagnetTarget } from './hooks/useParticleInteraction';
 export type { ClickMode } from './hooks/useParticleInteraction';
-export { useTextParticles } from './hooks/useTextParticles';
+export { useTextParticles } from './hooks/text/useTextParticles';
 export type { ParticleShape, ColorMode } from './types';
+export type { BackgroundModeName, BackgroundCanvas, ParticleOrientation } from './types/background';