Merge pull request #51 from DHTMLX/next

Rewrite/clarify doc using skills

Author: serhiipylypchuk1991

docs/api/config/columnshape-property.md

@@ -19,10 +19,10 @@ columnShape?: {
         [field: string]: number
     },
     autoWidth?: {
-        columns?: {
+        columns: {
             [field: string]: boolean
         },
-        auto: boolean | "header" | "data",
+        auto?: boolean | "header" | "data",
         maxRows?: number,
         firstOnly?: boolean
     }
@@ -34,9 +34,9 @@ columnShape?: {
 - `sort` - (optional) if **true** (default), the sorting is enabled in UI by clicking the column header; if **false**, the sorting is disabled
 - `width` - (optional) defines the width of a column; it's an object where each key is a field id and the value is the width of the column in pixels
 - `autoWidth` - (optional) an object that defines how column width should be calculated automatically. The default configuration uses 20 rows, and the width is calculated based on the header and data, with each field analyzed only once. The object parameters are the following: 
-    - `columns` - (optional) an object where each key is a field id and the boolean value defines whether column width should be calculated automatically
-    - `auto` - (required) if set to **header**, adjusts the width to the header text; if set to **data**, adjusts the width to the cell with the widest content; if set to **true**, the width is adjusted to the content of both headers and cell.
-    If autowidth is set  to **false**, the `width` value is set or the value of the `columnWidth` from the [`tableShape`](/api/config/tableshape-property) property is applied.
+    - `columns` - (required) an object where each key is a field id and the boolean value defines whether column width should be calculated automatically
+    - `auto` - (optional) if set to **header**, adjusts the width to the header text; if set to **data**, adjusts the width to the cell with the widest content; if set to **true**, the width is adjusted to the content of both headers and cell.
+    If autowidth is set  to **false**, the `width` value is set or the value of the `columnWidth` from the [`tableShape`](api/config/tableshape-property.md) property is applied.
     - `maxRows` - (optional) the number of rows to be processed for the autoWidth calculation
     - `firstOnly` - (optional) if set to **true** (default), each field of the same data is analyzed only once to calculate the column width; in case of multiple columns based on the same data (e.g., the *oil* field with the *count* operation and the *oil* field with the *sum* operation), only data in the first one will be analyzed and the others will inherit this width
 
@@ -77,6 +77,6 @@ const table = new pivot.Pivot("#root", {
 });
 ~~~
 
-**Related samples:**
+**Related samples**:
 - [Pivot 2. Auto width. Sizing columns to content](https://snippet.dhtmlx.com/tn1yw14m)
 - [Pivot 2. Set columns width](https://snippet.dhtmlx.com/ceu34kkn)

docs/api/config/config-property.md

@@ -27,14 +27,14 @@ The `config` parameters are used to define which fields will be applied as rows
 
 - `rows` - (optional) defines the rows of the Pivot table. The default value is an empty array. It can be a string which represents a single field ID or an object with the field ID and a method for data extraction; the object parameters are the following:
   - `field` - (required) the ID of a field
-  - `method` - (optional) defines a method for data aggregation in the field; methods for the time-based data fields are available by default: year, month, day, hour, minute which group data by year/month/day/hour; here you can also add the name of a custom method ([see `predicates`](/api/config/predicates-property)) for the field of any data type
+  - `method` - (optional) defines a method for data aggregation in the field; methods for the time-based data fields are available by default: "year", "quarter", "month", "week", "day", "hour", "minute" which group data accordingly; here you can also add the name of a custom method ([see `predicates`](api/config/predicates-property.md)) for the field of any data type
 - `columns` - (optional) defines columns for the Pivot table. It's an empty array by default. It can be a single field ID or an object with the field ID and a method for data extraction; the object parameters are the following:
   - `field` - (required) the ID of a field
   - `method` - (optional) defines a method for data processing (for time-based data fields).
-  By default, methods are available for the time-based fields (the **date** type) with the next values: "year", "quarter", "month", "week", "day", "hour", "minute". Here you can also add the name of a custom method ([see `predicates`](/api/config/predicates-property)) for the field of any data type
+  By default, methods are available for the time-based fields (the **date** type) with the next values: "year", "quarter", "month", "week", "day", "hour", "minute". Here you can also add the name of a custom method ([see `predicates`](api/config/predicates-property.md)) for the field of any data type
 - `values` - (optional) defines the data aggregation for the cells of the Pivot table. It's an empty array by default. Each element can be a string representing a data field ID and aggregation method or an object containing the field ID and the method for data aggregation. The object parameters are the following:
   - `field` - (required) the ID of a field
-  - `method` - (required) defines a method for data extraction; for methods types and their description refer to [Applying methods](/guides/working-with-data#default-methods)
+  - `method` - (required) defines a method for data extraction; for methods types and their description refer to [Applying methods](guides/working-with-data.md#default-methods)
 
 <details>
 
@@ -49,7 +49,7 @@ You can define `values` in either of the two equally valid ways:
 ~~~jsx
 values: [
     "sum(sales)", // option one
-    { id: "sales", method: "sum" }, // option two
+    { field: "sales", method: "sum" }, // option two
 ]
 ~~~
 
@@ -78,7 +78,7 @@ values: [
     - `includes` - (optional) an array of values to be displayed from those that are already filtered; available for text and dates values
 
 :::info
-When config is processed by Pivot, its properties receive extra data and if you try to return the config state via the [`api.getState()`](/api/internal/getstate-method) method, the full object will look like this:
+When config is processed by Pivot, its properties receive extra data and if you try to return the config state via the [`api.getState()`](api/internal/getstate-method.md) method, the full object will look like this:
 
 ~~~jsx
 interface IParsedField {

docs/api/config/configpanel-property.md

@@ -50,9 +50,9 @@ const table = new pivot.Pivot("#root", {
 });
 ~~~
 
-**Related sample:** [Pivot 2.0: Toggle visibility of configuration panel](https://snippet.dhtmlx.com/1xq1x5bo)
+**Related sample**: [Pivot 2.0: Toggle visibility of configuration panel](https://snippet.dhtmlx.com/1xq1x5bo)
 
-**Related articles:**
-- [`show-config-panel` event](/api/events/show-config-panel-event)
-- [`showConfigPanel()` method](/api/methods/showconfigpanel-method)
-- [Controlling visibility of Configuration panel](/guides/configuration#controlling-visibility-of-configuration-panel)
+**Related articles**:
+- [`show-config-panel` event](api/events/show-config-panel-event.md)
+- [`showConfigPanel()` method](api/methods/showconfigpanel-method.md)
+- [Controlling visibility of Configuration panel](guides/configuration.md#controlling-visibility-of-configuration-panel)

docs/api/config/fields-property.md

@@ -32,21 +32,21 @@ Each object in the `fields` array should have the following properties:
 
 - `id` - (required) the ID of a field
 - `label` - (optional) the field label to be displayed in GUI
-- `type` - (required) data type in a field ( "number", "date", or "string")
+- `type` - (required) data type in a field ( "number", "date", or "text")
 - `sort` - (optional) defines the default sorting order for the field. Accepts "asc", "desc", or a custom sorting function
-- `format` - (optional) allows customizing the format of numbers and dates in a field; the format will be also applied during [export](/guides/exporting-data)
+- `format` - (optional) allows customizing the format of numbers and dates in a field; the format will be also applied during [export](guides/exporting-data.md)
     - `string` - (optional) the format for dates (by default, Pivot uses `dateFormat` from locale)
     - `boolean` - (optional) if set to **false**, a number is displayed as is, without any formatting
     - `numberFormatOptions` - (optional) an object with options for formatting numeric fields; by default, numbers will be shown with a maximum of 3 decimal digits and group separation for the integer part is applied.
         - `minimumIntegerDigits`(number) - (optional) the minimum number of integer (for example, if the value is set to 2, the number 1 will be shown as "01"); the default is 1;
-        - `minimumFractionDigits`(number) - (optional) the minimum number of fraction digits to use (for example, if the value is set to 2, the number 10.5 will be shown as "10.50"); the default is 1;
+        - `minimumFractionDigits`(number) - (optional) the minimum number of fraction digits to use (for example, if the value is set to 2, the number 10.5 will be shown as "10.50"); the default is 0;
         - `maximumFractionDigits`(number) - (optional) the maximum number of fraction digits to use (for example, if the value is set to 2, the number 10.3333... will be shown as "10.33"); the default is 3;  
         For more details about digit options refer to  [Digit options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#minimumintegerdigits)
         - `prefix` (string) - (optional) a string (before a number) for additional symbols like currency
         - `suffix` (string) - (optional) a string (after a number) for additional symbols like currency
 
 :::info
-If a template is applied via the [`tableShape`](/api/config/tableshape-property) property, it will override the `format` settings.
+If a template is applied via the [`tableShape`](api/config/tableshape-property.md) property, it will override the `format` settings.
 :::
 
 ### Example
@@ -106,7 +106,7 @@ const table = new pivot.Pivot("#root", {
 
 **Related articles**: 
 
-- [Number formatting](/guides/localization/#number-formatting)
-- [Applying formats to fields](/guides/working-with-data/#applying-formats-to-fields)
+- [Number formatting](guides/localization.md#number-formatting)
+- [Applying formats to fields](guides/working-with-data.md#applying-formats-to-fields)
 
-**Related sample:**  [Pivot 2. Defining fields formats](https://snippet.dhtmlx.com/77nc4j8v)
+**Related sample**:  [Pivot 2. Defining fields formats](https://snippet.dhtmlx.com/77nc4j8v)

docs/api/config/headershape-property.md

@@ -76,8 +76,8 @@ new pivot.Pivot("#pivot", {
 **Related samples**:
 - [Pivot 2. Vertical orientation of text in grid headers](https://snippet.dhtmlx.com/4qroi8ka)
 - [Pivot 2. Collapsible columns](https://snippet.dhtmlx.com/pt2ljmcm)
-- [Pivot 2. Adding сustom CSS for table and header cells](https://snippet.dhtmlx.com/nfdcs4i2)
+- [Pivot 2. Adding custom CSS for table and header cells](https://snippet.dhtmlx.com/nfdcs4i2)
 
 **Related articles**: 
-- [Configuration](/guides/configuration)
-- [Cell style](/guides/stylization/#cell-style)
+- [Configuration](guides/configuration.md)
+- [Cell style](guides/stylization.md#cell-style)

docs/api/config/limits-property.md

@@ -10,7 +10,7 @@ description: You can learn about the limits config in the documentation of the D
 
 @short: Optional. Defines the maximum limit for the number of rows and columns in the final dataset
 
-Please, also refer to [Limiting data](/guides/working-with-data#limiting-loaded-data).
+Please, also refer to [Limiting data](guides/working-with-data.md#limiting-loaded-data).
 
 ### Usage
 
@@ -58,4 +58,4 @@ const table = new pivot.Pivot("#root", {
 });
 ~~~
 
-**Related sample:** [Pivot 2. Data limits](https://snippet.dhtmlx.com/7ryns8oe)
+**Related sample**: [Pivot 2. Data limits](https://snippet.dhtmlx.com/7ryns8oe)

docs/api/config/locale-property.md

@@ -18,10 +18,10 @@ locale?: object;
 
 ### Default config
 
-By default, Pivot uses the [English](/guides/localization/#default-locale) locale. You can set it to the custom locale as well.
+By default, Pivot uses the [English](guides/localization.md#default-locale) locale. You can set it to the custom locale as well.
 
 :::tip
-To change the current locale dynamically, you can use the [`setLocale()`](/api/methods/setlocale-method) method of Pivot
+To change the current locale dynamically, you can use the [`setLocale()`](api/methods/setlocale-method.md) method of Pivot
 :::
 
 ### Example

docs/api/config/methods-property.md

@@ -68,7 +68,7 @@ defaultMethods = {
 };
 ~~~
 
-The definition of each method you can see here: [Applying methods](/guides/working-with-data#default-methods)
+The definition of each method you can see here: [Applying methods](guides/working-with-data.md#default-methods)
 
 ## Example
 
@@ -158,6 +158,6 @@ const table = new pivot.Pivot("#root", {
 });
 ~~~
 
-**Related sample:** [Pivot 2. Custom maths methods](https://snippet.dhtmlx.com/lv90d8q2) 
+**Related sample**: [Pivot 2. Custom maths methods](https://snippet.dhtmlx.com/lv90d8q2) 
 
-**Related article**: [Applying maths methods](/guides/working-with-data#applying-maths-methods)
+**Related article**: [Applying maths methods](guides/working-with-data.md#applying-maths-methods)

docs/api/config/predicates-property.md

@@ -41,12 +41,14 @@ The property is an object where a key is the name of a custom function and value
     - `type` - (optional) defines which field type will be applied: "number"|"text"|"date"|"tuple". "tuple" is a combo filter applied for numeric values (data will be filtered by the numeric value but in filter the text value will be displayed)
     - `format` - (optional) the function that defines the format for displaying filter options; if no format is defined, the one from the template parameter will be applied; if the type here (for the `filter` object) is not specified, the format will be applied for the type set for the `type` parameter of the predicate
 - `handler` - (required for custom predicates) the function that defines how data should be processed; the function should take a single argument as the value to be processed and return the processed value
-- `template` - (optional) the function that defines how data should be displayed; the function returns the processed value and it takes the value returned by `handler` and if necessary you can localize text values using [`locale`](/api/config/locale-property).
+- `template` - (optional) the function that defines how data should be displayed; the function returns the processed value and it takes the value returned by `handler` and if necessary you can localize text values using [`locale`](api/config/locale-property.md).
 
 The following default predicates are applied in case no predicate is specified via the `predicates` property:
 
 ~~~jsx
 const defaultPredicates = {
+    // a service predicate that represents the raw (unprocessed) value
+    $empty: { label: (type) => `Raw ${type}`, type: ["number", "date", "text"] },
     year: { label: "Year", type: "date", filter: { type: "number" } },
     quarter: { label: "Quarter", type: "date", filter: { type: "tuple" } },
     month: { label: "Month", type: "date", filter: { type: "tuple" } },
@@ -110,6 +112,6 @@ const table = new pivot.Pivot("#pivot", {
 });
 ~~~
 
-**Related article**: [Processing data with predicates](/guides/working-with-data#processing-data-with-predicates)
+**Related article**: [Processing data with predicates](guides/working-with-data.md#processing-data-with-predicates)
 
 **Related sample**: [Pivot 2. Custom predicates](https://snippet.dhtmlx.com/mhymus00)

docs/api/config/readonly-property.md

@@ -49,4 +49,4 @@ const table = new pivot.Pivot("#root", {
 });
 ~~~
 
-**Related sample:** [Pivot 2. Readonly mode](https://snippet.dhtmlx.com/0k0mvycv)
+**Related sample**: [Pivot 2. Readonly mode](https://snippet.dhtmlx.com/0k0mvycv)