@docyrus/generative-ui

@docyrus/generative-ui

React UI package for Docyrus-backed generative interfaces built on top of @json-render.

This package is the frontend/runtime layer. It gives you:

• the GenerativeUI React component
• React registry helpers for adapter-based preview rendering
• the shared mode catalogs and compile helpers re-exported from @docyrus/generative-ui-core
• typed mode/adaptor contracts for dashboard, widget, data-grid, form, email, PDF, and image generation

If you need backend-safe catalogs, prompt metadata, or compile helpers without a React runtime, use @docyrus/generative-ui-core directly.

Package Split

The generative UI system is intentionally split into two packages:

• @docyrus/generative-ui Frontend/runtime package. Use this in React applications.
• @docyrus/generative-ui-core Shared non-React package. Use this in backend services, API layers, validators, and generators.

In practice:

• browser app -> @docyrus/generative-ui
• backend API -> @docyrus/generative-ui-core

Installation

pnpm add @docyrus/generative-ui @docyrus/signin react react-dom

Peer dependencies:

• react
• react-dom
• @docyrus/signin

What GenerativeUI Does

GenerativeUI is a two-pane experience:

• left side: chat / prompt history
• right side: rendered preview or raw JSON

It talks to a backend endpoint that streams AI SDK UIMessage responses and json-render patch parts. For React-based modes, it compiles child-based json-render specs into adapter payloads before previewing them.

Default backend route shape:

/v1/ai/generate-ui/:mode

You can change that with endpointBasePath.

Supported Modes

• dashboard
• widget
• data-grid
• form
• email
• pdf
• image

Adapter requirements:

• dashboard -> requires adapters.dashboard
• widget -> requires adapters.widget
• data-grid -> requires adapters.widget
• form -> requires adapters.form
• email, pdf, image -> no React adapter required

Quick Start

import {
  GenerativeUI,
  type FormAdapterProps,
  type SmartCanvasValue,
  type SmartCanvasWidget,
} from "@docyrus/generative-ui";

function DashboardAdapter({ value }: { value: SmartCanvasValue }) {
  return <pre>{JSON.stringify(value, null, 2)}</pre>;
}

function WidgetAdapter({ widget }: { widget: SmartCanvasWidget }) {
  return <pre>{JSON.stringify(widget, null, 2)}</pre>;
}

function FormAdapter({ definition }: FormAdapterProps) {
  return <pre>{JSON.stringify(definition, null, 2)}</pre>;
}

export function Example() {
  return (
    <GenerativeUI
      modes={["dashboard", "widget", "data-grid", "form", "email", "pdf", "image"]}
      adapters={{
        dashboard: DashboardAdapter,
        widget: WidgetAdapter,
        form: FormAdapter,
      }}
      endpointBasePath="/v1/ai/generate-ui"
      defaultMode="dashboard"
      className="h-[900px]"
    />
  );
}

GenerativeUI Props

interface GenerativeUIProps {
  modes?: GenerativeUIMode[];
  defaultMode?: GenerativeUIMode;
  chatSurfaceMode?: "fixed" | "floating";
  endpointBasePath?: string;
  floatingPlaceholder?: string;
  adapters?: {
    dashboard?: DashboardAdapter;
    widget?: WidgetAdapter;
    form?: FormAdapter;
  };
  className?: string;
  onModeChange?: (mode: GenerativeUIMode) => void;
}

Notes:

• if modes is omitted, the component enables all supported modes it can satisfy from the provided adapters
• data-grid reuses the widget adapter because its compiled output is still a SmartCanvasWidget
• chatSurfaceMode="floating" is useful when embedding the generator as an assistant-style overlay

Adapter Model

The model does not directly generate the final adapter payloads for the React modes.

Instead, the flow is:

• the backend streams a child-based json-render spec
• the frontend parses that spec
• the frontend compiles it into the final adapter shape
• the preview is rendered through your adapter component

This is why the package exports both:

• catalogs / schemas / compile helpers
• registry helpers for preview rendering

Common Exports

Component:

• GenerativeUI

Registry helpers:

• createDashboardRegistry
• createWidgetRegistry
• createFormRegistry

Compile helpers and adapter-spec helpers:

• compileDashboardSpec
• compileWidgetSpec
• compileDataGridSpec
• compileFormSpec
• createDashboardAdapterSpec
• createWidgetAdapterSpec
• createDataGridAdapterSpec
• createFormAdapterSpec

Catalogs and schemas:

• dashboardCatalog
• widgetCatalog
• dataGridCatalog
• formCatalog
• dashboardSchema
• widgetSchema
• dataGridSchema
• formSchema

Types:

• GenerativeUIMode
• SmartCanvasWidget
• SmartCanvasValue
• GeneratedFormDefinition
• GeneratedFormField
• DashboardAdapterProps
• WidgetAdapterProps
• FormAdapterProps

Backend Expectations

For best results, pair this package with a backend that uses @docyrus/generative-ui-core.

The backend should:

• accept POST /v1/ai/generate-ui/:mode
• stream AI SDK UIMessage responses
• emit json-render patches
• validate React-based modes with the compile helpers from core

Minimal backend usage looks like:

import { getCatalogForMode, ROOT_ELEMENT_TYPES } from "@docyrus/generative-ui-core";

When To Use @docyrus/generative-ui-core Instead

Use core directly when you need:

• mode metadata such as SUPPORTED_MODES
• backend prompt generation via getCatalogForMode()
• compile-time validation on the server
• React-free access to catalogs and schemas
• CommonJS support in Node backends

Development Notes

• this package is published as a dist-based package
• it depends on @docyrus/generative-ui-core for all non-React mode logic
• image preview rendering uses a browser-side helper module and may rely on bundler-specific behavior when @json-render/image is involved

Related Packages

• @docyrus/generative-ui-core
• @json-render/core
• @json-render/react
• @json-render/react-email
• @json-render/react-pdf
• @json-render/image