A deterministic UI renderer for ui_frame messages defined by @airforms/ui-schema.
This package renders structured UI inside a chat interface. It does not call LLMs, manage conversations, or execute tools. It strictly:
- Accepts a validated
ui_frame - Renders components deterministically
- Collects structured values
- Emits
ui_submitevents
This package is one component in the overall AirForms product stack (Layer 2):
- UI Schema (
@airforms/ui-schema) - Renderer (this package)
- Orchestrator
The renderer transforms this:
{
"type": "ui_frame",
"version": "1.0",
"frameId": "insurance:lookup",
"title": "Find your policy",
"state": { "values": {} },
"components": [
{ "id": "policyNumber", "type": "text", "label": "Policy number", "required": true },
{ "id": "dob", "type": "date", "label": "Date of birth", "required": true }
],
"primaryAction": {
"label": "Look up",
"action": { "type": "ui_submit" }
}
}Into a live interactive UI component inside a chat message bubble.
No HTML generation. No dynamic scripts. No arbitrary layouts.
Deterministic rendering only.
npm install @airforms/renderer-reactPeer dependency:
npm install @airforms/ui-schemaimport { ChatUIRenderer } from "@airforms/renderer-react"
import type { UiFrame } from "@airforms/ui-schema"
function ChatMessage({ frame }: { frame: UiFrame }) {
return (
<ChatUIRenderer
frame={frame}
onSubmit={(submit) => {
console.log("ui_submit", submit)
}}
/>
)
}| Prop | Type | Required | Description |
|---|---|---|---|
frame |
UiFrame |
yes | Validated frame from orchestrator |
onSubmit |
(submit: UiSubmit) => void |
yes | Fired when primary action is triggered |
onBack |
(frameId: string) => void |
optional | For ui_back |
onReplace |
(frameId: string) => void |
optional | For ui_replace |
disabled |
boolean |
optional | Disable all inputs |
The renderer supports only protocol-approved primitives:
texttextareanumberdateselectslidermap_pinreview
Each component is rendered deterministically based on type.
No dynamic injection. No runtime component registration (v0).
- Required fields block submission.
sliderenforcesmin/max/step.selectonly allows listed values.numberrespects numeric bounds if defined.- Validation errors display inline.
- Internal component state mirrors
frame.state.values. - Submission emits:
{
"type": "ui_submit",
"frameId": "<frameId>",
"values": { ... }
}The renderer does not persist beyond the current render unless host chooses to.
Given the same ui_frame, the output UI must always render the same structure.
No layout heuristics. No interpretation beyond schema rules.
The map_pin component:
- Displays a visible map (OpenStreetMap tiles)
- Supports pan + zoom
- Supports click-to-select pin placement
- Supports geolocation-based initial centering when available
- Supports "Use map center" fallback selection
- Emits
{ lat: number, lng: number } - Rounds to 6 decimal places
- Includes OpenStreetMap attribution in the rendered map
- All inputs labeled via
label - Buttons keyboard-accessible
- Map supports keyboard fallback (center selection)
Renderer provides minimal neutral styles.
The host application may:
- Wrap renderer in chat bubble UI
- Override styles via className or theme prop (v1+)
Renderer must not enforce design system decisions.
Renderer must include:
- Component rendering tests
- Submission tests
- Validation blocking tests
- Snapshot tests for stable rendering
Tests must verify:
- Required fields prevent submission
- Invalid values are rejected
- Valid values emit correct
ui_submit
- Host receives
ui_frame - Host renders
<ChatUIRenderer /> - User fills form
- User clicks primary button
- Renderer emits
ui_submit - Host forwards to orchestrator
- Tool execution
- Conversation management
- Streaming tokens
- Dynamic component injection
- Custom layout engines
- Drag/drop
- File uploads
- Multi-step wizard engine
Those belong to future versions or higher layers.
Implement a deterministic React renderer for ui_frame as defined by @airforms/ui-schema.
-
All v0 component types render.
-
Validation blocks submission when required fields are missing.
-
onSubmitemits validui_submit. -
Tests cover:
- happy path
- missing required fields
- invalid slider bounds
- invalid select value
-
No runtime schema logic lives here — assume frames are validated upstream.
- Do not mutate the incoming
frame. - Internal state should initialize from
frame.state.values. - Renderer must be pure UI — no network calls.
- No HTML string rendering.
- No
dangerouslySetInnerHTML.
src/
components/
TextInput.tsx
TextArea.tsx
NumberInput.tsx
DateInput.tsx
SelectInput.tsx
SliderInput.tsx
MapPinInput.tsx
Review.tsx
ChatUIRenderer.tsx
validation.ts
index.ts
test/
renderer.test.tsx
Minimum implementation:
requiredslider.min/maxselectvalue must match optionsnumbernumeric enforcement
Do not overbuild validation in v0.
- No unnecessary re-renders.
- Use controlled inputs.
- Avoid deep clones of
frame.
- Never execute arbitrary code.
- Never interpret values as markup.
- Treat all strings as plain text.
This renderer is not a form builder.
It is a deterministic execution surface for conversational UI frames.
It must remain small, predictable, and boring.
Its power comes from strict adherence to the protocol contract.