The Open Standard for Generative UI
docs: code tab fallback, API Reference overview, and mobile Docs button (#1339)
abhithesys0aba97312d22
diff --git a/docs/components/code-block-tabs.tsx b/docs/components/code-block-tabs.tsxnew file mode 100644index 000000000..92caa30dd--- /dev/null+++ b/docs/components/code-block-tabs.tsx@@ -0,0 +1,32 @@+"use client";++import { CodeBlockTabs as BaseCodeBlockTabs } from "fumadocs-ui/components/codeblock";+import { Children, isValidElement, useState, type ComponentProps } from "react";++/**+ * Code block tabs that fall back to their first tab when the remembered group value isn't one of+ * theirs. Fumadocs restores a `tab-group` choice as is, so picking "OpenAI" on one page left a+ * block on another page with no matching tab showing nothing.+ */+export function CodeBlockTabs({+ defaultValue,+ children,+ ...props+}: ComponentProps<typeof BaseCodeBlockTabs>) {+ const values = Children.toArray(children).flatMap((child) =>+ isValidElement<{ value?: unknown }>(child) && typeof child.props.value === "string"+ ? [child.props.value]+ : [],+ );+ const [selected, setSelected] = useState(defaultValue ?? values[0]);++ return (+ <BaseCodeBlockTabs+ {...props}+ value={selected !== undefined && values.includes(selected) ? selected : values[0]}+ onValueChange={setSelected}+ >+ {children}+ </BaseCodeBlockTabs>+ );+}diff --git a/docs/components/site-marketing-header.module.css b/docs/components/site-marketing-header.module.cssindex 017a59d6b..e71bfa366 100644--- a/docs/components/site-marketing-header.module.css+++ b/docs/components/site-marketing-header.module.css@@ -252,27 +252,53 @@}/* GitHub button pinned to the bottom of the mobile tray, separated like a section. */+/* Docs and GitHub side by side, as two equal buttons. */.mobileTrayFooter {- display: flex;- flex-direction: column;+ display: grid;+ grid-template-columns: repeat(2, minmax(0, 1fr));gap: 0.625rem;- /* Takes up the slack, so the button sits at the bottom of the screen when the- sections are collapsed and is simply pushed down when they are not. */+ /* Takes up the slack, so the buttons sit at the bottom of the screen when the+ sections are collapsed. Sticky, so they stay there when open sections make+ the tray scroll. The negative margin cancels .mobileTrayInner's bottom+ padding, so the footer's own background covers the gap under it. */+ position: sticky;+ bottom: 0;margin-top: auto;- padding-top: 1.5rem;+ margin-bottom: -1rem;+ padding-block: 1rem;+ border-top: 1px solid var(--openui-border-default);+ background: var(--openui-foreground);}-/* Full-width GitHub button with the trailing arrow pushed to the right edge. */-.mobileTrayFooter a {- width: 100%;- justify-content: flex-start;+[data-theme="dark"] .mobileTrayFooter {+ background: #000;}-/* Trailing arrow: same lucide ArrowRight as the homepage mobile CTA. */-.mobileTrayArrow {- margin-left: auto;- flex-shrink: 0;- color: currentColor;+/* Docs: a secondary button beside the primary GitHub one. Same size and shape as+ the compact GitHub pill; colours from the site's secondary pill+ (.pillSecondary in Button.module.css), which follow the theme tokens. */+.mobileTrayDocsLink {+ box-sizing: border-box;+ display: inline-flex;+ height: 2.5rem;+ align-items: center;+ gap: 0.375rem;+ padding-inline: 0.875rem;+ border: 1px solid var(--openui-border-default);+ border-radius: 999px;+ background: var(--openui-foreground);+ box-shadow: var(--openui-shadow-l);+ color: var(--openui-text-neutral-primary);+ font-family: "Inter", "Segoe UI", sans-serif;+ font-size: 0.9375rem;+ font-weight: 500;+ text-decoration: none;+}++/* Both buttons fill their column, contents centred. */+.mobileTrayFooter a {+ width: 100%;+ justify-content: center;}@media (min-width: 1024px) {diff --git a/docs/components/site-marketing-header.tsx b/docs/components/site-marketing-header.tsxindex 409853620..73d7e4bc8 100644--- a/docs/components/site-marketing-header.tsx+++ b/docs/components/site-marketing-header.tsx@@ -11,7 +11,7 @@ import {SitePrimaryNav,} from "@/components/site-primary-nav";import { ThemeToggle } from "@/components/theme-toggle";-import { ArrowRight, ChevronDown } from "lucide-react";+import { BookOpen, ChevronDown } from "lucide-react";import { AnimatePresence, motion } from "motion/react";import { useTheme } from "next-themes";import Link from "next/link";@@ -84,8 +84,11 @@ function MobileMenu({ onClose }: { onClose: () => void }) {rather than trailing loose underneath it. Benchmarks is deliberately not oneof them: it is duplicated in the nav on purpose while it is new, and thetray already lists it under Other, so the second copy is dropped here. */+ /* Documentation is the one link most visitors open the menu for, so it sits in+ the sticky footer next to GitHub instead of being folded in with the rest. */+ const docsLink = leafItems.find((leaf) => leaf.href === "/docs");const covered = new Set(sections.flatMap((section) => section.items.map((item) => item.href)));- const extras = leafItems.filter((leaf) => !covered.has(leaf.href));+ const extras = leafItems.filter((leaf) => !covered.has(leaf.href) && leaf !== docsLink);if (extras.length > 0 && sections.length > 0) {const last = sections[sections.length - 1];sections[sections.length - 1] = { ...last, items: [...last.items, ...extras] };@@ -191,18 +194,21 @@ function MobileMenu({ onClose }: { onClose: () => void }) {})}<div className={styles.mobileTrayFooter}>+ {docsLink && (+ <Link+ className={styles.mobileTrayDocsLink}+ href={docsLink.href}+ onClick={onClose}+ aria-label={docsLink.title}+ >+ <BookOpen size={18} aria-hidden="true" />+ <span>Docs</span>+ </Link>+ )}<GitHubButtonvariant="desktopGlow"compacthref="https://github.com/thesysdev/openui"- arrow={- <ArrowRight- className={styles.mobileTrayArrow}- size={18}- strokeWidth={2}- aria-hidden="true"- />- }/></div></div>diff --git a/docs/content/docs/api-reference/index.mdx b/docs/content/docs/api-reference/index.mdxindex cf25f5202..c2941411c 100644--- a/docs/content/docs/api-reference/index.mdx+++ b/docs/content/docs/api-reference/index.mdx@@ -1,121 +1,96 @@----title: OpenUI SDK-description: Package guide for the full OpenUI SDK surface, including framework-agnostic, React, Angular, Vue, Svelte, email, browser-bundle, and CLI entrypoints.+title: API Reference+description: Reference for every OpenUI package, grouped by what it does.----The OpenUI SDK is split into packages that build on each other:+## Where to start-- **`@openuidev/lang-core`** — Framework-agnostic parser, prompt-generation, runtime-evaluation, and type layer. Use this when you need OpenUI Lang outside React, or when a backend/Edge function needs to generate prompts and parse streamed output without pulling in UI bindings.+- **A React chat app, fast:** [`@openuidev/react-ui`](/docs/api-reference/react-ui) gives you `AgentInterface`, a ready-made chat surface.+- **Your own React chat UI:** [`@openuidev/react-headless`](/docs/api-reference/react-headless) for chat state and streaming, with [`@openuidev/react-lang`](/docs/api-reference/react-lang) to render OpenUI Lang.+- **A backend, or a framework other than React:** [`@openuidev/lang-core`](https://github.com/thesysdev/openui/tree/main/packages/lang-core) for prompts and parsing, or the [Vue](/docs/api-reference/vue-lang), [Svelte](/docs/api-reference/svelte-lang), or [Angular](/docs/api-reference/angular-lang) bindings.-- **`@openuidev/react-lang`** — React runtime. Define component libraries with Zod schemas, generate system prompts, parse OpenUI Lang, and render streamed output to React. This is the foundation for React integrations.--- **`@openuidev/react-headless`** — Headless chat state management. Provides `ChatProvider`, thread/message hooks, streaming protocol adapters (OpenAI, Vercel AI SDK, AG-UI), and message format converters. Use this when you want full control over your chat UI.--- **`@openuidev/react-ui`** — `AgentInterface`, a ready-to-use chat surface with thread history and support for OpenUI component libraries. Depends on both packages above. Use this for the fastest path to a working chat interface.--- **`@openuidev/assistant-ui`** — OpenUI tool renderers, model instructions, and toolkit wiring for applications built with assistant-ui. The core integration supports any assistant-ui runtime; an optional `/ai-sdk` subpath adds Vercel AI SDK continuation behavior.--- **`@openuidev/langchain`** — LangChain and LangGraph integration primitives for transforming protocol-v2 agent streams into AG-UI events and relaying them to an OpenUI frontend over Web-standard Server-Sent Events.--- **`@openuidev/server`** — Server utilities for OpenUI Gateway. Repair invalid OpenUI Lang with Autofix, and persist a completed turn as Conversations API items. Import from `/openai` or `/vercel`.--- **`@openuidev/react-email`** — Pre-built email component library and prompt options for model-generated emails that can be rendered to HTML with React Email.--- **`@openuidev/vue-lang`** — Vue 3 bindings for defining model-renderable components, generating prompts from those definitions, and rendering streamed OpenUI Lang in Vue apps.--- **`@openuidev/svelte-lang`** — Svelte 5 bindings for defining model-renderable components, generating prompts, and rendering streamed OpenUI Lang in Svelte apps.--- **`@openuidev/browser-bundle`** — Prebuilt browser bundle for CDN, iframe, and no-build integrations. It packages the renderer, UI library, React, ReactDOM, and styles into script-tag-friendly assets.--- **`@openuidev/devtools`** — Development-only floating widget that surfaces the events captured by `@openuidev/observability`, with error messages and stack traces.--- **`@openuidev/cli`** — Command-line tool for scaffolding new OpenUI chat apps, generating system prompts or JSON schemas from library definitions, and deploying projects.--- **`@openuidev/angular-lang`** — Angular bindings for defining component libraries with Zod schemas, generating prompts, and rendering streamed OpenUI Lang with reactive state and actions.--- **`@openuidev/a2ui`** — Framework-agnostic A2UI v1.0 protocol client that uses OpenUI Lang statements for component payloads. Add the optional React entrypoint to render surfaces with `@openuidev/react-lang`.--## Choosing a package--| If you need... | Start here |-| :-------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------- |-| Prompt generation or parsing without a UI framework | [`@openuidev/lang-core`](https://github.com/thesysdev/openui/tree/main/packages/lang-core) |-| React rendering primitives for OpenUI Lang | [`@openuidev/react-lang`](/docs/api-reference/react-lang) |-| Chat state and streaming without prebuilt UI | [`@openuidev/react-headless`](/docs/api-reference/react-headless) |-| A ready-made React chat surface | [`@openuidev/react-ui`](/docs/api-reference/react-ui) |-| OpenUI tool rendering in an assistant-ui application | [`@openuidev/assistant-ui`](/docs/api-reference/assistant-ui) |-| A LangChain or LangGraph agent connected to an OpenUI frontend | [`@openuidev/langchain`](/docs/api-reference/langchain) |-| Autofix or conversation history on the Gateway | [`@openuidev/server`](/docs/api-reference/server) |-| Model-generated emails | [`@openuidev/react-email`](/docs/api-reference/react-email) |-| Vue integration | [`@openuidev/vue-lang`](/docs/api-reference/vue-lang) |-| Svelte integration | [`@openuidev/svelte-lang`](/docs/api-reference/svelte-lang) |-| Script-tag, CDN, or iframe embeds | [`@openuidev/browser-bundle`](https://github.com/thesysdev/openui/tree/main/packages/browser-bundle) |-| An in-app panel showing captured errors during development | [`@openuidev/devtools`](/docs/api-reference/devtools) |-| App scaffolding, prompt/schema generation, and deploy from the command line | [`@openuidev/cli`](/docs/api-reference/cli) |-| Angular integration | [`@openuidev/angular-lang`](/docs/api-reference/angular-lang) |-| A2UI lifecycle and messages with OpenUI Lang component payloads | [`@openuidev/a2ui`](/docs/api-reference/a2ui) |--## Packages+## Core<Cards><Cardtitle="@openuidev/lang-core"href="https://github.com/thesysdev/openui/tree/main/packages/lang-core">- Framework-agnostic parser, prompt-generation, runtime-evaluation, and type APIs for OpenUI Lang.+ Framework-agnostic parser, prompt generation, and runtime for OpenUI Lang. Docs on GitHub.</Card>+</Cards>++## Renderers++<Cards><Card title="@openuidev/react-lang" href="/docs/api-reference/react-lang">- defineComponent, createLibrary, Renderer, parser APIs, action types, context hooks, and form- validation.+ Define component libraries, generate prompts, and render streamed OpenUI Lang in React.+ </Card>+ <Card title="@openuidev/vue-lang" href="/docs/api-reference/vue-lang">+ Vue 3 bindings to define components and render streamed OpenUI Lang.</Card>+ <Card title="@openuidev/svelte-lang" href="/docs/api-reference/svelte-lang">+ Svelte 5 bindings to define components and render streamed OpenUI Lang.+ </Card>+ <Card title="@openuidev/angular-lang" href="/docs/api-reference/angular-lang">+ Angular bindings to define components and render streamed OpenUI Lang.+ </Card>+</Cards>++## Chat++<Cards><Card title="@openuidev/react-headless" href="/docs/api-reference/react-headless">- ChatProvider, useThread/useThreadList, stream protocol adapters (OpenAI, AG-UI), and message- format converters.+ Chat state, thread hooks, and stream adapters, with no UI.</Card><Card title="@openuidev/react-ui" href="/docs/api-reference/react-ui">- AgentInterface, a ready-to-use artifact chat surface with thread history, and two built-in- component libraries (general-purpose and chat-optimized).+ `AgentInterface`, a ready-made chat surface with thread history.</Card>+</Cards>++## Agent integrations++<Cards><Card title="@openuidev/assistant-ui" href="/docs/api-reference/assistant-ui">- Tool renderers, toolkit and instruction factories, interactive form handling, and optional- runtime-specific continuation helpers for assistant-ui applications.+ OpenUI tool renderers and model instructions for assistant-ui apps.</Card><Card title="@openuidev/langchain" href="/docs/api-reference/langchain">- LangGraph stream transformation, stateless run helpers, and AG-UI SSE relay APIs for OpenUI- frontends.+ Relay LangChain and LangGraph agent streams to an OpenUI frontend.</Card>+ <Card title="@openuidev/a2ui" href="/docs/api-reference/a2ui">+ A2UI v1.0 client that uses OpenUI Lang for component payloads.+ </Card>+</Cards>++## Server++<Cards><Card title="@openuidev/server" href="/docs/api-reference/server">- Autofix helpers for Chat Completions and the Vercel AI SDK, plus conversation history- persistence.+ Autofix and conversation history for OpenUI Gateway.</Card>+</Cards>++## Component libraries++<Cards><Card title="@openuidev/react-email" href="/docs/api-reference/react-email">- API reference for the pre-built email templates library and prompt options.+ Email components and prompt options for model-generated emails.</Card>- <Card title="@openuidev/vue-lang" href="/docs/api-reference/vue-lang">- Vue 3 bindings for defining model-renderable components and rendering streamed OpenUI Lang.+</Cards>++## Tooling++<Cards>+ <Card title="@openuidev/cli" href="/docs/api-reference/cli">+ Scaffold apps, generate prompts and library specs, and deploy.</Card>- <Card title="@openuidev/svelte-lang" href="/docs/api-reference/svelte-lang">- Svelte 5 bindings for defining model-renderable components and rendering streamed OpenUI Lang.+ <Card title="@openuidev/devtools" href="/docs/api-reference/devtools">+ Development-only widget that shows captured errors and stack traces.</Card><Cardtitle="@openuidev/browser-bundle"href="https://github.com/thesysdev/openui/tree/main/packages/browser-bundle">- CDN, iframe, and no-build browser bundle for the renderer, UI library, React, and styles.- </Card>- <Card title="@openuidev/devtools" href="/docs/api-reference/devtools">- Development-only floating widget surfacing captured events with error messages and stack traces.- </Card>- <Card title="@openuidev/cli" href="/docs/api-reference/cli">- openui create (scaffold a Next.js app), openui generate-api-key (mint a Gateway key), openui- deploy, and openui generate (system prompt + library spec from a library definition).- </Card>- <Card title="@openuidev/angular-lang" href="/docs/api-reference/angular-lang">- Angular component definitions, Renderer inputs and outputs, injection helpers, and form- validation.- </Card>- <Card title="@openuidev/a2ui" href="/docs/api-reference/a2ui">- A2UI v1.0 surface lifecycle, messages, actions, data model, functions, and schemas with OpenUI- Lang component updates.+ Script-tag bundle for CDN, iframe, and no-build embeds. Docs on GitHub.</Card></Cards>diff --git a/docs/content/docs/api-reference/meta.json b/docs/content/docs/api-reference/meta.jsonindex afd4bfd5d..da28c848f 100644--- a/docs/content/docs/api-reference/meta.json+++ b/docs/content/docs/api-reference/meta.json@@ -3,18 +3,24 @@"root": true,"pages": ["index",+ "---Renderers---","react-lang",+ "vue-lang",+ "svelte-lang",+ "angular-lang",+ "---Chat---","react-headless","react-ui",+ "---Agent integrations---","assistant-ui","langchain",+ "a2ui",+ "---Server---","server",+ "---Component libraries---","react-email",- "devtools",+ "---Tooling---","cli",- "angular-lang",- "vue-lang",- "svelte-lang",- "a2ui"+ "devtools"]}diff --git a/docs/content/docs/build-agents/chat-ui.mdx b/docs/content/docs/build-agents/chat-ui.mdxindex e44d70cdf..01f6ae2c6 100644--- a/docs/content/docs/build-agents/chat-ui.mdx+++ b/docs/content/docs/build-agents/chat-ui.mdx@@ -1,6 +1,7 @@---title: Choose a chat UIdescription: Compare the chat UIs that can render OpenUI Lang and pick one for your agent.+hideFooter: true---The chat UI has two jobs in an OpenUI agent:diff --git a/docs/mdx-components.tsx b/docs/mdx-components.tsxindex 54a8e8ec1..7c482cc0b 100644--- a/docs/mdx-components.tsx+++ b/docs/mdx-components.tsx@@ -13,6 +13,7 @@ import {DgScoreboard,DgSpeedArc,} from "@/components/charts/diffusion-charts";+import { CodeBlockTabs } from "@/components/code-block-tabs";import { DocsCard } from "@/components/docs-card";import { FakeVisual } from "@/components/fake-visual";import { Mermaid } from "@/components/mermaid";@@ -26,6 +27,7 @@ export function getMDXComponents(components?: MDXComponents): MDXComponents {return {...defaultMdxComponents,...TabsComponents,+ CodeBlockTabs,Card: DocsCard,TweetEmbed,FakeVisual,