OpenUI Lang — 컴포넌트 사용 사례 55개

총 55개 항목 · 111개 예제를 설명한다. 각 항목은 한국어 설명, 위치 기반 호출 계약, 완성된 OpenUI Lang 프로그램을 포함한다.

이 문서의 범위와 읽는 방법

이 문서는 OpenUI Lang을 사용해 UI를 기술하는 라이브러리의 독립적인 사용 설명서다. 특정 프로젝트의 저장소·소스 파일·로컬 서버·다른 문서를 열지 않아도 계약과 예제를 읽을 수 있도록 구성했다. 여기에 정의한 이름·인자 순서·동작은 이 문서가 설명하는 카탈로그의 계약이며, 모든 OpenUI 카탈로그에 동일한 항목이 기본 제공된다는 뜻은 아니다.

Markdown은 예제 코드를 보여주는 문서 형식이다. 코드를 실행해 실제 화면을 표시하려면 OpenUI Lang 파서·평가기·렌더러와 본문에 설명된 컴포넌트·함수·액션을 등록한 호스트 애플리케이션이 필요하다. 이 문서 자체가 실행 엔진이나 설치 패키지는 아니다.

공통 문법

root = Col([Text("횟수: " + $count), Button("증가", @Set($count, $count + 1))])
$count = 0

• root = ...: 화면 진입점이다. root에서 연결한 요소가 표시된다.
• Col(...), Text(...): 등록된 컴포넌트를 생성하는 표현식이다.
• $count = 0: 사용자가 변경할 수 있는 상태의 초깃값이다. 초깃값에는 숫자·문자열·배열·객체·null 같은 literal을 사용한다.
• result = @Percent(3, 4): 계산 표현식이다. 해당 함수가 등록돼 있다면 75가 계산된다. 일반 변수 result와 상태 변수 $result는 구별한다.
• @Set($count, 새값): 클릭 등의 이벤트에서 상태값을 바꾸는 내장 액션이다. 변경된 상태를 읽는 표현식과 UI가 다시 평가된다.
• 조건 ? 참일때값 : 거짓일때값: 조건에 따라 값을 선택한다.
• 인자는 위치 기반이다. ?가 붙은 계약 항목은 선택 인자이며 중간 인자를 건너뛸 때 예제처럼 null을 사용할 수 있다.
• null, false, 0, ""은 서로 다른 값이다. 객체 키는 {"id": 1}처럼 따옴표로 감싼다.
• 표현식은 참조를 정의보다 앞에 둘 수 있다. 따라서 첫 줄의 root가 뒤에 선언된 상태나 계산값을 참조하는 예제가 있다.

예제에 사용하는 보조 요소와 타입

이름	의미 / 최소 사용 계약
Col(children, gap?, align?)	자식을 세로로 배치한다. gap 숫자는 4px 단위이며, 예를 들어 4는 16px이다.
Text(text, size?, color?)	문장이나 문자열로 변환한 결과를 표시한다.
Table(columns, rows)	열 이름 배열과 행별 셀 배열로 표를 표시한다.
Button(label, action?)	클릭하면 action을 실행한다.
Input($value, label?, type?)	문자열·숫자 입력을 상태 변수에 연결한다. type은 text 또는 number다.
Box(children?, direction?, gap?, padding?, background?)	콘텐츠를 감싸 방향·간격·배경 등을 지정한다.
@Each(list, "item", expression)	목록의 각 항목에 expression을 적용해 결과 목록을 만든다.
@Join(list, separator?, field?)	항목 또는 지정 필드를 문자열로 연결한다.
@Set($state, value)	이벤트 발생 시 상태를 value로 바꾼다.
Node / Node[]	렌더링할 문자열·컴포넌트 표현식 / 그 목록이다.
$binding<T>	T 타입 값을 읽고 변경할 수 있는 상태 연결이다. 호출에서는 $value를 전달한다.
ActionExpression	클릭·제출 등의 이벤트에서 실행할 액션 표현식이다.
Color	ink·muted·surface·info·success·warning·danger 등의 토큰 또는 CSS 색상이다.
Radius	sm·md·lg·xl·full 또는 숫자로 지정한 모서리 반경이다.
Length	픽셀 숫자 또는 "50%" 같은 CSS 길이다.
Record<string, T>	문자열 키마다 T 타입 값을 갖는 객체다.

본문의 @Name(...)에는 값을 계산하는 함수와 이벤트를 실행하는 액션이 함께 등장한다. 함수는 결과값을 반환하고, 액션은 상태 변경·복사·대화 요청 같은 동작을 일으킨다. @Set·@Each 같은 내장 기능과 본문에서 설명하는 사용자 정의 항목은 구별한다.

화면을 읽는 기준

레이아웃 항목은 배치·간격·정렬, 입력 항목은 상태 변화, 미디어 항목은 외부 콘텐츠 표시, SVG 항목은 좌표와 도형의 변화를 관찰한다. MapMarker는 Map 안에서, SVG 도형은 Svg 안에서 사용한다. 컴포넌트 이름이 TypeScript 변수 이름과 같아야 하는 것은 아니며, 여기서는 계약에 나온 DSL 이름만 사용한다.

