# 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.

Web page: https://candor.themethodic.com/patterns/journal-entry

## Components

- **Timeline item** (`timeline-item`, Pro; https://candor.themethodic.com/docs/timeline-item.md): Each entry: the kind as a badge, the author and time, the text, and the decision's buttons in `actions` (Pro).
- **Consequence list** (`consequence-list`, Pro; https://candor.themethodic.com/docs/consequence-list.md): What 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 dialog** (`alert-dialog`, Pro; https://candor.themethodic.com/docs/alert-dialog.md): The confirm step for Undo: focus starts on the button that keeps the decision, and Escape keeps it too.
- **Button** (`button`, free; https://candor.themethodic.com/docs/button.md): Keep, Change… and Undo….

## Install

```bash
npx candor-ui@4 add timeline-item consequence-list alert-dialog
```

## Code

`journal.tsx`: The journal: each kind's word as the badge, the author and time, and Keep, Change… and Undo… on decisions.

```tsx
"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>
  )
}

```

## Notes

- An assumption, finding or recommendation an agent wrote is its own account: name the agent as `actor` and 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.
