Patterns / Journal entry
A journal of decisions, assumptions and findings
Long work leaves a trail of calls: what was decided, what was assumed to keep going, what was found on the way. A journal puts them in order so a person can read back why things are as they are, and change a decision they disagree with.
Each entry is a TimelineItem. Its badge is the kind in your words ("Decision", "Assumption", "Finding"), outlined and read after the title; the icon only repeats it. actor names who wrote it, a person or the agent by the name your app gives it, and time is when (null says "Time not recorded").
A decision gets actions: Keep and Change… as equal buttons, neither pre-selected, and Undo…. Undo opens an AlertDialog whose ConsequenceList says what undoing stops and what can't be taken back, before anything happens. The actions sit after the entry's text, outside its title and time, so a screen reader reads the entry first.
The components
- Timeline itemProEach entry: the kind as a badge, the author and time, the text, and the decision's buttons in `actions` (Pro).
- Consequence listProWhat undoing a decision stops and what can't be undone, in the confirm dialog; when your server hasn't said, it says so (Pro).
- Alert dialogProThe confirm step for Undo: focus starts on the button that keeps the decision, and Escape keeps it too.
- ButtonFreeKeep, Change… and Undo….
See it working
The code
The journal: each kind's word as the badge, the author and time, and Keep, Change… and Undo… on decisions.
"use client"
import { CircleHelp, Gavel, Search, StickyNote, type LucideIcon } from "lucide-react"
import { Timeline, TimelineItem } from "@/components/candor/timeline-item"
import { ConsequenceList } from "@/components/candor/consequence-list"
import { Button } from "@/components/candor/ui/button"
import {
AlertDialog,
AlertDialogAction,
AlertDialogCancel,
AlertDialogContent,
AlertDialogDescription,
AlertDialogFooter,
AlertDialogHeader,
AlertDialogTitle,
AlertDialogTrigger,
} from "@/components/candor/ui/alert-dialog"
/** One entry in your journal, from your server. */
type JournalEntry = {
id: string
kind: "decision" | "assumption" | "finding" | "note"
/** What was decided, assumed or found. An agent's entry is its own account, drawn as text. */
text: string
/** Who wrote it, named by your app: a person, or the agent by the name your app gives it. */
author: string
/** When it was written; null when your records don't say. */
at: string | null
/** For a decision, from your server: what undoing it stops, and what stays done (null when it hasn't said). */
undo?: { stops: string[]; irreversible: string[] | null } | undefined
}
/** Your kinds: the word is the badge, and the icon only repeats it. */
const kinds: Record<JournalEntry["kind"], { word: string; icon: LucideIcon }> = {
decision: { word: "Decision", icon: Gavel },
assumption: { word: "Assumption", icon: CircleHelp },
finding: { word: "Finding", icon: Search },
note: { word: "Note", icon: StickyNote },
}
export function Journal({ entries, onUndo, onKeep, onChange }: {
entries: JournalEntry[]
onUndo: (id: string) => Promise<void>
onKeep: (id: string) => void
/** Opens your editor for the decision, with the person's new answer still to be given. */
onChange: (id: string) => void
}) {
return (
<Timeline label="Journal">
{entries.map((entry) => (
<TimelineItem
key={entry.id}
icon={kinds[entry.kind].icon}
title={entry.text}
badge={kinds[entry.kind].word}
actor={entry.author}
time={entry.at}
actions={
entry.kind === "decision" ? (
<>
{/* Keep and Change sit as equal buttons: neither is the suggested answer. */}
<Button size="sm" variant="outline" onClick={() => onKeep(entry.id)}>
Keep
</Button>
<Button size="sm" variant="outline" onClick={() => onChange(entry.id)}>
Change…
</Button>
<UndoDecision entry={entry} onUndo={onUndo} />
</>
) : undefined
}
/>
))}
</Timeline>
)
}
/** Undo says what it stops and what can't be taken back before anything happens. */
function UndoDecision({ entry, onUndo }: { entry: JournalEntry; onUndo: (id: string) => Promise<void> }) {
return (
<AlertDialog>
<AlertDialogTrigger render={<Button size="sm" variant="ghost">Undo…</Button>} />
<AlertDialogContent>
<AlertDialogHeader>
<AlertDialogTitle>Undo this decision?</AlertDialogTitle>
<AlertDialogDescription>The question goes back to open, and the work that followed from it is checked again.</AlertDialogDescription>
</AlertDialogHeader>
<ConsequenceList stops={entry.undo?.stops} irreversible={entry.undo?.irreversible ?? null} />
<AlertDialogFooter>
<AlertDialogCancel>Keep the decision</AlertDialogCancel>
<AlertDialogAction variant="destructive" onClick={() => onUndo(entry.id)}>
Undo the decision
</AlertDialogAction>
</AlertDialogFooter>
</AlertDialogContent>
</AlertDialog>
)
}
Install
Each component brings in what it depends on. The free ones install as they are; Pro and Premium ones need a licence key.
Good to know
- An assumption, finding or recommendation an agent wrote is its own account: name the agent as
actorand pass its words as the title, which is drawn as text. - Keep the kinds' words in one place in your app, beside their icons, so the badge and the icon can't disagree.
- When your server can't say what undoing a decision leaves done, pass
irreversible={null}: the dialog says the app hasn't said, rather than implying nothing is lost.