Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions libs/react/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -751,6 +751,11 @@ comes from your function: pass the content to `A2uiMessageSurfaces` from
and render `A2uiSurface` yourself, returning `skeleton` until a surface is
ready.

`sourceDetails: true` adds a closed "Details" disclosure under each surface
that shows the message content it was built from, headed "Layout source" for a
spec and "Response source" for A2UI. Pass `{ summary, spec, a2ui }` instead of
`true` to replace that text. A placeholder and a message left as text get none.

A message shown as a surface gets no built-in message actions. A custom
`renderMessage` keeps full ownership of its rows.

Expand Down
78 changes: 62 additions & 16 deletions libs/react/src/chat/generative-ui.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,16 @@ export interface MessageRenderEvent {
readonly event: RenderEvent;
}

/** Text of the source disclosure under a surface; see `MessageGenerativeUi.sourceDetails`. */
export interface MessageSourceLabels {
/** The disclosure's toggle. Defaults to "Details". */
readonly summary?: string;
/** Heading over a spec's source. Defaults to "Layout source". */
readonly spec?: string;
/** Heading over A2UI source. Defaults to "Response source". */
readonly a2ui?: string;
}

/**
* Turns on generated UI inside the transcript. Each part is separate: an
* assistant message is rendered as a surface only for the kinds configured
Expand Down Expand Up @@ -85,6 +95,12 @@ export interface MessageGenerativeUi {
* with `A2uiSurface`; return `content.skeleton` until one is ready.
*/
readonly renderA2ui?: (content: MessageA2uiContent) => ReactNode;
/**
* Adds a closed "Details" disclosure under each surface that shows the
* message content the surface was built from. Pass labels to replace its
* text. Off unless set.
*/
readonly sourceDetails?: boolean | MessageSourceLabels;
/** Placeholder text while a surface is being built. Defaults to "Building UI…". */
readonly skeletonLabel?: string;
}
Expand Down Expand Up @@ -190,6 +206,32 @@ function renderable(
};
}

/** The message content a surface was built from, closed until the reader opens it. */
function SourceDetails({
kind,
content,
options,
}: {
readonly kind: 'spec' | 'a2ui';
readonly content: string;
readonly options: MessageGenerativeUi;
}) {
const { sourceDetails } = options;
if (sourceDetails === undefined || sourceDetails === false) return null;
const labels = sourceDetails === true ? {} : sourceDetails;
return (
<details className="tp-chat-generative-ui__source" data-kind={kind}>
<summary>{labels.summary ?? 'Details'}</summary>
<p>
{kind === 'spec'
? labels.spec ?? 'Layout source'
: labels.a2ui ?? 'Response source'}
</p>
<pre>{content}</pre>
</details>
);
}

/** Content from the agent must not take the transcript down: a surface that throws gives way to `fallback`. */
class SurfaceBoundary extends Component<
{
Expand Down Expand Up @@ -275,22 +317,25 @@ function SpecSurface({
loading: streaming,
};
return (
<div
className="tp-chat-generative-ui"
data-kind="spec"
data-streaming={String(streaming)}
>
{store === undefined ? (
<RenderSpec {...shared} state={tree.state} />
) : (
<RenderSpec
{...shared}
store={store}
handlers={handlers}
onEvent={onRenderEvent === undefined ? undefined : onEvent}
/>
)}
</div>
<>
<div
className="tp-chat-generative-ui"
data-kind="spec"
data-streaming={String(streaming)}
>
{store === undefined ? (
<RenderSpec {...shared} state={tree.state} />
) : (
<RenderSpec
{...shared}
store={store}
handlers={handlers}
onEvent={onRenderEvent === undefined ? undefined : onEvent}
/>
)}
</div>
<SourceDetails kind="spec" content={content} options={options} />
</>
);
}

Expand Down Expand Up @@ -359,6 +404,7 @@ export function GenerativeUiContent({
}}
/>
</div>
<SourceDetails kind="a2ui" content={content} options={options} />
</SurfaceBoundary>
);
}
1 change: 1 addition & 0 deletions libs/react/src/chat/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -111,6 +111,7 @@ export type {
MessageA2uiContent,
MessageGenerativeUi,
MessageRenderEvent,
MessageSourceLabels,
} from './generative-ui.js';
export { Reasoning, type ReasoningProps } from './reasoning.js';
export { Trace, type TraceProps, type TraceState } from './trace.js';
Expand Down
137 changes: 137 additions & 0 deletions libs/react/src/chat/message-list-source-details.spec.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,137 @@
import { cleanup, render } from '@testing-library/react';
import { afterEach, describe, expect, it } from 'vitest';
import {
completeDelivery,
streamingDelivery,
type AgentSnapshot,
type Message,
} from '@threadplane/core';
import { createMessageContent } from '@threadplane/content/messages';
import { MessageList, type MessageGenerativeUi } from './index';

afterEach(cleanup);

const SPEC = JSON.stringify({
root: 'card',
elements: { card: { type: 'Card', props: { title: 'Lyon trip' } } },
});
const A2UI =
'---a2ui_JSON---\n{"version":"v0.9","createSurface":{"surfaceId":"trip"}}\n';
const registry: NonNullable<MessageGenerativeUi['registry']> = {
Card: (view) => <section>{String(view.props['title'])}</section>,
};
const renderA2ui: NonNullable<MessageGenerativeUi['renderA2ui']> = () => (
<section>surface</section>
);

const assistant = (content: string, id = 'a', streaming = false): Message => ({
id,
role: 'assistant',
content,
delivery: streaming ? streamingDelivery('g') : completeDelivery('g', 'success'),
});
const snapshot = (messages: readonly Message[]): AgentSnapshot => ({
status: 'idle',
messages,
toolCalls: [],
});
const rows = (...messages: Message[]) =>
createMessageContent().project(snapshot(messages));
const details = (container: HTMLElement) =>
[...container.querySelectorAll<HTMLDetailsElement>('details.tp-chat-generative-ui__source')];

