@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
package/docs/data.md
ADDED
|
@@ -0,0 +1,582 @@
|
|
|
1
|
+
# Data
|
|
2
|
+
|
|
3
|
+
A dashboard gets its data from **datasources** (`spec.datasources`). Datasources that
|
|
4
|
+
call an API go through **connections** (`spec.connections`), which hold the base URL and
|
|
5
|
+
the kind of auth, never the credentials. Values in requests and props use `${…}`
|
|
6
|
+
**templates**, written in a small, safe **expression language**.
|
|
7
|
+
|
|
8
|
+
- [Connections](#connections)
|
|
9
|
+
- [Datasources](#datasources)
|
|
10
|
+
- [Transforms](#transforms)
|
|
11
|
+
- [Loading, refresh and cache](#loading-refresh-and-cache)
|
|
12
|
+
- [Templates](#templates) and [expressions](#expressions)
|
|
13
|
+
- [Custom datasource types](#custom-datasource-types)
|
|
14
|
+
- [Errors](#errors)
|
|
15
|
+
|
|
16
|
+
## Connections
|
|
17
|
+
|
|
18
|
+
```json
|
|
19
|
+
"connections": {
|
|
20
|
+
"api": {
|
|
21
|
+
"baseUrl": "https://api.example.com/v1",
|
|
22
|
+
"auth": { "type": "bearer", "token": { "from": "host" } },
|
|
23
|
+
"headers": { "X-Tenant": "${context.tenant}" },
|
|
24
|
+
"timeout": "20s",
|
|
25
|
+
"retry": { "times": 3, "backoff": "exponential" }
|
|
26
|
+
}
|
|
27
|
+
}
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
| Field | Type | What it does |
|
|
31
|
+
|---|---|---|
|
|
32
|
+
| `baseUrl` | string, or `{ host: url }` | Where `path` requests go (below) |
|
|
33
|
+
| `auth` | object | How requests are authenticated (below) |
|
|
34
|
+
| `headers` | `{ name: template }` | Sent with every request on this connection. Templates are filled at send time; empty values are left out |
|
|
35
|
+
| `timeout` | duration | Per attempt. Default `"30s"` |
|
|
36
|
+
| `retry` | `false` or `{ times, backoff, on }` | `times` (0–10, default 2), `backoff` `"exponential"` (default: 300 ms, 600 ms, 1.2 s…) or `"fixed"` (500 ms), `on` (status codes, default 408, 429, 500, 502, 503, 504). Network errors and timeouts are retried too. A `Retry-After` header wins, capped at 30 s |
|
|
37
|
+
| `description` | string | For people |
|
|
38
|
+
|
|
39
|
+
GET requests are retried twice by default; other methods only when `retry` is set.
|
|
40
|
+
Durations are written `"300ms"`, `"30s"`, `"5m"`, `"1h"` or `"2d"`.
|
|
41
|
+
|
|
42
|
+
### `baseUrl` per host
|
|
43
|
+
|
|
44
|
+
One document can serve several environments. Give `baseUrl` as a map from the page's
|
|
45
|
+
host (`window.location.host`) to a base URL, with `"*"` as the fallback:
|
|
46
|
+
|
|
47
|
+
```json
|
|
48
|
+
"baseUrl": {
|
|
49
|
+
"app.example.com": "https://api.example.com/v1",
|
|
50
|
+
"staging.example.com": "https://api.staging.example.com/v1",
|
|
51
|
+
"localhost:5173": "http://localhost:8000/v1",
|
|
52
|
+
"*": "/api/v1"
|
|
53
|
+
}
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
With no match and no `"*"`, requests on that connection fail with a `config` error. A
|
|
57
|
+
connection without `baseUrl` points at the page's own origin.
|
|
58
|
+
|
|
59
|
+
### Auth types
|
|
60
|
+
|
|
61
|
+
| `auth.type` | Fields | What is sent |
|
|
62
|
+
|---|---|---|
|
|
63
|
+
| `none` | | Nothing |
|
|
64
|
+
| `bearer` | `token` (a token source), `header` (default `"Authorization"`), `scheme` (default `"Bearer"`), `refresh` | `Authorization: Bearer <token>` |
|
|
65
|
+
| `apiKey` | `in` (`"header"` or `"query"`), `name`, `from` (a token source) | The key as that header or query parameter |
|
|
66
|
+
| `cookie` | | The browser's cookies (`credentials: "include"`) |
|
|
67
|
+
| `headers` | `headers: { name: template }` | Those headers |
|
|
68
|
+
|
|
69
|
+
Auth is attached only to requests that name the connection **and** go to the
|
|
70
|
+
connection's own origin. A full `url` to another site never gets the token.
|
|
71
|
+
|
|
72
|
+
### Token sources
|
|
73
|
+
|
|
74
|
+
A token source says where the token comes from. It is never the token itself;
|
|
75
|
+
validation rejects literal tokens in a document (`secret`).
|
|
76
|
+
|
|
77
|
+
| Source | Reads |
|
|
78
|
+
|---|---|
|
|
79
|
+
| `{ "from": "host" }` | Your `getToken(connectionName)` callback |
|
|
80
|
+
| `{ "from": "localStorage", "key": "access_token" }` | `localStorage["access_token"]` |
|
|
81
|
+
| `{ "from": "sessionStorage", "key": "access_token" }` | `sessionStorage["access_token"]` |
|
|
82
|
+
| `{ "from": "cookie", "key": "access_token" }` | The `access_token` cookie |
|
|
83
|
+
|
|
84
|
+
### `getToken`
|
|
85
|
+
|
|
86
|
+
The recommended way: the document says `{ "from": "host" }` and your app supplies the
|
|
87
|
+
token, so the token never sits where document authors can point it.
|
|
88
|
+
|
|
89
|
+
```tsx
|
|
90
|
+
<DashSpecProvider
|
|
91
|
+
getToken={async (connection) => {
|
|
92
|
+
if (connection === "api") return auth.getAccessToken(); // string, null or undefined
|
|
93
|
+
return null;
|
|
94
|
+
}}
|
|
95
|
+
>
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
`getToken` is called for every request, so return a cached token and let your auth
|
|
99
|
+
library refresh it.
|
|
100
|
+
|
|
101
|
+
### `trustedOrigins`
|
|
102
|
+
|
|
103
|
+
Stored credentials (tokens from localStorage, sessionStorage or cookies, `cookie` auth,
|
|
104
|
+
and a token refresh written in the JSON) are sent only to:
|
|
105
|
+
|
|
106
|
+
- the page's own origin,
|
|
107
|
+
- connections your app passes in the `connections` prop (or names in `connectionMap`),
|
|
108
|
+
- origins you list in `trustedOrigins`.
|
|
109
|
+
|
|
110
|
+
```tsx
|
|
111
|
+
<DashSpecProvider trustedOrigins={["https://api.example.com"]}>
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
Otherwise the request fails with a `config` error that names `trustedOrigins`. This
|
|
115
|
+
stops a document from sending a viewer's stored token to a server of its choosing.
|
|
116
|
+
Tokens from `getToken` aren't checked: your callback decides what to return for which
|
|
117
|
+
connection.
|
|
118
|
+
|
|
119
|
+
### Token refresh
|
|
120
|
+
|
|
121
|
+
A `bearer` connection can refresh its token once when a request returns 401, then retry
|
|
122
|
+
the request. Concurrent 401s share one refresh.
|
|
123
|
+
|
|
124
|
+
From your app:
|
|
125
|
+
|
|
126
|
+
```json
|
|
127
|
+
"auth": { "type": "bearer", "token": { "from": "host" }, "refresh": { "from": "host" } }
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
```tsx
|
|
131
|
+
<DashboardRenderer document={doc} getToken={getToken} refreshToken={async (connection) => auth.refresh()} />
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
Or as a request in the JSON, for tokens kept in storage. It must go to the connection's
|
|
135
|
+
own origin, and only runs on a trusted connection. `${storage.<key>}` reads a stored
|
|
136
|
+
value; `save` writes response fields back (`storage key → JSON path`):
|
|
137
|
+
|
|
138
|
+
```json
|
|
139
|
+
"auth": {
|
|
140
|
+
"type": "bearer",
|
|
141
|
+
"token": { "from": "localStorage", "key": "auth_token" },
|
|
142
|
+
"refresh": {
|
|
143
|
+
"path": "/auth/refresh",
|
|
144
|
+
"body": { "refresh": "${storage.refresh_token}" },
|
|
145
|
+
"save": { "auth_token": "$.access" }
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
### Connections from your app
|
|
151
|
+
|
|
152
|
+
Your app can supply or override connections; its values win over the document's, and
|
|
153
|
+
headers are merged. Connections passed this way are trusted.
|
|
154
|
+
|
|
155
|
+
```tsx
|
|
156
|
+
<DashSpecProvider
|
|
157
|
+
connections={{ api: { baseUrl: config.apiUrl } }} // the document's "api" goes to your URL
|
|
158
|
+
connectionMap={{ legacyApi: "api" }} // the document's "legacyApi" uses your "api"
|
|
159
|
+
>
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
## Datasources
|
|
163
|
+
|
|
164
|
+
```json
|
|
165
|
+
"datasources": {
|
|
166
|
+
"orders": {
|
|
167
|
+
"type": "http",
|
|
168
|
+
"connection": "api",
|
|
169
|
+
"path": "/orders",
|
|
170
|
+
"query": { "from": "${filters.period.from}", "to": "${filters.period.to}", "region": "${filters.region}" },
|
|
171
|
+
"omitEmpty": true,
|
|
172
|
+
"select": "results",
|
|
173
|
+
"refresh": { "every": "60s", "whenVisible": true },
|
|
174
|
+
"cache": { "staleTime": "5m" }
|
|
175
|
+
}
|
|
176
|
+
}
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
A panel binds to a datasource with `"data": { "source": "orders" }`. Any template can
|
|
180
|
+
read its state as `${datasources.orders.data}`, `${datasources.orders.status}` (`idle`,
|
|
181
|
+
`loading`, `success`, `error`), `.error`, `.updatedAt` (epoch ms), `.stale` and `.live`.
|
|
182
|
+
|
|
183
|
+
Fields every datasource accepts:
|
|
184
|
+
|
|
185
|
+
| Field | What it does |
|
|
186
|
+
|---|---|
|
|
187
|
+
| `load` | `"onLoad"` (fetch at start), `"lazy"` (fetch when a panel showing it is on screen), `"manual"` (only via the `fetch` action). Without `load` it behaves like `"lazy"` |
|
|
188
|
+
| `refresh` | `{ every, whenVisible, when, onFocus }` ([below](#loading-refresh-and-cache)) |
|
|
189
|
+
| `cache` | `{ staleTime }`: reuse a response for the same request for this long |
|
|
190
|
+
| `transform` | [Transform steps](#transforms) applied to the response |
|
|
191
|
+
| `forEach` | `{ source, as, concurrency }`: one request per row of another datasource (below) |
|
|
192
|
+
| `timeout`, `retry` | As on connections; override them for this datasource |
|
|
193
|
+
| `onError` | `"keepLast"` (default: keep showing the last data, marked stale) or `"clear"` |
|
|
194
|
+
| `omitEmpty` | Leave out query parameters whose value is empty (`null`, `""`, `[]`), so "All" sends nothing |
|
|
195
|
+
| `description` | For people |
|
|
196
|
+
|
|
197
|
+
### `http`
|
|
198
|
+
|
|
199
|
+
| Field | What it does |
|
|
200
|
+
|---|---|
|
|
201
|
+
| `connection` | The connection to use. Required with `path` unless there is exactly one connection (the document's plus your app's); then that one is used |
|
|
202
|
+
| `path` or `url` | Exactly one: a path joined to the connection's `baseUrl`, or a full URL |
|
|
203
|
+
| `method` | `GET` (default), `POST`, `PUT`, `PATCH`, `DELETE` |
|
|
204
|
+
| `query` | Query parameters; arrays repeat the key (`?plant=a&plant=b`) |
|
|
205
|
+
| `headers` | Extra headers |
|
|
206
|
+
| `body` | JSON body (not sent for GET) |
|
|
207
|
+
| `select` | A path into the response to use as data (`"results"`, `"data.items"`) |
|
|
208
|
+
|
|
209
|
+
Values filled into `path` and `url` are URL-encoded, so a filter value like `../admin`
|
|
210
|
+
stays one path segment.
|
|
211
|
+
|
|
212
|
+
```json
|
|
213
|
+
"orderDetail": {
|
|
214
|
+
"type": "http",
|
|
215
|
+
"connection": "api",
|
|
216
|
+
"path": "/orders/${state.selectedOrderId}",
|
|
217
|
+
"load": "lazy"
|
|
218
|
+
}
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
### `graphql`
|
|
222
|
+
|
|
223
|
+
```json
|
|
224
|
+
"topProducts": {
|
|
225
|
+
"type": "graphql",
|
|
226
|
+
"connection": "api",
|
|
227
|
+
"path": "/graphql",
|
|
228
|
+
"query": "query Top($region: String) { topProducts(region: $region) { name sales } }",
|
|
229
|
+
"variables": { "region": "${filters.region}" },
|
|
230
|
+
"select": "topProducts"
|
|
231
|
+
}
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
The renderer POSTs `{ "query": …, "variables": … }` as JSON (`Content-Type: application/json`)
|
|
235
|
+
to the resolved URL, through the same connection, auth and origin rules as `http`.
|
|
236
|
+
`variables` are filled with `${…}` like other request fields; the `query` text is sent as
|
|
237
|
+
written, so its own `$region` syntax is untouched. Params given to the `fetch` action are
|
|
238
|
+
added to `variables`.
|
|
239
|
+
|
|
240
|
+
The data is the response's `data`; `select` is a path inside it (`"topProducts"`, not
|
|
241
|
+
`"data.topProducts"`). A response with a non-empty `errors` list fails with an `http` error
|
|
242
|
+
carrying the first error's message, and any partial `data` is not shown.
|
|
243
|
+
|
|
244
|
+
### `sse` (Server-Sent Events)
|
|
245
|
+
|
|
246
|
+
```json
|
|
247
|
+
"liveOrders": {
|
|
248
|
+
"type": "sse",
|
|
249
|
+
"connection": "api",
|
|
250
|
+
"path": "/orders/stream",
|
|
251
|
+
"event": "order",
|
|
252
|
+
"merge": "append",
|
|
253
|
+
"keep": 200,
|
|
254
|
+
"reconnect": { "maxDelay": "20s" }
|
|
255
|
+
}
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
| Field | What it does |
|
|
259
|
+
|---|---|
|
|
260
|
+
| `connection`, `path` / `url`, `query` | Where to connect |
|
|
261
|
+
| `event` | The SSE event name to listen to (default `message`) |
|
|
262
|
+
| `merge` | `"replace"` (default: each message is the data) or `"append"` (messages accumulate into a list) |
|
|
263
|
+
| `keep` | With `append`, how many items to keep (default 500) |
|
|
264
|
+
| `reconnect` | Default on. After a drop it waits 1 s, 2 s, 4 s… up to `maxDelay` (default `"30s"`), with some jitter, and starts over once data flows. `false` stays closed until the next refresh |
|
|
265
|
+
|
|
266
|
+
Messages that are JSON are parsed. Streams can't send custom headers, so of the auth
|
|
267
|
+
types only `cookie` applies to them (on a trusted connection).
|
|
268
|
+
|
|
269
|
+
### `websocket`
|
|
270
|
+
|
|
271
|
+
Same fields as `sse` except `event`, plus `send`: a JSON value sent on every
|
|
272
|
+
(re)connection, typically a subscribe message. `http(s)` URLs are turned into `ws(s)`.
|
|
273
|
+
|
|
274
|
+
```json
|
|
275
|
+
"ticker": {
|
|
276
|
+
"type": "websocket",
|
|
277
|
+
"url": "wss://stream.example.com/ticks",
|
|
278
|
+
"send": { "subscribe": ["orders", "returns"] },
|
|
279
|
+
"merge": "append",
|
|
280
|
+
"keep": 100,
|
|
281
|
+
"reconnect": true
|
|
282
|
+
}
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
### `static`
|
|
286
|
+
|
|
287
|
+
Data written in the document:
|
|
288
|
+
|
|
289
|
+
```json
|
|
290
|
+
"targets": { "type": "static", "data": [{ "region": "North", "target": 120 }, { "region": "South", "target": 100 }] }
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
### `host`
|
|
294
|
+
|
|
295
|
+
Data your app passes in the `data` prop, by `key`:
|
|
296
|
+
|
|
297
|
+
```json
|
|
298
|
+
"currentUser": { "type": "host", "key": "user" }
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
```tsx
|
|
302
|
+
<DashboardRenderer document={doc} data={{ user: { name: "Ada", stores: ["S1", "S2"] } }} />
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
When `data` or `context` changes (by content, not by object identity), the renderer hands
|
|
306
|
+
the new values to the running dashboard: `host` datasources and everything that reads them
|
|
307
|
+
or `context` update, without a remount. Documents can still only read them. Without React,
|
|
308
|
+
call `runtime.setHostData(data)` and `runtime.setContext(context)`.
|
|
309
|
+
|
|
310
|
+
### Derived (`from`)
|
|
311
|
+
|
|
312
|
+
A datasource with `from` and no `type` is computed from another one, with
|
|
313
|
+
[transform steps](#transforms). It never makes a request, and it updates whenever its
|
|
314
|
+
source does.
|
|
315
|
+
|
|
316
|
+
```json
|
|
317
|
+
"byRegion": {
|
|
318
|
+
"from": "orders",
|
|
319
|
+
"transform": [
|
|
320
|
+
{ "filter": "status != 'cancelled'" },
|
|
321
|
+
{ "groupBy": "region", "sum": "total", "count": "orders" },
|
|
322
|
+
{ "sort": "total", "order": "desc" }
|
|
323
|
+
]
|
|
324
|
+
}
|
|
325
|
+
```
|
|
326
|
+
|
|
327
|
+
### `forEach`: one request per row
|
|
328
|
+
|
|
329
|
+
`forEach` repeats a request once per row of another datasource. The row is available in
|
|
330
|
+
templates under the `as` name. Requests run `concurrency` at a time (default 6, max 32).
|
|
331
|
+
|
|
332
|
+
```json
|
|
333
|
+
"storeStats": {
|
|
334
|
+
"type": "http",
|
|
335
|
+
"connection": "api",
|
|
336
|
+
"path": "/stores/${store.id}/stats",
|
|
337
|
+
"forEach": { "source": "stores", "as": "store", "concurrency": 4 }
|
|
338
|
+
}
|
|
339
|
+
```
|
|
340
|
+
|
|
341
|
+
The data is a list of `{ "store": <row>, "data": <response> }`, or
|
|
342
|
+
`{ "store": <row>, "error": { … } }` for a row whose request failed.
|
|
343
|
+
|
|
344
|
+
### Server-side paging
|
|
345
|
+
|
|
346
|
+
Widgets keep their own state in `panels.<id>.ui`, and datasources can read it. A `Table`
|
|
347
|
+
with `"pagination": { "mode": "server", "totalPath": "count" }` writes `page`,
|
|
348
|
+
`pageSize` and `offset`; with server `search`, `sorting` or `filtering` it also writes
|
|
349
|
+
`search`, `sortKey`, `sortOrder`, `ordering` (`"-field"` for descending) and `filters`.
|
|
350
|
+
|
|
351
|
+
```json
|
|
352
|
+
"orders": {
|
|
353
|
+
"type": "http",
|
|
354
|
+
"connection": "api",
|
|
355
|
+
"path": "/orders",
|
|
356
|
+
"query": {
|
|
357
|
+
"page": "${panels.ordersTable.ui.page ?? 1}",
|
|
358
|
+
"page_size": "${panels.ordersTable.ui.pageSize ?? 20}",
|
|
359
|
+
"search": "${panels.ordersTable.ui.search}",
|
|
360
|
+
"ordering": "${panels.ordersTable.ui.ordering}"
|
|
361
|
+
},
|
|
362
|
+
"omitEmpty": true
|
|
363
|
+
}
|
|
364
|
+
```
|
|
365
|
+
|
|
366
|
+
## Transforms
|
|
367
|
+
|
|
368
|
+
`transform` is a list of steps applied in order to the (selected) response, in the
|
|
369
|
+
browser. Each step is an object whose key names the operation.
|
|
370
|
+
|
|
371
|
+
| Step | Example | What it does |
|
|
372
|
+
|---|---|---|
|
|
373
|
+
| `filter` | `{ "filter": "total > 100 && region == filters.region" }` | Keeps rows where the expression is true. Row fields come first, then the dashboard scope |
|
|
374
|
+
| `map` | `{ "map": { "field": "status", "to": "statusLabel", "values": { "P": "Paid", "L": "Late" }, "default": "Other" } }` | Replaces a field's value by lookup (into `to` if given). Without `default` the original value is kept |
|
|
375
|
+
| `groupBy` + aggregates | `{ "groupBy": ["region", "channel"], "sum": "total", "avg": "margin", "count": "orders" }` | One row per group with the group fields and the aggregates. Aggregates: `sum`, `avg`, `min`, `max`, `first`, `last` (a field or a list), `count` (`true` → field `count`, or a field name). Without `groupBy`, one object for all rows |
|
|
376
|
+
| `pivot` | `{ "pivot": { "rows": "region", "cols": "month", "value": "total" } }` | Turns the values of `cols` into columns holding `value` |
|
|
377
|
+
| `sort` | `{ "sort": ["region", "total"], "order": "desc" }` | Sorts by one or more fields; `order` `"asc"` (default) or `"desc"`. Numbers sort as numbers; empty values go last |
|
|
378
|
+
| `limit` | `{ "limit": 10 }` | Keeps the first N rows |
|
|
379
|
+
| `pick` | `{ "pick": ["region", "total"] }` | Keeps only these fields |
|
|
380
|
+
| `fn` | `{ "fn": "return rows.filter(r => r.total > 0)" }` | Your own code over `rows`, run in the [script sandbox](state-and-events.md#scripts) |
|
|
381
|
+
|
|
382
|
+
Aggregates skip values that aren't numbers; `avg`, `min` and `max` of nothing are `null`,
|
|
383
|
+
`sum` is 0. A step that fails reports `Step N: <message>`. A transform stops with an
|
|
384
|
+
error past 100 000 rows. Very large data belongs in your API.
|
|
385
|
+
|
|
386
|
+
A transform on a fetched datasource re-runs (without a new request) when something it
|
|
387
|
+
reads changes, for example a filter used in a `filter` step.
|
|
388
|
+
|
|
389
|
+
## Loading, refresh and cache
|
|
390
|
+
|
|
391
|
+
- A datasource loads when it is needed: at start for `load: "onLoad"` and for the
|
|
392
|
+
options of filters; when a panel showing it comes on screen (within 200 px); when a
|
|
393
|
+
modal using it opens; when another needed datasource depends on it; and on the `fetch`
|
|
394
|
+
action.
|
|
395
|
+
- It reloads when its resolved request changes: when a filter, state value or other
|
|
396
|
+
datasource that its templates read changes. Only the latest request counts; older ones
|
|
397
|
+
are cancelled.
|
|
398
|
+
- A datasource you only read in templates (`${datasources.summary.data.total}` in a
|
|
399
|
+
title) isn't bound to a panel, so give it `"load": "onLoad"`.
|
|
400
|
+
|
|
401
|
+
`refresh` polls:
|
|
402
|
+
|
|
403
|
+
| Field | What it does |
|
|
404
|
+
|---|---|
|
|
405
|
+
| `every` | Reload this often (`"30s"`). Never faster than 1 s. After failures the wait grows (up to 5×). Paused while the browser tab is hidden |
|
|
406
|
+
| `whenVisible` | Only while a panel showing it is on screen |
|
|
407
|
+
| `when` | Only while this expression is true, e.g. `"includesToday(filters.period)"` |
|
|
408
|
+
| `onFocus` | Also reload when the tab becomes visible again |
|
|
409
|
+
|
|
410
|
+
`cache: { "staleTime": "5m" }` reuses a response for an identical request made within
|
|
411
|
+
that time, in memory, for the life of the dashboard.
|
|
412
|
+
|
|
413
|
+
`onError: "keepLast"` (default) keeps the last good data on screen marked as stale
|
|
414
|
+
(`${datasources.x.stale}`, and the `live` badge turns amber); `"clear"` drops it and
|
|
415
|
+
shows the error.
|
|
416
|
+
|
|
417
|
+
To reload from the dashboard, use the `refresh` action (all loaded datasources, or the
|
|
418
|
+
listed ones); from your app, `ref.current.refresh("orders")` or
|
|
419
|
+
`useDashboardActions(id).refresh()`.
|
|
420
|
+
|
|
421
|
+
## Templates
|
|
422
|
+
|
|
423
|
+
Any string in a datasource, prop or action can contain `${…}` placeholders:
|
|
424
|
+
|
|
425
|
+
```json
|
|
426
|
+
"title": "Orders in ${filters.region} (${fmt.number(datasources.orders.data.count)})"
|
|
427
|
+
```
|
|
428
|
+
|
|
429
|
+
- A string that is exactly one placeholder keeps the value's type:
|
|
430
|
+
`"value": "${filters.period}"` is the range object, `"${state.limit}"` a number.
|
|
431
|
+
- In mixed text, values become strings: `null` and `undefined` become `""`, objects JSON.
|
|
432
|
+
- Filters can be read by their short name: `${region}` is `${filters.region}`.
|
|
433
|
+
|
|
434
|
+
## Expressions
|
|
435
|
+
|
|
436
|
+
`${…}` contains an expression. Bare expressions (no `${}`) are used in `visibleWhen`,
|
|
437
|
+
`when`, `refresh.when`, `optionsFilter`, transform `filter` steps and Table
|
|
438
|
+
`rowMutedWhen` / column `tone`.
|
|
439
|
+
|
|
440
|
+
```json
|
|
441
|
+
"visibleWhen": "view == 'detail' && has(context.roles, 'manager')"
|
|
442
|
+
```
|
|
443
|
+
|
|
444
|
+
The language is a safe subset of JavaScript: no assignment, no `new`, no function
|
|
445
|
+
bodies, no globals, no prototype access. It can only call the helpers below.
|
|
446
|
+
|
|
447
|
+
| Syntax | Examples |
|
|
448
|
+
|---|---|
|
|
449
|
+
| Literals | `42`, `'North'`, `"North"`, `true`, `null`, `[1, 2]`, `{ a: 1 }` |
|
|
450
|
+
| Names and members | `filters.region`, `row['unit price']`, `rows[0]`, `a?.b` |
|
|
451
|
+
| Arithmetic | `+ - * / %`, unary `-` and `!` |
|
|
452
|
+
| Comparison | `== != === !==` (strict, except `null == undefined`), `< <= > >=` |
|
|
453
|
+
| Logic | `&&`, `\|\|`, `??`, `cond ? a : b` |
|
|
454
|
+
| Helper calls | `len(rows)`, `fmt.number(total, 1)` |
|
|
455
|
+
|
|
456
|
+
Reading a member of `null` or `undefined` gives `undefined` instead of an error.
|
|
457
|
+
|
|
458
|
+
### What expressions can read
|
|
459
|
+
|
|
460
|
+
| Name | What it is |
|
|
461
|
+
|---|---|
|
|
462
|
+
| `filters.<name>` (or just `<name>`) | Filter values. A `DateRange` is `{ from, to, preset }` with `YYYY-MM-DD` dates |
|
|
463
|
+
| `<your key>`, `state.<your key>` | Your own state (`spec.state`). `state` is the whole state tree, so `state.filters.region` works too |
|
|
464
|
+
| `datasources.<id>` | `{ status, data, error, updatedAt, stale, live }` |
|
|
465
|
+
| `panels.<id>` | A panel's state: `selection`, `hover`, `drill`, `controls`, `hiddenSeries`, `ui`, `hidden` |
|
|
466
|
+
| `panel` | The current panel's state (in its props and actions); `panel.controls.<name>` reads its panel controls |
|
|
467
|
+
| `view` | The current view name |
|
|
468
|
+
| `modal` | The open modal, `{ id, args }`; read arguments as `modal.args.<name>` |
|
|
469
|
+
| `highlight.<group>` | The hovered value of a highlight group |
|
|
470
|
+
| `context.<…>` | What your app passes in the `context` prop |
|
|
471
|
+
| `event` | In actions: the event (`event.datum`, `event.value`, `event.x`, `event.series`, `event.index`…) |
|
|
472
|
+
| `drill.<level>` | The values picked at each drill level of the panel |
|
|
473
|
+
| `parent` | The parent node's data (nested nodes) |
|
|
474
|
+
| `item`, `index` | Inside a Repeater: the row and its position. In `optionsFilter`: the option's row |
|
|
475
|
+
| `row` | Table column `template`, `href`, `tone` and `rowMutedWhen`: the row |
|
|
476
|
+
| `<field>` | In a transform `filter` step: the row's fields |
|
|
477
|
+
|
|
478
|
+
### Helpers
|
|
479
|
+
|
|
480
|
+
| Helper | Returns |
|
|
481
|
+
|---|---|
|
|
482
|
+
| `has(list, value)` | Whether a list (or string) contains a value |
|
|
483
|
+
| `len(value)` | Length of a list or string, or the number of keys of an object |
|
|
484
|
+
| `round(n, decimals = 0)` | `n` rounded |
|
|
485
|
+
| `min(...values)`, `max(...values)` | Smallest / largest; lists are flattened |
|
|
486
|
+
| `sum(list, key?)` | Sum of a list, or of `key` in each row |
|
|
487
|
+
| `lookup(list, key, value)` | The first row whose `key` equals `value` |
|
|
488
|
+
| `join(list, sep = ",")` | The items joined as text |
|
|
489
|
+
| `lower(text)`, `upper(text)` | Lower / upper case |
|
|
490
|
+
| `now()` | Current time, epoch ms |
|
|
491
|
+
| `ago(duration)` | Epoch ms `duration` ago: `ago('8h')` |
|
|
492
|
+
| `dayStart()` | Start of today's plant day, epoch ms |
|
|
493
|
+
| `today()` | Today's date, `YYYY-MM-DD` |
|
|
494
|
+
| `includesToday(range)` | Whether a `{ from, to }` range contains today |
|
|
495
|
+
| `granularityFor(range)` | `"heat"` (≤ 1 day), `"day"` (≤ 31), `"week"` (≤ 92), `"month"` (≤ 730) or `"year"` |
|
|
496
|
+
| `fmt.number(v, decimals?)` | `1,234.5` in the dashboard's locale |
|
|
497
|
+
| `fmt.compact(v)` | `12.3K` |
|
|
498
|
+
| `fmt.percent(v, decimals = 0)` | `42.5%` (`v` is already a percentage) |
|
|
499
|
+
| `fmt.duration(seconds)` | `1 hr 1 min` |
|
|
500
|
+
| `fmt.date(v, style = "date")` | A date; `style` `"date"`, `"datetime"` or `"time"`, in the dashboard's time zone |
|
|
501
|
+
| `fmt.ago(v)` | `just now`, `3 min ago`, `2 hr ago`, `4 days ago` |
|
|
502
|
+
| `t.<key>` | `display.translations` text for the active locale, else the first locale's, else the key ([JSON format](json-format.md#specdisplay)) |
|
|
503
|
+
|
|
504
|
+
"Today" follows the document's `display.timeZone` (IANA, default: the viewer's) and
|
|
505
|
+
`display.dayStartsAt` (`"HH:mm"`): with `"06:00"`, 05:00 still belongs to yesterday.
|
|
506
|
+
Date presets (`today`, `last7days`, …) follow the same rules.
|
|
507
|
+
|
|
508
|
+
## Custom datasource types
|
|
509
|
+
|
|
510
|
+
Add your own `type` (a data warehouse client, a cache, a native bridge) with the
|
|
511
|
+
`datasourceTypes` prop. A type has a `type` name and either `fetch` (one result) or
|
|
512
|
+
`subscribe` (a stream):
|
|
513
|
+
|
|
514
|
+
```ts
|
|
515
|
+
import type { DatasourceType } from "@dashspec/renderer";
|
|
516
|
+
|
|
517
|
+
const warehouse: DatasourceType = {
|
|
518
|
+
type: "acme.warehouse",
|
|
519
|
+
async fetch(ds, { signal, tree }) {
|
|
520
|
+
const region = tree.filters.region;
|
|
521
|
+
return acmeWarehouse.query(String(ds.table), { region }, { signal });
|
|
522
|
+
},
|
|
523
|
+
};
|
|
524
|
+
|
|
525
|
+
const prices: DatasourceType = {
|
|
526
|
+
type: "acme.prices",
|
|
527
|
+
subscribe(ds, { push }) {
|
|
528
|
+
const off = acmePriceFeed.on(String(ds.symbol), (tick) => push(tick));
|
|
529
|
+
return off; // called when the stream stops
|
|
530
|
+
},
|
|
531
|
+
};
|
|
532
|
+
```
|
|
533
|
+
|
|
534
|
+
```tsx
|
|
535
|
+
<DashSpecProvider datasourceTypes={[warehouse, prices]}>
|
|
536
|
+
```
|
|
537
|
+
|
|
538
|
+
```json
|
|
539
|
+
"sales": { "type": "acme.warehouse", "table": "sales_daily", "query": { "region": "${filters.region}" } }
|
|
540
|
+
```
|
|
541
|
+
|
|
542
|
+
`fetch(ds, ctx)` receives the datasource as written (templates **not** filled) and
|
|
543
|
+
`{ http, request, signal, tree }`: `request(r)` sends a request through the dashboard's
|
|
544
|
+
HTTP client (with connections and auth), `tree` is the current
|
|
545
|
+
[state tree](state-and-events.md#the-state-tree). `subscribe(ds, { http, push, tree })`
|
|
546
|
+
calls `push(data)` for each update and returns a stop function; it handles its own
|
|
547
|
+
reconnects.
|
|
548
|
+
|
|
549
|
+
The datasource reloads when its built-in request fields (`connection`, `url`, `path`,
|
|
550
|
+
`method`, `query`, `headers`, `body`, `timeout`, `retry`, `omitEmpty`) resolve to new
|
|
551
|
+
values, so put the templates that should trigger a reload in `query`. The common fields
|
|
552
|
+
(`transform`, `refresh`, `cache`, `onError`, …) work as for built-in types.
|
|
553
|
+
|
|
554
|
+
## Errors
|
|
555
|
+
|
|
556
|
+
Every failed request becomes a `DataError` with a `code`:
|
|
557
|
+
|
|
558
|
+
| Code | Meaning |
|
|
559
|
+
|---|---|
|
|
560
|
+
| `network` | The request didn't reach the server, or a live stream closed |
|
|
561
|
+
| `timeout` | No answer within the timeout |
|
|
562
|
+
| `http` | A non-2xx status; `status` is set and the message uses the API's `detail` field when there is one |
|
|
563
|
+
| `parse` | The response said JSON but wasn't |
|
|
564
|
+
| `too-large` | The response is bigger than `maxResponseBytes` (10 MB) |
|
|
565
|
+
| `config` | A mistake in the setup: unknown connection, no `baseUrl` for this host, a template that failed, stored credentials for an untrusted origin |
|
|
566
|
+
| `aborted` | The request was cancelled (a newer one replaced it) |
|
|
567
|
+
|
|
568
|
+
A derived datasource whose transform fails has the code `transform`.
|
|
569
|
+
|
|
570
|
+
The error shows in the panels that use the datasource (customise with `messages.error`,
|
|
571
|
+
`renderError` or a design system's `ErrorState`), is readable as
|
|
572
|
+
`${datasources.<id>.error}`, and reaches your `onError`:
|
|
573
|
+
|
|
574
|
+
```tsx
|
|
575
|
+
<DashboardRenderer
|
|
576
|
+
document={doc}
|
|
577
|
+
onError={(e) => {
|
|
578
|
+
// { code: "http", message: "503 Service Unavailable", status: 503, datasource: "orders" }
|
|
579
|
+
if (e.datasource) metrics.increment("dashboard.datasource_error", { code: e.code });
|
|
580
|
+
}}
|
|
581
|
+
/>
|
|
582
|
+
```
|