Form 안의 @ToAssistant("요청")는 폼 값과 후속 요청을 호스트에 전달하는 내장 액션이다. 실제 AI 대화로 이어질지는 호스트가 결정한다. Link는 HTTP(S) 주소를 연다. 이미지·지도·YouTube는 네트워크와 외부 서비스가 필요하며 문서에 포함된 정적 파일이 아니다. Image 예제의 HTTPS 주소도 외부 예시 이미지다. HtmlView는 별도 샌드박스 안에서 HTML을 실행한다.

전체 목차

• Col — 자식 요소를 세로로 배치한다. gap을 생략하면 문서 흐름에 맞춘 기본 간격을 적용한다.

• Row — 자식 요소를 가로로 배치하고 간격·정렬·줄바꿈을 지정한다.

• Box — 방향·여백·배경·테두리·크기를 지정하는 범용 컨테이너다.

• Grid — 자식 요소를 같은 너비의 열에 배치한다. 최소 자식 너비로 반응형 열 수를 조절한다.

• Card — 관련 콘텐츠를 테두리 또는 부드러운 배경의 패널로 묶는다.

• Carousel — 카드나 콘텐츠를 가로로 스크롤하고 항목 단위로 이동한다.

• Popover — 트리거를 눌렀을 때 추가 설명을 작은 패널로 표시한다.

• Divider — 콘텐츠 사이에 구분선을 표시한다.

• Spacer — Row 안의 남은 공간을 채워 요소 사이를 벌린다.

• Title — 제목이나 강조 숫자를 크기·색상과 함께 표시한다.

• Text — 일반 문장과 인라인 Markdown 서식을 표시한다.

• Caption — 작은 보조 설명을 표시한다.

• Label — 필드나 그룹의 이름을 표시한다.

• Badge — 상태나 짧은 사실을 색상·아이콘이 있는 태그로 표시한다.

• Link — HTTP(S) 링크를 새 탭에서 연다.

• List — 문자열 또는 ListItem을 글머리표·번호·타임라인으로 표시한다.

• ListItem — 제목·설명·사용자 지정 마커를 갖는 목록 항목이다.

• Markdown — 제목·목록·인용·코드·표가 있는 Markdown 본문을 표시한다.

• Quote — 인용 문장과 선택적 출처를 표시한다.

• Code — 복사 버튼이 있는 코드 블록을 표시한다.

• Math — LaTeX 수식을 블록 또는 인라인으로 표시한다.

• Button — 클릭 액션을 실행하는 버튼이다. 스타일·크기·아이콘·비활성 상태를 지정할 수 있다.

• IconButton — 접근성 라벨을 갖는 아이콘 버튼이다.

• Pressable — 임의의 콘텐츠를 클릭 가능한 선택 타일로 만든다.

• Input — 문자열 또는 숫자를 상태 변수에 바인딩하는 입력 컴포넌트다.

• TextArea — 여러 줄 문자열을 입력한다.

• Select — 긴 선택 목록에 적합한 드롭다운이다.

• SegmentedControl — 소수의 선택지를 나란히 배치한다.

• Slider — 최솟값·최댓값·간격을 지정해 숫자 상태를 조절한다.

• Checkbox — 불리언 상태를 변경하고 완료 시 취소선을 표시할 수 있다.

• RadioGroup — 하나의 항목을 목록·알약·카드 형태로 선택한다.

• DatePicker — YYYY-MM-DD 날짜 상태를 입력한다.

• Timer — 시작·일시 정지·초기화를 지원하는 카운트다운이다.

• Form — 입력을 묶고 ToAssistant로 제출할 때 폼 값을 함께 전달한다.

• SearchImage — 검색어로 사진을 찾는다. 외부 이미지 서비스의 응답에 의존한다.

• Image — 지정 URL의 이미지를 표시하고 실패 시 대체 검색을 시도한다.

• Icon — Lucide 이름으로 아이콘을 표시한다.

• Table — 열 이름과 행별 셀 배열로 표를 표시한다.

• Chart — 행 데이터로 막대·선·영역·원형·도넛·산점도 차트를 표시한다.

• Map — 마커에 맞춘 지도를 표시하고 경로·선택 상태를 연결할 수 있다.

• MapMarker — Map 안에서 이름·좌표·분류·아이콘을 갖는 장소를 정의한다.

• YouTube — 영상 ID 또는 URL로 YouTube를 임베드한다.

• Flashcard — 클릭하면 앞뒷면이 전환되는 학습 카드다.

• Celebration — 조건이 true가 될 때 축하 효과를 표시한다.

• Svg — 도형을 배치할 좌표계와 SVG 캔버스를 정의한다.

• Circle — 중심 좌표와 반지름으로 원을 그린다.

