@dashspec/renderer 0.0.0-stage → 0.1.1

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.
@@ -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}`.