Reject join.across and join.shim for animated joins (#4634)

Author: metsw24-max

docs/src/content/docs/api-constructor.md

@@ -76,7 +76,7 @@ where the overall height is the `pageHeight` multiplied by the number of `pages`
 | [options.text.wrap] | <code>string</code> | <code>&quot;&#x27;word&#x27;&quot;</code> | word wrapping style when width is provided, one of: 'word', 'char', 'word-char' (prefer word, fallback to char) or 'none'. |
 | [options.join] | <code>Object</code> |  | describes how an array of input images should be joined. |
 | [options.join.across] | <code>number</code> | <code>1</code> | number of images to join horizontally. |
-| [options.join.animated] | <code>boolean</code> | <code>false</code> | set this to `true` to join the images as an animated image. |
+| [options.join.animated] | <code>boolean</code> | <code>false</code> | set this to `true` to join the images as an animated image, cannot be used with `across` or `shim`. |
 | [options.join.shim] | <code>number</code> | <code>0</code> | number of pixels to insert between joined images. |
 | [options.join.background] | <code>string</code> \| <code>Object</code> |  | parsed by the [color](https://www.npmjs.org/package/color) module to extract values for red, green, blue and alpha. |
 | [options.join.halign] | <code>string</code> | <code>&quot;&#x27;left&#x27;&quot;</code> | horizontal alignment style for images joined horizontally (`'left'`, `'centre'`, `'center'`, `'right'`). |

lib/constructor.mjs

@@ -202,7 +202,7 @@ const queueListener = (queueLength) => {
  * @param {string} [options.text.wrap='word'] - word wrapping style when width is provided, one of: 'word', 'char', 'word-char' (prefer word, fallback to char) or 'none'.
  * @param {Object} [options.join] - describes how an array of input images should be joined.
  * @param {number} [options.join.across=1] - number of images to join horizontally.
- * @param {boolean} [options.join.animated=false] - set this to `true` to join the images as an animated image.
+ * @param {boolean} [options.join.animated=false] - set this to `true` to join the images as an animated image, cannot be used with `across` or `shim`.
  * @param {number} [options.join.shim=0] - number of pixels to insert between joined images.
  * @param {string|Object} [options.join.background] - parsed by the [color](https://www.npmjs.org/package/color) module to extract values for red, green, blue and alpha.
  * @param {string} [options.join.halign='left'] - horizontal alignment style for images joined horizontally (`'left'`, `'centre'`, `'center'`, `'right'`).

lib/input.mjs

@@ -511,6 +511,9 @@ function _createInputDescriptor (input, inputOptions, containerOptions) {
             throw is.invalidParameterError('join.valign', 'valid alignment', inputOptions.join.valign);
           }
         }
+        if (inputDescriptor.joinAnimated && (inputDescriptor.joinAcross > 1 || inputDescriptor.joinShim > 0)) {
+          throw new Error('Expected neither join.across nor join.shim when join.animated is set');
+        }
       } else {
         throw new Error('Expected input to be an array of images to join');
       }

test/unit/join.js

@@ -124,6 +124,26 @@ suite('Join input images together', () => {
       /Expected integer between 0 and 100000 for join.shim but received -1 of type number/
     );
   });
+  test('Animated with across throws', (t) => {
+    t.plan(2);
+    t.assert.throws(
+      () => sharp([fixtures.inputJpg, fixtures.inputJpg], { join: { animated: true, across: 2 } }),
+      /Expected neither join.across nor join.shim when join.animated is set/
+    );
+    t.assert.doesNotThrow(
+      () => sharp([fixtures.inputJpg, fixtures.inputJpg], { join: { animated: true, across: 1 } })
+    );
+  });
+  test('Animated with shim throws', (t) => {
+    t.plan(2);
+    t.assert.throws(
+      () => sharp([fixtures.inputJpg, fixtures.inputJpg], { join: { animated: true, shim: 4 } }),
+      /Expected neither join.across nor join.shim when join.animated is set/
+    );
+    t.assert.doesNotThrow(
+      () => sharp([fixtures.inputJpg, fixtures.inputJpg], { join: { animated: true, shim: 0 } })
+    );
+  });
   test('Invalid halign', (t) => {
     t.plan(1);
     t.assert.throws(