• Ellipse — 중심 좌표와 두 반지름으로 타원을 그린다.

• Rect — 위치·크기·모서리 반경으로 사각형을 그린다.

• Line — 두 좌표 사이에 선을 그린다.

• Path — SVG 경로 문자열로 곡선과 도형을 그린다.

• Polyline — 여러 좌표를 연결하는 꺾은선을 그린다.

• Polygon — 여러 좌표를 닫힌 다각형으로 연결한다.

• G — 도형을 그룹으로 묶어 이동·회전·투명도를 함께 적용한다.

• SvgText — SVG 좌표에 정렬·크기·색상을 지정한 글자를 표시한다.

• HtmlView — 샌드박스 iframe 안에서 HTML과 인라인 JavaScript를 실행한다.

Col

자식 요소를 세로로 배치한다. gap을 생략하면 문서 흐름에 맞춘 기본 간격을 적용한다.

호출 계약

Col(children: Node[], gap?: number, align?: "start" | "center" | "end" | "stretch")

이 항목의 예제는 Col 컴포넌트만 사용한다. 문자열을 각각 Col로 감싸 실제 요소 사이의 간격·정렬 차이를 보여준다.

예제 1. 기본 세로 흐름

root = Col([Col(["첫 번째 항목"]), Col(["두 번째 항목"]), Col(["세 번째 항목"])])

예제 2. 간격 4 = 16px

root = Col([Col(["첫 번째 항목"]), Col(["두 번째 항목"]), Col(["세 번째 항목"])], 4)

예제 3. 중첩과 정렬

root = Col([Col([Col(["안쪽 A"]), Col(["안쪽 B"])], 2), Col([Col(["안쪽 C"]), Col(["안쪽 D"])], 4)], 6, "center")

Row

자식 요소를 가로로 배치하고 간격·정렬·줄바꿈을 지정한다.

호출 계약

Row(children: Node[], gap?: number, align?: "start" | "center" | "end" | "stretch", justify?: "start" | "center" | "end" | "between", wrap?: boolean)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다.

예제 1. 기본 가로 배치

root = Col([Row([Text("왼쪽"), Text("가운데"), Text("오른쪽")], 4)])

예제 2. 양끝 정렬

root = Col([Row([Text("시작"), Text("끝")], 2, "center", "between", true)])

Box

방향·여백·배경·테두리·크기를 지정하는 범용 컨테이너다.

호출 계약

Box(children?: Node[], direction?: "row" | "col", gap?: number, padding?: number, background?: Color, radius?: Radius, border?: boolean, width?: Length, height?: Length, flex?: number, align?: "start" | "center" | "end" | "stretch", justify?: "start" | "center" | "end" | "between", wrap?: boolean)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다.

예제 1. 배경·테두리

root = Col([Box([Text("배경과 여백")], "col", 2, 4, "surface", "lg", true)])

예제 2. 가로 컨테이너

root = Col([Box([Text("가로 A"), Text("가로 B")], "row", 4, 6, "info", "xl")])

Grid

자식 요소를 같은 너비의 열에 배치한다. 최소 자식 너비로 반응형 열 수를 조절한다.

호출 계약

Grid(children: Node[], columns?: number, minChildWidth?: number, gap?: number)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다.

예제 1. 2열 그리드

root = Col([Grid([Card(["A"]), Card(["B"]), Card(["C"]), Card(["D"])], 2, 120, 4)])

예제 2. 반응형 최소 너비

root = Col([Grid([Card(["A"]), Card(["B"]), Card(["C"])], 3, 160, 2)])

Card

관련 콘텐츠를 테두리 또는 부드러운 배경의 패널로 묶는다.

호출 계약

Card(children: Node[], variant?: "outline" | "soft", padding?: number, gap?: number)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다.

예제 1. 테두리 카드

root = Col([Card([Text("기본 테두리 카드")])])

예제 2. 배경과 내부 간격

root = Col([Card([Text("부드러운 배경"), Text("여백 6")], "soft", 6, 3)])

Carousel

카드나 콘텐츠를 가로로 스크롤하고 항목 단위로 이동한다.

호출 계약

Carousel(children: Node[], itemWidth?: number, gap?: number)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다.

예제 1. 기본 사용 1

root = Col([Carousel([Card(["첫 카드"]), Card(["둘째 카드"]), Card(["셋째 카드"])], 200, 3)])

예제 2. 기본 사용 2

root = Col([Carousel([Card(["넓은 A"]), Card(["넓은 B"])], 320, 6)])

Popover

트리거를 눌렀을 때 추가 설명을 작은 패널로 표시한다.

호출 계약

Popover(trigger: string | Node[], content: string | Node[])

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다.

예제 1. 기본 사용 1

root = Col([Popover("눌러서 설명 보기", "접혀 있는 추가 설명입니다.")])

예제 2. 기본 사용 2

root = Col([Popover("용어: ROAS", "광고비 대비 광고 매출 비율")])

Divider

콘텐츠 사이에 구분선을 표시한다.

