trace

The building block for reasoning, tool calls, sources and more.

PreviousNext
Why does pnpm install fail in CI?
 package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

The last commit bumped a version in package.json without updating pnpm-lock.yaml, so the frozen install fails. Run pnpm install locally and commit the lockfile.

import { NgTemplateOutlet } from '@angular/common';
import { ChangeDetectionStrategy, Component, DestroyRef, inject, signal } from '@angular/core';

import { NgIcon, provideIcons } from '@ng-icons/core';
import {
  lucideArrowUpRight,
  lucideCircleAlert,
  lucideCircleCheck,
  lucideGlobe,
  lucideLoaderCircle,
} from '@ng-icons/lucide';

import { ZardBubbleImports } from '@/shared/components/bubble/bubble.imports';
import { ZardButtonComponent } from '@/shared/components/button/button.component';
import { ZardMessageImports } from '@/shared/components/message/message.imports';
import { ZardTraceImports } from '@/shared/components/trace/trace.imports';

interface ToolCall {
  readonly command: string;
  readonly state: 'running' | 'done' | 'error';
  readonly output: string;
  readonly defaultOpen?: boolean;
}

const QUESTION = 'Why does pnpm install fail in CI?';
const REASONING =
  'CI installs with a frozen lockfile, so the install stops when package.json and pnpm-lock.yaml disagree. I should check what the last commit changed, then reproduce the install.';
const TOOLS: (Omit<ToolCall, 'state'> & { failed?: boolean; duration: number })[] = [
  { command: 'pnpm --version', output: '10.18.0', duration: 700 },
  {
    command: 'git diff --stat HEAD~1 -- package.json pnpm-lock.yaml',
    output: ' package.json | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)',
    duration: 900,
    defaultOpen: true,
  },
  {
    command: 'pnpm install --frozen-lockfile',
    output:
      'ERR_PNPM_OUTDATED_LOCKFILE  Cannot install with "frozen-lockfile" because pnpm-lock.yaml is not up to date with package.json',
    duration: 1200,
    failed: true,
  },
];
const SOURCES = [
  { title: 'pnpm install | pnpm.io', url: 'https://pnpm.io/cli/install#--frozen-lockfile' },
  { title: 'Continuous Integration | pnpm.io', url: 'https://pnpm.io/continuous-integration' },
];
const ANSWER =
  'The last commit bumped a version in package.json without updating pnpm-lock.yaml, so the frozen install fails. Run pnpm install locally and commit the lockfile.';

