Skip to content
WebJs
Menu

Displays the steps the agent plans to take, and how far it has got.

Migrate the dialog components to Base UI.
Plan: migrate to Base UI 4 of 4 done
Install @base-ui/react Replace the Radix imports Rename asChild to render Run the type checker

Migrated Dialog and AlertDialog. The type checker passes.

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.

pnpm dlx @webjsdev/ui add trace

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.

Plan: add dark mode 1 of 4 done

Store the theme in a cookie so the server renders the right one and the page does not flash on load.

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
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.

modules/chat/actions/chat.server.ts
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:

AI SDK ElementsWebJs UI
PlanA trace with a trace collapsible, in place of a Card. Keep isStreaming in your component.
PlanHeaderThe collapsible's <summary>, holding a trace line. Set data-status="running" on the line while it streams, in place of the Shimmer.
PlanTitle, PlanDescriptionA trace title, and a trace description like "2 of 4 done".
PlanContentThe trace collapsible content, holding a trace for the steps.
PlanTriggerNothing of its own, since the whole summary opens the plan.
PlanActionA button next to the trace collapsible, not inside its <summary>, since a button cannot sit inside the trigger.
PlanFooterA plain container.

API Reference

See Trace.