jl-particle-interactive 0.1.0 → 0.2.1

package/README.md

@@ -0,0 +1,236 @@
+# jl-particle-interactive — React Canvas Particle Animations
+
+[![npm version](https://img.shields.io/npm/v/jl-particle-interactive)](https://www.npmjs.com/package/jl-particle-interactive)
+[![npm downloads](https://img.shields.io/npm/dm/jl-particle-interactive)](https://www.npmjs.com/package/jl-particle-interactive)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/jl-particle-interactive)](https://bundlephobia.com/package/jl-particle-interactive)
+[![license](https://img.shields.io/npm/l/jl-particle-interactive)](https://github.com/cjorgeluis122333/jl-particles-interactive/blob/main/LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue)](https://www.typescriptlang.org/)
+
+A canvas-based React library for rendering text and backgrounds as thousands of animated particles. Letters form from particle swarms, respond to magnetic hover, attract or repel on click, and backgrounds come alive with NET graphs, JELLYFISH glows, or pointer-following swarms. Built with zero runtime dependencies, full TypeScript support, and DPR-aware rendering for sharp output on retina displays.
+
+> Requires React 18+. No global CSS. Zero runtime dependencies.
+
+---
+
+## Why jl-particle-interactive?
+
+| Feature | jl-particle-interactive | tsparticles | particles.js |
+|---|---|---|---|
+| **Text that forms from particles** | ✓ (native, spatial coherence) | Plugin only (complex setup) | ✗ |
+| **Spring physics + float noise** | ✓ | ✗ | ✗ |
+| **Magnetic hover / click interact** | ✓ (attract & repel) | ✗ | ✗ |
+| **Ready-made background presets** | ✓ NET, JELLYFISH, FOLLOW_POINTER | General engine (DIY) | General engine (DIY) |
+| **Runtime dependencies** | **Zero** | 14+ packages | 0 (vanilla JS only) |
+| **React integration** | Native React hooks | Wrapper package needed | Manual integration |
+| **TypeScript** | Strict mode | Partial | ✗ |
+| **DPR-aware (retina)** | ✓ | ✗ | ✗ |
+
+---
+
+## Use cases
+
+- **Hero section animated titles** — Text materializes from particle chaos on page load
+- **Loading screens** — Words form and dissolve while content loads
+- **Interactive word carousels** — Cycle through words; particles re-form smoothly
+- **Animated backgrounds** — NET graph, JELLYFISH glow, or pointer-following swarm behind any content
+
+---
+
+## Installation
+
+```bash
+npm install jl-particle-interactive
+```
+
+---
+
+## Framework compatibility
+
+| Framework | Supported |
+|---|---|
+| Vite + React | ✓ |
+| Next.js (App Router & Pages) | ✓ (client components only — add `'use client'`) |
+| Create React App | ✓ |
+| Remix | ✓ (client-side only) |
+| Astro | ✓ (inside `client:only` components) |
+| TypeScript | ✓ (strict mode, declarations included) |
+
+---
+
+## What it offers
+
+| Feature | Description |
+|---|---|
+| **Text particles** | Thousands of canvas particles that form any text string using pixel-sampling with spatial coherence — letters look sharp at any size |
+| **Magnetic hover** | Particles are attracted to the cursor on hover (~173px radius spring force) |
+| **Click interactions** | Attract or repel particles on click/tap — particles flee or swarm toward the pointer |
+| **Animated backgrounds** | NET (connected node graph), JELLYFISH (organic glow rings), and FOLLOW_POINTER (swarm) modes |
+| **Spring physics** | Each particle uses spring + friction + float-noise physics — movement feels natural, never robotic |
+| **Customizable** | Colors (hex or RGB palettes), shapes (circle, square, bean), density, speed, ease, 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';