Breaking change: make the watermark API more obvious

Before you could specify both “gravity” and “tile”, which didn’t make sense.
The name “tile” was also awkwardly close to the other argument “file”.

The new API with “position: Repeat” is more user friendly.

README.md

@@ -66,19 +66,25 @@ opts = { quality: 80 }
 
 ##### Watermark
 
+You can overlay a transparent watermark over the final image:
+
 ```js
 opts = {
   watermark: {
-    // PNG file with transparency, relative to the working directory
-    file: 'path/watermark.png',
-    // NorthWest | North | NorthEast | West | Center | East | SouthWest | South | SouthEast
-    gravity: 'SouthEast',
-    // whether the watermark should be repeated across the whole image
-    tile: false
+    file: 'path/watermark.png',  // transparent PNG
+    position: 'NorthEast'        // position of the watermark
   }
 }
 ```
 
+The possible values for `position` are:
+
+- `Repeat` to repeat the watermark across the whole image
+- `Center` to position the watermark in the middle
+- `NorthWest`, `North`, `NorthEast`, `West`, `East`, `SouthWest`, `South`, `SouthEast` to position the watermark along the edge
+
+![watermark](docs/watermark.jpg) ![tiled](docs/watermark-tiled.jpg)
+
 Note: watermarks are not compatible with cropped images.
 The `watermark` option will simply be ignored if both width and height are specified.
 

lib/index.js

@@ -18,11 +18,10 @@ exports.image = function (source, target, options, callback) {
   const cropping = options.width && options.height
   if (options.watermark && !cropping) {
     image.composite(options.watermark.file)
-    if (options.watermark.tile) {
+    if (options.watermark.position === 'Repeat') {
       image.tile(options.watermark.file)
-    }
-    if (options.watermark.gravity) {
-      image.gravity(options.watermark.gravity)
+    } else if (typeof options.watermark.position === 'string') {
+      image.gravity(options.watermark.position)
     } else {
       image.gravity('SouthEast')
     }

test/image.js

@@ -94,7 +94,7 @@ tape('can add a watermark in a given location', (test) => {
     options: {
       watermark: {
         file: 'test-data/input/images/watermark.png',
-        gravity: 'NorthEast'
+        position: 'NorthEast'
       }
     }
   })
@@ -107,7 +107,7 @@ tape('can add a tiled watermark', (test) => {
     options: {
       watermark: {
         file: 'test-data/input/images/watermark.png',
-        tile: true
+        position: 'Repeat'
       }
     }
   })