@record-evolution/widget-mapbox 1.5.13 → 1.5.15

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 (8) hide show
  1. package/dist/tsconfig.tsbuildinfo +1 -1
  2. package/dist/widget-mapbox.js +3 -3
  3. package/dist/widget-mapbox.js.map +1 -1
  4. package/package.json +7 -2
  5. package/src/definition-schema.d.ts +73 -16
  6. package/src/definition-schema.json +35 -16
  7. package/src/widget-mapbox.ts +1 -1
  8. package/thumbnail.webp +0 -0
package/package.json CHANGED
@@ -3,14 +3,19 @@
3
3
  "description": "REWidget widget-mapbox",
4
4
  "license": "MIT",
5
5
  "author": "widget-mapbox",
6
- "version": "1.5.13",
6
+ "version": "1.5.15",
7
+ "engines": {
8
+ "node": ">=24.9.0",
9
+ "npm": ">=10.0.2"
10
+ },
7
11
  "type": "module",
8
12
  "main": "dist/widget-mapbox.js",
9
13
  "types": "dist/src/widget-mapbox.d.ts",
10
14
  "files": [
11
15
  "dist",
12
16
  "src",
13
- "thumbnail.png"
17
+ "thumbnail.png",
18
+ "thumbnail.webp"
14
19
  ],