@Component({
  selector: 'z-demo-trace-preview',
  imports: [
    NgIcon,
    NgTemplateOutlet,
    ZardButtonComponent,
    ...ZardBubbleImports,
    ...ZardMessageImports,
    ...ZardTraceImports,
  ],
  template: `
    <div class="flex min-h-72 w-full max-w-sm flex-col gap-4 py-6 text-sm">
      <z-message zAlign="end">
        <z-message-content>
          <z-bubble zAlign="end" zVariant="muted">
            <z-bubble-content>{{ question }}</z-bubble-content>
          </z-bubble>
        </z-message-content>
      </z-message>

      @if (thinking() || reasoning()) {
        <z-message>
          <z-message-content class="gap-4">
            <z-trace>
              <ng-template #thinkingLine>
                <z-trace-line [zStatus]="thinking() ? 'running' : undefined">
                  <z-trace-icon>
                    <ng-icon
                      [name]="thinking() ? 'lucideLoaderCircle' : 'lucideCircleCheck'"
                      [class.animate-spin]="thinking()"
                    />
                  </z-trace-icon>
                  <z-trace-title>{{ thinking() ? 'Thinking' : 'Thought for 5s' }}</z-trace-title>
                </z-trace-line>
              </ng-template>

              @if (reasoning()) {
                <z-trace-collapsible [zOpen]="reasoningOpen() ?? thinking()" (zOpenChange)="reasoningOpen.set($event)">
                  <z-trace-collapsible-trigger>
                    <ng-container *ngTemplateOutlet="thinkingLine" />
                  </z-trace-collapsible-trigger>
                  <z-trace-collapsible-content class="whitespace-pre-wrap">
                    {{ reasoning() }}
                  </z-trace-collapsible-content>
                </z-trace-collapsible>
              } @else {
                <ng-container *ngTemplateOutlet="thinkingLine" />
              }

              @for (tool of tools(); track tool.command) {
                @if (tool.state === 'running') {
                  <z-trace-line zStatus="running">
                    <z-trace-icon><ng-icon name="lucideLoaderCircle" class="animate-spin" /></z-trace-icon>
                    <z-trace-title>Running {{ tool.command }}</z-trace-title>
                  </z-trace-line>
                } @else {
                  <z-trace-collapsible [zOpen]="tool.defaultOpen ?? false">
                    <z-trace-collapsible-trigger>
                      <z-trace-line [zStatus]="tool.state === 'error' ? 'error' : undefined">
                        <z-trace-icon>
                          <ng-icon [name]="tool.state === 'error' ? 'lucideCircleAlert' : 'lucideCircleCheck'" />
                        </z-trace-icon>
                        <z-trace-title>
                          {{ tool.state === 'error' ? 'Failed to run' : 'Ran' }} {{ tool.command }}
                        </z-trace-title>
                      </z-trace-line>
                    </z-trace-collapsible-trigger>
                    <z-trace-collapsible-content>
                      <pre
                        class="max-h-64 overflow-auto rounded-lg border px-3 py-2.5 font-mono text-xs leading-relaxed whitespace-pre-wrap"
                        [class]="
                          tool.state === 'error'
                            ? 'border-destructive/30 bg-destructive/5 text-destructive'
                            : 'bg-muted/50 text-foreground'
                        "
                        >{{ tool.output }}</pre>
                    </z-trace-collapsible-content>
                  </z-trace-collapsible>
                }
              }

              @if (sources().length) {
                <z-trace-collapsible>
                  <z-trace-collapsible-trigger>
                    <z-trace-line [zStatus]="sourcesRunning() ? 'running' : undefined">
                      <z-trace-icon>
                        <ng-icon
                          [name]="sourcesRunning() ? 'lucideLoaderCircle' : 'lucideGlobe'"
                          [class.animate-spin]="sourcesRunning()"
                        />
                      </z-trace-icon>
                      <z-trace-title>
                        {{ sourcesRunning() ? 'Using' : 'Used' }} {{ sources().length }} sources
                      </z-trace-title>
                    </z-trace-line>
                  </z-trace-collapsible-trigger>
                  <z-trace-collapsible-content>
                    <z-trace>
                      @for (source of sources(); track source.url) {
                        <a [href]="source.url" target="_blank" rel="noreferrer">
                          <z-trace-line>
                            <z-trace-icon><ng-icon name="lucideGlobe" /></z-trace-icon>
                            <z-trace-title>
                              {{ source.title }}
                              <span class="sr-only">(opens in a new tab)</span>
                            </z-trace-title>
                            <z-trace-icon><ng-icon name="lucideArrowUpRight" /></z-trace-icon>
                          </z-trace-line>
                        </a>
                      }
                    </z-trace>
                  </z-trace-collapsible-content>
                </z-trace-collapsible>
              }
            </z-trace>

            @if (answer()) {
              <p>{{ answer() }}</p>
            }
          </z-message-content>
        </z-message>
      }

      @if (!busy()) {
        <button type="button" z-button zType="outline" zSize="sm" class="mt-auto self-start" (click)="replay()">
          Replay
        </button>
      }
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
  viewProviders: [
    provideIcons({ lucideArrowUpRight, lucideCircleAlert, lucideCircleCheck, lucideGlobe, lucideLoaderCircle }),
  ],
  host: { class: 'contents' },
})
export class ZardDemoTracePreviewComponent {
  protected readonly question = QUESTION;

  // The page opens on the finished turn; Replay streams it again.
  protected readonly reasoning = signal(REASONING);
  protected readonly thinking = signal(false);
  /** Undefined until the reader toggles the row, so the reasoning stays open while it streams. */
  protected readonly reasoningOpen = signal<boolean | undefined>(undefined);
  protected readonly tools = signal<ToolCall[]>(
    TOOLS.map(tool => ({ ...tool, state: tool.failed ? 'error' : 'done' })),
  );

  protected readonly sources = signal(SOURCES);
  protected readonly sourcesRunning = signal(false);
  protected readonly answer = signal(ANSWER);
  protected readonly busy = signal(false);

  /** Bumped on every replay and on destroy, so a stale run stops at its next step. */
  private run = 0;

  constructor() {
    inject(DestroyRef).onDestroy(() => this.run++);
  }

  protected async replay(): Promise<void> {
    const run = ++this.run;
    this.busy.set(true);
    this.reasoning.set('');
    this.reasoningOpen.set(undefined);
    this.tools.set([]);
    this.sources.set([]);
    this.answer.set('');

    this.thinking.set(true);
    if (!(await this.stream(REASONING, text => this.reasoning.set(text), 40, run))) return;
    this.thinking.set(false);

    for (const { failed, duration, ...tool } of TOOLS) {
      this.tools.update(tools => [...tools, { ...tool, state: 'running' }]);
      if (!(await this.wait(duration, run))) return;
      this.tools.update(tools =>
        tools.map(item => (item.command === tool.command ? { ...item, state: failed ? 'error' : 'done' } : item)),
      );
    }

    this.sources.set(SOURCES);
    this.sourcesRunning.set(true);
    if (!(await this.wait(1000, run))) return;
    this.sourcesRunning.set(false);

    if (!(await this.stream(ANSWER, text => this.answer.set(text), 20, run))) return;
    this.busy.set(false);
  }

  /** Reveals `text` a word at a time, like a streamed response. Resolves `false` if the run was replaced. */
  private async stream(text: string, set: (value: string) => void, delay: number, run: number): Promise<boolean> {
    let shown = '';
    for (const word of text.split(/(?<= )/)) {
      if (!(await this.wait(delay, run))) return false;
      shown += word;
      set(shown);
    }
    return true;
  }

  private wait(ms: number, run: number): Promise<boolean> {
    return new Promise(resolve => setTimeout(() => resolve(run === this.run), ms));
  }
}
z-trace is a list of lines. Each line has an icon, a title, and an optional description and status. A line can expand to show more detail, link to a page, or open a dialog or sheet.
Every line has the same shape, so reasoning, tool calls, sources and plans built from z-trace look and behave the same.
Use z-trace for the steps an agent takes, like calling a tool, running a subagent or editing a file. Use Message for its reply, and Marker for notes and dividers between turns.
For ready-made patterns built on z-trace, like Reasoning, Plan, Task and Sources, see AI Elements.

Installation

Copy
npx zard-cli@latest add trace

Usage

Use a z-trace-line for a single step:
import { NgIcon, provideIcons } from '@ng-icons/core';
import { lucideSearch, lucideTerminal } from '@ng-icons/lucide';

import { ZardTraceImports } from '@/shared/components/trace/trace.imports';

// Add NgIcon to the component imports and provideIcons({ lucideSearch, lucideTerminal }) to its viewProviders.
Copy
<z-trace>
  <z-trace-line>
    <z-trace-icon><ng-icon name="lucideSearch" /></z-trace-icon>
    <z-trace-title>Searched for minimumReleaseAge</z-trace-title>
  </z-trace-line>
</z-trace>
Copy
Wrap the line in a z-trace-collapsible to show more detail when it expands:
<z-trace>
  <z-trace-collapsible>
    <z-trace-collapsible-trigger>
      <z-trace-line>
        <z-trace-icon><ng-icon name="lucideTerminal" /></z-trace-icon>
        <z-trace-title>Ran node --version</z-trace-title>
      </z-trace-line>
    </z-trace-collapsible-trigger>
    <z-trace-collapsible-content>v24.18.0</z-trace-collapsible-content>
  </z-trace-collapsible>
</z-trace>
Copy

Composition

Use the following composition to build a trace:

z-trace
└── z-trace-line
    ├── z-trace-icon
    ├── z-trace-title
    ├── z-trace-description
    └── z-trace-icon
Copy
Wrap the line in a z-trace-collapsible to show more detail when it expands:
z-trace
└── z-trace-collapsible
    ├── z-trace-collapsible-trigger
    │   └── z-trace-line
    └── z-trace-collapsible-content
Copy
z-trace-line is always the line. To make a line do something, wrap it in that thing’s trigger.

Features

  • One row for reasoning, tool calls, sources, plans and tasks
  • Rows that expand, link out, or open a dialog, sheet, drawer or popover
  • running, error and pending states, with a shimmer while running
  • Nested rows, so a summary expands into steps and a step into its output
  • Keyboard and screen reader support from the trigger that wraps each row
  • Customizable styling through the class input on every part

Trace Line

Use a z-trace-line on its own for a step with no detail to show. It reads as plain text.
Created branch fix/frozen-lockfile
import { ChangeDetectionStrategy, Component } from '@angular/core';

import { NgIcon, provideIcons } from '@ng-icons/core';
import { lucideGitBranch } from '@ng-icons/lucide';

import { ZardTraceImports } from '@/shared/components/trace/trace.imports';

@Component({
  selector: 'z-demo-trace-line',
  imports: [NgIcon, ...ZardTraceImports],
  template: `
    <z-trace class="max-w-sm">
      <z-trace-line>
        <z-trace-icon><ng-icon name="lucideGitBranch" /></z-trace-icon>
        <z-trace-title>Created branch fix/frozen-lockfile</z-trace-title>
      </z-trace-line>
    </z-trace>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
  viewProviders: [provideIcons({ lucideGitBranch })],
  host: { class: 'contents' },
})
export class ZardDemoTraceLineComponent {}

Status

Set zStatus on z-trace-line when a step is running, has failed or hasn’t started yet.
Ran pnpm installFailed to run pnpm lintRunning pnpm buildRun pnpm test
import { ChangeDetectionStrategy, Component } from '@angular/core';

import { NgIcon, provideIcons } from '@ng-icons/core';
import { lucideCircle, lucideCircleAlert, lucideCircleCheck, lucideLoaderCircle } from '@ng-icons/lucide';

import { ZardTraceImports } from '@/shared/components/trace/trace.imports';

