Skip to content
Shaken UI
Sign in

Checkpoint

Save

A 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 checkpoint

Review the plan first. A dry run lists every file and package without changing anything:

npx @shakenui/cli add checkpoint --dry-run

Usage

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

PropTypeDefaultDescription
labelReactNode"Checkpoint"What the checkpoint marks.
timeDate | 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.
confirmbooleantrueAsks in a small popover before restoring.
confirmTitle / confirmDescriptionReactNode—Text of the confirmation. The default description names the time.
currentbooleanfalseThis is the state the conversation is in now; the action reads "Current".
disabledbooleanfalseDisables 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.tsxShow
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>
  );
}