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
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@ The native React APIs on this page are experimental, private source-build packag

The server sends a surface description and data-model updates. React retains the received surface, while form controls hold the traveler’s current edits. Search, Select, and Modify send intentional actions; typing does not start another agent run. The example admits a fixed flight-form profile rather than every possible A2UI component.

When components arrive before the data model, `A2uiSurface` shows a placeholder for each component whose data-bound props have no value yet, then mounts it once they do. An input's own `value` may stay unset, so an empty field the traveler fills in still appears. Pass `pendingFallback` to change the placeholder, or `null` to mount every component at once.

The [React conversation walkthrough](/docs/react/langgraph/concepts/conversation-turns) connects this capability to requests, tools, UI state, and saved history.

## Start a conversation
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ These protections do not validate your application schema. Admit untrusted view

Use stable element keys and registry component identities across updates. Container views must place the provided `children` where they belong. [Repeat loops](/docs/react/render/guides/repeat-loops) need meaningful unique identities when items can reorder.

A readiness registry entry can defer its component until its synchronous predicate accepts the props. Follow the [registry guide](/docs/react/render/guides/registry) for that mounted-view boundary. Readiness is presentation admission, not a network completion signal.
A registered component waits behind `RenderPendingFallback` while any resolved prop is undefined, and a readiness registry entry can defer its component until its synchronous predicate accepts the props. Follow the [registry guide](/docs/react/render/guides/registry) for that mounted-view boundary. Readiness is presentation admission, not a network completion signal.

## Retire owned work

Expand Down
21 changes: 21 additions & 0 deletions apps/website/content/docs/react/render/guides/registry.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,27 @@ export const tripViews: ReactRenderRegistry = {
};
~~~

## Wait for bound props

As in the Angular renderer, a registered component does not mount while any of its resolved props is `undefined`, such as a `$state` binding whose path has not arrived. RenderSpec shows `RenderPendingFallback` in its place, a labelled shimmer card that uses the generative UI skeleton classes. Once every prop has a value, the component mounts and stays mounted for that element, even if a value later goes missing. Each repeat row waits on its own props.

Pass a component as `pendingFallback` to show something else, or pass `null` to mount every component at once. To let one component mount with undefined props, register it as a readiness entry whose predicate always accepts:

~~~tsx
import type { ReactRenderRegistry } from '@threadplane/react/render';

export const views: ReactRenderRegistry = {
Heading: ({ props }) => <h2>{String(props['text'] ?? '')}</h2>,
Note: {
kind: 'readiness',
component: ({ props }) => <p>{String(props['text'] ?? '')}</p>,
isReady: () => true,
},
};
~~~

A readiness entry decides with its own predicate. Without its own `fallback`, it shows the tree's `pendingFallback`. The element reports `mounted` to `onEvent` once, when the placeholder first renders, which matches the Angular renderer.

The [React conversation walkthrough](/docs/react/langgraph/concepts/conversation-turns) connects this capability to requests, tools, UI state, and saved history.

