particle-network-bg 0.0.1

package/README.md

@@ -0,0 +1,198 @@
+# particle-network-bg
+
+Interactive particle network animation for backgrounds. Typed, zero dependencies (core), works with vanilla JS, React, or any framework.
+
+> **Note:** The demos are in the [`demo/`](./demo) directory.
+
+## Demo
+
+Live demos (after enabling [GitHub Pages](https://docs.github.com/en/pages)):
+
+- **[Vanilla JS](https://aliotadi.github.io/particle-network-bg/vanilla/)**
+- **[React](https://aliotadi.github.io/particle-network-bg/react/)**
+
+Run locally:
+
+```bash
+# Vanilla
+cd lib/demo/vanilla && npm install && npm run dev
+
+# React
+cd lib/demo/react && npm install && npm run dev
+```
+
+## Install
+
+```bash
+npm install particle-network-bg
+```
+
+## Usage
+
+### Vanilla JS
+
+```js
+import { ParticleNetwork } from "particle-network-bg";
+
+const canvas = document.getElementById("canvas");
+const network = new ParticleNetwork(canvas, {
+  particleCount: 100,
+  particleColor: "#000000",
+  lineColor: "#000000",
+  backgroundColor: "#ffffff",
+});
+
+network.start();
+
+// Later: cleanup
+network.cleanup();
+```
+
+### React – Component
+
+```jsx
+import { ParticleNetworkBg } from "particle-network-bg/react";
+
+function App() {
+  return (
+    <ParticleNetworkBg
+      config={{
+        particleCount: 80,
+        gradientEnabled: true,
+        gradientColors: ["#667eea", "#764ba2"],
+      }}
+      style={{ width: "100%", height: "100vh" }}
+    />
+  );
+}
+```
+
+### React – Hook
+
+```jsx
+import { useParticleNetwork } from "particle-network-bg/react";
+
+function App() {
+  const canvasRef = useParticleNetwork({
+    particleCount: 80,
+    gradientEnabled: true,
+    gradientColors: ["#667eea", "#764ba2"],
+  });
+
+  return (
+    <canvas
+      ref={canvasRef}
+      style={{ display: "block", width: "100%", height: "100vh" }}
+    />
+  );
+}
+```
+
+> **Note:** Config is applied on mount. The canvas resizes to the window.
+
+## Configuration
+
+| Option                   | Type                   | Default                  | Description                                              |
+| ------------------------ | ---------------------- | ------------------------ | -------------------------------------------------------- |
+| `particleCount`          | number                 | 100                      | Number of particles                                      |
+| `minRadius`              | number                 | 2                        | Min particle size (px)                                   |
+| `maxRadius`              | number                 | 6                        | Max particle size (px)                                   |
+| `particleColor`          | string                 | `#000000`                | Particle color (hex)                                     |
+| `lineColor`              | string                 | `#000000`                | Connection line color (hex)                              |
+| `lineWidth`              | number                 | 1                        | Line width                                               |
+| `lineOpacity`            | number                 | 0.2                      | Line opacity (0–1)                                       |
+| `maxDistance`            | number                 | 150                      | Max connection distance (px)                             |
+| `moveSpeed`              | number                 | 1                        | Particle movement speed                                  |
+| `backgroundColor`        | string                 | `#ffffff`                | Background color (hex)                                   |
+| `backgroundOpacity`      | number                 | 1                        | Background opacity (0–1)                                 |
+| `particleOpacity`        | number                 | 1                        | Particle opacity (0–1)                                   |
+| `mouseRadius`            | number                 | 200                      | Mouse interaction radius                                 |
+| `mouseInteraction`       | boolean                | true                     | Enable mouse repel effect                                |
+| `pulseEnabled`           | boolean                | true                     | Enable pulse animation                                   |
+| `pulseSpeed`             | number                 | 0                        | Pulse speed                                              |
+| `depthEffectEnabled`     | boolean                | true                     | 3D depth effect                                          |
+| `depthSpeed`             | number                 | 0.02                     | Depth animation speed                                    |
+| `gradientEnabled`        | boolean                | false                    | Use gradient background                                  |
+| `gradientType`           | `"linear" \| "radial"` | `"linear"`               | Gradient type                                            |
+| `gradientColors`         | string[]               | `["#667eea", "#764ba2"]` | Gradient colors (hex)                                    |
+| `gradientStops`          | number[]               | auto                     | Color stops (0–1), optional                              |
+| `gradientSpeed`          | number                 | 0.02                     | Gradient animation speed                                 |
+| `gradientMouseReaction`  | boolean                | true                     | **Radial only:** Gradient center follows mouse           |
+| `gradientMouseInfluence` | number                 | 0.5                      | **Radial only:** Mouse influence strength (0–1)          |
+| `gradientAngle`          | number                 | 0                        | **Linear spin mode:** Initial rotation angle (degrees)   |
+| `gradientRadius`         | number                 | 1                        | **Radial:** Gradient radius multiplier                   |
+| `gradientSpin`           | boolean                | false                    | **Linear:** `true` = rotate, `false` = flow continuously |
+| `gradientFlowAngle`      | number                 | 45                       | **Linear flow mode:** Direction of color flow (degrees)  |
+| `gradientOrbitRadius`    | number                 | 0.3                      | **Radial:** Orbit radius for center movement (0–1)       |
+
+## Gradient Examples
+
+### Linear Gradient (Continuous Flow)
+
+```js
+new ParticleNetwork(canvas, {
+  gradientEnabled: true,
+  gradientType: "linear",
+  gradientColors: ["#667eea", "#764ba2", "#f093fb"],
+  gradientSpeed: 0.02,
+  gradientSpin: false, // Flow mode (colors slide continuously)
+  gradientFlowAngle: 45, // Flow direction in degrees
+});
+```
+
+### Linear Gradient (Spin/Rotate)
+
+```js
+new ParticleNetwork(canvas, {
+  gradientEnabled: true,
+  gradientType: "linear",
+  gradientColors: ["#667eea", "#764ba2"],
+  gradientSpeed: 0.01,
+  gradientSpin: true, // Rotate the gradient angle
+  gradientAngle: 0, // Starting angle
+});
+```
+
+### Radial Gradient (Mouse Interactive)
+
+```js
+new ParticleNetwork(canvas, {
+  gradientEnabled: true,
+  gradientType: "radial",
+  gradientColors: ["#667eea", "#764ba2", "#f093fb"],
+  gradientSpeed: 0.02,
+  gradientMouseReaction: true, // Center follows mouse
+  gradientMouseInfluence: 0.5, // 0 = no effect, 1 = full follow
+  gradientOrbitRadius: 0.3, // Orbit radius when no mouse
+});
+```
+
+## API
+
+### React (`particle-network-bg/react`)
+
+- `ParticleNetworkBg` – Wrapper component. Props: `config`, `style`, `className`
+- `useParticleNetwork(config?)` – Hook that returns a canvas ref
+
+### `ParticleNetwork` (vanilla)
+
+- `start()` – Start animation
+- `stop()` – Stop animation
+- `cleanup()` – Remove listeners and stop (call on unmount)
+- `updateConfig(property, value)` – Update a config value at runtime
+- `reset(defaults)` – Reset to new defaults
+
+### Types
+
+```ts
+import type {
+  ParticleNetworkConfig,
+  Particle,
+  GradientType,
+} from "particle-network-bg";
+```
+
+## License
+
+MIT
+

package/dist/chunk-WD7BVW5Q.mjs

@@ -0,0 +1,449 @@
+// src/index.ts
+var DEFAULT_CONFIG = {
+  particleCount: 100,
+  minRadius: 2,
+  maxRadius: 6,
+  particleColor: "#000000",
+  lineColor: "#000000",
+  lineWidth: 1,
+  lineOpacity: 0.2,
+  maxDistance: 150,
+  moveSpeed: 1,
+  backgroundColor: "#ffffff",
+  backgroundOpacity: 1,
+  particleOpacity: 1,
+  mouseRadius: 200,
+  mouseInteraction: true,
+  pulseEnabled: true,
+  pulseSpeed: 0,
+  depthEffectEnabled: true,
+  depthSpeed: 0.02,
+  gradientEnabled: false,
+  gradientType: "linear",
+  gradientColors: ["#667eea", "#764ba2"],
+  gradientSpeed: 0.02,
+  gradientMouseReaction: true,
+  gradientMouseInfluence: 0.5,
+  gradientAngle: 0,
+  gradientRadius: 1,
+  gradientSpin: false,
+  gradientFlowAngle: 45,
+  gradientOrbitRadius: 0.3
+};
+var HEX_COLOR_REGEX = /^#[0-9A-Fa-f]{6}$/;
+var ParticleNetwork = class {
+  constructor(canvas, config = {}) {
+    this.particles = [];
+    this.animationId = null;
+    this.isRunning = false;
+    this.mousePosition = null;
+    this.pulseAngle = 0;
+    this.gradientAngle = 0;
+    this.gradientFlowOffset = 0;
+    this.gradientCenter = { x: 0, y: 0 };
+    this.smoothedMouseAngle = 0;
+    this.canvas = canvas;
+    const ctx = canvas.getContext("2d", { alpha: true });
+    if (!ctx) {
+      throw new Error("Could not initialize canvas context");
+    }
+    this.ctx = ctx;
+    this.config = this.validateConfig({ ...DEFAULT_CONFIG, ...config });
+    this.boundHandleResize = this.handleResize.bind(this);
+    this.boundHandleMouseMove = this.handleMouseMove.bind(this);
+    this.boundHandleMouseLeave = this.handleMouseLeave.bind(this);
+    this.handleResize();
+    this.createParticles();
+    this.setupEventListeners();
+  }
+  validateConfig(config) {
+    const numericParams = [
+      "particleCount",
+      "minRadius",
+      "maxRadius",
+      "lineWidth",
+      "lineOpacity",
+      "maxDistance",
+      "moveSpeed",
+      "backgroundOpacity",
+      "particleOpacity",
+      "mouseRadius",
+      "pulseSpeed",
+      "depthSpeed",
+      "gradientSpeed",
+      "gradientMouseInfluence",
+      "gradientAngle",
+      "gradientRadius",
+      "gradientFlowAngle",
+      "gradientOrbitRadius"
+    ];
+    for (const param of numericParams) {
+      const val = config[param];
+      if (typeof val !== "number" || isNaN(val)) {
+        throw new Error(`Invalid ${param}: must be a number`);
+      }
+    }
+    const booleanParams = [
+      "mouseInteraction",
+      "pulseEnabled",
+      "depthEffectEnabled",
+      "gradientEnabled",
+      "gradientMouseReaction",
+      "gradientSpin"
+    ];
+    for (const param of booleanParams) {
+      if (typeof config[param] !== "boolean") {
+        throw new Error(`Invalid ${param}: must be a boolean`);
+      }
+    }
+    const colorParams = [
+      "backgroundColor",
+      "particleColor",
+      "lineColor"
+    ];
+    for (const param of colorParams) {
+      if (!HEX_COLOR_REGEX.test(config[param])) {
+        throw new Error(`Invalid ${param}: must be a valid hex color`);
+      }
+    }
+    if (config.gradientEnabled) {
+      if (!Array.isArray(config.gradientColors) || config.gradientColors.length < 2) {
+        throw new Error(
+          "gradientColors must be an array of at least 2 hex colors"
+        );
+      }
+      for (const c of config.gradientColors) {
+        if (!HEX_COLOR_REGEX.test(c)) {
+          throw new Error(`Invalid gradient color: ${c} must be valid hex`);
+        }
+      }
+      if (config.gradientType !== "linear" && config.gradientType !== "radial") {
+        throw new Error("gradientType must be 'linear' or 'radial'");
+      }
+      if (config.gradientStops) {
+        if (config.gradientStops.length !== config.gradientColors.length) {
+          throw new Error(
+            "gradientStops length must match gradientColors length"
+          );
+        }
+        for (let i = 0; i < config.gradientStops.length; i++) {
+          const s = config.gradientStops[i];
+          if (typeof s !== "number" || s < 0 || s > 1) {
+            throw new Error(`gradientStops[${i}] must be a number 0-1`);
+          }
+          if (i > 0 && s <= config.gradientStops[i - 1]) {
+            throw new Error("gradientStops must be strictly increasing");
+          }
+        }
+      }
+    }
+    return config;
+  }
+  setupEventListeners() {
+    window.addEventListener("resize", this.boundHandleResize);
+    this.canvas.addEventListener("mousemove", this.boundHandleMouseMove);
+    this.canvas.addEventListener("mouseleave", this.boundHandleMouseLeave);
+  }
+  cleanup() {
+    window.removeEventListener("resize", this.boundHandleResize);
+    this.canvas.removeEventListener("mousemove", this.boundHandleMouseMove);
+    this.canvas.removeEventListener("mouseleave", this.boundHandleMouseLeave);
+    this.stop();
+  }
+  handleMouseMove(e) {
+    const rect = this.canvas.getBoundingClientRect();
+    this.mousePosition = {
+      x: e.clientX - rect.left,
+      y: e.clientY - rect.top
+    };
+  }
+  handleMouseLeave() {
+    this.mousePosition = null;
+  }
+  handleResize() {
+    this.canvas.width = window.innerWidth;
+    this.canvas.height = window.innerHeight;
+    this.gradientCenter = {
+      x: this.canvas.width / 2,
+      y: this.canvas.height / 2
+    };
+  }
+  createParticles() {
+    this.particles = [];
+    for (let i = 0; i < this.config.particleCount; i++) {
+      const sizeRange = this.config.maxRadius - this.config.minRadius;
+      const randomSize = Math.random() * sizeRange + this.config.minRadius;
+      this.particles.push({
+        x: Math.random() * this.canvas.width,
+        y: Math.random() * this.canvas.height,
+        dx: (Math.random() - 0.5) * this.config.moveSpeed,
+        dy: (Math.random() - 0.5) * this.config.moveSpeed,
+        radius: randomSize,
+        z: Math.random(),
+        dz: (Math.random() - 0.5) * this.config.depthSpeed * 2
+      });
+    }
+  }
+  updateParticles() {
+    this.particles.forEach((particle) => {
+      if (this.config.depthEffectEnabled) {
+        particle.z += particle.dz;
+        if (particle.z <= 0) {
+          particle.z = 0;
+          particle.dz = Math.abs(particle.dz);
+        } else if (particle.z >= 1) {
+          particle.z = 1;
+          particle.dz = -Math.abs(particle.dz);
+        }
+      }
+      if (this.config.pulseEnabled) {
+        this.pulseAngle += this.config.pulseSpeed;
+        const pulseScale = Math.sin(this.pulseAngle) * 0.5 + 1;
+        particle.currentRadius = particle.radius * pulseScale;
+      } else {
+        particle.currentRadius = particle.radius;
+      }
+      if (this.config.depthEffectEnabled) {
+        const depthScale = 0.4 + 0.6 * particle.z;
+        particle.currentRadius = (particle.currentRadius ?? particle.radius) * depthScale;
+      }
+      particle.x += particle.dx;
+      particle.y += particle.dy;
+      if (this.config.mouseInteraction && this.mousePosition) {
+        const dx = this.mousePosition.x - particle.x;
+        const dy = this.mousePosition.y - particle.y;
+        const distance = Math.sqrt(dx * dx + dy * dy);
+        if (distance < this.config.mouseRadius) {
+          const force = (this.config.mouseRadius - distance) / this.config.mouseRadius;
+          const angle = Math.atan2(dy, dx);
+          const repelX = Math.cos(angle) * force * 0.5;
+          const repelY = Math.sin(angle) * force * 0.5;
+          particle.dx -= repelX;
+          particle.dy -= repelY;
+        }
+      }
+      if (particle.x < 0 || particle.x > this.canvas.width) {
+        particle.dx = -particle.dx;
+      }
+      if (particle.y < 0 || particle.y > this.canvas.height) {
+        particle.dy = -particle.dy;
+      }
+      const speed = Math.sqrt(
+        particle.dx * particle.dx + particle.dy * particle.dy
+      );
+      if (speed > this.config.moveSpeed) {
+        particle.dx = particle.dx / speed * this.config.moveSpeed;
+        particle.dy = particle.dy / speed * this.config.moveSpeed;
+      }
+    });
+  }
+  drawParticles() {
+    this.ctx.fillStyle = this.config.particleColor;
+    this.particles.forEach((particle) => {
+      let opacity = this.config.particleOpacity;
+      if (this.config.depthEffectEnabled) {
+        opacity *= 0.6 + 0.4 * particle.z;
+      }
+      this.ctx.globalAlpha = opacity;
+      this.ctx.beginPath();
+      this.ctx.arc(
+        particle.x,
+        particle.y,
+        particle.currentRadius ?? particle.radius,
+        0,
+        Math.PI * 2
+      );
+      this.ctx.fill();
+    });
+    this.ctx.globalAlpha = 1;
+  }
+  drawConnections() {
+    for (let i = 0; i < this.particles.length; i++) {
+      for (let j = i + 1; j < this.particles.length; j++) {
+        const dx = this.particles[i].x - this.particles[j].x;
+        const dy = this.particles[i].y - this.particles[j].y;
+        const distance = Math.sqrt(dx * dx + dy * dy);
+        if (distance < this.config.maxDistance) {
+          const opacity = 1 - distance / this.config.maxDistance;
+          const color = this.hexToRgb(this.config.lineColor);
+          this.ctx.beginPath();
+          this.ctx.strokeStyle = `rgba(${color}, ${opacity * this.config.lineOpacity})`;
+          this.ctx.lineWidth = this.config.lineWidth;
+          this.ctx.moveTo(this.particles[i].x, this.particles[i].y);
+          this.ctx.lineTo(this.particles[j].x, this.particles[j].y);
+          this.ctx.stroke();
+        }
+      }
+    }
+  }
+  drawBackground() {
+    this.ctx.globalAlpha = this.config.backgroundOpacity;
+    if (this.config.gradientEnabled) {
+      const w = this.canvas.width;
+      const h = this.canvas.height;
+      const colors = this.config.gradientColors;
+      const stops = this.config.gradientStops ?? colors.map((_, i) => i / (colors.length - 1));
+      if (this.config.gradientType === "linear") {
+        const baseAngleRad = this.config.gradientFlowAngle * Math.PI / 180;
+        const diag = Math.sqrt(w * w + h * h);
+        let angle;
+        let offsetX = 0;
+        let offsetY = 0;
+        if (this.config.gradientSpin) {
+          this.gradientAngle += this.config.gradientSpeed;
+          angle = this.gradientAngle;
+        } else {
+          this.gradientFlowOffset = (this.gradientFlowOffset + this.config.gradientSpeed) % (Math.PI * 2);
+          const t = this.gradientFlowOffset / (Math.PI * 2);
+          offsetX = Math.cos(baseAngleRad) * t * diag;
+          offsetY = Math.sin(baseAngleRad) * t * diag;
+          angle = baseAngleRad;
+        }
+        const cos = Math.cos(angle);
+        const sin = Math.sin(angle);
+        const lineLen = this.config.gradientSpin ? diag / 2 : diag * 1.5;
+        const cx = w / 2 + offsetX;
+        const cy = h / 2 + offsetY;
+        const x1 = cx - cos * lineLen;
+        const y1 = cy - sin * lineLen;
+        const x2 = cx + cos * lineLen;
+        const y2 = cy + sin * lineLen;
+        const gradient = this.ctx.createLinearGradient(x1, y1, x2, y2);
+        if (this.config.gradientSpin) {
+          colors.forEach((c, i) => gradient.addColorStop(stops[i], c));
+        } else {
+          const extColors = [...colors, colors[0]];
+          for (let rep = 0; rep < 3; rep++) {
+            extColors.forEach((c, i) => {
+              gradient.addColorStop((rep + i / (extColors.length - 1)) / 3, c);
+            });
+          }
+        }
+        this.ctx.fillStyle = gradient;
+      } else {
+        const cx = w / 2;
+        const cy = h / 2;
+        const orbitR = Math.min(w, h) * this.config.gradientOrbitRadius;
+        let targetX;
+        let targetY;
+        this.gradientAngle += this.config.gradientSpeed;
+        targetX = cx + Math.cos(this.gradientAngle) * orbitR;
+        targetY = cy + Math.sin(this.gradientAngle) * orbitR;
+        if (this.config.gradientMouseReaction && this.mousePosition) {
+          const influence = this.config.gradientMouseInfluence;
+          targetX = targetX + (this.mousePosition.x - targetX) * influence;
+          targetY = targetY + (this.mousePosition.y - targetY) * influence;
+        }
+        const lerpFactor = 0.03;
+        this.gradientCenter.x += (targetX - this.gradientCenter.x) * lerpFactor;
+        this.gradientCenter.y += (targetY - this.gradientCenter.y) * lerpFactor;
+        this.gradientFlowOffset = (this.gradientFlowOffset + this.config.gradientSpeed) % (Math.PI * 2);
+        const t = this.gradientFlowOffset / (Math.PI * 2);
+        const r = Math.max(w, h) * this.config.gradientRadius * 2;
+        const gradient = this.ctx.createRadialGradient(
+          this.gradientCenter.x,
+          this.gradientCenter.y,
+          0,
+          this.gradientCenter.x,
+          this.gradientCenter.y,
+          r
+        );
+        const extColors = [...colors, colors[0]];
+        const entries = [];
+        for (let rep = 0; rep < 3; rep++) {
+          extColors.forEach((c, i) => {
+            const base = (rep + i / (extColors.length - 1)) / 3;
+            entries.push({ stop: (base + t) % 1, color: c });
+          });
+        }
+        entries.sort((a, b) => a.stop - b.stop);
+        if (entries[0].stop > 1e-3) {
+          entries.unshift({ stop: 0, color: entries[entries.length - 1].color });
+        }
+        if (entries[entries.length - 1].stop < 0.999) {
+          entries.push({ stop: 1, color: entries[0].color });
+        }
+        entries.forEach((e) => gradient.addColorStop(e.stop, e.color));
+        this.ctx.fillStyle = gradient;
+      }
+    } else {
+      this.ctx.fillStyle = this.config.backgroundColor;
+    }
+    this.ctx.fillRect(0, 0, this.canvas.width, this.canvas.height);
+    this.ctx.globalAlpha = 1;
+  }
+  hexToRgb(hex) {
+    hex = hex.replace(/^#/, "");
+    if (hex.length === 3) {
+      hex = hex.split("").map((c) => c + c).join("");
+    }
+    const result = /^([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
+    if (!result) return "255,255,255";
+    return result.slice(1).map((n) => parseInt(n, 16)).join(",");
+  }
+  stop() {
+    this.isRunning = false;
+    if (this.animationId !== null) {
+      cancelAnimationFrame(this.animationId);
+      this.animationId = null;
+    }
+  }
+  start() {
+    if (!this.isRunning) {
+      this.isRunning = true;
+      this.animate();
+    }
+  }
+  animate() {
+    this.drawBackground();
+    this.updateParticles();
+    this.drawParticles();
+    this.drawConnections();
+    if (this.isRunning) {
+      this.animationId = requestAnimationFrame(() => this.animate());
+    }
+  }
+  updateConfig(property, value) {
+    this.config[property] = value;
+    if (property === "particleCount") {
+      this.createParticles();
+    }
+    if (property === "moveSpeed") {
+      this.particles.forEach((particle) => {
+        const currentSpeed = Math.sqrt(
+          particle.dx * particle.dx + particle.dy * particle.dy
+        );
+        if (currentSpeed > 0) {
+          particle.dx = particle.dx / currentSpeed * value;
+          particle.dy = particle.dy / currentSpeed * value;
+        }
+      });
+    }
+    if (property === "minRadius" || property === "maxRadius") {
+      this.particles.forEach((particle) => {
+        const sizeRange = this.config.maxRadius - this.config.minRadius;
+        const randomSize = Math.random() * sizeRange + this.config.minRadius;
+        particle.radius = randomSize;
+      });
+    }
+    if (property === "depthSpeed") {
+      this.particles.forEach((particle) => {
+        const sign = particle.dz >= 0 ? 1 : -1;
+        particle.dz = sign * (Math.random() * 0.5 + 0.5) * value * 2;
+      });
+    }
+  }
+  reset(defaults) {
+    this.config = this.validateConfig({
+      ...DEFAULT_CONFIG,
+      ...defaults
+    });
+    this.createParticles();
+    this.stop();
+    this.start();
+  }
+};
+
+export {
+  ParticleNetwork
+};