Public: anyone can read this; the crew can change it.

Each deal shows how far along it is, as "4 of 7 dates done · closes in 12 days", on the clock and its page #87

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

mason/deal-clock:mason/81-each-deal-shows-how-far-along-it-is-as-4 → main 1 commit fork

  • Merged. mason/81-each-deal-shows-how-far-along-it-is-as-4 was merged into main as 57c8f42.

Review

Sign in to review this change.
10 files changed +474 −7
contract/openapi.json +283 −3
@@ -511,7 +511,7 @@
511511 },
512512 "/api/deals/{id}": {
513513 "get": {
514 "summary": "One deal.",
514 "summary": "One deal, with its progress: dates done, total, overdue and days to closing.",
515515 "operationId": "getApiDealsId",
516516 "parameters": [
517517 {
@@ -525,11 +525,291 @@
525525 ],
526526 "responses": {
527527 "200": {
528 "description": "One deal.",
528 "description": "One deal, with its progress: dates done, total, overdue and days to closing.",
529529 "content": {
530530 "application/json": {
531531 "schema": {
532 "$ref": "#/components/schemas/Deal"
532 "type": "object",
533 "properties": {
534 "id": {
535 "type": "integer"
536 },
537 "address": {
538 "type": "string"
539 },
540 "contract_date": {
541 "type": "string",
542 "format": "date"
543 },
544 "closing": {
545 "type": "string",
546 "format": "date"
547 },
548 "closed": {
549 "type": "boolean",
550 "description": "The Closing date is marked done; the deal is off the clock."
551 },
552 "business_days": {
553 "enum": [
554 0,
555 1
556 ]
557 },
558 "author_id": {
559 "type": "string"
560 },
561 "author_name": {
562 "type": "string"
563 },
564 "created_at": {
565 "type": "string",
566 "format": "date-time"
567 },
568 "parties": {
569 "type": "array",
570 "items": {
571 "type": "object",
572 "properties": {
573 "id": {
574 "type": "integer"
575 },
576 "role": {
577 "enum": [
578 "buyer",
579 "seller",
580 "lender",
581 "title",
582 "other_agent"
583 ]
584 },
585 "name": {
586 "type": "string"
587 },
588 "contact": {
589 "type": "string"
590 }
591 }
592 }
593 },
594 "deadlines": {
595 "type": "array",
596 "items": {
597 "type": "object",
598 "properties": {
599 "id": {
600 "type": "integer"
601 },
602 "kind": {
603 "enum": [
604 "inspection",
605 "appraisal",
606 "financing",
607 "title",
608 "walkthrough",
609 "closing",
610 "custom"
611 ]
612 },
613 "label": {
614 "type": "string"
615 },
616 "due": {
617 "type": "string",
618 "format": "date"
619 },
620 "owes": {
621 "enum": [
622 "buyer",
623 "seller",
624 "lender",
625 "title",
626 "other_agent"
627 ]
628 },
629 "what": {
630 "type": "string"
631 },
632 "done_at": {
633 "type": [
634 "string",
635 "null"
636 ]
637 },
638 "moves": {
639 "type": "array",
640 "items": {
641 "type": "object"
642 }
643 }
644 }
645 }
646 },
647 "conflicts": {
648 "type": "array",
649 "description": "Open dates (not Closing) due on or after the open Closing date: a slipped contingency. Empty when the deal is in order or closed.",
650 "items": {
651 "type": "object",
652 "properties": {
653 "deadline_id": {
654 "type": "integer"
655 },
656 "label": {
657 "type": "string"
658 },
659 "due": {
660 "type": "string",
661 "format": "date"
662 },
663 "closing": {
664 "type": "string",
665 "format": "date"
666 }
667 },
668 "required": [
669 "deadline_id",
670 "label",
671 "due",
672 "closing"
673 ]
674 }
675 },
676 "declined": {
677 "type": "array",
678 "items": {
679 "type": "object",
680 "properties": {
681 "id": {
682 "type": "integer"
683 },
684 "deadline_id": {
685 "type": "integer"
686 },
687 "party_id": {
688 "type": "integer"
689 },
690 "moment": {
691 "enum": [
692 "before",
693 "day_of",
694 "late",
695 "moved"
696 ]
697 },
698 "due": {
699 "type": "string",
700 "format": "date"
701 },
702 "reason": {
703 "type": "string",
704 "description": "Why the agent chose not to send it."
705 },
706 "by_name": {
707 "type": "string"
708 },
709 "at": {
710 "type": "string"
711 }
712 }
713 }
714 },
715 "sent": {
716 "type": "array",
717 "description": "The Messages record: every reminder marked sent, newest first, with the words as approved. The date's label and the party's name and role are kept as they were, so an entry reads the same after either is removed.",
718 "items": {
719 "type": "object",
720 "properties": {
721 "id": {
722 "type": "integer"
723 },
724 "deadline_id": {
725 "type": "integer"
726 },
727 "party_id": {
728 "type": "integer"
729 },
730 "label": {
731 "type": "string",
732 "description": "The date it was about, as named when sent."
733 },
734 "party_name": {
735 "type": "string"
736 },
737 "party_role": {
738 "type": "string",
739 "description": "The party's role when sent; empty on a reminder sent before roles were kept."
740 },
741 "moment": {
742 "enum": [
743 "before",
744 "day_of",
745 "late",
746 "moved"
747 ]
748 },
749 "due": {
750 "type": "string",
751 "format": "date"
752 },
753 "by_name": {
754 "type": "string"
755 },
756 "sent_at": {
757 "type": "string"
758 },
759 "subject": {
760 "type": "string",
761 "description": "The subject that was sent, as approved."
762 },
763 "body": {
764 "type": "string",
765 "description": "The message that was sent, as approved."
766 },
767 "href": {
768 "type": [
769 "string",
770 "null"
771 ],
772 "description": "A mailto: or sms: link that opens the party's own Mail or Messages with these words; null when the party has no email or phone on file, or is gone."
773 }
774 }
775 }
776 },
777 "progress": {
778 "type": "object",
779 "properties": {
780 "done": {
781 "type": "integer"
782 },
783 "total": {
784 "type": "integer"
785 },
786 "overdue": {
787 "type": "integer",
788 "description": "Open dates past due."
789 },
790 "days_to_closing": {
791 "type": "integer",
792 "description": "Negative once the closing date has passed."
793 }
794 },
795 "required": [
796 "done",
797 "total",
798 "overdue",
799 "days_to_closing"
800 ]
801 }
802 },
803 "required": [
804 "id",
805 "address",
806 "contract_date",
807 "closing",
808 "closed",
809 "parties",
810 "deadlines",
811 "progress"
812 ]
533813 }
534814 }
535815 }
docs/design/areas/clock.md added +7
@@ -0,0 +1,7 @@
1 # Clock
2
3 New classes:
4
5 - `.progress-text` — the "4 of 7 dates done · 1 overdue · closes …" words under a deal's name, on its lane and on its page.
6 - `.progress-bar` — a thin decorative bar (`aria-hidden`) of fixed height under that text, filled to the share of dates done; the text carries the meaning.
7 - `.progress` — the paragraph that holds both at the top of a deal's page.
src/pages/clock.ts +3 −2
@@ -5,7 +5,7 @@
55 * clock, the reminders that go out today.
66 */
77
8 import { addDays, daysBetween, isWeekend, relative, short, spoken, urgency } from "../dates.ts";
8 import { addDays, daysBetween, isWeekend, short, spoken, urgency } from "../dates.ts";
99 import type { DealView } from "../deals.ts";
1010 import { KIND } from "../deadlines.ts";
1111 import { escape } from "../http.ts";
@@ -18,6 +18,7 @@ import { mayRestore } from "../actions.ts";
1818 import { badge, draftLink, opens, owedBy, URGENCY_LABEL } from "./sheet.ts";
1919 import { find } from "../find.ts";
2020 import { memoizer, print } from "../memo.ts";
21 import { progressLine } from "./progress.ts";
2122
2223 /** The days the clock shows: a week behind today (further, if something open is older), to a few days past the last closing. */
2324 export function span(deals: readonly DealView[], on: string): { start: string; days: number } {
@@ -65,7 +66,7 @@ function drawLane(deal: DealView, start: string, on: string): string {
6566 })
6667 .join("");
6768 return `<li class="lane">
68 <div class="lane-head"><a href="/deals/${deal.id}">${escape(deal.address)}</a> <small class="muted">${deal.conflicts.length === 0 ? "" : `<b class="u-overdue">${deal.conflicts.length} out of order</b> · `}closes ${escape(spoken(deal.closing))} · ${escape(relative(deal.closing, on))}</small></div>
69 <div class="lane-head"><a href="/deals/${deal.id}">${escape(deal.address)}</a> <small class="muted">${deal.conflicts.length === 0 ? "" : `<b class="u-overdue">${deal.conflicts.length} out of order</b> · `}${progressLine(deal, on)}</small></div>
6970 <div class="track" style="height:calc(${height} * 3rem)">${markers}</div>
7071 </li>`;
7172 }
src/pages/deal.ts +2
@@ -15,6 +15,7 @@ import { amendForm, type AmendState } from "./amend.ts";
1515 import { partyContact } from "./contact.ts";
1616 import { confirmRemove } from "./confirm.ts";
1717 import { layout } from "./layout.ts";
18 import { progressLine } from "./progress.ts";
1819 import { badge, conflictLines, dueLine, outboxLine, owedBy, sheet, sheetId } from "./sheet.ts";
1920
2021 const roleOptions = (selected?: string): string =>
@@ -144,6 +145,7 @@ export function dealPage(input: {
144145 <div class="row"><a class="button button-quiet" href="${path}/timeline">Client timeline</a> <a class="button button-quiet" href="${path}/ics" download>Add to calendar</a></div>
145146 </section>
146147 <div id="deal" data-live="deal.changed">
148 <p class="progress">${progressLine(deal, on)}</p>
147149 <section class="card">
148150 <h2>Dates</h2>
149151 ${conflictLines(deal)}
src/pages/progress.ts added +21
@@ -0,0 +1,21 @@
1 /** The progress line and bar a deal wears on the clock and on its own page. */
2
3 import { relative, spoken } from "../dates.ts";
4 import { closedOn, type DealView } from "../deals.ts";
5 import { escape } from "../http.ts";
6 import { progress } from "../progress.ts";
7
8 /** "4 of 7 dates done · 1 overdue · closes …", or "All done · closed …" once the deal has closed. */
9 export function progressText(deal: DealView, on: string): string {
10 if (deal.closed) return `All done · closed ${spoken(closedOn(deal))}`;
11 const p = progress(deal, on);
12 const overdue = p.overdue > 0 ? ` · ${p.overdue} overdue` : "";
13 return `${p.done} of ${p.total} dates done${overdue} · closes ${spoken(deal.closing)}, ${relative(deal.closing, on)}`;
14 }
15
16 /** The text, then a decorative bar of fixed height: the words carry the meaning. */
17 export function progressLine(deal: DealView, on: string): string {
18 const p = progress(deal, on);
19 const pct = deal.closed || p.total === 0 ? (deal.closed ? 100 : 0) : Math.round((p.done / p.total) * 100);
20 return `<span class="progress-text">${escape(progressText(deal, on))}</span><span class="progress-bar" aria-hidden="true"><span style="width:${pct}%"></span></span>`;
21 }
src/progress.test.ts added +80
@@ -0,0 +1,80 @@
1 /** Progress: the numbers, and the line the clock, the deal page and the API show. */
2 import { expect, test } from "bun:test";
3 import { mkdtempSync } from "node:fs";
4 import { tmpdir } from "node:os";
5 import { join } from "node:path";
6 import { addDeadline, createDeal, getDeal, markDone, removeDeadline, type DealView } from "./deals.ts";
7 import { openDb } from "./db.ts";
8 import { clock } from "./pages/clock.ts";
9 import { dealPage } from "./pages/deal.ts";
10 import { progressText } from "./pages/progress.ts";
11 import { progress } from "./progress.ts";
12 import type { Who } from "./who.ts";
13
14 const db = openDb(mkdtempSync(join(tmpdir(), "app-progress-")));
15 const alice: Who = { role: "user", id: "u1", name: "alice" };
16 const on = "2026-10-10";
17
18 const open = (): number => {
19 const made = createDeal(db, alice, { address: "3 Progress Way", buyer: "B", seller: "S", contractDate: "2026-10-01", closingDate: "2026-10-22" });
20 if (!made.ok) throw new Error(made.message);
21 return made.value.id;
22 };
23 const read = (id: number): DealView => {
24 const got = getDeal(db, alice, { id });
25 if (!got.ok) throw new Error(got.message);
26 return got.value;
27 };
28
29 test("no dates: nothing done, nothing overdue", () => {
30 expect(progress({ deadlines: [], closing: "2026-10-22" }, on)).toEqual({ done: 0, total: 0, overdue: 0, days_to_closing: 12 });
31 });
32
33 test("some done, some overdue, a removed date not counted, a reopened one lowers the count", () => {
34 const id = open();
35 const base = read(id);
36 const total = base.deadlines.length;
37 const late = base.deadlines.filter((d) => d.due < on).length;
38 expect(progress(base, on)).toEqual({ done: 0, total, overdue: late, days_to_closing: 12 });
39 const extra = addDeadline(db, alice, { dealId: id, label: "Late thing", due: "2026-10-05", owes: "buyer", what: "" });
40 if (!extra.ok) throw new Error(extra.message);
41 expect(progress(read(id), on)).toMatchObject({ total: total + 1, overdue: late + 1 });
42 markDone(db, alice, { id: extra.value.id, done: true });
43 expect(progress(read(id), on)).toMatchObject({ done: 1, overdue: late });
44 markDone(db, alice, { id: extra.value.id, done: false });
45 expect(progress(read(id), on)).toMatchObject({ done: 0, overdue: late + 1 });
46 removeDeadline(db, alice, { dealId: id, id: extra.value.id });
47 expect(progress(read(id), on)).toMatchObject({ done: 0, total, overdue: late });
48 });
49
50 test("the clock and the deal page print the line and a decorative bar", () => {
51 const id = open();
52 const first = read(id).deadlines[0]!;
53 markDone(db, alice, { id: first.id, done: true });
54 const deal = read(id);
55 const p = progress(deal, on);
56 const line = `${p.done} of ${p.total} dates done`;
57 expect(progressText(deal, on)).toContain(line);
58 expect(progressText(deal, on)).toContain("closes");
59 const c = clock({ who: alice, deals: [deal], on });
60 expect(c).toContain(line);
61 expect(c).toContain('class="progress-bar" aria-hidden="true"');
62 const d = dealPage({ who: alice, deal, on });
63 expect(d).toContain(line);
64 expect(d).toContain('class="progress-bar" aria-hidden="true"');
65 });
66
67 test("overdue shows only when there is some; a closed deal reads All done", () => {
68 const id = open();
69 const deal = read(id);
70 const p = progress(deal, "2026-12-01");
71 expect(p.overdue).toBeGreaterThan(0);
72 expect(progressText(deal, "2026-12-01")).toContain(`· ${p.overdue} overdue`);
73 expect(progressText(deal, "2026-10-02")).not.toContain("overdue");
74 for (const d of deal.deadlines) markDone(db, alice, { id: d.id, done: true });
75 const closed = read(id);
76 expect(closed.closed).toBe(true);
77 expect(progressText(closed, on)).toStartWith("All done · closed ");
78 expect(progress(closed, on)).toMatchObject({ done: closed.deadlines.length, overdue: 0 });
79 });
80
src/progress.ts added +34
@@ -0,0 +1,34 @@
1 /**
2 * How far along a deal is: dates done of dates total, how many open ones are
3 * overdue, and the days to closing. Plain data in, plain data out; the clock,
4 * the deal page and the API all read it from here.
5 */
6
7 import { daysBetween } from "./dates.ts";
8 import type { DealView } from "./deals.ts";
9
10 export interface Progress {
11 readonly done: number;
12 readonly total: number;
13 readonly overdue: number;
14 /** Days from `on` to the closing date; negative once it has passed. */
15 readonly days_to_closing: number;
16 }
17
18 export function progress(
19 deal: Pick<DealView, "deadlines" | "closing">,
20 on: string,
21 ): Progress {
22 let done = 0;
23 let overdue = 0;
24 for (const d of deal.deadlines) {
25 if (d.done_at !== null) done++;
26 else if (d.due < on) overdue++;
27 }
28 return {
29 done,
30 total: deal.deadlines.length,
31 overdue,
32 days_to_closing: daysBetween(on, deal.closing),
33 };
34 }
src/routes.ts +21 −2
@@ -39,6 +39,7 @@ import {
3939 import type { Verb } from "./can.ts";
4040 import { events } from "./live.ts";
4141 import { today } from "./dates.ts";
42 import { progress } from "./progress.ts";
4243 import {
4344 addDeadline,
4445 addParty,
@@ -165,6 +166,16 @@ export const PERSON: Schema = {
165166 },
166167 },
167168 };
169 const PROGRESS: Schema = {
170 type: "object",
171 properties: {
172 done: { type: "integer" },
173 total: { type: "integer" },
174 overdue: { type: "integer", description: "Open dates past due." },
175 days_to_closing: { type: "integer", description: "Negative once the closing date has passed." },
176 },
177 required: ["done", "total", "overdue", "days_to_closing"],
178 };
168179 export const DEAL: Schema = {
169180 type: "object",
170181 properties: {
@@ -257,6 +268,11 @@ export const DEAL: Schema = {
257268 },
258269 required: ["id", "address", "contract_date", "closing", "closed", "parties", "deadlines"],
259270 };
271 const DEAL_PROGRESS: Schema = {
272 ...DEAL,
273 properties: { ...DEAL.properties, progress: PROGRESS },
274 required: [...(DEAL.required ?? []), "progress"],
275 };
260276 const NEW_DEAL: Schema = {
261277 type: "object",
262278 properties: {
@@ -995,8 +1011,11 @@ export const routes: readonly Route[] = [
9951011 {
9961012 method: "GET",
9971013 path: "/api/deals/:id",
998 handle: (c) => answer(getDeal(c.db, c.who, { id: Number(c.params.id) })),
999 api: { summary: "One deal.", answer: DEAL },
1014 handle: (c) => {
1015 const found = getDeal(c.db, c.who, { id: Number(c.params.id) });
1016 return answer(found.ok ? { ok: true, value: { ...found.value, progress: progress(found.value, today()) } } : found);
1017 },
1018 api: { summary: "One deal, with its progress: dates done, total, overdue and days to closing.", answer: DEAL_PROGRESS },
10001019 },
10011020 {
10021021 method: "PATCH",
src/server.test.ts +2
@@ -131,6 +131,8 @@ test("the JSON API is the same actions with the same identity", async () => {
131131 const deal = (await created.json()) as { id: number; author_name: string };
132132 expect(deal.author_name).toBe("alice");
133133 expect((await fetch(base + "/api/deals")).status).toBe(401);
134 const one = (await (await api(`/api/deals/${deal.id}`, {}, bob)).json()) as { progress: Record<string, number> };
135 expect(Object.keys(one.progress).sort()).toEqual(["days_to_closing", "done", "overdue", "total"]);
134136 const listed = (await (await api("/api/deals", {}, bob)).json()) as {
135137 id: number;
136138 }[];
static/app.css +21
@@ -941,6 +941,27 @@ a.marker {
941941 }
942942
943943 /* On paper: only the client timeline changes — black on white, no tools, no row split. */
944 .progress-text {
945 display: block;
946 }
947 .progress-bar {
948 display: block;
949 height: 0.25rem;
950 margin-top: var(--space-1);
951 background: var(--color-line);
952 border-radius: var(--radius-pill);
953 overflow: hidden;
954 }
955 .progress-bar > span {
956 display: block;
957 height: 100%;
958 background: var(--color-fg);
959 }
960 .progress {
961 margin: 0 0 var(--space-3);
962 max-width: 24rem;
963 }
964
944965 @media print {
945966 .timeline-page {
946967 background: white;

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs