@dashspec/renderer 0.1.8 → 0.1.10

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/README.md CHANGED
@@ -9,7 +9,7 @@
9
9
  | Page | What it covers |
10
10
  |---|---|
11
11
  | [Getting started](getting-started.md) | Install, a first dashboard, loading JSON from your API, validating with `loadDocument`, what viewers see for invalid documents |
12
- | [Widgets](widgets.md) | The 30 built-in widgets and their props, nesting with slots, and writing your own with `wrapComponent`, `defineWidget` and `lazyWidget` |
12
+ | [Widgets](widgets.md) | The 31 built-in widgets and their props, nesting with slots, and writing your own with `wrapComponent`, `defineWidget` and `lazyWidget` |
13
13
  | [Data](data.md) | Connections and auth, every datasource type, transforms, refresh and cache, `${…}` templates, the expression language and its helpers, custom datasource types, errors |
14
14
  | [State and events](state-and-events.md) | The state tree, widget events, every action with an example, named actions, `watch`, host actions, scripts, driving a dashboard from your app, URL sync |
15
15
  | [Design systems](design-systems.md) | Bringing your own components, filter controls, empty / error / loading states and custom filter kinds; combining design systems; aliasing built-ins |
package/docs/api.md CHANGED
@@ -408,7 +408,7 @@ See [Widgets](widgets.md) for a guide.
408
408
  | `wrapComponent(Component, options)` | Turns any React component into a widget by mapping props, events, state writes and slots (`WrapOptions`) |
409
409
  | `lazyWidget(def)` | A widget whose code downloads only when a dashboard uses it (`load: () => import(…)`, optional `fallback`) |
410
410
  | `checkWidget(def)` | Returns a list of contract problems (empty when fine). Use it in your tests |
411
- | `builtInWidgets` | The 30 built-in widget definitions |
411
+ | `builtInWidgets` | The 31 built-in widget definitions |
412
412
  | `createWidgetRegistry(builtIns, extra, aliases)` | Builds the kind → widget map the renderer uses (throws on un-namespaced or duplicate kinds). `WidgetRegistry` type |
413
413
 
