@soffits/dsh-card-board 0.10.1 → 0.12.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 +11 -0
- package/README.md +18 -5
- package/client.js +527 -128
- package/examples/boards/home/cards/countdown.json +9 -0
- package/index.js +2 -0
- package/locale/en.json +16 -1
- package/locale/fr.json +16 -1
- package/locale/zh.json +16 -1
- package/package.json +1 -1
- package/src/arrange-store.js +54 -0
- package/src/arrange.js +119 -0
- package/src/person-store.js +54 -0
- package/src/routes.js +31 -3
- package/src/schema.js +20 -3
- package/src/seen.js +7 -37
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,16 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.12.0
|
|
4
|
+
|
|
5
|
+
- Every list and status row now has an Ask button without declaring one, the way every card has its chat button: it opens a new conversation with that row and its card attached ("Ask Robin" when the board names an `assistant`). A row that declares its own `chat` action keeps it, and a row with all six buttons taken gets none. Rows without a `key` get it too: the chat names the row by its place in the card.
|
|
6
|
+
- New `ask` field, a boolean on a card (all its rows) or on a row: `false` leaves the default button out. The card's corner button is unchanged.
|
|
7
|
+
|
|
8
|
+
## 0.11.0
|
|
9
|
+
|
|
10
|
+
- Each person can arrange a board for themselves: drag a card (mouse: by the handle on hover; touch: press and hold the head), or use its menu (Pin to top, Move up, Move down; Alt+↑/↓ on the menu button). Pinned cards come first, and **Reset order** goes back to the board's `order`, which stays the default. The arrangement is stored once by the plugin per person (`<dataDir>/.arrange/`, the same identity as who sees what), follows them across devices and reaches their other open pages through the events stream (`{ "type": "arrange" }`). A card the person never placed goes where the board's order puts it.
|
|
11
|
+
- New card field `raise: { from?, until?, label? }`: during that window the card floats above everything, pins included, with a small tag saying why (`label`, or "Up for now"). The page decides from its own clock with one timer for the next window edge, so no polling and no card rewrite at the moment. New route `POST /api/card-board/arrange`; the board answer carries `arrangement` when the person has one.
|
|
12
|
+
- Why it is built this way: `docs/decisions/card-order.md`. English, French and Chinese words included.
|
|
13
|
+
|
|
3
14
|
## 0.10.1
|
|
4
15
|
|
|
5
16
|
- Fix: a row ticked done blanked the page when the card was rewritten without it (the kept row asked for buttons of a row the card no longer has). It now stays in place, struck through, as intended.
|
package/README.md
CHANGED
|
@@ -82,7 +82,7 @@ Board and card ids are lowercase letters, digits, `-` and `_`, up to 64 characte
|
|
|
82
82
|
}
|
|
83
83
|
```
|
|
84
84
|
|
|
85
|
-
`order` lists cards to put first; the rest follow by id. `layout` sets how wide a card is: `small` (a third of a wide screen), `medium` (a half), `large` (two thirds) or `wide` (all of it). Without it a card takes its type's default: `summary` and `timeline` are wide, `countdown` large, `stat` small, the rest medium; a summary is always wide. On a tablet small and medium cards take half the width and large and wide ones all of it; on a phone every card is full width. Heights are the cards' own: the board packs them like masonry, so a long card never stretches its neighbours and short ones fill the space beside it. A list longer than six rows shows six, then "N more", which opens the rest in place (a row that is new or just changed always shows). `assistant` is optional: the name the chat buttons ask ("Ask Robin" instead of "Ask"). `title` can be [text in several languages](#languages).
|
|
85
|
+
`order` lists cards to put first; the rest follow by id. This is the default: each person can [arrange their own view](#order-pins-and-raised-cards). `layout` sets how wide a card is: `small` (a third of a wide screen), `medium` (a half), `large` (two thirds) or `wide` (all of it). Without it a card takes its type's default: `summary` and `timeline` are wide, `countdown` large, `stat` small, the rest medium; a summary is always wide. On a tablet small and medium cards take half the width and large and wide ones all of it; on a phone every card is full width. Heights are the cards' own: the board packs them like masonry, so a long card never stretches its neighbours and short ones fill the space beside it. A list longer than six rows shows six, then "N more", which opens the rest in place (a row that is new or just changed always shows). `assistant` is optional: the name the chat buttons ask ("Ask Robin" instead of "Ask"). `title` can be [text in several languages](#languages).
|
|
86
86
|
|
|
87
87
|
A card:
|
|
88
88
|
|
|
@@ -106,6 +106,7 @@ A card:
|
|
|
106
106
|
| `staleAfter` | Seconds. Past this the card is dimmed and says how old it is. |
|
|
107
107
|
| `link` | An `http(s)` URL or a `/path` the title row links to. |
|
|
108
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`. |
|
|
109
|
+
| `raise` | `{ from?, until?, label? }`: during this window the card floats to the top; see [Order, pins and raised cards](#order-pins-and-raised-cards). |
|
|
109
110
|
| `actions` | Buttons on the card; see [Actions](#actions). |
|
|
110
111
|
| `detail` | More to show when the card is opened; see [Opening a card](#opening-a-card). |
|
|
111
112
|
| `data` | Depends on the type, below. |
|
|
@@ -253,6 +254,18 @@ Rows (of lists and status cards) may also have an `icon` and a `tone` (a tile be
|
|
|
253
254
|
|
|
254
255
|
The [examples](examples/boards/home) folder has a complete board with one card of each type.
|
|
255
256
|
|
|
257
|
+
### Order, pins and raised cards
|
|
258
|
+
|
|
259
|
+
A board's `order` is the default order. Each person can arrange their own view of a board without changing anyone else's: drag a card (a mouse pulls it by the handle that shows on hover; on a touch screen press and hold its head, then drag), or open its menu for **Pin to top**, **Move up** and **Move down** (with a keyboard, Alt+↑ and Alt+↓ on the menu button move it too). Pinned cards sit first, in the order they were pinned. **Reset order** next to the board's status goes back to the default. The arrangement is kept by the plugin, per person (the same identity as who sees what), so it follows them across devices, and it is the only thing the plugin stores about cards. A card the person never placed, such as a new one, goes where the board's order puts it.
|
|
260
|
+
|
|
261
|
+
A producer can raise a card for a while:
|
|
262
|
+
|
|
263
|
+
```json
|
|
264
|
+
"raise": { "from": "2026-03-03T07:40:00+01:00", "until": "2026-03-04T10:50:00+01:00", "label": { "en": "Leaves tomorrow", "fr": "Départ demain" } }
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
From `from` until `until` (either may be left out, but not both) the card sits above everything else, above pins too, since an urgent card shouldn't be buried by a standing preference. It carries a small tag, `label` or "Up for now", and drops back by itself. The page uses its own clock and one timer for the next moment a window opens or closes, so nobody has to rewrite the card then. Among raised cards the person's own order decides. The reasoning is in [docs/decisions/card-order.md](docs/decisions/card-order.md).
|
|
268
|
+
|
|
256
269
|
### What is new, and what just changed
|
|
257
270
|
|
|
258
271
|
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).
|
|
@@ -276,7 +289,7 @@ On a chart, hovering or tapping shows the value and date of the point under the
|
|
|
276
289
|
|
|
277
290
|
## Actions
|
|
278
291
|
|
|
279
|
-
A card, a list row or a status row can carry up to six buttons:
|
|
292
|
+
A card, a list row or a status row can carry up to six buttons (a list or status row also gets the Ask button below):
|
|
280
293
|
|
|
281
294
|
```json
|
|
282
295
|
"actions": [
|
|
@@ -289,7 +302,7 @@ A card, a list row or a status row can carry up to six buttons:
|
|
|
289
302
|
]
|
|
290
303
|
```
|
|
291
304
|
|
|
292
|
-
- `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");
|
|
305
|
+
- `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"), and every list and status row has one at the end of its buttons ("Ask"), about that row and its card; a row that declares a `chat` action keeps its own, and one with six buttons already gets none. Set `ask: false` on a row, or on a card for all its rows, where asking makes no sense (a row that only says "nothing else today"). 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.
|
|
293
306
|
- `step` is a suggested next step the assistant starts on one tap (on a row it sits with the row's other buttons, "Start" for instance): 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.
|
|
294
307
|
- `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.
|
|
295
308
|
- `link` opens `payload.url`.
|
|
@@ -348,9 +361,9 @@ From JavaScript the same checks are `import { checkCard, checkBoard } from '@sof
|
|
|
348
361
|
|
|
349
362
|
## How the page updates
|
|
350
363
|
|
|
351
|
-
`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.
|
|
364
|
+
`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, `{ "type": "arrange" }` when this person arranges the board from another page, 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.
|
|
352
365
|
|
|
353
|
-
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).
|
|
366
|
+
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`, and keeps their own order and pins with `POST /api/card-board/arrange` (`{ board, pinned, order }`, or `{ board, reset: true }`); the board answer carries it as `arrangement`. The page's words come once per language from `GET /api/card-board/locale?tag=<id>` (the merged `locale/*.json`, English filling gaps).
|
|
354
367
|
|
|
355
368
|
## Development
|
|
356
369
|
|