Skip to content

feat(react): show a placeholder while generated UI props are still undefined - #1648

Open
blove wants to merge 1 commit into
mainfrom
blove/react-render-readiness-fallback
Open

blove wants to merge 1 commit into
mainfrom
blove/react-render-readiness-fallback

Conversation

@blove

@blove blove commented Nov 18, 2026

Copy link
Copy Markdown
Contributor

Summary

Angular gives every registry entry a default readiness fallback. defineAngularRegistry pairs each component with DefaultFallbackComponent. render-element.component.ts (notReady, mountClass, and the per-index repeatMountedReal latch) mounts that fallback while any resolved prop is undefined or an optional schema fails, then latches once the real component mounts. internals/element-readiness.ts checks every resolved prop, not just bound ones; in practice only unresolved expressions produce undefined. A2UI catalogs get the same behavior through toRenderRegistry, so components that arrive before updateDataModel shimmer.

React only gated explicit { kind: 'readiness' } entries. Plain components and all of a2uiBasicCatalog() mounted at once with undefined props, so labels and fields rendered empty.

What changed:

  • RenderSpec default (Angular parity): a registered component now waits behind the new RenderPendingFallback while any resolved prop is undefined. The placeholder uses the GenerativeUiSkeleton markup and classes. Once ready, the component mounts and stays mounted for that element. Each repeat row latches on its own. The unknown-type fallback is not gated. React registry entries cannot carry a schema, so only the undefined check applies.
  • Readiness entries keep their own isReady. An entry with no fallback now shows the tree placeholder, matching Angular's entry.fallback ?? DefaultFallbackComponent.
  • Customization and opt-out: the new pendingFallback prop on RenderSpec replaces the placeholder. pendingFallback={null} restores the old immediate mounting. To opt out a single entry, register it as a readiness entry with isReady: () => true. A2uiSurface, A2uiMessageSurfaces and the chat generativeUi options forward pendingFallback.
  • A2UI: the basic catalog's inputs (TextField, CheckBox, ChoicePicker, DateTimeInput, Slider) wait on every prop except their own value. This deliberately differs from Angular. Angular's literal rule leaves an input bound to an unseeded path on the fallback forever, so the person can never type into it. Existing React specs type into unseeded fields. With pendingFallback={null}, A2uiSurface uses an ungated catalog. a2ui/styles.css styles the placeholder with A2UI tokens.
  • Lifecycle: unchanged. An element reports mounted once, when the placeholder first renders. Angular reports it the same way, from ngOnInit before readiness. DevTools marks report fallback and then mounted through the existing gate.
  • Render count: a readiness gate that is ready on its first render now starts admitted. Previously the real view rendered twice: once on the initial render, then again from the layout effect.

Existing specs that relied on immediate mounting with undefined props now opt out with pendingFallback={null} or assert the placeholder. This covers the readiness direct-view specs, seeded-state, computed unknown function, the A2UI DateTimeInput bound max, and the cockpit dashboard "Waiting" specs.

Verification

  • NX_DAEMON=false npx nx run-many -t test lint -p react: 102 files, 1539 tests pass. Lint has 0 errors; the existing warnings are unchanged.
  • npx nx run react:type-tests: passes.
  • node --test scripts/react-parity/verify-packages.spec.mjs: 103 pass, 0 fail.
  • node scripts/react-parity/inventory.mjs --check --drift warn: valid. The only output is the informational baseline-drift notice.
  • npx vitest run in apps/website: the docs content rules pass. Three files fail in this worktree only, for environmental reasons: posthog-node does not resolve through the symlinked node_modules, and API Extractor rejects a fixture outside the workspace. react-debug-preview.spec passes when rerun alone.
  • Unit tests pass for the 11 React example projects that use RenderSpec or A2UI: the cockpit render, generative-ui, json-render and a2ui projects, and native-conversation-react. In the parallel run, three failed under machine load; each passes when rerun alone. Two cockpit dashboard specs were updated to expect the placeholder.
  • e2e: all 6 cockpit render React projects pass. cockpit-ag-ui-a2ui-react (7), cockpit-ag-ui-json-render-react (30) and cockpit-chat-generative-ui-react pass. cockpit-chat-a2ui-react was not verified. Its fixture-test dependency asserts Node 22, and this machine runs Node 24. Run without that dependency, 7 tests pass and 1 fails because the backend never returns a response; the page is still waiting at "Waiting for the saved response…" and no surface rendered.

🤖 Generated with Claude Code

…defined

Angular gives every registry entry a default readiness fallback:
defineAngularRegistry pairs each component with DefaultFallbackComponent,
and render-element mounts that fallback while any resolved prop is
undefined (or a schema fails), latching once the real component mounts,
per element and per repeat row. A2UI catalogs get the same treatment, so
components that arrive before updateDataModel shimmer instead of
rendering empty labels.

React only gated explicit { kind: 'readiness' } entries, so plain
components and the whole a2uiBasicCatalog() mounted at once with
undefined props.

RenderSpec now applies Angular's rule by default: a registered component
waits behind RenderPendingFallback (GenerativeUiSkeleton markup) while
any resolved prop is undefined, then mounts and stays mounted for that
element. A readiness entry keeps its own predicate and shows the tree's
placeholder when it has no fallback, as Angular does with
fallback ?? DefaultFallbackComponent. The unknown-type `fallback` is not
gated. `pendingFallback` customizes the placeholder; `null` restores the
previous immediate mounting. A per-entry opt-out is a readiness entry
whose isReady always returns true.

A2UI: the basic catalog's inputs (TextField, CheckBox, ChoicePicker,
DateTimeInput, Slider) wait on every prop except their own `value`, so an
unseeded field the person fills in is not stuck on the placeholder, which
Angular's literal rule would do. A2uiSurface and A2uiMessageSurfaces take
`pendingFallback`; with null the surface uses an ungated catalog. Chat's
generativeUi options forward `pendingFallback` too.

A ready-on-first-render readiness gate now starts admitted, so the real
view renders once instead of twice. Element lifecycle events are
unchanged: an element reports `mounted` once when its placeholder first
renders, as Angular reports it from ngOnInit.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@blove
blove enabled auto-merge November 18, 2026 02:01

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant