Merge branch 'master' into gh-pages

.github/workflows/ci.yml

@@ -15,7 +15,7 @@ jobs:
       - uses: actions/checkout@v3
       - uses: actions/setup-node@v3.8.1
         with:
-          node-version: 12
+          node-version: 14
           registry-url: https://registry.npmjs.org/
       - run: npm install
       - run: npm run lint
@@ -25,3 +25,7 @@ jobs:
         if: startsWith(github.ref, 'refs/tags/') && github.event_name != 'pull_request'
         env:
           NODE_AUTH_TOKEN: ${{secrets.npm_token}}
+      - uses: actions/upload-artifact@v3
+        with:
+          name: test-screenshots
+          path: shots/

README.md

@@ -30,7 +30,7 @@ You can then `require('canvas-confetti');` to use it in your project build. _Not
 You can also include this library in your HTML page directly from a CDN:
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/canvas-confetti@1.8.0/dist/confetti.browser.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/canvas-confetti@1.9.0/dist/confetti.browser.min.js"></script>
 ```
 
 _Note: you should use the latest version at the time that you include your project. You can see all versions [on the releases page](https://github.com/catdad/canvas-confetti/releases)._
@@ -72,12 +72,12 @@ The `confetti` parameter is a single optional `options` object, which has the fo
   - `origin.x` _Number (default: 0.5)_: The `x` position on the page, with `0` being the left edge and `1` being the right edge.
   - `origin.y` _Number (default: 0.5)_: The `y` position on the page, with `0` being the top edge and `1` being the bottom edge.
 - `colors` _Array&lt;String&gt;_: An array of color strings, in the HEX format... you know, like `#bada55`.
-- `shapes` _Array&lt;String|Shape&gt;_: An array of shapes for the confetti. There are 3 built-in values of `square`, `circle`, and `star`. The default is to use both squares and circles in an even mix. To use a single shape, you can provide just one shape in the array, such as `['star']`. You can also change the mix by providing a value such as `['circle', 'circle', 'square']` to use two third circles and one third squares. You can also create your own shapes using the `confetti.shapeFromPath` helper method.
+- `shapes` _Array&lt;String|Shape&gt;_: An array of shapes for the confetti. There are 3 built-in values of `square`, `circle`, and `star`. The default is to use both squares and circles in an even mix. To use a single shape, you can provide just one shape in the array, such as `['star']`. You can also change the mix by providing a value such as `['circle', 'circle', 'square']` to use two third circles and one third squares. You can also create your own shapes using the [`confetti.shapeFromPath`](#confettishapefrompath-path-matrix---shape) or [`confetti.shapeFromText`](#confettishapefromtext-text-scalar-color-fontfamily---shape) helper methods.
 - `scalar` _Number (default: 1)_: Scale factor for each confetti particle. Use decimals to make the confetti smaller. Go on, try teeny tiny confetti, they are adorable!
 - `zIndex` _Integer (default: 100)_: The confetti should be on top, after all. But if you have a crazy high page, you can set it even higher.
 - `disableForReducedMotion` _Boolean (default: false)_: Disables confetti entirely for users that [prefer reduced motion](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion). The `confetti()` promise will resolve immediately in this case.
 
-### `confetti.shapeFromPath({ path, matrix? })` -> `Shape`
+### `confetti.shapeFromPath({ path, matrix? })` → `Shape`
 
 This helper method lets you create a custom confetti shape using an [SVG Path string](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/d). Any valid path should work, though there are a few caveats:
 - All paths will be filed. If you were hoping to have a stroke path, that is not implemented.
@@ -98,6 +98,31 @@ confetti({
 });
 ```
 
+### `confetti.shapeFromText({ text, scalar?, color?, fontFamily? })` → `Shape`
+
+This is the highly anticipated feature to render emoji confetti! Use any standard unicode emoji. Or other text, but... maybe don't use other text.
+
+While any text should work, there are some caveats:
+- For flailing confetti, something that is mostly square works best. That is, a single character, especially an emoji.
+- Rather than rendering text every time a confetti is drawn, this helper actually rasterizes the text. Therefore, it does not scale well after it is created. If you plan to use the `scalar` value to scale your confetti, use the same `scalar` value here when creating the shape. This will make sure the confetti are not blurry.
+
+The options for this method are:
+- `options` _`Object`_:
+  - `text` _`String`_: the text to be rendered as a confetti. If you can't make up your mind, I suggest "🐈".
+  - `scalar` _`Number, optional, default: 1`_: a scale value relative to the default size. It matches the `scalar` value in the confetti options.
+  - `color` _`String, optional, default: #000000`_: the color used to render the text.
+  - `fontFamily` _`String, optional, default: native emoji`_: the font family name to use when rendering the text. The default follows [best practices for rendring the native OS emoji of the device](https://nolanlawson.com/2022/04/08/the-struggle-of-using-native-emoji-on-the-web/), falling back to `sans-serif`. If using a web font, make sure this [font is loaded](https://developer.mozilla.org/en-US/docs/Web/API/FontFace/load) before rendering your confetti.
+
+```javascript
+var scalar = 2;
+var pineapple = confetti.shapeFromText({ text: '🍍', scalar });
+
+confetti({
+  shapes: [pineapple],
+  scalar
+});
+```
+
 ### `confetti.create(canvas, [globalOptions])` → `function`
 
 This method creates an instance of the `confetti` function that uses a custom canvas. This is useful if you want to limit the area on your page in which confetti appear. By default, this method will not modify the canvas in any way (other than drawing to it).

index.html

@@ -8,8 +8,9 @@
   <meta name="keywords" content="canvas,confetti,component,module,animation,javascript,catdad">
 
   <meta name="theme-color" content="#393939">
+  <link id="favicon" rel="shortcut icon" type="image/png" />
 
-  <title>🎊</title>
+  <title>canvas confetti</title>
 
   <link href="https://fonts.googleapis.com/css2?family=Noto+Sans&display=swap" rel="stylesheet">
 
@@ -536,6 +537,30 @@ <h2><a href="#paths" id="paths" class="anchor">Custom Shapes</a></h2>
     </div>
   </div>
 
+  <div class="container">
+    <div class="group" data-name="emoji">
+      <div class="flex-rows">
+        <div class="left">
+          <h2><a href="#emoji" id="emoji" class="anchor">Emoji</a></h2>
+          <button class="run">
+            Run
+            <span class="icon">
+              <svg class="icon"><use xlink:href="#run"></use></svg>
+            </span>
+          </button>
+        </div>
+        <div class="description">
+          <p>
+            Don't know any custom shapes? That's okay, just use emoji instead! That's what they
+            are for anyway. I mean... why do they even exist if we weren't supposed to make
+            confetti out of them? Think about it.
+          </p>
+        </div>
+      </div>
+      <div class="editor"></div>
+    </div>
+  </div>
+
   <div class="container">
     <div class="group" data-name="custom">
       <div class="flex-rows">
@@ -856,6 +881,44 @@ <h2><a href="#custom-canvas" id="custom-canvas" class="anchor">Custom Canvas</a>
           shapes: [ heart ],
           colors: ['#f93963', '#a10864', '#ee0b93']
         });
