import { html, nothing } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { bubbleClass, bubbleContentClass } from '#components/ui/bubble.ts';
import { buttonClass } from '#components/ui/button.ts';
import { messageClass, messageContentClass } from '#components/ui/message.ts';
import {
traceClass, traceLineClass, traceIconClass, traceTitleClass, traceDescriptionClass,
traceCollapsibleClass, traceCollapsibleTriggerClass, traceCollapsibleContentClass,
} from '#components/ui/trace.ts';
import {
ChevronRightIcon, CircleCheckIcon, CircleDotIcon, CircleIcon, RouteIcon,
} from '#lib/ui/lucide.ts';
type Step = { title: string; status: 'done' | 'running' | 'pending' };
const plan: { title: string; steps: Step[] } = {
title: 'Plan: migrate to Base UI',
steps: [
{ title: 'Install @base-ui/react', status: 'done' },
{ title: 'Replace the Radix imports', status: 'done' },
{ title: 'Rename asChild to render', status: 'done' },
{ title: 'Run the type checker', status: 'done' },
],
};
const done = plan.steps.filter((step) => step.status === 'done').length;
function stepIcon(status: Step['status']) {
if (status === 'done') return CircleCheckIcon();
return status === 'running' ? CircleDotIcon() : CircleIcon();
}
// The conversation once the plan has finished: every step is done and the
// reply has streamed after it.
export default function PlanDemo() {
return html`
<div class="flex min-h-72 w-full max-w-sm flex-col gap-4 py-6 text-sm">
<div data-slot="message" data-align="end" class=${messageClass()}>
<div data-slot="message-content" class=${messageContentClass()}>
<div data-slot="bubble" data-variant="muted" data-align="end" class=${bubbleClass({ variant: 'muted' })}>
<div data-slot="bubble-content" class=${bubbleContentClass()}>Migrate the dialog components to Base UI.</div>
</div>
</div>
</div>
<div data-slot="message" data-align="start" class=${messageClass()}>
<div data-slot="message-content" class=${cn(messageContentClass(), 'gap-4')}>
<div data-slot="trace" class=${traceClass()}>
<details data-slot="trace-collapsible" open class=${cn(traceCollapsibleClass(), 'group/trace-collapsible')}>
<summary data-slot="trace-collapsible-trigger" class=${traceCollapsibleTriggerClass()}>
<span data-slot="trace-line" class=${traceLineClass()}>
<span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${RouteIcon()}</span>
<span data-slot="trace-title" class=${traceTitleClass()}>${plan.title}</span>
<span data-slot="trace-description" class=${traceDescriptionClass()}>${done} of ${plan.steps.length} done</span>
</span>
<span data-slot="trace-icon" aria-hidden="true" class=${cn(traceIconClass(), 'transition-transform group-open/trace-collapsible:rotate-90')}>${ChevronRightIcon()}</span>
</summary>
<div data-slot="trace-collapsible-content" class=${traceCollapsibleContentClass()}>
<div data-slot="trace" class=${traceClass()}>
${plan.steps.map((step) => html`
<span data-slot="trace-line" data-status=${step.status === 'pending' ? 'pending' : nothing} class=${traceLineClass()}>
<span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${stepIcon(step.status)}</span>
<span data-slot="trace-title" class=${traceTitleClass()}>${step.title}</span>
</span>
`)}
</div>
</div>
</details>
</div>
<p>Migrated Dialog and AlertDialog. The type checker passes.</p>
</div>
</div>
<button type="button" data-slot="button" data-variant="outline" data-size="sm" class=${cn(buttonClass({ variant: 'outline', size: 'sm' }), 'mt-auto self-start')}>
Replay
</button>
</div>
`;
}
View Code
Plan is the list of steps the agent decides on before it starts, such as the steps of a migration. Each step is done, running or pending, and the title counts how many are done.
Plan is built with a trace, with a trace collapsible for the plan.
When the steps are not known up front, use Task instead.
Installation
Plan is built with the Trace component.
Copy and paste the following code into your project.
/**
* Trace: a vertical timeline of steps (a tool call, a reasoning step, a
* deploy stage), each with an icon on a connecting line, a title and an
* optional collapsible detail. Tier-1 class helper; compose with plain
* elements and `<details>` for the collapsible part.
*
* shadcn parity:
* Trace → traceClass()
* TraceLine / TraceIcon → traceLineClass() / traceIconClass()
* TraceTitle / TraceDescription
* → traceTitleClass() / traceDescriptionClass()
* TraceCollapsible / TraceCollapsibleTrigger / TraceCollapsibleContent
* → <details> / <summary> / a div, with the
* trace collapsible helpers
*
* shadcn has no new-york version of this component, so its look in the
* default style is shadcn's vega style, the classic shadcn look.
*
* A11y (required for accessible output): a trace is an ordered list of steps,
* so render it as `<ol>` with each step an `<li>`. A step's status must be in
* text, not only in the icon colour ("Failed", "Done"), and a decorative icon
* takes `aria-hidden="true"`. A collapsible step is a native `<details>` with a
* `<summary>`, which carries the expanded state by itself.
*
* Design tokens used: --border, --muted-foreground, --foreground.
*
* @example
* ```html
* <ol class=${traceClass()} data-slot="trace">
* <li class=${traceLineClass()} data-slot="trace-line">
* <span class=${traceTitleClass()} data-slot="trace-title">Fetched the issue</span>
* </li>
* </ol>
* ```
*/
/** Set `data-slot="trace"` on the element. */
export function traceClass(): string {
return 'gap-2 *:has-[>[data-slot=trace-line]]:rounded-md *:has-[>[data-slot=trace-line]]:focus-visible:ring-3 *:has-[>[data-slot=trace-line]]:focus-visible:ring-ring/50 flex w-full min-w-0 flex-col *:has-[>[data-slot=trace-line]]:flex *:has-[>[data-slot=trace-line]]:w-fit *:has-[>[data-slot=trace-line]]:max-w-full *:has-[>[data-slot=trace-line]]:min-w-0 *:has-[>[data-slot=trace-line]]:text-start *:has-[>[data-slot=trace-line]]:outline-none';
}
/** Set `data-slot="trace-line"` on the element. */
export function traceLineClass(): string {
return 'gap-2 text-sm flex w-fit max-w-full min-w-0 items-center text-muted-foreground transition-colors in-[a,button]:cursor-pointer in-[a:hover,button:hover]:text-foreground data-[status=error]:text-destructive data-[status=error]:in-[a:hover,button:hover]:text-destructive data-[status=pending]:opacity-60 data-[status=running]:*:data-[slot=trace-title]:shimmer';
}
/** Set `data-slot="trace-icon"` on the element. */
export function traceIconClass(): string {
return "size-4 [&_svg:not([class*='size-'])]:size-4 [[data-slot=trace-title]~&]:-ms-1 flex shrink-0 items-center justify-center [&_svg]:pointer-events-none";
}
/** Set `data-slot="trace-title"` on the element. */
export function traceTitleClass(): string {
return 'min-w-0 truncate motion-reduce:shimmer-none';
}
/** Set `data-slot="trace-description"` on the element. */
export function traceDescriptionClass(): string {
return 'shrink-0 text-muted-foreground/70 tabular-nums';
}
/** Set `data-slot="trace-collapsible"` on the element. */
export function traceCollapsibleClass(): string {
return 'flex w-full min-w-0 flex-col';
}
/** Set `data-slot="trace-collapsible-trigger"` on the element. */
export function traceCollapsibleTriggerClass(): string {
return 'gap-1 rounded-md focus-visible:ring-3 focus-visible:ring-ring/50 group/trace-collapsible-trigger flex w-fit max-w-full min-w-0 cursor-pointer items-center text-start text-muted-foreground transition-colors outline-none hover:text-foreground has-[[data-status=error]]:text-destructive';
}
/** Set `data-slot="trace-collapsible-content"` on the element. */
export function traceCollapsibleContentClass(): string {
return 'mt-2 mb-1 ms-[calc(--spacing(2)-1px)] border-s pe-1 ps-4 leading-relaxed min-w-0 wrap-break-word text-muted-foreground';
}
Update the import paths to match your project setup.
Usage
import {
traceClass,
traceCollapsibleClass,
traceCollapsibleContentClass,
traceCollapsibleTriggerClass,
traceDescriptionClass,
traceIconClass,
traceLineClass,
traceTitleClass,
} from '#components/ui/trace.ts';
<div data-slot="trace" class=${traceClass()}>
<details data-slot="trace-collapsible" open class=${cn(traceCollapsibleClass(), 'group/trace-collapsible')}>
<summary data-slot="trace-collapsible-trigger" class=${traceCollapsibleTriggerClass()}>
<span data-slot="trace-line" data-status="running" class=${traceLineClass()}>
<span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>
${RouteIcon()}
</span>
<span data-slot="trace-title" class=${traceTitleClass()}>Plan: migrate to Base UI</span>
<span data-slot="trace-description" class=${traceDescriptionClass()}>2 of 5 done</span>
</span>
<span data-slot="trace-icon" aria-hidden="true" class=${cn(traceIconClass(), 'transition-transform group-open/trace-collapsible:rotate-90')}>
${ChevronRightIcon()}
</span>
</summary>
<div data-slot="trace-collapsible-content" class=${traceCollapsibleContentClass()}>
<div data-slot="trace" class=${traceClass()}>
<span data-slot="trace-line" class=${traceLineClass()}>
<span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>
${CircleCheckIcon()}
</span>
<span data-slot="trace-title" class=${traceTitleClass()}>Replace the Radix imports</span>
</span>
<span data-slot="trace-line" data-status="running" class=${traceLineClass()}>
<span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>
${CircleDotIcon()}
</span>
<span data-slot="trace-title" class=${traceTitleClass()}>Rename asChild to render</span>
</span>
<span data-slot="trace-line" data-status="pending" class=${traceLineClass()}>
<span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>
${CircleIcon()}
</span>
<span data-slot="trace-title" class=${traceTitleClass()}>Run the type checker</span>
</span>
</div>
</div>
</details>
</div>
Details
Put a description above the steps, inside the trace collapsible content.
Store the theme in a cookie so the server renders the right one and the page does not flash on load.
import { html, nothing } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
traceClass, traceLineClass, traceIconClass, traceTitleClass, traceDescriptionClass,
traceCollapsibleClass, traceCollapsibleTriggerClass, traceCollapsibleContentClass,
} from '#components/ui/trace.ts';
import {
ChevronRightIcon, CircleCheckIcon, CircleIcon, RouteIcon,
} from '#lib/ui/lucide.ts';
const steps = [
'Add a dark variant to the theme tokens',
'Read the theme from a cookie on the server',
'Add a toggle to the settings page',
'Check contrast on the charts',
];
export default function PlanDescription() {
return html`
<div data-slot="trace" class=${cn(traceClass(), 'max-w-sm')}>
<details data-slot="trace-collapsible" open class=${cn(traceCollapsibleClass(), 'group/trace-collapsible')}>
<summary data-slot="trace-collapsible-trigger" class=${traceCollapsibleTriggerClass()}>
<span data-slot="trace-line" class=${traceLineClass()}>
<span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${RouteIcon()}</span>
<span data-slot="trace-title" class=${traceTitleClass()}>Plan: add dark mode</span>
<span data-slot="trace-description" class=${traceDescriptionClass()}>1 of ${steps.length} done</span>
</span>
<span data-slot="trace-icon" aria-hidden="true" class=${cn(traceIconClass(), 'transition-transform group-open/trace-collapsible:rotate-90')}>${ChevronRightIcon()}</span>
</summary>
<div data-slot="trace-collapsible-content" class=${cn(traceCollapsibleContentClass(), 'flex flex-col gap-3')}>
<p>
Store the theme in a cookie so the server renders the right one and
the page does not flash on load.
</p>
<div data-slot="trace" class=${traceClass()}>
${steps.map((step, index) => html`
<span data-slot="trace-line" data-status=${index > 0 ? 'pending' : nothing} class=${traceLineClass()}>
<span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${index === 0 ? CircleCheckIcon() : CircleIcon()}</span>
<span data-slot="trace-title" class=${traceTitleClass()}>${step}</span>
</span>
`)}
</div>
</div>
</details>
</div>
`;
}
View Code
AI SDK
Stream the plan as a data part with a fixed id, from the 'use server' action that streams the reply. Each time the plan changes, yield it again with the same id, and keep the latest part for each id where your component collects the parts, so it updates in place.
yield { type: 'data-plan', id: 'plan', data: { title, steps } };
const plan = message.parts.find((part) => part.type === 'data-plan');
See AI SDK for streaming the parts to a component.
Migrating from AI SDK Elements
If you used Plan from AI SDK Elements, its wrapper lives in components/ai-elements/plan.tsx. In a WebJs app it becomes this pattern, built from WebJs UI components. Each export of the wrapper maps onto a part:
API Reference
See Trace.