@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/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
+ ```