checkin-view.ts

apps/dashboard/src/checkin-view.ts

1. /**
2. * The end-of-day note, rendered: the form one person fills in, and the log its
3. * readers see.
4. *
5. * What this file is careful about is not the same thing the rest of the board
6. * is careful about. Every other surface turns five live sources into
7. * numbers, and its hardest job is keeping an absent number from rendering as a
8. * zero. Here there are no numbers at all. The hardest job is the same rule
9. * pointed at prose: a day with no note, a day nobody was asked about, a store
10. * that could not be read, and a store that was never set up are four different
11. * facts, and the one that matters ("she has not written one since Tuesday")
12. * is only true if the other three cannot be mistaken for it.
13. *
14. * So each has its own words on the page, and none of them is silence.
15. *
16. * Runtime-neutral (rule 7). The Worker imports this to stamp the block into a
17. * pre-rendered page at serve time; the D1 access that feeds it lives in
18. * apps/worker/src/checkin.ts, which is the only part that needs Worker types.
19. */
21. import { MERIDIAN_TZ, calendarDate, localDay, localStamp } from '@meridian/ninety-client'
22. import {
23. CHECKIN_FIELD_CAP,
24. CHECKIN_GRACE_UNTIL_HOUR,
25. CHECKIN_HISTORY_DAYS,
26. CHECKIN_OPENS_AT_HOUR,
27. CHECKIN_QUESTIONS,
28. CHECKIN_READERS,
29. CHECKIN_WEEKDAYS_ONLY,
30. canWriteCheckin,
31. checkinAuthorFor,
32. checkinExpectedFrom,
33. readableCheckinAuthors,
34. } from '../../../config/checkin.js'
35. import { esc, join, map } from './html.js'
36. import type { Viewer } from './viewer.js'
38. /** One stored note. Mirrors the `checkin` table, camel-cased. */
39. export interface CheckinNote {
40. person: string
41. day: string
42. did: string
43. unsure: string
44. need: string
45. submittedAt: string
46. updatedAt: string
47. revisions: number
48. authorEmail: string
49. }
51. /** One superseded version, from the append-only `checkin_revision` table. */
52. export interface CheckinRevision {
53. person: string
54. day: string
55. revision: number
56. did: string
57. unsure: string
58. need: string
59. writtenAt: string
60. }
62. /**
63. * What came back from the store, and the three ways it can fail to be notes.
64. *
65. * `unconfigured` and `failed` are different on purpose. The first means nobody
66. * has created the D1 database or bound it yet: a deploy step, fixable in two
67. * commands, and nothing has ever been written. The second means the store
68. * exists and would not answer: rows probably do exist and cannot be shown.
69. * Collapsing them into one "unavailable" would say the same sentence in the
70. * one case where the reader's next action differs. Neither may ever be rendered as
71. * an empty list; that is rule 1 and the prime invariant meeting.
72. */
73. export type CheckinStore =
74. | { state: 'ok'; notes: CheckinNote[]; earlier: CheckinRevision[]; truncated: boolean }
75. | { state: 'unconfigured' }
76. | { state: 'failed'; error: string }
78. /** What the last submission did, echoed back through the redirect. */
79. export type CheckinOutcome = 'saved' | 'updated' | 'unchanged' | 'empty' | 'stale' | 'failed'
81. const OUTCOMES: readonly CheckinOutcome[] = [
82. 'saved',
83. 'updated',
84. 'unchanged',
85. 'empty',
86. 'stale',
87. 'failed',
88. ]
90. /** Narrow a query-string value, so only our own words reach the page. */
91. export function parseOutcome(raw: string | null | undefined): CheckinOutcome | null {
92. const v = (raw ?? '').trim()
93. return (OUTCOMES as readonly string[]).includes(v) ? (v as CheckinOutcome) : null
94. }
96. // --- days ---------------------------------------------------------------------------
98. /**
99. * The hour of the day in Meridian time, 0-23.
100. *
101. * `hourCycle: 'h23'` rather than `hour12: false`, which renders midnight as 24
102. * in some ICU builds and would have made the grace window below silently never
103. * fire on exactly one hour of the day.
104. */
105. export function localHour(now: Date, tz: string = MERIDIAN_TZ): number {
106. const part = new Intl.DateTimeFormat('en-US', { timeZone: tz, hour: 'numeric', hourCycle: 'h23' })
107. .formatToParts(now)
108. .find((p) => p.type === 'hour')
109. const n = Number(part?.value ?? NaN)
110. return Number.isFinite(n) ? n % 24 : 0
111. }
113. /** The calendar day before this one. Pure string arithmetic, no timezone. */
114. export function previousDay(day: string): string {
115. const [y, m, d] = day.split('-').map(Number)
116. const t = new Date(Date.UTC(y!, m! - 1, d!) - 86_400_000)
117. return t.toISOString().slice(0, 10)
118. }
120. /**
121. * Which day a note submitted now is about.
122. *
123. * Before 4 AM Meridian time it is about the day that just ended, not the one that
124. * just started. Somebody finishing at 00:30 would otherwise file two facts at
125. * once, both wrong: an empty day behind them, which the log reports as missed,
126. * and a note on a day they have not worked yet.
127. *
128. * Every read and every write goes through this one function, so the day the
129. * form claims and the day the row lands on cannot drift apart.
130. */
131. export function checkinDay(now: Date, tz: string = MERIDIAN_TZ): string {
132. const today = localDay(now, tz)
133. return localHour(now, tz) < CHECKIN_GRACE_UNTIL_HOUR ? previousDay(today) : today
134. }
136. /** Is the form past its "end of day" mark, in Meridian time? */
137. export function checkinIsOpen(now: Date, tz: string = MERIDIAN_TZ): boolean {
138. const h = localHour(now, tz)
139. // The small hours are the tail of yesterday's evening, so the form is open.
140. return h >= CHECKIN_OPENS_AT_HOUR || h < CHECKIN_GRACE_UNTIL_HOUR
141. }
143. /** Monday-Friday. `day` is YYYY-MM-DD, read as a plain calendar date. */
144. export function isWeekday(day: string): boolean {
145. const [y, m, d] = day.split('-').map(Number)
146. const dow = new Date(Date.UTC(y!, m! - 1, d!)).getUTCDay()
147. return dow >= 1 && dow <= 5
148. }
150. /**
151. * The days the log should account for: newest first, back to whichever came
152. * later: the window, their start date, or the day the habit began.
153. *
154. * The list is of days, not of notes, and that is the whole design. A list built
155. * from the rows that exist can only show what was written, so the one thing
156. * this feature is for, noticing that nothing was written, would be invisible
157. * in it. See rule 9 in docs/ARCHITECTURE.md: collecting a thing and showing it
158. * are not the same step, and the last one is the one that goes missing.
159. */
160. export function expectedDays(
161. through: string,
162. from: string | null,
163. days: number = CHECKIN_HISTORY_DAYS,
164. weekdaysOnly: boolean = CHECKIN_WEEKDAYS_ONLY,
165. ): string[] {
166. if (!from) return []
167. const out: string[] = []
168. let day = through
169. for (let i = 0; i < days && day >= from; i++) {
170. if (!weekdaysOnly || isWeekday(day)) out.push(day)
171. day = previousDay(day)
172. }
173. return out
174. }
176. /**
177. * The day range one person's log needs, and the row ceiling for it.
178. *
179. * Exported so the query and the render cannot disagree. If the store fetched a
180. * narrower window than the card lists, days with notes would render as "no
181. * note": a missing row rendered as a missed day, which is the one thing this
182. * feature must never say. One function, both callers.
183. */
184. export function checkinWindow(
185. person: string,
186. through: string,
187. ): { from: string; limit: number } {
188. const expected = expectedDays(through, checkinExpectedFrom(person))
189. const from = expected[expected.length - 1] ?? through
190. // Weekends inside the window can hold notes too, so the ceiling is the span
191. // in calendar days, not the count of weekdays. A limit sized to the weekday
192. // count would drop a Saturday note off the oldest end and show that day as
193. // "no note".
194. //
195. // The +1 means `truncated` cannot fire while one-row-per-person-per-day
196. // holds, and that is the point: if it ever does fire, the unique constraint
197. // has been lost and the reader is told the list is short rather than being
198. // handed a quietly clipped one (rule 5).
199. return { from, limit: CHECKIN_HISTORY_DAYS + 1 }
200. }
202. // --- rendering ----------------------------------------------------------------------
204. /** "left blank", never an empty line: an unanswered question is a fact. */
205. const answerHtml = (text: string): string =>
206. text.trim()
207. ? `<p class="ci-answer">${esc(text)}</p>`
208. : `<p class="ci-answer ci-blank">left blank</p>`
210. /** The store's own failure states, in the store's own words. Never an empty list. */
211. function storeBanner(store: CheckinStore): string {
212. if (store.state === 'unconfigured') {
213. return `<p class="ci-banner ci-bad"><b>The note store is not set up.</b>
214. This board has no D1 binding for <code>CHECKINS</code>, so nothing can be read and nothing
215. can be saved. That is a deploy step, not a missing note
216. (see <code>apps/worker/migrations/0001_checkin.sql</code>).</p>`
217. }
218. if (store.state === 'failed') {
219. // What happened, not why (rule 1). This says what the store said and
220. // stops.
221. return `<p class="ci-banner ci-bad"><b>The note store could not be read.</b>
222. ${esc(store.error)}, so this list is missing, not empty. Notes written earlier are still
223. in the database.</p>`
224. }
225. return store.truncated
226. ? `<p class="ci-banner">Showing the most recent ${CHECKIN_HISTORY_DAYS} days. There are older
227. notes than these.</p>`
228. : ''
229. }
231. /** The line that confirms what just happened to a submission. */
232. function outcomeBanner(outcome: CheckinOutcome | null, day: string): string {
233. if (!outcome) return ''
234. const label = esc(calendarDate(day))
235. switch (outcome) {
236. case 'saved':
237. return `<p class="ci-banner ci-good">Saved. That is ${label} written up.</p>`
238. case 'updated':
239. return `<p class="ci-banner ci-good">Updated. The earlier version is kept.</p>`
240. case 'unchanged':
241. return `<p class="ci-banner">Nothing had changed, so nothing was written.</p>`
242. case 'empty':
243. return `<p class="ci-banner ci-bad">All three boxes were empty, so nothing was saved:
244. a blank note reads exactly like no note at all. Even “quiet day, nothing needed”
245. is worth more than a blank.</p>`
246. case 'stale':
247. return `<p class="ci-banner ci-bad">That page was open from an earlier day, so nothing was
248. saved rather than filed against the wrong one. Reload and it will be ${label} again.</p>`
249. case 'failed':
250. return `<p class="ci-banner ci-bad">The note was <b>not</b> saved; the store refused the
251. write. Copy what you typed somewhere before you reload.</p>`
252. }
253. }
255. /** One question's box. `value` pre-fills an edit. */
256. function questionField(
257. q: (typeof CHECKIN_QUESTIONS)[number],
258. value: string,
259. autofocus: boolean,
260. ): string {
261. return `<div class="ci-field">
262. <label class="ci-q" for="ci-${q.id}">${esc(q.prompt)}</label>
263. <textarea class="ci-input" id="ci-${q.id}" name="${q.id}" rows="3"
264. maxlength="${CHECKIN_FIELD_CAP}" placeholder="${esc(q.placeholder)}"
265. ${autofocus ? 'autofocus' : ''}>${esc(value)}</textarea>
266. </div>`
267. }
269. /**
270. * The author's card: her form, plus what she has already written.
271. *
272. * Folded before the hour, never locked. The note is for the end of the day,
273. * so before 4 PM the card is shut and says so. It still
274. * opens, and a submission at 2 PM is accepted: a form that refuses text
275. * somebody has already typed is a form that throws it away, and there is no
276. * version of this feature where losing what she wrote is the safe outcome.
277. */
278. function authorCard(
279. store: CheckinStore,
280. day: string,
281. now: Date,
282. outcome: CheckinOutcome | null,
283. ): string {
284. const today = store.state === 'ok' ? store.notes.find((n) => n.day === day) : undefined
285. const open = checkinIsOpen(now)
286. const hour12 = CHECKIN_OPENS_AT_HOUR % 12 || 12
287. const openLabel = `${hour12}:00 ${CHECKIN_OPENS_AT_HOUR < 12 ? 'AM' : 'PM'}`
288. const writable = store.state === 'ok'
289. // A note typed after midnight is about yesterday, and it says so where she can
290. // see it. Otherwise the only clue is a date she is not looking at.
291. const backdated = day !== localDay(now)
292. const mine =
293. store.state === 'ok' ? store.notes.filter((n) => n.day !== day).slice(0, 5) : []
295. return `<div class="card ci-card">
296. <div class="rule"></div>
297. <div class="ci-head">
298. <div>
299. <div class="eyebrow">End of day</div>
300. <h1 class="ci-title">Your three lines for ${esc(calendarDate(day))}</h1>
301. </div>
302. <span class="ci-chip ${today ? 'ci-done' : open ? 'ci-due' : ''}">${
303. today ? 'written' : open ? 'not written yet' : `opens at ${esc(openLabel)}`
304. }</span>
305. </div>
306. <div class="ci-body">
307. <p class="ci-intro">What you did, what you are unsure about, what you need. It takes two
308. minutes and it means nobody has to hover, and a question you write down tonight gets
309. answered tomorrow instead of in three weeks.
310. ${
311. // Who reads it, on the form itself. Somebody answering "what I'm
312. // unsure about" honestly is entitled to know exactly who sees it,
313. // before they type rather than after.
314. `Read by ${esc(CHECKIN_READERS.length === 1 ? 'one person' : `${CHECKIN_READERS.length} people`)}:
315. ${esc(CHECKIN_READERS.join(', '))}. Nobody else on the board can see this card at all.`
316. }
317. </p>
318. ${outcomeBanner(outcome, day)}
319. ${storeBanner(store)}
320. ${
321. backdated
322. ? `<p class="ci-banner">It is past midnight, so this is <b>${esc(calendarDate(day))}</b>'s
323. note: the day that just ended, not the one that just started.</p>`
324. : ''
325. }
326. ${
327. writable
328. ? `<details class="ci-form-wrap" ${open || today ? 'open' : ''}>
329. <summary class="ci-summary">${
330. today ? 'Edit tonight’s note' : open ? 'Write it' : 'Finishing early? Write it now'
331. }</summary>
332. <form method="post" action="/checkin" class="ci-form">
333. <input type="hidden" name="day" value="${esc(day)}">
334. ${map(CHECKIN_QUESTIONS, (q, i) =>
335. questionField(q, today ? String(today[q.id]) : '', i === 0 && open && !today),
336. )}
337. <div class="ci-bar">
338. <button type="submit" class="ci-save">${today ? 'Update the note' : 'Save the note'}</button>
339. <span class="ci-hint">${
340. today
341. ? 'Edits are kept. The earlier version stays on the record and is visible to the same two people.'
342. : 'One box is enough if that is the honest answer. An all-blank note is not saved.'
343. }</span>
344. </div>
345. </form>
346. </details>`
347. : // The store could not be read. The form is still rendered: a read
348. // failure is not a write failure, and hiding the boxes guarantees
349. // the loss that showing them only risks.
350. `<details class="ci-form-wrap" open>
351. <summary class="ci-summary">Write it anyway</summary>
352. <form method="post" action="/checkin" class="ci-form">
353. <input type="hidden" name="day" value="${esc(day)}">
354. ${map(CHECKIN_QUESTIONS, (q) => questionField(q, '', false))}
355. <div class="ci-bar">
356. <button type="submit" class="ci-save">Save the note</button>
357. <span class="ci-hint">The store would not answer a read just now, so this may not
358. save either. Keep a copy of anything long until you see it land.</span>
359. </div>
360. </form>
361. </details>`
362. }
363. ${
364. mine.length
365. ? `<div class="ci-mine">
366. <h3 class="ci-sub">What you wrote before</h3>
367. ${map(mine, (n) => noteBlock(n, []))}
368. </div>`
369. : ''
370. }
371. </div>
372. </div>`
373. }
375. /** One written note, with its questions as headings. */
376. function noteBlock(note: CheckinNote, earlier: CheckinRevision[]): string {
377. const prior = earlier
378. .filter((r) => r.day === note.day && r.revision < note.revisions)
379. .sort((a, b) => b.revision - a.revision)
380. return `<div class="ci-note">
381. <div class="ci-note-head">
382. <span class="ci-day">${esc(calendarDate(note.day))}</span>
383. <span class="ci-when">${esc(localStamp(note.submittedAt))}</span>
384. ${
385. note.revisions > 1
386. ? `<span class="ci-chip">edited &middot; ${note.revisions} versions</span>`
387. : ''
388. }
389. </div>
390. ${map(CHECKIN_QUESTIONS, (q) => `<div class="ci-a">
391. <div class="ci-a-label">${esc(q.label)}</div>
392. ${answerHtml(String(note[q.id]))}
393. </div>`)}
394. ${
395. prior.length
396. ? `<details class="ci-prior">
397. <summary>What it said before</summary>
398. ${map(prior, (r) => `<div class="ci-note ci-old">
399. <div class="ci-note-head">
400. <span class="ci-day">version ${r.revision}</span>
401. <span class="ci-when">${esc(localStamp(r.writtenAt))}</span>
402. </div>
403. ${map(CHECKIN_QUESTIONS, (q) => `<div class="ci-a">
404. <div class="ci-a-label">${esc(q.label)}</div>
405. ${answerHtml(String(r[q.id]))}
406. </div>`)}
407. </div>`)}
408. </details>`
409. : ''
410. }
411. </div>`
412. }
414. /**
415. * The readers' card: one row per day, including the days with nothing in them.
416. *
417. * The empty rows are the feature. A log of the notes that exist can say what
418. * she wrote; only a log of the days can say she stopped writing on Tuesday,
419. * which is what a reader is looking for.
420. */
421. function readerCard(person: string, store: CheckinStore, day: string, now: Date): string {
422. const from = checkinExpectedFrom(person)
423. const notes = store.state === 'ok' ? store.notes : []
424. const byDay = new Map(notes.map((n) => [n.day, n]))
425. const earlier = store.state === 'ok' ? store.earlier : []
427. // The days a note was expected: weekdays, back to the day the habit began.
428. const expected = expectedDays(day, from)
429. const oldest = expected[expected.length - 1] ?? day
430. // Plus any day inside that window that has a note but was not expected: a
431. // Saturday she worked. Fetched and then not shown is exactly the bug shape
432. // rule 9 describes, and a weekend note is the one somebody most wants read.
433. const extra = notes
434. .map((n) => n.day)
435. .filter((d) => d <= day && d >= oldest && !expected.includes(d))
436. const days = [...new Set([...expected, ...extra])].sort().reverse()
438. // Today is not a missed day until the day is over. Before the form even
439. // opens, "no note yet" is the correct and uninteresting answer.
440. const pending = !byDay.has(day) && !checkinIsOpen(now)
441. const written = days.filter((d) => byDay.has(d)).length
442. const missed = expected.filter((d) => !byDay.has(d) && !(d === day && pending)).length
444. return `<div class="card ci-card">
445. <div class="rule"></div>
446. <div class="ci-head">
447. <div>
448. <div class="eyebrow">End of day &middot; ${esc(person)}</div>
449. <h1 class="ci-title">What she did, what she is unsure about, what she needs</h1>
450. </div>
451. ${
452. // The count and the list under it must account for each other (rule 9).
453. // Every day in these two numbers is a row below.
454. store.state === 'ok' && days.length
455. ? `<span class="ci-chip ${missed ? 'ci-due' : 'ci-done'}">${written} written &middot; ${missed} weekday${
456. missed === 1 ? '' : 's'
457. } missed</span>`
458. : ''
459. }
460. </div>
461. <div class="ci-body">
462. <p class="ci-intro">Her own words, the evening she wrote them. Visible to you and
463. ${esc(CHECKIN_READERS.length - 1 === 1 ? 'one other person' : `${CHECKIN_READERS.length - 1} other people`)}
464. and nobody else, including the people who can see her onboarding plan.</p>
465. ${storeBanner(store)}
466. ${
467. store.state !== 'ok'
468. ? '' // The banner said what happened. A list here would be a claim.
469. : !from
470. ? `<p class="ci-empty">${esc(person)} has no onboarding plan, so no note has been
471. asked for. This is not a run of missed days.</p>`
472. : !days.length
473. ? `<p class="ci-empty">Nothing has been asked for yet. The daily note starts
474. ${esc(calendarDate(from))}.</p>`
475. : map(days, (d) => {
476. const note = byDay.get(d)
477. if (note) return noteBlock(note, earlier)
478. return `<div class="ci-note ci-none">
479. <div class="ci-note-head">
480. <span class="ci-day">${esc(calendarDate(d))}</span>
481. <span class="ci-when">${
482. d === day && pending
483. ? 'not written yet; the day is not over'
484. : 'no note'
485. }</span>
486. </div>
487. </div>`
488. })
489. }
490. </div>
491. </div>`
492. }
494. /**
495. * The whole block for one viewer: a form, a log, both, or nothing.
496. *
497. * Nothing is the default. A viewer with no grant gets an empty string, and the
498. * caller writes an empty string into the page: not a hidden div, not a
499. * disabled card. Anything behind `hidden` is readable from view-source.
500. */
501. export function checkinBlock(
502. viewer: Viewer,
503. stores: Record<string, CheckinStore>,
504. now: Date = new Date(),
505. outcome: CheckinOutcome | null = null,
506. ): string {
507. const day = checkinDay(now)
508. const own = checkinAuthorFor(viewer)
509. const readable = readableCheckinAuthors(viewer)
510. if (!readable.length && !own) return ''
512. const missing: CheckinStore = { state: 'failed', error: 'no answer from the store' }
513. return join([
514. own && canWriteCheckin(viewer)
515. ? authorCard(stores[own] ?? missing, day, now, outcome)
516. : '',
517. // A reader's own card is the form above, which already lists what she wrote.
518. ...readable
519. .filter((p) => p !== own)
520. .map((p) => readerCard(p, stores[p] ?? missing, day, now)),
521. ])
522. }
524. /**
525. * The markers the Worker replaces at serve time.
526. *
527. * A placeholder and not a rendered card, because Every page on this board is
528. * pre-rendered by a cron and read back out of KV, so a card rendered at sync
529. * time would show a form for a day that had not started and a log missing
530. * everything written since. The theme stamp, the notes injection and the sync
531. * line all solve this the same way.
532. *
533. * The fallback between them is not empty, deliberately. `pnpm dashboard` writes
534. * a file with no Worker behind it, and an empty div there is a feature that
535. * silently is not there (rule 8). The text says which is which.
536. */
537. export const CHECKIN_START = '<!--checkin:start-->'
538. export const CHECKIN_END = '<!--checkin:end-->'
540. export const checkinPlaceholder = (): string =>
541. `${CHECKIN_START}<div class="card ci-card"><div class="rule"></div>
542. <div class="ci-body"><p class="ci-empty"><b>The end-of-day note lives on the live board.</b>
543. This copy was rendered to a file, which has no way to read the note store or accept a
544. form. Open the deployed board to write or read one.</p></div>
545. </div>${CHECKIN_END}`
547. /**
548. * Swap the placeholder for the real block. A page without the markers is
549. * returned untouched, which is what a viewer with no grant gets.
550. */
551. export function stampCheckin(html: string, block: string): string {
552. const from = html.indexOf(CHECKIN_START)
553. if (from === -1) return html
554. const to = html.indexOf(CHECKIN_END, from)
555. if (to === -1) return html
556. return html.slice(0, from) + block + html.slice(to + CHECKIN_END.length)
557. }