OpenUI Lang — 액션 사용 사례 1개

총 1개 항목 · 2개 예제를 설명한다. 각 항목은 한국어 설명, 위치 기반 호출 계약, 완성된 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 같은 내장 기능과 본문에서 설명하는 사용자 정의 항목은 구별한다.

액션 계약과 실행 주체

이 문서의 사용자 정의 액션은 CopyToClipboard 하나다. @Set은 상태 변경, @ToAssistant는 후속 대화 요청, @OpenUrl은 주소 열기에 쓰는 내장 액션이며 이 사용자 정의 목록과 별개다.

DSL은 복사 요청을 표현하고 호스트가 브라우저 API로 실제 복사를 수행한다. 호출식이 존재하는 것만으로 클립보드가 자동 구현되지는 않는다. 호스트는 아래처럼 액션 이름과 인자를 받아 처리할 수 있다. 코드는 다른 프로젝트 파일을 가져오지 않는 JavaScript 예시다.

async function handleAction(event) {
  if (event.type !== "CopyToClipboard") return false;
  const text = event.params?.text;
  if (typeof text !== "string") {
    return { ok: false, message: "복사할 문자열이 필요합니다." };
  }
  try {
    await navigator.clipboard.writeText(text);
    return { ok: true, message: "복사했습니다." };
  } catch {
    return { ok: false, message: "복사 권한이나 브라우저 실행 환경을 확인하세요." };
  }
}

// 호스트는 렌더러의 액션 콜백에 handleAction을 연결한다.
// 아래는 콜백에 전달되는 이벤트의 핵심 필드 예시다.
const copyEvent = {
  type: "CopyToClipboard",
  params: { text: "Hello Intelligent UI" }
};

navigator.clipboard는 브라우저 환경과 권한에 영향을 받으며 보통 HTTPS 같은 보안 컨텍스트가 필요하다. 사용자 클릭에서 호출하고, 성공 여부를 확인해 알림을 표시한다. 이 예시는 문서 설명용이며, 문서를 읽는 것만으로 사용자 클립보드에 접근하거나 코드가 실행되지는 않는다.

전체 목차

• CopyToClipboard — 클릭한 시점에 지정한 문자열을 브라우저 클립보드에 복사한다.

CopyToClipboard

클릭한 시점에 지정한 문자열을 브라우저 클립보드에 복사한다.

호출 계약

CopyToClipboard(text: string)

버튼 클릭 시 호스트에 CopyToClipboard 이벤트를 전달한다. 호스트는 text를 읽어 복사하고 성공·실패 결과를 사용자에게 알리는 책임을 갖는다.

예제 1. 고정 문장 복사

root = Col([Button("문장 복사", @CopyToClipboard("Hello Intelligent UI"))])

동작 순서: 버튼을 클릭하면 text가 "Hello Intelligent UI"인 복사 이벤트가 발생한다. 호스트 처리에 성공하면 클립보드에 같은 문자열이 들어간다. 붙여넣기로 내용을 확인할 수 있다.

예제 2. 입력한 내용 복사

root = Col([Input($text, "복사할 내용"), Button("입력 복사", @CopyToClipboard($text))])
$text = "사과, 우유, 빵"

동작 순서: 처음에는 입력에 "사과, 우유, 빵"이 표시된다. 입력을 바꾸면 $text가 갱신되고, 복사 버튼을 누른 시점의 문자열을 복사 이벤트로 전달한다. 빈 문자열도 문자열이며 그대로 복사할 수 있다.

확인할 사항

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