[update] what's new for v5.2, add a draft for migration guide

Author: mafanya23

docs/migration.md

@@ -6,6 +6,83 @@ description: You can learn about migration in the documentation of the DHTMLX Ja
 
 # Migration to newer versions
 
+## 5.1 -> 5.2
+
+### toolbarBlocks
+
+In v5.2 the [toolbarBlocks](api/spreadsheet_toolbarblocks_config.md) property is modified in the following way:
+
+- the default set of toolbar options is extended by the new *"cell"* option. It includes the *Border* button and the *Merge* button (previously, it was in the *"align"* block) 
+- the *"actions"* toolbar block is extended with the *Insert link* button (previously, it was in the *"helpers"* block) 
+- the *"helpers"* toolbar block is renamed to *"help"* and isn't included in the default set of toolbar options
+
+~~~jsx title="Before v5.2" {9}
+// default configuration
+toolbarBlocks: [
+    "undo", 
+    "colors", 
+    "decoration", 
+    "align", 
+    "format", 
+    "actions",
+    "helpers"
+]
+~~~
+
+~~~jsx title="From v5.2" {7}
+// default configuration
+toolbarBlocks: [
+    "undo", 
+    "colors", 
+    "decoration", 
+    "align", 
+    "cell",
+    "format", 
+    "actions"
+]
+~~~
+
+### Freezing/unfreezing functionality
+
+In v5.2 the way of freezing/unfreezing columns and rows has been modified:
+
+- the `leftSplit` and `topSplit` configuration properties that have been used for fixing columns and rows were deprecated
+- new API methods `freezeCols()`, `unfreezeCols()`, `freezeRows()`, `unfreezeRows()` and a new action `toggleFreeze` were introduced
+
+~~~jsx title="Before v5.0"
+const spreadsheet = new dhx.Spreadsheet("spreadsheet_container", {
+    topSplit: 1, // the number of row to "freeze"
+    leftSplit: 1 // the number of columns to "freeze"
+});
+~~~
+
+~~~jsx title="From v5.0" 
+// for rows
+spreadsheet.freezeRows("B2"); // the rows up to the second row will be fixed
+spreadsheet.freezeRows("sheet2!B2"); // the rows up to the second row in "sheet2" will be fixed
+spreadsheet.unfreezeRows(); // fixed rows in the current sheet will be unfrozen
+spreadsheet.unfreezeRows("sheet2!A1"); // fixed rows in "sheet2" will be unfrozen
+
+// for columns
+spreadsheet.freezeCols("B2"); // the columns up to the "B" column will be fixed
+spreadsheet.freezeCols("sheet2!B2"); // the columns up to the "B" column in "sheet2" will be fixed
+spreadsheet.unfreezeCols(); // fixed columns in the current sheet will be unfrozen
+spreadsheet.unfreezeCols("sheet2!A1"); // fixed columns in "sheet2" will be unfrozen
+
+// using the `toggleFreeze` action with the beforeAction/afterAction events
+spreadsheet.events.on("afterAction", (actionName, config) => {
+    if (actionName === "toggleFreeze") {
+        console.log(actionName, config);
+    }
+});
+
+spreadsheet.events.on("beforeAction", (actionName, config) => {
+    if (actionName === "toggleFreeze") {
+        console.log(actionName, config);
+    }
+});
+~~~
+
 ## 4.3 -> 5.0
 
 In v5.0, the *"help"* option of the [toolbarBlocks](api/spreadsheet_toolbarblocks_config.md) property is renamed to *"helpers"*. Besides, the default set of options is extended by the new *"actions"* option.

docs/whats_new.md

@@ -31,11 +31,13 @@ The new release introduces some changes to the `toolbarBlocks` property and the
     - the ability to freeze/unfreeze columns and rows via API
         - new methods: `freezeCols()`, `unfreezeCols()`, `freezeRows()`, `unfreezeRows()`
         - new action: `toggleFreeze` 
+        - new `freeze` property for the *sheets* object of the `parse()` method
 - Hiding/showing columns/rows:
     - the ability to hide/show columns and rows via UI
     - the ability to hide/show columns and rows via API
         - new methods: `hideCols()`, `showCols()`, `hideRows()`, `showRows()`
         - new action: `toggleVisibility` 
+        - new `hidden` property for the *cols* and *rows* configs of the *sheets* object of the `parse()` method
 - Working with formulas:
     - a popup with descriptions for formulas is added
     - a new locale: `formulas` is added