@json-render/ink
JSON 사양을 표준 컴포넌트, 데이터 바인딩, 가시성, 액션, 동적 속성을 갖춘 인터랙티브 터미널 컴포넌트 트리로 변환하는 Ink 터미널 렌더러입니다.
빠른 시작
import { defineCatalog } from "@json-render/core";
import { schema } from "@json-render/ink/schema";
import {
standardComponentDefinitions,
standardActionDefinitions,
} from "@json-render/ink/catalog";
import { defineRegistry, Renderer, type Components } from "@json-render/ink";
import { z } from "zod";
// 표준 + 커스텀 컴포넌트로 카탈로그 생성
const catalog = defineCatalog(schema, {
components: {
...standardComponentDefinitions,
CustomWidget: {
props: z.object({ title: z.string() }),
slots: [],
description: "커스텀 위젯",
},
},
actions: standardActionDefinitions,
});
// 커스텀 컴포넌트만 등록 (표준 컴포넌트는 내장)
const { registry } = defineRegistry(catalog, {
components: {
CustomWidget: ({ props }) => <Text>{props.title}</Text>,
} as Components<typeof catalog>,
});
// 렌더링
function App({ spec }) {
return (
<JSONUIProvider initialState={{}}>
<Renderer spec={spec} registry={registry} />
</JSONUIProvider>
);
}
사양 구조 (플랫 요소 맵)
Ink 스키마는 루트 키가 있는 플랫 요소 맵을 사용합니다:
{
"root": "main",
"elements": {
"main": {
"type": "Box",
"props": { "flexDirection": "column", "padding": 1 },
"children": ["heading", "content"]
},
"heading": {
"type": "Heading",
"props": { "text": "Dashboard", "level": "h1" },
"children": []
},
"content": {
"type": "Text",
"props": { "text": "Hello from the terminal!" },
"children": []
}
}
}
표준 컴포넌트
레이아웃
Box- Flexbox 레이아웃 컨테이너 (터미널<div>와 유사). 그룹화, 간격, 테두리, 정렬에 사용합니다. 기본 flexDirection은 row입니다.Text- 선택적 스타일(색상, 굵게, 기울임 등)이 있는 텍스트 출력Newline- 빈 줄을 삽입합니다. 반드시 flexDirection이 column인 Box 안에 있어야 합니다.Spacer- 주축을 따라 확장되는 유연한 빈 공간
콘텐츠
Heading- 섹션 제목 (h1: 굵게+밑줄, h2: 굵게, h3: 굵게+흐리게, h4: 흐리게)Divider- 선택적 중앙 제목이 있는 수평 구분선Badge- 색상이 있는 인라인 레이블 (변형: 기본, 정보, 성공, 경고, 오류)Spinner- 선택적 레이블이 있는 애니메이션 로딩 스피너ProgressBar- 수평 진행률 표시줄 (0-1)Sparkline- 유니코드 블록 문자를 사용한 인라인 차트BarChart- 레이블과 값이 있는 수평 막대 차트Table- 헤더와 행이 있는 표 형식 데이터List- 글머리 기호 또는 번호가 매겨진 목록ListItem- 제목, 부제목, 앞/뒤 텍스트가 있는 구조화된 목록 행Card- 선택적 제목이 있는 테두리 컨테이너KeyValue- 키-값 쌍 표시Link- 선택적 레이블이 있는 클릭 가능한 URLStatusLine- 색상 아이콘이 있는 상태 메시지 (정보, 성공, 경고, 오류)Markdown- 터미널 스타일로 마크다운 텍스트 렌더링
인터랙티브
TextInput- 텍스트 입력 필드 (이벤트: submit, change)Select- 화살표 키 탐색이 있는 선택 메뉴 (이벤트: change)MultiSelect- 스페이스바로 전환하는 다중 선택 (이벤트: change, submit)ConfirmInput- 예/아니오 확인 프롬프트 (이벤트: confirm, deny)Tabs- 왼쪽/오른쪽 화살표 키가 있는 탭 표시줄 탐색 (이벤트: change)
가시성 조건
요소에 visible을 사용하여 상태에 따라 표시/숨기기를 제어합니다. 문법: { "$state": "/path" }, { "$state": "/path", "eq": value }, { "$state": "/path", "not": true }, AND의 경우 { "$and": [cond1, cond2] }, OR의 경우 { "$or": [cond1, cond2] }.
동적 속성 표현식
모든 속성 값은 렌더링 시 해결되는 데이터 기반 표현식이 될 수 있습니다:
{ "$state": "/state/key" }- 상태 모델에서 읽습니다 (단방향 읽기){ "$bindState": "/path" }- 양방향 바인딩: 폼 컴포넌트의 자연스러운 값 속성에 사용합니다{ "$bindItem": "field" }- 반복 항목 필드에 대한 양방향 바인딩{ "$cond": <조건>, "$then": <값>, "$else": <값> }- 조건부 값{ "$template": "안녕하세요, ${/name}!" }- 문자열에 상태 값 보간
컴포넌트는 양방향 바인딩에 statePath 속성을 사용하지 않습니다. 대신 자연스러운 값 속성에 { "$bindState": "/path" }를 사용하세요.
이벤트 시스템
컴포넌트는 emit을 사용하여 명명된 이벤트를 발생시킵니다. 요소의 on 필드는 이벤트를 액션 바인딩에 매핑합니다:
CustomButton: ({ props, emit }) => (
<Box>
<Text>{props.label}</Text>
{/* emit("press")는 사양의 on.press에 바인딩된 액션을 트리거합니다 */}
</Box>
),
{
"type": "CustomButton",
"props": { "label": "제출" },
"on": { "press": { "action": "submit" } },
"children": []
}
내장 액션
setState, pushState, removeState는 내장되어 있으며 자동으로 처리됩니다:
{ "action": "setState", "params": { "statePath": "/activeTab", "value": "home" } }
{ "action": "pushState", "params": { "statePath": "/items", "value": { "text": "새 항목" } } }
{ "action": "removeState", "params": { "statePath": "/items", "index": 0 } }
반복 (동적 목록)
컨테이너 요소에 repeat 필드를 사용하여 상태 배열의 항목을 렌더링합니다:
{
"type": "Box",
"props": { "flexDirection": "column" },
"repeat": { "statePath": "/items", "key": "id" },
"children": ["item-row"]
}
반복되는 자식 내부에서는 { "$item": "field" }를 사용하여 현재 항목을 읽고 { "$index": true }를 사용하여 현재 인덱스를 읽습니다.
스트리밍
useUIStream을 사용하여 JSONL 패치 스트림에서 점진적으로 사양을 렌더링합니다:
import { useUIStream } from "@json-render/ink";
const { spec, send, isStreaming } = useUIStream({ api: "/api/generate" });
서버 측 프롬프트 생성
./server 내보내기를 사용하여 카탈로그에서 AI 시스템 프롬프트를 생성합니다:
import { catalog } from "./catalog";
const systemPrompt = catalog.prompt({ system: "당신은 터미널 어시스턴트입니다." });
제공자
| 제공자 | 목적 |
|---|---|
StateProvider | 컴포넌트 간 상태 공유 (JSON Pointer 경로). 제어 모드를 위한 선택적 store 속성을 허용합니다. |
ActionProvider | 이벤트 시스템을 통해 전달된 액션 처리 |
VisibilityProvider | 상태 기반 조건부 렌더링 활성화 |
ValidationProvider | 폼 필드 유효성 검사 |
FocusProvider | 인터랙티브 컴포넌트 간 포커스 관리 |
JSONUIProvider | 모든 컨텍스트를 위한 결합 제공자 |
외부 저장소 (제어 모드)
외부 상태 관리를 사용하려면 StateProvider (또는 JSONUIProvider)에 StateStore를 전달합니다:
import { createStateStore, type StateStore } from "@json-render/ink";
const store = createStateStore({ count: 0 });
<StateProvider store={store}>{children}</StateProvider>
store.set("/count", 1); // React가 자동으로 다시 렌더링합니다
store가 제공되면 initialState와 onStateChange는 무시됩니다.
createRenderer (상위 수준 API)
import { createRenderer } from "@json-render/ink";
import { standardComponents } from "@json-render/ink";
import { catalog } from "./catalog";
const InkRenderer = createRenderer(catalog, {
...standardComponents,
// 여기에 커스텀 컴포넌트 재정의
});
// InkRenderer는 모든 제공자(상태, 가시성, 액션, 포커스)를 포함합니다
render(
<InkRenderer spec={spec} state={{ activeTab: "overview" }} />
);
주요 내보내기
| 내보내기 | 목적 |
|---|---|
defineRegistry | 카탈로그에서 타입 안전 컴포넌트 레지스트리 생성 |
Renderer | 레지스트리를 사용하여 사양 렌더링 |
createRenderer | 상위 수준: 내장 제공자가 있는 컴포넌트 생성 |
JSONUIProvider | 모든 컨텍스트를 위한 결합 제공자 |
schema | Ink 플랫 요소 맵 스키마 (내장 상태 액션 포함) |
standardComponentDefinitions | 모든 표준 컴포넌트에 대한 카탈로그 정의 |
standardActionDefinitions | 표준 액션에 대한 카탈로그 정의 |
standardComponents | 사전 구축된 컴포넌트 구현 |
useStateStore | 상태 컨텍스트에 접근 |
useStateValue | 상태에서 단일 값 가져오기 |
useBoundProp | $bindState/$bindItem 표현식을 위한 양방향 바인딩 |
useActions | 액션 컨텍스트에 접근 |
useAction | 단일 액션 디스패치 함수 가져오기 |
useOptionalValidation | useValidation의 비-예외 변형 |
useUIStream | API 엔드포인트에서 사양 스트리밍 |
createStateStore | 프레임워크에 독립적인 인메모리 StateStore 생성 |
StateStore | 외부 상태 관리를 연결하기 위한 인터페이스 |
Components | 타입이 있는 컴포넌트 맵 (카탈로그 인식) |
Actions | 타입이 있는 액션 맵 (카탈로그 인식) |
ComponentContext | 타입이 있는 컴포넌트 컨텍스트 (카탈로그 인식) |
flatToTree | 플랫 요소 맵을 트리 구조로 변환 |
터미널 UI 디자인 가이드라인
- 레이아웃에는 Box를 사용하세요 (flexDirection, padding, gap). 기본 flexDirection은 row입니다.
- 터미널 너비는 약 80-120열입니다. 주요 구조에는 수직 레이아웃(flexDirection: column)을 선호하세요.
- 시각적 그룹화를 위해 Box에서 borderStyle을 사용하세요 (single, double, round, bold).
- 명명된 터미널 색상을 사용하세요: red, green, yellow, blue, magenta, cyan, white, gray.
- 섹션 제목에는 Heading, 섹션 구분에는 Divider, 상태에는 Badge, 레이블이 있는 데이터에는 KeyValue, 테두리 그룹에는 Card를 사용하세요.
- 다중 뷰 UI에는 Tabs를 사용하고 자식 콘텐츠에는 가시성 조건을 적용하세요.
- 인라인 트렌드에는 Sparkline, 값 비교에는 BarChart를 사용하세요.