The Open Standard for Generative UI
Add interactivity doc for openui-lang (#280)
Aditya-thesys848d9f852a21
diff --git a/benchmarks/README.md b/benchmarks/README.mdindex 39550d94d..61ee9bbb5 100644--- a/benchmarks/README.md+++ b/benchmarks/README.md@@ -92,11 +92,11 @@ benchmarks/`schema.json` and `system-prompt.txt` are generated by `library.toJSONSchema()` and `library.prompt()` in `@openuidev/react-ui`. If you add or change components, regenerate them:```ts-import { defaultLibrary } from "@openuidev/react-ui";+import { openuiLibrary } from "@openuidev/react-ui";import { writeFileSync } from "fs";-writeFileSync("schema.json", JSON.stringify(defaultLibrary.toJSONSchema(), null, 2));-writeFileSync("system-prompt.txt", defaultLibrary.prompt());+writeFileSync("schema.json", JSON.stringify(openuiLibrary.toJSONSchema(), null, 2));+writeFileSync("system-prompt.txt", openuiLibrary.prompt());```The parser (`createParser`) reads component definitions from the `$defs` section of this file to map positional arguments to named props.diff --git a/docs/app/(home)/components/FeaturesSection.tsx b/docs/app/(home)/components/FeaturesSection.tsxindex ef33407a4..d7ed2ae90 100644--- a/docs/app/(home)/components/FeaturesSection.tsx+++ b/docs/app/(home)/components/FeaturesSection.tsx@@ -19,12 +19,12 @@ interface Feature {const FEATURES: Feature[] = [{title: "Performance Optimized",- description: "2.1x faster rendering than json-render",+ description: "Up to 3.0x faster rendering than json-render",iconPath: svgPaths.p7658f00,},{title: "Token efficient",- description: "52% lesser tokens than json-render",+ description: "Up to 67.1% lesser tokens than json-render",iconPath: svgPaths.p2a8ddd80,},{diff --git a/docs/app/docs/openui-lang/page.tsx b/docs/app/docs/openui-lang/page.tsxindex a29e1e09b..83b82d5be 100644--- a/docs/app/docs/openui-lang/page.tsx+++ b/docs/app/docs/openui-lang/page.tsx@@ -94,14 +94,14 @@ export default function OpenUILangOverview() {>A2UI</Link>{" "}- that uses ~52% fewer tokens than equivalent JSON structures. Define your component library+ that uses up to 67.1% fewer tokens than equivalent JSON structures. Define your component librarywith Zod schemas and parse LLM responses into renderable components.</p><div className="flex flex-col gap-3 sm:flex-row"><Buttonhref="/docs/openui-lang/quickstart"- text="Build with Default Library"+ text="Build with OpenUI Library"variant="primary"/><Button@@ -127,7 +127,7 @@ export default function OpenUILangOverview() {<FeatureCardicon={<Zap />}title="Token Efficient"- description="Uses ~52% fewer tokens than equivalent JSON structures, significantly reducing inference cost and latency."+ description="Uses up to 67.1% fewer tokens than equivalent JSON structures, significantly reducing inference cost and latency."/><FeatureCardicon={<Shield />}diff --git a/docs/app/playground/components/CatalogPanel/CatalogPanel.tsx b/docs/app/playground/components/CatalogPanel/CatalogPanel.tsxindex 333837335..5ad8032fc 100644--- a/docs/app/playground/components/CatalogPanel/CatalogPanel.tsx+++ b/docs/app/playground/components/CatalogPanel/CatalogPanel.tsx@@ -66,9 +66,9 @@ export function CatalogPanel() {return (<aside className={`catalog-panel${isCollapsed ? " catalog-panel--collapsed" : ""}`}><div className="catalog-panel-header">- {!isCollapsed && <span className="catalog-panel-title">Catalog: Default Library</span>}+ {!isCollapsed && <span className="catalog-panel-title">Library: OpenUI Library</span>}{isCollapsed && (- <span className="catalog-panel-icon-only" title="Catalog: Default Library">+ <span className="catalog-panel-icon-only" title="Library: OpenUI Library"><LayoutList size={16} /></span>)}diff --git a/docs/components/overview-components/overview-page.tsx b/docs/components/overview-components/overview-page.tsxindex 7b088c301..97b60cab3 100644--- a/docs/components/overview-components/overview-page.tsx+++ b/docs/components/overview-components/overview-page.tsx@@ -83,7 +83,7 @@ export function OverviewPage() {>A2UI</a>{" "}- that reduces token usage by up to 52%. Define your component library with Zod schemas, get+ that reduces token usage by up to 67.1%. Define your component library with Zod schemas, getautomatic system prompts, and parse LLM responses into renderable components.</p>@@ -244,7 +244,7 @@ import { FullScreen, openuiLibrary } from "@openuidev/react-ui";<Separator className="my-8 sm:my-16" />- {/* Default Library Section */}+ {/* OpenUI Library Section */}<div id="library" className="mb-12 sm:mb-20"><div className="mb-4 flex items-start gap-3 sm:mb-6 sm:gap-4"><div className="flex size-10 shrink-0 items-center justify-center rounded-lg bg-fd-muted sm:size-12">diff --git a/docs/content/docs/openui-lang/benchmarks.mdx b/docs/content/docs/openui-lang/benchmarks.mdxindex 81d51973e..4dfffd66d 100644--- a/docs/content/docs/openui-lang/benchmarks.mdx+++ b/docs/content/docs/openui-lang/benchmarks.mdx@@ -74,7 +74,7 @@ Generated by GPT-5.2 at temperature 0. Token counts measured with `tiktoken` usi| e-commerce-product | 2,449 | 2,381 | 1,166 | -52.4% | -51.0% || **TOTAL** | **10,180** | **9,948** | **4,800** | **-52.8%** | **-51.7%** |-OpenUI Lang uses roughly **half the tokens** of both JSON alternatives across all scenarios.+OpenUI Lang uses up to **67.1% fewer tokens** than both JSON alternatives across all scenarios.---@@ -92,7 +92,7 @@ Latency scales linearly with output token count at a given generation speed. At| settings-panel | 20.73s | 20.08s | 9.00s | **2.3x faster** || e-commerce-product | 40.82s | 39.68s | 19.43s | **2.1x faster** |-The latency advantage compounds with UI complexity. A pricing page or dashboard — the kinds of UIs where Generative UI delivers the most value — render **2–3× faster** with OpenUI Lang.+The latency advantage compounds with UI complexity. A contact form renders **up to 3.0× faster**, and even complex dashboards and pricing pages — the kinds of UIs where Generative UI delivers the most value — render **2–3× faster** with OpenUI Lang.---@@ -134,7 +134,7 @@ The latency advantage compounds with UI complexity. A pricing page or dashboard### Why is JSON-Render heavier than expected?-Vercel JSON-Render encodes each element as a separate `{"op":"add","path":"/elements/id","value":{...}}` line. The `op`, `path`, `value`, `type`, `props`, and `children` keys repeat for every node. For deeply nested UIs (dashboards, pricing pages), the structural repetition accumulates significantly — averaging **2.1× the tokens** of OpenUI Lang across our scenarios.+Vercel JSON-Render encodes each element as a separate `{"op":"add","path":"/elements/id","value":{...}}` line. The `op`, `path`, `value`, `type`, `props`, and `children` keys repeat for every node. For deeply nested UIs (dashboards, pricing pages), the structural repetition accumulates significantly — up to **3.0× the tokens** of OpenUI Lang across our scenarios.---diff --git a/docs/content/docs/openui-lang/index.mdx b/docs/content/docs/openui-lang/index.mdxindex 26bee8281..591bafdab 100644--- a/docs/content/docs/openui-lang/index.mdx+++ b/docs/content/docs/openui-lang/index.mdx@@ -58,7 +58,7 @@ cancelBtn = Button("Cancel", "action:cancel_contact", "secondary")<Cards><Card title="Quick Start" href="/docs/openui-lang/quickstart">- Start with the default library and render immediately.+ Start with the OpenUI library and render immediately.</Card><Card title="Defining Components" href="/docs/openui-lang/defining-components">Build custom component contracts with Zod.diff --git a/docs/content/docs/openui-lang/interactivity.mdx b/docs/content/docs/openui-lang/interactivity.mdxnew file mode 100644index 000000000..62ba4a59b--- /dev/null+++ b/docs/content/docs/openui-lang/interactivity.mdx@@ -0,0 +1,131 @@+---+title: Interactivity+description: Handle actions, forms, and state in OpenUI components.+---++OpenUI components can be interactive. The `Renderer` manages form state automatically and exposes callbacks for actions and persistence.++## Actions++When a user clicks a button or follow-up, the component calls `triggerAction`. The `Renderer` wraps this into an `ActionEvent` and fires `onAction`.++```tsx+<Renderer+ library={myLibrary}+ response={content}+ onAction={(event) => {+ if (event.type === "continue_conversation") {+ // event.humanFriendlyMessage — button label or follow-up text+ // event.formState — field values at time of click+ // event.formName — scoping form name, if any+ }+ }}+/>+```++### `ActionEvent`++| Field | Type | Description |+| :--------------------- | :------------------------------ | :--------------------------------------------- |+| `type` | `string` | Action type (see built-in types below). |+| `params` | `Record<string, any>` | Extra parameters from the component. |+| `humanFriendlyMessage` | `string` | Display label for the action. |+| `formState` | `Record<string, any> \| undefined` | Raw field state at time of action. |+| `formName` | `string \| undefined` | Form that scoped the action, if any. |++### Built-in action types++```ts+enum BuiltinActionType {+ ContinueConversation = "continue_conversation",+ OpenUrl = "open_url",+}+```++- `ContinueConversation` — sends the user's intent back to the LLM.+- `OpenUrl` — opens a URL in a new tab. Expects `params.url`.++### Using `triggerAction` in components++Inside `defineComponent`, use the `useTriggerAction` hook:++```tsx+const MyButton = defineComponent({+ name: "MyButton",+ description: "A clickable button.",+ props: z.object({ label: z.string() }),+ component: ({ props }) => {+ const triggerAction = useTriggerAction();+ return <button onClick={() => triggerAction(props.label)}>{props.label}</button>;+ },+});+```++`triggerAction(userMessage, formName?, action?)` — the second and third arguments are optional.++---++## Form state++The `Renderer` tracks field values automatically. Components use `useSetFieldValue` and `useGetFieldValue` to read and write state.++### Persistence++Use `onStateUpdate` to persist field state (e.g. to a message in your thread store) and `initialState` to hydrate it on load.++```tsx+<Renderer+ library={myLibrary}+ response={content}+ onStateUpdate={(state) => {+ // state is a raw Record<string, any> of all field values+ saveToBackend(state);+ }}+ initialState={loadedState}+/>+```++`onStateUpdate` fires on every field change. The state format is opaque — persist and hydrate it as-is.++### Field hooks++Use these inside `defineComponent` renderers:++| Hook | Signature | Description |+| :------------------ | :------------------------------------------------------------------------------------------------- | :--------------------------------- |+| `useGetFieldValue` | `(formName: string \| undefined, name: string) => any` | Read a field's current value. |+| `useSetFieldValue` | `(formName: string \| undefined, componentType: string \| undefined, name: string, value: any, shouldTriggerSaveCallback?: boolean) => void` | Write a field value. |+| `useFormName` | `() => string \| undefined` | Get the enclosing form's name. |+| `useSetDefaultValue`| `(options: { formName?, componentType, name, existingValue, defaultValue, shouldTriggerSaveCallback? }) => void` | Set a default if no value exists. |++---++## Validation++Form fields can declare validation rules. The `Form` component provides a validation context via `useFormValidation`.++```ts+interface FormValidationContextValue {+ errors: Record<string, string | undefined>;+ validateField: (name: string, value: unknown, rules: ParsedRule[]) => boolean;+ registerField: (name: string, rules: ParsedRule[], getValue: () => unknown) => void;+ unregisterField: (name: string) => void;+ validateForm: () => boolean;+ clearFieldError: (name: string) => void;+}+```++Built-in validators include `required`, `minLength`, `maxLength`, `min`, `max`, `pattern`, and `email`. Custom validators can be added via `builtInValidators`.++---++## Next Steps++<Cards>+ <Card title="Renderer" href="/docs/openui-lang/renderer">+ Full Renderer props reference.+ </Card>+ <Card title="API Reference" href="/docs/api-reference/lang-react">+ Complete lang-react API.+ </Card>+</Cards>diff --git a/docs/content/docs/openui-lang/meta.json b/docs/content/docs/openui-lang/meta.jsonindex 5606f63c0..2b2c934ed 100644--- a/docs/content/docs/openui-lang/meta.json+++ b/docs/content/docs/openui-lang/meta.json@@ -9,6 +9,7 @@"defining-components","system-prompts","renderer",+ "interactivity","---Advanced---","specification","benchmarks"diff --git a/docs/content/docs/openui-lang/quickstart.mdx b/docs/content/docs/openui-lang/quickstart.mdxindex 2cc45f13f..dfb5c8cc3 100644--- a/docs/content/docs/openui-lang/quickstart.mdx+++ b/docs/content/docs/openui-lang/quickstart.mdx@@ -1,6 +1,6 @@---title: Quick Start-description: Use the default library to render OpenUI Lang immediately.+description: Use the OpenUI library to render OpenUI Lang immediately.---This is the fastest path: use `openuiLibrary` from `@openuidev/react-ui` and render LLM output with `@openuidev/lang-react`.diff --git a/docs/content/docs/openui-lang/standard-library.mdx b/docs/content/docs/openui-lang/standard-library.mdxindex f1b264197..2ac59e108 100644--- a/docs/content/docs/openui-lang/standard-library.mdx+++ b/docs/content/docs/openui-lang/standard-library.mdx@@ -1,6 +1,6 @@---title: Using the Standard Library-description: Use the built-in default library from @openuidev/react-ui.+description: Use the built-in OpenUI library from @openuidev/react-ui.---OpenUI ships with a prebuilt `openuiLibrary` for common layouts, forms, content, and charts.@@ -11,7 +11,7 @@ OpenUI ships with a prebuilt `openuiLibrary` for common layouts, forms, content,npm install @openuidev/lang-react @openuidev/react-ui```-## Render with default library+## Render with OpenUI library```tsximport "@openuidev/react-ui/components.css";diff --git a/docs/content/docs/openui-lang/syntax.mdx b/docs/content/docs/openui-lang/syntax.mdxindex 949b50e1b..b7ce890b2 100644--- a/docs/content/docs/openui-lang/syntax.mdx+++ b/docs/content/docs/openui-lang/syntax.mdx@@ -38,7 +38,7 @@ cancelBtn = Button("Cancel", "action:cancel", "secondary")## Rules- First statement is the entry point.-- For default library prompts, start with `root = Stack(...)`.+- For OpenUI library prompts, start with `root = Stack(...)`.- Arguments are positional, based on Zod key order.- Optional args can be omitted from the end.- Forward references are allowed.diff --git a/docs/lib/layout.shared.tsx b/docs/lib/layout.shared.tsxindex 58740c198..dcd25bc8e 100644--- a/docs/lib/layout.shared.tsx+++ b/docs/lib/layout.shared.tsx@@ -8,7 +8,7 @@ export const gitConfig = {export const siteConfig = {githubUrl: `https://github.com/${gitConfig.user}/${gitConfig.repo}`,- discordUrl: "https://discord.gg/ZeSTyHZTEV",+ discordUrl: "https://discord.com/invite/Pbv5PsqUSv",};export function baseOptions(): BaseLayoutProps {diff --git a/packages/create-openui-app/src/templates/openui-chat/src/app/page.tsx b/packages/create-openui-app/src/templates/openui-chat/src/app/page.tsxindex db66d864a..b828b1d20 100644--- a/packages/create-openui-app/src/templates/openui-chat/src/app/page.tsx+++ b/packages/create-openui-app/src/templates/openui-chat/src/app/page.tsx@@ -4,9 +4,9 @@ import "@openuidev/react-ui/styles/index.css";import { openAIMessageFormat, openAIReadableStreamAdapter } from "@openuidev/react-headless";import { FullScreen } from "@openuidev/react-ui";-import { defaultLibrary, defaultPromptOptions } from "@openuidev/react-ui/genui-lib";+import { openuiLibrary, openuiPromptOptions } from "@openuidev/react-ui/genui-lib";-const systemPrompt = defaultLibrary.prompt(defaultPromptOptions);+const systemPrompt = openuiLibrary.prompt(openuiPromptOptions);export default function Home() {return (@@ -24,7 +24,7 @@ export default function Home() {});}}streamProtocol={openAIReadableStreamAdapter()}- componentLibrary={defaultLibrary}+ componentLibrary={openuiLibrary}agentName="OpenUI Chat"/></div>