@k8ordo/ui

Generative UI

Have an LLM build UI out of @k8ordo/ui components only. With json-render or OpenUI, the adapters in this library cover everything from the prompt to the rendering.

Install

Install zod and the packages for whichever you use, json-render or OpenUI.

json-render

bash
npm install @json-render/core @json-render/react zod

OpenUI

bash
npm install @openuidev/react-lang @openuidev/lang-core zod

The supported versions are json-render 0.22.x and OpenUI 1.x. json-render is still 0.x, where a minor release can break compatibility.

Warning

Pitfall

The adapters read the React context that json-render or OpenUI itself provides. If your app and @k8ordo/ui resolve different versions of it, the types and the build still pass. At render time, though, the form components fail: OpenUI with useOpenUI must be used within a <Renderer /> component., json-render with useStateStore must be used within a StateProvider. Keep one version in the app.

Prompt generation

system-prompt.ts
import { catalog, uiRules } from '@k8ordo/ui/json-render';

const systemPrompt = catalog.prompt({ customRules: [...uiRules] });

@k8ordo/ui/json-render loads on the server. A Server Component or any server code can call catalog.prompt().

uiRules lists the rules a model most often breaks, such as giving a table row as many cells as there are columns. Pass them as customRules and they are added to the prompt.

system-prompt.ts
const systemPrompt = catalog.prompt({
  customRules: [...uiRules, 'Write all UI text in Japanese.'],
A rule that sets the language of the UI text
});

Everything the adapters hand the model is English, whatever the application’s locale. To set the language of the text written into the UI, add a rule of your own.

Rendering in the browser

gen-ui.tsx
'use client';
import type { UISpec } from '@k8ordo/ui/json-render';
import { JsonRenderUI } from '@k8ordo/ui/json-render/registry';

export function GenUi({ spec }: { spec: UISpec }) {
  return (
    <JsonRenderUI
      spec={spec}
      onStateChange={(changes) => console.log(changes)}
    />
  );
}

JsonRenderUI bundles json-render’s provider, its renderer and the component registry. Passing the spec is all it takes.

To collect form values, pass onStateChange. It receives an array of the changed path and value pairs.

Validating the output

ts
import { validateGeneratedSpec } from '@k8ordo/ui/json-render';

async function toSpec(
  output: string,
  ask: (prompt: string) => Promise<string>,
) {
  const result = validateGeneratedSpec(JSON.parse(output));
  if (result.ok) return result.spec;
  const retried = validateGeneratedSpec(
    JSON.parse(await ask(result.repairPrompt)),
  );
  return retried.ok ? retried.spec : null;
}

validateGeneratedSpec fixes what can be fixed mechanically, then checks the spec’s structure and each component’s props. When the spec passes, it returns the spec.

When it does not, it returns the issues it found and a repairPrompt built from them. The repairPrompt can be sent straight back to the model.

Typed specs

tsx
import type { UISpec } from '@k8ordo/ui/json-render';

const spec = {
  root: 'root',
  elements: {
    root: { type: 'Stack', props: { direction: 'column' }, children: ['ok'] },
    ok: { type: 'Button', props: { label: 'OK' } },
  },
} satisfies UISpec;

When you write a spec by hand, add satisfies UISpec. A misspelt component name or prop becomes a type error.

OpenUI

gen-ui.tsx
'use client';
import { library } from '@k8ordo/ui/openui';
import { Renderer } from '@openuidev/react-lang';

export function GenUi({ response }: { response: string }) {
  return <Renderer library={library} response={response} />;
}

OpenUI renders the model’s output string with library. Rendering happens in a Client Component.

system-prompt.ts
import { prompt } from '@k8ordo/ui/openui/prompt';

const systemPrompt = prompt();

The prompt comes from prompt() in @k8ordo/ui/openui/prompt. That entry does not depend on React, so it runs on the server. A rule that sets the language of the UI text goes in additionalRules.

k8ordo

React libraries that use Baseline features without holding back.