Checkpoint
SaveA marker in a conversation that it can be restored to: a hairline divider with a label, the time, and a Restore action that asks for confirmation.
- Category
- AI elements
- Version
- 0.1.1
- Frameworks
- Next.js, Vite + React
- Styling
- Tailwind CSS v4
Preview
Checkpoint preview
Rename the users table to accounts and update the queries.
Before the table rename
Renamed the table in a new migration and updated 14 queries across 6 files. The tests pass.
Installation
npx @shakenui/cli add checkpointReview the plan first. A dry run lists every file and package without changing anything:
npx @shakenui/cli add checkpoint --dry-runUsage
checkpoint-example.tsx
"use client";
import { useState } from "react";
import { Checkpoint } from "@/components/shaken/agent/checkpoint";
export default function CheckpointExample() {
const [restored, setRestored] = useState(false);
return (
<div className="grid w-full max-w-lg gap-4 text-sm">
<p className="ml-auto max-w-[80%] rounded-xl bg-zinc-950/[0.04] px-3.5 py-2 text-zinc-950 dark:bg-white/[0.06] dark:text-white">
Rename the users table to accounts and update the queries.
</p>
<Checkpoint
label="Before the table rename"
time="14:32"
current={restored}
onRestore={() => new Promise((resolve) => setTimeout(resolve, 900)).then(() => setRestored(true))}
/>
{restored ? (
<button
type="button"
onClick={() => setRestored(false)}
className="justify-self-start rounded-md text-xs text-zinc-500 underline decoration-zinc-500/40 underline-offset-4 hover:text-zinc-950 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-sky-500 dark:hover:text-white"
>
Show the example again
</button>
) : (
<p className="leading-relaxed text-zinc-950 dark:text-white">
Renamed the table in a new migration and updated 14 queries across 6 files. The tests pass.
</p>
)}
</div>
);
}API
| Prop | Type | Default | Description |
|---|---|---|---|
| label | ReactNode | "Checkpoint" | What the checkpoint marks. |
| time | Date | string | — | A Date renders as a local time in a <time> element; a string is shown as is. |
| onRestore | () => void | Promise | — | Restores to this point. A promise keeps the confirm button busy; the confirmation closes on success and shows an error if it rejects. Without it, no action is shown. |
| confirm | boolean | true | Asks in a small popover before restoring. |
| confirmTitle / confirmDescription | ReactNode | — | Text of the confirmation. The default description names the time. |
| current | boolean | false | This is the state the conversation is in now; the action reads "Current". |
| disabled | boolean | false | Disables the action, for example while the agent runs. |
Accessibility
- The row is a group labeled "Checkpoint: <label>"; the divider lines are decorative.
- Restore opens a Base UI Popover that moves focus inside, closes with Escape, and returns focus to the trigger. It has a title and description wired to aria-labelledby and aria-describedby.
- While restoring, the confirm button is aria-busy and keeps its width; a failure is announced with role="alert".
- With reduced motion the popover appears without scale.
Files
Installed into src/components/shaken, or components/shaken when the project has no src directory.
src/components/shaken/agent/checkpoint.tsxcheckpoint- Also installs button@0.2.1registry dependency
- Also installs popover@0.2.2registry dependency
- npm packages: noneReact and Tailwind CSS v4 required
Source
The exact source the CLI installs, from /r/items/react/checkpoint/0.1.1.json.
agent/checkpoint.tsxShowHide
agent/checkpoint.tsx
"use client";
import { type ComponentProps, type ReactNode, useState } from "react";
import { Button } from "../ui/button";
import { Popover, PopoverClose, PopoverContent, PopoverDescription, PopoverTitle, PopoverTrigger } from "../ui/popover";
function cx(...classes: Array<string | false | null | undefined>) {
return classes.filter(Boolean).join(" ");
}
export interface CheckpointProps extends Omit<ComponentProps<"div">, "children" | "role"> {
/** What the checkpoint marks, for example "Before the schema change". @default "Checkpoint" */
label?: ReactNode;
/** When the checkpoint was taken. A Date shows as a local time ("14:32") in a `<time>` element. */
time?: Date | string;
/**
* Restores the conversation to this point. Return a promise to keep the confirm button busy
* until it settles; the confirmation closes when it resolves and stays open if it rejects.
* Without it, no restore action is shown.
*/
onRestore?: () => void | Promise<unknown>;
/** Asks before restoring. @default true */
confirm?: boolean;
/** Heading of the confirmation. @default "Restore this checkpoint?" */
confirmTitle?: ReactNode;
/** Body of the confirmation. Defaults to a sentence naming the time, if there is one. */
confirmDescription?: ReactNode;
/** Marks this checkpoint as the state the conversation is in now; the action reads "Current". */
current?: boolean;
/** Disables the restore action, for example while the agent is still running. */
disabled?: boolean;
}
function formatTime(time: Date | string | undefined) {
if (time == null) return null;
if (typeof time === "string") return { text: time, iso: undefined };
return {
text: time.toLocaleTimeString(undefined, { hour: "2-digit", minute: "2-digit" }),
iso: time.toISOString(),
};
}
/**
* A marker between messages that the conversation can go back to: a hairline divider with a
* label, the time, and a Restore action that asks for confirmation first.
*/
export function Checkpoint({
label = "Checkpoint",
time,
onRestore,
confirm = true,
confirmTitle = "Restore this checkpoint?",
confirmDescription,
current = false,
disabled = false,
className,
...props
}: CheckpointProps) {
const [open, setOpen] = useState(false);
const [busy, setBusy] = useState(false);
const [failed, setFailed] = useState(false);
const stamp = formatTime(time);
async function restore() {
if (!onRestore) return;
setFailed(false);
const result = onRestore();
if (!(result instanceof Promise)) {
setOpen(false);
return;
}
setBusy(true);
try {
await result;
setOpen(false);
} catch {
setFailed(true);
} finally {
setBusy(false);
}
}
const action = cx(
"inline-flex h-7 shrink-0 cursor-pointer items-center gap-1.5 rounded-md px-2 text-xs font-medium",
"text-zinc-600 transition-[background-color,color,scale] duration-150 ease-out active:duration-100 motion-safe:active:scale-[0.97] motion-reduce:transition-none",
"hover:bg-zinc-950/[0.04] hover:text-zinc-950 data-[popup-open]:bg-zinc-950/[0.06] data-[popup-open]:text-zinc-950",
"dark:text-zinc-400 dark:hover:bg-white/[0.06] dark:hover:text-white dark:data-[popup-open]:bg-white/[0.09] dark:data-[popup-open]:text-white",
"focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-sky-500",
"disabled:pointer-events-none disabled:opacity-45",
);
const description =
confirmDescription ??
(stamp
? `The conversation and its file changes go back to how they were at ${stamp.text}. Messages after that are removed.`
: "The conversation and its file changes go back to this point. Messages after it are removed.");
return (
<div
role="group"
aria-label={typeof label === "string" ? `Checkpoint: ${label}` : "Checkpoint"}
data-current={current || undefined}
className={cx("flex w-full min-w-0 items-center gap-3 text-xs", className)}
{...props}
>
<span aria-hidden="true" className="h-px min-w-4 flex-1 bg-zinc-950/10 dark:bg-white/10" />
<span className="flex min-w-0 items-center gap-2">
<BookmarkIcon current={current} />
<span className="min-w-0 truncate text-zinc-600 dark:text-zinc-400">{label}</span>
{stamp ? (
<time dateTime={stamp.iso} className="shrink-0 font-mono text-[11px] text-zinc-500 tabular-nums">
{stamp.text}
</time>
) : null}
</span>
{current ? (
<span className="inline-flex h-7 shrink-0 items-center px-2 text-xs font-medium text-zinc-500">Current</span>
) : onRestore ? (
confirm ? (
<Popover
open={open}
onOpenChange={(next) => {
if (busy) return;
setOpen(next);
if (next) setFailed(false);
}}
>
<PopoverTrigger disabled={disabled} className={action}>
<RestoreIcon />
Restore
</PopoverTrigger>
<PopoverContent side="top" sideOffset={6} className="w-76 p-4">
<PopoverTitle>{confirmTitle}</PopoverTitle>
<PopoverDescription className="mt-1">{description}</PopoverDescription>
{failed ? (
<p role="alert" className="mt-3 rounded-lg border border-red-500/35 bg-red-500/[0.08] px-3 py-2 text-sm text-red-700 dark:text-red-300">
The checkpoint could not be restored. Try again.
</p>
) : null}
<div className="mt-4 flex justify-end gap-2">
<PopoverClose disabled={busy} render={<Button variant="secondary" size="sm" />}>
Cancel
</PopoverClose>
<Button size="sm" loading={busy} onClick={restore}>
Restore
</Button>
</div>
</PopoverContent>
</Popover>
) : (
<button type="button" disabled={disabled} onClick={() => void onRestore()} className={action}>
<RestoreIcon />
Restore
</button>
)
) : null}
<span aria-hidden="true" className="h-px min-w-4 flex-1 bg-zinc-950/10 dark:bg-white/10" />
</div>
);
}
function BookmarkIcon({ current }: { current: boolean }) {
return (
<svg
aria-hidden="true"
viewBox="0 0 16 16"
fill="none"
stroke="currentColor"
strokeWidth={1.5}
strokeLinejoin="round"
className={cx("size-3.5 shrink-0 transition-colors duration-200 motion-reduce:transition-none", current ? "text-zinc-950 dark:text-white" : "text-zinc-400 dark:text-zinc-500")}
>
<path d="M4.5 2.75h7v10.5L8 10.75l-3.5 2.5Z" className={current ? "fill-current" : undefined} />
</svg>
);
}
function RestoreIcon() {
return (
<svg aria-hidden="true" viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth={1.5} strokeLinecap="round" strokeLinejoin="round" className="size-3.5 shrink-0">
<path d="M3 8a5 5 0 1 0 1.5-3.55" />
<path d="M3 2.75v2.5h2.5" />
</svg>
);
}