magic-canvas-text 1.0.0 → 1.0.1

package/README.md

@@ -1,36 +1,49 @@
-# ✨ Magic canvas text
+# ✨ Magic Canvas Text
 
-**Magic canvas text** is a lightweight npm library for rendering animated, interactive particle-based text using the HTML5 canvas.  
-It supports mouse and touch interactions, gradients, multiple animation start modes, and mobile-optimized behavior.
+**Magic Canvas Text** is a lightweight npm library for rendering animated, interactive particle-based text using the HTML5 canvas.
+It supports mouse and touch interactions, gradients, multiple animation start modes, and mobile‑optimized behavior.
 
-Ideal for landing pages, hero sections, and playful UI elements.
+Perfect for landing pages, hero sections, and playful UI elements.
 
 ---
 
 ## 📦 Installation
 
-Install the package via npm:
+Install the package via npm or yarn:
 
 ```bash
 npm install magic-canvas-text
-````
+```
+
 ```bash
 yarn add magic-canvas-text
 ```
 
+---
+
 ## 🚀 Usage
-Import
-import { initializeText } from "magic-canvas-text;
 
 ### HTML
 
 Create a container element where the canvas will be injected:
 
+```html
 <div class="text-con"></div>
+```
+
+> ⚠️ The container should be empty and have a defined width & height.
+
+---
+
+### JavaScript
+
+```js
+import { initializeText } from "magic-canvas-text";
+
+const element = document.querySelector(".your-class");
 
-### JS
-initializeText({
-  textContainerClass: "text-con",
+const magicText = initializeText({
+  element,
   text: "Magic Text",
   fontSize: 100,
   fontSizeMobile: 30,
@@ -44,62 +57,132 @@ initializeText({
   colorOne: "#ff0000",
   colorTwo: "#00ff00",
   colorThree: "#0000ff",
-  startMode: "auto",
+  startMode: "random",
 });
+```
+
+### ✅ Important API Change
+
+Magic Canvas Text now **expects a DOM element**, not a class name or selector string.
 
-### ## 🔧 Configuration Options
+This makes the API:
 
-| Option | Type | Required | Notes |
-|------|------|----------|-------|
-| `textContainerClass` | `string` | ✅ Yes | Must match an existing DOM element and an empty one|
-| `text` | `string` | ❌ No | Defaults to `"Magic Text"` |
-| `fontSize` | `number` | ✅ Yes | Required for proper font rendering |
-| `fontSizeMobile` | `number` | ✅ Yes | Required for mobile rendering |
-| `textColor` | `string` | ⚠️ Conditional | Defaults to `#000000` |
-| `bgColor` | `string` | ❌ No | Defaults to `#ffffff` |
-| `effectColorApplied` | `boolean` | ⚠️ Recommended | Enables hover color effect |
-| `effectColor` | `string` | ⚠️ Conditional | Required when `effectColorApplied === true` |
-| `effectRadius` | `number` | ❌ No | Defaults to `80` (mobile capped at `100`) |
-| `duration` | `number` | ❌ No | Defaults internally to `0.05` |
-| `gradient` | `boolean` | ⚠️ Recommended | Enables gradient text |
-| `colorOne` | `string` | ⚠️ Conditional | Required when `gradient === true` |
-| `colorTwo` | `string` | ⚠️ Conditional | Required when `gradient === true` |
-| `colorThree` | `string` | ⚠️ Conditional | Required when `gradient === true` |
-| `startMode` | `string` | ❌ No | Defaults to `random` |
+* more predictable
+* framework‑friendly (React, Vue, Svelte)
+* safer against double initialization
 
+---
 