+      },
+      emoji: function () {
+        var scalar = 2;
+        var unicorn = confetti.shapeFromText({ text: '🦄', scalar });
+
+        var defaults = {
+          spread: 360,
+          ticks: 60,
+          gravity: 0,
+          decay: 0.96,
+          startVelocity: 20,
+          shapes: [unicorn],
+          scalar
+        };
+
+        function shoot() {
+          confetti({
+            ...defaults,
+            particleCount: 30
+          });
+
+          confetti({
+            ...defaults,
+            particleCount: 5,
+            flat: true
+          });
+
+          confetti({
+            ...defaults,
+            particleCount: 15,
+            scalar: scalar / 2,
+            shapes: ['circle']
+          });
+        }
+
+        setTimeout(shoot, 0);
+        setTimeout(shoot, 100);
+        setTimeout(shoot, 200);
       }
     };
 
@@ -911,6 +974,21 @@ <h2><a href="#custom-canvas" id="custom-canvas" class="anchor">Custom Canvas</a>
     };
   </script>
 
+  <script>
+    // render favicon live, because why not
+    addEventListener("load", (event) => {
+      const image = confetti.shapeFromText('🎊', { scalar: 512/10 });
+      const canvas = new OffscreenCanvas(image.bitmap.width, image.bitmap.height);
+      const ctx = canvas.getContext('bitmaprenderer');
+      ctx.transferFromImageBitmap(image.bitmap);
+
+      canvas.convertToBlob().then(blob => {
+        const icon = document.getElementById('favicon');
+        icon.setAttribute('href', URL.createObjectURL(blob));
+      });
+    });
+  </script>
+
   <script src="/analytics.js" async></script>
 </body>
 </html>

package.json

