Version Compare

Install

pnpm exec vegastack-design verify version-compare

pnpm dlx shadcn@4.21.0 add @vegastack/version-compare

Usage

VersionCompare is a document's history at full size, for DialogContent size="fullscreen": the selected version's text on the start side, the versions beside it, and the actions on the selected version in a footer that stays put while both sides scroll.

import {
  Dialog,
  DialogContent,
  DialogHeader,
  DialogTitle,
} from "@/components/ui/dialog";
import { VersionCompare } from "@/components/ui/version-compare";

<Dialog open={open} onOpenChange={setOpen}>
  <DialogContent size="fullscreen">
    <DialogHeader>
      <DialogTitle>History · Pricing v2</DialogTitle>
    </DialogHeader>
    <VersionCompare
      versions={versions}
      currentId={versions[0]?.id}
      selectedId={selected}
      onSelect={setSelected}
      showChanges={showChanges}
      onShowChangesChange={setShowChanges}
      preview={<MarkdownView typeScale="document">{text}</MarkdownView>}
      diff={showChanges ? { before: previousText, after: text } : null}
      actions={
        <>
          <Button variant="outline" onClick={copy}>
            Copy
          </Button>
          <Button onClick={restore}>Restore this version</Button>
        </>
      }
    />
  </DialogContent>
</Dialog>;

• The list is a VersionList grouped by day: "Current", the kind badges, an agent's versions under the agent avatar (author.kind: "agent"), Named only (namedOnly, onNamedOnlyChange) and scroll paging (loadMore) pass straight through.
• The preview is preview, the host's own rendering of the selected version (MarkdownView, a read-only TextEdit). With "Show changes" on (showChanges, its switch shown when onShowChangesChange is set) and a diff given, the preview is a DiffView of the two texts instead; without a diff the host's preview stays, so a host can show its own formatted diff (TextEdit's diff view).
• toolbar sits beside "Show changes": a compare-with toggle, "Name this version".
• actions — Restore this version, Copy — sit in the footer.

The preview and the list share a ResizablePanels group: drag the handle to give the list more room (it keeps at least 240px). Below 640px one side shows at a time: the list first; a tap (or Enter) on a version pushes its preview in, with the actions, and a "Versions" button goes back.

A host that opens the history on one version — a "View changes" link to an agent's checkpoint — sets selectedId, showChanges and defaultPhoneView="preview", so a phone opens on that version's changes rather than the list; "Versions" still goes back. To drive the side itself, pass phoneView with onPhoneViewChange, which reports "preview" on a pick and "list" from the back button. A side the host sets moves no focus; a side the reader picks takes focus with it.

// Opened from "View changes" on a checkpoint: start on it, compared with now.
const [selected, setSelected] = React.useState(checkpointId);
const [showChanges, setShowChanges] = React.useState(true);

<VersionCompare
  versions={versions}
  selectedId={selected}
  onSelect={setSelected}
  showChanges={showChanges}
  onShowChangesChange={setShowChanges}
  diff={showChanges ? { before: textOf(selected), after: currentText } : null}
  defaultPhoneView="preview"
/>;

Examples

In a full-screen dialog

Its home: DialogContent size="fullscreen" fills the viewport less a 16px inset (the whole screen on a phone), so the dialog's header stays at the top and VersionCompare fills the rest.

API Reference

Accessibility

• The preview is a region named "Selected version" (previewLabel); the list is the VersionList listbox, each day a group named by its heading, one tab stop with the selection following the arrow keys.
• "Show changes" is a switch labelled by its text; the resize handle is a focusable separator.
• On a phone the back button is a labelled "Versions" button.

Do / Don't