## Try each registry mode
Expand Down
3 changes: 2 additions & 1 deletion cockpit/ag-ui/json-render/react/src/dashboard-views.spec.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -255,7 +255,8 @@ it('updates the same retained layout from latest shared state without mutating t
});
it('distinguishes unavailable data from valid empty lists and zero values', () => {
const view = render(<RenderSpec spec={spec} registry={dashboardRegistry} />);
expect(screen.getAllByText('Waiting for dashboard data…')).toHaveLength(4);
// RenderSpec holds each view behind its placeholder until the bound data arrives.
expect(screen.getAllByText('Building UI…')).toHaveLength(4);
view.rerender(
<RenderSpec
spec={spec}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -261,7 +261,8 @@ it('updates the same retained layout from latest shared state without mutating t
});
it('distinguishes unavailable data from valid empty lists and zero values', () => {
const view = render(<RenderSpec spec={spec} registry={dashboardRegistry} />);
expect(screen.getAllByText('Waiting for dashboard data…')).toHaveLength(4);
// RenderSpec holds each view behind its placeholder until the bound data arrives.
expect(screen.getAllByText('Building UI…')).toHaveLength(4);
view.rerender(
<RenderSpec
spec={spec}
Expand Down
2 changes: 1 addition & 1 deletion fixtures/react-parity/react-readiness/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,4 +4,4 @@ Private, bounded development StrictMode fixture for the actual application-owned

Run `node scripts/react-parity/verify-react-readiness.mjs --retain NEW_DIRECTORY` after fresh core, content, and React builds. The runner installs exactly those three local artifacts using the existing `react-render` profile and current root lock. Strict installed type checking uses `skipLibCheck:false`. Vite builds without workspace configuration or environment files and records all module inputs separately from modules with executed bytes. Installed parser dependencies are legitimate; parser execution is excluded from this proof.

The browser checks literal state and command counts, actual DOM identity and edited local inputs, pending children and null fallback, committed admission followed by missing data, contract replacement, remounts, direct memo/forwardRef undefined values, stable repeated keys, and a real suspended candidate cancelled before admission commits. Each browser step and screenshot is retained with installed/type/emitted/source hashes, the root lock fingerprint, and owned process/profile/socket cleanup receipts. This fixture does not claim full renderer parity, SSR, schema validation, forms, or backend integration.
The browser checks literal state and command counts, actual DOM identity and edited local inputs, pending children and an absent fallback that shows the default placeholder, committed admission followed by missing data, contract replacement, remounts, direct memo/forwardRef undefined values under `pendingFallback={null}`, the default placeholder for an unresolved binding without that opt-out, stable repeated keys, and a real suspended candidate cancelled before admission commits. Each browser step and screenshot is retained with installed/type/emitted/source hashes, the root lock fingerprint, and owned process/profile/socket cleanup receipts. This fixture does not claim full renderer parity, SSR, schema validation, forms, or backend integration.
36 changes: 29 additions & 7 deletions fixtures/react-parity/react-readiness/react.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -140,6 +140,17 @@ const directRegistry: ReactRenderRegistry = {
Memo: DirectMemo,
Forward: DirectForward,
};
// The same unresolved binding without the opt-out: the default placeholder stands in.
function DefaultWaitReal() {
return <p data-testid="default-wait-real">Mounted too early</p>;
}
const defaultWaitSpec: RenderSpecData = {
root: 'wait',
elements: {
wait: { type: 'Wait', props: { absent: { $state: '/missing' } } },
},
};
const defaultWaitRegistry: ReactRenderRegistry = { Wait: DefaultWaitReal };
const rowSpec: RenderSpecData = {
root: 'rows',
elements: {
Expand Down Expand Up @@ -184,18 +195,29 @@ function App() {
return (
<>
<p data-testid="descriptor">{descriptor}</p>
<RenderSpec
key={epoch}
spec={spec}
registry={registry}
state={snapshot}
loading={loading}
/>
<div data-testid="main-tree">
<RenderSpec
key={epoch}
spec={spec}
registry={registry}
state={snapshot}
loading={loading}
/>
</div>
{/* Direct exotic components receive undefined props only with the documented opt-out. */}
<RenderSpec
spec={directSpec}
registry={directRegistry}
state={snapshot}
pendingFallback={null}
/>
<div data-testid="default-wait">
<RenderSpec
spec={defaultWaitSpec}
registry={defaultWaitRegistry}
state={snapshot}
/>
</div>
<RenderSpec spec={rowSpec} registry={rowRegistry} state={snapshot} />
</>
);
Expand Down
2 changes: 1 addition & 1 deletion libs/react/src/a2ui/catalog/choices.spec.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -313,7 +313,7 @@ describe('A2UI DateTimeInput', () => {
});

it('maps min and max to the native bounds in the same format', () => {
const { element } = input({ min: '2026-03-01T00:00:00', max: { path: '/latest' } }, '2026-03-04');
const { element } = input({ min: '2026-03-01T00:00:00' }, '2026-03-04');
expect([element.min, element.max]).toEqual(['2026-03-01', '']);
cleanup();
const surfaces = store(
Expand Down
40 changes: 37 additions & 3 deletions libs/react/src/a2ui/catalog/index.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,7 @@
import type { ReactRenderRegistry } from '../../render/index.js';
import type {
ReactRenderRegistry,
RenderReadinessEntry,
} from '../../render/index.js';
import { A2uiAudioPlayer } from './audio-player.js';
import { A2uiButton } from './button.js';
import { A2uiCard } from './card.js';
Expand All @@ -18,7 +21,22 @@ import { A2uiText } from './text.js';
import { A2uiTextField } from './text-field.js';
import { A2uiVideo } from './video.js';

const CATALOG: ReactRenderRegistry = Object.freeze({
/**
* An input waits, like every other component, while a prop such as its label
* has not arrived; its `value` alone may stay undefined, because the person
* fills an unseeded field.
*/
const ready: RenderReadinessEntry['isReady'] = (props) =>
Object.entries(props).every(
([key, value]) => key === 'value' || value !== undefined
);
const input = (
component: RenderReadinessEntry['component']
): RenderReadinessEntry =>
Object.freeze({ kind: 'readiness', component, isReady: ready });

/** Every basic component, mounted at once, for a surface whose `pendingFallback` is null. */
const EAGER: ReactRenderRegistry = Object.freeze({
AudioPlayer: A2uiAudioPlayer,
Button: A2uiButton,
Card: A2uiCard,
Expand All @@ -39,12 +57,28 @@ const CATALOG: ReactRenderRegistry = Object.freeze({
Video: A2uiVideo,
});

const CATALOG: ReactRenderRegistry = Object.freeze({
...EAGER,
CheckBox: input(A2uiCheckBox),
ChoicePicker: input(A2uiChoicePicker),
DateTimeInput: input(A2uiDateTimeInput),
Slider: input(A2uiSlider),
TextField: input(A2uiTextField),
});

/**
* The A2UI basic catalog: Text, Image, Icon, Video, AudioPlayer, Row, Column,
* List, Card, Divider, Tabs, Modal, TextField, CheckBox, ChoicePicker,
* DateTimeInput, Slider and Button. Inputs write to the surface's store when `A2uiSurface` is given one;
* a Button hands its event action to the surface's `onAction`.
* a Button hands its event action to the surface's `onAction`. A component
* shows a placeholder while a data-bound prop has no value yet, except an
* input's own `value`.
*/
export function a2uiBasicCatalog(): ReactRenderRegistry {
return CATALOG;
}

/** The basic catalog without any wait, so every component mounts at once. */
export function a2uiEagerCatalog(): ReactRenderRegistry {
return EAGER;
}
6 changes: 5 additions & 1 deletion libs/react/src/a2ui/message-surfaces.spec.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -158,8 +158,12 @@ describe('A2uiMessageSurfaces', () => {
expect(view.queryByRole('status')).not.toBeNull();
expect(surfaceIds(view.container)).toEqual([]);
view.rerender(<A2uiMessageSurfaces content={content(CREATE + COMPONENTS)} />);
expect(view.queryByRole('status')).toBeNull();
expect(surfaceIds(view.container)).toEqual(['trip']);
// The surface is live; only its Text bound to /title waits for the data model.
expect(view.getByRole('status').closest('.a2ui-surface')).not.toBeNull();
view.rerender(<A2uiMessageSurfaces content={content(CREATE + COMPONENTS + title('Lyon'))} />);
expect(view.queryByRole('status')).toBeNull();
expect(view.container.textContent).toContain('Lyon');
});

it('renders nothing for a finished message with no surface', () => {
Expand Down
7 changes: 6 additions & 1 deletion libs/react/src/a2ui/message-surfaces.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,12 @@ export interface A2uiMessageContent {
export interface A2uiMessageSurfacesProps
extends Pick<
A2uiSurfaceProps,
'onAction' | 'onValidationError' | 'functions' | 'catalog' | 'className'
| 'onAction'
| 'onValidationError'
| 'functions'
| 'catalog'
| 'pendingFallback'
| 'className'
> {
readonly content: A2uiMessageContent;
}
Expand Down
80 changes: 80 additions & 0 deletions libs/react/src/a2ui/readiness.spec.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
import { cleanup, render } from '@testing-library/react';
import { afterEach, describe, expect, it } from 'vitest';
import type { A2uiSurfaceSnapshot } from '@threadplane/content/a2ui';
import type { RenderViewProps } from '../render/index';
import { A2uiSurface } from './index';

afterEach(cleanup);

type Component = A2uiSurfaceSnapshot['components'][number];
const surface = (
components: readonly Component[],
dataModel: A2uiSurfaceSnapshot['dataModel'] = {}
): A2uiSurfaceSnapshot => ({
surfaceId: 's1',
catalogId: 'basic',
components,
dataModel,
});
const components: readonly Component[] = [
{ id: 'root', component: 'Column', children: ['title', 'guest'] },
{ id: 'title', component: 'Text', text: { path: '/title' } },
{
id: 'guest',
component: 'TextField',
label: { path: '/guestLabel' },
value: { path: '/guest' },
},
];

describe('A2uiSurface readiness', () => {
it('shows placeholders for components that arrive before the data model, then mounts them', () => {
const view = render(<A2uiSurface surface={surface(components)} />);
const pending = view.getAllByRole('status');
expect(pending).toHaveLength(2);
expect(pending.every((el) => el.closest('.a2ui-surface'))).toBe(true);
expect(view.queryByRole('textbox')).toBeNull();

// The input value is never seeded: the person fills it in.
view.rerender(
<A2uiSurface
surface={surface(components, { title: 'Lyon trip', guestLabel: 'Guest' })}
/>
);
expect(view.queryByRole('status')).toBeNull();
expect(view.container.textContent).toContain('Lyon trip');
expect((view.getByLabelText('Guest') as HTMLInputElement).value).toBe('');
});

it('keeps a mounted component when its data later goes missing', () => {
const view = render(
<A2uiSurface
surface={surface(components, { title: 'Lyon trip', guestLabel: 'Guest' })}
/>
);
const field = view.getByRole('textbox');
view.rerender(<A2uiSurface surface={surface(components)} />);
expect(view.queryByRole('status')).toBeNull();
expect(view.getByRole('textbox')).toBe(field);
});

it('takes a custom pendingFallback, or null to mount at once', () => {
const Pending = ({ elementKey }: RenderViewProps) => (
<p data-pending={elementKey}>waiting</p>
);
const view = render(
<A2uiSurface surface={surface(components)} pendingFallback={Pending} />
);
expect(
[...view.container.querySelectorAll('[data-pending]')].map((el) =>
el.getAttribute('data-pending')
)
).toEqual(['title', 'guest']);
cleanup();
const eager = render(
<A2uiSurface surface={surface(components)} pendingFallback={null} />
);
expect(eager.queryByRole('status')).toBeNull();
expect(eager.getByRole('textbox')).toBeTruthy();
});
});
63 changes: 63 additions & 0 deletions libs/react/src/a2ui/styles.css
Original file line number Diff line number Diff line change
Expand Up @@ -541,6 +541,63 @@
.a2ui-unsupported {
display: contents;
}
/* RenderPendingFallback: a component whose data-bound props have not arrived. */
.a2ui-surface .tp-render-pending {
display: block;
box-sizing: border-box;
inline-size: 100%;
min-inline-size: 0;
padding: var(--a2ui-spacing-3);
border: 1px solid var(--a2ui-outline);
border-radius: var(--a2ui-shape-medium);
background: var(--a2ui-surface-variant);
color: var(--a2ui-on-surface-variant);
font-size: var(--a2ui-typography-label-size);
}
.a2ui-surface .tp-render-pending .tp-genui-skeleton__label {
display: block;
margin-block-end: var(--a2ui-spacing-2);
}
.a2ui-surface .tp-render-pending .tp-genui-skeleton__rows {
display: flex;
flex-direction: column;
gap: var(--a2ui-spacing-2);
}
.a2ui-surface .tp-render-pending .tp-genui-skeleton__row {
display: block;
block-size: 0.625rem;
border-radius: var(--a2ui-shape-extra-small);
background: linear-gradient(
90deg,
color-mix(in srgb, currentColor 22%, transparent) 0%,
color-mix(in srgb, currentColor 10%, transparent) 50%,
color-mix(in srgb, currentColor 22%, transparent) 100%
);
background-size: 200% 100%;
animation: a2ui-pending-shimmer 1.4s ease-in-out infinite;
}
.a2ui-surface .tp-render-pending .tp-genui-skeleton__row:nth-child(1) {
inline-size: 70%;
}
.a2ui-surface .tp-render-pending .tp-genui-skeleton__row:nth-child(2) {
inline-size: 90%;
}
.a2ui-surface .tp-render-pending .tp-genui-skeleton__row:nth-child(3) {
inline-size: 50%;
}
@keyframes a2ui-pending-shimmer {
0% {
background-position: 200% 0;
}
100% {
background-position: -200% 0;
}
}
@media (prefers-reduced-motion: reduce) {
.a2ui-surface .tp-render-pending .tp-genui-skeleton__row {
animation: none;
}
}
@media (forced-colors: active) {
.a2ui-card,
.a2ui-divider--horizontal {
Expand All @@ -555,6 +612,12 @@
.a2ui-modal {
border-color: CanvasText;
}
.a2ui-surface .tp-render-pending {
border-color: CanvasText;
}
.a2ui-surface .tp-render-pending .tp-genui-skeleton__row {
background: GrayText;
}
.a2ui-tf__input,
.a2ui-dti__input,
.a2ui-cp__filter {
Expand Down
Loading
Loading