@vaadin/charts 24.7.0-alpha6 → 24.7.0-alpha8

package/web-types.lit.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/web-types",
   "name": "@vaadin/charts",
-  "version": "24.7.0-alpha6",
+  "version": "24.7.0-alpha8",
   "description-markup": "markdown",
   "framework": "lit",
   "framework-config": {
@@ -14,6 +14,90 @@
   "contributions": {
     "html": {
       "elements": [
+        {
+          "name": "vaadin-chart-series",
+          "description": "`<vaadin-chart-series>` is a custom element for creating series for Vaadin Charts.\n\n### Basic use\n\nTo use `<vaadin-chart-series>`, add it inside a `<vaadin-chart>` element:\n\n```html\n <vaadin-chart>\n   <vaadin-chart-series></vaadin-chart-series>\n </vaadin-chart>\n```\n\n`<vaadin-chart-series>` accepts `values` as an array attribute, so you can add it to your element definition:\n\n```html\n <vaadin-chart-series values=\"[10,20,30,40,50]\"></vaadin-chart-series>\n```\n\nwhich will add a new line series, where each value will be a data point.\nLook for the Properties session to see all available attributes.\n\n### Dynamically adding and removing series\n\nYou are also able to add and remove series by using DOM API.\n\nTo create a new series, call `document.createElement('vaadin-chart-series')` and append it to your `<vaadin-chart>`:\n\n```js\n const chart = \\* a <vaadin-chart> reference *\\\n const newSeries = document.createElement('vaadin-chart-series');\n newSeries.values = [10,20,30,40,50];\n chart.appendChild(newSeries);\n```\n\nIn order to remove it, you should use the series to be removed as a reference for the `#removeChild()` call:\n\n```js\n const chart = \\* a <vaadin-chart> reference *\\\n const seriesToBeRemoved = \\* a <vaadin-chart-series> reference to remove*\\\n chart.removeChild(seriesToBeRemoved);\n```",
+          "extension": true,
+          "attributes": [
+            {
+              "name": ".values",
+              "description": "An array of data used by the series.\nFormat depends on the chart type and can be:\n  - An array of numerical values `[y0, y1, y2, y3,...]`\n  - An array of arrays with 2 values (`x`, `y`) `[ [x0, y0], [x1, y1], [x2, y2], ... ]`\n  - An array of objects, each one describing one point `[ {x: x0, y: y0, name: 'Point0', color: '#FF0000'}, {...}, ...]`\n\n See more in [API Site](https://api.highcharts.com/highcharts/series)\n\nNote that you should always use [Polymer API](https://www.polymer-project.org/2.0/docs/devguide/model-data#array-mutation)\nto mutate the values array in order to make the component aware of the\nchange and be able to synchronize it.",
+              "value": {
+                "kind": "expression"
+              }
+            },
+            {
+              "name": ".valueMin",
+              "description": "Value-axis minimum-value.\nSets the value to a series bound by 'unit' property.\nOtherwise sets the value to the first series.\nUndefined by default (determined from data).",
+              "value": {
+                "kind": "expression"
+              }
+            },
+            {
+              "name": ".valueMax",
+              "description": "Value-axis maximum-value.\nSee the 'valueMin'",
+              "value": {
+                "kind": "expression"
+              }
+            },
+            {
+              "name": ".type",
+              "description": "A string with the type of the series.\nDefaults to `'line'` in case no type is set for the chart.\nNote that `'bar'`, `'gauge'` and `'solidgauge'` should be set as default series type on `<vaadin-chart>`.",
+              "value": {
+                "kind": "expression"
+              }
+            },
+            {
+              "name": ".title",
+              "description": "The name of the series as shown in the legend, tooltip etc.",
+              "value": {
+                "kind": "expression"
+              }
+            },
+            {
+              "name": ".markers",
+              "description": "Shows/hides data-point markers for line-like series.\nAcceptable input are:\n - `shown`: markers are always visible\n - `hidden`: markers are always hidden\n - `auto`: markers are visible for widespread data and hidden, when data is dense *(default)*",
+              "value": {
+                "kind": "expression"
+              }
+            },
+            {
+              "name": ".unit",
+              "description": "Used to connect the series to an axis; if multiple series have the same `unit`, they will share axis.\nDisplayed as a title for the axis.\nIf no unit is defined, then series will be connected to the first axis.",
+              "value": {
+                "kind": "expression"
+              }
+            },
+            {
+              "name": ".stack",
+              "description": "Used to group series in a different stacks.\n\"stacking\" property should be specified either for each series or in plotOptions.\nIt is recommended to place series in a single stack, when they belong to the same yAxis.",
+              "value": {
+                "kind": "expression"
+              }
+            },
+            {
+              "name": ".neckPosition",
+              "description": "The height of the neck, the lower part of the funnel.\nA number defines pixel width, a percentage string defines a percentage of the plot area height. Defaults to 30%.\nNote that this property only applies for \"funnel\" charts.",
+              "value": {
+                "kind": "expression"
+              }
+            },
+            {
+              "name": ".neckWidth",
+              "description": "The width of the neck, the lower part of the funnel.\nA number defines pixel width, a percentage string defines a percentage of the plot area width. Defaults to 30%.\nNote that this property only applies for \"funnel\" charts.",
+              "value": {
+                "kind": "expression"
+              }
+            },
+            {
+              "name": ".additionalOptions",
+              "description": "Represents additional JSON configuration.",
+              "value": {
+                "kind": "expression"
+              }
+            }
+          ]
+        },
         {
           "name": "vaadin-chart",
           "description": "`<vaadin-chart>` is a Web Component for creating high quality charts.\n\n### Basic use\n\nThere are two ways of configuring your `<vaadin-chart>` element: **HTML API**, **JS API** and **JSON API**.\nNote that you can make use of all APIs in your element.\n\n#### Configuring your chart using HTML API\n\n`vaadin-chart` has a set of attributes to make it easier for you to customize your chart.\n\n```html\n <vaadin-chart title=\"The chart title\" subtitle=\"The chart subtitle\">\n   <vaadin-chart-series\n         type=\"column\"\n         title=\"The series title\"\n         values=\"[10,20,30]\">\n   </vaadin-chart-series>\n </vaadin-chart>\n```\n\n> Note that while you can set type for each series individually, for some types, such as `'bar'`, `'gauge'` and `'solidgauge'`, you\n> have to set it as the default series type on `<vaadin-chart>` in order to work properly.\n\n#### Configuring your chart using JS API\n\n1. Set an id for the `<vaadin-chart>` in the template\n```html\n    <vaadin-chart id=\"mychart\"></vaadin-chart>\n```\n1. Add a function that uses `configuration` property (JS Api) to set chart title, categories and data\n```js\ninitChartWithJSApi() {\n    requestAnimationFrame(() => {\n       const configuration = this.$.mychart.configuration;\n       configuration.setTitle({ text: 'The chart title' });\n       // By default there is one X axis, it is referenced by configuration.xAxis[0].\n       configuration.xAxis[0].setCategories(['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']);\n       configuration.addSeries({\n           type: 'column',\n           data: [29.9, 71.5, 106.4, 129.2, 144.0, 176.0, 135.6, 148.5, 216.4, 194.1, 95.6, 54.4]\n       });\n    });\n}\n```\n1. Call that function from connectedCallback (when the element is added to a document)\n```js\nconnectedCallback() {\n    super.connectedCallback();\n    this.initChartWithJSApi();\n}\n```\n\n#### Configuring your chart using JS JSON API\n\nJS JSON API is a simple alternative to the JS API.\n\n1. Set an id for the `<vaadin-chart>` in the template\n```html\n    <vaadin-chart id=\"mychart\"></vaadin-chart>\n```\n1. Add a function that uses `updateConfiguration` method (JS JSON Api) to set chart title, categories and data\n```js\ninitChartWithJSJSONApi() {\n    this.$.mychart.updateConfiguration({\n      title: {\n        text: 'The chart title'\n      },\n      subtitle: {\n        text: 'Subtitle'\n      },\n      xAxis: {\n        categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']\n      },\n      series: [{\n        type: 'column',\n        data: [29.9, 71.5, 106.4, 129.2, 144.0, 176.0, 135.6, 148.5, 216.4, 194.1, 95.6, 54.4]\n      }]\n    });\n}\n```\n1. Call that function from connectedCallback (when the element is added to a document)\n```js\nconnectedCallback() {\n    super.connectedCallback();\n    this.initChartWithJSJSONApi();\n}\n```\n\nIt should be noted that chart style customization cannot be done via the JS or JSON API.\nStyling properties in the JSON configuration will be ignored. The following section discusses chart styling.\n\n### CSS Styling\n\nChart appearance is primarily controlled by CSS style rules.\nA comprehensive list of the supported style classes can be found at\nhttps://www.highcharts.com/docs/chart-design-and-style/style-by-css\n\nSee also the [Chart Styling](https://vaadin.com/docs/latest/components/charts/css-styling) documentation.\n\n### RTL support\n\n`vaadin-charts` as well as [Highcharts](https://www.highcharts.com/) by itself are not adjusting the layout\nbased on the `dir` attribute. In order to make `vaadin-charts` display RTL content properly additional\nJSON configuration should be used.\nEach chart should be updated based on the specific needs, but general recommendations are:\n\n 1. Set `reversed` to true for xAxis (https://api.highcharts.com/highcharts/xAxis.reversed).\n 2. Set `useHTML` to true for text elements, i.e. `tooltip` (https://api.highcharts.com/highcharts/tooltip.useHTML).\n 3. Set `rtl` to true for `legend` (https://api.highcharts.com/highcharts/legend.rtl).\n\n### Setting colors\n\nAlthough charts can be styled as described above, there is a simpler way for setting colors.\nColors can be set using CSS custom properties `--vaadin-charts-color-{n}` (where `n` goes from `0 - 9`).\n\nFor example `--vaadin-charts-color-0` sets the color of the first series on a chart.\n\n### Validating your License\n\nWhen using Vaadin Charts in a development environment, you will see a pop-up that asks you\nto validate your license by signing in to vaadin.com.",
@@ -363,90 +447,6 @@
               }
             }
           ]
-        },
-        {
-          "name": "vaadin-chart-series",
-          "description": "`<vaadin-chart-series>` is a custom element for creating series for Vaadin Charts.\n\n### Basic use\n\nTo use `<vaadin-chart-series>`, add it inside a `<vaadin-chart>` element:\n\n```html\n <vaadin-chart>\n   <vaadin-chart-series></vaadin-chart-series>\n </vaadin-chart>\n```\n\n`<vaadin-chart-series>` accepts `values` as an array attribute, so you can add it to your element definition:\n\n```html\n <vaadin-chart-series values=\"[10,20,30,40,50]\"></vaadin-chart-series>\n```\n\nwhich will add a new line series, where each value will be a data point.\nLook for the Properties session to see all available attributes.\n\n### Dynamically adding and removing series\n\nYou are also able to add and remove series by using DOM API.\n\nTo create a new series, call `document.createElement('vaadin-chart-series')` and append it to your `<vaadin-chart>`:\n\n```js\n const chart = \\* a <vaadin-chart> reference *\\\n const newSeries = document.createElement('vaadin-chart-series');\n newSeries.values = [10,20,30,40,50];\n chart.appendChild(newSeries);\n```\n\nIn order to remove it, you should use the series to be removed as a reference for the `#removeChild()` call:\n\n```js\n const chart = \\* a <vaadin-chart> reference *\\\n const seriesToBeRemoved = \\* a <vaadin-chart-series> reference to remove*\\\n chart.removeChild(seriesToBeRemoved);\n```",
-          "extension": true,
-          "attributes": [
-            {
-              "name": ".values",
-              "description": "An array of data used by the series.\nFormat depends on the chart type and can be:\n  - An array of numerical values `[y0, y1, y2, y3,...]`\n  - An array of arrays with 2 values (`x`, `y`) `[ [x0, y0], [x1, y1], [x2, y2], ... ]`\n  - An array of objects, each one describing one point `[ {x: x0, y: y0, name: 'Point0', color: '#FF0000'}, {...}, ...]`\n\n See more in [API Site](https://api.highcharts.com/highcharts/series)\n\nNote that you should always use [Polymer API](https://www.polymer-project.org/2.0/docs/devguide/model-data#array-mutation)\nto mutate the values array in order to make the component aware of the\nchange and be able to synchronize it.",
-              "value": {
-                "kind": "expression"
-              }
-            },
-            {
-              "name": ".valueMin",
-              "description": "Value-axis minimum-value.\nSets the value to a series bound by 'unit' property.\nOtherwise sets the value to the first series.\nUndefined by default (determined from data).",
-              "value": {
-                "kind": "expression"
-              }
-            },
-            {
-              "name": ".valueMax",
-              "description": "Value-axis maximum-value.\nSee the 'valueMin'",
-              "value": {
-                "kind": "expression"
-              }
-            },
-            {
-              "name": ".type",
-              "description": "A string with the type of the series.\nDefaults to `'line'` in case no type is set for the chart.\nNote that `'bar'`, `'gauge'` and `'solidgauge'` should be set as default series type on `<vaadin-chart>`.",
-              "value": {
-                "kind": "expression"
-              }
-            },
-            {
-              "name": ".title",
-              "description": "The name of the series as shown in the legend, tooltip etc.",
-              "value": {
-                "kind": "expression"
-              }
-            },
-            {
-              "name": ".markers",
-              "description": "Shows/hides data-point markers for line-like series.\nAcceptable input are:\n - `shown`: markers are always visible\n - `hidden`: markers are always hidden\n - `auto`: markers are visible for widespread data and hidden, when data is dense *(default)*",
-              "value": {
-                "kind": "expression"
-              }
-            },
-            {
-              "name": ".unit",
-              "description": "Used to connect the series to an axis; if multiple series have the same `unit`, they will share axis.\nDisplayed as a title for the axis.\nIf no unit is defined, then series will be connected to the first axis.",
-              "value": {
-                "kind": "expression"
-              }
-            },
-            {
-              "name": ".stack",
-              "description": "Used to group series in a different stacks.\n\"stacking\" property should be specified either for each series or in plotOptions.\nIt is recommended to place series in a single stack, when they belong to the same yAxis.",
-              "value": {
-                "kind": "expression"
-              }
-            },
-            {
-              "name": ".neckPosition",
-              "description": "The height of the neck, the lower part of the funnel.\nA number defines pixel width, a percentage string defines a percentage of the plot area height. Defaults to 30%.\nNote that this property only applies for \"funnel\" charts.",
-              "value": {
-                "kind": "expression"
-              }
-            },
-            {
-              "name": ".neckWidth",
-              "description": "The width of the neck, the lower part of the funnel.\nA number defines pixel width, a percentage string defines a percentage of the plot area width. Defaults to 30%.\nNote that this property only applies for \"funnel\" charts.",
-              "value": {
-                "kind": "expression"
-              }
-            },
-            {
-              "name": ".additionalOptions",
-              "description": "Represents additional JSON configuration.",
-              "value": {
-                "kind": "expression"
-              }
-            }
-          ]
         }
       ]
     }