@amphore-dev/shades 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amphore Dev
+
+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,317 @@
+# 🎨 Shades
+
+Library for creating animated shape visualizations on canvas.
+
+## 🚀 Live Demo
+
+[View the interactive demo](https://amphore-dev.github.io/Shades/) (deployed from the [`example/`](./example/) directory)
+
+## Features
+
+✨ **Framework-agnostic** - Works with React, Vue, Angular, Svelte, or vanilla JavaScript  
+🎯 **TypeScript** - Full type safety and IntelliSense support  
+🎨 **Multiple shapes** - Circles, squares, triangles, text, spirals, and images  
+🎭 **Smooth animations** - Buttery smooth 60fps animations  
+⚡ **Performant** - Optimized canvas rendering  
+🎮 **Interactive** - Mouse/touch controls and zoom  
+🐛 **Debug mode** - Built-in performance monitoring
+
+## Installation
+
+```bash
+npm install @amphore-dev/shades
+# or
+yarn add @amphore-dev/shades
+```
+
+## Quick Start
+
+### Vanilla JavaScript/TypeScript
+
+```typescript
+import { ShadesEngine } from "@amphore-dev/shades";
+
+const canvas = document.getElementById("myCanvas") as HTMLCanvasElement;
+
+const shades = new ShadesEngine(canvas, {
+  randomized: true,
+  debug: false,
+});
+
+shades.generate(); // Generate shapes
+shades.start(); // Start animation
+```
+
+### With React
+
+```tsx
+import { useEffect, useRef } from "react";
+import { ShadesEngine } from "@amphore-dev/shades";
+
+function ShadesComponent() {
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+  const shadesRef = useRef<ShadesEngine>();
+
+  useEffect(() => {
+    if (canvasRef.current) {
+      shadesRef.current = new ShadesEngine(canvasRef.current, {
+        randomized: true,
+      });
+
+      shadesRef.current.generate();
+      shadesRef.current.start();
+    }
+
+    return () => {
+      shadesRef.current?.destroy();
+    };
+  }, []);
+
+  return <canvas ref={canvasRef} className="w-full h-full" />;
+}
+```
+
+### With Vue 3
+
+```vue
+<template>
+  <canvas ref="canvasRef" class="w-full h-full" />
+</template>
+
+<script setup lang="ts">
+import { ref, onMounted, onUnmounted } from "vue";
+import { ShadesEngine } from "@amphore-dev/shades";
+
+const canvasRef = ref<HTMLCanvasElement>();
+let shades: ShadesEngine;
+
+onMounted(() => {
+  if (canvasRef.value) {
+    shades = new ShadesEngine(canvasRef.value, {
+      randomized: true,
+    });
+
+    shades.generate();
+    shades.start();
+  }
+});
+
+onUnmounted(() => {
+  shades?.destroy();
+});
+</script>
+```
+
+## API Reference
+
+### Constructor
+
+```typescript
+new ShadesEngine(canvas: HTMLCanvasElement, options?: TShadesEngineOptions)
+```
+
+#### Options
+
+```typescript
+interface TShadesEngineOptions {
+  shapes?: TShadeType[]; // Shape types to use for generation (ex: ["circle", "star"])
+  customShapes?: Record<string, TShadeTypeConstructor>; // Custom shape classes (ex: { "star": StarShape })
+  randomized?: boolean; // Enable randomized generation
+  debug?: boolean; // Show debug information
+  fadeDuration?: number; // Fade duration in milliseconds (default: 500ms)
+}
+```
+
+### Methods
+
+| Method                       | Description                        |
+| ---------------------------- | ---------------------------------- |
+| `generate()`                 | Generate shapes and setup          |
+| `start()`                    | Start animation                    |
+| `pause()`                    | Pause animation                    |
+| `regenerate()`               | Generate new shapes                |
+| `destroy()`                  | Cleanup and remove event listeners |
+| `zoom(scale: number)`        | Zoom in/out                        |
+| `setDebug(enabled: boolean)` | Toggle debug mode                  |
+| `getShadesConfig()`          | Get current configuration          |
+| `isAnimating()`              | Check if animation is running      |
+
+### Controls
+
+- **Click** - Regenerate shapes
+- **Mouse move** - Parallax effect
+- **Mouse wheel** - Zoom in/out
+
+## Custom Shapes
+
+Create your own custom shapes by extending the `ShadeItem` class:
+
+### Creating a Custom Shape
+
+```typescript
+import {
+  ShadeItem,
+  TShadeColor,
+  TShadeConfig,
+  TShapeOptions,
+  TPoint,
+} from "@amphore-dev/shades";
+
+export class StarShape extends ShadeItem {
+  constructor(
+    x: number,
+    y: number,
+    color: TShadeColor,
+    options: TShapeOptions = {}
+  ) {
+    super(x, y, color, { filled: true, rotation: true, ...options });
+    this.type = "star";
+  }
+
+  draw = (
+    ctx: CanvasRenderingContext2D,
+    config: TShadeConfig,
+    offset: TPoint
+  ) => {
+    const { gradRatio, nbrShades, totalWidth, totalHeight, center, width } =
+      config;
+
+    for (let i = 0; i < nbrShades; i++) {
+      this.setColors(ctx, gradRatio, i);
+      ctx.beginPath();
+
+      const x =
+        center.x +
+        (this.position.x - totalWidth / 2 + width / 2) +
+        offset.x * (1 - (gradRatio * i) / 100);
+      const y =
+        center.y +
+        (this.position.y - totalHeight / 2 + width / 2) +
+        offset.y * (1 - (gradRatio * i) / 100);
+
+      this.drawStar(ctx, x, y, width / 2, width / 4, 5);
+      this.drawPath(ctx);
+      ctx.closePath();
+
+      if (this.rotation) {
+        this.angle += ((0.5 / nbrShades) * Math.PI) / 180;
+      }
+    }
+  };
+
+  private drawStar(
+    ctx: CanvasRenderingContext2D,
+    x: number,
+    y: number,
+    outer: number,
+    inner: number,
+    points: number
+  ) {
+    const step = Math.PI / points;
+    let rot = (Math.PI / 2) * 3 + this.angle;
+
+    ctx.moveTo(x, y - outer);
+    for (let i = 0; i < points; i++) {
+      ctx.lineTo(x + Math.cos(rot) * outer, y + Math.sin(rot) * outer);
+      rot += step;
+      ctx.lineTo(x + Math.cos(rot) * inner, y + Math.sin(rot) * inner);
+      rot += step;
+    }
+    ctx.lineTo(x, y - outer);
+  }
+}
+```
+
+### Using Custom Shapes
+
+```typescript
+import { ShadesEngine } from "@amphore-dev/shades";
+import { StarShape } from "./StarShape";
+
+const engine = new ShadesEngine(canvas, {
+  shapes: ["star", "circle", "heart"], // Mix built-in and custom
+  customShapes: {
+    star: StarShape, // Register your custom shape
+  },
+  fadeDuration: 800,
+});
+
+engine.generate();
+engine.start();
+```
+
+### Benefits
+
+- ✅ **Full extensibility** - Create any imaginable shape
+- ✅ **Seamless integration** - Mix with built-in shapes
+- ✅ **Type safety** - Complete TypeScript support
+- ✅ **Performance** - No overhead, direct compilation
+
+## Advanced Usage
+
+```typescript
+import { ShadesEngine } from "@amphore-dev/shades";
+
+const shades = new ShadesEngine(canvas, {
+  shapes: [
+    {
+      type: "circle",
+      nbrItemsX: 10,
+      nbrItemsY: 10,
+      spacing: 20,
+      colors: [
+        { r: 255, g: 100, b: 100 },
+        { r: 100, g: 255, b: 100 },
+      ],
+    },
+  ],
+});
+```
+
+## Advanced Usage
+
+### Custom Colors
+
+```typescript
+import { ShadesEngine, getRandColors } from "@amphore-dev/shades";
+
+const customColors = [
+  { r: 255, g: 0, b: 0 },
+  { r: 0, g: 255, b: 0 },
+  { r: 0, g: 0, b: 255 },
+];
+
+const shades = new ShadesEngine(canvas, {
+  shapes: [{ colors: customColors }],
+});
+```
+
+### Event Handling
+
+The engine automatically handles:
+
+- Canvas resize
+- Mouse/touch events
+- Animation frame management
+- Memory cleanup
+
+## Examples
+
+Check out `example/example-vanilla.html` for a complete example with controls.
+
+## Building From Source
+
+```bash
+git clone https://github.com/Amphore-Dev/shades.git
+cd shades
+npm install
+npm run build
+```
+
+## License
+
+MIT © [Your Name]
+
+---
+
+**Framework-agnostic by design** 🚀

package/dist/classes/ShadesEngine.d.ts

@@ -0,0 +1,65 @@
+import { ShadeItem } from "./index.js";
+import { TShadeConfig, TShadeTypeConstructor, TShadeType } from "../types/index.js";
+export type TShadesEngineDebugOptions = {
+    className?: string;
+};
+export type TShadesEngineOptions = {
+    shapes?: TShadeType[];
+    customShapes?: Record<string, TShadeTypeConstructor>;
+    randomized?: boolean;
+    debug?: boolean | TShadesEngineDebugOptions;
+    fadeDuration?: number;
+};
+export declare class ShadesEngine {
+    private canvas;
+    private context;
+    private options;
+    private items;
+    private config;
+    private offset;
+    private targetOffset;
+    private genCount;
+    private fade;
+    private animationFrameId;
+    private isPlaying;
+    private elapsedTime;
+    private framesCount;
+    private boundHandleClick;
+    private boundHandleMouseMove;
+    private boundHandleWheel;
+    private boundHandleResize;
+    private debug;
+    private debugContainer;
+    constructor(canvas: HTMLCanvasElement, options?: TShadesEngineOptions);
+    private setupCanvas;
+    generate(): void;
+    private initDefaultGeneration;
+    private getConfig;
+    private genItems;
+    private animate;
+    private getCenter;
+    private handleMouseMove;
+    private zoomShades;
+    private handleWheel;
+    private handleClick;
+    private handleResize;
+    private attachEventListeners;
+    private detachEventListeners;
+    start(): void;
+    pause(): void;
+    destroy(): void;
+    regenerate(): void;
+    getShadesConfig(): TShadeConfig;
+    getItems(): ShadeItem[];
+    isAnimating(): boolean;
+    zoom(scale: number): void;
+    private initializeDebug;
+    private startFPSCounter;
+    private updateDebug;
+    getDebugInfo(): {
+        genCount: number;
+        config: TShadeConfig;
+    };
+    setDebug(value: boolean | TShadesEngineDebugOptions): void;
+}
+//# sourceMappingURL=ShadesEngine.d.ts.map

package/dist/classes/ShadesEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShadesEngine.d.ts","sourceRoot":"","sources":["../../src/classes/ShadesEngine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAyB,MAAM,YAAY,CAAC;AAC9D,OAAO,EAGL,YAAY,EAEZ,qBAAqB,EACrB,UAAU,EACX,MAAM,mBAAmB,CAAC;AAI3B,MAAM,MAAM,yBAAyB,GAAG;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,CAAC,EAAE,UAAU,EAAE,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;IACrD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,KAAK,CAAC,EAAE,OAAO,GAAG,yBAAyB,CAAC;IAC5C,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,OAAO,CAA2B;IAC1C,OAAO,CAAC,OAAO,CAAuB;IAGtC,OAAO,CAAC,KAAK,CAAmB;IAChC,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,MAAM,CAA0B;IACxC,OAAO,CAAC,YAAY,CAA0B;IAC9C,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,IAAI,CAOV;IAGF,OAAO,CAAC,gBAAgB,CAAuB;IAC/C,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,WAAW,CAAwB;IAG3C,OAAO,CAAC,gBAAgB,CAAa;IACrC,OAAO,CAAC,oBAAoB,CAA0B;IACtD,OAAO,CAAC,gBAAgB,CAA0B;IAClD,OAAO,CAAC,iBAAiB,CAAa;IAGtC,OAAO,CAAC,KAAK,CAA8C;IAC3D,OAAO,CAAC,cAAc,CAA+B;gBAEzC,MAAM,EAAE,iBAAiB,EAAE,OAAO,GAAE,oBAAyB;IA0BzE,OAAO,CAAC,WAAW;IAKZ,QAAQ,IAAI,IAAI;IA0BvB,OAAO,CAAC,qBAAqB;IAiB7B,OAAO,CAAC,SAAS;IAQjB,OAAO,CAAC,QAAQ;IA4EhB,OAAO,CAAC,OAAO;IAyEf,OAAO,CAAC,SAAS;IAOjB,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,UAAU;IAclB,OAAO,CAAC,WAAW;IAQnB,OAAO,CAAC,WAAW;IA2BnB,OAAO,CAAC,YAAY;IAYpB,OAAO,CAAC,oBAAoB;IAO5B,OAAO,CAAC,oBAAoB;IASrB,KAAK,IAAI,IAAI;IAQb,KAAK,IAAI,IAAI;IAQb,OAAO,IAAI,IAAI;IAiBf,UAAU,IAAI,IAAI;IAIlB,eAAe,IAAI,YAAY;IAI/B,QAAQ,IAAI,SAAS,EAAE;IAIvB,WAAW,IAAI,OAAO;IAItB,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAMhC,OAAO,CAAC,eAAe;IA2BvB,OAAO,CAAC,eAAe;IASvB,OAAO,CAAC,WAAW;IAeZ,YAAY,IAAI;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,YAAY,CAAA;KAAE;IAO1D,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,yBAAyB,GAAG,IAAI;CAWlE"}