@record-evolution/widget-gauge 1.7.29 → 1.7.30

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 (4) hide show
  1. package/dist/widget-gauge.js +2 -2
  2. package/package.json +5 -1
  3. package/src/definition-schema.d.ts +44 -11
  4. package/src/definition-schema.json +22 -13
package/dist/widget-gauge.js CHANGED
@@ -553,7 +553,7 @@ var Jt = Object.defineProperty, Qt = Object.getOwnPropertyDescriptor, v = (s, t,
553
553
  q.use([yt, vt, bt]);
554
554
  let _ = class extends H {
555
555
  constructor() {
556
- super(), this.dataSets = [], this.canvasList = /* @__PURE__ */ new Map(), this.origWidth = 600, this.origHeight = 350, this.textContainerHeight = 36, this.modifier = 1, this.version = "1.7.29", this.resizeObserver = new ResizeObserver(() => {
556
+ super(), this.dataSets = [], this.canvasList = /* @__PURE__ */ new Map(), this.origWidth = 600, this.origHeight = 350, this.textContainerHeight = 36, this.modifier = 1, this.version = "1.7.30", this.resizeObserver = new ResizeObserver(() => {
557
557
  this.adjustSizes(), this.applyData();
558
558
  }), this.template = {
559
559
  series: [
@@ -905,7 +905,7 @@ v([
905
905
  $t(".wrapper")
906
906
  ], _.prototype, "wrapper", 2);
907
907
  _ = v([
908
- Gt("widget-gauge-1.7.29")
908
+ Gt("widget-gauge-1.7.30")
909
909
  ], _);
910
910
  export {
911
911
  _ as WidgetGauge
package/package.json CHANGED
@@ -3,7 +3,11 @@
3
3
  "description": "REWidget widget-gauge",
4
4
  "license": "MIT",
5
5
  "author": "widget-gauge",
6
- "version": "1.7.29",
6
+ "version": "1.7.30",
7
+ "engines": {
8
+ "node": ">=24.9.0",
9
+ "npm": ">=10.0.2"
10
+ },
7
11
  "type": "module",
8
12
  "main": "dist/widget-gauge.js",
9
13
  "types": "dist/src/widget-gauge.d.ts",
package/src/definition-schema.d.ts CHANGED
@@ -5,36 +5,48 @@
5
5
  * and run json-schema-to-typescript to regenerate this file.
6
6
  */
7
7
 
8
+ /**
9
+ * The main heading displayed above the gauge(s). Use to describe what metric is being shown (e.g., 'CPU Temperature', 'Tank Level').
10
+ */
8
11
  export type Title = string;
12
+ /**
13
+ * Secondary text displayed below the title. Use for additional context like location, device name, or measurement conditions.
14
+ */
9
15
  export type Subtitle = string;
16
+ /**
17
+ * The name displayed below or inside the gauge to identify what value it shows. Appears in legends when multiple gauges are present.
18
+ */
10
19
  export type Label = string;
11
20
  /**
12
- * The unit of the values. e.g. °C or km/h
21
+ * The measurement unit displayed after the value (e.g., '°C', 'km/h', '%', 'PSI'). Keep short for better display.
13
22
  */
14
23
  export type Unit = string;
15
24
  /**
16
- * The number of decimal places to show in the value. If not specified, precision is 0.
25
+ * Number of decimal places to display (e.g., 0 for whole numbers, 1 for 23.5, 2 for 23.45). Default is 0.
17
26
  */
18
27
  export type Decimals = number;
19
28
  /**
20
- * Draw multiple Charts based on the split column of a data table.
29
+ * When enabled, automatically creates multiple gauges based on distinct values in a pivot column. Use when you have one data table containing values for multiple entities (e.g., temperatures for multiple devices).
21
30
  */
22
31
  export type MultiChart = boolean;
23
32
  /**
24
- * The value of the gauge
33
+ * The numeric value to display on the gauge. Can be bound to a data column for real-time updates. Used when Multi Chart is disabled.
25
34
  */
26
35
  export type Value = number;
27
36
  /**
28
- * This should be an ISO String date like 2023-11-04T22:47:52.351152+00:00. Will only be used to detect data age of data.
37
+ * ISO 8601 timestamp string (e.g., '2023-11-04T22:47:52.351152+00:00'). Used to detect data age and apply maxLatency filtering if configured.
29
38
  */
30
39
  export type Timestamp = string;
40
+ /**
41
+ * The numeric measurement value for this data point.
42
+ */
31
43
  export type Value1 = number;
32
44
  /**
33
- * You can specify a table column 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 gauge for each city.
45
+ * Column value used to split data into multiple gauges. Each unique value creates a separate gauge (e.g., device_id creates one gauge per device).
34
46
  */
35
47
  export type SplitDataBy = string;
36
48
  /**
37
- * Provide a list of values. Only the latest value is shown in the gauge unless you configure "Advanced Settings" below or use split data.
49
+ * Data array for Multi Chart mode. Only the latest value per pivot group is displayed unless averaging is configured. Provide timestamp for data freshness indication.
38
50
  */
39
51
  export type Data = {
40
52
  tsp?: Timestamp;
@@ -43,12 +55,15 @@ export type Data = {
43
55
  [k: string]: unknown;
44
56
  }[];
45
57
  /**
46
- * The start value of the gauge. If not specified 0 is used.
58
+ * The minimum value shown on the gauge scale (left-most point). Default is 0. Set to negative for metrics that can go below zero.
47
59
  */
48
60
  export type GaugeStartValue = number;
61
+ /**
62
+ * The upper boundary value for this color section. The last section's limit defines the gauge maximum.
63
+ */
49
64
  export type RightLimit = number;
50
65
  /**
51
- * The right limits of the gauge sections and the color for that section.
66
+ * Define color zones by specifying the upper boundary and color for each section. Sections are drawn from the gauge minimum to the first limit, then between consecutive limits.
52
67
  */
53
68
  export type SectionRightLimits = {
54
69
  limit?: RightLimit;
@@ -56,13 +71,16 @@ export type SectionRightLimits = {
56
71
  [k: string]: unknown;
57
72
  }[];
58
73
  /**
59
- * Calculate the average over the given number of newest values. (If you use 'split by', then per each of the split dataseries.) If not specified then the latest value is shown without modification.
74
+ * Calculate a rolling average over the specified number of most recent data points. Useful for smoothing noisy sensor data. Leave empty to show raw latest value.
60
75
  */
61
76
  export type AverageLatestValues = number;
62
77
  /**
63
- * If you provide timestamp data, the delivered value is only shown in the gauge when the age of the data is not older than the given maximum Latency in seconds.
78
+ * Maximum age (in seconds) for data to be displayed. If the latest data point's timestamp is older than this threshold, the gauge shows no value or a stale indicator. Useful for detecting sensor offline conditions.
64
79
  */
65
80
  export type MaximumLatencyInSeconds = number;
81
+ /**
82
+ * Array of gauge configurations. Each entry creates a separate gauge dial that can display different metrics or the same metric for different entities (via pivot).
83
+ */
66
84
  export type Gauges = {
67
85
  label?: Label;
68
86
  valueColor?: ValueColor;
@@ -76,23 +94,38 @@ export type Gauges = {
76
94
  [k: string]: unknown;
77
95
  }[];
78
96
 
97
+ /**
98
+ * A circular gauge widget for displaying single numeric values within a defined range. Use this widget to show KPIs, sensor readings, progress indicators, or any metric that benefits from a visual representation against minimum and maximum boundaries. Supports color-coded sections to indicate value zones (e.g., normal/warning/critical), multiple gauges in one widget, and automatic pivot-based generation from data columns. Ideal for real-time monitoring dashboards showing temperature, speed, utilization, or similar bounded metrics.
99
+ */
79
100
  export interface GaugeChartConfiguration {
80
101
  title?: Title;
81
102
  subTitle?: Subtitle;
82
103
  dataseries?: Gauges;
83
104
  [k: string]: unknown;
84
105
  }
106
+ /**
107
+ * The color of the numeric value text displayed on the gauge. Use a contrasting color for readability.
108
+ */
85
109
  export interface ValueColor {
86
110
  [k: string]: unknown;
87
111
  }
112
+ /**
113
+ * Configure the gauge scale range and color zones to indicate value severity or status levels.
114
+ */
88
115
  export interface GaugeColorSections {
89
116
  gaugeMinValue?: GaugeStartValue;
90
117
  sectionLimits?: SectionRightLimits;
91
118
  [k: string]: unknown;
92
119
  }
120
+ /**
121
+ * The fill color for this section of the gauge arc. Use semantic colors like green for normal, yellow for warning, red for critical.
122
+ */
93
123
  export interface SectionColor {
94
124
  [k: string]: unknown;
95
125
  }
126
+ /**
127
+ * Additional settings for data processing and display behavior.
128
+ */
96
129
  export interface AdvancedConfiguration {
97
130
  averageLatest?: AverageLatestValues;
98
131
  maxLatency?: MaximumLatencyInSeconds;
package/src/definition-schema.json CHANGED
@@ -1,19 +1,23 @@
1
1
  {
2
2
  "title": "Gauge-chart Configuration",
3
+ "description": "A circular gauge widget for displaying single numeric values within a defined range. Use this widget to show KPIs, sensor readings, progress indicators, or any metric that benefits from a visual representation against minimum and maximum boundaries. Supports color-coded sections to indicate value zones (e.g., normal/warning/critical), multiple gauges in one widget, and automatic pivot-based generation from data columns. Ideal for real-time monitoring dashboards showing temperature, speed, utilization, or similar bounded metrics.",
3
4
  "type": "object",
4
5
  "properties": {
5
6
  "title": {
6
7
  "title": "Title",
8
+ "description": "The main heading displayed above the gauge(s). Use to describe what metric is being shown (e.g., 'CPU Temperature', 'Tank Level').",
7
9
  "type": "string",
8
10
  "order": 1
9
11
  },
10
12
  "subTitle": {
11
13
  "title": "Subtitle",
14
+ "description": "Secondary text displayed below the title. Use for additional context like location, device name, or measurement conditions.",
12
15
  "type": "string",
13
16
  "order": 2
14
17
  },
15
18
  "dataseries": {
16
19
  "title": "Gauges",
20
+ "description": "Array of gauge configurations. Each entry creates a separate gauge dial that can display different metrics or the same metric for different entities (via pivot).",
17
21
  "type": "array",
18
22
  "dataDrivenDisabled": true,
19
23
  "order": 2,
@@ -22,39 +26,41 @@
22
26
  "properties": {
23
27
  "label": {
24
28
  "title": "Label",
29
+ "description": "The name displayed below or inside the gauge to identify what value it shows. Appears in legends when multiple gauges are present.",
25
30
  "type": "string",
26
31
  "required": true,
27
32
  "order": 1
28
33
  },
29
34
  "valueColor": {
30
35
  "title": "Value Color",
36
+ "description": "The color of the numeric value text displayed on the gauge. Use a contrasting color for readability.",
31
37
  "type": "color",
32
38
  "order": 2
33
39
  },
34
40
  "unit": {
35
41
  "title": "Unit",
36
- "description": "The unit of the values. e.g. °C or km/h",
42
+ "description": "The measurement unit displayed after the value (e.g., '°C', 'km/h', '%', 'PSI'). Keep short for better display.",
37
43
  "type": "string",
38
44
  "dataDrivenDisabled": false,
39
45
  "order": 3
40
46
  },
41
47
  "precision": {
42
48
  "title": "Decimals",
43
- "description": "The number of decimal places to show in the value. If not specified, precision is 0.",
49
+ "description": "Number of decimal places to display (e.g., 0 for whole numbers, 1 for 23.5, 2 for 23.45). Default is 0.",
44
50
  "type": "number",
45
51
  "dataDrivenDisabled": true,
46
52
  "order": 4
47
53
  },
48
54
  "multiChart": {
49
55
  "title": "Multi Chart",
50
- "description": "Draw multiple Charts based on the split column of a data table.",
56
+ "description": "When enabled, automatically creates multiple gauges based on distinct values in a pivot column. Use when you have one data table containing values for multiple entities (e.g., temperatures for multiple devices).",
51
57
  "type": "boolean",
52
58
  "dataDrivenDisabled": true,
53
59
  "order": 6
54
60
  },
55
61
  "value": {
56
62
  "title": "Value",
57
- "description": "The value of the gauge",
63
+ "description": "The numeric value to display on the gauge. Can be bound to a data column for real-time updates. Used when Multi Chart is disabled.",
58
64
  "type": "number",
59
65
  "condition": {
60
66
  "relativePath": "../multiChart",
@@ -64,7 +70,7 @@
64
70
  },
65
71
  "data": {
66
72
  "title": "Data",
67
- "description": "Provide a list of values. Only the latest value is shown in the gauge unless you configure \"Advanced Settings\" below or use split data.",
73
+ "description": "Data array for Multi Chart mode. Only the latest value per pivot group is displayed unless averaging is configured. Provide timestamp for data freshness indication.",
68
74
  "type": "array",
69
75
  "condition": {
70
76
  "relativePath": "../multiChart",
@@ -76,19 +82,20 @@
76
82
  "properties": {
77
83
  "tsp": {
78
84
  "title": "Timestamp",
79
- "description": "This should be an ISO String date like 2023-11-04T22:47:52.351152+00:00. Will only be used to detect data age of data.",
85
+ "description": "ISO 8601 timestamp string (e.g., '2023-11-04T22:47:52.351152+00:00'). Used to detect data age and apply maxLatency filtering if configured.",
80
86
  "type": "string",
81
87
  "order": 1
82
88
  },
83
89
  "value": {
84
90
  "title": "Value",
91
+ "description": "The numeric measurement value for this data point.",
85
92
  "type": "number",
86
93
  "order": 2,
87
94
  "required": true
88
95
  },
89
96
  "pivot": {
90
97
  "title": "Split Data by",
91
- "description": "You can specify a table column 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 gauge for each city.",
98
+ "description": "Column value used to split data into multiple gauges. Each unique value creates a separate gauge (e.g., device_id creates one gauge per device).",
92
99
  "order": 3,
93
100
  "type": "string"
94
101
  }
@@ -97,20 +104,20 @@
97
104
  },
98
105
  "sections": {
99
106
  "title": "Gauge Color Sections",
100
- "description": "",
107
+ "description": "Configure the gauge scale range and color zones to indicate value severity or status levels.",
101
108
  "type": "object",
102
109
  "order": 8,
103
110
  "properties": {
104
111
  "gaugeMinValue": {
105
112
  "title": "Gauge Start Value",
106
- "description": "The start value of the gauge. If not specified 0 is used.",
113
+ "description": "The minimum value shown on the gauge scale (left-most point). Default is 0. Set to negative for metrics that can go below zero.",
107
114
  "type": "number",
108
115
  "dataDrivenDisabled": true,
109
116
  "order": 1
110
117
  },
111
118
  "sectionLimits": {
112
119
  "title": "Section Right Limits",
113
- "description": "The right limits of the gauge sections and the color for that section.",
120
+ "description": "Define color zones by specifying the upper boundary and color for each section. Sections are drawn from the gauge minimum to the first limit, then between consecutive limits.",
114
121
  "type": "array",
115
122
  "dataDrivenDisabled": true,
116
123
  "order": 2,
@@ -119,12 +126,14 @@
119
126
  "properties": {
120
127
  "limit": {
121
128
  "title": "Right Limit",
129
+ "description": "The upper boundary value for this color section. The last section's limit defines the gauge maximum.",
122
130
  "type": "number",
123
131
  "dataDrivenDisabled": true,
124
132
  "order": 1
125
133
  },
126
134
  "sectionColor": {
127
135
  "title": "Section Color",
136
+ "description": "The fill color for this section of the gauge arc. Use semantic colors like green for normal, yellow for warning, red for critical.",
128
137
  "type": "color",
129
138
  "dataDrivenDisabled": true,
130
139
  "order": 2
@@ -136,20 +145,20 @@
136
145
  },
137
146
  "advanced": {
138
147
  "title": "Advanced Configuration",
139
- "description": "",
148
+ "description": "Additional settings for data processing and display behavior.",
140
149
  "type": "object",
141
150
  "order": 9,
142
151
  "properties": {
143
152
  "averageLatest": {
144
153
  "title": "Average Latest Values",
145
- "description": "Calculate the average over the given number of newest values. (If you use 'split by', then per each of the split dataseries.) If not specified then the latest value is shown without modification.",
154
+ "description": "Calculate a rolling average over the specified number of most recent data points. Useful for smoothing noisy sensor data. Leave empty to show raw latest value.",
146
155
  "type": "number",
147
156
  "dataDrivenDisabled": true,
148
157
  "order": 6
149
158
  },
150
159
  "maxLatency": {
151
160
  "title": "Maximum Latency in seconds",
152
- "description": "If you provide timestamp data, the delivered value is only shown in the gauge when the age of the data is not older than the given maximum Latency in seconds.",
161
+ "description": "Maximum age (in seconds) for data to be displayed. If the latest data point's timestamp is older than this threshold, the gauge shows no value or a stale indicator. Useful for detecting sensor offline conditions.",
153
162
  "type": "number",
154
163
  "dataDrivenDisabled": true,
155
164
  "order": 7