@dashspec/renderer 0.1.5 → 0.1.7

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.
@@ -182,6 +182,43 @@ export const acme = defineDesignSystem({
182
182
  (`${filters.shift}`), starts at `default` (or `null`), and is written to the URL as text.
183
183
  A namespaced filter kind with no registered component renders nothing.
184
184
 
185
+ ## Your own filter bar
186
+
187
+ Register a whole filter bar as `ui.FilterBar` (on `DashSpecProvider`, a design system or the
188
+ renderer) and it replaces DashSpec's: any layout, any design. Widgets and datasources react to
189
+ it exactly as to the built-in bar.
190
+
191
+ ```tsx
192
+ import type { UIFilterBarProps } from "@dashspec/renderer";
193
+
194
+ function MyFilterBar({ filters, values, setFilter, reset, isDefault, views, view, setView, renderControl }: UIFilterBarProps) {
195
+ return (
196
+ <header className="my-bar">
197
+ {filters.map((f) =>
198
+ f.name === "period" ? <MyDatePicker key={f.name} value={values.period} onChange={(v) => setFilter("period", v)} />
199
+ : <span key={f.name}>{renderControl(f.name)}</span>, // DashSpec's own control, with your design system's parts
200
+ )}
201
+ <select value={view ?? ""} onChange={(e) => setView(e.target.value)}>
202
+ {views.map((v) => <option key={v.name} value={v.name}>{v.label}</option>)}
203
+ </select>
204
+ {!isDefault && <button onClick={reset}>Reset</button>}
205
+ </header>
206
+ );
207
+ }
208
+
209
+ <DashSpecProvider ui={{ FilterBar: MyFilterBar }}>…</DashSpecProvider>
210
+ ```
211
+
212
+ `filters` lists what the bar would show now (not `hidden`, not placed on the canvas as a `Filter`
213
+ node, `visibleWhen` true), each with its whole `spec.variables` entry as `config`. In the
214
+ Builder's edit mode DashSpec's own bar is shown so filters stay selectable.
215
+
216
+ **Filters outside the renderer.** Keep the controls anywhere in your app and pass their values
217
+ in: `variables={{ period, line }}` on `DashboardRenderer` (controlled) with
218
+ `onVariableChange`, or call `useDashboardActions(id).setVariable(name, value)` from any
219
+ component. Set `display.filterBar.show: false` in the document to hide DashSpec's bar. See
220
+ [State and events](state-and-events.md).
221
+
185
222
  ## Combine several
186
223
 
187
224
  Pass several design systems; they combine:
package/docs/theming.md CHANGED
@@ -103,6 +103,28 @@ const acme = createTheme({
103
103
 
104
104
  `createTheme` never changes its input or the base theme.
105
105
 
106
+ ## Per-widget overrides
107
+
108
+ `widgets` in `createTheme` styles every panel of one widget kind (built-in or your own) and carries
109
+ settings for your own widgets. It is scoped to the dashboards using that theme.
110
+
111
+ ```ts
112
+ const theme = createTheme({
113
+ widgets: {
114
+ Kpi: {
115
+ vars: { "--ds-type-kpi-size": "32px" }, // any --ds-* token, or your own variables
116
+ css: "& .ds-kpi-label { text-transform: uppercase; }", // & is the panel
117
+ },
118
+ "acme.Gauge": { settings: { ring: "thick" } }, // read by your widget
119
+ },
120
+ });
121
+ ```
122
+
123
+ Each panel carries `data-kind="<kind>"`, which is what these rules target. Your own widget
124
+ (registered with `widgets` on the provider or renderer) reads its entry with
125
+ `useThemeTokens()?.theme.widgets?.["acme.Gauge"]`. Variable names must look like `--name`; values
126
+ with `;`, braces or `<>` are dropped, and `css` may not contain a `<style>` tag.
127
+
106
128
  ## Use a theme
107
129
 
108
130
  Pass it to the renderer, a provider, or a design system:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dashspec/renderer",
3
- "version": "0.1.5",
3
+ "version": "0.1.7",
4
4
  "description": "Draws a dashboard from DashSpec JSON: widgets, data, events, state.",
5
5
  "keywords": [
6
6
  "dashboard",