-### 🎬 Start Modes
+## 🔧 Configuration Options
+
+| Option               | Type          | Required       | Description                                          |
+| -------------------- | ------------- | -------------- | ---------------------------------------------------- |
+| `element`            | `HTMLElement` | ✅ Yes          | Target element where the canvas will be mounted      |
+| `text`               | `string`      | ❌ No           | Text to render (default: `"Magic Text"`)             |
+| `fontSize`           | `number`      | ❌ No           | Desktop font size (default: `100`)                   |
+| `fontSizeMobile`     | `number`      | ❌ No           | Mobile font size (default: `30`)                     |
+| `textColor`          | `string`      | ❌ No           | Solid text color (default: `#000000`)                |
+| `bgColor`            | `string`      | ❌ No           | Canvas background color (default: `#ffffff`)         |
+| `effectColorApplied` | `boolean`     | ❌ No           | Enables hover color effect                           |
+| `effectColor`        | `string`      | ⚠️ Conditional | Required if `effectColorApplied === true`            |
+| `effectRadius`       | `number`      | ❌ No           | Interaction radius (default: `80`, mobile max `100`) |
+| `duration`           | `number`      | ❌ No           | Particle easing speed (default: `0.05`)              |
+| `gradient`           | `boolean`     | ❌ No           | Enables gradient text                                |
+| `colorOne`           | `string`      | ⚠️ Conditional | Required when `gradient === true`                    |
+| `colorTwo`           | `string`      | ⚠️ Conditional | Required when `gradient === true`                    |
+| `colorThree`         | `string`      | ⚠️ Conditional | Required when `gradient === true`                    |
+| `startMode`          | `string`      | ❌ No           | Particle start animation mode (default: `random`)    |
 
-- random – particles spawn at random positions
+---
 
-- left – particles animate in from the left
+## 🎬 Start Modes
 
-- center – particles animate from the center
+* `random` – particles spawn at random positions
+* `left` – particles animate in from the left
+* `center` – particles animate from the center
+* `top` – particles animate in from top
+* `bottom` – particles animate in from below
 
-- bottom – particles animate from below
+---
 
-### 🧹 Cleanup
+## 🧹 Cleanup
 
-To remove the canvas, animation loop, and event listeners:
+Each initialization returns an instance with a `destroy()` method.
 
-const magicText = initializeText({ ... });
+```js
+const magicText = initializeText({ element, text: "Hello" });
 
 // later
 magicText.destroy();
+```
+
+This removes:
+
+* the canvas
+* animation loop
+* event listeners
+* internal instance reference
+
+---
 
+## 📱 Mobile Support
 
-### 📱 Mobile Support
+* Touch interaction support
+* Optimized interaction radius
+* Separate mobile font sizing
 
-- Touch events supported
+---
+
+## 🧩 Framework Usage
+
+### React
+
+```js
+const ref = useRef(null);
+
+useEffect(() => {
+  const instance = initializeText({
+    element: ref.current,
+    text: "React Magic",
+  });
+
+  return () => instance?.destroy();
+}, []);
+```
+
+### Vue
+
+```js
+const title = ref(null);
+
+onMounted(() => {
+  initializeText({
+    element: title.value,
+    text: "Vue Magic",
+  });
+});
+```
+
+---
 
