own-list-view.ts

apps/dashboard/src/own-list-view.ts

1. /**
2. * The private list, rendered: the lines one person logs for themselves.
3. *
4. * What this file is careful about: every other surface on this board turns five
5. * live sources into numbers, and its hardest job is keeping an absent number
6. * from rendering as a zero. This one has exactly one reader (its author) and
7. * two hard jobs instead.
8. *
9. * The first is that "empty" means something different here. Everywhere else an
10. * empty list is a claim about the world, and the prime invariant exists so that
11. * "we looked and there is nothing" cannot be confused with "no source covers
12. * this" or "the fetch failed". Here an empty list is a claim about the owner:
13. * it means they have not written anything. That is a true zero and must read as
14. * one, while a store that is missing or unreadable must still read as neither.
15. * Four facts, four sentences, and none of them silence.
16. *
17. * The second is that none of it may reach anybody else. The pages this board
18. * serves are pre-rendered per viewer by a cron and read back from KV; this block
19. * is stamped into the viewer's own page at serve time, so no private text is
20. * ever written to KV at all. `ownListBlock` re-derives the person from the
21. * viewer and refuses to render a store belonging to anybody else.
22. *
23. * It is also why "overdue" is computed here and now. A pre-rendered overdue
24. * flag would be decided by the 6 a.m. cron, would be wrong by lunchtime, and
25. * would be silently wrong, which is the worst kind. Every load re-decides.
26. *
27. * Runtime-neutral (rule 7). The Worker imports this to stamp the block into a
28. * pre-rendered page; the D1 access that feeds it lives in
29. * apps/worker/src/own-list.ts, which is the only part that needs Worker types.
30. */
32. import { MERIDIAN_TZ, calendarDate, localDay, localStamp } from '@meridian/ninety-client'
33. import {
34. OWN_OPEN_CAP,
35. OWN_PRIORITIES,
36. OWN_PRIORITY_LABEL,
37. OWN_TEXT_CAP,
38. type OwnPriority,
39. hasOwnList,
40. ownListPersonFor,
41. ownPriorityOrder,
42. } from '../../../config/own-list.js'
43. import { esc, join, map } from './html.js'
44. import { parseWorkKey, workKeyLabel } from './work-key.js'
45. import type { Viewer } from './viewer.js'
47. /** One stored line. Mirrors the `own_item` table, camel-cased. */
48. export interface OwnItem {
49. id: number
50. text: string
51. /** YYYY-MM-DD, or null for "no date", which is not the same as overdue. */
52. due: string | null
53. priority: OwnPriority
54. /** `order:MD2639582` / `task:41837`, or null. */
55. linkKey: string | null
56. createdAt: string
57. updatedAt: string
58. edits: number
59. /** ISO 8601 UTC when it was completed, or null while it is open. */
60. doneAt: string | null
61. }
63. /**
64. * What a read of the store came back with.
65. *
66. * `unconfigured` and `failed` stay distinct for the same reason they do in
67. * CheckinStore: collapsing them into one "unavailable" would print the same
68. * sentence in the two cases where the next action differs: one is a deploy
69. * step, the other is a database that answered and refused.
70. */
71. export type OwnStore =
72. | {
73. state: 'ok'
74. /** Whose list this is. Checked against the viewer before anything renders. */
75. person: string
76. open: OwnItem[]
77. done: OwnItem[]
78. /** More open lines exist than were fetched (rule 5). Should be impossible. */
79. truncated: boolean
80. /** Completed lines beyond the folded block's window. */
81. doneHidden: number
82. }
83. | { state: 'unconfigured' }
84. | { state: 'failed'; error: string }
86. export type OwnOutcome =
87. | 'added'
88. | 'edited'
89. | 'unchanged'
90. | 'completed'
91. | 'reopened'
92. | 'empty'
93. | 'toolong'
94. | 'badaction'
95. | 'badid'
96. | 'baddate'
97. | 'badlink'
98. | 'badpriority'
99. | 'notfound'
100. | 'stale'
101. | 'full'
102. | 'failed'
104. const OUTCOMES: readonly OwnOutcome[] = [
105. 'added',
106. 'edited',
107. 'unchanged',
108. 'completed',
109. 'reopened',
110. 'empty',
111. 'toolong',
112. 'badaction',
113. 'badid',
114. 'baddate',
115. 'badlink',
116. 'badpriority',
117. 'notfound',
118. 'stale',
119. 'full',
120. 'failed',
121. ]
123. /**
124. * Narrow a query-string value to an outcome, or null.
125. *
126. * An allow-list rather than a cast, so only our own words reach the page; the
127. * value arrives in a URL anybody can type. Anything else renders no banner at
128. * all, which is the safe answer: a banner is a claim about what just happened.
129. */
130. export function parseOwnOutcome(raw: string | null | undefined): OwnOutcome | null {
131. const v = (raw ?? '').trim()
132. return (OUTCOMES as readonly string[]).includes(v) ? (v as OwnOutcome) : null
133. }
135. // --- dates --------------------------------------------------------------------------
137. export type DueState = 'overdue' | 'today' | 'later' | 'none'
139. /**
140. * Where a line sits relative to today, in Meridian time.
141. *
142. * A line with no date is `none` and never becomes `overdue`. That distinction is
143. * the prime invariant on this surface: "I did not give this a date" and "this
144. * was due on Friday" are different facts, and only one of them is a reproach.
145. */
146. export function dueState(due: string | null, today: string): DueState {
147. if (!due) return 'none'
148. if (due < today) return 'overdue'
149. if (due === today) return 'today'
150. return 'later'
151. }
153. /**
154. * Open lines in the order the card reads them.
155. *
156. * Dated before undated, soonest first, priority breaking ties, then id so the
157. * order is stable across loads. The store's SQL asks for the same order; this
158. * function is what the card actually trusts, because a page whose grouping and
159. * whose sort came from two different definitions would eventually disagree with
160. * itself and there would be no way to tell which was right.
161. */
162. export function sortOpen(items: OwnItem[]): OwnItem[] {
163. return [...items].sort((a, b) => {
164. if ((a.due === null) !== (b.due === null)) return a.due === null ? 1 : -1
165. if (a.due && b.due && a.due !== b.due) return a.due < b.due ? -1 : 1
166. const p = ownPriorityOrder(a.priority) - ownPriorityOrder(b.priority)
167. return p !== 0 ? p : a.id - b.id
168. })
169. }
171. // --- rendering ----------------------------------------------------------------------
173. const GROUPS: { state: DueState; label: string }[] = [
174. { state: 'overdue', label: 'Overdue' },
175. { state: 'today', label: 'Due today' },
176. { state: 'later', label: 'Dated' },
177. { state: 'none', label: 'No date' },
178. ]
180. /** The store's own words and no diagnosis (rule 1). */
181. function storeBanner(store: OwnStore): string {
182. if (store.state === 'unconfigured') {
183. return `<p class="own-banner own-bad"><b>Your own list is not set up on this board.</b>
184. There is no D1 binding for <code>CHECKINS</code>, so nothing can be read and nothing can
185. be saved. That is a deploy step, not an empty list. See
186. <code>apps/worker/migrations/0002_own_list.sql</code>.</p>`
187. }
188. if (store.state === 'failed') {
189. return `<p class="own-banner own-bad"><b>Your own list could not be read.</b>
190. ${esc(store.error)}. So this is missing, not empty. Anything you have added is
191. still in the database.</p>`
192. }
193. if (store.truncated) {
194. // Rule 5: what we have, plus the fact that there was more. This should be
195. // unreachable (the add route refuses past the cap), so it says so rather
196. // than presenting a clipped list as a whole one.
197. return `<p class="own-banner own-bad">Showing the first ${OWN_OPEN_CAP} open lines. There are
198. more than that, which should not be possible: the add form refuses past the cap. If
199. you are seeing this, tell Sam.</p>`
200. }
201. return ''
202. }
204. function outcomeBanner(outcome: OwnOutcome | null): string {
205. if (!outcome) return ''
206. switch (outcome) {
207. case 'added':
208. return `<p class="own-banner own-good">Added. It stays on your list until you complete it.</p>`
209. case 'edited':
210. return `<p class="own-banner own-good">Changed.</p>`
211. case 'unchanged':
212. return `<p class="own-banner">Nothing had changed, so nothing was written.</p>`
213. case 'completed':
214. return `<p class="own-banner own-good">Done. It is folded under <b>Done</b> below.
215. Completing something never throws it away, and reopening is one click.</p>`
216. case 'reopened':
217. return `<p class="own-banner own-good">Back on your open list.</p>`
218. case 'empty':
219. return `<p class="own-banner own-bad">A line with no text is a bullet you cannot act on
220. later, so nothing was saved. Even three words is enough.</p>`
221. case 'toolong':
222. return `<p class="own-banner own-bad">That was longer than ${OWN_TEXT_CAP} characters, so
223. nothing was saved rather than saving part of it. Shorten it and try again; your
224. text is still in the box if you go back.</p>`
225. case 'full':
226. return `<p class="own-banner own-bad">Your list is at its cap of open lines, so this was
227. <b>not</b> added. Complete something first; nothing was trimmed to make room.</p>`
228. case 'notfound':
229. return `<p class="own-banner own-bad">That line is not on your list. It may have been
230. changed from another tab. Nothing was altered.</p>`
231. case 'stale':
232. return `<p class="own-banner own-bad">That page was open from before this line last changed,
233. so nothing was done rather than done to the wrong version. Reload and try again.</p>`
234. case 'baddate':
235. return `<p class="own-banner own-bad">That date was not a real one, so nothing was saved.
236. A line can have no date at all, which is different from being overdue.</p>`
237. case 'badlink':
238. return `<p class="own-banner own-bad">A link has to be an order number or a task id, like
239. <code>MD2639582</code> or <code>task:41837</code>. Nothing was saved.</p>`
240. case 'badpriority':
241. case 'badaction':
242. case 'badid':
243. return `<p class="own-banner own-bad">That form did not arrive in a shape this page
244. recognises, so nothing was changed. Reload and try again.</p>`
245. case 'failed':
246. return `<p class="own-banner own-bad">It was <b>not</b> saved: the store refused the
247. write. Copy what you typed somewhere before you reload.</p>`
248. }
249. }
251. /** The link chip: the id the rest of the board already uses for that work. */
252. function linkChip(linkKey: string | null): string {
253. const parsed = parseWorkKey(linkKey)
254. if (!parsed) return ''
255. // A label, not an anchor. The board has no per-order page to link to, and a
256. // link that scrolled somewhere plausible but wrong is worse than a label.
257. return `<span class="own-link">${esc(workKeyLabel(parsed))}</span>`
258. }
260. function priorityChip(p: OwnPriority): string {
261. // Normal is the default and says nothing; only the two ends earn a chip.
262. if (p === 'normal') return ''
263. return `<span class="own-pri own-pri-${esc(p)}">${esc(OWN_PRIORITY_LABEL[p])}</span>`
264. }
266. function dueLabel(item: OwnItem, today: string): string {
267. if (!item.due) return `<span class="own-when own-nodate">no date</span>`
268. const state = dueState(item.due, today)
269. const word = state === 'overdue' ? 'was due' : state === 'today' ? 'due today' : 'due'
270. const shown = state === 'today' ? '' : ` ${esc(calendarDate(item.due))}`
271. return `<span class="own-when own-when-${state}">${word}${shown}</span>`
272. }
274. /** The hidden fields every mutation form carries. */
275. function rowTokens(item: OwnItem): string {
276. return `<input type="hidden" name="id" value="${esc(String(item.id))}">
277. <input type="hidden" name="seen" value="${esc(item.updatedAt)}">`
278. }
280. function openRow(item: OwnItem, today: string, writable: boolean): string {
281. const state = dueState(item.due, today)
282. return `<li class="own-row own-row-${state}">
283. <div class="own-row-main">
284. <p class="own-text">${esc(item.text)}</p>
285. <div class="own-meta">
286. ${dueLabel(item, today)}
287. ${priorityChip(item.priority)}
288. ${linkChip(item.linkKey)}
289. ${item.edits ? `<span class="own-edited">edited</span>` : ''}
290. </div>
291. </div>
292. ${
293. writable
294. ? `<div class="own-row-acts">
295. <form method="post" action="/own" class="own-act">
296. ${rowTokens(item)}
297. <input type="hidden" name="action" value="done">
298. <button type="submit" class="own-btn">Done</button>
299. </form>
300. <details class="own-edit">
301. <summary class="own-btn own-btn-quiet">Edit</summary>
302. ${itemForm(item, today, 'edit')}
303. </details>
304. </div>`
305. : ''
306. }
307. </li>`
308. }
310. function doneRow(item: OwnItem, writable: boolean): string {
311. return `<li class="own-row own-row-done">
312. <div class="own-row-main">
313. <p class="own-text">${esc(item.text)}</p>
314. <div class="own-meta">
315. <span class="own-when">done ${esc(item.doneAt ? localStamp(item.doneAt) : '')} CT</span>
316. ${linkChip(item.linkKey)}
317. </div>
318. </div>
319. ${
320. writable
321. ? `<div class="own-row-acts">
322. <form method="post" action="/own" class="own-act">
323. ${rowTokens(item)}
324. <input type="hidden" name="action" value="reopen">
325. <button type="submit" class="own-btn own-btn-quiet">Reopen</button>
326. </form>
327. </div>`
328. : ''
329. }
330. </li>`
331. }
333. /**
334. * The add form, and the edit form, which are the same fields.
335. *
336. * One function because they must stay the same fields: an edit box missing a
337. * control the add box has would silently drop that value on every edit.
338. */
339. function itemForm(item: OwnItem | null, today: string, mode: 'add' | 'edit'): string {
340. const id = mode === 'add' ? 'own-new' : `own-edit-${item?.id ?? 0}`
341. const parsed = parseWorkKey(item?.linkKey ?? null)
342. return `<form method="post" action="/own" class="own-form">
343. <input type="hidden" name="action" value="${mode === 'add' ? 'add' : 'edit'}">
344. ${item ? rowTokens(item) : ''}
345. <label class="own-label" for="${esc(id)}-text">What needs doing</label>
346. <textarea id="${esc(id)}-text" name="text" class="own-input" rows="2"
347. maxlength="${OWN_TEXT_CAP}"
348. placeholder="Call the gym back about the 10 ft backdrop proof">${esc(item?.text ?? '')}</textarea>
349. <div class="own-form-row">
350. <span class="own-field">
351. <label class="own-label" for="${esc(id)}-due">Due</label>
352. <input id="${esc(id)}-due" type="date" name="due" class="own-date"
353. value="${esc(item?.due ?? '')}">
354. </span>
355. <span class="own-field">
356. <label class="own-label" for="${esc(id)}-pri">Priority</label>
357. <select id="${esc(id)}-pri" name="priority" class="own-select">
358. ${map(
359. OWN_PRIORITIES,
360. (p) =>
361. `<option value="${esc(p)}"${
362. (item?.priority ?? 'normal') === p ? ' selected' : ''
363. }>${esc(OWN_PRIORITY_LABEL[p])}</option>`,
364. )}
365. </select>
366. </span>
367. <span class="own-field">
368. <label class="own-label" for="${esc(id)}-link">Order or task <span class="own-opt">optional</span></label>
369. <input id="${esc(id)}-link" type="text" name="link" class="own-text-in"
370. value="${esc(parsed?.key ?? '')}" placeholder="MD2639582">
371. </span>
372. </div>
373. <div class="own-form-acts">
374. <button type="submit" class="own-btn own-btn-go">${mode === 'add' ? 'Add to my list' : 'Save changes'}</button>
375. ${
376. mode === 'add'
377. ? `<span class="own-hint">Today is ${esc(calendarDate(today))}. Leave the date blank if it does not have one.</span>`
378. : ''
379. }
380. </div>
381. </form>`
382. }
384. /**
385. * The reconciliation sentence: what the numbers above mean and what they do not.
386. *
387. * Rule 9, and the version of it that actually bites on this card. The risk here
388. * is not a number above an empty list; it is a reader seeing "on my board 4" at
389. * the top of the card and "3 open" here and having no way to know whether the 3
390. * is inside the 4. It is not, and saying so is one sentence.
391. */
392. function reconciliation(open: number, overdue: number, done: number, loadIsNull: boolean): string {
393. const bits = [
394. `${open} open, and ${open === 1 ? 'it is' : 'all of them are'} listed above.`,
395. overdue
396. ? `${overdue} of ${open === 1 ? 'them' : 'those'} ${overdue === 1 ? 'is' : 'are'} past its date and counted in both numbers.`
397. : '',
398. done ? `${done} completed ${done === 1 ? 'line is' : 'lines are'} folded below and in neither.` : '',
399. loadIsNull
400. ? `“On my board” above reads – because no source covers your work
401. individually. Your own list is not a source, and adding to it does not change that.`
402. : `Nothing here is counted in “on my board” at the top of this card:
403. that number is orders, tasks, to-dos and tracker items. This list is yours and is not
404. a source.`,
405. ]
406. return `<p class="own-reconcile">${bits.filter(Boolean).join(' ')}</p>`
407. }
409. /**
410. * The whole block, stamped over the placeholder at serve time.
411. *
412. * Nothing is the default. A viewer with no list, or a store belonging to
413. * somebody else, gets an empty string, not a hidden div. Hidden markup is not
414. * hidden, which is why the board renders a variant per viewer at all.
415. */
416. export function ownListBlock(
417. viewer: Viewer,
418. store: OwnStore,
419. now: Date = new Date(),
420. outcome: OwnOutcome | null = null,
421. loadIsNull = false,
422. ): string {
423. const person = ownListPersonFor(viewer)
424. if (!person || !hasOwnList(viewer)) return ''
426. // The store must be the one that was asked for. This cannot happen through
427. // any current call path (the Worker reads with this same name), and it is
428. // checked anyway, because the cost of the refactor that breaks it is one
429. // person reading another's private list, and the cost of the check is a
430. // string comparison.
431. if (store.state === 'ok' && store.person !== person) {
432. return card(
433. person,
434. '',
435. `<p class="own-banner own-bad"><b>Your own list could not be shown.</b> The board read a
436. list that is not yours and refused to render it. Nothing was disclosed and nothing was
437. changed. Tell Sam.</p>`,
438. )
439. }
441. const today = localDay(now, MERIDIAN_TZ)
442. const writable = store.state !== 'unconfigured'
443. const open = store.state === 'ok' ? sortOpen(store.open) : []
444. const done = store.state === 'ok' ? store.done : []
445. const overdue = open.filter((i) => dueState(i.due, today) === 'overdue').length
447. const chip =
448. store.state === 'ok'
449. ? `<span class="own-chip ${overdue ? 'own-chip-due' : ''}">${open.length} open${
450. overdue ? ` · ${overdue} overdue` : ''
451. }</span>`
452. : // Not a zero. A store that could not be read has no count, and printing
453. // "0 open" here would be the prime invariant broken on the one surface
454. // where the reader is the only person who could notice.
455. `<span class="own-chip own-chip-dark">not read</span>`
457. const body = join([
458. outcomeBanner(outcome),
459. storeBanner(store),
460. store.state !== 'ok'
461. ? // The banner said what happened. A list here would be a claim.
462. ''
463. : open.length
464. ? join([
465. ...GROUPS.map((g) => {
466. const rows = open.filter((i) => dueState(i.due, today) === g.state)
467. if (!rows.length) return ''
468. return `<div class="own-group">
469. <div class="own-group-head">${esc(g.label)} <span class="own-group-n">${rows.length}</span></div>
470. <ul class="own-rows">${map(rows, (i) => openRow(i, today, writable))}</ul>
471. </div>`
472. }),
473. reconciliation(open.length, overdue, done.length, loadIsNull),
474. ])
475. : done.length
476. ? `<p class="own-empty">Nothing open. ${done.length} completed
477. ${done.length === 1 ? 'line is' : 'lines are'} kept below; completing
478. something never removes it.</p>`
479. : // A true zero, and it must read as one. Everywhere else on this board
480. // an empty list is a claim about the world and has to be kept apart
481. // from "not tracked"; here it is a claim about the owner, and saying
482. // so is what stops it reading like every other absence on the page.
483. `<p class="own-empty"><b>Nothing on your own list.</b> This one is empty because you
484. have not added anything yet. It is the only list on this card that is not
485. read from a source, so an empty one means exactly that.</p>`,
486. writable
487. ? `<details class="own-add"${open.length || done.length ? '' : ' open'}>
488. <summary class="own-btn own-btn-go">Add a line</summary>
489. ${
490. store.state === 'failed'
491. ? `<p class="own-hint own-hint-warn">The store would not answer a read just now, so
492. this may not save either. Keep a copy of anything long until you see it land.</p>`
493. : ''
494. }
495. ${itemForm(null, today, 'add')}
496. </details>`
497. : // No form at all without a binding: a box that could only lose what was
498. // typed into it is worse than no box, which is the same call `bootNotes`
499. // makes when the notes tag is absent.
500. '',
501. done.length
502. ? `<details class="own-done">
503. <summary class="own-btn own-btn-quiet">Done (${done.length})</summary>
504. <ul class="own-rows">${map(done, (i) => doneRow(i, writable))}</ul>
505. ${
506. store.state === 'ok' && store.doneHidden
507. ? `<p class="own-hint">${store.doneHidden} older completed
508. ${store.doneHidden === 1 ? 'line is' : 'lines are'} kept in the database and not
509. listed here. Nothing was deleted.</p>`
510. : ''
511. }
512. </details>`
513. : '',
514. ])
516. return card(person, chip, body)
517. }
519. function card(person: string, chip: string, body: string): string {
520. return `<div class="own-wrap">
521. <div class="own-head">
522. <div class="own-title">My own list</div>
523. ${chip}
524. </div>
525. <p class="own-sub">Only you. Nobody else who signs into this board can read these:
526. there is no reader list and no leadership view, and no count from here appears on any
527. shared page. Nothing here chases you either: it is waiting when you open the board, and
528. the dates are checked fresh each time you load it.</p>
529. ${body}
530. <p class="own-foot">Filed under ${esc(person)}.</p>
531. </div>`
532. }
534. // --- markers ------------------------------------------------------------------------
536. /**
537. * Stamped into a pre-rendered page at serve time, like the theme, the notes
538. * JSON, the sync line and the end-of-day note.
539. *
540. * It has to be stamped rather than rendered for two independent reasons, and
541. * the second is the one that matters: a line added a minute ago must show on
542. * the next load without waiting for a cron, and no private text may ever be
543. * written into the KV page at all. What sits in KV is the placeholder below.
544. */
545. export const OWN_START = '<!--ownlist:start-->'
546. export const OWN_END = '<!--ownlist:end-->'
548. /**
549. * Not empty, and rule 8 is why. An empty div here is a feature that silently is
550. * not there: visible in a variant sitting in KV before the Worker stamps it,
551. * in a variant dumped to a file, and above all in a deploy where the Worker
552. * stopped stamping. The last sentence is for whoever is looking at one of those
553. * and needs to know at a glance that no private text is in it.
554. */
555. export const ownListPlaceholder = (): string =>
556. `${OWN_START}<div class="own-wrap"><p class="own-empty"><b>Your own list lives on the live
557. board.</b> This copy was rendered to a file, which has no way to read your list or accept
558. the form. Open the deployed board to add a line.
559. <b>Nothing of yours is in this file.</b></p></div>${OWN_END}`
561. /** Swap the placeholder for the real block. A page without markers is untouched. */
562. export function stampOwnList(html: string, block: string): string {
563. const from = html.indexOf(OWN_START)
564. if (from === -1) return html
565. const to = html.indexOf(OWN_END, from)
566. if (to === -1) return html
567. return html.slice(0, from) + block + html.slice(to + OWN_END.length)
568. }