@soffits/dsh-card-board 0.5.0 → 0.7.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 +14 -0
- package/README.md +62 -12
- package/client.js +1349 -1047
- package/examples/boards/home/board.json +6 -0
- package/examples/boards/home/cards/chores.json +30 -4
- package/examples/boards/home/cards/countdown.json +57 -0
- package/examples/boards/home/cards/house.json +15 -5
- package/examples/boards/home/cards/savings.json +3 -1
- package/examples/boards/home/cards/summary.json +50 -0
- package/examples/boards/home/cards/weather.json +43 -5
- package/index.js +7 -1
- package/locale/en.json +9 -3
- package/locale/fr.json +9 -3
- package/locale/zh.json +9 -3
- package/package.json +9 -5
- package/src/routes.js +135 -19
- package/src/schema.js +127 -17
- package/src/seen.js +111 -0
- package/src/store.js +17 -3
- package/src/watch.js +113 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,19 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.7.0
|
|
4
|
+
|
|
5
|
+
- The board is live: changes arrive over a Server-Sent Events route (`/api/card-board/events`), the page fetches only the card that changed, and a card or row that changes in front of you gets a short wash and "just now". Polling stays as the fallback while the stream is down.
|
|
6
|
+
- "New since you last looked": a dot on cards and keyed rows that changed since your last visit, remembered per person on the server, so it holds across devices.
|
|
7
|
+
- New card types: `summary` (a sentence and chips at the top of a board) and `countdown` (a ticking number and the stops on the way, hiding itself after `expiresAt`).
|
|
8
|
+
- Cards may carry an `icon` and a `tone`; list and status rows an `icon`, `tone`, `key` and an `active` window ("now" while it lasts); a row's `date` reads relative to today. Stat items may add a `spark`, a `progress` bar and a `strip` of small values with icons. New tone `violet`.
|
|
9
|
+
- Breaking: a stat item's `delta` is now words, `{ text, tone?, dir? }`, instead of `{ value, unit?, tone? }`.
|
|
10
|
+
- The page is drawn with DSH's own components (tabs, tags, status dots) and @soffits/dsh-ui-kit, which it now needs; it is built from `src/client/` into `client.js`.
|
|
11
|
+
|
|
12
|
+
## 0.6.0
|
|
13
|
+
|
|
14
|
+
- Suggested next steps: cards and rows can carry `step` actions, concrete next steps whoever writes the card knows ("Renew the books online"). A tap records the press like done and snooze (the event `ui.action.step`, with who pressed it), then the step is sent with the card or row to the assistant as the person, and the button links to the conversation. At most 3 per card or row, a label of up to 80 characters is required. Needs @soffits/dsh-ui-actions 0.2.0.
|
|
15
|
+
- A row's steps sit on their own line under it; its other buttons stay beside the title.
|
|
16
|
+
|
|
3
17
|
## 0.5.0
|
|
4
18
|
|
|
5
19
|
- The action buttons come from the shared [`@soffits/dsh-ui-actions`](https://github.com/soffits/dsh-ui-actions) plugin (`ctx.uiActions`) instead of a copy of `client.actions.js` in this package, which is gone. Install that plugin to get buttons; the page works without it, just without buttons. A chat button opens a conversation with the card or row attached to the message box as a small card, and the sent message shows it with the board's icon and name. The board names itself to it once, so cards from other pages read the same.
|
package/README.md
CHANGED
|
@@ -12,6 +12,12 @@ The plugin only displays. It makes no outbound requests, holds no credentials an
|
|
|
12
12
|
npx @deepseek-ai/dsh plugin --profile web add @soffits/dsh-card-board@latest
|
|
13
13
|
```
|
|
14
14
|
|
|
15
|
+
It needs [@soffits/dsh-ui-kit](https://github.com/soffits/dsh-ui-kit), the small shared pieces the page is drawn with (icons, ticking times, rings, the live dot), and uses [@soffits/dsh-ui-actions](https://github.com/soffits/dsh-ui-actions) for buttons when it's there:
|
|
16
|
+
|
|
17
|
+
```sh
|
|
18
|
+
npx @deepseek-ai/dsh plugin --profile web add @soffits/dsh-ui-kit@latest @soffits/dsh-ui-actions@latest
|
|
19
|
+
```
|
|
20
|
+
|
|
15
21
|
Restart `dsh web` afterwards. It adds one Host row, `card-board`, and a **Boards** entry in the sidebar. Boards live in `card-board` under the DSH home unless you set `dataDir`.
|
|
16
22
|
|
|
17
23
|
## Configuration
|
|
@@ -32,7 +38,7 @@ Override the row in your profile's `cordis.patch.yml`:
|
|
|
32
38
|
| `people` | `{}` | Verified user id → person id, for a DSH several people sign in to. |
|
|
33
39
|
| `peopleFile` | | A JSON file with more of that mapping, re-read when it changes. `people` wins on a clash. |
|
|
34
40
|
| `peopleKey` | | The key in `peopleFile` that holds the mapping; empty means the whole file. |
|
|
35
|
-
| `pollSeconds` | `30` | How often an open, visible page checks for changes. A hidden tab doesn't poll. |
|
|
41
|
+
| `pollSeconds` | `30` | How often an open, visible page checks for changes while its live connection is down. A hidden tab doesn't poll. |
|
|
36
42
|
| `actionLog` | `<dataDir>/.actions.jsonl` | Where action presses are appended. |
|
|
37
43
|
| `actionTimeoutSeconds` | `300` | A press nobody handles within this time shows as not handled. |
|
|
38
44
|
|
|
@@ -93,18 +99,19 @@ A card:
|
|
|
93
99
|
|
|
94
100
|
| Field | |
|
|
95
101
|
| --- | --- |
|
|
96
|
-
| `type` | `stat`, `line`, `bar`, `donut`, `list`, `timeline` or `status` |
|
|
102
|
+
| `type` | `summary`, `countdown`, `stat`, `line`, `bar`, `donut`, `list`, `timeline` or `status` |
|
|
97
103
|
| `title` | Shown on the card. |
|
|
104
|
+
| `icon`, `tone` | An icon on a tile tinted with the tone, before the title. Icons are [Lucide](https://lucide.dev/icons) names; the bundled set is in dsh-ui-kit's `icons.json`, and a name it doesn't have draws nothing. |
|
|
98
105
|
| `updatedAt` | ISO date-time with a zone. The CLI fills it in when you leave it out. |
|
|
99
106
|
| `staleAfter` | Seconds. Past this the card is dimmed and says how old it is. |
|
|
100
107
|
| `link` | An `http(s)` URL or a `/path` the title row links to. |
|
|
101
|
-
| `stat` |
|
|
108
|
+
| `stat` | Headline numbers above a chart or rows (beside a chart when the card is wide): the same shape as a `stat` card's `data`. |
|
|
102
109
|
| `actions` | Buttons on the card; see [Actions](#actions). |
|
|
103
110
|
| `data` | Depends on the type, below. |
|
|
104
111
|
|
|
105
112
|
Unknown fields are errors, so a typo fails when the file is written instead of quietly not showing. A card that doesn't parse or fails the schema shows as a small error card with the reason; the rest of the board is unaffected.
|
|
106
113
|
|
|
107
|
-
Colours are never given directly. `tone` is one of `ok`, `warn`, `bad`, `
|
|
114
|
+
Colours are never given directly. `tone` is one of `ok`, `warn`, `bad`, `accent`, `violet` or `muted`, and the page maps it to DSH's theme, light or dark. Dates are `YYYY-MM-DD` or ISO date-times. Numbers, dates and units are formatted by the page in the viewer's language.
|
|
108
115
|
|
|
109
116
|
### Languages
|
|
110
117
|
|
|
@@ -118,18 +125,50 @@ Ids are lowercase BCP 47 tags and `en` is required, the same shape DSH uses for
|
|
|
118
125
|
|
|
119
126
|
The page's own words (buttons, empty states, errors) live in [`locale/<tag>.json`](locale), under `ui`, one file per language. English, French and Chinese ship. Which languages exist is whatever files are there: a new language is one new file with the same keys as `en.json`, no code change (a test checks every file has every key and the same `{placeholders}`), and a missing key falls back to the primary language, then English.
|
|
120
127
|
|
|
128
|
+
### summary
|
|
129
|
+
|
|
130
|
+
A full-width line at the top of a board: what matters now, in a sentence, with a few facts as chips. The page heads it with the day and its part ("Tuesday afternoon") from its own clock, so that is always right.
|
|
131
|
+
|
|
132
|
+
```json
|
|
133
|
+
{ "text": "A quiet day: the library books are due, and the train leaves the day after tomorrow.",
|
|
134
|
+
"chips": [
|
|
135
|
+
{ "icon": "train-front", "text": "Train", "tone": "accent", "to": "2026-03-04T07:40:00+01:00" },
|
|
136
|
+
{ "icon": "book-open", "text": "Books due today", "tone": "warn" }
|
|
137
|
+
] }
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
A chip with `to` (an ISO time) gets a ticking "in 1d 19h" after its text.
|
|
141
|
+
|
|
142
|
+
### countdown
|
|
143
|
+
|
|
144
|
+
A big ticking number until `to`, and the stops on the way with the next one marked. After `to` it says "now"; after `expiresAt` the card hides itself, so whoever writes it needn't remove it on time.
|
|
145
|
+
|
|
146
|
+
```json
|
|
147
|
+
{ "to": "2026-03-04T07:40:00+01:00", "label": "until the train leaves", "sub": "3 h 10 m, one change",
|
|
148
|
+
"steps": [
|
|
149
|
+
{ "at": "2026-03-04T07:15:00+01:00", "label": "At the station" },
|
|
150
|
+
{ "at": "2026-03-04T10:50:00+01:00", "label": "Arrive in Marseille", "sub": "14° and sunny", "zone": "Europe/Paris" }
|
|
151
|
+
],
|
|
152
|
+
"expiresAt": "2026-03-04T10:50:00+01:00" }
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
A step's time shows in its `zone` (an IANA name) when it has one, with the zone's short name when it isn't the viewer's.
|
|
156
|
+
|
|
121
157
|
### stat
|
|
122
158
|
|
|
123
159
|
One to six big numbers.
|
|
124
160
|
|
|
125
161
|
```json
|
|
126
162
|
{ "items": [
|
|
127
|
-
{ "label": "Temperature", "value": 4.5, "unit": "°C", "
|
|
128
|
-
|
|
163
|
+
{ "label": "Temperature", "value": 4.5, "unit": "°C", "sub": "feels like 1 °C",
|
|
164
|
+
"delta": { "text": "2.1° colder than yesterday", "tone": "accent", "dir": "down" },
|
|
165
|
+
"strip": [{ "label": "11", "value": 5.6, "icon": "sun" }, { "label": "12", "value": 6.2, "icon": "sun", "on": true }] },
|
|
166
|
+
{ "label": "Spent this month", "value": 3423, "unit": "of 4,310", "progress": { "value": 3423, "max": 4310, "text": "on pace for 4,286" } },
|
|
167
|
+
{ "label": "Total", "value": 18240, "unit": "EUR", "spark": [16100, 16850, 17200, 18240] }
|
|
129
168
|
] }
|
|
130
169
|
```
|
|
131
170
|
|
|
132
|
-
`value` is a number or a string (for numbers you've already formatted). `tone` on an item colours its value.
|
|
171
|
+
`value` is a number or a string (for numbers you've already formatted). `tone` on an item colours its value. Each item may add a `delta` (a change in words, with a tone and a `dir` of `up`, `down` or `flat` for its arrow), a `progress` bar, a `spark` line or a `strip` of small values with icons, like the next hours of weather (`on` marks one).
|
|
133
172
|
|
|
134
173
|
### line
|
|
135
174
|
|
|
@@ -182,7 +221,9 @@ Each bar has a single `value` or named `values`; with `values` and no `stacked`,
|
|
|
182
221
|
}
|
|
183
222
|
```
|
|
184
223
|
|
|
185
|
-
`checked` draws a checkbox (display only). `progress` draws a ring
|
|
224
|
+
`checked` draws a checkbox (display only). `progress` draws a ring above the rows, with its `label` and an optional `sub`.
|
|
225
|
+
|
|
226
|
+
Rows (of lists and status cards) may also have an `icon` and a `tone` (a tile before the row), a `key` (a stable id, so the page can tell which row changed) and `active: { from, to }`: during that window the row is highlighted and says "now", earlier the same day it says "from 18:00". The page decides when, so nobody has to rewrite the file at noon. A row's `date` shows relative to today ("tomorrow", "in 3 days") and moves on by itself.
|
|
186
227
|
|
|
187
228
|
### timeline
|
|
188
229
|
|
|
@@ -195,7 +236,7 @@ Each bar has a single `value` or named `values`; with `values` and no `stacked`,
|
|
|
195
236
|
}
|
|
196
237
|
```
|
|
197
238
|
|
|
198
|
-
`kind` is `travel
|
|
239
|
+
`kind` is `travel`, `due`, `event`, `health`, `home` or `money`, each drawn with its own icon and default tone; `tone` overrides it. Today gets a thin line.
|
|
199
240
|
|
|
200
241
|
### status
|
|
201
242
|
|
|
@@ -211,6 +252,10 @@ Each bar has a single `value` or named `values`; with `values` and no `stacked`,
|
|
|
211
252
|
|
|
212
253
|
The [examples](examples/boards/home) folder has a complete board with one card of each type.
|
|
213
254
|
|
|
255
|
+
### What is new, and what just changed
|
|
256
|
+
|
|
257
|
+
Nothing to write for these. Each card has a content version (a hash of the card without `updatedAt`, so rewriting the same data changes nothing), and each keyed row its own. The server remembers, per person, which versions they have seen, so a dot marks what changed since they last looked, on any device. A card or row that changes while the page is open gets a short wash and "just now" first (only the dot with reduced motion).
|
|
258
|
+
|
|
214
259
|
## Actions
|
|
215
260
|
|
|
216
261
|
A card, a list row or a status row can carry up to six buttons:
|
|
@@ -219,6 +264,7 @@ A card, a list row or a status row can carry up to six buttons:
|
|
|
219
264
|
"actions": [
|
|
220
265
|
{ "kind": "done", "id": "library-books:done" },
|
|
221
266
|
{ "kind": "snooze", "id": "library-books:snooze" },
|
|
267
|
+
{ "kind": "step", "id": "library-books:renew", "label": { "en": "Renew the books online", "fr": "Renouveler les livres en ligne" } },
|
|
222
268
|
{ "kind": "chat", "id": "landlord:ask", "label": "Draft a message", "payload": { "prompt": "Help me write a short follow-up to the landlord." } },
|
|
223
269
|
{ "kind": "event", "id": "front-door:lock", "label": "Lock" },
|
|
224
270
|
{ "kind": "link", "id": "panel", "label": "Home panel", "payload": { "url": "https://example.com/home" } }
|
|
@@ -226,10 +272,11 @@ A card, a list row or a status row can carry up to six buttons:
|
|
|
226
272
|
```
|
|
227
273
|
|
|
228
274
|
- `chat` opens a new conversation (or the session named in `payload.session`) with a draft that quotes the card or row and carries its ids as JSON, after `payload.prompt` if you gave one. Nothing is sent until the person sends it, so the message comes from them like any other. Every card also has a chat button in its corner without declaring one ("Chat about this"); when the board names an `assistant` the buttons say who they ask ("Ask Robin"). A `label` and `payload.prompt` can be text in several languages.
|
|
275
|
+
- `step` is a suggested next step the assistant starts on one tap: the label says the step plainly ("Renew the books online") and the tap is the person's go-ahead for exactly that. The press is recorded on the server like `done`, then the page sends the step (`payload.prompt` when it needs more words than the label, never more than it authorises; otherwise the label) with the card or row into a new session (or `payload.session`) as the person, with no draft to confirm, and the button links to that session. At most 3 steps per card or row; add one only where the data has a clear next step. The label (up to 80 characters) is required.
|
|
229
276
|
- `done`, `snooze` and `event` are pressed on the server. A snooze without `payload.until` asks: in 3 hours, tomorrow at 9:00, or a time.
|
|
230
277
|
- `link` opens `payload.url`.
|
|
231
278
|
|
|
232
|
-
`id` is yours: letters, digits and `. _ : -`, unique within the card or row. `label` is optional except for `event`. `payload` is any small object (up to 4 KB of JSON).
|
|
279
|
+
`id` is yours: letters, digits and `. _ : -`, unique within the card or row. `label` is optional except for `event` and `step`. `payload` is any small object (up to 4 KB of JSON).
|
|
233
280
|
|
|
234
281
|
The plugin doesn't act on a press itself. It checks that the person may see the board and that the action is in the card as written, then records an event:
|
|
235
282
|
|
|
@@ -273,13 +320,16 @@ From JavaScript the same checks are `import { checkCard, checkBoard } from '@sof
|
|
|
273
320
|
|
|
274
321
|
## How the page updates
|
|
275
322
|
|
|
276
|
-
|
|
323
|
+
`GET /api/card-board/events?board=<board>` is a Server-Sent Events stream: the plugin watches the board's folder and sends `{ "type": "card", "id": … }` for a card written, added or removed, `{ "type": "board" }` for board.json, and a comment every 25 seconds to keep proxies from closing it. The page then fetches only that card from `GET /api/card-board/card?board=<board>&id=<card>`. Who may listen is checked like any read, and someone a board.json change takes off the viewers gets `{ "type": "gone" }` and the stream closes.
|
|
324
|
+
|
|
325
|
+
While that stream is down (or a press waits to be picked up), the page polls `GET /api/card-board/board?id=<board>` instead, with the last `ETag` in `If-None-Match`. The tag is built from file sizes and times, so an unchanged board answers 304 without reading a card. Coming back to the tab checks at once. The page reports what the person has seen to `POST /api/card-board/seen`. The page's words come once per language from `GET /api/card-board/locale?tag=<id>` (the merged `locale/*.json`, English filling gaps).
|
|
277
326
|
|
|
278
327
|
## Development
|
|
279
328
|
|
|
280
329
|
```sh
|
|
281
330
|
npm install
|
|
282
|
-
npm run
|
|
331
|
+
npm run build # client.js from src/client/
|
|
332
|
+
npm run check # client.js is current, syntax of every file, and the example board against the schema
|
|
283
333
|
npm test # node --test, including a run behind DSH's real Connection
|
|
284
334
|
```
|
|
285
335
|
|