Skip to content
Shaken UI
Sign in

Plan

Save

The 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 approval

Edit the steps, then approve to start.

Enter adds a step below. Backspace on an empty step removes it.

Installation

npx @shakenui/cli add plan

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

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

Usage

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

PropTypeDefaultDescription
steps{ id, label, detail?, status? }[]—Steps in order. label is plain text so it can be edited. status overrides the value derived from current.
currentnumber—Index of the step in progress; earlier steps count as done. Leave it out while the plan waits for approval.
title / descriptionReactNode"Plan"Heading and an optional line under it.
activityAgentActivity"working"The Agent State mark on the current step.
editablebooleanfalseTurns 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 / rejectLabelReactNode"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.tsxShow
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>
  );
}