호출 계약

Divider()

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다.

예제 1. 기본 사용 1

root = Col([Col(["위쪽", Divider(), "아래쪽"])])

예제 2. 기본 사용 2

root = Col([Col([Divider(), "구분선 사이 콘텐츠", Divider()], 4)])

Spacer

Row 안의 남은 공간을 채워 요소 사이를 벌린다.

호출 계약

Spacer()

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다.

예제 1. 기본 사용 1

root = Col([Row(["왼쪽", Spacer(), "오른쪽"])])

예제 2. 기본 사용 2

root = Col([Row(["A", Spacer(), "B", Spacer(), "C"])])

Title

제목이나 강조 숫자를 크기·색상과 함께 표시한다.

호출 계약

Title(text: string, size?: "sm" | "md" | "lg" | "xl" | "2xl" | "3xl", color?: Color)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다.

예제 1. 기본 사용 1

root = Col([Title("페이지 제목", "lg")])

예제 2. 기본 사용 2

root = Col([Title("강조 숫자 1,234", "3xl", "info")])

Text

일반 문장과 인라인 Markdown 서식을 표시한다.

호출 계약

Text(text: string | Node[], size?: "xs" | "sm" | "md" | "lg", color?: Color, weight?: "normal" | "medium" | "semibold", italic?: boolean, lineThrough?: boolean, tabularNums?: boolean, maxLines?: number)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다.

예제 1. 기본 사용 1

root = Col([Text("일반 문장과 **강조**, *기울임*", "md")])

예제 2. 기본 사용 2

root = Col([Text("작고 흐린 안내", "sm", "muted")])

Caption

작은 보조 설명을 표시한다.

호출 계약

Caption(text: string, color?: Color)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다.

예제 1. 기본 사용 1

root = Col([Caption("보조 설명")])

예제 2. 기본 사용 2

root = Col([Caption("확인할 사항", "warning")])

Label

필드나 그룹의 이름을 표시한다.

호출 계약

Label(text: string)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다.

예제 1. 기본 사용 1

root = Col([Label("이름")])

예제 2. 기본 사용 2

root = Col([Label("선택할 항목")])

Badge

상태나 짧은 사실을 색상·아이콘이 있는 태그로 표시한다.

호출 계약

Badge(text: string, color?: "neutral" | "info" | "success" | "warning" | "danger" | "purple" | "pink", icon?: string)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다.

예제 1. 기본 사용 1

root = Col([Badge("완료", "success", "check")])

예제 2. 기본 사용 2

root = Col([Badge("검토 필요", "warning")])

Link

HTTP(S) 링크를 새 탭에서 연다.

호출 계약

Link(text: string, url: string)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다.

예제 1. 기본 사용 1

root = Col([Link("OpenUI", "https://www.openui.com")])

예제 2. 기본 사용 2

root = Col([Link("예시 사이트", "https://example.com")])

List

문자열 또는 ListItem을 글머리표·번호·타임라인으로 표시한다.

호출 계약

List(items: (string | ListItem)[], marker?: "bullet" | "number" | "none", timeline?: boolean)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다.

예제 1. 기본 사용 1

root = Col([List(["사과", "배", "우유"], "bullet")])

예제 2. 기본 사용 2

root = Col([List(["시작", "진행", "완료"], "number")])

ListItem

제목·설명·사용자 지정 마커를 갖는 목록 항목이다.

호출 계약

ListItem(title: string, description?: string, marker?: string, children?: Node[])

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다.

예제 1. 기본 사용 1

root = Col([List([ListItem("준비", "자료를 모읍니다", "1"), ListItem("실행", "결과를 확인합니다", "2")], "none", true)])

예제 2. 기본 사용 2

root = Col([List([ListItem("메모", "하나의 항목에 제목과 설명", "→")])])

Markdown

제목·목록·인용·코드·표가 있는 Markdown 본문을 표시한다.

호출 계약

Markdown(text: string)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다.

예제 1. 기본 사용 1

root = Col([Markdown("## 요약\n- 첫 항목\n- **강조** 항목")])

예제 2. 기본 사용 2

root = Col([Markdown("> 인용 문장\n\n본문과 `inline code`")])

Quote

인용 문장과 선택적 출처를 표시한다.

호출 계약

Quote(text: string, cite?: string)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다.

예제 1. 기본 사용 1

root = Col([Quote("작게 시작하고 직접 확인합니다.", "예시 문장")])

예제 2. 기본 사용 2

root = Col([Quote("출처를 생략한 인용")])

Code

복사 버튼이 있는 코드 블록을 표시한다.

호출 계약

Code(code: string, language?: string)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다.

예제 1. 기본 사용 1

root = Col([Code("const total = 3 + 4;", "javascript")])

예제 2. 기본 사용 2

root = Col([Code("print(3 + 4)", "python")])

Math

LaTeX 수식을 블록 또는 인라인으로 표시한다.

호출 계약

Math(tex: string, inline?: boolean)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다.

