@konfetti-js/core 0.3.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @konfetti-js/core
 
-A lightweight, zero-dependency confetti animation library for the web. About 4 kB gzipped, TypeScript-first, and safe to import during server rendering.
+A lightweight, zero-dependency confetti animation library for the web. Pieces behave like paper: they tumble in 3D, catch the light and float down. About 5 kB gzipped, TypeScript-first, and safe to import during server rendering.
 
 **[Live demo and docs](https://andreabettich.github.io/konfetti.js/)**
 

package/dist/index.cjs

@@ -88,7 +88,7 @@ var DEFAULT_OPTIONS = {
   decay: 0.9,
   gravity: 1,
   drift: 0,
-  ticks: 200,
+  ticks: 600,
   origin: { x: 0.5, y: 0.5 },
   colors: DEFAULT_COLORS,
   shapes: ["circle", "square"],
@@ -146,6 +146,9 @@ function degToRad(deg) {
 function randomRange(min, max) {
   return Math.random() * (max - min) + min;
 }
+function randomSign() {
+  return Math.random() < 0.5 ? -1 : 1;
+}
 function randomItem(arr) {
   return arr[Math.floor(Math.random() * arr.length)];
 }
@@ -174,11 +177,11 @@ var ParticlePool = class {
      */
     this.palette = [];
     this.colorIds = /* @__PURE__ */ new Map();
-    this.data = new Float32Array(initialCapacity * 16 /* SIZE */);
+    this.data = new Float32Array(initialCapacity * 25 /* SIZE */);
   }
   /** How many particles fit before the buffer has to grow */
   get capacity() {
-    return this.data.length / 16 /* SIZE */;
+    return this.data.length / 25 /* SIZE */;
   }
   /**
    * Remove every particle
@@ -200,17 +203,19 @@ var ParticlePool = class {
     const angleRad = degToRad(options.angle);
     const spreadRad = degToRad(options.spread);
     for (let i = 0; i < count; i++) {
-      const idx = (this.activeCount + i) * 16 /* SIZE */;
+      const idx = (this.activeCount + i) * 25 /* SIZE */;
       const particleAngle = angleRad + randomRange(-spreadRad / 2, spreadRad / 2);
       const velocity = options.startVelocity * randomRange(0.5, 1);
       data[idx + 0 /* X */] = originX;
       data[idx + 1 /* Y */] = originY;
       data[idx + 2 /* VelocityX */] = Math.cos(particleAngle) * velocity;
       data[idx + 3 /* VelocityY */] = -Math.sin(particleAngle) * velocity;
-      data[idx + 4 /* Rotation */] = randomRange(0, Math.PI * 2);
-      data[idx + 5 /* RotationSpeed */] = randomRange(-0.1, 0.1);
       data[idx + 6 /* Tilt */] = randomRange(0, Math.PI * 2);
-      data[idx + 7 /* TiltSpeed */] = randomRange(0.05, 0.15);
+      data[idx + 7 /* TiltSpeed */] = randomRange(0.08, 0.22) * randomSign();
+      data[idx + 16 /* Wobble */] = randomRange(0, Math.PI * 2);
+      data[idx + 17 /* WobbleSpeed */] = randomRange(0.02, 0.07) * randomSign();
+      data[idx + 4 /* Rotation */] = randomRange(0, Math.PI * 2);
+      data[idx + 5 /* RotationSpeed */] = randomRange(-0.04, 0.04);
       data[idx + 8 /* Color */] = this.colorId(randomItem(options.colors));
       data[idx + 9 /* Shape */] = shapeToIndex(randomItem(options.shapes));
       data[idx + 10 /* Scalar */] = options.scalar * randomRange(0.8, 1.2);
@@ -219,6 +224,8 @@ var ParticlePool = class {
       data[idx + 13 /* Drift */] = options.drift + randomRange(-0.5, 0.5);
       data[idx + 14 /* Gravity */] = options.gravity;
       data[idx + 15 /* Decay */] = options.decay;
+      data[idx + 18 /* AirPhase */] = randomRange(0, Math.PI * 2);
+      data[idx + 19 /* AirPhaseSpeed */] = randomRange(0.02, 0.05);
     }
     this.activeCount += count;
   }
@@ -229,11 +236,11 @@ var ParticlePool = class {
     const data = this.data;
     let writeIdx = 0;
     for (let readIdx = 0; readIdx < this.activeCount; readIdx++) {
-      const srcIdx = readIdx * 16 /* SIZE */;
+      const srcIdx = readIdx * 25 /* SIZE */;
       if (data[srcIdx + 11 /* Life */] <= 0) continue;
       if (writeIdx !== readIdx) {
-        const dstIdx = writeIdx * 16 /* SIZE */;
-        data.copyWithin(dstIdx, srcIdx, srcIdx + 16 /* SIZE */);
+        const dstIdx = writeIdx * 25 /* SIZE */;
+        data.copyWithin(dstIdx, srcIdx, srcIdx + 25 /* SIZE */);
       }
       writeIdx++;
     }
@@ -254,7 +261,7 @@ var ParticlePool = class {
     const remap = /* @__PURE__ */ new Map();
     this.clearPalette();
     for (let i = 0; i < this.activeCount; i++) {
-      const idx = i * 16 /* SIZE */ + 8 /* Color */;
+      const idx = i * 25 /* SIZE */ + 8 /* Color */;
       const oldId = data[idx];
       let newId = remap.get(oldId);
       if (newId === void 0) {
@@ -281,36 +288,105 @@ var ParticlePool = class {
     if (needed <= this.capacity) return;
     let capacity = this.capacity;
     while (capacity < needed) capacity *= 2;
-    const grown = new Float32Array(Math.min(capacity, MAX_PARTICLES) * 16 /* SIZE */);
-    grown.set(this.data.subarray(0, this.activeCount * 16 /* SIZE */));
+    const grown = new Float32Array(Math.min(capacity, MAX_PARTICLES) * 25 /* SIZE */);
+    grown.set(this.data.subarray(0, this.activeCount * 25 /* SIZE */));
     this.data = grown;
   }
 };
 
+// src/orientation.ts
+var LIGHT_X = -0.3;
+var LIGHT_Y = -0.6;
+var LIGHT_Z = 0.742;
+function lightness(m) {
+  const facing = m[8] < 0 ? -1 : 1;
+  return Math.max(0, facing * (m[6] * LIGHT_X + m[7] * LIGHT_Y + m[8] * LIGHT_Z));
+}
+function createOrientation() {
+  return new Float64Array(9);
+}
+function orient(data, idx, out) {
+  const tilt = data[idx + 6 /* Tilt */];
+  const wobble = data[idx + 16 /* Wobble */];
+  const rotation = data[idx + 4 /* Rotation */];
+  const cx = Math.cos(tilt);
+  const sx = Math.sin(tilt);
+  const cy = Math.cos(wobble);
+  const sy = Math.sin(wobble);
+  const cz = Math.cos(rotation);
+  const sz = Math.sin(rotation);
+  out[0] = cz * cy;
+  out[1] = sz * cy;
+  out[2] = -sy;
+  out[3] = cz * sy * sx - sz * cx;
+  out[4] = sz * sy * sx + cz * cx;
+  out[5] = cy * sx;
+  out[6] = cz * sy * cx + sz * sx;
+  out[7] = sz * sy * cx - cz * sx;
+  out[8] = cy * cx;
+  return out;
+}
+
 // src/physics.ts
-function updateParticles(pool, dt) {
+var PAPER_GRAVITY = 0.45;
+var FALL_DRAG = 0.0475;
+var FLUTTER_SPEED = 4;
+var GLIDE = 0.6;
+var AIR_SWAY = 1;
+var OFFSCREEN_MARGIN = 60;
+var orientation = createOrientation();
+function updateParticles(pool, dt, width, height) {
   const data = pool.data;
   for (let i = 0; i < pool.activeCount; i++) {
-    const idx = i * 16 /* SIZE */;
-    let vx = data[idx + 2 /* VelocityX */];
-    let vy = data[idx + 3 /* VelocityY */];
-    const tilt = data[idx + 6 /* Tilt */];
-    vy += data[idx + 14 /* Gravity */] * dt;
-    vx += data[idx + 13 /* Drift */] * Math.sin(tilt) * dt;
-    const damping = data[idx + 15 /* Decay */] ** dt;
-    vx *= damping;
-    vy *= damping;
-    data[idx + 2 /* VelocityX */] = vx;
-    data[idx + 3 /* VelocityY */] = vy;
-    data[idx + 0 /* X */] += vx * dt;
-    data[idx + 1 /* Y */] += vy * dt;
-    data[idx + 4 /* Rotation */] += data[idx + 5 /* RotationSpeed */] * dt;
-    data[idx + 6 /* Tilt */] = tilt + data[idx + 7 /* TiltSpeed */] * dt;
-    data[idx + 11 /* Life */] -= dt;
+    updateParticle(data, i * 25 /* SIZE */, dt, width, height);
   }
   pool.compact();
   return pool.activeCount > 0;
 }
+function updateParticle(data, idx, dt, width, height) {
+  let vx = data[idx + 2 /* VelocityX */];
+  let vy = data[idx + 3 /* VelocityY */];
+  const m = orient(data, idx, orientation);
+  const nx = m[6];
+  const ny = m[7];
+  data[idx + 20 /* AxisXX */] = m[0];
+  data[idx + 21 /* AxisXY */] = m[1];
+  data[idx + 22 /* AxisYX */] = m[3];
+  data[idx + 23 /* AxisYY */] = m[4];
+  data[idx + 24 /* Light */] = lightness(m);
+  vy += data[idx + 14 /* Gravity */] * PAPER_GRAVITY * dt;
+  if (vy > 0) {
+    const drag = FALL_DRAG * (0.35 + 0.65 * Math.abs(ny));
+    vy = Math.max(0, vy - drag * vy * Math.min(vy, FLUTTER_SPEED) * dt);
+    vx -= GLIDE * vy * 2 * nx * ny * dt;
+  }
+  const phase = data[idx + 18 /* AirPhase */];
+  const airX = data[idx + 13 /* Drift */] + AIR_SWAY * Math.sin(phase);
+  const damping = data[idx + 15 /* Decay */] ** dt;
+  vx = airX + (vx - airX) * damping;
+  vy *= damping;
+  const spin = 0.6 + Math.min(1.4, Math.hypot(vx, vy) / 3);
+  data[idx + 2 /* VelocityX */] = vx;
+  data[idx + 3 /* VelocityY */] = vy;
+  data[idx + 0 /* X */] += vx * dt;
+  data[idx + 1 /* Y */] += vy * dt;
+  data[idx + 6 /* Tilt */] += data[idx + 7 /* TiltSpeed */] * spin * dt;
+  data[idx + 16 /* Wobble */] += data[idx + 17 /* WobbleSpeed */] * dt;
+  data[idx + 4 /* Rotation */] += data[idx + 5 /* RotationSpeed */] * dt;
+  data[idx + 18 /* AirPhase */] = phase + data[idx + 19 /* AirPhaseSpeed */] * dt;
+  data[idx + 11 /* Life */] -= dt;
+  if (width > 0 && height > 0) {
+    const x = data[idx + 0 /* X */];
+    const y = data[idx + 1 /* Y */];
+    const fellOut = y > height + OFFSCREEN_MARGIN && vy >= 0;
+    const leftOut = x < -OFFSCREEN_MARGIN * 2 && vx <= 0;
+    const rightOut = x > width + OFFSCREEN_MARGIN * 2 && vx >= 0;
+    const floatedOut = y < -OFFSCREEN_MARGIN && vy <= 0 && data[idx + 14 /* Gravity */] <= 0;
+    if (fellOut || leftOut || rightOut || floatedOut) {
+      data[idx + 11 /* Life */] = 0;
+    }
+  }
+}
 
 // src/presets.ts
 var FIREWORK_COLORS = ["#ff0000", "#ffff00", "#00ff00", "#00ffff", "#ff00ff"];
@@ -395,7 +471,7 @@ var PRESETS = {
           gravity: 0.5,
           drift: 0,
           origin: { x: 0.5, y: 0 },
-          ticks: 300
+          ticks: 900
         }
       }
     ]
@@ -414,7 +490,7 @@ var PRESETS = {
           gravity: 0.3,
           drift: 1,
           origin: { x: 0.5, y: -0.1 },
-          ticks: 400,
+          ticks: 1200,
           colors: ["#ffffff", "#e0e0e0", "#c0c0c0"],
           shapes: ["circle"]
         }
@@ -474,6 +550,40 @@ function isPresetName(value) {
 
 // src/renderer.ts
 var BASE_SIZE = 10;
+var SHADE_STEPS = 16;
+var MIN_BRIGHTNESS = 0.55;
+var MAX_BRIGHTNESS = 1.2;
+var LIFETIME_FADE = 0.1;
+var MAX_SHADE_CACHE = 4096;
+var BLACK = [0, 0, 0, 1];
+function parseColor(ctx, color) {
+  ctx.fillStyle = "#000000";
+  ctx.fillStyle = color;
+  const overBlack = String(ctx.fillStyle);
+  ctx.fillStyle = "#ffffff";
+  ctx.fillStyle = color;
+  if (String(ctx.fillStyle) !== overBlack) return null;
+  const hex = /^#([0-9a-f]{6})$/i.exec(overBlack);
+  if (hex) {
+    const value = Number.parseInt(hex[1], 16);
+    return [value >> 16, value >> 8 & 255, value & 255, 1];
+  }
+  const rgba = /^rgba?\((\d+),\s*(\d+),\s*(\d+)(?:,\s*([\d.]+))?/.exec(overBlack);
+  if (!rgba) return null;
+  const alpha = rgba[4] === void 0 ? 1 : Number(rgba[4]);
+  return [Number(rgba[1]), Number(rgba[2]), Number(rgba[3]), alpha];
+}
+function buildShades([r, g, b, alpha]) {
+  const shades = [];
+  for (let step = 0; step < SHADE_STEPS; step++) {
+    const brightness = MIN_BRIGHTNESS + (MAX_BRIGHTNESS - MIN_BRIGHTNESS) * step / (SHADE_STEPS - 1);
+    const [sr, sg, sb] = [r, g, b].map(
+      (c) => Math.round(brightness <= 1 ? c * brightness : c + (255 - c) * (brightness - 1))
+    );
+    shades.push(alpha < 1 ? `rgba(${sr}, ${sg}, ${sb}, ${alpha})` : `rgb(${sr}, ${sg}, ${sb})`);
+  }
+  return shades;
+}
 function createOverlayCanvas() {
   const canvas = document.createElement("canvas");
   canvas.className = "konfetti-canvas";
@@ -496,7 +606,9 @@ var Renderer = class {
     this.width = 0;
     this.height = 0;
     this.pixelRatio = 1;
-    /** Particle indices grouped by palette color, reused between frames */
+    /** Brightness steps per color */
+    this.shadeCache = /* @__PURE__ */ new Map();
+    /** Particle indices grouped by color and shade step, reused between frames */
     this.buckets = [];
     this.ownsCanvas = !canvas;
     this.canvas = canvas ?? createOverlayCanvas();
@@ -544,7 +656,10 @@ var Renderer = class {
     this.ctx.clearRect(0, 0, this.canvas.width, this.canvas.height);
   }
   /**
-   * Draw all particles, batched by color to limit fillStyle changes
+   * Draw every piece as flat paper turned in 3D: the transform is the piece's
+   * rotation projected onto the screen (computed by physics), and its color is
+   * shaded by how much its visible side faces the light. Pieces are drawn
+   * grouped by color and shade, so the fill changes once per group.
    */
   render(pool) {
     this.clear();
@@ -553,35 +668,32 @@ var Renderer = class {
     const data = pool.data;
     const ratio = this.pixelRatio;
     const buckets = this.buckets;
-    for (const bucket of buckets) bucket.length = 0;
+    for (const bucket of buckets) if (bucket) bucket.length = 0;
     for (let i = 0; i < pool.activeCount; i++) {
-      const colorId = data[i * 16 /* SIZE */ + 8 /* Color */];
-      if (!buckets[colorId]) buckets[colorId] = [];
-      buckets[colorId].push(i);
+      const idx = i * 25 /* SIZE */;
+      const step = Math.round(data[idx + 24 /* Light */] * (SHADE_STEPS - 1));
+      const key = data[idx + 8 /* Color */] * SHADE_STEPS + step;
+      if (!buckets[key]) buckets[key] = [];
+      buckets[key].push(idx);
     }
-    for (let colorId = 0; colorId < buckets.length; colorId++) {
-      const bucket = buckets[colorId];
+    for (let key = 0; key < buckets.length; key++) {
+      const bucket = buckets[key];
       if (!bucket || bucket.length === 0) continue;
-      ctx.fillStyle = pool.palette[colorId];
-      for (const particle of bucket) {
-        const idx = particle * 16 /* SIZE */;
-        const tilt = data[idx + 6 /* Tilt */];
-        const rotation = data[idx + 4 /* Rotation */];
+      const color = pool.palette[Math.floor(key / SHADE_STEPS)];
+      ctx.fillStyle = this.shadesFor(ctx, color)[key % SHADE_STEPS];
+      for (const idx of bucket) {
         const opacity = Math.min(
           1,
-          data[idx + 11 /* Life */] / data[idx + 12 /* MaxLife */] * 2
+          data[idx + 11 /* Life */] / (data[idx + 12 /* MaxLife */] * LIFETIME_FADE)
         );
-        const size = BASE_SIZE * data[idx + 10 /* Scalar */] * (0.8 + 0.2 * Math.cos(tilt));
+        const size = BASE_SIZE * data[idx + 10 /* Scalar */];
         if (size < 0.5 || opacity < 0.01) continue;
-        const cos = Math.cos(rotation);
-        const sin = Math.sin(rotation);
-        const squash = 0.6 + 0.4 * Math.abs(Math.cos(tilt));
         ctx.globalAlpha = opacity;
         ctx.setTransform(
-          ratio * cos,
-          ratio * sin,
-          -ratio * sin * squash,
-          ratio * cos * squash,
+          ratio * data[idx + 20 /* AxisXX */],
+          ratio * data[idx + 21 /* AxisXY */],
+          ratio * data[idx + 22 /* AxisYX */],
+          ratio * data[idx + 23 /* AxisYY */],
           ratio * data[idx + 0 /* X */],
           ratio * data[idx + 1 /* Y */]
         );
@@ -591,6 +703,15 @@ var Renderer = class {
     ctx.globalAlpha = 1;
     ctx.setTransform(1, 0, 0, 1, 0, 0);
   }
+  shadesFor(ctx, color) {
+    let shades = this.shadeCache.get(color);
+    if (!shades) {
+      if (this.shadeCache.size >= MAX_SHADE_CACHE) this.shadeCache.clear();
+      shades = buildShades(parseColor(ctx, color) ?? BLACK);
+      this.shadeCache.set(color, shades);
+    }
+    return shades;
+  }
   /**
    * Destroy renderer and remove the canvas if we created it
    */
@@ -613,6 +734,8 @@ var Konfetti = class {
     this.paused = false;
     this.destroyed = false;
     this.resizeWithWindow = false;
+    /** Follows a custom canvas whose size changes through layout, not just window resizes */
+    this.resizeObserver = null;
     this.timeouts = /* @__PURE__ */ new Set();
     this.intervals = /* @__PURE__ */ new Set();
     this.handleResize = () => {
@@ -630,7 +753,8 @@ var Konfetti = class {
       if (!this.renderer) return;
       const dt = clamp((time - this.lastTime) / FRAME_MS, 0, MAX_STEP);
       this.lastTime = time;
-      const hasParticles = updateParticles(this.pool, dt);
+      const { width, height } = this.renderer.getDimensions();
+      const hasParticles = updateParticles(this.pool, dt, width, height);
       this.renderer.render(this.pool);
       if (hasParticles) {
         this.frameId = requestAnimationFrame(this.tick);
@@ -642,7 +766,13 @@ var Konfetti = class {
     }
     this.renderer = new Renderer(canvas);
     this.resizeWithWindow = createOptions.resize !== false;
-    if (this.resizeWithWindow) window.addEventListener("resize", this.handleResize);
+    if (this.resizeWithWindow) {
+      window.addEventListener("resize", this.handleResize);
+      if (canvas && typeof ResizeObserver !== "undefined") {
+        this.resizeObserver = new ResizeObserver(this.handleResize);
+        this.resizeObserver.observe(canvas);
+      }
+    }
     document.addEventListener("visibilitychange", this.handleVisibilityChange);
   }
   /**
@@ -729,6 +859,8 @@ var Konfetti = class {
     this.reset();
     this.destroyed = true;
     if (this.resizeWithWindow) window.removeEventListener("resize", this.handleResize);
+    this.resizeObserver?.disconnect();
+    this.resizeObserver = null;
     document.removeEventListener("visibilitychange", this.handleVisibilityChange);
     this.renderer?.destroy();
   }