Plan
SaveThe steps an agent intends to take with progress, the current step highlighted with a live mark and finished steps checked, plus an editable mode for approval before anything runs.
- Category
- AI elements
- Version
- 0.1.0
- Frameworks
- Next.js, Vite + React
- Styling
- Tailwind CSS v4
Preview
Plan preview
Migrate billing emails to the new template
Waiting for approvalEdit the steps, then approve to start.
Enter adds a step below. Backspace on an empty step removes it.
Installation
npx @shakenui/cli add planReview the plan first. A dry run lists every file and package without changing anything:
npx @shakenui/cli add plan --dry-runUsage
plan-example.tsx
import { Plan } from "@/components/shaken/agent/plan";
export default function PlanExample() {
return (
<Plan
className="max-w-md"
title="Migrate billing emails to the new template"
current={2}
activity="working"
steps={[
{ id: "1", label: "Find every place that sends a billing email", detail: "4 call sites in api/billing" },
{ id: "2", label: "Map old template fields to the new ones" },
{ id: "3", label: "Update the senders to use the new template", detail: "invoice.ts, receipt.ts" },
{ id: "4", label: "Render each email with test data" },
{ id: "5", label: "Open a pull request" },
]}
/>
);
}API
| Prop | Type | Default | Description |
|---|---|---|---|
| steps | { id, label, detail?, status? }[] | — | Steps in order. label is plain text so it can be edited. status overrides the value derived from current. |
| current | number | — | Index of the step in progress; earlier steps count as done. Leave it out while the plan waits for approval. |
| title / description | ReactNode | "Plan" | Heading and an optional line under it. |
| activity | AgentActivity | "working" | The Agent State mark on the current step. |
| editable | boolean | false | Turns steps into text fields with add and remove. Uncontrolled while editing: steps seeds it and onStepsChange reports changes. |
| onApprove / onReject | (steps) => void / () => void | — | Show the approve and discard buttons. onApprove receives the edited steps without empty ones. |
| approveLabel / rejectLabel | ReactNode | "Approve plan" / "Discard" | Button text. |
Accessibility
- The plan is a labeled section; progress is a progressbar with aria-valuetext such as "2 of 5 steps done".
- The current step has aria-current="step" and every step has a screen-reader status after its label.
- In editable mode each field is labeled "Step N" and each remove button "Remove step N". Enter adds a step below and moves focus to it; Backspace on an empty step removes it and focuses the previous one.
- Remove buttons appear on hover and on keyboard focus, and stay visible on touch screens.
- With reduced motion the progress bar, new rows, and glyph swaps change without animation.
Files
Installed into src/components/shaken, or components/shaken when the project has no src directory.
src/components/shaken/agent/plan.tsxplan- Also installs agent-state@0.1.0registry dependency
- Also installs step-list@0.3.0registry dependency
- Also installs button@0.2.1registry dependency
- npm packages: noneReact and Tailwind CSS v4 required
Source
The exact source the CLI installs, from /r/items/react/plan/0.1.0.json.
agent/plan.tsxShowHide
agent/plan.tsx
"use client";
import { type ComponentProps, type KeyboardEvent, type ReactNode, useEffect, useId, useRef, useState } from "react";
import { Button } from "../ui/button";
import { type AgentActivity, AgentMark } from "./agent-state";
import { StatusGlyph } from "./step-list";
function cx(...classes: Array<string | false | null | undefined>) {
return classes.filter(Boolean).join(" ");
}
const ease = "ease-[cubic-bezier(0.23,1,0.32,1)]";
export type PlanStepStatus = "pending" | "current" | "done" | "failed" | "skipped";
export interface PlanStep {
id: string;
/** What the agent will do. Plain text so it can be edited before approval. */
label: string;
/** Optional second line, such as the files or tools involved. */
detail?: ReactNode;
/** Overrides the status derived from `current`. */
status?: PlanStepStatus;
}
export interface PlanProps extends Omit<ComponentProps<"section">, "children" | "title"> {
/** @default "Plan" */
title?: ReactNode;
/** One line under the title, for example the goal the plan serves. */
description?: ReactNode;
steps: PlanStep[];
/**
* Index of the step in progress. Earlier steps count as done, later ones as pending.
* Leave it out while the plan waits for approval, or when every step carries a `status`.
*/
current?: number;
/** Which Agent State mark moves on the current step. @default "working" */
activity?: AgentActivity;
/**
* Turns the steps into text fields so the reader can edit, add, and remove steps before
* approving. The list is uncontrolled while editing: `steps` seeds it, `onStepsChange`
* reports every change, and `onApprove` receives the final list.
*/
editable?: boolean;
onStepsChange?: (steps: PlanStep[]) => void;
/** Shows the approve button. Receives the steps as edited. */
onApprove?: (steps: PlanStep[]) => void;
/** Shows a secondary button next to approve, for example to discard the plan. */
onReject?: () => void;
/** @default "Approve plan" */
approveLabel?: ReactNode;
/** @default "Discard" */
rejectLabel?: ReactNode;
}
function statusOf(step: PlanStep, index: number, current: number | undefined): PlanStepStatus {
if (step.status) return step.status;
if (current == null) return "pending";
return index < current ? "done" : index === current ? "current" : "pending";
}
const spoken: Record<PlanStepStatus, string> = {
pending: "Not started",
current: "In progress",
done: "Done",
failed: "Failed",
skipped: "Skipped",
};
/**
* The steps an agent intends to take, with progress ("2 of 5"). Finished steps are checked,
* the current one is highlighted with a live mark, and the rest wait in order. With
* `editable`, the reader can rewrite the plan and approve it before anything runs.
*/
export function Plan({
title = "Plan",
description,
steps,
current,
activity = "working",
editable = false,
onStepsChange,
onApprove,
onReject,
approveLabel = "Approve plan",
rejectLabel = "Discard",
className,
...props
}: PlanProps) {
const titleId = useId();
const [draft, setDraft] = useState(steps);
const list = editable ? draft : steps;
const statuses = list.map((step, index) => statusOf(step, index, current));
const done = statuses.filter((status) => status === "done" || status === "skipped").length;
const failed = statuses.includes("failed");
const total = list.length;
const ratio = total ? done / total : 0;
const finished = total > 0 && done === total;
const awaiting = editable || (current == null && !list.some((step) => step.status));
function update(next: PlanStep[]) {
setDraft(next);
onStepsChange?.(next);
}
return (
<section
aria-labelledby={titleId}
data-state={awaiting ? "awaiting-approval" : finished ? "done" : failed ? "failed" : "running"}
className={cx(
"w-full overflow-hidden rounded-xl border border-zinc-950/10 bg-white text-zinc-950 shadow-[0_1px_2px_rgb(0_0_0/0.04)]",
"dark:border-white/10 dark:bg-black dark:text-white dark:shadow-[inset_0_1px_0_rgb(255_255_255/0.06)]",
className,
)}
{...props}
>
<header className="px-4 pt-3.5 pb-3">
<div className="flex flex-wrap items-baseline justify-between gap-x-4 gap-y-1">
<h3 id={titleId} className="min-w-0 text-sm leading-5 font-semibold text-pretty">
{title}
</h3>
<PlanMeta awaiting={awaiting} finished={finished} failed={failed} done={done} total={total} />
</div>
{description != null ? <p className="mt-0.5 text-sm text-zinc-600 dark:text-zinc-400">{description}</p> : null}
{!awaiting ? (
<div
role="progressbar"
aria-label="Plan progress"
aria-valuemin={0}
aria-valuemax={total}
aria-valuenow={done}
aria-valuetext={`${done} of ${total} steps done`}
className="mt-3 h-0.5 overflow-hidden rounded-full bg-zinc-950/[0.07] dark:bg-white/10"
>
<div
className={cx(
"h-full origin-left rounded-full transition-[scale,background-color] duration-500 motion-reduce:transition-none",
ease,
failed ? "bg-red-500" : "bg-zinc-950 dark:bg-white",
)}
style={{ scale: `${ratio} 1` }}
/>
</div>
) : null}
</header>
{editable ? (
<EditableSteps steps={draft} onChange={update} />
) : (
<ol className="grid gap-0.5 border-t border-zinc-950/[0.07] p-1.5 dark:border-white/[0.08]">
{list.map((step, index) => (
<PlanRow key={step.id} step={step} index={index} status={statuses[index] ?? "pending"} activity={activity} />
))}
</ol>
)}
{onApprove || onReject ? (
<footer className="flex items-center justify-end gap-2 border-t border-zinc-950/[0.07] px-4 py-3 dark:border-white/[0.08]">
{onReject ? (
<Button variant="ghost" size="sm" onClick={onReject}>
{rejectLabel}
</Button>
) : null}
{onApprove ? (
<Button size="sm" disabled={!list.some((step) => step.label.trim())} onClick={() => onApprove(list.filter((step) => step.label.trim()))}>
{approveLabel}
</Button>
) : null}
</footer>
) : null}
</section>
);
}
function PlanMeta({ awaiting, finished, failed, done, total }: { awaiting: boolean; finished: boolean; failed: boolean; done: number; total: number }) {
if (awaiting) {
return (
<span className="inline-flex shrink-0 items-center gap-1.5 self-start text-xs leading-5 text-amber-700 dark:text-amber-400">
<StatusGlyph kind="waiting" />
Waiting for approval
</span>
);
}
return (
<span
key={finished ? "done" : failed ? "failed" : "progress"}
className={cx(
"inline-flex shrink-0 items-center gap-1.5 font-mono text-xs tabular-nums",
failed ? "text-red-600 dark:text-red-400" : "text-zinc-500",
`transition-opacity duration-200 ${ease} starting:opacity-0 motion-reduce:transition-none`,
)}
>
{finished ? <StatusGlyph kind="success" /> : failed ? <StatusGlyph kind="failed" /> : null}
{done} of {total}
</span>
);
}
function PlanRow({ step, index, status, activity }: { step: PlanStep; index: number; status: PlanStepStatus; activity: AgentActivity }) {
const isCurrent = status === "current";
return (
<li
aria-current={isCurrent ? "step" : undefined}
data-status={status}
className={cx(
"grid grid-cols-[1.25rem_minmax(0,1fr)] gap-x-2.5 rounded-lg px-2.5 py-2",
"transition-[background-color] duration-200 motion-reduce:transition-none",
isCurrent ? "bg-zinc-950/[0.04] dark:bg-white/[0.06]" : "",
)}
>
<span aria-hidden="true" className="flex h-5 items-center justify-center">
{isCurrent ? (
<AgentMark activity={activity} size={16} className="text-zinc-950 dark:text-white" />
) : status === "done" ? (
<StatusGlyph key="done" kind="success" />
) : status === "failed" ? (
<StatusGlyph key="failed" kind="failed" />
) : status === "skipped" ? (
<StatusGlyph key="skipped" kind="skipped" />
) : (
<StepNumber n={index + 1} />
)}
</span>
<div className="min-w-0">
<p
className={cx(
"text-sm leading-5 break-words transition-colors duration-200 motion-reduce:transition-none",
isCurrent
? "font-medium text-zinc-950 dark:text-white"
: status === "done"
? "text-zinc-600 dark:text-zinc-400"
: status === "failed"
? "text-zinc-950 dark:text-white"
: status === "skipped"
? "text-zinc-500 line-through decoration-zinc-500/60"
: "text-zinc-500",
)}
>
{step.label}
<span className="sr-only">, {spoken[status]}</span>
</p>
{step.detail != null ? (
<p className={cx("mt-0.5 text-xs", status === "failed" ? "text-red-600 dark:text-red-400" : "text-zinc-500")}>{step.detail}</p>
) : null}
</div>
</li>
);
}
function StepNumber({ n }: { n: number }) {
return (
<span className="flex size-4 items-center justify-center rounded-full border border-dashed border-zinc-950/25 font-mono text-[9px] leading-none text-zinc-500 tabular-nums dark:border-white/25">
{n}
</span>
);
}
let created = 0;
function EditableSteps({ steps, onChange }: { steps: PlanStep[]; onChange: (steps: PlanStep[]) => void }) {
const inputs = useRef(new Map<string, HTMLTextAreaElement>());
const [focusId, setFocusId] = useState<string | null>(null);
const prefix = useId();
useEffect(() => {
if (!focusId) return;
const input = inputs.current.get(focusId);
input?.focus();
setFocusId(null);
}, [focusId]);
function insertAfter(index: number) {
created += 1;
const step: PlanStep = { id: `${prefix}-new-${created}`, label: "" };
onChange([...steps.slice(0, index + 1), step, ...steps.slice(index + 1)]);
setFocusId(step.id);
}
function remove(index: number) {
const next = steps.filter((_, i) => i !== index);
onChange(next);
const neighbour = next[Math.max(0, index - 1)];
if (neighbour) setFocusId(neighbour.id);
}
function onKeyDown(event: KeyboardEvent<HTMLTextAreaElement>, index: number) {
if (event.key === "Enter" && !event.nativeEvent.isComposing) {
event.preventDefault();
insertAfter(index);
} else if (event.key === "Backspace" && event.currentTarget.value === "" && steps.length > 1) {
event.preventDefault();
remove(index);
}
}
return (
<div className="border-t border-zinc-950/[0.07] p-1.5 dark:border-white/[0.08]">
<ol className="grid gap-0.5">
{steps.map((step, index) => (
<li
key={step.id}
className={cx(
"group grid grid-cols-[1.25rem_minmax(0,1fr)_auto] items-start gap-x-2.5 rounded-lg py-1 pr-1 pl-2.5",
`transition-[opacity,translate] duration-200 ${ease} starting:-translate-y-1 starting:opacity-0 motion-reduce:transition-none`,
)}
>
<span aria-hidden="true" className="flex h-8 items-center justify-center">
<StepNumber n={index + 1} />
</span>
<textarea
rows={1}
ref={(node) => {
if (node) inputs.current.set(step.id, node);
else inputs.current.delete(step.id);
}}
value={step.label}
aria-label={`Step ${index + 1}`}
placeholder="Describe the step"
onChange={(event) => onChange(steps.map((item) => (item.id === step.id ? { ...item, label: event.target.value.replace(/\s*\n\s*/g, " ") } : item)))}
onKeyDown={(event) => onKeyDown(event, index)}
className={cx(
"-ml-2 block min-h-8 min-w-0 resize-none rounded-md border border-transparent bg-transparent px-2 py-1.5 text-sm leading-5 field-sizing-content text-zinc-950 placeholder:text-zinc-400 dark:text-white dark:placeholder:text-zinc-600",
"transition-[border-color,background-color] duration-150 ease-out motion-reduce:transition-none",
"hover:border-zinc-950/10 dark:hover:border-white/10",
"focus-visible:border-zinc-950/15 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-sky-500 dark:focus-visible:border-white/20",
)}
/>
<button
type="button"
aria-label={`Remove step ${index + 1}`}
disabled={steps.length <= 1}
onClick={() => remove(index)}
className={cx(
"mt-0.5 inline-flex size-7 cursor-pointer items-center justify-center rounded-md text-zinc-500",
"transition-[background-color,color,opacity] duration-150 ease-out motion-reduce:transition-none",
"opacity-0 group-focus-within:opacity-100 group-hover:opacity-100 [@media(hover:none)]:opacity-100",
"hover:bg-zinc-950/[0.04] hover:text-zinc-950 dark:hover:bg-white/[0.06] dark:hover:text-white",
"focus-visible:opacity-100 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-sky-500",
"disabled:pointer-events-none disabled:opacity-0",
)}
>
<svg aria-hidden="true" viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth={1.5} strokeLinecap="round" className="size-3.5">
<path d="m4.5 4.5 7 7m0-7-7 7" />
</svg>
</button>
</li>
))}
</ol>
<button
type="button"
onClick={() => insertAfter(steps.length - 1)}
className={cx(
"mt-0.5 flex h-8 w-full cursor-pointer items-center gap-2.5 rounded-lg px-2.5 text-sm text-zinc-500",
"transition-[background-color,color] duration-150 ease-out motion-reduce:transition-none",
"hover:bg-zinc-950/[0.04] hover:text-zinc-950 dark:hover:bg-white/[0.06] dark:hover:text-white",
"focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-sky-500",
)}
>
<svg aria-hidden="true" viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth={1.5} strokeLinecap="round" className="size-4 shrink-0 translate-x-0.5">
<path d="M8 3.5v9M3.5 8h9" />
</svg>
Add step
</button>
<p className="px-2.5 pt-1 pb-1.5 text-xs text-zinc-500">Enter adds a step below. Backspace on an empty step removes it.</p>
</div>
);
}