예제 1. 기본 사용 1

root = Col([Math("E = mc^2")])

예제 2. 기본 사용 2

root = Col([Math("a^2 + b^2 = c^2")])

Button

클릭 액션을 실행하는 버튼이다. 스타일·크기·아이콘·비활성 상태를 지정할 수 있다.

호출 계약

Button(label: string, action?: ActionExpression, variant?: "solid" | "outline" | "soft" | "ghost", color?: "primary" | "danger" | "success", size?: "sm" | "md" | "lg", icon?: string, disabled?: boolean, block?: boolean)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다.

예제 1. 클릭 카운터

root = Col([Button("증가", @Set($count, $count + 1)), Text("횟수: " + $count)])
$count = 0

예제 2. 버튼 스타일

root = Col([Button("외곽선", @Set($clicked, true), "outline"), Button("비활성", null, "soft", null, null, null, true), Text("클릭: " + $clicked)])
$clicked = false

IconButton

접근성 라벨을 갖는 아이콘 버튼이다.

호출 계약

IconButton(icon: string, action?: ActionExpression, label?: string, variant?: "outline" | "ghost" | "solid")

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다.

예제 1. 아이콘 카운터

root = Col([IconButton("plus", @Set($n, $n + 1), "하나 추가"), Text("수량: " + $n)])
$n = 0

예제 2. 초기화 버튼

root = Col([IconButton("rotate-ccw", @Set($n, 0), "초기화", "solid"), Input($n, "수량", "number")])
$n = 5

Pressable

임의의 콘텐츠를 클릭 가능한 선택 타일로 만든다.

호출 계약

Pressable(children: Node[], action?: ActionExpression, selected?: boolean, padding?: number, background?: Color, radius?: Radius)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다.

예제 1. 선택 타일

root = Col([Pressable(["클릭하여 선택"], @Set($on, !$on), $on, 4), Text("선택: " + $on)])
$on = false

예제 2. 배경 타일

root = Col([Pressable(["확인"], @Set($on, !$on), $on, 6, "info", "lg")])
$on = true

Input

문자열 또는 숫자를 상태 변수에 바인딩하는 입력 컴포넌트다.

호출 계약

Input(value: $binding<string | number>, label?: string, type?: "text" | "number", placeholder?: string)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다.

예제 1. 문자 입력

root = Col([Input($value, "이름", "text", "이름을 입력하세요"), Text("입력: " + $value)])
$value = "도도"

예제 2. 숫자 입력

root = Col([Input($value, "수량", "number"), Text("두 배: " + ($value * 2))])
$value = 3

TextArea

여러 줄 문자열을 입력한다.

호출 계약

TextArea(value: $binding<string>, label?: string, placeholder?: string, rows?: number)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다.

예제 1. 메모

root = Col([TextArea($value, "메모", "여기에 입력", 3), Text($value)])
$value = "첫 메모"

예제 2. 긴 입력

root = Col([TextArea($value, "초안", "자유롭게 작성", 6), Text($value)])
$value = ""

Select

긴 선택 목록에 적합한 드롭다운이다.

호출 계약

Select(value: $binding<string>, options: (string | {value: string, label: string})[], label?: string, placeholder?: string)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다.

예제 1. 문자열 옵션

root = Col([Select($value, ["서울", "부산", "제주"], "도시"), Text("선택: " + $value)])
$value = "서울"

예제 2. 값과 라벨

root = Col([Select($value, [{"value":"a","label":"기본"},{"value":"b","label":"확장"}], "요금제"), Text($value)])
$value = "a"

SegmentedControl

소수의 선택지를 나란히 배치한다.

호출 계약

SegmentedControl(value: $binding<string>, options: (string | {value: string, label: string})[], block?: boolean)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다.

예제 1. 보기 선택

root = Col([SegmentedControl($value, ["일", "주", "월"]), Text($value)])
$value = "주"

예제 2. 전체 너비

root = Col([SegmentedControl($value, ["개요", "상세"], true), Text($value)])
$value = "개요"

Slider

최솟값·최댓값·간격을 지정해 숫자 상태를 조절한다.

호출 계약

Slider(value: $binding<number>, min: number, max: number, step?: number, label?: string, unit?: string, marks?: {value: number, label: string}[])

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다.

예제 1. 비율 조절

root = Col([Slider($value, 0, 100, 5, "진행률", "%"), Text("값: " + $value)])
$value = 30

예제 2. 세밀한 조절

root = Col([Slider($value, 0, 1, 0.1, "혼합 비율"), Text("값: " + $value)])
$value = 0.5

Checkbox

불리언 상태를 변경하고 완료 시 취소선을 표시할 수 있다.

호출 계약

Checkbox(checked: $binding<boolean>, label: string, lineThrough?: boolean)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다.

예제 1. 기본 체크

root = Col([Checkbox($done, "확인했습니다"), Text("체크: " + $done)])
$done = false

예제 2. 완료 취소선

