@soffits/dsh-card-board 0.6.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 CHANGED
@@ -1,5 +1,14 @@
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
+
3
12
  ## 0.6.0
4
13
 
5
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.
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` | A headline above a chart: the same shape as a `stat` card's `data`. |
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`, `muted` or `accent`, 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.
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", "delta": { "value": -2.1, "unit": "°C", "tone": "accent" }, "sub": "feels like 1 °C" },
128
- { "label": "Humidity", "value": 71, "unit": "%" }
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 beside the rows.
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` (drawn as a plane), `due`, `event`, `health`, `home` or `money`; each has a default tone, and `tone` overrides it. Today gets a thin line.
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:
@@ -275,13 +320,16 @@ From JavaScript the same checks are `import { checkCard, checkBoard } from '@sof
275
320
 
276
321
  ## How the page updates
277
322
 
278
- The page polls `GET /api/card-board/board?id=<board>` while it's visible, 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's words come once per language from `GET /api/card-board/locale?tag=<id>` (the merged `locale/*.json`, English filling gaps).
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).
279
326
 
280
327
  ## Development
281
328
 
282
329
  ```sh
283
330
  npm install
284
- npm run check # syntax of every file, and the example board against the schema
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
285
333
  npm test # node --test, including a run behind DSH's real Connection
286
334
  ```
287
335