Json Ui

json-ui

Version: 1.0.0 | Last Updated: 2026-01-29

You are an expert at the json-ui package — a JSON-to-HTML report renderer with React component support, bilingual i18n, and a CLI tool. Help users by:

• Writing components: Add new component types following existing patterns
• Rendering reports: Generate HTML from JSON report definitions
• Debugging: Fix rendering, build, or i18n issues
• Answering questions: Explain architecture, component catalog, data flow

Quick Reference

Documentation

Refer to local source files for detailed documentation:

• packages/json-ui/src/catalog.ts - All Zod schemas and type definitions
• packages/json-ui/src/cli.ts - HTML renderer and CLI entry point
• packages/json-ui/src/components/index.tsx - React component implementations

IMPORTANT: Documentation Completeness Check

Before answering questions, Claude MUST:

1. Read the relevant source file(s) listed above
2. If file read fails: Inform user "本地文档不完整，建议更新"
3. Still answer based on SKILL.md patterns + built-in knowledge

Architecture

JSON Report Format

Reports are trees of nodes:

jsonCopy code
{
  "type": "Report",
  "props": { "title": "My Report", "theme": "auto" },
  "children": [
    {
      "type": "Section",
      "props": { "title": "Overview", "icon": "bulb" },
      "children": [
        { "type": "Abstract", "props": { "text": "..." } }
      ]
    }
  ]
}

Three Rendering Layers

Data Flow

Copy code
JSON file → CLI parse → renderNode() recursion → HTML string → file write → browser open

Component Catalog (38 types)

Layout

Paper Info

Content

Rich Content

Data Display

Interactive

Brand

I18n System

Backward-Compatible Bilingual Strings

The I18nString type accepts both plain strings and bilingual objects:

typescriptCopy code
// catalog.ts
export const I18nString = z.union([
  z.string(),
  z.object({ en: z.string(), zh: z.string() }),
]);

JSON Usage

jsonCopy code
// Plain string (backward compatible)
{ "title": "Hello World" }

// Bilingual object
{ "title": { "en": "Hello World", "zh": "你好世界" } }

HTML Rendering (cli.ts)

For HTML output, i18n strings render as dual spans:

typescriptCopy code
// renderI18n() outputs:
<span class="i18n-en">Hello</span><span class="i18n-zh">你好</span>

// CSS controls visibility:
html[lang="en"] .i18n-zh { display: none; }
html[lang="zh"] .i18n-en { display: none; }

For HTML attributes (alt, title) where only a plain string works:

typescriptCopy code
// resolveI18n() picks one language:
const alt = resolveI18n(props.alt, 'en'); // returns plain string

React Rendering (components/index.tsx)

typescriptCopy code
// Use <I18nText> component for JSX:
<I18nText value={props.title} />

// Use resolveI18nStr() for plain string contexts:
const altText = resolveI18nStr(props.alt, 'en');

Language Switcher

• Fixed top-right button: EN | 中文
• Toggles <html lang="en|zh"> attribute
• Persists choice via localStorage.getItem('json-ui-lang')

Key Patterns

Pattern 1: Adding a New Component

1. Define schema in catalog.ts:

typescriptCopy code
export const MyWidgetSchema = z.object({
  label: I18nString,        // Use I18nString for user-visible text
  count: z.number(),        // Use z.string()/z.number() for data
  variant: VariantType.default('default'),
});

// Add to catalog object:
export const catalog = {
  // ...existing...
  MyWidget: MyWidgetSchema,
} as const;

// Export type:
export type MyWidgetProps = z.infer<typeof MyWidgetSchema>;

2. Add HTML renderer in cli.ts renderNode() switch:

typescriptCopy code
case 'MyWidget': {
  const { label, count, variant } = props;
  return `<div class="my-widget ${variant}">
    <span>${renderI18n(label)}</span>
    <strong>${escapeHtml(String(count))}</strong>
  </div>`;
}

3. Add React component in components/index.tsx:

typescriptCopy code
export const MyWidget: React.FC<MyWidgetProps> = ({ label, count, variant = 'default' }) => (
  <div className={`my-widget ${variant}`}>
    <span><I18nText value={label} /></span>
    <strong>{count}</strong>
  </div>
);

Pattern 2: Handling I18n in Special Cases

For text that needs processing (e.g., Abstract highlights):

typescriptCopy code
// HTML (cli.ts) - process each language separately:
if (isI18n(text)) {
  return `<span class="i18n-en">${processText(text.en)}</span>
          <span class="i18n-zh">${processText(text.zh)}</span>`;
} else {
  return processText(String(text));
}

// React (components/index.tsx):
if (typeof text === 'object' && 'en' in text && 'zh' in text) {
  return (
    <>
      <span className="i18n-en" dangerouslySetInnerHTML={{ __html: processText(text.en) }} />
      <span className="i18n-zh" dangerouslySetInnerHTML={{ __html: processText(text.zh) }} />
    </>
  );
}

Common Errors

CRITICAL: Image Handling

Do NOT use crossorigin="anonymous" on <img> tags.

Sites like arxiv.org do not send CORS headers. Adding crossorigin="anonymous" causes the browser to require CORS, which fails and blocks the image.

htmlCopy code
<!-- WRONG - breaks images from arxiv and similar sites -->
<img src="..." referrerpolicy="no-referrer" crossorigin="anonymous" />

<!-- CORRECT -->
<img src="..." referrerpolicy="no-referrer" />

Chinese Translation Guidelines

When writing Chinese translations for ML/AI papers:

Build & CLI

bashCopy code
# Build (ESM + DTS via tsup)
cd packages/json-ui && pnpm build

# Render report to HTML
node dist/cli.js render example-report-rich.json

# With options
node dist/cli.js render report.json -o output.html --no-open

When Writing Code

1. Always use I18nString for user-visible text properties in schemas
2. Always handle both string and {en, zh} forms in renderers
3. Never use crossorigin="anonymous" on img tags
4. Keep referrerpolicy="no-referrer" on img tags for privacy
5. Test with pnpm build after any schema or component changes
6. Update all three layers (catalog, cli, components) when adding components