describe('MessageList generativeUi sourceDetails', () => {
it('adds no disclosure unless sourceDetails is set', () => {
const view = render(
<MessageList
rows={rows(assistant(SPEC), assistant(A2UI, 'b'))}
generativeUi={{ registry, renderA2ui }}
/>
);
expect(details(view.container)).toHaveLength(0);
view.rerender(
<MessageList
rows={rows(assistant(SPEC), assistant(A2UI, 'b'))}
generativeUi={{ registry, renderA2ui, sourceDetails: false }}
/>
);
expect(details(view.container)).toHaveLength(0);
});

it('shows a closed disclosure with the source under each surface', () => {
const view = render(
<MessageList
rows={rows(assistant(SPEC), assistant(A2UI, 'b'))}
generativeUi={{ registry, renderA2ui, sourceDetails: true }}
/>
);
const [spec, a2ui] = details(view.container);
expect(details(view.container)).toHaveLength(2);
expect(spec.open).toBe(false);
expect(spec.getAttribute('data-kind')).toBe('spec');
expect(spec.querySelector('summary')?.textContent).toBe('Details');
expect(spec.querySelector('p')?.textContent).toBe('Layout source');
expect(spec.querySelector('pre')?.textContent).toBe(SPEC);
// It follows its surface inside the same message body.
const surface = spec.previousElementSibling as HTMLElement;
expect(surface.className).toBe('tp-chat-generative-ui');
expect(surface.textContent).toBe('Lyon trip');
expect(spec.closest('.tp-chat-message__body')).not.toBeNull();

expect(a2ui.getAttribute('data-kind')).toBe('a2ui');
expect(a2ui.querySelector('p')?.textContent).toBe('Response source');
expect(a2ui.querySelector('pre')?.textContent).toBe(A2UI);
expect((a2ui.previousElementSibling as HTMLElement).textContent).toBe('surface');
});

it('takes its text from labels', () => {
const view = render(
<MessageList
rows={rows(assistant(SPEC), assistant(A2UI, 'b'))}
generativeUi={{
registry,
renderA2ui,
sourceDetails: { summary: 'Source', spec: 'Layout', a2ui: 'Envelopes' },
}}
/>
);
const [spec, a2ui] = details(view.container);
expect(spec.querySelector('summary')?.textContent).toBe('Source');
expect(spec.querySelector('p')?.textContent).toBe('Layout');
expect(a2ui.querySelector('summary')?.textContent).toBe('Source');
expect(a2ui.querySelector('p')?.textContent).toBe('Envelopes');
});

it('adds none to text, to content that is not a spec, or to a placeholder', () => {
const options: MessageGenerativeUi = { registry, sourceDetails: true };
const view = render(
<MessageList
rows={rows(
assistant('Plain'),
assistant('{"answer": 42}', 'b'),
assistant(A2UI, 'c'),
assistant('{"root"', 'd', true)
)}
generativeUi={options}
/>
);
expect(view.getByRole('status')).not.toBeNull();
expect(details(view.container)).toHaveLength(0);
});

it('keeps the disclosure open while its message streams', () => {
const content = createMessageContent();
const at = (length: number, streaming = true) =>
content.project(snapshot([assistant(SPEC.slice(0, length), 'a', streaming)]));
const options: MessageGenerativeUi = { registry, sourceDetails: true };
const view = render(
<MessageList rows={at(SPEC.length - 1)} generativeUi={options} />
);
const [open] = details(view.container);
open.open = true;
view.rerender(<MessageList rows={at(SPEC.length, false)} generativeUi={options} />);
expect(details(view.container)[0]).toBe(open);
expect(open.open).toBe(true);
expect(open.querySelector('pre')?.textContent).toBe(SPEC);
});
});
15 changes: 15 additions & 0 deletions libs/react/src/chat/styles.css
Original file line number Diff line number Diff line change
Expand Up @@ -2873,6 +2873,21 @@
.tp-chat-message__body:has(> .tp-chat-generative-ui) > .tp-chat-message__caret {
display: none;
}
/* The source a surface was built from, for a reader who wants to check it. */
.tp-chat-generative-ui__source {
margin-block: 12px;
color: var(--tp-chat-muted, var(--ds-text-secondary, GrayText));
font-size: 12px;
}
.tp-chat-generative-ui__source > summary {
cursor: pointer;
}
.tp-chat-generative-ui__source > pre {
max-block-size: 280px;
overflow: auto;
white-space: pre-wrap;
overflow-wrap: anywhere;
}

.tp-genui-skeleton {
display: block;
Expand Down
8 changes: 8 additions & 0 deletions scripts/react-parity/dispositions.json
Original file line number Diff line number Diff line change
Expand Up @@ -18653,6 +18653,14 @@
"target": "libs/react/src/chat/generative-ui.tsx",
"reason": "What onRenderEvent receives: the ID of the message whose spec tree produced the event, and the RenderSpec event (an action that ran, a state write, or a reported result)."
},
{
"id": "export:libs/react/src/chat/index.ts#MessageSourceLabels",
"taskIds": ["T19", "T27"],
"treatment": "react",
"status": "in-progress",
"target": "libs/react/src/chat/generative-ui.tsx",
"reason": "Replacement text for the opt-in source disclosure under a surface: its toggle and the headings over a spec's and an A2UI message's source."
},
{
"id": "source:libs/react/src/chat/typing-indicator.tsx",
"taskIds": ["T23"],
Expand Down
Loading