Merge pull request #290 from tradingview/129-two-price-axises

docs/3.0-breaking-changes.md

@@ -0,0 +1,140 @@
+# Version 3.0 breaking change
+
+Lighweight charts library 3.0 announces the major improvement: supporting two price scales.
+In order of keeping API clear and consistent, we desided to allow breaking change of the API.
+We understand disadvantages of breaking changes in the API, so we have not removed support of the current API at all, but have deprecated it, so the most common cases will continue working.
+You could refer new API [here](./price-scale.md)
+
+Following are migration rules.
+
+## Default behavior
+
+Default behavior is not changed. If you do not specify price scale options, the chart will have right price scale visible and all the serieses will assign to it.
+
+## Left price scale
+
+If you need the price scale to be drawn on the left side, you should make following changes.
+instead of
+
+```javascript
+var chart = LightweightCharts.createChart(container, {
+    priceScale: {
+        position: 'left',
+    },
+});
+```
+
+use
+
+```javascript
+var chart = LightweightCharts.createChart(container, {
+    rightPriceScale: {
+        visible: false,
+    },
+    leftPriceScale: {
+        visible: true,
+    },
+});
+```
+
+then specify target price scale while creating a series:
+
+```javascript
+var histSeries = chart.addHistogramSeries({
+    priceScaleId: 'left',
+});
+```
+
+New version fully supports this case via old API, however this support will be removed in the future releases.
+
+## No price scale
+
+To create chart without any visible price scale, instead of
+
+```javascript
+var chart = LightweightCharts.createChart(container, {
+    priceScale: {
+        position: 'none',
+    },
+});
+```
+
+use
+
+```javascript
+var chart = LightweightCharts.createChart(container, {
+    leftPriceScale: {
+        visible: false,
+    },
+    rightPriceScale: {
+        visible: false,
+    },
+});
+```
+
+New version fully supports this case via old API, however this support will be removed in the future releases.
+
+## Creating overlay
+
+To create an overlay series, instead of
+
+```javascript
+var histogramSeries = chart.addHistogramSeries({
+    overlay: true,
+});
+```
+
+use
+
+```javascript
+var histogramSeries = chart.addHistogramSeries({
+    // or any other _the same_ id for all overlay series
+    priceScaleId: '',
+});
+```
+
+New version fully supports this case via old API, however this support will be removed in the future releases.
+
+## Move price scale from right to left or vice versa
+
+To do this, instead of
+
+```javascript
+var chart = LightweightCharts.createChart(container);
+
+var mainSeries = chart.addLineSeries();
+
+...
+
+chart.applyOptions({
+    priceScale: {
+        position: 'left',
+    },
+});
+```
+
+use
+
+```javascript
+var chart = LightweightCharts.createChart(container);
+
+var mainSeries = chart.addLineSeries();
+
+...
+
+chart.applyOptions({
+    leftPriceScale: {
+        visible: 'true',
+    },
+    rightPriceScale: {
+        visible: 'false',
+    },
+});
+
+mainSeries.applyOptions({
+    priceScaleId: 'left,
+});
+
+```
+
+New version does not support this case via old API, so, if you use it, you should migrate your code in order of keeping it working.

docs/price-scale.md

@@ -0,0 +1,40 @@
+# Price Scale
+
+Price Scale is an object that maps prices to coordinates and vice versa.
+The rules of converting depend on price scale mod, visible height of chart and visible part of data.
+
+Chart always has two predefined price scales: left and right, and unlimited number of overlay scales.
+Left and right price scales could be visible, overlay price scales are always hidden, so the user cannot interact them directly.
+
+## Autoscale
+
+Autoscaling is a feature of automatic adjusting price scale to fit the visible range of data.
+Autoscaling is enabled by default, however you could turn it off by zooming price scale or calling `PriceScaleApi.setOptions` method with `autoScale` field set to false.
+Overlay price scales are always autoscaled.
+
+## PriceScale ID
+
+Each price scale has corresponsing ID to refer it via API. Left and right price scales have predefined IDs `left` and `right`.
+While creating a series, you could specify PriceScaleID.
+If this id refers to already existing price scale, new series will share the price scale with already existing series.
+If specified price scale does not exist, it will be implicitly created.
+So to create two series on the same overlay price scale just specify the same `priceScaleId` for them.
+You could get `id` of the scale with `PriceScaleApi.id` method.
+
+## Percentage scales
+
+Percentage mode of price scale allows relative comparing of series.
+All the serieses attached to the percentage scale are placed to have the first visible data item on the same point.
+Percentage scales are always autoscaled.
+
+## Logarithmic scales
+
+The reason of having logarithmic scales is comparing relative change instead of absolute change.
+On regular scale every candle with 100-points change has the same height.
+On logarithmic scale every candle with 2% change has the same height.
+Logarithmic scale cannot be percentage.
+
+## Equality of price scales
+
+Lightweight charts library does not guarantee to return the same instance of `PriceScaleApi` object while returning the same actual price scale.
+So you should never compare objects of `PriceScaleApi`, comapre `PriceScaleApi.id()` values instead.