@Component({
  selector: 'z-demo-trace-status',
  imports: [NgIcon, ...ZardTraceImports],
  template: `
    <z-trace class="max-w-sm">
      <z-trace-line>
        <z-trace-icon><ng-icon name="lucideCircleCheck" /></z-trace-icon>
        <z-trace-title>Ran pnpm install</z-trace-title>
      </z-trace-line>
      <z-trace-line zStatus="error">
        <z-trace-icon><ng-icon name="lucideCircleAlert" /></z-trace-icon>
        <z-trace-title>Failed to run pnpm lint</z-trace-title>
      </z-trace-line>
      <z-trace-line zStatus="running">
        <z-trace-icon><ng-icon name="lucideLoaderCircle" class="animate-spin" /></z-trace-icon>
        <z-trace-title>Running pnpm build</z-trace-title>
      </z-trace-line>
      <z-trace-line zStatus="pending">
        <z-trace-icon><ng-icon name="lucideCircle" /></z-trace-icon>
        <z-trace-title>Run pnpm test</z-trace-title>
      </z-trace-line>
    </z-trace>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
  viewProviders: [provideIcons({ lucideCircle, lucideCircleAlert, lucideCircleCheck, lucideLoaderCircle })],
  host: { class: 'contents' },
})
export class ZardDemoTraceStatusComponent {}
StatusUse for
noneWork that is done: "Ran pnpm install".
errorWork that failed. Say so in the title: "Failed to run pnpm lint".
runningWork in progress. Write the title in the present tense: "Running pnpm build".
pendingWork that has not started, such as a plan step: "Run pnpm test".

Description

Put secondary text such as a diff stat, a duration or a count in a z-trace-description after the z-trace-title. It does not truncate.
Edited src/app/settings/notification-preferences.component.ts+48 −12Ran pnpm test14sSearched for provideHttpClient8 results
import { ChangeDetectionStrategy, Component } from '@angular/core';

import { NgIcon, provideIcons } from '@ng-icons/core';
import { lucideFilePen, lucideSearch, lucideTerminal } from '@ng-icons/lucide';

import { ZardTraceImports } from '@/shared/components/trace/trace.imports';

@Component({
  selector: 'z-demo-trace-description',
  imports: [NgIcon, ...ZardTraceImports],
  template: `
    <z-trace class="max-w-sm">
      <z-trace-line>
        <z-trace-icon><ng-icon name="lucideFilePen" /></z-trace-icon>
        <z-trace-title>Edited src/app/settings/notification-preferences.component.ts</z-trace-title>
        <z-trace-description class="font-mono">+48 −12</z-trace-description>
      </z-trace-line>
      <z-trace-line>
        <z-trace-icon><ng-icon name="lucideTerminal" /></z-trace-icon>
        <z-trace-title>Ran pnpm test</z-trace-title>
        <z-trace-description>14s</z-trace-description>
      </z-trace-line>
      <z-trace-line>
        <z-trace-icon><ng-icon name="lucideSearch" /></z-trace-icon>
        <z-trace-title>Searched for provideHttpClient</z-trace-title>
        <z-trace-description>8 results</z-trace-description>
      </z-trace-line>
    </z-trace>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
  viewProviders: [provideIcons({ lucideFilePen, lucideSearch, lucideTerminal })],
  host: { class: 'contents' },
})
export class ZardDemoTraceDescriptionComponent {}

Collapsible

Wrap the line in a z-trace-collapsible to show more detail when it expands. Put the z-trace-line inside z-trace-collapsible-trigger and the detail in z-trace-collapsible-content.
import { ChangeDetectionStrategy, Component } from '@angular/core';

import { NgIcon, provideIcons } from '@ng-icons/core';
import { lucideTerminal } from '@ng-icons/lucide';

import { ZardTraceImports } from '@/shared/components/trace/trace.imports';

@Component({
  selector: 'z-demo-trace-collapsible',
  imports: [NgIcon, ...ZardTraceImports],
  template: `
    <div class="w-full max-w-sm">
      <z-trace-collapsible>
        <z-trace-collapsible-trigger>
          <z-trace-line>
            <z-trace-icon><ng-icon name="lucideTerminal" /></z-trace-icon>
            <z-trace-title>Ran node --version</z-trace-title>
          </z-trace-line>
        </z-trace-collapsible-trigger>
        <z-trace-collapsible-content>
          <pre
            class="bg-muted/50 text-foreground max-h-64 overflow-auto rounded-lg border px-3 py-2.5 font-mono text-xs leading-relaxed whitespace-pre-wrap"
            >{{ output }}</pre>
        </z-trace-collapsible-content>
      </z-trace-collapsible>
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
  viewProviders: [provideIcons({ lucideTerminal })],
  host: { class: 'contents' },
})
export class ZardDemoTraceCollapsibleComponent {
  protected readonly output = '$ node --version\nv24.18.0';
}

Open State

Rows start closed. Set zOpen on z-trace-collapsible to start open, or bind [(zOpen)] to control a row.
$ node --version
v24.18.0
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';

import { NgIcon, provideIcons } from '@ng-icons/core';
import { lucideTerminal } from '@ng-icons/lucide';

import { ZardButtonComponent } from '@/shared/components/button/button.component';
import { ZardTraceImports } from '@/shared/components/trace/trace.imports';

@Component({
  selector: 'z-demo-trace-open',
  imports: [NgIcon, ZardButtonComponent, ...ZardTraceImports],
  template: `
    <div class="flex w-full max-w-sm flex-col items-start gap-4">
      <z-trace-collapsible zOpen>
        <z-trace-collapsible-trigger>
          <z-trace-line>
            <z-trace-icon><ng-icon name="lucideTerminal" /></z-trace-icon>
            <z-trace-title>Ran node --version</z-trace-title>
          </z-trace-line>
        </z-trace-collapsible-trigger>
        <z-trace-collapsible-content>
          <pre
            class="bg-muted/50 text-foreground max-h-64 overflow-auto rounded-lg border px-3 py-2.5 font-mono text-xs leading-relaxed whitespace-pre-wrap"
            >{{ nodeOutput }}</pre>
        </z-trace-collapsible-content>
      </z-trace-collapsible>

      <z-trace-collapsible [(zOpen)]="open">
        <z-trace-collapsible-trigger>
          <z-trace-line>
            <z-trace-icon><ng-icon name="lucideTerminal" /></z-trace-icon>
            <z-trace-title>Ran pnpm --version</z-trace-title>
          </z-trace-line>
        </z-trace-collapsible-trigger>
        <z-trace-collapsible-content>
          <pre
            class="bg-muted/50 text-foreground max-h-64 overflow-auto rounded-lg border px-3 py-2.5 font-mono text-xs leading-relaxed whitespace-pre-wrap"
            >{{ pnpmOutput }}</pre>
        </z-trace-collapsible-content>
      </z-trace-collapsible>

      <button type="button" z-button zType="outline" zSize="sm" (click)="open.set(!open())">
        {{ open() ? 'Hide' : 'Show' }} the pnpm output
      </button>
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
  viewProviders: [provideIcons({ lucideTerminal })],
  host: { class: 'contents' },
})
export class ZardDemoTraceOpenComponent {
  protected readonly open = signal(false);
  protected readonly nodeOutput = '$ node --version\nv24.18.0';
  protected readonly pnpmOutput = '$ pnpm --version\n10.33.4';
}
To open a row while it streams and let the reader’s click win, keep the reader’s choice in a signal that starts undefined and bind open() ?? running().
// Undefined until the reader toggles the row, so it follows `running` until then.
protected readonly open = signal<boolean | undefined>(undefined);
Copy
<z-trace-collapsible [zOpen]="open() ?? running()" (zOpenChange)="open.set($event)">
  <z-trace-collapsible-trigger>
    <z-trace-line [zStatus]="running() ? 'running' : undefined">…</z-trace-line>
  </z-trace-collapsible-trigger>
  <z-trace-collapsible-content>{{ text() }}</z-trace-collapsible-content>
</z-trace-collapsible>
Copy

Dialog

Wrap the z-trace-line in the button that opens the dialog. The dialog owns its open state, Escape and focus return.
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';

