@record-evolution/widget-linechart 1.6.29 → 1.6.31

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/dist/widget-linechart.js +163 -160
  2. package/dist/widget-linechart.js.map +1 -1
  3. package/package.json +1 -1
  4. package/src/definition-schema.d.ts +65 -23
  5. package/src/definition-schema.json +68 -39
  6. package/src/widget-linechart.ts +18 -5
package/src/definition-schema.json CHANGED
@@ -1,25 +1,51 @@
1
1
  {
2
2
  "title": "inputData",
3
+ "description": "A versatile chart widget for visualizing data as line charts, bar charts, or scatter plots. Use this widget for time-series data, trend analysis, comparisons, and general data visualization. Supports multiple data series with different chart types in the same view, automatic pivot-based series generation, zoom controls, and flexible styling options. The ECharts-based rendering provides smooth animations and interactive tooltips. Ideal for monitoring dashboards, historical data analysis, and any scenario requiring visual data representation over continuous or categorical dimensions.",
3
4
  "type": "object",
4
5
  "properties": {
5
- "title": { "title": "Title", "type": "string", "order": 1 },
6
- "subTitle": { "title": "Subtitle", "type": "string", "order": 2 },
6
+ "title": {
7
+ "title": "Title",
8
+ "description": "The main heading displayed above the chart. Use to describe what data is being visualized (e.g., 'Temperature Over Time', 'Sales by Region').",
9
+ "type": "string",
10
+ "order": 1
11
+ },
12
+ "subTitle": {
13
+ "title": "Subtitle",
14
+ "description": "Secondary text displayed below the title. Use for additional context like data source, time period, or measurement units.",
15
+ "type": "string",
16
+ "order": 2
17
+ },
7
18
  "axis": {
8
19
  "title": "Configuration",
20
+ "description": "Chart display settings including axes, legend, and layout options.",
9
21
  "type": "object",
10
22
  "order": 3,
11
23
  "properties": {
24
+ "xAxisLabel": {
25
+ "title": "X-Axis Label",
26
+ "description": "Label text displayed below the horizontal axis. Describes the x-dimension (e.g., 'Time', 'Date', 'Category').",
27
+ "type": "string",
28
+ "dataDrivenDisabled": false,
29
+ "order": 0
30
+ },
31
+ "yAxisLabel": {
32
+ "title": "Y-Axis Label",
33
+ "description": "Label text displayed beside the vertical axis. Describes the measured values (e.g., 'Temperature (°C)', 'Count', 'Revenue ($)').",
34
+ "type": "string",
35
+ "dataDrivenDisabled": false,
36
+ "order": 1
37
+ },
12
38
  "showLegend": {
13
39
  "title": "Show Legend",
14
- "description": "Display the chart legend.",
40
+ "description": "When enabled, displays a legend identifying each data series by color and label. Essential for multi-series charts.",
15
41
  "type": "boolean",
16
42
  "default": true,
17
43
  "dataDrivenDisabled": true,
18
- "order": 1
44
+ "order": 1.1
19
45
  },
20
46
  "showTitle": {
21
47
  "title": "Show Title",
22
- "description": "Display the chart title.",
48
+ "description": "When enabled, displays the chart title and subtitle. Disable for compact layouts or when the widget container provides its own title.",
23
49
  "type": "boolean",
24
50
  "default": true,
25
51
  "dataDrivenDisabled": true,
@@ -27,7 +53,7 @@
27
53
  },
28
54
  "showBox": {
29
55
  "title": "Show Box Frame",
30
- "description": "Display a border frame around the chart area.",
56
+ "description": "When enabled, draws a border frame around the chart plotting area. Useful for visual separation in dense dashboards.",
31
57
  "type": "boolean",
32
58
  "default": false,
33
59
  "dataDrivenDisabled": true,
@@ -35,28 +61,22 @@
35
61
  },
36
62
  "timeseries": {
37
63
  "title": "Timeseries Chart",
38
- "description": "This will apply a proper time series x-Axis. Check if your x-values are timestamps.",
64
+ "description": "When enabled, treats x-axis values as timestamps and applies proper time-based scaling and formatting. Enable when your x-values are dates/times (ISO strings or timestamps). Disable for categorical x-axes.",
39
65
  "type": "boolean",
40
66
  "dataDrivenDisabled": true,
41
67
  "order": 4
42
68
  },
43
69
  "columnLayout": {
44
70
  "title": "Vertical Layout",
45
- "description": "When multiple charts are drawn, then they will be layed out horizontically or vertically.",
71
+ "description": "When multiple charts are drawn (via chartName grouping), this controls their arrangement. Enabled = stacked vertically, Disabled = arranged horizontally side by side.",
46
72
  "type": "boolean",
47
73
  "dataDrivenDisabled": true,
48
74
  "order": 5
49
75
  },
50
76
 
51
- "xAxisLabel": {
52
- "title": "X-Axis Label",
53
- "type": "string",
54
- "dataDrivenDisabled": false,
55
- "order": 6
56
- },
57
77
  "showXAxis": {
58
78
  "title": "Show X-Axis",
59
- "description": "Display the x-axis with labels. When hidden, bottom padding is removed.",
79
+ "description": "When enabled, displays the x-axis line, ticks, and labels. Disable to remove bottom axis and its padding for minimal designs.",
60
80
  "type": "boolean",
61
81
  "default": true,
62
82
  "dataDrivenDisabled": true,
@@ -65,20 +85,14 @@
65
85
  "xAxisZoom": {
66
86
  "title": "X-Axis Zoom Tool",
67
87
  "type": "boolean",
68
- "description": "If checked, a zoom tool will be shown on the x-axis to zoom into the chart.",
88
+ "description": "When enabled, shows a slider control below the chart for zooming into specific x-axis ranges. Useful for long time series where users need to focus on specific periods.",
69
89
  "dataDrivenDisabled": true,
70
90
  "order": 8
71
91
  },
72
92
 
73
- "yAxisLabel": {
74
- "title": "Y-Axis Label",
75
- "type": "string",
76
- "dataDrivenDisabled": false,
77
- "order": 9
78
- },
79
93
  "showYAxis": {
80
94
  "title": "Show Y-Axis",
81
- "description": "Display the y-axis with labels. When hidden, left padding is removed.",
95
+ "description": "When enabled, displays the y-axis line, ticks, and labels. Disable to remove left axis and its padding for minimal designs.",
82
96
  "type": "boolean",
83
97
  "default": true,
84
98
  "dataDrivenDisabled": true,
@@ -86,7 +100,7 @@
86
100
  },
87
101
  "yAxisScaling": {
88
102
  "title": "Y-Axis Scaling",
89
- "description": "If checked, the Y-Axis will be scaled to the data range. If not checked, the Y-Axis will always start at 0.",
103
+ "description": "When enabled, the y-axis range automatically adjusts to fit the data (min to max). When disabled, the y-axis always starts at 0, which is better for comparing absolute values.",
90
104
  "type": "boolean",
91
105
  "dataDrivenDisabled": true,
92
106
  "order": 11
@@ -95,6 +109,7 @@
95
109
  },
96
110
  "dataseries": {
97
111
  "title": "Dataseries",
112
+ "description": "Array of data series to plot. Each series can have its own chart type (line/bar/scatter), colors, and styling. Multiple series can share an axis or be grouped into separate charts.",
98
113
  "type": "array",
99
114
  "dataDrivenDisabled": true,
100
115
  "order": 4,
@@ -103,13 +118,14 @@
103
118
  "properties": {
104
119
  "label": {
105
120
  "title": "Label",
106
- "description": "The name for this data series",
121
+ "description": "Display name for this data series shown in legends and tooltips. Should clearly identify what data this series represents.",
107
122
  "type": "string",
108
123
  "required": true,
109
124
  "order": 1
110
125
  },
111
126
  "type": {
112
127
  "title": "Drawing Style",
128
+ "description": "The visual representation type: 'line' for continuous line charts (best for trends), 'bar' for vertical bar charts (best for comparisons), 'scatter' for individual data points (best for correlation analysis).",
113
129
  "type": "string",
114
130
  "enum": ["bar", "line", "scatter"],
115
131
  "required": true,
@@ -118,21 +134,27 @@
118
134
  },
119
135
  "backgroundColor": {
120
136
  "title": "Fill Color",
121
- "description": "The inner color of the bars if you chose Drawing Type 'bar' or the inner colors of the points if you chose Drawing Type 'line'.",
137
+ "description": "For bar charts: the bar fill color. For line charts: the data point marker fill color. For scatter: the point fill color. Leave empty to use theme default.",
122
138
  "type": "color",
123
139
  "color": true,
124
140
  "order": 3
125
141
  },
126
- "borderColor": { "title": "Line Color", "type": "color", "color": true, "order": 4 },
142
+ "borderColor": {
143
+ "title": "Line Color",
144
+ "description": "For line charts: the line stroke color. For bar charts: the bar border color. This is the primary color identifying the series.",
145
+ "type": "color",
146
+ "color": true,
147
+ "order": 4
148
+ },
127
149
  "styling": {
128
150
  "title": "Styling",
129
- "description": "",
151
+ "description": "Additional visual styling options for the series.",
130
152
  "type": "object",
131
153
  "order": 6,
132
154
  "properties": {
133
155
  "fill": {
134
156
  "title": "Line Area Fill",
135
- "description": "Check this box to turn a line chart into an area chart.",
157
+ "description": "When enabled for line charts, fills the area between the line and the x-axis, creating an area chart. Useful for visualizing volume or cumulative values.",
136
158
  "type": "boolean",
137
159
  "condition": { "relativePath": "../../type", "showIfValueIn": ["line"] },
138
160
  "dataDrivenDisabled": true,
@@ -140,14 +162,14 @@
140
162
  },
141
163
  "borderWidth": {
142
164
  "title": "Line Width",
143
- "description": "Width of the lines in the chart.",
165
+ "description": "Thickness of lines in pixels. Larger values make lines more prominent. Typical values: 1-2 for dense charts, 2-4 for emphasis.",
144
166
  "type": "number",
145
167
  "dataDrivenDisabled": true,
146
168
  "order": 2
147
169
  },
148
170
  "borderDash": {
149
171
  "title": "Line Dash Style",
150
- "description": "",
172
+ "description": "Line pattern for line charts: 'solid' for continuous lines, 'dashed' for long dashes, 'dotted' for dots. Use different patterns to distinguish overlapping series.",
151
173
  "type": "string",
152
174
  "condition": { "relativePath": "../../type", "showIfValueIn": ["line"] },
153
175
  "enum": ["solid", "dashed", "dotted"],
@@ -156,6 +178,7 @@
156
178
  },
157
179
  "pointStyle": {
158
180
  "title": "Symbol Style",
181
+ "description": "Shape of data point markers: 'circle', 'rect' (square), 'roundRect', 'triangle', 'diamond', 'pin', 'arrow', or 'none' to hide markers. Different shapes help distinguish series.",
159
182
  "condition": {
160
183
  "relativePath": "../../type",
161
184
  "showIfValueIn": ["line", "scatter"]
@@ -177,20 +200,20 @@
177
200
  },
178
201
  "advanced": {
179
202
  "title": "Advanced Settings",
180
- "description": "",
203
+ "description": "Advanced configuration for multi-chart layouts and draw ordering.",
181
204
  "type": "object",
182
205
  "order": 7,
183
206
  "properties": {
184
207
  "drawOrder": {
185
208
  "title": "Draw Order",
186
- "description": "Determines the draw order of the series. Dataseries with lower numbers are drawn on top of ones with higher numbers within one chart.",
209
+ "description": "Z-index controlling which series appears on top when overlapping. Lower numbers are drawn on top. Use to ensure important series aren't hidden behind others.",
187
210
  "type": "number",
188
211
  "dataDrivenDisabled": true,
189
212
  "order": 2
190
213
  },
191
214
  "chartName": {
192
215
  "title": "Chart Name",
193
- "description": "If two dataseries have the same 'Chart Name', they will be drawn in the same chart. Otherwise they will get their own chart. If the name contains #split# as substring then a separat chart will be drawn for each split dataseries.",
216
+ "description": "Groups series into separate charts. Series with the same chartName share one chart; different names create separate charts. Use '#split#' in the name to auto-create one chart per pivot value.",
194
217
  "type": "string",
195
218
  "dataDrivenDisabled": true,
196
219
  "order": 3
@@ -199,7 +222,7 @@
199
222
  },
200
223
  "data": {
201
224
  "title": "Data",
202
- "description": "The data used to draw this data series.",
225
+ "description": "Array of data points to plot. Each point has x (position on horizontal axis), y (value), and optionally r (point size) and pivot (for auto-generating series).",
203
226
  "type": "array",
204
227
  "order": 5,
205
228
  "items": {
@@ -207,15 +230,21 @@
207
230
  "properties": {
208
231
  "x": {
209
232
  "title": "X-Value",
210
- "description": "If timeseries is checked in the settings, then this should be an ISO String date like 2023-11-04T22:47:52.351152+00:00. But this works with many other formats as well.",
233
+ "description": "The horizontal axis value. For timeseries charts, use ISO 8601 timestamp strings (e.g., '2023-11-04T22:47:52.351152+00:00') or Unix timestamps. For categorical charts, use category labels.",
211
234
  "type": "string",
212
235
  "order": 1,
213
236
  "required": true
214
237
  },
215
- "y": { "title": "Y-Value", "type": "string", "order": 2, "required": true },
238
+ "y": {
239
+ "title": "Y-Value",
240
+ "description": "The vertical axis value representing the measurement or count at this x position.",
241
+ "type": "string",
242
+ "order": 2,
243
+ "required": true
244
+ },
216
245
  "r": {
217
246
  "title": "Point Size",
218
- "description": "Controls the symbol size for line and scatter charts.",
247
+ "description": "Radius/size of the data point marker for line and scatter charts. Use varying sizes to encode a third data dimension (bubble chart effect).",
219
248
  "condition": {
220
249
  "relativePath": "../../../type",
221
250
  "showIfValueIn": ["line", "scatter"]
@@ -225,7 +254,7 @@
225
254
  },
226
255
  "pivot": {
227
256
  "title": "Split Data by",
228
- "description": "You can specify a column in the input data to autogenerate dataseries for each distinct entry in this column. E.g. if you have a table with columns [city, timestamp, temperature] and specify 'city' as split column, then you will get a line for each city.",
257
+ "description": "Column value used to split this data into multiple series automatically. Each unique pivot value creates a separate line/bar series (e.g., pivot by 'city' to get one line per city).",
229
258
  "order": 4,
230
259
  "type": "string"
231
260
  }
package/src/widget-linechart.ts CHANGED
@@ -48,6 +48,9 @@ export class WidgetLinechart extends LitElement {
48
48
  @property({ type: Object })
49
49
  theme?: Theme
50
50
 
51
+ @property({ type: Object })
52
+ timeRange?: { start: number; end: number }
53
+
51
54
  @state()
52
55
  private canvasList: Map<
53
56
  string,
@@ -463,16 +466,25 @@ export class WidgetLinechart extends LitElement {
463
466
  option.xAxis.type = this.xAxisType()
464
467
  option.xAxis.show = showXAxis
465
468
  if (this.xAxisType() === 'time') {
466
- const axisMax = chart.series.map((s) => s.maxDate ?? 0).reduce((a, b) => Math.max(a, b), 0)
467
- const axisMin = chart.series
469
+ // Use provided timeRange if available and valid, otherwise calculate from data
470
+ const dataMin = chart.series
468
471
  .map((s) => s.minDate ?? Infinity)
469
472
  .reduce((a, b) => Math.min(a, b), Infinity)
473
+ const dataMax = chart.series.map((s) => s.maxDate ?? 0).reduce((a, b) => Math.max(a, b), 0)
474
+
475
+ const timeRangeStart = Number(this.timeRange?.start)
476
+ const timeRangeEnd = Number(this.timeRange?.end)
477
+
478
+ const axisMin = !isNaN(timeRangeStart) ? timeRangeStart : dataMin
479
+ const axisMax = !isNaN(timeRangeEnd) ? timeRangeEnd : dataMax
480
+
470
481
  option.xAxis = {
471
482
  ...option.xAxis,
472
- min: axisMin ?? new Date().getTime() - 1 * 24 * 60 * 60 * 1000,
473
- max: axisMax ?? new Date().getTime()
483
+ min: axisMin !== Infinity ? axisMin : new Date().getTime() - 1 * 24 * 60 * 60 * 1000,
484
+ max: axisMax !== 0 ? axisMax : new Date().getTime()
474
485
  }
475
486
  }
487
+
476
488
  option.dataZoom[0].show = this.inputData?.axis?.xAxisZoom ?? false
477
489
  option.toolbox.show = this.inputData?.axis?.xAxisZoom ?? false
478
490
 
@@ -484,6 +496,7 @@ export class WidgetLinechart extends LitElement {
484
496
  option.yAxis.show = showYAxis
485
497
  option.yAxis.nameLocation = 'end'
486
498
  option.yAxis.nameGap = 10
499
+ option.yAxis.nameTextStyle = { align: 'left' }
487
500
  option.yAxis.axisLine = { show: true }
488
501
  if (['value', 'log'].includes(option.yAxis.type))
489
502
  option.yAxis.axisLabel = {
@@ -511,7 +524,7 @@ export class WidgetLinechart extends LitElement {
511
524
  }
512
525
 
513
526
  // Calculate animation duration based on update frequency
514
- const animationDuration = this.calculateAnimationDuration(chart, label)
527
+ const animationDuration = this.updateThresholdMs //this.calculateAnimationDuration(chart, label)
515
528
  option.animation = true
516
529
  option.animationEasing = 'linear'
517
530
  option.animationDuration = animationDuration