15
20
  "scripts": {
16
21
  "analyze": "cem analyze --litelement",
package/src/definition-schema.d.ts CHANGED
@@ -5,10 +5,16 @@
5
5
  * and run json-schema-to-typescript to regenerate this file.
6
6
  */
7
7
 
8
+ /**
9
+ * The main heading displayed above the map. Use to describe what geographic data is being shown (e.g., 'Fleet Locations', 'Sensor Network').
10
+ */
8
11
  export type Title = string;
12
+ /**
13
+ * Secondary text displayed below the title. Use for additional context like region, time period, or data source.
14
+ */
9
15
  export type Subtitle = string;
10
16
  /**
11
- * The basic style of the map.
17
+ * The visual appearance of the base map: 'streets' for road-focused, 'outdoors' for terrain, 'light/dark' for minimal designs, 'satellite' for aerial imagery, 'navigation' for routing focus.
12
18
  */
13
19
  export type MapStyle =
14
20
  | "streets-v12"
@@ -19,69 +25,96 @@ export type MapStyle =
19
25
  | "satellite-streets-v12"
20
26
  | "navigation-day-v1"
21
27
  | "navigation-night-v1";
28
+ /**
29
+ * When enabled, displays a legend identifying each data layer by color and label. Useful for multi-layer maps.
30
+ */
22
31
  export type ShowLegend = boolean;
23
32
  /**
24
- * If true, the map automatically keeps the drawn locations in focus.
33
+ * When enabled, the map automatically pans and zooms to keep all data points in view as they update. Disable for fixed-view maps where users control the viewport.
25
34
  */
26
35
  export type AutoFollow = boolean;
27
36
  /**
28
- * The name for this data series
37
+ * Display name for this map layer shown in legends and tooltips. Should identify what entities or data this layer represents.
29
38
  */
30
39
  export type SeriesLabel = string;
31
40
  /**
32
- * Create the specified type of layer on the map.
41
+ * Visualization style: 'circle' for point markers, 'symbol' for icon markers with labels, 'heatmap' for density visualization, 'line' for connected paths/routes.
33
42
  */
34
43
  export type LayerType = "circle" | "symbol" | "heatmap" | "line";
35
44
  /**
36
- * Restrict the number of rows for this dataseries to the given number of newest values. (If you use split data, then per each of the split dataseries.)
45
+ * Limit displayed data to the N most recent points per pivot group. Useful for showing only current positions without historical trail. Leave empty to show all data.
37
46
  */
38
47
  export type LatestValues = number;
39
48
  /**
40
- * Blur of 1 means the whole circle is blurred starting from the center point. Blur 0 means no blur effect.
49
+ * Edge blur effect from 0 (sharp edges) to 1 (fully blurred from center). Use slight blur (0.1-0.3) for softer appearance.
41
50
  */
42
51
  export type Blur = number;
43
52
  /**
44
- * Opactity 1 means fully opaque, 0 means fully transparent.
53
+ * Circle transparency from 0 (invisible) to 1 (fully opaque). Use lower values when circles overlap to see density.
45
54
  */
46
55
  export type Opacity = number;
56
+ /**
57
+ * Font size in pixels for label text on circle markers.
58
+ */
47
59
  export type TextSize = number;
60
+ /**
61
+ * Font size in pixels for label text on symbol markers.
62
+ */
48
63
  export type TextSize1 = number;
49
64
  /**
50
- * For available icons check the maki icon set here https://labs.mapbox.com/maki-icons/
65
+ * Icon identifier from available icons: 'marker' for location pin, 'car-front'/'car-top' for vehicle tracking. See Maki icon set at https://labs.mapbox.com/maki-icons/ for more options.
51
66
  */
52
67
  export type IconName = "marker" | "car-front" | "car-top";
53
68
  /**
54
- * In multiples of the original icon size
69
+ * Scale multiplier for the icon (1 = original size, 2 = double size, 0.5 = half size).
55
70
  */
56
71
  export type IconSize = number;
57
72
  /**
58
- * The higher the intensity, the more 'hot' the heatmap becomes. The value is a multiple with default value 1. e.g. to double the intensitiy choose 2.
73
+ * Heat intensity multiplier. Higher values make the heatmap appear 'hotter' with colors reaching maximum faster. Default is 1.
59
74
  */
60
75
  export type Intensity = number;
76
+ /**
77
+ * Heatmap layer transparency from 0 (invisible) to 1 (fully opaque). Lower values let the base map show through.
78
+ */
61
79
  export type Opacity1 = number;
62
80
  /**
63
- * The radius will be combined with the data value to to determine the heat radius of a point.
81
+ * Base radius in pixels for each point's heat contribution. Combined with data value to determine actual heat spread. Larger radius = more blending.
64
82
  */
65
83
  export type RadiusBaseSize = number;
84
+ /**
85
+ * Thickness of the route line in pixels. Use thicker lines for emphasis or when zoomed out.
86
+ */
66
87
  export type LineWidth = number;
67
88
  /**
68
- * For available icons check the maki icon set here https://labs.mapbox.com/maki-icons/
89
+ * Icon displayed at the current position (end of line): 'marker' for generic location, 'car-front'/'car-top' for vehicles.
69
90
  */
70
91
  export type IconName1 = "marker" | "car-front" | "car-top";
71
92
  /**
72
- * In multiples of the original icon size
93
+ * Scale multiplier for the position icon (1 = original size).
73
94
  */
74
95
  export type IconSize1 = number;
96
+ /**
97
+ * The east-west coordinate in decimal degrees (-180 to 180). Example: -122.4194 for San Francisco.
98
+ */
75
99
  export type Longitude = number;
100
+ /**
101
+ * The north-south coordinate in decimal degrees (-90 to 90). Example: 37.7749 for San Francisco.
102
+ */
76
103
  export type Latitude = number;
104
+ /**
105
+ * Optional elevation/altitude value in meters. Can be used for 3D visualization or displayed in tooltips.
106
+ */
77
107
  export type Altitude = number;
108
+ /**
109
+ * Numeric value associated with this location. Used for heatmap intensity, marker sizing, or tooltip display.
110
+ */
78
111
  export type DataPointValue = number;
79
112
  /**
80
- * 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, lon, lat, temperature] and specify 'city' as split column, then you will get a layer for each city.
113
+ * Column value used to split data into multiple layers automatically. Each unique pivot value creates a separate map layer (e.g., pivot by 'vehicle_id' for fleet tracking).
81
114
  */
82
115
  export type SplitDataBy = string;
83
116
  /**
84
- * This is the map data
117
+ * Array of geographic data points. Each point must have latitude and longitude coordinates, with optional altitude, value, and pivot for grouping.
85
118
  */
86
119
  export type MapData = {
87
120
  lon?: Longitude;
@@ -91,6 +124,9 @@ export type MapData = {
91
124
  pivot?: SplitDataBy;
92
125
  [k: string]: unknown;
93
126
  }[];
127
+ /**
128
+ * Array of map layers. Each layer displays geographic data points with its own visualization style (circles, symbols, heatmap, or lines).
129
+ */
94
130
  export type Dataseries = {
95
131
  label?: SeriesLabel;
96
132
  type?: LayerType;
@@ -105,7 +141,7 @@ export type Dataseries = {
105
141
  }[];
106
142
 
107
143
  /**
108
- * A map-chart
144
+ * A Mapbox-powered geospatial visualization widget for displaying location-based data on interactive maps. Use this widget for GPS tracking, asset locations, geographic heatmaps, route visualization, or any data with latitude/longitude coordinates. Supports multiple layer types including circles (points), symbols (icons), heatmaps (density), and lines (tracks/routes). Features auto-follow mode to keep markers in view, multiple map styles, and pivot-based auto-generation of layers from data columns. Ideal for fleet management, IoT device monitoring, field service tracking, and geographic data analysis.
109
145
  */
110
146
  export interface InputData {
111
147
  title?: Title;
@@ -116,9 +152,15 @@ export interface InputData {
116
152
  dataseries?: Dataseries;
117
153
  [k: string]: unknown;
118
154
  }
155
+ /**
156
+ * Primary color for this layer's markers or fill. Used as default when data-driven coloring isn't configured.
157
+ */
119
158
  export interface LayerBaseColor {
120
159
  [k: string]: unknown;
121
160
  }
161
+ /**
162
+ * Styling options specific to circle (point) layers.
163
+ */
122
164
  export interface CircleLayerConfiguration {
123
165
  "circle-blur"?: Blur;
124
166
  "circle-opacity"?: Opacity;
@@ -126,9 +168,15 @@ export interface CircleLayerConfiguration {
126
168
  "text-size"?: TextSize;
127
169
  [k: string]: unknown;
128
170
  }
171
+ /**
172
+ * Color of label text displayed on or near the circle markers.
173
+ */
129
174
  export interface TextColor {
130
175
  [k: string]: unknown;
131
176
  }
177
+ /**
178
+ * Styling options specific to symbol (icon) layers.
179
+ */
132
180
  export interface SymbolLayerConfiguration {
133
181
  "text-color"?: TextColor1;
134
182
  "text-size"?: TextSize1;
@@ -136,15 +184,24 @@ export interface SymbolLayerConfiguration {
136
184
  "icon-size"?: IconSize;
137
185
  [k: string]: unknown;
138
186
  }
187
+ /**
188
+ * Color of label text displayed near the symbol icons.
189
+ */
139
190
  export interface TextColor1 {
140
191
  [k: string]: unknown;
141
192
  }
193
+ /**
194
+ * Styling options specific to heatmap (density) layers.
195
+ */
142
196
  export interface HeatmapLayerConfiguration {
143
197
  "heatmap-intensity"?: Intensity;
144
198
  "heatmap-opacity"?: Opacity1;
145
199
  "heatmap-radius"?: RadiusBaseSize;
146
200
  [k: string]: unknown;
147
201
  }
202
+ /**
203
+ * Styling options specific to line (track/route) layers.
204
+ */
148
205
  export interface TrackLayerConfiguration {
149
206
  "line-width"?: LineWidth;
150
207
  "icon-image"?: IconName1;
package/src/definition-schema.json CHANGED
@@ -1,21 +1,23 @@
1
1
  {
2
2
  "title": "InputData",
3
- "description": "A map-chart",
3
+ "description": "A Mapbox-powered geospatial visualization widget for displaying location-based data on interactive maps. Use this widget for GPS tracking, asset locations, geographic heatmaps, route visualization, or any data with latitude/longitude coordinates. Supports multiple layer types including circles (points), symbols (icons), heatmaps (density), and lines (tracks/routes). Features auto-follow mode to keep markers in view, multiple map styles, and pivot-based auto-generation of layers from data columns. Ideal for fleet management, IoT device monitoring, field service tracking, and geographic data analysis.",
4
4
  "type": "object",
5
5
  "properties": {
6
6
  "title": {
7
7
  "title": "Title",
8
+ "description": "The main heading displayed above the map. Use to describe what geographic data is being shown (e.g., 'Fleet Locations', 'Sensor Network').",
8
9
  "type": "string",
9
10
  "order": 1
10
11
  },
11
12
  "subTitle": {
12
13
  "title": "Subtitle",
14
+ "description": "Secondary text displayed below the title. Use for additional context like region, time period, or data source.",
13
15
  "type": "string",
14
16
  "order": 2
15
17
  },
16
18
  "style": {
17
19
  "title": "Map Style",
18
- "description": "The basic style of the map.",
20
+ "description": "The visual appearance of the base map: 'streets' for road-focused, 'outdoors' for terrain, 'light/dark' for minimal designs, 'satellite' for aerial imagery, 'navigation' for routing focus.",
19
21
  "type": "string",
20
22
  "dataDrivenDisabled": true,
21
23
  "enum": [
@@ -33,19 +35,21 @@
33
35
  },
34
36
  "showLegend": {
35
37
  "title": "Show Legend",
38
+ "description": "When enabled, displays a legend identifying each data layer by color and label. Useful for multi-layer maps.",
36
39
  "type": "boolean",
37
40
  "dataDrivenDisabled": true,
38
41
  "order": 4
39
42
  },
40
43
  "follow": {
41
44
  "title": "Auto Follow",
42
- "description": "If true, the map automatically keeps the drawn locations in focus.",
45
+ "description": "When enabled, the map automatically pans and zooms to keep all data points in view as they update. Disable for fixed-view maps where users control the viewport.",
43
46
  "type": "boolean",
44
47
  "dataDrivenDisabled": true,
45
48
  "order": 5
46
49
  },
47
50
  "dataseries": {
48
51
  "title": "Dataseries",
52
+ "description": "Array of map layers. Each layer displays geographic data points with its own visualization style (circles, symbols, heatmap, or lines).",
49
53
  "order": 8,
50
54
  "type": "array",
51
55
  "dataDrivenDisabled": true,
@@ -54,14 +58,14 @@
54
58
  "properties": {
55
59
  "label": {
56
60
  "title": "Series Label",
57
- "description": "The name for this data series",
61
+ "description": "Display name for this map layer shown in legends and tooltips. Should identify what entities or data this layer represents.",
58
62
  "type": "string",
59
63
  "required": true,
60
64
  "order": 1
61
65
  },
62
66
  "type": {
63
67
  "title": "Layer type",
64
- "description": "Create the specified type of layer on the map.",
68
+ "description": "Visualization style: 'circle' for point markers, 'symbol' for icon markers with labels, 'heatmap' for density visualization, 'line' for connected paths/routes.",
65
69
  "type": "string",
66
70
  "required": true,
67
71
  "dataDrivenDisabled": true,
@@ -70,19 +74,21 @@
70
74
  },
71
75
  "color": {
72
76
  "title": "Layer Base Color",
77
+ "description": "Primary color for this layer's markers or fill. Used as default when data-driven coloring isn't configured.",
73
78
  "type": "color",
74
79
  "color": true,
75
80
  "order": 3
76
81
  },
77
82
  "latestValues": {
78
83
  "title": "Latest Values",
79
- "description": "Restrict the number of rows for this dataseries to the given number of newest values. (If you use split data, then per each of the split dataseries.)",
84
+ "description": "Limit displayed data to the N most recent points per pivot group. Useful for showing only current positions without historical trail. Leave empty to show all data.",
80
85
  "type": "number",
81
86
  "dataDrivenDisabled": true,
82
87
  "order": 4
83
88
  },
84
89
  "circleConfig": {
85
90
  "title": "Circle Layer Configuration",
91
+ "description": "Styling options specific to circle (point) layers.",
86
92
  "type": "object",
87
93
  "order": 5,
88
94
  "condition": {
@@ -92,7 +98,7 @@
92
98
  "properties": {
93
99
  "circle-blur": {
94
100
  "title": "Blur",
95
- "description": "Blur of 1 means the whole circle is blurred starting from the center point. Blur 0 means no blur effect.",
101
+ "description": "Edge blur effect from 0 (sharp edges) to 1 (fully blurred from center). Use slight blur (0.1-0.3) for softer appearance.",
96
102
  "dataDrivenDisabled": true,
97
103
  "min": 0,
98
104
  "max": 1,
@@ -101,7 +107,7 @@
101
107
  },
102
108
  "circle-opacity": {
103
109
  "title": "Opacity",
104
- "description": "Opactity 1 means fully opaque, 0 means fully transparent.",
110
+ "description": "Circle transparency from 0 (invisible) to 1 (fully opaque). Use lower values when circles overlap to see density.",
105
111
  "dataDrivenDisabled": true,
106
112
  "min": 0,
107
113
  "max": 1,
@@ -110,12 +116,14 @@
110
116
  },
111
117
  "text-color": {
112
118
  "title": "Text Color",
119
+ "description": "Color of label text displayed on or near the circle markers.",
113
120
  "type": "color",
114
121
  "color": true,
115
122
  "order": 3
116
123
  },
117
124
  "text-size": {
118
125
  "title": "Text Size",
126
+ "description": "Font size in pixels for label text on circle markers.",
119
127
  "type": "number",
120
128
  "min": 1,
121
129
  "order": 4
@@ -124,6 +132,7 @@
124
132
  },
125
133
  "symbolConfig": {
126
134
  "title": "Symbol Layer Configuration",
135
+ "description": "Styling options specific to symbol (icon) layers.",
127
136
  "type": "object",
128
137
  "order": 5,
129
138
  "condition": {
@@ -133,26 +142,28 @@
133
142
  "properties": {
134
143
  "text-color": {
135
144
  "title": "Text Color",
145
+ "description": "Color of label text displayed near the symbol icons.",
136
146
  "type": "color",
137
147
  "color": true,
138
148
  "order": 1
139
149
  },
140
150
  "text-size": {
141
151
  "title": "Text Size",
152
+ "description": "Font size in pixels for label text on symbol markers.",
142
153
  "type": "number",
143
154
  "min": 1,
144
155
  "order": 2
145
156
  },
146
157
  "icon-image": {
147
158
  "title": "Icon Name",
148
- "description": "For available icons check the maki icon set here https://labs.mapbox.com/maki-icons/",
159
+ "description": "Icon identifier from available icons: 'marker' for location pin, 'car-front'/'car-top' for vehicle tracking. See Maki icon set at https://labs.mapbox.com/maki-icons/ for more options.",
149
160
  "type": "string",
150
161
  "enum": ["marker", "car-front", "car-top"],
151
162
  "order": 3
152
163
  },
153
164
  "icon-size": {
154
165
  "title": "Icon size",
155
- "description": "In multiples of the original icon size",
166
+ "description": "Scale multiplier for the icon (1 = original size, 2 = double size, 0.5 = half size).",
156
167
  "type": "number",
157
168
  "min": 0,
158
169
  "order": 4
@@ -161,6 +172,7 @@
161
172
  },
162
173
  "heatmapConfig": {
163
174
  "title": "Heatmap Layer Configuration",
175
+ "description": "Styling options specific to heatmap (density) layers.",
164
176
  "type": "object",
165
177
  "order": 5,
166
178
  "condition": {
@@ -170,13 +182,14 @@
170
182
  "properties": {
171
183
  "heatmap-intensity": {
172
184
  "title": "Intensity",
173
- "description": "The higher the intensity, the more 'hot' the heatmap becomes. The value is a multiple with default value 1. e.g. to double the intensitiy choose 2.",
185
+ "description": "Heat intensity multiplier. Higher values make the heatmap appear 'hotter' with colors reaching maximum faster. Default is 1.",
174
186
  "type": "number",
175
187
  "min": 0,
176
188
  "order": 1
177
189
  },
178
190
  "heatmap-opacity": {
179
191
  "title": "Opacity",
192
+ "description": "Heatmap layer transparency from 0 (invisible) to 1 (fully opaque). Lower values let the base map show through.",
180
193
  "type": "number",
181
194
  "min": 0,
182
195
  "max": 1,
@@ -184,7 +197,7 @@
184
197
  },
185
198
  "heatmap-radius": {
186
199
  "title": "Radius Base Size",
187
- "description": "The radius will be combined with the data value to to determine the heat radius of a point.",
200
+ "description": "Base radius in pixels for each point's heat contribution. Combined with data value to determine actual heat spread. Larger radius = more blending.",
188
201
  "type": "number",
189
202
  "min": 0,
190
203
  "order": 3
@@ -193,6 +206,7 @@
193
206
  },
194
207
  "lineConfig": {
195
208
  "title": "Track Layer Configuration",
209
+ "description": "Styling options specific to line (track/route) layers.",
196
210
  "type": "object",
197
211
  "order": 5,
198
212
  "condition": {
@@ -202,20 +216,21 @@
202
216
  "properties": {
203
217
  "line-width": {
204
218
  "title": "Line Width",
219
+ "description": "Thickness of the route line in pixels. Use thicker lines for emphasis or when zoomed out.",
205
220
  "type": "number",
206
221
  "min": 1,
207
222
  "order": 1
208
223
  },
209
224
  "icon-image": {
210
225
  "title": "Icon Name",
211
- "description": "For available icons check the maki icon set here https://labs.mapbox.com/maki-icons/",
226
+ "description": "Icon displayed at the current position (end of line): 'marker' for generic location, 'car-front'/'car-top' for vehicles.",
212
227
  "type": "string",
213
228
  "enum": ["marker", "car-front", "car-top"],
214
229
  "order": 3
215
230
  },
216
231
  "icon-size": {
217
232
  "title": "Icon size",
218
- "description": "In multiples of the original icon size",
233
+ "description": "Scale multiplier for the position icon (1 = original size).",
219
234
  "type": "number",
220
235
  "min": 0,
221
236
  "order": 4
@@ -224,7 +239,7 @@
224
239
  },
225
240
  "data": {
226
241
  "title": "Map data",
227
- "description": "This is the map data",
242
+ "description": "Array of geographic data points. Each point must have latitude and longitude coordinates, with optional altitude, value, and pivot for grouping.",
228
243
  "type": "array",
229
244
  "order": 6,
230
245
  "items": {
@@ -232,29 +247,33 @@
232
247
  "properties": {
233
248
  "lon": {
234
249
  "title": "Longitude",
250
+ "description": "The east-west coordinate in decimal degrees (-180 to 180). Example: -122.4194 for San Francisco.",
235
251
  "type": "number",
236
252
  "required": true,
237
253
  "order": 1
238
254
  },
239
255
  "lat": {
240
256
  "title": "Latitude",
257
+ "description": "The north-south coordinate in decimal degrees (-90 to 90). Example: 37.7749 for San Francisco.",
241
258
  "type": "number",
242
259
  "required": true,
243
260
  "order": 2
244
261
  },
245
262
  "alt": {
246
263
  "title": "Altitude",
264
+ "description": "Optional elevation/altitude value in meters. Can be used for 3D visualization or displayed in tooltips.",
247
265
  "type": "number",
248
266
  "order": 3
249
267
  },
250
268
  "value": {
251
269
  "title": "Data point value",
270
+ "description": "Numeric value associated with this location. Used for heatmap intensity, marker sizing, or tooltip display.",
252
271
  "type": "number",
253
272
  "order": 4
254
273
  },
255
274
  "pivot": {
256
275
  "title": "Split Data by",
257
- "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, lon, lat, temperature] and specify 'city' as split column, then you will get a layer for each city.",
276
+ "description": "Column value used to split data into multiple layers automatically. Each unique pivot value creates a separate map layer (e.g., pivot by 'vehicle_id' for fleet tracking).",
258
277
  "type": "string",
259
278
  "order": 5
260
279
  }
package/src/widget-mapbox.ts CHANGED
@@ -458,7 +458,7 @@ export class WidgetMapbox extends LitElement {
458
458
  const config = ds.config as SymbolLayerConfiguration
459
459
  if (!config) return
460
460
  const sz = config['icon-size'] ?? 1
461
- const _imageName = config['icon-image'] ?? 'car'
461
+ const _imageName = config['icon-image'] ?? 'car-front'
462
462
  const imageName = _imageName + sz
463
463
  if (['line', 'symbol'].includes(ds.type ?? '') && !this.imageList.includes(imageName)) {
464
464
  const img = new Image(24 * sz, 24 * sz) as HTMLImageElement
package/thumbnail.webp ADDED
Binary file