actionbook/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

| Task | File | Pattern | |------|------|---------| | Define component schema | src/catalog.ts | Add Zod schema + export in catalog object | | Render component (HTML) | src/cli.ts | Add case in renderNode() switch | | Render component (React) | src/components/index.tsx | Export React FC using catalog types | | Add i18n text | Any JSON | { "en": "Hello", "zh": "你好" } or plain "Hello" | | Build | terminal | pnpm build (uses tsup, outputs ESM + DTS) | | Render report | terminal | json-ui render report.json [-o out.html] [--no-open] |

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:

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

Three Rendering Layers

| Layer | File | Output | Use Case | |-------|------|--------|----------| | Zod Schemas | catalog.ts | Type definitions | Validation, type safety | | HTML Renderer | cli.ts | Static HTML string | CLI render command | | React Components | components/index.tsx | React elements | Embedded usage |

Data Flow

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

Component Catalog (38 types)

Layout

| Component | Key Props | Description | |-----------|-----------|-------------| | Report | title?, theme | Root wrapper, 800px max-width | | Section | title, icon?, collapsible? | Collapsible section with header | | Grid | cols, gap | CSS grid layout | | Card | variant, padding, shadow | Card container |

Paper Info

| Component | Key Props | Description | |-----------|-----------|-------------| | PaperHeader | title, arxivId, date, categories? | Paper title + metadata | | AuthorList | authors, layout?, maxVisible? | Author names + affiliations | | Abstract | text, highlights?, maxLength? | Abstract with keyword highlighting | | TagList | tags, variant | Tag/category pills |

Content

| Component | Key Props | Description | |-----------|-----------|-------------| | ContributionList | items, numbered? | Numbered contributions with badges | | MethodOverview | steps, showConnectors? | Step-by-step method pipeline | | Highlight | text, type, source? | Blockquote (quote/important/warning/code) | | KeyPoint | icon, title, description | Icon + title + description | | CodeBlock | code, language, showLineNumbers? | Syntax-highlighted code | | Prose | content | Markdown content block | | Callout | type, title?, content | Info/tip/warning/important/note box |

Rich Content

| Component | Key Props | Description | |-----------|-----------|-------------| | Image | src, alt?, caption?, width? | Single image | | Figure | images, caption?, label? | Multi-image figure | | Formula | latex, block?, label? | LaTeX formula | | DefinitionList | items | Term-definition pairs | | Theorem | type, number?, title?, content | Theorem/lemma/proposition | | Algorithm | title, steps, caption? | Algorithm pseudocode | | ResultsTable | columns, rows, highlights? | Results with best-cell highlighting |

Data Display

| Component | Key Props | Description | |-----------|-----------|-------------| | Metric | label, value, trend?, icon? | Single metric card | | MetricsGrid | metrics, cols? | Grid of metric cards | | Table | columns, rows, striped?, caption? | Data table |

Interactive

| Component | Key Props | Description | |-----------|-----------|-------------| | LinkButton | href, label, icon?, external? | Styled link button | | LinkGroup | links, layout? | Group of link buttons |

Brand

| Component | Key Props | Description | |-----------|-----------|-------------| | BrandHeader | badge?, poweredBy?, showBadge? | AI-generated badge header | | BrandFooter | timestamp, attribution?, disclaimer? | Footer with attribution |

I18n System

Backward-Compatible Bilingual Strings

The I18nString type accepts both plain strings and bilingual objects:

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

JSON Usage

// 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:

// 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:

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

React Rendering (components/index.tsx)

// 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:

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:

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:

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):

// 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

| Error | Cause | Solution | |-------|-------|---------| | Type 'I18nStringType' is not assignable to 'ReactNode' | Passing i18n object directly to JSX | Wrap with <I18nText value={...} /> | | Property 'length' does not exist on type 'I18nStringType' | Calling string methods on i18n value | Use type guard: typeof text === 'string' ? text : text.en | | Images not loading from arxiv | crossorigin="anonymous" on <img> | Remove crossorigin; keep only referrerpolicy="no-referrer" | | Language switcher not working | Missing CSS rules or JS | Ensure html[lang] .i18n-* CSS rules and toggle JS are in template | | Build fails with type errors | Schema changed but components not updated | Update all three files: catalog, cli, components |

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.

<!-- 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:

| Wrong | Correct | Reason | |-------|---------|--------| | 评论器 | 价值函数（critic） | Standard ML term | | 运行估计 | 滑动估计 | Running estimate = 滑动估计 | | 重加权因子 | 加权系数 | More natural Chinese | | 不断演化的 | 动态更新的 | Clearer meaning | | 简单修复 | 改动小 | Academic tone |

Build & CLI

# 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