import { NgIcon, provideIcons } from '@ng-icons/core';
import { lucideArrowUpRight, lucideChevronRight, lucideGlobe } from '@ng-icons/lucide';

import { ZardDialogImports } from '@/shared/components/dialog/dialog.imports';
import { ZardTraceImports } from '@/shared/components/trace/trace.imports';

@Component({
  selector: 'z-demo-trace-dialog',
  imports: [NgIcon, ...ZardDialogImports, ...ZardTraceImports],
  template: `
    <z-trace class="max-w-sm">
      <button type="button" (click)="open.set(true)">
        <z-trace-line>
          <z-trace-icon><ng-icon name="lucideGlobe" /></z-trace-icon>
          <z-trace-title>Searched the web for build cache settings</z-trace-title>
          <z-trace-icon><ng-icon name="lucideChevronRight" class="rtl:-scale-x-100" /></z-trace-icon>
        </z-trace-line>
      </button>
    </z-trace>

    <z-dialog [(zVisible)]="open">
      <z-dialog-header>
        <z-dialog-title>Searched the web for build cache settings</z-dialog-title>
        <z-dialog-description>Three results were used in the response.</z-dialog-description>
      </z-dialog-header>
      <z-trace>
        @for (result of results; track result.url) {
          <a [href]="result.url" target="_blank" rel="noreferrer">
            <z-trace-line>
              <z-trace-icon><ng-icon name="lucideGlobe" /></z-trace-icon>
              <z-trace-title>
                {{ result.title }}
                <span class="sr-only">(opens in a new tab)</span>
              </z-trace-title>
              <z-trace-icon><ng-icon name="lucideArrowUpRight" /></z-trace-icon>
            </z-trace-line>
          </a>
        }
      </z-trace>
    </z-dialog>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
  viewProviders: [provideIcons({ lucideArrowUpRight, lucideChevronRight, lucideGlobe })],
  host: { class: 'contents' },
})
export class ZardDemoTraceDialogComponent {
  protected readonly open = signal(false);

  protected readonly results = [
    { title: 'Build cache | angular.dev', url: 'https://angular.dev/cli/cache' },
    { title: 'Image optimization | angular.dev', url: 'https://angular.dev/guide/image-optimization' },
    { title: 'Building Angular apps | angular.dev', url: 'https://angular.dev/tools/cli/build' },
  ];
}
<button type="button" (click)="open.set(true)">
  <z-trace-line>
    <z-trace-title>Searched the web for build cache settings</z-trace-title>
    <z-trace-icon><ng-icon name="lucideChevronRight" /></z-trace-icon>
  </z-trace-line>
</button>

<z-dialog [(zVisible)]="open">…</z-dialog>
Copy

Sheet

The same shape as the dialog. Drawer and Popover work the same way.
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';

import { NgIcon, provideIcons } from '@ng-icons/core';
import { lucideChevronRight, lucideFolderSearch } from '@ng-icons/lucide';

import { ZardSheetImports } from '@/shared/components/sheet/sheet.imports';
import { ZardTraceImports } from '@/shared/components/trace/trace.imports';

@Component({
  selector: 'z-demo-trace-sheet',
  imports: [NgIcon, ...ZardSheetImports, ...ZardTraceImports],
  template: `
    <z-trace class="max-w-sm">
      <button type="button" (click)="open.set(true)">
        <z-trace-line>
          <z-trace-icon><ng-icon name="lucideFolderSearch" /></z-trace-icon>
          <z-trace-title>Explored {{ files.length }} files</z-trace-title>
          <z-trace-icon><ng-icon name="lucideChevronRight" class="rtl:-scale-x-100" /></z-trace-icon>
        </z-trace-line>
      </button>
    </z-trace>

    <z-sheet [(zVisible)]="open">
      <z-sheet-header>
        <z-sheet-title>Explored {{ files.length }} files</z-sheet-title>
        <z-sheet-description>Files read while preparing the response.</z-sheet-description>
      </z-sheet-header>
      <ul class="flex flex-col gap-2 px-6 font-mono text-xs">
        @for (file of files; track file) {
          <li>{{ file }}</li>
        }
      </ul>
    </z-sheet>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
  viewProviders: [provideIcons({ lucideChevronRight, lucideFolderSearch })],
  host: { class: 'contents' },
})
export class ZardDemoTraceSheetComponent {
  protected readonly open = signal(false);

  protected readonly files = ['src/app/app.config.ts', 'src/app/app.routes.ts', 'angular.json', 'package.json'];
}

Group

Put rows that sit next to each other in a z-trace. It also styles any trigger or link that wraps a z-trace-line.
Searched for minimumReleaseAgeRead pnpm-workspace.yamlRan pnpm install
import { ChangeDetectionStrategy, Component } from '@angular/core';

import { NgIcon, provideIcons } from '@ng-icons/core';
import { lucideFileText, lucideSearch, lucideTerminal } from '@ng-icons/lucide';

import { ZardTraceImports } from '@/shared/components/trace/trace.imports';

@Component({
  selector: 'z-demo-trace-group',
  imports: [NgIcon, ...ZardTraceImports],
  template: `
    <z-trace class="max-w-sm">
      <z-trace-line>
        <z-trace-icon><ng-icon name="lucideSearch" /></z-trace-icon>
        <z-trace-title>Searched for minimumReleaseAge</z-trace-title>
      </z-trace-line>
      <z-trace-line>
        <z-trace-icon><ng-icon name="lucideFileText" /></z-trace-icon>
        <z-trace-title>Read pnpm-workspace.yaml</z-trace-title>
      </z-trace-line>
      <z-trace-line>
        <z-trace-icon><ng-icon name="lucideTerminal" /></z-trace-icon>
        <z-trace-title>Ran pnpm install</z-trace-title>
      </z-trace-line>
    </z-trace>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
  viewProviders: [provideIcons({ lucideFileText, lucideSearch, lucideTerminal })],
  host: { class: 'contents' },
})
export class ZardDemoTraceGroupComponent {}

Sources

A collapsible row whose detail is a z-trace of link rows. See the Sources pattern.
import { ChangeDetectionStrategy, Component } from '@angular/core';

import { NgIcon, provideIcons } from '@ng-icons/core';
import { lucideArrowUpRight, lucideGlobe } from '@ng-icons/lucide';

import { ZardTraceImports } from '@/shared/components/trace/trace.imports';

@Component({
  selector: 'z-demo-trace-sources',
  imports: [NgIcon, ...ZardTraceImports],
  template: `
    <div class="w-full max-w-sm">
      <z-trace-collapsible zOpen>
        <z-trace-collapsible-trigger>
          <z-trace-line>
            <z-trace-icon><ng-icon name="lucideGlobe" /></z-trace-icon>
            <z-trace-title>Used {{ sources.length }} sources</z-trace-title>
          </z-trace-line>
        </z-trace-collapsible-trigger>
        <z-trace-collapsible-content>
          <z-trace>
            @for (source of sources; track source.href) {
              <a [href]="source.href" target="_blank" rel="noreferrer">
                <z-trace-line>
                  <z-trace-icon><ng-icon name="lucideGlobe" /></z-trace-icon>
                  <z-trace-title>
                    {{ source.title }}
                    <span class="sr-only">(opens in a new tab)</span>
                  </z-trace-title>
                  <z-trace-icon><ng-icon name="lucideArrowUpRight" /></z-trace-icon>
                </z-trace-line>
              </a>
            }
          </z-trace>
        </z-trace-collapsible-content>
      </z-trace-collapsible>
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
  viewProviders: [provideIcons({ lucideArrowUpRight, lucideGlobe })],
  host: { class: 'contents' },
})
export class ZardDemoTraceSourcesComponent {
  protected readonly sources = [
    { title: 'Installation | angular.dev', href: 'https://angular.dev/installation' },
    { title: '@angular/cli | npmjs.com', href: 'https://www.npmjs.com/package/@angular/cli' },
    { title: 'Settings: minimumReleaseAge | pnpm.io', href: 'https://pnpm.io/settings#minimumreleaseage' },
  ];
}