docs/series-basics.md

@@ -38,15 +38,15 @@ Here are common parameters for every series:
 
 |Name|Type|Default|Description|
 |-|----|-------|-|
-|`overlay`|`boolean`|`false`|Whether or not series should be an overlay|
+|`priceScaleId`|`string`|`right` if right scale is visible and `left` if not|Target price scale to bind new series to|
 |`title`|`string`|`''`|You can name series when adding it to a chart. This name will be displayed on the label next to the last value label|
-|`scaleMargins`|`{ top, bottom }`|`undefined`|[Margins](#scale-margins) of the _overlay_ series|
+|`scaleMargins`|`{ top, bottom }`|`undefined`|[Margins](#scale-margins) of the price scale of series|
 
 Example:
 
 ```javascript
 const lineSeries = chart.addLineSeries({
-    overlay: true,
+    priceScaleId: 'left',
     title: 'Series title example',
     scaleMargins: {
         top: 0.1,
@@ -55,15 +55,38 @@ const lineSeries = chart.addLineSeries({
 });
 ```
 
-### Overlay
+### Binding to price scale
 
-When adding any series to a chart, you can specify if you want target series to be attached to a price axis. By default, series are attached to a price axis.
+When adding any series to a chart, you can specify if you want target series to be attached to a certain price axis - left or right.
+By default, series are attached to the right price axis.
 This means one can scale the series with price axis. Note that price axis visible range depends on series values.
-In contrast, overlay series just draws itself on a chart independent from the price axis.
 
 ```javascript
 const lineSeries = chart.addLineSeries({
-    overlay: true,
+    priceScaleId: 'left',
+});
+```
+
+In contrast, overlay series just draws itself on a chart independent from the visible price axis.
+To create overlay specify unique id as a `priceScaleId` or just keep is as empty string.
+
+```javascript
+const lineSeries = chart.addLineSeries({
+    priceScaleId: 'my-overlay-id',
+});
+```
+
+At any moment you can get access to the price scale the series is bound to with `priceScale` method and change its options
+
+```javascript
+const lineSeries = chart.addLineSeries({
+    priceScaleId: 'my-overlay-id',
+});
+lineSeries.priceScale().applyOptions({
+    scaleMargins: {
+        top: 0.1,
+        bottom: 0.3,
+    },
 });
 ```
 
@@ -84,7 +107,7 @@ Typically, we do not want series to be drawn too close to a chart border. It nee
 
 By default, the library keeps an empty space below the data (10%) and above the data (20%).
 
-These values could be adjusted for visible axis using chart options.  However, you can also define them for overlay series.
+These values could be adjusted for visible axis using chart options. However, you can also define them for series.
 
 The margins is an object with the following properties:
 
@@ -95,7 +118,7 @@ Each value of an object is a number between 0 (0%) and 1 (100%).
 
 ```javascript
 const lineSeries = chart.addLineSeries({
-    overlay: true,
+    priceScaleId: 'right,
     scaleMargins: {
         top: 0.6,
         bottom: 0.05,
@@ -105,11 +128,11 @@ const lineSeries = chart.addLineSeries({
 
 The code above places series at the bottom of a chart.
 
-You can change margins using `ChartApi.applyOptions` for the visible axis:
+You can change margins using `ChartApi.applyOptions` for the certain axis:
 
 ```javascript
 chart.applyOptions({
-    priceScale: {
+    rightPriceScale: {
         scaleMargins: {
             top: 0.6,
             bottom: 0.05,