@dashspec/renderer 0.0.0-stage → 0.1.0
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.
- package/CHANGELOG.md +81 -0
- package/LICENSE +21 -0
- package/README.md +317 -2
- package/dist/chunk-M4WXE3FW.js +254 -0
- package/dist/chunk-M4WXE3FW.js.map +1 -0
- package/dist/chunk-NLKXHTLO.js +178 -0
- package/dist/chunk-NLKXHTLO.js.map +1 -0
- package/dist/chunk-S4EW5IEA.js +3372 -0
- package/dist/chunk-S4EW5IEA.js.map +1 -0
- package/dist/core-C8ay_SoY.d.ts +7611 -0
- package/dist/core.d.ts +3 -0
- package/dist/core.js +167 -0
- package/dist/core.js.map +1 -0
- package/dist/index-CdW6ugMG.d.ts +27 -0
- package/dist/index.d.ts +1434 -0
- package/dist/index.js +7638 -0
- package/dist/index.js.map +1 -0
- package/dist/sandbox-WEMG76LE.js +10 -0
- package/dist/sandbox-WEMG76LE.js.map +1 -0
- package/dist/sandbox.d.ts +15 -0
- package/dist/sandbox.js +8 -0
- package/dist/sandbox.js.map +1 -0
- package/dist/schema.json +3060 -0
- package/docs/README.md +25 -0
- package/docs/api.md +513 -0
- package/docs/data.md +582 -0
- package/docs/design-systems.md +227 -0
- package/docs/getting-started.md +242 -0
- package/docs/json-format.md +346 -0
- package/docs/security.md +141 -0
- package/docs/server-rendering.md +126 -0
- package/docs/state-and-events.md +551 -0
- package/docs/theming.md +244 -0
- package/docs/widgets.md +606 -0
- package/package.json +104 -3
|
@@ -0,0 +1,551 @@
|
|
|
1
|
+
# State and events
|
|
2
|
+
|
|
3
|
+
A dashboard keeps all of its live values in one **state tree**: filter values, what
|
|
4
|
+
each panel has selected, the current view, the open pop-up, datasource results, and
|
|
5
|
+
your own values. Widgets emit **events** (a click, a row click, a tab change), and the
|
|
6
|
+
document answers them with **actions** that change the state, load data or talk to your
|
|
7
|
+
app. Your app can read and drive the same state.
|
|
8
|
+
|
|
9
|
+
- [The state tree](#the-state-tree)
|
|
10
|
+
- [Events](#events)
|
|
11
|
+
- [Actions](#actions): every built-in action
|
|
12
|
+
- [Named actions](#named-actions), [watch](#watch), [host actions](#host-actions), [scripts](#scripts)
|
|
13
|
+
- [Read and drive a dashboard from your app](#drive-a-dashboard-from-your-app)
|
|
14
|
+
- [URL sync](#url-sync)
|
|
15
|
+
|
|
16
|
+
## The state tree
|
|
17
|
+
|
|
18
|
+
| Path | What it holds | Written by |
|
|
19
|
+
|---|---|---|
|
|
20
|
+
| `filters.<name>` | Filter values (`spec.variables`) | Filter controls, `setVariable`, your app |
|
|
21
|
+
| `panels.<id>` | Each panel's state: `selection`, `hover`, `drill`, `controls`, `hiddenSeries`, `hidden`, `ui` | Actions, widgets (`ui` via `setUi`) |
|
|
22
|
+
| `view` | The current view (which `layouts` entries show) | `setView`, your app |
|
|
23
|
+
| `modal` | The open pop-up: `{ id, args }`, or `null` | `openModal`, `closeModal` |
|
|
24
|
+
| `highlight.<group>` | The hovered value of a highlight group | `highlight` |
|
|
25
|
+
| `datasources.<id>` | `{ status, data, error, updatedAt, stale, live }` | The data engine. Read-only |
|
|
26
|
+
| `context` | What your app passed in `context` | Your app. Read-only |
|
|
27
|
+
| `<your key>` | Your own values, declared with defaults in `spec.state` | `setState`, scripts, widgets, your app |
|
|
28
|
+
|
|
29
|
+
```json
|
|
30
|
+
"state": { "selectedOrderId": null, "compare": false }
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Your own keys live at the top level next to the runtime's: read them as
|
|
34
|
+
`${selectedOrderId}` or `${state.selectedOrderId}` (`state` is the whole tree). The
|
|
35
|
+
names `filters`, `panels`, `view`, `modal`, `highlight`, `datasources` and `context`
|
|
36
|
+
are reserved. Writes that would break the tree are refused and reported: replacing
|
|
37
|
+
`filters`, `panels` or `highlight` with a non-object, or writing `datasources` or
|
|
38
|
+
`context`.
|
|
39
|
+
|
|
40
|
+
Panel **controls** are small filters that belong to one panel. They take the same
|
|
41
|
+
fields as filters and are read as `${panel.controls.<name>}` inside that panel, or
|
|
42
|
+
`${panels.<id>.controls.<name>}` elsewhere:
|
|
43
|
+
|
|
44
|
+
```json
|
|
45
|
+
"trend": {
|
|
46
|
+
"kind": "LineChart",
|
|
47
|
+
"spec": { "data": { "source": "daily" }, "x": "date", "y": "${panel.controls.metric}" },
|
|
48
|
+
"controls": [{ "name": "metric", "kind": "Select", "options": ["orders", "revenue"], "default": "orders" }]
|
|
49
|
+
}
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Events
|
|
53
|
+
|
|
54
|
+
A node's `on` map answers its widget's events. Each entry is a list of steps; a step
|
|
55
|
+
is an action object or the name of a [named action](#named-actions):
|
|
56
|
+
|
|
57
|
+
```json
|
|
58
|
+
"ordersTable": {
|
|
59
|
+
"kind": "Table",
|
|
60
|
+
"spec": { "data": { "source": "orders" } },
|
|
61
|
+
"on": {
|
|
62
|
+
"rowClick": [
|
|
63
|
+
{ "do": "setSelection" },
|
|
64
|
+
{ "do": "openModal", "modal": "order", "args": { "id": "${event.datum.id}" } }
|
|
65
|
+
]
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
The event object, readable as `${event.*}`:
|
|
71
|
+
|
|
72
|
+
| Field | What it is |
|
|
73
|
+
|---|---|
|
|
74
|
+
| `type` | The event name (`click`, `rowClick`, …) |
|
|
75
|
+
| `panel` | The panel's id |
|
|
76
|
+
| `part` | Where it happened (`row`, `cell`, `bar`, `legend`, `tile`…) |
|
|
77
|
+
| `datum` | The row behind it (a table row, a chart point's row, a tile's row) |
|
|
78
|
+
| `value` | The value (a cell's value, a slice's value, the tab key) |
|
|
79
|
+
| `series`, `x`, `y`, `index` | Charts: series name, category, value, row index |
|
|
80
|
+
| `column` | Table `cellClick`: the column key |
|
|
81
|
+
|
|
82
|
+
Each widget's events are listed in [Widgets](widgets.md#built-in-widgets). Clicking
|
|
83
|
+
something doesn't select it by itself; add a `setSelection` step when other panels
|
|
84
|
+
should react to it.
|
|
85
|
+
|
|
86
|
+
**Per part.** Instead of a list, give one handler per part:
|
|
87
|
+
|
|
88
|
+
```json
|
|
89
|
+
"on": { "click": { "bar": [{ "do": "drillDown" }], "legend": [{ "do": "toggleSeries" }] } }
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
**Conditions.** Any action can have `when`, an expression; the step is skipped when it
|
|
93
|
+
is false:
|
|
94
|
+
|
|
95
|
+
```json
|
|
96
|
+
{ "do": "openModal", "modal": "order", "when": "event.datum.status != 'draft'", "args": { "id": "${event.datum.id}" } }
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
**Run modes.** When an event fires again while its previous run is still going
|
|
100
|
+
(a slow `http` or script), the handler's mode decides what happens: `"latest"`
|
|
101
|
+
(default: a still-running script's further state writes are dropped), `"parallel"` (both
|
|
102
|
+
run), or `"queue"` (the new run waits for the previous one):
|
|
103
|
+
|
|
104
|
+
```json
|
|
105
|
+
"on": { "click": { "run": [{ "do": "http", "connection": "api", "path": "/orders/recount" }], "mode": "queue" } }
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
**Dashboard events** go in `spec.on`:
|
|
109
|
+
|
|
110
|
+
| Event | When | Event fields |
|
|
111
|
+
|---|---|---|
|
|
112
|
+
| `load` | Once, when the dashboard starts | |
|
|
113
|
+
| `variableChange` | A filter changed | `name`, `value` |
|
|
114
|
+
| `close` | The viewer closed a pop-up (×, Escape or the backdrop) | `modal` |
|
|
115
|
+
|
|
116
|
+
```json
|
|
117
|
+
"on": { "variableChange": [{ "do": "clearSelection", "panel": "ordersTable" }] }
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
A modal's own `on.close` (a list of actions) also runs when the viewer closes it.
|
|
121
|
+
|
|
122
|
+
## Actions
|
|
123
|
+
|
|
124
|
+
Every action is an object with `do` and the fields below. Any `${…}` in its fields is
|
|
125
|
+
filled when it runs, with `event` in scope. Every action also takes `when`. The schema of
|
|
126
|
+
each is exported as `ACTION_SCHEMAS[do]` from `@dashspec/renderer/core`.
|
|
127
|
+
|
|
128
|
+
### State
|
|
129
|
+
|
|
130
|
+
**`setState`**: writes your own state. `merge: true` merges an object into the current
|
|
131
|
+
value.
|
|
132
|
+
|
|
133
|
+
```json
|
|
134
|
+
{ "do": "setState", "path": "selectedOrderId", "value": "${event.datum.id}" }
|
|
135
|
+
{ "do": "setState", "path": "chartOptions", "value": { "stacked": true }, "merge": true }
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
**`setVariable`**: sets a filter by `name`.
|
|
139
|
+
|
|
140
|
+
```json
|
|
141
|
+
{ "do": "setVariable", "name": "region", "value": "${event.datum.region}" }
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
**`setSelection`**: stores a selection on a panel (`panels.<id>.selection`). Without
|
|
145
|
+
`panel`, the event's panel; without `value`, the event's `datum` (or `value`).
|
|
146
|
+
|
|
147
|
+
```json
|
|
148
|
+
{ "do": "setSelection" }
|
|
149
|
+
{ "do": "setSelection", "panel": "map", "value": "${event.datum.storeId}" }
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
**`clearSelection`**: clears it (`panel` optional, as above).
|
|
153
|
+
|
|
154
|
+
```json
|
|
155
|
+
{ "do": "clearSelection", "panel": "ordersTable" }
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
### View
|
|
159
|
+
|
|
160
|
+
**`show`**, **`hide`**, **`toggle`**: show or hide panels (`panel` is an id or a list).
|
|
161
|
+
|
|
162
|
+
```json
|
|
163
|
+
{ "do": "toggle", "panel": ["details", "detailsChart"] }
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
**`setView`**: switches to another view: the `layouts` entries with that `view`.
|
|
167
|
+
|
|
168
|
+
```json
|
|
169
|
+
{ "do": "setView", "view": "detail" }
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
**`openModal`**: opens a pop-up from `spec.modals`. Its panels read `args` as
|
|
173
|
+
`${modal.args.*}`.
|
|
174
|
+
|
|
175
|
+
```json
|
|
176
|
+
{ "do": "openModal", "modal": "order", "args": { "id": "${event.datum.id}", "customer": "${event.datum.customer}" } }
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
**`closeModal`**: closes it.
|
|
180
|
+
|
|
181
|
+
```json
|
|
182
|
+
{ "do": "closeModal" }
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
**`highlight`**: sets a highlight group's value to the hovered `x` (or `datum`), and
|
|
186
|
+
clears it on `hoverEnd`. Widgets with `"highlight": "<group>"` in their spec show it.
|
|
187
|
+
|
|
188
|
+
```json
|
|
189
|
+
"on": { "hover": [{ "do": "highlight", "group": "day" }], "hoverEnd": [{ "do": "highlight", "group": "day" }] }
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
**`toggleSeries`**: hides or shows a chart series (`panels.<id>.hiddenSeries`).
|
|
193
|
+
Without `series`, the event's series; without `panel`, the event's panel.
|
|
194
|
+
|
|
195
|
+
```json
|
|
196
|
+
{ "do": "toggleSeries", "panel": "trend", "series": "returns" }
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
**`fullscreen`**: asks the browser to show the page full screen.
|
|
200
|
+
|
|
201
|
+
```json
|
|
202
|
+
{ "do": "fullscreen" }
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
### Drill-down
|
|
206
|
+
|
|
207
|
+
A panel declares drill **levels**; the first is the top. At each level, `x` picks the
|
|
208
|
+
category field and `query` is added to the panel's datasource query (with
|
|
209
|
+
`${drill.<level>}` holding the value picked at that level). The breadcrumb in the panel
|
|
210
|
+
header goes back up.
|
|
211
|
+
|
|
212
|
+
```json
|
|
213
|
+
"salesChart": {
|
|
214
|
+
"kind": "BarChart",
|
|
215
|
+
"spec": { "data": { "source": "sales" }, "x": "month", "y": "total" },
|
|
216
|
+
"drill": {
|
|
217
|
+
"levels": [
|
|
218
|
+
{ "name": "month", "label": "Month", "x": "month" },
|
|
219
|
+
{ "name": "day", "label": "Day", "x": "day", "query": { "month": "${drill.month}", "granularity": "day" } }
|
|
220
|
+
]
|
|
221
|
+
},
|
|
222
|
+
"on": { "click": [{ "do": "drillDown" }] }
|
|
223
|
+
}
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
A level may also name another `source`, and the last level may hold an action in `do`
|
|
227
|
+
(with its fields alongside) that runs instead of drilling further.
|
|
228
|
+
|
|
229
|
+
**`drillDown`**, **`drillUp`**, **`drillReset`**: go one level down (recording the
|
|
230
|
+
clicked `x`), one level up, or back to the top. `panel` defaults to the event's panel.
|
|
231
|
+
|
|
232
|
+
```json
|
|
233
|
+
{ "do": "drillUp", "panel": "salesChart" }
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
### Data
|
|
237
|
+
|
|
238
|
+
**`refresh`**: reloads datasources: one id, a list, or every loaded one without
|
|
239
|
+
`source`.
|
|
240
|
+
|
|
241
|
+
```json
|
|
242
|
+
{ "do": "refresh", "source": ["orders", "summary"] }
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
**`fetch`**: loads a datasource now (also a `manual` one), adding `params` to its query.
|
|
246
|
+
|
|
247
|
+
```json
|
|
248
|
+
{ "do": "fetch", "source": "orderHistory", "params": { "customer": "${event.datum.customerId}" } }
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
**`http`**: sends a request. `method` defaults to `POST`; give exactly one of `path`
|
|
252
|
+
(with `connection`) or `url`. `saveTo` stores the response at a state path.
|
|
253
|
+
|
|
254
|
+
```json
|
|
255
|
+
{
|
|
256
|
+
"do": "http",
|
|
257
|
+
"connection": "api",
|
|
258
|
+
"path": "/orders/${event.datum.id}/approve",
|
|
259
|
+
"body": { "note": "${state.approvalNote}" },
|
|
260
|
+
"saveTo": "lastApproval"
|
|
261
|
+
}
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
**`download`**: requests a file and saves it. `method` defaults to `GET`.
|
|
265
|
+
|
|
266
|
+
```json
|
|
267
|
+
{ "do": "download", "connection": "api", "path": "/reports/weekly.pdf", "query": { "week": "${filters.week}" }, "filename": "weekly-${filters.week}.pdf" }
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
**`export`**: downloads the rows a panel shows. `format` is `csv`; `xlsx` needs an
|
|
271
|
+
add-on (it reports `export` to `onError`).
|
|
272
|
+
|
|
273
|
+
```json
|
|
274
|
+
{ "do": "export", "panel": "ordersTable", "format": "csv", "filename": "orders-${today()}.csv" }
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
### Navigation and messages
|
|
278
|
+
|
|
279
|
+
**`navigate`**: opens a link. Only `http(s)`, `mailto` and same-site links are opened
|
|
280
|
+
(others are refused and reported as `unsafe-url`). Your `onNavigate` handles it if
|
|
281
|
+
given (use your router there).
|
|
282
|
+
|
|
283
|
+
```json
|
|
284
|
+
{ "do": "navigate", "to": "/orders/${event.datum.id}", "query": { "tab": "history" }, "newTab": false }
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
**`openDashboard`**: asks your app to open another dashboard by its `metadata.key`,
|
|
288
|
+
with filter values. Handled by `onOpenDashboard`; nothing happens without it.
|
|
289
|
+
|
|
290
|
+
```json
|
|
291
|
+
{ "do": "openDashboard", "dashboard": "store-detail", "filters": { "store": "${event.datum.storeId}" }, "newTab": true }
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
**`toast`**: shows a message through your `onToast` (default: `console.info`). `tone`
|
|
295
|
+
is `good`, `warn`, `bad`, `neutral` or `info`.
|
|
296
|
+
|
|
297
|
+
```json
|
|
298
|
+
{ "do": "toast", "message": "Order ${event.datum.id} approved", "tone": "good" }
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
**`emit`**: sends a named event to your app's `onEvent`, as `{ type: event, value: payload }`.
|
|
302
|
+
|
|
303
|
+
```json
|
|
304
|
+
{ "do": "emit", "event": "orderOpened", "payload": { "id": "${event.datum.id}" } }
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
### Flow and code
|
|
308
|
+
|
|
309
|
+
**`sequence`**: runs steps in order (each waits for the previous one).
|
|
310
|
+
|
|
311
|
+
```json
|
|
312
|
+
{ "do": "sequence", "steps": [{ "do": "http", "connection": "api", "path": "/orders/sync" }, { "do": "refresh", "source": "orders" }, "notifyDone"] }
|
|
313
|
+
```
|
|
314
|
+
|
|
315
|
+
**`call`**: calls a function your app registered in `functions`, with `args`.
|
|
316
|
+
|
|
317
|
+
```json
|
|
318
|
+
{ "do": "call", "fn": "openCustomerPanel", "args": { "id": "${event.datum.customerId}" } }
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
```tsx
|
|
322
|
+
<DashboardRenderer document={doc} functions={{ openCustomerPanel: (args) => drawer.open(args) }} />
|
|
323
|
+
```
|
|
324
|
+
|
|
325
|
+
**`script`**: runs a callback (see [Scripts](#scripts)).
|
|
326
|
+
|
|
327
|
+
```json
|
|
328
|
+
{ "do": "script", "code": "(event, state) => { state.compare = !state.compare }" }
|
|
329
|
+
```
|
|
330
|
+
|
|
331
|
+
Any other `do` must be a [host action](#host-actions) (`"acme.notify"`). An unknown
|
|
332
|
+
`do` is a validation warning, and running it reports an `action` error.
|
|
333
|
+
|
|
334
|
+
## Named actions
|
|
335
|
+
|
|
336
|
+
Reusable actions go in `spec.actions`, by name; handlers refer to them by that name.
|
|
337
|
+
A named action is an action object or a callback:
|
|
338
|
+
|
|
339
|
+
```json
|
|
340
|
+
"actions": {
|
|
341
|
+
"openOrder": { "do": "openModal", "modal": "order", "args": { "id": "${event.datum.id}" } },
|
|
342
|
+
"notifyDone": { "do": "toast", "message": "Done", "tone": "good" },
|
|
343
|
+
"flagOrder": "(event, state, api) => api.http('api', { method: 'POST', path: '/orders/' + event.datum.id + '/flag' })"
|
|
344
|
+
},
|
|
345
|
+
"panels": {
|
|
346
|
+
"ordersTable": { "kind": "Table", "spec": { "data": { "source": "orders" } }, "on": { "rowClick": ["openOrder"] } }
|
|
347
|
+
}
|
|
348
|
+
```
|
|
349
|
+
|
|
350
|
+
The `Content` widget's Markdown can run one too: `[Export](action:exportOrders)`.
|
|
351
|
+
|
|
352
|
+
## `watch`
|
|
353
|
+
|
|
354
|
+
`watch` runs actions when a value in the state tree changes, whatever changed it: a
|
|
355
|
+
filter, another panel's selection, your own state.
|
|
356
|
+
|
|
357
|
+
```json
|
|
358
|
+
"orderDetail": {
|
|
359
|
+
"kind": "Kpi",
|
|
360
|
+
"spec": { "data": { "source": "orderDetail", "path": "total" } },
|
|
361
|
+
"watch": [
|
|
362
|
+
{ "path": "panels.ordersTable.selection", "do": [{ "do": "setState", "path": "selectedOrderId", "value": "${event.value.id}" }] },
|
|
363
|
+
{ "path": "filters.region", "do": [{ "do": "clearSelection", "panel": "ordersTable" }] }
|
|
364
|
+
]
|
|
365
|
+
}
|
|
366
|
+
```
|
|
367
|
+
|
|
368
|
+
The handler gets `{ type: "stateChange", panel, value }` as `event`, where `value` is
|
|
369
|
+
the new value. If watches keep triggering each other (more than 50 runs in one second),
|
|
370
|
+
all watches stop and `onError` gets `{ code: "loop" }`.
|
|
371
|
+
|
|
372
|
+
## Host actions
|
|
373
|
+
|
|
374
|
+
Your app can add actions. Register a function under a namespaced name; documents use
|
|
375
|
+
it as `do`:
|
|
376
|
+
|
|
377
|
+
```tsx
|
|
378
|
+
import { DashSpecProvider } from "@dashspec/renderer";
|
|
379
|
+
|
|
380
|
+
<DashSpecProvider
|
|
381
|
+
actions={{
|
|
382
|
+
"acme.notify": async (action, { event, api }) => {
|
|
383
|
+
await notifications.send({ channel: String(action.channel), text: String(action.message) });
|
|
384
|
+
api.toast("Sent", "good");
|
|
385
|
+
},
|
|
386
|
+
}}
|
|
387
|
+
>
|
|
388
|
+
```
|
|
389
|
+
|
|
390
|
+
```json
|
|
391
|
+
{ "do": "acme.notify", "channel": "ops", "message": "Order ${event.datum.id} needs review" }
|
|
392
|
+
```
|
|
393
|
+
|
|
394
|
+
The function receives the action object with its templates filled, and
|
|
395
|
+
`{ event, api }`, where `api` is the [callback API](#the-api-object). Its own fields are
|
|
396
|
+
up to you; validation doesn't check them.
|
|
397
|
+
|
|
398
|
+
## Scripts
|
|
399
|
+
|
|
400
|
+
When an action list isn't enough, documents can contain code:
|
|
401
|
+
|
|
402
|
+
- a **callback**: a handler or named action written as a function,
|
|
403
|
+
`(event, state, api) => { … }`,
|
|
404
|
+
- a **`script` action**: `{ "do": "script", "code": "(event, state, api) => { … }" }`,
|
|
405
|
+
- an **`fn` transform step**: `{ "fn": "return rows.filter(r => r.total > 0)" }`,
|
|
406
|
+
- an **`fn` prop**: any widget prop written as `{ "fn": "…" }` becomes a function with
|
|
407
|
+
parameters `p` (what the widget passes) and `data` (the panel's data).
|
|
408
|
+
|
|
409
|
+
```json
|
|
410
|
+
"on": {
|
|
411
|
+
"rowClick": "(event, state, api) => { state.selectedOrderId = event.datum.id; if (event.datum.total > 1000) api.toast('Large order', 'warn'); }"
|
|
412
|
+
}
|
|
413
|
+
```
|
|
414
|
+
|
|
415
|
+
```json
|
|
416
|
+
"options": { "tooltip": { "formatter": { "fn": "return p.name + ': ' + p.value + ' orders'" } } }
|
|
417
|
+
```
|
|
418
|
+
|
|
419
|
+
### Script modes
|
|
420
|
+
|
|
421
|
+
The `scripts` prop decides how this code runs:
|
|
422
|
+
|
|
423
|
+
| Mode | What happens |
|
|
424
|
+
|---|---|
|
|
425
|
+
| `"sandbox"` (default) | Code runs in a QuickJS WebAssembly sandbox, loaded only when a document has code. It sees only `event`, `state` and `api` (or `rows`, or the fn parameters): no `window`, DOM, storage, cookies, network or tokens. Values cross as JSON. Limits: 1 s for synchronous code, 50 ms per fn prop call, 30 s for a callback including its awaits, 32 MB memory |
|
|
426
|
+
| `"trusted"` | Code runs with `new Function` in the page. Only for documents written by people you trust as much as your own code |
|
|
427
|
+
| `"off"` | Callbacks and fn props do nothing; fn transforms fail with an error |
|
|
428
|
+
|
|
429
|
+
Keep the default unless you have a reason; see [Security](security.md).
|
|
430
|
+
|
|
431
|
+
### The `state` object
|
|
432
|
+
|
|
433
|
+
`state` in a callback is the live state tree. Reads see current values; assignments
|
|
434
|
+
write at once, even after an `await`:
|
|
435
|
+
|
|
436
|
+
```js
|
|
437
|
+
(event, state, api) => {
|
|
438
|
+
state.selectedOrderId = event.datum.id;
|
|
439
|
+
state.filters.region = event.datum.region;
|
|
440
|
+
state.compare = !state.compare;
|
|
441
|
+
}
|
|
442
|
+
```
|
|
443
|
+
|
|
444
|
+
The same write rules as `setState` apply (no writing `datasources` or `context`).
|
|
445
|
+
|
|
446
|
+
### The `api` object
|
|
447
|
+
|
|
448
|
+
| Method | What it does |
|
|
449
|
+
|---|---|
|
|
450
|
+
| `api.fetch(source, params?)` | Loads a datasource now; resolves with its data |
|
|
451
|
+
| `api.http(connection, request)` | Sends a request on a connection (`{ method?, path or url, query?, body? }`, `GET` by default); resolves with the response |
|
|
452
|
+
| `api.refresh(source?)` | Reloads one, several or all datasources |
|
|
453
|
+
| `api.navigate(to)` | Like `navigate` (same link check) |
|
|
454
|
+
| `api.toast(message, tone?)` | Like `toast` |
|
|
455
|
+
| `api.emit(event, payload?)` | Like `emit` |
|
|
456
|
+
| `api.call(fn, args?)` | Calls one of your `functions`; resolves with its result |
|
|
457
|
+
|
|
458
|
+
A callback that throws reports `{ code: "script" }` to `onError` and shows the message
|
|
459
|
+
as a `bad` toast.
|
|
460
|
+
|
|
461
|
+
## Drive a dashboard from your app
|
|
462
|
+
|
|
463
|
+
### Listen
|
|
464
|
+
|
|
465
|
+
```tsx
|
|
466
|
+
<DashboardRenderer
|
|
467
|
+
document={doc}
|
|
468
|
+
onVariableChange={(name, value) => analytics.track("filter", { name, value })}
|
|
469
|
+
onSelectionChange={(panel, selection) => panel === "ordersTable" && setSidebarOrder(selection)}
|
|
470
|
+
onEvent={(e) => e.type === "orderOpened" && router.prefetch(`/orders/${(e.value as { id: string }).id}`)}
|
|
471
|
+
onStateChange={(tree) => console.debug(tree.view)}
|
|
472
|
+
/>
|
|
473
|
+
```
|
|
474
|
+
|
|
475
|
+
### Control values
|
|
476
|
+
|
|
477
|
+
`variables`, `state` and `view` set values from your app. They are applied when the
|
|
478
|
+
dashboard starts and whenever the object's content changes; only values that differ
|
|
479
|
+
from the current ones are written, so the viewer's own changes aren't undone on every
|
|
480
|
+
render. A filter given in `variables` isn't read from the URL.
|
|
481
|
+
|
|
482
|
+
```tsx
|
|
483
|
+
const [region, setRegion] = useState("North");
|
|
484
|
+
|
|
485
|
+
<RegionTabs value={region} onChange={setRegion} />
|
|
486
|
+
<DashboardRenderer
|
|
487
|
+
document={doc}
|
|
488
|
+
variables={{ region }}
|
|
489
|
+
onVariableChange={(name, value) => name === "region" && setRegion(String(value))}
|
|
490
|
+
/>;
|
|
491
|
+
```
|
|
492
|
+
|
|
493
|
+
`state` takes paths: `state={{ selectedOrderId: orderId }}`.
|
|
494
|
+
|
|
495
|
+
### The ref handle
|
|
496
|
+
|
|
497
|
+
```tsx
|
|
498
|
+
const dash = useRef<DashboardHandle>(null);
|
|
499
|
+
|
|
500
|
+
<DashboardRenderer ref={dash} document={doc} />
|
|
501
|
+
<button onClick={() => dash.current?.refresh()}>Reload</button>
|
|
502
|
+
<button onClick={() => dash.current?.run({ do: "openModal", modal: "order", args: { id: "A-1" } })}>Open A-1</button>
|
|
503
|
+
<button onClick={() => dash.current?.exportData("ordersTable")}>Export</button>
|
|
504
|
+
```
|
|
505
|
+
|
|
506
|
+
Methods: `getState`, `setState`, `setVariable`, `refresh`, `reset`, `run`,
|
|
507
|
+
`exportData` (see the [API reference](api.md#dashboardhandle)).
|
|
508
|
+
|
|
509
|
+
### Hooks by `id`
|
|
510
|
+
|
|
511
|
+
Components anywhere in your app (not only inside the renderer) can read and drive a
|
|
512
|
+
dashboard by its `id`:
|
|
513
|
+
|
|
514
|
+
```tsx
|
|
515
|
+
import { useDashboardActions, useDashboardState } from "@dashspec/renderer";
|
|
516
|
+
|
|
517
|
+
function OrderSidebar() {
|
|
518
|
+
const selected = useDashboardState("orders", (t) => t.panels.ordersTable?.selection);
|
|
519
|
+
const { setVariable, refresh, ready } = useDashboardActions("orders");
|
|
520
|
+
if (!ready) return null;
|
|
521
|
+
return (
|
|
522
|
+
<aside>
|
|
523
|
+
<p>Selected: {JSON.stringify(selected)}</p>
|
|
524
|
+
<button onClick={() => setVariable("region", "South")}>South</button>
|
|
525
|
+
<button onClick={() => refresh("orders")}>Reload</button>
|
|
526
|
+
</aside>
|
|
527
|
+
);
|
|
528
|
+
}
|
|
529
|
+
|
|
530
|
+
<DashboardRenderer id="orders" document={doc} />;
|
|
531
|
+
```
|
|
532
|
+
|
|
533
|
+
## URL sync
|
|
534
|
+
|
|
535
|
+
In view mode, filter values and the current view are kept in the page's query string,
|
|
536
|
+
so a link reopens the dashboard as the viewer left it:
|
|
537
|
+
|
|
538
|
+
```
|
|
539
|
+
https://app.example.com/reports?orders.region=North&orders.period=2026-11-01..2026-11-07&orders.view=detail
|
|
540
|
+
```
|
|
541
|
+
|
|
542
|
+
- Keys are prefixed with the dashboard's `id` (`orders.region`), or `v.` without one.
|
|
543
|
+
Without an `id`, only the first dashboard on a page syncs; give each its own `id`.
|
|
544
|
+
- Lists are comma-separated; date ranges are `from..to`, or a preset name
|
|
545
|
+
(`?orders.period=last7days`), which reads back as that preset's dates for today, the
|
|
546
|
+
same way a filter's `default` preset is resolved.
|
|
547
|
+
- A filter with `"persist": "memory"` or `"none"` stays out of the URL (`"url"` is the
|
|
548
|
+
default).
|
|
549
|
+
- The URL is updated with `history.replaceState`, so filtering doesn't add history
|
|
550
|
+
entries.
|
|
551
|
+
- Turn it off with `urlSync={false}`.
|