@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/theming.md
ADDED
|
@@ -0,0 +1,244 @@
|
|
|
1
|
+
# Theming
|
|
2
|
+
|
|
3
|
+
Every built-in widget reads its colours, fonts, spacing and radii from **tokens**,
|
|
4
|
+
exposed as `--ds-*` CSS variables on the dashboard's root element. Change the tokens and
|
|
5
|
+
the whole dashboard follows, charts included. Nothing reads a UI library's theme, and
|
|
6
|
+
nothing outside the dashboard is touched.
|
|
7
|
+
|
|
8
|
+
## Tokens
|
|
9
|
+
|
|
10
|
+
A `Theme` has a name, a mode, shared scale tokens, and one colour set per mode:
|
|
11
|
+
|
|
12
|
+
```ts
|
|
13
|
+
interface Theme {
|
|
14
|
+
name: string;
|
|
15
|
+
mode: "light" | "dark" | "auto"; // auto follows the viewer's system setting
|
|
16
|
+
scale: ScaleTokens; // shared by both modes
|
|
17
|
+
light: ColorTokens;
|
|
18
|
+
dark: ColorTokens;
|
|
19
|
+
}
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
| Group | Tokens |
|
|
23
|
+
|---|---|
|
|
24
|
+
| `scale.font` | `heading`, `body`, `data` (numbers, with tabular figures), and type `roles`: `display`, `title`, `heading`, `body`, `label`, `caption`, `kpi`, `data` (each `{ family, size, weight, lineHeight, letterSpacing? }`) |
|
|
25
|
+
| `scale.space` | `xxs`, `xs`, `sm`, `md`, `lg`, `xl`, `xxl` (px) |
|
|
26
|
+
| `scale.radius` | `control`, `card`, `sheet`, `full` (px) |
|
|
27
|
+
| `scale.shadow` | `raised`, `overlay` |
|
|
28
|
+
| `scale.motion` | `fast`, `normal`, `slow` (ms), `easing`, `enter`, `exit` |
|
|
29
|
+
| `scale.z` | `raised`, `sticky`, `overlay`, `tooltip` |
|
|
30
|
+
| `scale.breakpoints` | `sm`, `md`, `lg`, `xl`, `tv` (px) |
|
|
31
|
+
| `scale.density` | `"compact"`, `"comfortable"` (default) or `"spacious"`. Scales every `--ds-space-*` (×0.75, ×1, ×1.25, rounded) and sets `--ds-control-height` (30, 36, 42 px) for filters, buttons and inputs; also emitted as `--ds-density`. Your own widgets can read it with `useThemeTokens` |
|
|
32
|
+
| `surface` | `page`, `card`, `sunken`, `overlay`, `selection`, `scrim`, `backdrop?` (page background, may be a gradient), `tableHeader?` |
|
|
33
|
+
| `text` | `primary`, `secondary`, `subtle`, `disabled`, `onFill` |
|
|
34
|
+
| `border` | `default`, `control`, `focus` |
|
|
35
|
+
| `action` | `primary`, `primaryHover`, `primaryActive`, `onPrimary` |
|
|
36
|
+
| `status` | `good`, `warn`, `bad`, `neutral`, `info`, each `{ fg, bg, border, solid }` |
|
|
37
|
+
| `chart` | `series` (categorical colours, in order), `sequential` (low → high, for heatmaps), `axis`, `grid`, `tooltipBg`, `tooltipText` |
|
|
38
|
+
|
|
39
|
+
The default theme (`defaultTheme`) uses mode `auto` and the font stack
|
|
40
|
+
`Inter, system-ui, sans-serif`. The package doesn't load fonts: load Inter yourself, or
|
|
41
|
+
set your own font.
|
|
42
|
+
|
|
43
|
+
## `createTheme`
|
|
44
|
+
|
|
45
|
+
### Short form
|
|
46
|
+
|
|
47
|
+
Most brands need only a few values. The short form applies to both modes:
|
|
48
|
+
|
|
49
|
+
```ts
|
|
50
|
+
import { createTheme } from "@dashspec/renderer";
|
|
51
|
+
|
|
52
|
+
const acme = createTheme({
|
|
53
|
+
name: "acme",
|
|
54
|
+
colors: {
|
|
55
|
+
primary: "#4f46e5",
|
|
56
|
+
good: "#16a34a",
|
|
57
|
+
warn: "#d97706",
|
|
58
|
+
bad: "#dc2626",
|
|
59
|
+
series: ["#4f46e5", "#06b6d4", "#f59e0b", "#ef4444", "#8b5cf6"],
|
|
60
|
+
},
|
|
61
|
+
font: { family: "'Acme Sans', system-ui, sans-serif", data: "'Acme Mono', monospace" },
|
|
62
|
+
radius: 12, // card radius in px; controls get half
|
|
63
|
+
density: "compact",
|
|
64
|
+
});
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
| Field | What it sets |
|
|
68
|
+
|---|---|
|
|
69
|
+
| `name` | The theme's name |
|
|
70
|
+
| `mode` | `"light"`, `"dark"` or `"auto"` (default: the base theme's, `auto`) |
|
|
71
|
+
| `extends` | Start from another `Theme` instead of `defaultTheme` |
|
|
72
|
+
| `colors.primary` | `action.primary` and `border.focus` |
|
|
73
|
+
| `colors.good` / `warn` / `bad` | That status tone's `solid` and `border` |
|
|
74
|
+
| `colors.series` | `chart.series` |
|
|
75
|
+
| `font.family` | Body font, and heading and data fonts unless given |
|
|
76
|
+
| `font.heading`, `font.data` | Heading and number fonts |
|
|
77
|
+
| `radius` | `radius.card`, and `radius.control` at half |
|
|
78
|
+
| `density` | `scale.density`: `"compact"`, `"comfortable"` or `"spacious"` (spacing and control height) |
|
|
79
|
+
|
|
80
|
+
### Full overrides
|
|
81
|
+
|
|
82
|
+
`scale`, `light` and `dark` take any part of the token tree and are merged deeply over
|
|
83
|
+
the base theme after the short form. Arrays (like `series`) replace, they don't merge.
|
|
84
|
+
|
|
85
|
+
```ts
|
|
86
|
+
const acme = createTheme({
|
|
87
|
+
colors: { primary: "#4f46e5" },
|
|
88
|
+
scale: {
|
|
89
|
+
font: { roles: { kpi: { family: "data", size: 34, weight: 700, lineHeight: 40 } } },
|
|
90
|
+
space: { md: 14 },
|
|
91
|
+
},
|
|
92
|
+
light: {
|
|
93
|
+
surface: { page: "#f8fafc", backdrop: "linear-gradient(180deg, #eef2ff 0%, #f8fafc 240px)" },
|
|
94
|
+
status: { good: { bg: "#dcfce7", fg: "#14532d" } },
|
|
95
|
+
},
|
|
96
|
+
dark: {
|
|
97
|
+
surface: { page: "#0b1020", card: "#121a2f" },
|
|
98
|
+
chart: { grid: "#1f2a44" },
|
|
99
|
+
},
|
|
100
|
+
});
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
`createTheme` never changes its input or the base theme.
|
|
104
|
+
|
|
105
|
+
## Use a theme
|
|
106
|
+
|
|
107
|
+
Pass it to the renderer, a provider, or a design system:
|
|
108
|
+
|
|
109
|
+
```tsx
|
|
110
|
+
<DashboardRenderer document={doc} theme={acme} />
|
|
111
|
+
|
|
112
|
+
<DashSpecProvider theme={acme}>…</DashSpecProvider>
|
|
113
|
+
|
|
114
|
+
defineDesignSystem({ name: "Acme", theme: acme });
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Which theme applies: the renderer's `theme` prop, else the provider's, else the last
|
|
118
|
+
design system that has one, else the default theme.
|
|
119
|
+
|
|
120
|
+
## Light, dark and auto
|
|
121
|
+
|
|
122
|
+
`mode` decides which colour set is used:
|
|
123
|
+
|
|
124
|
+
- `"light"` or `"dark"`: always that one.
|
|
125
|
+
- `"auto"`: follows the viewer's `prefers-color-scheme`, and switches live when it
|
|
126
|
+
changes. Server rendering and the first client render use light, then switch (see
|
|
127
|
+
[Server rendering](server-rendering.md#hydration)).
|
|
128
|
+
|
|
129
|
+
Follow your app's own dark mode by building the theme with the current mode:
|
|
130
|
+
|
|
131
|
+
```tsx
|
|
132
|
+
const theme = useMemo(() => createTheme({ extends: acme, mode: isDark ? "dark" : "light" }), [isDark]);
|
|
133
|
+
<DashboardRenderer document={doc} theme={theme} />;
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
A document can ask for a mode too: `"display": { "theme": "dark" }` applies `dark` to
|
|
137
|
+
whichever theme the host gave.
|
|
138
|
+
|
|
139
|
+
## Named themes
|
|
140
|
+
|
|
141
|
+
Register several themes by name; a document picks one with `display.theme`:
|
|
142
|
+
|
|
143
|
+
```tsx
|
|
144
|
+
<DashSpecProvider
|
|
145
|
+
theme={acme}
|
|
146
|
+
themes={{
|
|
147
|
+
"acme-dark": createTheme({ extends: acme, mode: "dark" }),
|
|
148
|
+
"acme-tv": createTheme({ extends: acme, mode: "dark", scale: { font: { roles: { kpi: { family: "data", size: 48, weight: 700, lineHeight: 56 } } } } }),
|
|
149
|
+
}}
|
|
150
|
+
>
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
```json
|
|
154
|
+
"display": { "title": "Wall screen", "theme": "acme-tv" }
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
`display.theme` resolves in this order:
|
|
158
|
+
|
|
159
|
+
1. A name in `themes`: that theme, in its own mode.
|
|
160
|
+
2. `"light"`, `"dark"` or `"auto"`: the host's theme in that mode.
|
|
161
|
+
3. Anything else: the host's theme, and `onError` receives
|
|
162
|
+
`{ code: "unknown-theme", message }`.
|
|
163
|
+
|
|
164
|
+
## CSS variables
|
|
165
|
+
|
|
166
|
+
The renderer wraps the dashboard in a `<div class="ds-root" data-ds-theme="light|dark">`
|
|
167
|
+
and sets every token on it as a variable:
|
|
168
|
+
|
|
169
|
+
| Token | Variable |
|
|
170
|
+
|---|---|
|
|
171
|
+
| `surface.card` | `--ds-color-surface-card` |
|
|
172
|
+
| `text.secondary` | `--ds-color-text-secondary` |
|
|
173
|
+
| `status.good.bg` | `--ds-color-status-good-bg` |
|
|
174
|
+
| `chart.series[0]` | `--ds-color-chart-series-1` |
|
|
175
|
+
| `space.md` | `--ds-space-md` (`12px`; scaled by `density`) |
|
|
176
|
+
| `density` | `--ds-control-height` (`36px`), `--ds-density` |
|
|
177
|
+
| `radius.card` | `--ds-radius-card` |
|
|
178
|
+
| `font.roles.kpi.size` | `--ds-type-kpi-size` (also `-family`, `-weight`, `-line-height`, `-letter-spacing`) |
|
|
179
|
+
| `motion.fast` | `--ds-motion-fast` (`150ms`) |
|
|
180
|
+
|
|
181
|
+
Short aliases: `--ds-primary`, `--ds-good`, `--ds-warn`, `--ds-bad` (status `solid`),
|
|
182
|
+
`--ds-font`, `--ds-radius` (card radius), `--ds-series-1`, `--ds-series-2`, …
|
|
183
|
+
|
|
184
|
+
Use them in your own widgets so they follow the theme and dark mode:
|
|
185
|
+
|
|
186
|
+
```css
|
|
187
|
+
.acme-battery {
|
|
188
|
+
background: var(--ds-color-surface-sunken);
|
|
189
|
+
border-radius: var(--ds-radius-control);
|
|
190
|
+
color: var(--ds-color-text-primary);
|
|
191
|
+
font: var(--ds-type-data-weight) var(--ds-type-data-size) / var(--ds-type-data-line-height) var(--ds-font-data);
|
|
192
|
+
}
|
|
193
|
+
.acme-battery-fill { background: var(--ds-good); }
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
A node's `style.background` and `style.borderColor` accept token names too:
|
|
197
|
+
`"background": "status-good-bg"` becomes `var(--ds-color-status-good-bg)`.
|
|
198
|
+
|
|
199
|
+
`themeCssVars(theme, mode)` returns the variables for one mode as an object, if you need
|
|
200
|
+
them elsewhere.
|
|
201
|
+
|
|
202
|
+
### `themeStylesheet`
|
|
203
|
+
|
|
204
|
+
To style other parts of your page with the same tokens, or for pages that don't use
|
|
205
|
+
React, `themeStylesheet` returns the variables as CSS: light on the selector, dark under
|
|
206
|
+
`[data-ds-theme="dark"]`.
|
|
207
|
+
|
|
208
|
+
```ts
|
|
209
|
+
import { themeStylesheet } from "@dashspec/renderer";
|
|
210
|
+
|
|
211
|
+
const css = themeStylesheet(acme, ".acme-dashboard-shell");
|
|
212
|
+
// .acme-dashboard-shell { --ds-color-surface-page: #f8fafc; … }
|
|
213
|
+
// .acme-dashboard-shell[data-ds-theme="dark"] { … }
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
Set `data-ds-theme="dark"` on the element yourself to switch it. Tokens whose name or
|
|
217
|
+
value could break out of a CSS rule (`;`, braces, `<`, `>`, line breaks, `\`) are left
|
|
218
|
+
out, so a theme built from user input can't inject CSS.
|
|
219
|
+
|
|
220
|
+
## Charts
|
|
221
|
+
|
|
222
|
+
Charts use the same tokens: `chart.series` colours the series in order, `chart.axis`
|
|
223
|
+
and `chart.grid` the axes, `chart.tooltipBg` and `chart.tooltipText` the tooltip,
|
|
224
|
+
`chart.sequential` the matrix chart's scale, and fonts come from `scale.font`. They
|
|
225
|
+
re-theme when the mode changes.
|
|
226
|
+
|
|
227
|
+
For one chart, override anything ECharts supports with the widget's `options` prop; it
|
|
228
|
+
is merged last:
|
|
229
|
+
|
|
230
|
+
```json
|
|
231
|
+
"trend": {
|
|
232
|
+
"kind": "LineChart",
|
|
233
|
+
"spec": {
|
|
234
|
+
"data": { "source": "daily" },
|
|
235
|
+
"x": "date",
|
|
236
|
+
"y": "orders",
|
|
237
|
+
"options": { "color": ["#0ea5e9"], "legend": { "show": false }, "grid": { "left": 48 } }
|
|
238
|
+
}
|
|
239
|
+
}
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
`echartsTheme(theme, mode)` returns the ECharts theme object built from the tokens, if
|
|
243
|
+
you draw your own ECharts charts and want them to match. Inside a widget,
|
|
244
|
+
`useThemeTokens()` gives you `{ theme, mode }`.
|