-- Optimized interaction radius for performance
+## 🌐 Demo
+
+[Magic Canvas Text Demo](https://luayabbas1981.github.io/magic-text/)
+
+---
 
-- Separate mobile font size configuration
+## 📦 Github
 
-### Links
+[magic-canvas-text on npm](https://github.com/Luayabbas1981/magic-canvas-text)
 
--github [Magic canvas text...](https://github.com/Luayabbas1981/magic-canvas-text)
+---
+
+## 👤 Portfolio
+
+[Portfolio](https://luay-portfolio.interflowcode.de/)
+
+---
 
-### 📄 License
+## 📄 License
 
-MIT License
+MIT License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magic-canvas-text",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "An interactive particle-based text animation library using HTML5 Canvas.",
   "main": "src/index.js",
   "files": [

package/src/index.js

@@ -1,250 +1,248 @@
 // Initialize Magic Text
 function initializeText({
-  textContainerClass,
-  text,
-  fontSize,
-  fontSizeMobile,
-  textColor,
-  bgColor,
-  effectColorApplied,
-  effectColor,
-  effectRadius,
-  duration,
-  gradient,
+  element,
+  text = "Magic Text",
+  fontSize = 100,
+  fontSizeMobile = 30,
+  textColor = "#000",
+  bgColor = "#fff",
+  effectColorApplied = false,
+  effectColor = "#0088ff",
+  effectRadius = 80,
+  duration = 0.05,
+  gradient = false,
   colorOne,
   colorTwo,
   colorThree,
-  startMode,
+  startMode = "random",
 }) {
-  // App values
+  if (typeof window === "undefined") return;
+
+  if (!(element instanceof HTMLElement)) {
+    console.error("MagicText: element must be a DOM element");
+    return;
+  }
+
+  // prevent double init
+  if (element._magicTextInstance) {
+    return element._magicTextInstance;
+  }
+
   const gap = 1;
   let animationId;
   let destroyed = false;
   const particles = [];
+
   const mouse = {
     x: null,
     y: null,
     radius: effectRadius,
   };
-  // Check device
-  if (typeof window === "undefined") return;
+
   const isMobile =
     /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(
       navigator.userAgent,
     );
 
-  const textContainer = document.querySelector(`.${textContainerClass}`);
-  if (!textContainer) {
-    console.error(`No element found with class name "${textContainerClass}".`);
-    return;
-  }
-  textContainer.classList.add("magic-text-container");
+  element.classList.add("magic-text-container");
+
   const canvas = document.createElement("canvas");
   canvas.classList.add("magic-text-canvas");
-  textContainer.appendChild(canvas);
+  element.appendChild(canvas);
+
   const ctx = canvas.getContext("2d");
-  canvas.width = textContainer.clientWidth;
-  canvas.height = textContainer.clientHeight;
-  const canvasWidth = canvas.width;
-  const canvasHeight = canvas.height;
-  canvas.style.backgroundColor = bgColor || "#ffffff";
 
-  // Create particles from text
+  function resizeCanvas() {
+    canvas.width = element.clientWidth;
+    canvas.height = element.clientHeight;
+  }
+
+  resizeCanvas();
+  canvas.style.backgroundColor = bgColor;
+
+  const canvasWidth = () => canvas.width;
+  const canvasHeight = () => canvas.height;
+
+  // ---------- Particle ----------
   class Particle {
-    constructor(ctx, x, y, color, startMode) {
-      this.ctx = ctx;
+    constructor(x, y, color) {
       this.originX = x;
       this.originY = y;
+
       const start = getStartPosition(startMode, x, y);
       this.x = start.x;
       this.y = start.y;
 
       this.color = color;
       this.baseColor = color;
-      this.secondColor = effectColor || "#0088ff";
+      this.secondColor = effectColor;
       this.size = gap;
-      this.ease = Math.random() * 0.1 + (duration || 0.05);
+      this.ease = Math.random() * 0.1 + duration;
       this.pushX = 0;
       this.pushY = 0;
       this.friction = 0.9;
     }
 
     update() {
-      let isHovering = false;
+      let hovering = false;
+
       if (mouse.x !== null) {
         const dx = this.x - mouse.x;
         const dy = this.y - mouse.y;
-        const distance = Math.sqrt(dx * dx + dy * dy);
-        if (distance < mouse.radius) {
-          isHovering = true;
-          const force = (mouse.radius - distance) / mouse.radius;
+        const dist = Math.sqrt(dx * dx + dy * dy);
+
+        if (dist < mouse.radius) {
+          hovering = true;
+          const force = (mouse.radius - dist) / mouse.radius;
           const angle = Math.atan2(dy, dx);
+
           this.pushX += Math.cos(angle) * force * 7 * this.ease * 5;
           this.pushY += Math.sin(angle) * force * 7 * this.ease * 5;
-          if (
-            effectColorApplied &&
-            effectColor &&
-            this.originX > mouse.x &&
-            this.originY > mouse.y
-          ) {
+
+          if (effectColorApplied) {
             this.color = this.secondColor;
           }
         }
       }
 
-      if (!isHovering) {
+      if (!hovering) {
         this.color = this.baseColor;
       }
-      // Apply push force
+
       this.pushX *= this.friction;
       this.pushY *= this.friction;
 
       this.x += this.pushX;
       this.y += this.pushY;
 
-      // Ease back to original text position
       this.x += (this.originX - this.x) * this.ease;
       this.y += (this.originY - this.y) * this.ease;
     }
 
     draw() {
-      this.ctx.fillStyle = this.color;
-      this.ctx.fillRect(this.x, this.y, this.size, this.size);
+      ctx.fillStyle = this.color;
+      ctx.fillRect(this.x, this.y, this.size, this.size);
     }
   }
-  // Draw Text on Canvas
+
+  // ---------- Text ----------
   function drawText() {
-    ctx.clearRect(0, 0, canvasWidth, canvasHeight);
-    const fontFamily = "Arial Black, sans-serif";
+    ctx.clearRect(0, 0, canvasWidth(), canvasHeight());
+
     const activeFontSize = isMobile ? fontSizeMobile : fontSize;
-    ctx.font = `italic bold ${activeFontSize}px ${fontFamily}`;
+    ctx.font = `italic bold ${activeFontSize}px Arial Black, sans-serif`;
     ctx.textAlign = "center";
     ctx.textBaseline = "middle";
+
     if (gradient && colorOne && colorTwo && colorThree) {
-      const grad = ctx.createLinearGradient(0, 0, canvasWidth, canvasHeight);
+      const grad = ctx.createLinearGradient(
+        0,
+        0,
+        canvasWidth(),
+        canvasHeight(),
+      );
       grad.addColorStop(0.3, colorOne);
       grad.addColorStop(0.5, colorTwo);
       grad.addColorStop(0.8, colorThree);
       ctx.fillStyle = grad;
     } else {
-      ctx.fillStyle = textColor || "#000000";
+      ctx.fillStyle = textColor;
     }
-    ctx.fillText(text || "Magic Text", canvasWidth / 2, canvasHeight / 2);
+
+    ctx.fillText(text, canvasWidth() / 2, canvasHeight() / 2);
   }
+
   function createParticlesFromText() {
-    mouse.radius = effectRadius || 80;
-    if (isMobile && mouse.radius > 100) {
-      mouse.radius = 100;
-    }
+    mouse.radius = isMobile ? Math.min(effectRadius, 100) : effectRadius;
     particles.length = 0;
-    startMode = startMode || "random";
+
     drawText();
-    const imageData = ctx.getImageData(0, 0, canvasWidth, canvasHeight);
-    const pixels = imageData.data;
-    ctx.clearRect(0, 0, canvasWidth, canvasHeight);
-    for (let y = 0; y < canvasHeight; y += gap) {
-      for (let x = 0; x < canvasWidth; x += gap) {
-        const index = (y * canvasWidth + x) * 4;
-        const alpha = pixels[index + 3];
-        if (alpha > 0) {
-          const r = pixels[index];
-          const g = pixels[index + 1];
-          const b = pixels[index + 2];
-          const color = `rgb(${r}, ${g}, ${b})`;
-          particles.push(new Particle(ctx, x, y, color, startMode));
+
+    const imageData = ctx.getImageData(0, 0, canvasWidth(), canvasHeight());
+    ctx.clearRect(0, 0, canvasWidth(), canvasHeight());
+
+    for (let y = 0; y < canvasHeight(); y += gap) {
+      for (let x = 0; x < canvasWidth(); x += gap) {
+        const i = (y * canvasWidth() + x) * 4;
+        if (imageData.data[i + 3] > 0) {
+          const r = imageData.data[i];
+          const g = imageData.data[i + 1];
+          const b = imageData.data[i + 2];
+          particles.push(new Particle(x, y, `rgb(${r},${g},${b})`));
         }
       }
     }
   }
-  // Animate
+
   function animate() {
     if (destroyed) return;
-    ctx.clearRect(0, 0, canvasWidth, canvasHeight);
-    particles.forEach((particle) => {
-      particle.update();
-      particle.draw();
+
+    ctx.clearRect(0, 0, canvasWidth(), canvasHeight());
+    particles.forEach((p) => {
+      p.update();
+      p.draw();
     });
 
     animationId = requestAnimationFrame(animate);
   }
-  // Modes
-  function getStartPosition(mode, originX, originY) {
+
+  function getStartPosition(mode, ox, oy) {
     switch (mode) {
       case "center":
-        return {
-          x: canvasWidth / 2,
-          y: canvasHeight / 2,
-        };
+        return { x: canvasWidth() / 2, y: canvasHeight() / 2 };
       case "bottom":
-        return {
-          x: originX,
-          y: canvasHeight + 20,
-        };
-
+        return { x: ox, y: canvasHeight() + 20 };
+      case "top":
+        return { x: ox, y: -20 };
       case "left":
-        return {
-          x: -20,
-          y: originY,
-        };
-
-      case "random":
+        return { x: -20, y: oy };
       default:
         return {
-          x: Math.random() * canvasWidth,
-          y: Math.random() * canvasHeight,
+          x: Math.random() * canvasWidth(),
+          y: Math.random() * canvasHeight(),
         };
     }
   }
-  // Mouse events
-  function onMouseMove(e) {
-    const rect = canvas.getBoundingClientRect();
-    mouse.x = e.clientX - rect.left;
-    mouse.y = e.clientY - rect.top;
-  }
-  function onMouseLeave() {
-    mouse.x = null;
-    mouse.y = null;
-  }
-  function onTouchStart(e) {
-    const rect = canvas.getBoundingClientRect();
-    const touch = e.touches[0];
-    mouse.x = touch.clientX - rect.left;
-    mouse.y = touch.clientY - rect.top;
-  }
-  function onTouchMove(e) {
+
+  // ---------- Events ----------
+  function updateMouse(e, touch = false) {
     const rect = canvas.getBoundingClientRect();
-    const touch = e.touches[0];
-    mouse.x = touch.clientX - rect.left;
-    mouse.y = touch.clientY - rect.top;
+    const p = touch ? e.touches[0] : e;
+    mouse.x = p.clientX - rect.left;
+    mouse.y = p.clientY - rect.top;
   }
-  function onTouchEnd() {
-    mouse.x = null;
-    mouse.y = null;
+
+  function resetMouse() {
+    mouse.x = mouse.y = null;
   }
 
-  canvas.addEventListener("mousemove", onMouseMove);
-  canvas.addEventListener("mouseleave", onMouseLeave);
-  canvas.addEventListener("touchstart", onTouchStart, { passive: true });
-  canvas.addEventListener("touchmove", onTouchMove, { passive: true });
-  canvas.addEventListener("touchend", onTouchEnd);
-  // Cleanup function
+  canvas.addEventListener("mousemove", updateMouse);
+  canvas.addEventListener("mouseleave", resetMouse);
+  canvas.addEventListener("touchstart", (e) => updateMouse(e, true), {
+    passive: true,
+  });
+  canvas.addEventListener("touchmove", (e) => updateMouse(e, true), {
+    passive: true,
+  });
+  canvas.addEventListener("touchend", resetMouse);
+
+  // ---------- Destroy ----------
   function destroy() {
     if (destroyed) return;
     destroyed = true;
-    cancelAnimationFrame(animationId);
-
-    canvas.removeEventListener("mousemove", onMouseMove);
-    canvas.removeEventListener("mouseleave", onMouseLeave);
-    canvas.removeEventListener("touchstart", onTouchStart);
-    canvas.removeEventListener("touchmove", onTouchMove);
-    canvas.removeEventListener("touchend", onTouchEnd);
 
+    cancelAnimationFrame(animationId);
     canvas.remove();
     particles.length = 0;
+
+    delete element._magicTextInstance;
   }
-  // Initial Setup
+
+  // ---------- Init ----------
   createParticlesFromText();
   animate();
-  return { destroy };
+
+  element._magicTextInstance = { destroy };
+  return element._magicTextInstance;
 }
 export { initializeText };