Chain of Thought

A chain of thought is a collapsible row with step rows inside. Set the parent’s status and title from its children.
Read the last twelve deploys
import { ChangeDetectionStrategy, Component } from '@angular/core';

import { NgIcon, provideIcons } from '@ng-icons/core';
import { lucideChevronRight, lucideFileText, lucideSearch } from '@ng-icons/lucide';

import { ZardBadgeComponent } from '@/shared/components/badge/badge.component';
import { ZardTraceImports } from '@/shared/components/trace/trace.imports';

@Component({
  selector: 'z-demo-trace-chain-of-thought',
  imports: [NgIcon, ZardBadgeComponent, ...ZardTraceImports],
  template: `
    <div class="w-full max-w-sm">
      <z-trace-collapsible zOpen>
        <z-trace-collapsible-trigger>
          <z-trace-line zStatus="running">
            <z-trace-title>Looking into the slow deploy</z-trace-title>
          </z-trace-line>
        </z-trace-collapsible-trigger>
        <z-trace-collapsible-content zKeepMounted>
          <z-trace>
            <z-trace-collapsible>
              <z-trace-collapsible-trigger>
                <z-trace-line>
                  <z-trace-icon><ng-icon name="lucideSearch" /></z-trace-icon>
                  <z-trace-title>Searched for the checkout build log</z-trace-title>
                </z-trace-line>
              </z-trace-collapsible-trigger>
              <z-trace-collapsible-content class="flex flex-wrap gap-1.5">
                <z-badge zType="secondary">angular.dev</z-badge>
                <z-badge zType="secondary">github.com</z-badge>
              </z-trace-collapsible-content>
            </z-trace-collapsible>

            <a href="#chain-of-thought">
              <z-trace-line>
                <z-trace-icon><ng-icon name="lucideFileText" /></z-trace-icon>
                <z-trace-title>Read the last twelve deploys</z-trace-title>
                <z-trace-icon><ng-icon name="lucideChevronRight" class="rtl:-scale-x-100" /></z-trace-icon>
              </z-trace-line>
            </a>

            <z-trace-collapsible>
              <z-trace-collapsible-trigger>
                <z-trace-line zStatus="running">
                  <z-trace-icon><ng-icon name="lucideSearch" /></z-trace-icon>
                  <z-trace-title>Searching for the cache key</z-trace-title>
                </z-trace-line>
              </z-trace-collapsible-trigger>
              <z-trace-collapsible-content>
                <pre
                  class="bg-muted/50 text-foreground max-h-64 overflow-auto rounded-lg border px-3 py-2.5 font-mono text-xs leading-relaxed whitespace-pre-wrap"
                >
cache key image optimization</pre>
              </z-trace-collapsible-content>
            </z-trace-collapsible>
          </z-trace>
        </z-trace-collapsible-content>
      </z-trace-collapsible>
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
  viewProviders: [provideIcons({ lucideChevronRight, lucideFileText, lucideSearch })],
  host: { class: 'contents' },
})
export class ZardDemoTraceChainOfThoughtComponent {}

Commit

A commit is a collapsible row with a line for each changed file. Say what changed in the title, Added, Edited or Deleted, and put the line counts in the description. Each file opens its diff in a Sheet.
import { ChangeDetectionStrategy, Component, computed, signal } from '@angular/core';

import { NgIcon, provideIcons } from '@ng-icons/core';
import { lucideChevronRight, lucideFilePen, lucideFilePlus, lucideGitCommitHorizontal } from '@ng-icons/lucide';

import { ZardSheetImports } from '@/shared/components/sheet/sheet.imports';
import { ZardTraceImports } from '@/shared/components/trace/trace.imports';

interface ChangedFile {
  readonly path: string;
  readonly added: boolean;
  readonly additions: number;
  readonly deletions: number;
  readonly diff: string;
}

type DiffKind = 'hunk' | 'added' | 'removed' | 'context';

@Component({
  selector: 'z-demo-trace-commit',
  imports: [NgIcon, ...ZardSheetImports, ...ZardTraceImports],
  template: `
    <z-trace class="max-w-sm">
      <z-trace-collapsible zOpen>
        <z-trace-collapsible-trigger>
          <z-trace-line>
            <z-trace-icon><ng-icon name="lucideGitCommitHorizontal" /></z-trace-icon>
            <z-trace-title>Committed a1b2c3: Fix the login redirect</z-trace-title>
          </z-trace-line>
        </z-trace-collapsible-trigger>
        <z-trace-collapsible-content>
          <z-trace>
            @for (file of files; track file.path) {
              <button type="button" (click)="show(file)">
                <z-trace-line>
                  <z-trace-icon><ng-icon [name]="file.added ? 'lucideFilePlus' : 'lucideFilePen'" /></z-trace-icon>
                  <z-trace-title>{{ file.added ? 'Added' : 'Edited' }} {{ file.path }}</z-trace-title>
                  <z-trace-description class="font-mono">
                    +{{ file.additions }} −{{ file.deletions }}
                  </z-trace-description>
                  <z-trace-icon><ng-icon name="lucideChevronRight" class="rtl:-scale-x-100" /></z-trace-icon>
                </z-trace-line>
              </button>
            }
          </z-trace>
        </z-trace-collapsible-content>
      </z-trace-collapsible>
    </z-trace>

    <z-sheet [(zVisible)]="open" zSize="lg">
      <z-sheet-header>
        <z-sheet-title class="font-mono">{{ selected().path }}</z-sheet-title>
        <z-sheet-description>
          {{ selected().additions }} additions, {{ selected().deletions }} deletions
        </z-sheet-description>
      </z-sheet-header>
      <pre
        class="bg-muted/50 mx-6 mb-6 rounded-lg border py-3 font-mono text-xs leading-relaxed"
      ><code>@for (line of lines(); track $index) {<span class="block px-3 wrap-break-word whitespace-pre-wrap" [class]="lineClass[line.kind]">{{ line.text }}</span>}</code></pre>
    </z-sheet>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
  viewProviders: [provideIcons({ lucideChevronRight, lucideFilePen, lucideFilePlus, lucideGitCommitHorizontal })],
  host: { class: 'contents' },
})
export class ZardDemoTraceCommitComponent {
  protected readonly files: readonly ChangedFile[] = [
    {
      path: 'src/app/login/login.component.ts',
      added: false,
      additions: 2,
      deletions: 2,
      diff: `@@ -18,7 +18,7 @@ export class LoginComponent {
   private readonly route = inject(ActivatedRoute);
   private readonly router = inject(Router);
 
-  private readonly redirectTo =
-    this.route.snapshot.queryParamMap.get('next') ?? '/';
+  private readonly redirectTo = safeRedirect(
+    this.route.snapshot.queryParamMap.get('next'));
 
   protected onSignedIn(): void {`,
    },
    {
      path: 'src/app/auth/safe-redirect.ts',
      added: true,
      additions: 7,
      deletions: 0,
      diff: `@@ -0,0 +1,7 @@
+export function safeRedirect(next: string | null): string {
+  if (!next || !next.startsWith('/') || next.startsWith('//')) {
+    return '/';
+  }
+
+  return next;
+}`,
    },
  ];

