doc: update docs with new api

Author: Maya Shavin

docs/url-docs/content/en/examples/advanced.md

@@ -1,7 +1,7 @@
 ---
 title: Advanced
 description: 'Advanced examples to use Cloudinary url builder'
-position: 7
+position: 8
 category: Examples
 ---
 

docs/url-docs/content/en/examples/basic.md

@@ -1,7 +1,7 @@
 ---
 title: Basic
 description: 'Basic examples to use Cloudinary url builder'
-position: 6
+position: 7
 category: Examples
 ---
 

docs/url-docs/content/en/options.md

@@ -3,6 +3,7 @@ title: Options
 description: 'Configuration options for Cloudinary url builder'
 position: 3
 category: Guide
+version: 1
 ---
 
 To configure the builder globally, you can use `setConfig()` method:
@@ -29,6 +30,8 @@ const src = buildImageUrl('public-id', {
 
 ## Cloudinary options
 
+* Type: `CloudConfig`
+
 ### `cloudName`
 
 * Type: `String`

docs/url-docs/content/en/usage/transformations.md

@@ -3,9 +3,10 @@ title: Transformations
 description: 'Supported transformation fields'
 position: 5
 category: Usage
+version: 1
 ---
 
-To transform and optimize your images and videos on delivery, you can pass the following fields to `options.transformations` in each build url method call.
+To transform and optimize your images and videos on delivery, you can pass the following fields to `options.transformations` in each build url method call or `options` in `Transformer.transform` call.
 
 <alert type="info">
 
@@ -52,7 +53,7 @@ See [Resize type](https://cloudinary.com/documentation/image_transformation_refe
 
 ### `rotation`
 
-* Type: `String` | `Number`
+* Type: `Rotation`
 * Accepted values: any degree number, or `auto_right` | `auto_left` | `ignore` | `vflip` | `hflip`
 
 To rotate or flip a given asset by certain degrees, or automatically based on orientation.
@@ -70,6 +71,12 @@ const url = buildImageUrl('example', {
 })
 ```
 
+<alert type="info">
+
+You can use import `ROTATION_MODES` from `cloudinary-build-url` to choose the desired rotation mode.
+
+</alert>
+
 ### `background`
 
 * Type: `String`
@@ -118,7 +125,8 @@ const url = buildImageUrl('example', {
 
 ### `effect`
 
-* Type: `String`
+* Type: `Effect`
+* An available effect or array of effects to apply to asset.
 
 Apply a filter or an effect on the desired asset. See[Effects](https://cloudinary.com/documentation/image_transformation_reference#effect_parameter) for the full list of syntax and available effects.
 
@@ -221,7 +229,7 @@ const url = buildImageUrl('example', {
 
 * Type: `String`
 
-Create a layer over the base image. This can be use with `x`, `y`, `gravity` to customize the position of the overlay.
+Create a layer over the base image. This can be use with `position.x`, `position.y`, `gravity` to customize the position of the overlay.
 
 ```js
 import { buildImageUrl } from 'cloudinary-build-url'
@@ -241,7 +249,7 @@ const url = buildImageUrl('face_top', {
 
 * Type: `String`
 
-Create a layer below a partial-transparent image. This can be use with `x`, `y`, `gravity` to customize the position of the underlay.
+Create a layer below a partial-transparent image. This can be use with `position.x`, `position.y`, `gravity` to customize the position of the underlay.
 
 ```js
 import { buildImageUrl } from 'cloudinary-build-url'
@@ -545,11 +553,15 @@ const url = buildImageUrl('example', {
 })
 ```
 
-### `x`
+### `position`
 
-* Type: `Number`
-
-Horizontal coordinate for cropping, placing overlay and applying regional effects.
+* Type: `Position`
+  * `x`
+    * Type: `number`
+    * Horizontal coordinate for cropping, placing overlay and applying regional effects.
+  * `y`
+    * Type: `Number`
+    * Vertical coordinate for cropping, placing overlay and applying regional effects.
 
 ```js
 import { buildImageUrl } from 'cloudinary-build-url'
@@ -559,31 +571,10 @@ const url = buildImageUrl('face-top', {
     cloudName: 'demo',
   },
   transformations: {
-    x: 130,
-    resize: {
-      width: 80,
-      height: 80,
-      type: 'crop'
+    position: {
+      x: 130,
+      y: 340
     }
-  }
-})
-```
-
-### `y`
-
-* Type: `Number`
-
-Vertical coordinate for cropping, placing overlay and applying regional effects.
-
-```js
-import { buildImageUrl } from 'cloudinary-build-url'
-
-const url = buildImageUrl('face-top', {
-  cloud: {
-    cloudName: 'demo',
-  },
-  transformations: {
-    y: 340,
     resize: {
       width: 80,
       height: 80,

docs/url-docs/content/en/usage/transformer.md

@@ -0,0 +1,68 @@
+---
+title: Transformer
+description: 'Generate the set of Cloudinary transformations'
+position: 6
+category: Usage
+version: 1
+---
+
+In addition to the build URL API, the package exposes an instance of `Transformer`, which can be used to calculate transformations independently.
+
+## `Transformer.transform(options)`
+
+* `options`:
+  * Type: `TransformerOption`
+  * **Required**
+  * Object contains all the accepted transformation keys and values to to generate.
+* Output:
+  * Type: `Transformation`
+
+Returns an array of mapped transformation params according to Cloudinary format.
+
+```js
+import { Transformer } from 'cloudinary-build-url 
+
+const transArr = Transformer.transform({
+  resize: {
+    width: 500,
+    height: 500,
+    type: 'thumb'
+  },
+  gravity: 'auto',
+  chaining: [{
+    effect: 'grayscale'
+  }]
+})
+
+console.log(transArr)
+//['c_thumb','w_500', 'h_500', 'g_auto', ['e_grayscale']]
+```
+
+See [Transformations](/usage/transformations) for more details on accepted properties for `options`.
+
+## `Transformer.toString(transformations)`
+
+* `transformations`:
+  * Type: `Transformation`
+  * Array of transformation params according to Cloudinary format.
+* Output:
+  * Type: `String`
+
+Returns a string that contains all the given transformations, separated by `,` or `/` and ready to inject to Cloudinary image URL.
+
+```js
+import { Transformer } from 'cloudinary-build-url'
+
+const trans = Transformer.toString([
+    'c_thumb',
+    'w_500',
+    'h_500',
+    'g_auto',
+    [ 'e_grayscale' ]
+  ])
+
+console.log(trans)
+//'c_thumb,w_500,h_500,g_auto/e_grayscale'
+```
+
+See [Image Transformation API](https://cloudinary.com/documentation/image_transformation_reference) for more details on how to compute transformation params.