root = Col([Checkbox($done, "문서 읽기", true)])
$done = true

RadioGroup

하나의 항목을 목록·알약·카드 형태로 선택한다.

호출 계약

RadioGroup(value: $binding<string>, options: (string | {value: string, label: string, description?: string})[], label?: string, variant?: "list" | "pills" | "cards")

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다.

예제 1. 목록 선택

root = Col([RadioGroup($value, ["기본", "확장"], "플랜", "list"), Text($value)])
$value = "기본"

예제 2. 카드 선택

root = Col([RadioGroup($value, [{"value":"a","label":"입문","description":"작게 시작"},{"value":"b","label":"심화","description":"더 많은 기능"}], "학습", "cards"), Text($value)])
$value = "a"

DatePicker

YYYY-MM-DD 날짜 상태를 입력한다.

호출 계약

DatePicker(value: $binding<string>, label?: string, min?: string, max?: string)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다.

예제 1. 날짜 선택

root = Col([DatePicker($date, "일정"), Text($date)])
$date = "2026-10-25"

예제 2. 범위 제한

root = Col([DatePicker($date, "10월 일정", "2026-10-01", "2026-10-31"), Text($date)])
$date = "2026-10-15"

Timer

시작·일시 정지·초기화를 지원하는 카운트다운이다.

호출 계약

Timer(seconds: $binding<number>, label?: string)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다.

예제 1. 짧은 타이머

root = Col([Timer($seconds, "10초 타이머"), Text("남은 시간: " + $seconds)])
$seconds = 10

예제 2. 완료 메시지

root = Col([Timer($seconds, "카운트다운"), Text($seconds == 0 ? "완료!" : "진행 대기/진행 중")])
$seconds = 5

Form

입력을 묶고 ToAssistant로 제출할 때 폼 값을 함께 전달한다.

호출 계약

Form(children: Node[])

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다.

예제 1. 제출 이벤트

root = Col([Form([Input($name, "이름"), Button("제출", @ToAssistant("이 이름으로 인사해줘"))])])
$name = "도도"

예제 2. 선택 폼

root = Col([Form([Select($city, ["서울", "부산"], "도시"), Button("계획 요청", @ToAssistant("여행 계획을 만들어줘"))])])
$city = "서울"

SearchImage

검색어로 사진을 찾는다. 외부 이미지 서비스의 응답에 의존한다.

호출 계약

SearchImage(query: string, aspectRatio?: number, radius?: Radius, fit?: "cover" | "contain")

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다. 외부 지도·이미지·영상 서비스 연결이 필요할 수 있다.

예제 1. 기본 사용 1

root = Col([SearchImage("Lisbon Belem Tower", 1.5)])

예제 2. 기본 사용 2

root = Col([SearchImage("Golden Gate Bridge", 2, "lg")])

Image

지정 URL의 이미지를 표시하고 실패 시 대체 검색을 시도한다.

호출 계약

Image(src: string, alt: string, aspectRatio?: number, radius?: Radius, fit?: "cover" | "contain")

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다.

예제 1. 기본 사용 1

root = Col([Image("https://placehold.co/320x200/png?text=Example+1", "첫 번째 예시 이미지", 1, "lg", "contain")])

예제 2. 기본 사용 2

root = Col([Image("https://placehold.co/480x240/png?text=Example+2", "두 번째 예시 이미지", 2, "sm", "contain")])

Icon

Lucide 이름으로 아이콘을 표시한다.

호출 계약

Icon(name: string, size?: "sm" | "md" | "lg" | "xl", color?: Color)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다.

예제 1. 기본 사용 1

root = Col([Icon("map-pin", "xl", "info")])

예제 2. 기본 사용 2

root = Col([Icon("check", "lg", "success")])

Table

열 이름과 행별 셀 배열로 표를 표시한다.

호출 계약

Table(columns: string[], rows: any[][])

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다.

예제 1. 기본 사용 1

root = Col([Table(["품목", "수량"], [["사과", 3], ["우유", 2]])])

예제 2. 기본 사용 2

root = Col([Table(["상태", "설명"], [[Badge("완료", "success"), "검증 완료"], [Badge("대기"), "다음 작업"]])])

Chart

행 데이터로 막대·선·영역·원형·도넛·산점도 차트를 표시한다.

호출 계약

Chart(type: "bar" | "line" | "area" | "pie" | "donut" | "scatter", data: Record<string, string | number>[], x?: string, series?: string[], format?: "number" | "currency" | "percent", currency?: string, stacked?: boolean, height?: number)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다.

예제 1. 기본 사용 1

root = Col([Chart("bar", [{"label":"월","value":10},{"label":"화","value":20}], "label", ["value"])])

예제 2. 기본 사용 2

root = Col([Chart("line", [{"label":"월","value":10},{"label":"화","value":20},{"label":"수","value":15}], "label", ["value"])])

Map

마커에 맞춘 지도를 표시하고 경로·선택 상태를 연결할 수 있다.