  protected readonly open = signal(false);
  protected readonly selected = signal<ChangedFile>(this.files[0]);

  protected readonly lineClass: Record<DiffKind, string> = {
    hunk: 'text-muted-foreground',
    added: 'bg-emerald-500/10 text-emerald-700 dark:text-emerald-400',
    removed: 'bg-red-500/10 text-red-700 dark:text-red-400',
    context: 'text-foreground',
  };

  /** One entry per diff line, without the leading `+`, `-` or space. */
  protected readonly lines = computed(() =>
    this.selected()
      .diff.split('\n')
      .map(line => {
        if (line.startsWith('@@')) return { kind: 'hunk' as DiffKind, text: line };
        const kind: DiffKind = line.startsWith('+') ? 'added' : line.startsWith('-') ? 'removed' : 'context';
        return { kind, text: line.slice(1) || ' ' };
      }),
  );

  protected show(file: ChangedFile): void {
    this.selected.set(file);
    this.open.set(true);
  }
}

Whole Turn

Three levels: the turn, a summary, and the rows. Text between steps sits between two z-trace lists.
Ran node --version

Node is installed and pnpm is not. Reading the workspace config.

Read angular.json
import { ChangeDetectionStrategy, Component } from '@angular/core';

import { NgIcon, provideIcons } from '@ng-icons/core';
import { lucideBrain, lucideChevronRight, lucideFileText, lucideTerminal } from '@ng-icons/lucide';

import { ZardTraceImports } from '@/shared/components/trace/trace.imports';

@Component({
  selector: 'z-demo-trace-whole-turn',
  imports: [NgIcon, ...ZardTraceImports],
  template: `
    <div class="w-full max-w-sm">
      <z-trace-collapsible zOpen>
        <z-trace-collapsible-trigger>
          <z-trace-line zStatus="error">
            <z-trace-title>Worked for 2m 4s, 1 command failed</z-trace-title>
          </z-trace-line>
        </z-trace-collapsible-trigger>
        <z-trace-collapsible-content zKeepMounted class="flex flex-col gap-2">
          <z-trace>
            <z-trace-collapsible>
              <z-trace-collapsible-trigger>
                <z-trace-line>
                  <z-trace-icon><ng-icon name="lucideBrain" /></z-trace-icon>
                  <z-trace-title>Thought</z-trace-title>
                  <z-trace-description>12s</z-trace-description>
                </z-trace-line>
              </z-trace-collapsible-trigger>
              <z-trace-collapsible-content class="whitespace-pre-wrap">
                I should check which package managers are installed before I scaffold anything.
              </z-trace-collapsible-content>
            </z-trace-collapsible>

            <z-trace-collapsible zOpen>
              <z-trace-collapsible-trigger>
                <z-trace-line zStatus="error">
                  <z-trace-icon><ng-icon name="lucideTerminal" /></z-trace-icon>
                  <z-trace-title>Ran 2 commands, 1 failed</z-trace-title>
                </z-trace-line>
              </z-trace-collapsible-trigger>
              <z-trace-collapsible-content zKeepMounted>
                <z-trace>
                  <z-trace-line>
                    <z-trace-icon><ng-icon name="lucideTerminal" /></z-trace-icon>
                    <z-trace-title>Ran node --version</z-trace-title>
                  </z-trace-line>
                  <z-trace-collapsible>
                    <z-trace-collapsible-trigger>
                      <z-trace-line zStatus="error">
                        <z-trace-icon><ng-icon name="lucideTerminal" /></z-trace-icon>
                        <z-trace-title>Failed to run pnpm --version</z-trace-title>
                      </z-trace-line>
                    </z-trace-collapsible-trigger>
                    <z-trace-collapsible-content>
                      <pre
                        class="border-destructive/30 bg-destructive/5 text-destructive max-h-64 overflow-auto rounded-lg border px-3 py-2.5 font-mono text-xs leading-relaxed whitespace-pre-wrap"
                        >{{ error }}</pre>
                    </z-trace-collapsible-content>
                  </z-trace-collapsible>
                </z-trace>
              </z-trace-collapsible-content>
            </z-trace-collapsible>
          </z-trace>

          <p class="text-foreground">Node is installed and pnpm is not. Reading the workspace config.</p>

          <z-trace>
            <a href="#whole-turn">
              <z-trace-line>
                <z-trace-icon><ng-icon name="lucideFileText" /></z-trace-icon>
                <z-trace-title>Read angular.json</z-trace-title>
                <z-trace-icon><ng-icon name="lucideChevronRight" class="rtl:-scale-x-100" /></z-trace-icon>
              </z-trace-line>
            </a>
          </z-trace>
        </z-trace-collapsible-content>
      </z-trace-collapsible>
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
  viewProviders: [provideIcons({ lucideBrain, lucideChevronRight, lucideFileText, lucideTerminal })],
  host: { class: 'contents' },
})
export class ZardDemoTraceWholeTurnComponent {
  protected readonly error = 'command not found: pnpm';
}

Reasoning

Render the reasoning of a streamed reply. The row is a z-trace-line until the first text arrives. See Open State and the Reasoning pattern.
import { NgTemplateOutlet } from '@angular/common';
import { ChangeDetectionStrategy, Component, DestroyRef, inject, signal } from '@angular/core';

import { NgIcon, provideIcons } from '@ng-icons/core';
import { lucideBrain } from '@ng-icons/lucide';

import { ZardBubbleImports } from '@/shared/components/bubble/bubble.imports';
import { ZardButtonComponent } from '@/shared/components/button/button.component';
import { ZardMessageImports } from '@/shared/components/message/message.imports';
import { ZardTraceImports } from '@/shared/components/trace/trace.imports';

const QUESTION = 'Why is the checkout deploy so slow?';
const REASONING =
  'The build log shows install and compile finish in under a minute. Image optimization takes almost four, and it reruns on every deploy because the cache key includes the commit hash.';
const ANSWER =
  'Image optimization is the bottleneck. Key its cache on the lockfile and the image directory instead of the commit hash.';

@Component({
  selector: 'z-demo-trace-reasoning',
  imports: [
    NgIcon,
    NgTemplateOutlet,
    ZardButtonComponent,
    ...ZardBubbleImports,
    ...ZardMessageImports,
    ...ZardTraceImports,
  ],
  template: `
    <div class="flex min-h-72 w-full max-w-sm flex-col gap-4 py-6 text-sm">
      @if (sent()) {
        <z-message zAlign="end">
          <z-message-content>
            <z-bubble zAlign="end" zVariant="muted">
              <z-bubble-content>{{ question }}</z-bubble-content>
            </z-bubble>
          </z-message-content>
        </z-message>
      }

      @if (thinking() || reasoning()) {
        <z-message>
          <z-message-content class="gap-4">
            <z-trace>
              <ng-template #line>
                <z-trace-line [zStatus]="thinking() ? 'running' : undefined">
                  <z-trace-icon><ng-icon name="lucideBrain" /></z-trace-icon>
                  <z-trace-title>{{ thinking() ? 'Thinking' : 'Thought' }}</z-trace-title>
                </z-trace-line>
              </ng-template>

              <!-- A plain line until the first text arrives, then a row that follows the stream until it is toggled. -->
              @if (reasoning()) {
                <z-trace-collapsible [zOpen]="open() ?? thinking()" (zOpenChange)="open.set($event)">
                  <z-trace-collapsible-trigger>
                    <ng-container *ngTemplateOutlet="line" />
                  </z-trace-collapsible-trigger>
                  <z-trace-collapsible-content class="whitespace-pre-wrap">
                    {{ reasoning() }}
                  </z-trace-collapsible-content>
                </z-trace-collapsible>
              } @else {
                <ng-container *ngTemplateOutlet="line" />
              }
            </z-trace>

            @if (answer()) {
              <p>{{ answer() }}</p>
            }
          </z-message-content>
        </z-message>
      }

      @if (!busy()) {
        <button type="button" z-button zType="outline" zSize="sm" class="mt-auto self-start" (click)="next()">
          {{ sent() ? 'Reset' : 'Send message' }}
        </button>
      }
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
  viewProviders: [provideIcons({ lucideBrain })],
  host: { class: 'contents' },
})
export class ZardDemoTraceReasoningComponent {
  protected readonly question = QUESTION;

