import { html } 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,
traceCollapsibleClass, traceCollapsibleTriggerClass, traceCollapsibleContentClass,
} from '#components/ui/trace.ts';
import {
ChevronRightIcon, CircleCheckIcon, CircleDotIcon, CircleIcon, ListChecksIcon, ListTodoIcon,
} from '#lib/ui/lucide.ts';
type Todo = { content: string; status: 'pending' | 'in_progress' | 'completed' };
// The last todo list the agent wrote: every todo is done.
const todos: Todo[] = [
'Add a dark variant to the theme tokens',
'Read the theme from a cookie',
'Add a toggle to the settings page',
'Check contrast on the charts',
].map((content) => ({ content, status: 'completed' }));
function todoLine(todo: Todo) {
const icon = todo.status === 'completed'
? CircleCheckIcon()
: todo.status === 'in_progress' ? CircleDotIcon() : CircleIcon();
return html`<span data-slot="trace-line" class=${traceLineClass()}>
<span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${icon}</span>
<span data-slot="trace-title" class=${traceTitleClass()}>${todo.content}</span>
</span>`;
}
function section(icon: unknown, title: string, items: Todo[]) {
return html`
<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()}>${icon}</span>
<span data-slot="trace-title" class=${traceTitleClass()}>${title}</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()}>${items.map(todoLine)}</div>
</div>
</details>
`;
}
// The conversation once the agent has finished. A section shows only while it
// holds a todo, so with everything done only Completed is left.
export default function QueueDemo() {
const pending = todos.filter((todo) => todo.status !== 'completed');
const completed = todos.filter((todo) => todo.status === 'completed');
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()}>Add dark mode to the settings page.</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()}>
${pending.length > 0 ? section(ListTodoIcon(), `${pending.length} to do`, pending) : ''}
${completed.length > 0 ? section(ListChecksIcon(), `${completed.length} completed`, completed) : ''}
</div>
<p>Dark mode is in. The toggle is under Settings, Appearance.</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
Queue is the agent's todo list. Todos sit in two sections, To do and Completed, and the icon on each todo shows its status. The agent updates the list as it works, so a todo moves from one section to the other when it is done.
Queue is built with a trace, with a trace collapsible for each section.
Installation
Queue 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,
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" class=${traceLineClass()}>
<span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>
${ListTodoIcon()}
</span>
<span data-slot="trace-title" class=${traceTitleClass()}>2 to do</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()}>
${CircleIcon()}
</span>
<span data-slot="trace-title" class=${traceTitleClass()}>Update the registry snapshots</span>
</span>
<span data-slot="trace-line" class=${traceLineClass()}>
<span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>
${CircleIcon()}
</span>
<span data-slot="trace-title" class=${traceTitleClass()}>Add tests for the combobox</span>
</span>
</div>
</div>
</details>
<details data-slot="trace-collapsible" 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()}>
${ListChecksIcon()}
</span>
<span data-slot="trace-title" class=${traceTitleClass()}>1 completed</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()}>Add a changeset</span>
</span>
</div>
</div>
</details>
</div>
Descriptions
A todo with a description is a trace collapsible that opens to show it. A todo without one stays a trace line.
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
traceClass, traceLineClass, traceIconClass, traceTitleClass,
traceCollapsibleClass, traceCollapsibleTriggerClass, traceCollapsibleContentClass,
} from '#components/ui/trace.ts';
import {
ChevronRightIcon, CircleCheckIcon, CircleIcon, ListChecksIcon, ListTodoIcon,
} from '#lib/ui/lucide.ts';
type Todo = { title: string; description?: string; done: boolean };
const todos: Todo[] = [
{
title: 'Write the migration guide',
description: 'Cover the renamed props and the new data attributes.',
done: true,
},
{ title: 'Add a changeset', done: true },
{
title: 'Fix the focus ring on the select trigger',
description: 'It is clipped by overflow-hidden on the field.',
done: false,
},
{ title: 'Update the registry snapshots', done: false },
{
title: 'Add tests for the combobox',
description: 'Typing, clearing and keyboard selection.',
done: false,
},
];
// A trace collapsible: a native <details> whose summary holds the line and a
// chevron that turns while it is open.
function collapsible(line: unknown, content: unknown, open = false) {
return html`
<details data-slot="trace-collapsible" ?open=${open} class=${cn(traceCollapsibleClass(), 'group/trace-collapsible')}>
<summary data-slot="trace-collapsible-trigger" class=${traceCollapsibleTriggerClass()}>
${line}
<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()}>${content}</div>
</details>
`;
}
function line(icon: unknown, title: string) {
return html`<span data-slot="trace-line" class=${traceLineClass()}>
<span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${icon}</span>
<span data-slot="trace-title" class=${traceTitleClass()}>${title}</span>
</span>`;
}
// A todo with a description opens to show it. One without stays a line.
function todoRow(todo: Todo) {
const row = line(todo.done ? CircleCheckIcon() : CircleIcon(), todo.title);
return todo.description ? collapsible(row, todo.description) : row;
}
export default function QueueDescriptions() {
const pending = todos.filter((todo) => !todo.done);
const completed = todos.filter((todo) => todo.done);
return html`
<div data-slot="trace" class=${cn(traceClass(), 'max-w-sm')}>
${collapsible(
line(ListTodoIcon(), `${pending.length} to do`),
html`<div data-slot="trace" class=${traceClass()}>${pending.map(todoRow)}</div>`,
true,
)}
${collapsible(
line(ListChecksIcon(), `${completed.length} completed`),
html`<div data-slot="trace" class=${traceClass()}>${completed.map(todoRow)}</div>`,
)}
</div>
`;
}
View Code
<details data-slot="trace-collapsible" 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()}>
${CircleIcon()}
</span>
<span data-slot="trace-title" class=${traceTitleClass()}>Fix the focus ring on the select trigger</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()}>
It is clipped by overflow-hidden on the field.
</div>
</details>
AI SDK
The agent writes its todos with a tool, writeTodos in this example. Each call sends the whole list, so render the last call and skip one whose input is still streaming. See AI SDK for streaming the parts from a server action.
const todos = message.parts
.filter((part) => part.type === 'tool-writeTodos')
.filter((part) => part.state !== 'input-streaming')
.at(-1)?.input?.todos;
Map each todo status to a section, an icon and a trace line status. Set "running" on the todo in progress only while the chat streams, so its title stops shimmering when the agent stops.
Migrating from AI SDK Elements
If you used Queue from AI SDK Elements, its wrapper lives in components/ai-elements/queue.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.