#1199: Fix merge strategy and add docs

Author: JosefBredereck

packages/core/src/lib/pseudopattern_hunter.js

@@ -73,8 +73,6 @@ pseudopattern_hunter.prototype.find_pseudopatterns = function(
             !patternlab.config.patternMergeVariantArrays
           ) {
             return srcValue;
-          } else if (_.isArray(objValue)) {
-            return objValue.concat(srcValue);
           }
           // Lodash will only check for "undefined" and eslint needs a consistent
           // return so do not remove

packages/core/test/pseudopattern_hunter_tests.js

@@ -148,8 +148,8 @@ tap.test('pseudo pattern variant data should merge arrays', function(test) {
       JSON.stringify(pl.patterns[1].jsonFileData),
       JSON.stringify({
         a: 2,
-        b: [2, 3, 8],
-        c: { d: [4, 5, 6, 7], e: 8, f: { a: ['a'], b: ['b', 'x'], c: ['c'] } },
+        b: [8, 3],
+        c: { d: [6, 7], e: 8, f: { a: ['a'], b: ['x'], c: ['c'] } },
       })
     );
   });
@@ -170,12 +170,8 @@ tap.test(
         JSON.stringify(pl.patterns[1].jsonFileData),
         JSON.stringify({
           a: 2,
-          b: [2, 3, 8],
-          c: {
-            d: [4, 5, 6, 7],
-            e: 8,
-            f: { a: ['a'], b: ['b', 'x'], c: ['c'] },
-          },
+          b: [8, 3],
+          c: { d: [6, 7], e: 8, f: { a: ['a'], b: ['x'], c: ['c'] } },
         })
       );
     });

packages/docs/src/docs/advanced-config-options.md

@@ -186,6 +186,19 @@ For example, to export the navigation, header, and footer, one might do:
 
 **default**: `[]`
 
+### patternMergeVariantArrays
+
+Used to override the merge behavior of pattern variants. For more information see [The Pseudo-Pattern File Data](docs/using-pseudo-patterns/#heading-the-pseudo-pattern-file data).
+
+- `true` will merge arrays of the pattern and pseudo-pattern with [lodash merge](https://lodash.com/docs/4.17.15#merge)
+- `false` will override arrays from the pattern with pseudo-patterns arrays
+
+```javascript
+"patternMergeVariantArrays": true,
+```
+
+**default**: `true` | `undefined`
+
 ### serverOptions
 
 Sets live-server options. See the [live-server documentation](https://github.com/pattern-lab/live-server#usage-from-node) for more details.

packages/docs/src/docs/pattern-pseudo-patterns.md

@@ -19,7 +19,9 @@ Pseudo-patterns are similar to [pattern-specific JSON files](/docs/creating-patt
 
 The tilde (`~`) and `.json` file extension are the hints that Pattern Lab uses to determine that this is a pseudo-pattern. The `patternName` tells Pattern Lab which existing pattern it should use when rendering the pseudo-pattern. The JSON file itself works exactly like the [pattern-specific JSON file](/docs/creating-pattern-specific-values/). It has the added benefit that the pseudo-pattern will also inherit any values from the existing pattern's pattern-specific JSON file.
 
-By default, arrays in pseudo-pattern data will be concatenated with the base pattern's array data. To override this behavior globally you can set the parameter `patternMergeVariantArrays` in your `patternlab-config.json` to `false`. Arrays will then be overwritten and you will only have the variant's array data left.
+## The Pseudo-Pattern File Data
+
+By default, arrays in pseudo-pattern data will be merged with the base pattern's array data on an index basis, effectively creating an array having as many entries as the larger of the two, with the indices declared in the variant replacing the first n of the parent, while keeping the rest. Declaring a larger array in the variant results in only using the variant array. To override this behavior globally you can set the parameter `patternMergeVariantArrays` in your `patternlab-config.json` to `false`. Arrays will then be overwritten and you will only have the variant's array data left.
 
 ```json
 "patternMergeVariantArrays": false