414
414
  Types: `WidgetDefinition`, `AnyWidgetDefinition` (for lists of widgets with different
@@ -231,7 +231,7 @@ Report these to your monitoring with `onError`:
231
231
 
232
232
  ## Next steps
233
233
 
234
- - [Widgets](widgets.md): the 30 built-in widgets, nesting, and writing your own.
234
+ - [Widgets](widgets.md): the 31 built-in widgets, nesting, and writing your own.
235
235
  - [Data](data.md): connections, auth, datasources, templates and expressions.
236
236
  - [State and events](state-and-events.md): clicks, actions, filters, and driving a dashboard from your app.
237
237
  - [Design systems](design-systems.md): use your own components and controls.
package/docs/widgets.md CHANGED
@@ -1,7 +1,7 @@
1
1
  # Widgets
2
2
 
3
3
  Every box on a dashboard is a **node** in `spec.panels`: a `kind` (which widget) and a
4
- `spec` (that widget's props). The renderer ships 30 built-in widgets, and you can add
4
+ `spec` (that widget's props). The renderer ships 31 built-in widgets, and you can add
5
5
  your own.
6
6
 
7
7
  ```json
@@ -19,7 +19,7 @@ your own.
19
19
  ## Props every widget shares
20
20
 
21
21
  Besides its own props, every built-in widget except the atoms (Text, Value, Progress,
22
- Icon, Divider) accepts these in `spec`:
22
+ Icon, Divider, Button) accepts these in `spec`:
23
23
 
24
24
  | Prop | Type | What it does |
25
25
  |---|---|---|
@@ -67,7 +67,7 @@ Field props such as `x`, `label` or `value` name a field of each data row; dot p
67
67
  | Kind | What it shows | Main props | Events |
68
68
  |---|---|---|---|
69
69
  | `Kpi` | A metric card: label, big value, target and an "On track / Action needed" chip | `unit`, `unitStyle` (`small` / `value`), `format`, `decimals`, `target`, `targetLabel`, `goodWhen` (`up` / `down` / `none`), `badge`, `statusLabels`, `compare`, `band`, `progress`, `note`, `emptyText`, `empty` (show `emptyText` even with a value), `sublabel`, `size` (`normal` / `hero`), `tone` | `click`, `hover` (part `value`) |
70
- | `Tiles` | One tile per row: label, big number, caption | `label`, `value` (required), `caption`, `status`, `statusMap`, `valueTone`, `count`, `format`, `unit`, `columns`, `minTileWidth`, `wrap`, `selectable`, `selected` | `click`, `hover`, `select` (part `tile`) |
70
+ | `Tiles` | One tile per row: label, big number, caption | `label`, `value` (required), `caption`, `status`, `statusMap`, `valueTone`, `count`, `format`, `unit`, `columns`, `minTileWidth`, `wrap`, `chips`, `mutedWhen`, `highlightWhen`, `highlightTone`, `selectable`, `selected`; `value` may be a template over `row` (`"${row.value ?? row.passed}"`) | `click`, `hover`, `select` (part `tile`) |
71
71
  | `Gauge` | A value on an arc or circle with coloured bands | `min` (0), `max` (100), `bands: [{ to, tone }]`, `shape` (`arc` / `circle`), `unit`, `format`, `decimals` | `click` |
72
72
  | `Status` | A status badge from a state field, or fixed text | `state` (field, default `"state"`), `stateMap`, `labels`, `label`, `text`, `tone` | `click` |
73
73
 
@@ -147,7 +147,7 @@ Charts take their colours from the theme's `chart.series` tokens (see
147
147
 
148
148
  | Kind | What it shows | Main props | Events |
149
149
  |---|---|---|---|
150
- | `Table` | Rows and columns with sorting, search, filters, paging, totals and pivots | `columns` (below), `columnsFrom`, `totals`, `pivot`, `pagination`, `search`, `sorting`, `filtering`, `sticky`, `rowKey`, `rowMutedWhen`, `virtual`, `density`, `maxHeight` (px; rows scroll past it) | `rowClick`, `cellClick`, `hover` (parts `row`, `cell`) |
150
+ | `Table` | Rows and columns with sorting, search, filters, paging, totals and pivots | `columns` (below), `columnsFrom`, `totals`, `pivot`, `pagination`, `search`, `sorting`, `filtering`, `sticky`, `rowKey`, `rowMutedWhen`, `virtual`, `density`, `maxHeight` (px; rows scroll past it), `totalsRow`, `expand` (slot `detail`) | `rowClick`, `cellClick`, `hover` (parts `row`, `cell`) |
151
151
  | `CardGrid` | One card per row with fields, a status and a progress bar | `cardTitle` (required), `fields: [{ key, label, format, unit }]`, `status`, `statusMap`, `progress: { value, max, label }`, `badge`, `minCardWidth`, `selectable`, `selected`, `rowKey` | `click`, `select` (part `card`) |
152
152
 
153
153
  A table column is `{ key, label?, type?, … }`. `type` is `text`, `number`, `badge`,
@@ -155,7 +155,28 @@ A table column is `{ key, label?, type?, … }`. `type` is `text`, `number`, `ba
155
155
  `format`, `decimals`, `prefix`, `suffix`, `align`, `empty`, `template`
156
156
  (`"${row.first} ${row.last}"`), `list`, `map` (badge value → tone), `tone` (an
157
157
  expression over `row`), `href` (link template), `max` (progress), `width`, `sortable`,
158
- `filter` (`text` / `select` / `min`) and `filterOptions`.
158
+ `filter` (`text` / `select` / `min`) and `filterOptions`. For richer cells: `sub` (a second line,
159
+ template), `chips` (`[{ text, tone, when }]`, tags under the value shown when `when` holds),
160
+ `weight` (`regular` / `medium` / `semibold` / `bold`) and `valueTone` (an expression over `row` and
161
+ `value` returning a tone, `action` or `muted`).
162
+
163
+ `columnsFrom` builds columns from the data (`{ path, key, label }`). Its `column` is a pattern
164
+ applied to each generated column, with `{key}` and `{label}` filled in; with fixed `columns` too,
165
+ `after` puts the generated ones after that column:
166
+
167
+ ```json
168
+ "columns": [{ "key": "order", "label": "Order" }, { "key": "qty", "label": "Qty" }],
169
+ "columnsFrom": {
170
+ "path": "stages", "key": "id", "label": "name", "after": "qty",
171
+ "column": { "key": "stages.{key}.done", "chips": [{ "text": "${row.stages.{key}.waiting} waiting", "tone": "warn", "when": "row.stages.{key}.waiting > 0" }] }
172
+ }
173
+ ```
174
+
175
+ `totalsRow: { path, label }` draws a total row taken from the data (e.g. the API's own totals)
176
+ with the columns' options; `label` (a template over that row) fills the first column. Use it when
177
+ summing the shown rows isn't right (server paging). `expand: true` opens the `detail` slot under a
178
+ clicked row, with the row as `${item.*}`; the open row's key is in `panels.<id>.ui.expanded` and
179
+ the row in `ui.expandedRow`, so a datasource can fetch its details.
159
180
 
160
181
  ```json
161
182
  "orders": {
@@ -271,6 +292,7 @@ Small pieces for building your own cards inside `Card`, `Row` or a header slot.
271
292
  | `Progress` | A progress bar | `field`, `max`, `color`, `goodFrom`, `showPercent`, `thickness` | none |
272
293
  | `Icon` | An icon: `bolt`, `fire`, `factory`, `clock`, `check`, `alert`, `up`, `down`, `gauge`, `box`, `user`, `money` | `icon`, `size`, `color`, `background` | `click` |
273
294
  | `Divider` | A line | `direction`, `dashed` | none |
295
+ | `Button` | A button that runs the panel's `on.click` | `label`, `icon` (incl. `arrow-left`, `arrow-right`), `iconAfter`, `variant` (`primary` / `secondary` / `subtle` / `link`), `size` (`sm` / `md`), `disabled` (e.g. `"${datasources.trend.data.meta.prev == null}"`), `ariaLabel` | `click` |
274
296
 
275
297
  ```json
276
298
  "revenueCard": {
@@ -309,8 +331,9 @@ top-level nodes go in `layouts`; nested ones live only in their parent's slot.
309
331
 
310
332
  The rules:
311
333
 
312
- - **Every node** has a `header` slot (next to the title) and a `footer` slot (under the
313
- body). The header takes only small widgets: atoms, `Status`, `Content`, `Filter`.
334
+ - **Every node** has a `header` slot (next to the title), a `toolbar` slot (a row under the
335
+ title, above the body: navigation, actions, notes) and a `footer` slot (under the body).
336
+ The header takes only small widgets: atoms, `Status`, `Content`, `Filter`.
314
337
  - Layout widgets add their own: `items` (Container, Row, Column), `body` (Card), one
315
338
  slot per tab `key` (Tabs), `item` (Repeater).
316
339
  - A node sits in **one place**: on the grid or in one slot.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dashspec/renderer",
3
- "version": "0.1.8",
3
+ "version": "0.1.10",
4
4
  "description": "Draws a dashboard from DashSpec JSON: widgets, data, events, state.",
5
5
  "keywords": [
6
6
  "dashboard",