diff --git a/libs/react/README.md b/libs/react/README.md index c0c383898..0a43a2173 100644 --- a/libs/react/README.md +++ b/libs/react/README.md @@ -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. diff --git a/libs/react/src/chat/generative-ui.tsx b/libs/react/src/chat/generative-ui.tsx index 406484e0d..006707ed2 100644 --- a/libs/react/src/chat/generative-ui.tsx +++ b/libs/react/src/chat/generative-ui.tsx @@ -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 @@ -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; } @@ -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 ( +
+ {labels.summary ?? 'Details'} +

+ {kind === 'spec' + ? labels.spec ?? 'Layout source' + : labels.a2ui ?? 'Response source'} +

+
{content}
+
+ ); +} + /** Content from the agent must not take the transcript down: a surface that throws gives way to `fallback`. */ class SurfaceBoundary extends Component< { @@ -275,22 +317,25 @@ function SpecSurface({ loading: streaming, }; return ( -
- {store === undefined ? ( - - ) : ( - - )} -
+ <> +
+ {store === undefined ? ( + + ) : ( + + )} +
+ + ); } @@ -359,6 +404,7 @@ export function GenerativeUiContent({ }} /> + ); } diff --git a/libs/react/src/chat/index.ts b/libs/react/src/chat/index.ts index fe4e2ef09..e25ec3928 100644 --- a/libs/react/src/chat/index.ts +++ b/libs/react/src/chat/index.ts @@ -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'; diff --git a/libs/react/src/chat/message-list-source-details.spec.tsx b/libs/react/src/chat/message-list-source-details.spec.tsx new file mode 100644 index 000000000..74b8f9dcc --- /dev/null +++ b/libs/react/src/chat/message-list-source-details.spec.tsx @@ -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 = { + Card: (view) =>
{String(view.props['title'])}
, +}; +const renderA2ui: NonNullable = () => ( +
surface
+); + +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('details.tp-chat-generative-ui__source')]; + +describe('MessageList generativeUi sourceDetails', () => { + it('adds no disclosure unless sourceDetails is set', () => { + const view = render( + + ); + expect(details(view.container)).toHaveLength(0); + view.rerender( + + ); + expect(details(view.container)).toHaveLength(0); + }); + + it('shows a closed disclosure with the source under each surface', () => { + const view = render( + + ); + 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( + + ); + 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( + + ); + 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( + + ); + const [open] = details(view.container); + open.open = true; + view.rerender(); + expect(details(view.container)[0]).toBe(open); + expect(open.open).toBe(true); + expect(open.querySelector('pre')?.textContent).toBe(SPEC); + }); +}); diff --git a/libs/react/src/chat/styles.css b/libs/react/src/chat/styles.css index da5ae7e01..0f8a42496 100644 --- a/libs/react/src/chat/styles.css +++ b/libs/react/src/chat/styles.css @@ -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; diff --git a/scripts/react-parity/dispositions.json b/scripts/react-parity/dispositions.json index 5d4d5b6da..240225b64 100644 --- a/scripts/react-parity/dispositions.json +++ b/scripts/react-parity/dispositions.json @@ -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"],