호출 계약

Map(markers: MapMarker[], route?: boolean, selected?: $binding<string>, height?: number)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다. 외부 지도·이미지·영상 서비스 연결이 필요할 수 있다.

예제 1. 기본 사용 1

root = Col([Map([MapMarker("서울", 37.5665, 126.978)], false, null, 260)])

예제 2. 기본 사용 2

root = Col([Map([MapMarker("리스본", 38.7223, -9.1393), MapMarker("벨렝", 38.6979, -9.2067)], false, null, 280)])

MapMarker

Map 안에서 이름·좌표·분류·아이콘을 갖는 장소를 정의한다.

호출 계약

MapMarker(label: string, lat: number, lng: number, category?: string, icon?: string)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다. 외부 지도·이미지·영상 서비스 연결이 필요할 수 있다.

예제 1. 기본 사용 1

root = Col([Map([MapMarker("서울시청", 37.5665, 126.978, "관광", "🏛️")], false, null, 260)])

예제 2. 기본 사용 2

root = Col([Map([MapMarker("리스본", 38.7223, -9.1393, "도시", "📍")], false, null, 260)])

YouTube

영상 ID 또는 URL로 YouTube를 임베드한다.

호출 계약

YouTube(video: string, title?: string)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다. 외부 지도·이미지·영상 서비스 연결이 필요할 수 있다.

예제 1. 기본 사용 1

root = Col([YouTube("aqz-KE-bpKQ", "Big Buck Bunny")])

예제 2. 기본 사용 2

root = Col([YouTube("https://www.youtube.com/watch?v=aqz-KE-bpKQ", "URL로 영상 지정")])

Flashcard

클릭하면 앞뒷면이 전환되는 학습 카드다.

호출 계약

Flashcard(front: string | Node[], back: string | Node[], hint?: string)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다.

예제 1. 기본 사용 1

root = Col([Flashcard("사과의 영어는?", "Apple", "눌러서 정답 보기")])

예제 2. 기본 사용 2

root = Col([Flashcard("2 × 3", "6")])

Celebration

조건이 true가 될 때 축하 효과를 표시한다.

호출 계약

Celebration(when: boolean)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다.

예제 1. 클릭하여 축하

root = Col([Button("완료!", @Set($done, !$done)), Celebration($done), Text("완료: " + $done)])
$done = false

예제 2. 조건 충족

root = Col([Checkbox($done, "목표 달성"), Celebration($done)])
$done = false

Svg

도형을 배치할 좌표계와 SVG 캔버스를 정의한다.

호출 계약

Svg(children: Node[], viewBox: string, width?: Length, height?: Length)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다. SVG 도형은 부모 Svg 안에서 렌더링한다.

예제 1. 기본 사용 1

root = Col([Svg([Circle(80, 50, 30, "info")], "0 0 160 100", 320, 200)])

예제 2. 기본 사용 2

root = Col([Svg([Rect(20, 20, 120, 60, "surface", "info", 2), SvgText("도형", 80, 55, 18, "ink", "middle")], "0 0 160 100", 320, 200)])

Circle

중심 좌표와 반지름으로 원을 그린다.

호출 계약

Circle(cx: number, cy: number, r: number, fill?: Color, stroke?: Color, strokeWidth?: number, opacity?: number)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다. SVG 도형은 부모 Svg 안에서 렌더링한다.

예제 1. 기본 사용 1

root = Col([Svg([Circle(60, 50, 25, "info")], "0 0 160 100", 320, 200)])

예제 2. 기본 사용 2

root = Col([Svg([Circle(60, 50, 30, "surface", "danger", 3)], "0 0 160 100", 320, 200)])

Ellipse

중심 좌표와 두 반지름으로 타원을 그린다.

호출 계약

Ellipse(cx: number, cy: number, rx: number, ry: number, fill?: Color, stroke?: Color, strokeWidth?: number, opacity?: number)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다. SVG 도형은 부모 Svg 안에서 렌더링한다.

예제 1. 기본 사용 1

root = Col([Svg([Ellipse(80, 50, 55, 25, "success")], "0 0 160 100", 320, 200)])

예제 2. 기본 사용 2

root = Col([Svg([Ellipse(80, 50, 30, 40, "surface", "info", 3)], "0 0 160 100", 320, 200)])

Rect

위치·크기·모서리 반경으로 사각형을 그린다.

호출 계약

Rect(x: number, y: number, width: number, height: number, fill?: Color, stroke?: Color, strokeWidth?: number, opacity?: number, rx?: number)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다. SVG 도형은 부모 Svg 안에서 렌더링한다.

예제 1. 기본 사용 1

root = Col([Svg([Rect(20, 20, 100, 60, "info")], "0 0 160 100", 320, 200)])

예제 2. 기본 사용 2

root = Col([Svg([Rect(20, 20, 100, 60, "surface", "purple", 3, 1, 12)], "0 0 160 100", 320, 200)])

Line

두 좌표 사이에 선을 그린다.

