@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,227 @@
|
|
|
1
|
+
# Design systems
|
|
2
|
+
|
|
3
|
+
A dashboard should look like the rest of your app. DashSpec draws its own widgets and
|
|
4
|
+
controls by default, and lets you bring any design system (MUI, Ant Design, Chakra,
|
|
5
|
+
your in-house library) in three layers:
|
|
6
|
+
|
|
7
|
+
1. **Widgets**: your components as dashboard widgets (`acme.DataGrid`).
|
|
8
|
+
2. **Controls**: your components for the controls DashSpec draws itself: the filter
|
|
9
|
+
inputs and the empty, error and loading states.
|
|
10
|
+
3. **Theme**: your colours, fonts and radii as DashSpec tokens.
|
|
11
|
+
|
|
12
|
+
`defineDesignSystem` packages the three, and the renderer (or a `DashSpecProvider`)
|
|
13
|
+
takes a list of them.
|
|
14
|
+
|
|
15
|
+
## `defineDesignSystem`
|
|
16
|
+
|
|
17
|
+
```tsx
|
|
18
|
+
import { createTheme, defineDesignSystem, wrapComponent } from "@dashspec/renderer";
|
|
19
|
+
import { z } from "zod";
|
|
20
|
+
import { AcmeDataGrid, AcmeSelect, AcmeDatePicker, AcmeSpinner, AcmeEmpty } from "@acme/ui";
|
|
21
|
+
|
|
22
|
+
export const acme = defineDesignSystem({
|
|
23
|
+
name: "Acme",
|
|
24
|
+
widgets: [
|
|
25
|
+
wrapComponent(AcmeDataGrid, {
|
|
26
|
+
kind: "acme.DataGrid",
|
|
27
|
+
meta: { label: "Data grid" },
|
|
28
|
+
schema: z.object({ title: z.string().optional(), columns: z.array(z.string()).default([]) }),
|
|
29
|
+
mapProps: ({ spec, data }) => ({ columns: spec.columns, rows: Array.isArray(data) ? data : [] }),
|
|
30
|
+
events: { onRowClick: "rowClick" },
|
|
31
|
+
}),
|
|
32
|
+
],
|
|
33
|
+
ui: {
|
|
34
|
+
Select: ({ label, options, value, onChange }) => (
|
|
35
|
+
<AcmeSelect
|
|
36
|
+
label={label}
|
|
37
|
+
value={value as string}
|
|
38
|
+
onChange={(v: string) => onChange(v)}
|
|
39
|
+
items={options.map((o) => ({ id: String(o.value), text: o.label }))}
|
|
40
|
+
/>
|
|
41
|
+
),
|
|
42
|
+
Date: ({ label, value, onChange, min, max }) => (
|
|
43
|
+
<AcmeDatePicker label={label} value={value} min={min} max={max} onChange={onChange} />
|
|
44
|
+
),
|
|
45
|
+
Loading: () => <AcmeSpinner />,
|
|
46
|
+
EmptyState: ({ message }) => <AcmeEmpty text={message ?? "No data"} />,
|
|
47
|
+
},
|
|
48
|
+
theme: createTheme({
|
|
49
|
+
name: "acme",
|
|
50
|
+
colors: { primary: "#4f46e5", series: ["#4f46e5", "#06b6d4", "#f59e0b", "#ef4444"] },
|
|
51
|
+
font: { family: "'Acme Sans', system-ui, sans-serif" },
|
|
52
|
+
radius: 10,
|
|
53
|
+
}),
|
|
54
|
+
});
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
`DesignSystem`:
|
|
58
|
+
|
|
59
|
+
| Field | Type | What it is |
|
|
60
|
+
|---|---|---|
|
|
61
|
+
| `name` | `string` | Required. Widgets without `meta.category` are grouped under it in editor palettes |
|
|
62
|
+
| `widgets` | `AnyWidgetDefinition[]` | Its components as widgets. Kinds must be namespaced (`acme.DataGrid`). See [Widgets](widgets.md#write-your-own-widget) |
|
|
63
|
+
| `ui` | `UIComponents` | Its controls for DashSpec's own UI (below) |
|
|
64
|
+
| `theme` | `Theme` | Its look, used when the host passes no `theme` prop. See [Theming](theming.md) |
|
|
65
|
+
|
|
66
|
+
## Register it
|
|
67
|
+
|
|
68
|
+
Once for the whole app, with a provider:
|
|
69
|
+
|
|
70
|
+
```tsx
|
|
71
|
+
import { DashSpecProvider } from "@dashspec/renderer";
|
|
72
|
+
import { acme } from "./acme-design-system";
|
|
73
|
+
|
|
74
|
+
export function Root() {
|
|
75
|
+
return (
|
|
76
|
+
<DashSpecProvider designSystems={[acme]}>
|
|
77
|
+
<App />
|
|
78
|
+
</DashSpecProvider>
|
|
79
|
+
);
|
|
80
|
+
}
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
or per dashboard:
|
|
84
|
+
|
|
85
|
+
```tsx
|
|
86
|
+
<DashboardRenderer document={doc} designSystems={[acme]} />
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Documents then use the widgets by kind:
|
|
90
|
+
|
|
91
|
+
```json
|
|
92
|
+
"orders": { "kind": "acme.DataGrid", "spec": { "title": "Orders", "data": { "source": "orders" }, "columns": ["id", "total"] } }
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
## The `ui` controls
|
|
96
|
+
|
|
97
|
+
Each control you supply replaces DashSpec's own, everywhere it appears: the filter bar,
|
|
98
|
+
`Filter` widgets on the canvas, and panel controls. Controls you leave out stay
|
|
99
|
+
DashSpec's. Each receives exactly the props below.
|
|
100
|
+
|
|
101
|
+
Every filter control gets `name` (the filter's name, for forms and test ids) and
|
|
102
|
+
`label` (`string | undefined`).
|
|
103
|
+
|
|
104
|
+
| Control | Used for | Props besides `name`, `label` |
|
|
105
|
+
|---|---|---|
|
|
106
|
+
| `Select` | `Select` filters | `options: Option[]`, `value: unknown`, `onChange(value)`, `stepper?: boolean` (show previous / next buttons) |
|
|
107
|
+
| `MultiSelect` | `MultiSelect` filters | `options: Option[]`, `value: unknown[]`, `onChange(values: unknown[])` |
|
|
108
|
+
| `Date` | `Date` filters | `value: string` (`YYYY-MM-DD`), `onChange(value: string)`, `min?`, `max?`, `stepper?` |
|
|
109
|
+
| `DateRange` | `DateRange` filters | `value: { from?, to?, preset? }`, `onChange(value)`, `presets: { value, label, from, to }[]`, `min?`, `max?`, `maxDays?` |
|
|
110
|
+
| `Search` | `Search` filters | `value: string`, `onChange(value: string)`, `placeholder?`. Call `onChange` on every keystroke: DashSpec debounces it |
|
|
111
|
+
| `Toggle` | `Toggle` filters | `value: boolean`, `onChange(value: boolean)` |
|
|
112
|
+
| `Chips` | `Chips` filters | `options: Option[]`, `value: unknown`, `onChange(value)`, `multiple: boolean` |
|
|
113
|
+
| `EmptyState` | A panel with no data | `panel: string`, `message?: string` |
|
|
114
|
+
| `ErrorState` | A panel whose data failed | `panel: string`, `message?: string` |
|
|
115
|
+
| `Loading` | A panel waiting for data | `panel: string`, `message?: string` |
|
|
116
|
+
| `filters` | Your own filter kinds | A map of namespaced kind → component (below) |
|
|
117
|
+
|
|
118
|
+
`Option` is `{ value: unknown; label: string; count?: number }`. A `DateRange` value
|
|
119
|
+
has the dates as `YYYY-MM-DD` strings; when the viewer picks a preset, pass `preset`
|
|
120
|
+
too, e.g. `{ from: "2026-11-01", to: "2026-11-07", preset: "last7days" }` (each entry of
|
|
121
|
+
`presets` gives you its `from` and `to`).
|
|
122
|
+
|
|
123
|
+
A `DateRange` control in practice:
|
|
124
|
+
|
|
125
|
+
```tsx
|
|
126
|
+
import type { UIDateRangeProps } from "@dashspec/renderer";
|
|
127
|
+
|
|
128
|
+
function AcmeDateRange({ label, value, onChange, presets }: UIDateRangeProps) {
|
|
129
|
+
return (
|
|
130
|
+
<AcmeRangePicker
|
|
131
|
+
label={label}
|
|
132
|
+
start={value.from}
|
|
133
|
+
end={value.to}
|
|
134
|
+
shortcuts={presets.map((p) => ({ id: p.value, text: p.label }))}
|
|
135
|
+
onShortcut={(id: string) => {
|
|
136
|
+
const p = presets.find((x) => x.value === id);
|
|
137
|
+
if (p) onChange({ from: p.from, to: p.to, preset: p.value });
|
|
138
|
+
}}
|
|
139
|
+
onChange={(start: string, end: string) => onChange({ from: start, to: end, preset: "custom" })}
|
|
140
|
+
/>
|
|
141
|
+
);
|
|
142
|
+
}
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
The `renderEmpty`, `renderError` and `renderLoading` props of `DashboardRenderer` win
|
|
146
|
+
over `EmptyState`, `ErrorState` and `Loading` when both are given.
|
|
147
|
+
|
|
148
|
+
## Custom filter kinds
|
|
149
|
+
|
|
150
|
+
A filter kind of your own (a shift picker, a customer search backed by your API) is a
|
|
151
|
+
namespaced `kind` in the document plus a component under `ui.filters`:
|
|
152
|
+
|
|
153
|
+
```json
|
|
154
|
+
"variables": [
|
|
155
|
+
{ "name": "shift", "kind": "acme.ShiftPicker", "label": "Shift", "default": "day", "x-acme-shifts": ["day", "night"] }
|
|
156
|
+
]
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
```tsx
|
|
160
|
+
import type { UICustomFilterProps } from "@dashspec/renderer";
|
|
161
|
+
|
|
162
|
+
function ShiftPicker({ label, value, onChange, config }: UICustomFilterProps) {
|
|
163
|
+
const shifts = (config["x-acme-shifts"] as string[] | undefined) ?? ["day", "night"];
|
|
164
|
+
return (
|
|
165
|
+
<AcmeSegmented
|
|
166
|
+
label={label}
|
|
167
|
+
value={value as string}
|
|
168
|
+
options={shifts}
|
|
169
|
+
onChange={(v: string) => onChange(v)}
|
|
170
|
+
/>
|
|
171
|
+
);
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
export const acme = defineDesignSystem({
|
|
175
|
+
name: "Acme",
|
|
176
|
+
ui: { filters: { "acme.ShiftPicker": ShiftPicker } },
|
|
177
|
+
});
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
`config` is the filter's whole definition from the JSON, so put your own settings in
|
|
181
|
+
`x-` fields (they are kept and never warned about). The value is stored like any filter
|
|
182
|
+
(`${filters.shift}`), starts at `default` (or `null`), and is written to the URL as text.
|
|
183
|
+
A namespaced filter kind with no registered component renders nothing.
|
|
184
|
+
|
|
185
|
+
## Combine several
|
|
186
|
+
|
|
187
|
+
Pass several design systems; they combine:
|
|
188
|
+
|
|
189
|
+
```tsx
|
|
190
|
+
<DashSpecProvider designSystems={[mui, acmeCharts, acmeOverrides]}>
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
- **Widgets**: all of them. Two systems can't register the same kind.
|
|
194
|
+
- **Controls**: later systems win, control by control. `ui.filters` merge by kind.
|
|
195
|
+
- **Theme**: the last system that has one.
|
|
196
|
+
- Then the renderer's own `ui` prop wins over all of them, control by control, and its
|
|
197
|
+
`theme` prop wins over their theme.
|
|
198
|
+
|
|
199
|
+
`combineDesignSystems(list)` returns the combined `{ widgets, ui, theme }` if you need it
|
|
200
|
+
yourself.
|
|
201
|
+
|
|
202
|
+
Providers also nest: an inner `DashSpecProvider` adds its design systems after the
|
|
203
|
+
outer one's (see [merge rules](api.md#dashspecprovider)).
|
|
204
|
+
|
|
205
|
+
## Point built-in kinds at your components
|
|
206
|
+
|
|
207
|
+
Documents written with built-in kinds (`"kind": "Table"`) can switch to your widget
|
|
208
|
+
without being edited, with `aliases`:
|
|
209
|
+
|
|
210
|
+
```tsx
|
|
211
|
+
const AcmeTable = wrapComponent(AcmeDataGrid, {
|
|
212
|
+
kind: "acme.Table",
|
|
213
|
+
implements: "table", // the same role as the built-in Table
|
|
214
|
+
meta: { label: "Acme table" },
|
|
215
|
+
mapProps: ({ spec, data }) => ({ columns: spec.columns, rows: data }),
|
|
216
|
+
});
|
|
217
|
+
|
|
218
|
+
<DashSpecProvider widgets={[AcmeTable]} aliases={{ Table: "acme.Table" }}>
|
|
219
|
+
<App />
|
|
220
|
+
</DashSpecProvider>;
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
Your widget then receives the built-in's JSON props (`columns`, `search`, …) in
|
|
224
|
+
`spec`, so map the ones you support. If both widgets declare `implements`, the roles
|
|
225
|
+
must match or the renderer throws; this keeps an alias from turning a table into a
|
|
226
|
+
chart. Your own kind can't simply be named `Table`: host kinds are always namespaced
|
|
227
|
+
and can't replace a built-in, only alias it.
|
|
@@ -0,0 +1,242 @@
|
|
|
1
|
+
# Getting started
|
|
2
|
+
|
|
3
|
+
`@dashspec/renderer` draws a complete, interactive dashboard from one JSON document:
|
|
4
|
+
the grid, the filter bar, the data fetching, the widgets, the events. You give it the
|
|
5
|
+
document; it does the rest.
|
|
6
|
+
|
|
7
|
+
This page takes you from `npm install` to a dashboard loaded from your API.
|
|
8
|
+
|
|
9
|
+
## Install
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
npm install @dashspec/renderer react react-dom zod
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
`react`, `react-dom` (18.3 or 19) and `zod` (3.23 or newer 3.x) are peer dependencies,
|
|
16
|
+
so your app owns their versions. Everything else (charts, grid, the script sandbox) is
|
|
17
|
+
bundled with the package.
|
|
18
|
+
|
|
19
|
+
There is no stylesheet to import: the renderer injects its own CSS, scoped under a
|
|
20
|
+
`.ds-root` element, and reads colours and spacing from `--ds-*` CSS variables (see
|
|
21
|
+
[Theming](theming.md)).
|
|
22
|
+
|
|
23
|
+
The package has three entry points:
|
|
24
|
+
|
|
25
|
+
| Import from | What it holds | Runs on |
|
|
26
|
+
|---|---|---|
|
|
27
|
+
| `@dashspec/renderer` | `DashboardRenderer`, `DashSpecProvider`, widgets, design systems, theme, hooks, and everything in `/core` | Browser (marked `"use client"`) |
|
|
28
|
+
| `@dashspec/renderer/core` | `loadDocument`, `validateDocument`, the schema, expressions, HTTP helpers, transforms. No React | Browser, Node, edge, workers |
|
|
29
|
+
| `@dashspec/renderer/sandbox` | `createSandboxRunner`, the QuickJS script sandbox | Browser |
|
|
30
|
+
|
|
31
|
+
## Your first dashboard
|
|
32
|
+
|
|
33
|
+
A document has an `apiVersion`, a `kind`, `metadata` and a `spec`. The `spec` needs at
|
|
34
|
+
least `panels` (the widgets) and `layouts` (where they go on the grid).
|
|
35
|
+
|
|
36
|
+
```json
|
|
37
|
+
{
|
|
38
|
+
"apiVersion": "dashspec.dev/v2",
|
|
39
|
+
"kind": "Dashboard",
|
|
40
|
+
"metadata": { "key": "sales-overview", "name": "Sales overview" },
|
|
41
|
+
"spec": {
|
|
42
|
+
"display": { "title": "Sales overview" },
|
|
43
|
+
"datasources": {
|
|
44
|
+
"sales": {
|
|
45
|
+
"type": "static",
|
|
46
|
+
"data": [
|
|
47
|
+
{ "region": "North", "orders": 120 },
|
|
48
|
+
{ "region": "South", "orders": 95 },
|
|
49
|
+
{ "region": "West", "orders": 140 }
|
|
50
|
+
]
|
|
51
|
+
}
|
|
52
|
+
},
|
|
53
|
+
"panels": {
|
|
54
|
+
"total": {
|
|
55
|
+
"kind": "Kpi",
|
|
56
|
+
"spec": { "title": "Orders this week", "data": { "value": 355 }, "unit": "orders", "target": 300 }
|
|
57
|
+
},
|
|
58
|
+
"byRegion": {
|
|
59
|
+
"kind": "BarChart",
|
|
60
|
+
"spec": { "title": "Orders by region", "data": { "source": "sales" }, "x": "region", "y": "orders" }
|
|
61
|
+
}
|
|
62
|
+
},
|
|
63
|
+
"layouts": [
|
|
64
|
+
{
|
|
65
|
+
"items": [
|
|
66
|
+
{ "panel": "total", "x": 0, "y": 0, "w": 4, "h": 5 },
|
|
67
|
+
{ "panel": "byRegion", "x": 4, "y": 0, "w": 8, "h": 9 }
|
|
68
|
+
]
|
|
69
|
+
}
|
|
70
|
+
]
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Render it:
|
|
76
|
+
|
|
77
|
+
```tsx
|
|
78
|
+
import { DashboardRenderer } from "@dashspec/renderer";
|
|
79
|
+
import salesOverview from "./sales-overview.json";
|
|
80
|
+
|
|
81
|
+
export function SalesPage() {
|
|
82
|
+
return <DashboardRenderer document={salesOverview} />;
|
|
83
|
+
}
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
That is the whole integration. `document` is the only required prop.
|
|
87
|
+
|
|
88
|
+
What happened:
|
|
89
|
+
|
|
90
|
+
- `datasources.sales` is a `static` datasource: its rows are in the document.
|
|
91
|
+
- `byRegion` binds to it with `"data": { "source": "sales" }` and plots `region` against `orders`.
|
|
92
|
+
- `total` binds to a fixed value with `"data": { "value": 355 }`.
|
|
93
|
+
- The grid has 12 columns by default; each layout item places a panel with `x`, `y`, `w`, `h`.
|
|
94
|
+
|
|
95
|
+
## Load the document from your API
|
|
96
|
+
|
|
97
|
+
Documents usually live in a database, not in your bundle. Fetch the JSON however you
|
|
98
|
+
like and pass it in; render nothing (or a skeleton) until it arrives.
|
|
99
|
+
|
|
100
|
+
```tsx
|
|
101
|
+
import { useEffect, useState } from "react";
|
|
102
|
+
import { DashboardRenderer } from "@dashspec/renderer";
|
|
103
|
+
|
|
104
|
+
export function DashboardPage({ dashboardKey }: { dashboardKey: string }) {
|
|
105
|
+
const [doc, setDoc] = useState<unknown>(null);
|
|
106
|
+
|
|
107
|
+
useEffect(() => {
|
|
108
|
+
let cancelled = false;
|
|
109
|
+
fetch(`/api/dashboards/${encodeURIComponent(dashboardKey)}`)
|
|
110
|
+
.then((r) => r.json())
|
|
111
|
+
.then((json) => !cancelled && setDoc(json));
|
|
112
|
+
return () => {
|
|
113
|
+
cancelled = true;
|
|
114
|
+
};
|
|
115
|
+
}, [dashboardKey]);
|
|
116
|
+
|
|
117
|
+
if (!doc) return <p>Loading…</p>;
|
|
118
|
+
return <DashboardRenderer id={dashboardKey} document={doc} />;
|
|
119
|
+
}
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
`document` is typed `unknown` on purpose: the renderer validates whatever it receives.
|
|
123
|
+
|
|
124
|
+
The dashboard's own data usually comes from your API too. Declare a connection in the
|
|
125
|
+
document and give the renderer the token at runtime. Tokens never go in the JSON:
|
|
126
|
+
|
|
127
|
+
```json
|
|
128
|
+
"connections": {
|
|
129
|
+
"api": {
|
|
130
|
+
"baseUrl": "https://api.example.com/v1",
|
|
131
|
+
"auth": { "type": "bearer", "token": { "from": "host" } }
|
|
132
|
+
}
|
|
133
|
+
},
|
|
134
|
+
"datasources": {
|
|
135
|
+
"sales": { "type": "http", "connection": "api", "path": "/sales/by-region" }
|
|
136
|
+
}
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
```tsx
|
|
140
|
+
<DashboardRenderer
|
|
141
|
+
document={doc}
|
|
142
|
+
getToken={async (connection) => (connection === "api" ? await auth.getAccessToken() : null)}
|
|
143
|
+
/>
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
[Data](data.md) covers connections, auth, refresh and every datasource type.
|
|
147
|
+
|
|
148
|
+
## Validate with `loadDocument`
|
|
149
|
+
|
|
150
|
+
The renderer validates every document before drawing it. To check a document yourself
|
|
151
|
+
(when saving it, in CI, on a server), call `loadDocument` from the React-free `/core`
|
|
152
|
+
entry. It migrates older formats, then validates:
|
|
153
|
+
|
|
154
|
+
```ts
|
|
155
|
+
import { loadDocument } from "@dashspec/renderer/core";
|
|
156
|
+
|
|
157
|
+
const result = loadDocument(json);
|
|
158
|
+
|
|
159
|
+
if (result.status === "valid") {
|
|
160
|
+
save(result.document); // typed as Dashboard
|
|
161
|
+
} else {
|
|
162
|
+
for (const p of result.problems.filter((p) => p.severity === "error")) {
|
|
163
|
+
console.error(`${p.path}: ${p.message} (${p.code})`);
|
|
164
|
+
}
|
|
165
|
+
}
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
Each problem is `{ severity, path, code, message }`. For example, a typo and a panel
|
|
169
|
+
that doesn't exist give:
|
|
170
|
+
|
|
171
|
+
```json
|
|
172
|
+
[
|
|
173
|
+
{
|
|
174
|
+
"severity": "warning",
|
|
175
|
+
"path": "spec.panels.total.visibleWen",
|
|
176
|
+
"code": "unknown-field",
|
|
177
|
+
"message": "\"visibleWen\" isn't a known field here; it is ignored (did you mean \"visibleWhen\"?)"
|
|
178
|
+
},
|
|
179
|
+
{
|
|
180
|
+
"severity": "error",
|
|
181
|
+
"path": "spec.layouts.0.items.0.panel",
|
|
182
|
+
"code": "unknown-panel",
|
|
183
|
+
"message": "No panel \"nope\""
|
|
184
|
+
}
|
|
185
|
+
]
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
Warnings never stop a dashboard from rendering. Unknown fields and unknown choice values
|
|
189
|
+
are warnings, so a document written for a newer renderer still opens on an older one.
|
|
190
|
+
Only errors make a document invalid. The full list of codes is in the
|
|
191
|
+
[API reference](api.md#problem-codes).
|
|
192
|
+
|
|
193
|
+
`loadDocument` from `/core` checks the document's structure and the links between its
|
|
194
|
+
parts. It checks each panel's widget props only when you pass `widgets`; the renderer
|
|
195
|
+
always passes its registered widgets, so it also reports bad widget props.
|
|
196
|
+
|
|
197
|
+
## What viewers see when a document is invalid
|
|
198
|
+
|
|
199
|
+
When a document has errors, the renderer doesn't throw and doesn't break your page. It
|
|
200
|
+
shows, in place of the dashboard:
|
|
201
|
+
|
|
202
|
+
> **This dashboard can't be shown: its JSON has 2 problem(s).**
|
|
203
|
+
> - `spec.layouts.0.items.0.panel` No panel "nope"
|
|
204
|
+
> - `spec.layouts.0.items.0` x + w = 20 is wider than the 12-column grid
|
|
205
|
+
|
|
206
|
+
(up to 20 errors, each with its path). To show your own message instead, pass
|
|
207
|
+
`renderError`; for an invalid document it receives `{ code: "invalid", message }` with
|
|
208
|
+
the first problem's message:
|
|
209
|
+
|
|
210
|
+
```tsx
|
|
211
|
+
<DashboardRenderer
|
|
212
|
+
document={doc}
|
|
213
|
+
renderError={(error, panel) =>
|
|
214
|
+
panel ? <MyPanelError message={error.message} /> : <MyPageError message={error.message} />
|
|
215
|
+
}
|
|
216
|
+
/>
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
Smaller failures stay local:
|
|
220
|
+
|
|
221
|
+
- A panel whose `kind` isn't registered shows "Unknown widget" and the rest renders.
|
|
222
|
+
- A datasource that fails shows its error in the panels that use it.
|
|
223
|
+
- A widget that throws shows "This panel could not be shown" in that panel only.
|
|
224
|
+
- A widget prop that fails its schema is dropped; the widget keeps its other props.
|
|
225
|
+
|
|
226
|
+
Report these to your monitoring with `onError`:
|
|
227
|
+
|
|
228
|
+
```tsx
|
|
229
|
+
<DashboardRenderer document={doc} onError={(e) => monitoring.report(e.code, e.message, e)} />
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
## Next steps
|
|
233
|
+
|
|
234
|
+
- [Widgets](widgets.md): the 30 built-in widgets, nesting, and writing your own.
|
|
235
|
+
- [Data](data.md): connections, auth, datasources, templates and expressions.
|
|
236
|
+
- [State and events](state-and-events.md): clicks, actions, filters, and driving a dashboard from your app.
|
|
237
|
+
- [Design systems](design-systems.md): use your own components and controls.
|
|
238
|
+
- [Theming](theming.md): colours, fonts, dark mode.
|
|
239
|
+
- [Server rendering](server-rendering.md): Next.js App Router and SSR.
|
|
240
|
+
- [Security](security.md): what to set up before rendering documents you didn't write.
|
|
241
|
+
- [JSON format](json-format.md): every field of the document.
|
|
242
|
+
- [API reference](api.md): every export and prop.
|