@@ -1,6 +1,6 @@
 {
   "name": "canvas-confetti",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "performant confetti animation in the browser",
   "main": "src/confetti.js",
   "module": "dist/confetti.module.mjs",
@@ -34,7 +34,7 @@
     "eslint": "^4.16.0",
     "eslint-plugin-ava": "9.0.0",
     "jimp": "^0.2.28",
-    "puppeteer": "^1.0.0",
+    "puppeteer": "^19.11.1",
     "rootrequire": "^1.0.0",
     "send": "^0.16.1",
     "terser": "^3.14.1"

src/confetti.js

@@ -356,6 +356,37 @@
         Math.abs(y2 - y1) * 0.1,
         Math.PI / 10 * fetti.wobble
       ));
+    } else if (fetti.shape.type === 'bitmap') {
+      var rotation = Math.PI / 10 * fetti.wobble;
+      var scaleX = Math.abs(x2 - x1) * 0.1;
+      var scaleY = Math.abs(y2 - y1) * 0.1;
+      var width = fetti.shape.bitmap.width * fetti.scalar;
+      var height = fetti.shape.bitmap.height * fetti.scalar;
+
+      var matrix = new DOMMatrix([
+        Math.cos(rotation) * scaleX,
+        Math.sin(rotation) * scaleX,
+        -Math.sin(rotation) * scaleY,
+        Math.cos(rotation) * scaleY,
+        fetti.x,
+        fetti.y
+      ]);
+
+      // apply the transform matrix from the confetti shape
+      matrix.multiplySelf(new DOMMatrix(fetti.shape.matrix));
+
+      var pattern = context.createPattern(fetti.shape.bitmap, 'no-repeat');
+      pattern.setTransform(matrix);
+
+      context.globalAlpha = (1 - progress);
+      context.fillStyle = pattern;
+      context.fillRect(
+        fetti.x - (width / 2),
+        fetti.y - (height / 2),
+        width,
+        height
+      );
+      context.globalAlpha = 1;
     } else if (fetti.shape === 'circle') {
       context.ellipse ?
         context.ellipse(fetti.x, fetti.y, Math.abs(x2 - x1) * fetti.ovalScalar, Math.abs(y2 - y1) * fetti.ovalScalar, Math.PI / 10 * fetti.wobble, 0, 2 * Math.PI) :
@@ -657,7 +688,7 @@
     return t2;
   }
 
-  function createPathFetti(pathData) {
+  function shapeFromPath(pathData) {
     if (!canUsePaths) {
       throw new Error('path confetti are not supported in this browser');
     }
@@ -717,14 +748,61 @@
     };
   }
 
+  function shapeFromText(textData) {
+    var text,
+        scalar = 1,
+        color = '#000000',
+        // see https://nolanlawson.com/2022/04/08/the-struggle-of-using-native-emoji-on-the-web/
+        fontFamily = '"Twemoji Mozilla", "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji", "EmojiOne Color", "Android Emoji", "system emoji", sans-serif';
+
+    if (typeof textData === 'string') {
+      text = textData;
+    } else {
+      text = textData.text;
+      scalar = 'scalar' in textData ? textData.scalar : scalar;
+      fontFamily = 'fontFamily' in textData ? textData.fontFamily : fontFamily;
+      color = 'color' in textData ? textData.color : color;
+    }
+
+    // all other confetti are 10 pixels,
+    // so this pixel size is the de-facto 100% scale confetti
+    var fontSize = 10 * scalar;
+    var font = '' + fontSize + 'px ' + fontFamily;
+
+    var canvas = new OffscreenCanvas(fontSize, fontSize);
+    var ctx = canvas.getContext('2d');
+
+    ctx.font = font;
+    var size = ctx.measureText(text);
+    var width = Math.floor(size.width);
+    var height = Math.floor(size.fontBoundingBoxAscent + size.fontBoundingBoxDescent);
+
+    canvas = new OffscreenCanvas(width, height);
+    ctx = canvas.getContext('2d');
+    ctx.font = font;
+    ctx.fillStyle = color;
+
+    ctx.fillText(text, 0, fontSize);
+
+    var scale = 1 / scalar;
+
+    return {
+      type: 'bitmap',
+      // TODO these probably need to be transfered for workers
+      bitmap: canvas.transferToImageBitmap(),
+      matrix: [scale, 0, 0, scale, -width * scale / 2, -height * scale / 2]
+    };
+  }
+
   module.exports = function() {
     return getDefaultFire().apply(this, arguments);
   };
   module.exports.reset = function() {
     getDefaultFire().reset();
   };
   module.exports.create = confettiCannon;
-  module.exports.shapeFromPath = createPathFetti;
+  module.exports.shapeFromPath = shapeFromPath;
+  module.exports.shapeFromText = shapeFromText;
 }((function () {
   if (typeof window !== 'undefined') {
     return window;