  protected readonly sent = signal(false);
  protected readonly thinking = signal(false);
  protected readonly reasoning = signal('');
  protected readonly open = signal<boolean | undefined>(undefined);
  protected readonly answer = signal('');
  protected readonly busy = signal(false);

  /** Bumped on every run and on destroy, so a stale run stops at its next step. */
  private run = 0;

  constructor() {
    inject(DestroyRef).onDestroy(() => this.run++);
  }

  protected next(): void {
    if (this.sent()) {
      this.reset();
    } else {
      void this.send();
    }
  }

  private reset(): void {
    this.run++;
    this.sent.set(false);
    this.thinking.set(false);
    this.reasoning.set('');
    this.open.set(undefined);
    this.answer.set('');
  }

  private async send(): Promise<void> {
    const run = ++this.run;
    this.sent.set(true);
    this.busy.set(true);
    this.thinking.set(true);

    if (!(await this.wait(400, run))) return;
    if (!(await this.stream(REASONING, text => this.reasoning.set(text), 60, run))) return;
    this.thinking.set(false);

    if (!(await this.wait(400, run))) return;
    if (!(await this.stream(ANSWER, text => this.answer.set(text), 20, run))) return;
    this.busy.set(false);
  }

  /** Reveals `text` a word at a time, like a streamed response. Resolves `false` if the run was replaced. */
  private async stream(text: string, set: (value: string) => void, delay: number, run: number): Promise<boolean> {
    let shown = '';
    for (const word of text.split(/(?<= )/)) {
      if (!(await this.wait(delay, run))) return false;
      shown += word;
      set(shown);
    }
    return true;
  }

  private wait(ms: number, run: number): Promise<boolean> {
    return new Promise(resolve => setTimeout(() => resolve(run === this.run), ms));
  }
}

Tool

Render the tool calls of a streamed reply: a running line while the call runs, then a row that expands into its output.
import { ChangeDetectionStrategy, Component, DestroyRef, inject, signal } from '@angular/core';

import { NgIcon, provideIcons } from '@ng-icons/core';
import { lucideTerminal } from '@ng-icons/lucide';

import { ZardBubbleImports } from '@/shared/components/bubble/bubble.imports';
import { ZardButtonComponent } from '@/shared/components/button/button.component';
import { ZardMessageImports } from '@/shared/components/message/message.imports';
import { ZardTraceImports } from '@/shared/components/trace/trace.imports';

interface ToolCall {
  readonly command: string;
  readonly state: 'running' | 'done' | 'error';
  readonly output: string;
}

const QUESTION = 'Which package managers are installed?';
const COMMANDS = [
  { command: 'node --version', output: 'v24.18.0', failed: false },
  { command: 'npm --version', output: '11.6.2', failed: false },
  { command: 'pnpm --version', output: 'command not found: pnpm', failed: true },
];
const ANSWER = 'Node 24 and npm 11 are installed. pnpm is not.';