호출 계약

Line(x1: number, y1: number, x2: number, y2: number, stroke?: Color, strokeWidth?: number, opacity?: number)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다. SVG 도형은 부모 Svg 안에서 렌더링한다.

예제 1. 기본 사용 1

root = Col([Svg([Line(20, 20, 140, 80, "info", 3)], "0 0 160 100", 320, 200)])

예제 2. 기본 사용 2

root = Col([Svg([Line(20, 50, 140, 50, "danger", 6)], "0 0 160 100", 320, 200)])

Path

SVG 경로 문자열로 곡선과 도형을 그린다.

호출 계약

Path(d: string, fill?: Color, stroke?: Color, strokeWidth?: number, opacity?: number)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다. SVG 도형은 부모 Svg 안에서 렌더링한다.

예제 1. 기본 사용 1

root = Col([Svg([Path("M20 80 Q80 0 140 80", "none", "info", 3)], "0 0 160 100", 320, 200)])

예제 2. 기본 사용 2

root = Col([Svg([Path("M20 20 L140 20 L80 80 Z", "success")], "0 0 160 100", 320, 200)])

Polyline

여러 좌표를 연결하는 꺾은선을 그린다.

호출 계약

Polyline(points: string, stroke?: Color, strokeWidth?: number, fill?: Color, opacity?: number)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다. SVG 도형은 부모 Svg 안에서 렌더링한다.

예제 1. 기본 사용 1

root = Col([Svg([Polyline("20,80 60,20 100,60 140,30", "info", 3)], "0 0 160 100", 320, 200)])

예제 2. 기본 사용 2

root = Col([Svg([Polyline("20,20 80,80 140,20", "danger", 4)], "0 0 160 100", 320, 200)])

Polygon

여러 좌표를 닫힌 다각형으로 연결한다.

호출 계약

Polygon(points: string, fill?: Color, stroke?: Color, strokeWidth?: number, opacity?: number)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다. SVG 도형은 부모 Svg 안에서 렌더링한다.

예제 1. 기본 사용 1

root = Col([Svg([Polygon("80,10 145,85 15,85", "warning")], "0 0 160 100", 320, 200)])

예제 2. 기본 사용 2

root = Col([Svg([Polygon("30,20 130,20 150,70 80,90 10,70", "info")], "0 0 160 100", 320, 200)])

G

도형을 그룹으로 묶어 이동·회전·투명도를 함께 적용한다.

호출 계약

G(children: Node[], transform?: string, opacity?: number)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다. SVG 도형은 부모 Svg 안에서 렌더링한다.

예제 1. 기본 사용 1

root = Col([Svg([G([Rect(0, 0, 60, 40, "info"), Circle(30, 20, 10, "surface")], "translate(40 30)")], "0 0 160 100", 320, 200)])

예제 2. 기본 사용 2

root = Col([Svg([G([Rect(40, 30, 60, 40, "purple")], "rotate(20 70 50)", 0.7)], "0 0 160 100", 320, 200)])

SvgText

SVG 좌표에 정렬·크기·색상을 지정한 글자를 표시한다.

호출 계약

SvgText(text: string, x: number, y: number, size?: number, fill?: Color, anchor?: "start" | "middle" | "end", weight?: "normal" | "medium" | "semibold")

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다. SVG 도형은 부모 Svg 안에서 렌더링한다.

예제 1. 기본 사용 1

root = Col([Svg([SvgText("Hello SVG", 80, 55, 20, "ink", "middle")], "0 0 160 100", 320, 200)])

예제 2. 기본 사용 2

root = Col([Svg([SvgText("가운데 정렬", 80, 55, 16, "info", "middle", "semibold")], "0 0 160 100", 320, 200)])

HtmlView

샌드박스 iframe 안에서 HTML과 인라인 JavaScript를 실행한다.

호출 계약

HtmlView(html: string, height?: number, title?: string)

대상 항목을 중심으로 구성하며, 결과를 표시하거나 상태를 확인하기 위한 보조 컴포넌트를 함께 사용한다.

예제 1. 기본 사용 1

root = Col([HtmlView("<h2>샌드박스 HTML</h2><p>독립된 HTML 콘텐츠입니다.</p>", 160, "HTML 예시")])

예제 2. 기본 사용 2

root = Col([HtmlView("<button onclick=\"this.textContent=Number(this.textContent)+1\">0</button>", 120, "HTML 카운터")])

확인할 사항

• 계약의 인자 순서와 타입을 확인한다. 숫자와 숫자 문자열은 같지 않다.
• 코드를 읽을 때 초기 상태, 이벤트 발생, 계산 결과, 화면 갱신을 순서대로 따라간다.
• 기대 결과와 다른 경우 해당 함수나 컴포넌트의 계약, 상태 연결, 호스트의 오류 처리를 확인한다.
• 예제는 학습용이다. 모든 호스트에서 자동 실행되거나 동일한 카탈로그가 설치돼 있다는 의미는 아니다.