@Component({
  selector: 'z-demo-trace-tool',
  imports: [NgIcon, ZardButtonComponent, ...ZardBubbleImports, ...ZardMessageImports, ...ZardTraceImports],
  template: `
    <div class="flex min-h-72 w-full max-w-sm flex-col gap-4 py-6 text-sm">
      @if (sent()) {
        <z-message zAlign="end">
          <z-message-content>
            <z-bubble zAlign="end" zVariant="muted">
              <z-bubble-content>{{ question }}</z-bubble-content>
            </z-bubble>
          </z-message-content>
        </z-message>
      }

      @if (tools().length) {
        <z-message>
          <z-message-content class="gap-4">
            <z-trace>
              @for (tool of tools(); track tool.command) {
                @if (tool.state === 'running') {
                  <z-trace-line zStatus="running">
                    <z-trace-icon><ng-icon name="lucideTerminal" /></z-trace-icon>
                    <z-trace-title>Running {{ tool.command }}</z-trace-title>
                  </z-trace-line>
                } @else {
                  <z-trace-collapsible>
                    <z-trace-collapsible-trigger>
                      <z-trace-line [zStatus]="tool.state === 'error' ? 'error' : undefined">
                        <z-trace-icon><ng-icon name="lucideTerminal" /></z-trace-icon>
                        <z-trace-title>
                          {{ tool.state === 'error' ? 'Failed to run' : 'Ran' }} {{ tool.command }}
                        </z-trace-title>
                      </z-trace-line>
                    </z-trace-collapsible-trigger>
                    <z-trace-collapsible-content>
                      <pre
                        class="bg-muted/50 text-foreground max-h-64 overflow-auto rounded-lg border px-3 py-2.5 font-mono text-xs leading-relaxed whitespace-pre-wrap"
                        >{{ tool.output }}</pre>
                    </z-trace-collapsible-content>
                  </z-trace-collapsible>
                }
              }
            </z-trace>

            @if (answer()) {
              <p>{{ answer() }}</p>
            }
          </z-message-content>
        </z-message>
      }

      @if (!busy()) {
        <button type="button" z-button zType="outline" zSize="sm" class="mt-auto self-start" (click)="next()">
          {{ sent() ? 'Reset' : 'Send message' }}
        </button>
      }
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
  viewProviders: [provideIcons({ lucideTerminal })],
  host: { class: 'contents' },
})
export class ZardDemoTraceToolComponent {
  protected readonly question = QUESTION;

  protected readonly sent = signal(false);
  protected readonly tools = signal<ToolCall[]>([]);
  protected readonly answer = signal('');
  protected readonly busy = signal(false);

  /** Bumped on every run and on destroy, so a stale run stops at its next step. */
  private run = 0;

  constructor() {
    inject(DestroyRef).onDestroy(() => this.run++);
  }

  protected next(): void {
    if (this.sent()) {
      this.run++;
      this.sent.set(false);
      this.tools.set([]);
      this.answer.set('');
    } else {
      void this.send();
    }
  }

  private async send(): Promise<void> {
    const run = ++this.run;
    this.sent.set(true);
    this.busy.set(true);

    for (const { failed, ...tool } of COMMANDS) {
      this.tools.update(tools => [...tools, { ...tool, state: 'running' }]);
      if (!(await this.wait(900, run))) return;
      this.tools.update(tools =>
        tools.map(item => (item.command === tool.command ? { ...item, state: failed ? 'error' : 'done' } : item)),
      );
    }

    let shown = '';
    for (const word of ANSWER.split(/(?<= )/)) {
      if (!(await this.wait(20, run))) return;
      shown += word;
      this.answer.set(shown);
    }
    this.busy.set(false);
  }

  private wait(ms: number, run: number): Promise<boolean> {
    return new Promise(resolve => setTimeout(() => resolve(run === this.run), ms));
  }
}

RTL

To enable RTL support in zard/ui, see the RTL configuration guide.
تم البحث عن minimumReleaseAge
قراءة وثائق pnpm (يفتح في علامة تبويب جديدة)جارٍ تشغيل pnpm build
// You will notice this example is rendered inside a wrapper that sets the dir and data-lang attributes, and
// reads its text from a translations helper. This is because this site is not RTL by default.
// In your application you won't need either: set dir="rtl" on <html> (or use the CDK Dir directive on a subtree)
// and write the text of your own language. See the RTL guide: https://zardui.com/docs/rtl

import { ChangeDetectionStrategy, Component } from '@angular/core';

import { NgIcon, provideIcons } from '@ng-icons/core';
import { lucideArrowUpRight, lucideSearch, lucideTerminal } from '@ng-icons/lucide';

import { ZardTraceImports } from '@/shared/components/trace/trace.imports';
import { injectRtlTranslation, type ZardRtlTranslations } from '@/shared/demo-utils/rtl-translation';

const translations: ZardRtlTranslations<{
  searched: string;
  ran: string;
  duration: string;
  output: string;
  running: string;
  read: string;
  opensInNewTab: string;
}> = {
  en: {
    dir: 'ltr',
    values: {
      searched: 'Searched for minimumReleaseAge',
      ran: 'Ran pnpm install',
      duration: '12s',
      output: 'Done in 11.8s',
      running: 'Running pnpm build',
      read: 'Read the pnpm docs',
      opensInNewTab: '(opens in a new tab)',
    },
  },
  ar: {
    dir: 'rtl',
    values: {
      searched: 'تم البحث عن minimumReleaseAge',
      ran: 'تم تشغيل pnpm install',
      duration: '12 ث',
      output: 'تم في 11.8 ثانية',
      running: 'جارٍ تشغيل pnpm build',
      read: 'قراءة وثائق pnpm',
      opensInNewTab: '(يفتح في علامة تبويب جديدة)',
    },
  },
  he: {
    dir: 'rtl',
    values: {
      searched: 'חיפוש של minimumReleaseAge',
      ran: 'הורץ pnpm install',
      duration: '12 שנ׳',
      output: 'הסתיים ב-11.8 שניות',
      running: 'מריץ את pnpm build',
      read: 'קריאת התיעוד של pnpm',
      opensInNewTab: '(נפתח בלשונית חדשה)',
    },
  },
};

@Component({
  selector: 'z-demo-trace-rtl',
  imports: [NgIcon, ...ZardTraceImports],
  template: `
    <z-trace class="max-w-sm">
      <z-trace-line>
        <z-trace-icon><ng-icon name="lucideSearch" /></z-trace-icon>
        <z-trace-title>{{ i18n.t().searched }}</z-trace-title>
      </z-trace-line>

      <z-trace-collapsible>
        <z-trace-collapsible-trigger>
          <z-trace-line>
            <z-trace-icon><ng-icon name="lucideTerminal" /></z-trace-icon>
            <z-trace-title>{{ i18n.t().ran }}</z-trace-title>
            <z-trace-description>{{ i18n.t().duration }}</z-trace-description>
          </z-trace-line>
        </z-trace-collapsible-trigger>
        <z-trace-collapsible-content>{{ i18n.t().output }}</z-trace-collapsible-content>
      </z-trace-collapsible>

      <a href="https://pnpm.io" target="_blank" rel="noreferrer">
        <z-trace-line>
          <z-trace-icon><ng-icon name="lucideSearch" /></z-trace-icon>
          <z-trace-title>
            {{ i18n.t().read }}
            <span class="sr-only">{{ i18n.t().opensInNewTab }}</span>
          </z-trace-title>
          <z-trace-icon><ng-icon name="lucideArrowUpRight" class="rtl:-scale-x-100" /></z-trace-icon>
        </z-trace-line>
      </a>

      <z-trace-line zStatus="running">
        <z-trace-icon><ng-icon name="lucideTerminal" /></z-trace-icon>
        <z-trace-title>{{ i18n.t().running }}</z-trace-title>
      </z-trace-line>
    </z-trace>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
  viewProviders: [provideIcons({ lucideArrowUpRight, lucideSearch, lucideTerminal })],
  host: { class: 'contents' },
})
export class ZardDemoTraceRtlComponent {
  protected readonly i18n = injectRtlTranslation(translations);
}

Accessibility

z-trace adds no roles of its own. Each line gets its semantics from the element that wraps it.
  • A z-trace-line on its own is a span-like box. It is read as text and is not a tab stop.
  • Wrap it in a z-trace-collapsible-trigger and it becomes a button with aria-expanded. Wrap it in a link, or in the trigger for a dialog or sheet, and it takes the keyboard and focus behavior of that element.
  • z-trace-icon is hidden from assistive tech, so z-trace-title is the accessible name. Write it as a sentence that says what happened, like "Edited trace.component.ts", not just "trace.component.ts".
  • When a link opens a new tab, add "(opens in a new tab)" to the title with sr-only.
  • Status is shown with color and motion, so put it in the title too. Write "Running pnpm build" while it runs and "Failed to run pnpm build" when it errors.
  • The shimmer on a running title stops when the reader prefers reduced motion. The title still says what is happening.
  • z-trace-collapsible-content mutes its text. If you put a block with a muted background inside it, give the block text-foreground so it keeps its contrast.

API Reference

z-trace, [z-trace]

A list of rows. It also styles any trigger or link that directly wraps a z-trace-line.

Prop
[class]

Custom CSS classes

Type
ClassValue
Default
''

z-trace-line, [z-trace-line]

One row. Renders as a span-like box, so it is not a button or a tab stop; wrap it in a trigger or a link to make it do something.

Prop
[zStatus]

Work that is running (shimmering title), failed (destructive) or not started yet (dimmed)

Type
running | error | pending
Default
—
[class]

Custom CSS classes

Type
ClassValue
Default
''

z-trace-icon, [z-trace-icon]

Decorative icon slot, hidden from assistive tech.

Prop
[class]

Custom CSS classes

Type
ClassValue
Default
''

z-trace-title, [z-trace-title]

One-line sentence that truncates and shimmers while running. It is the accessible name.

Prop
[class]

Custom CSS classes

Type
ClassValue
Default
''

z-trace-description, [z-trace-description]

Secondary text such as a count, a duration or diff stats. Does not truncate.

Prop
[class]

Custom CSS classes

Type
ClassValue
Default
''

z-trace-collapsible, [z-trace-collapsible]

An expandable row, built on z-collapsible.

Prop
[zOpen]

Open state; supports [(zOpen)]

Type
boolean
Default
false
[class]

Custom CSS classes

Type
ClassValue
Default
''
Event
(zOpenChange)

Emitted with the new open state

Type
EventEmitter<boolean>
Default
—

z-trace-collapsible-trigger, [z-trace-collapsible-trigger]

Wraps its content in a button that toggles the row, with aria-expanded, and adds the chevron. class styles the button.

Prop
[class]

Custom CSS classes

Type
ClassValue
Default
''

z-trace-collapsible-content, [z-trace-collapsible-content]

The detail shown when the row is open; its text is muted.

Prop
[zKeepMounted]

Keep the content in the DOM while the row is closed instead of removing it after the collapse

Type
boolean
Default
false
[class]

Custom CSS classes

Type
ClassValue
Default
''
github iconwhatsapp icondiscord iconX icon

Made with ❤ in Brazil. Open source and available on GitHub .