요소

Native Shell의 모든 화면은 View, Text, Image 같은 기본 요소와 Button, Dialog, NavStack 같은 기본 컴포넌트로 구성됩니다. 각 기본 요소는 NSH 런타임이 생성하고 배치하는 네이티브 뷰입니다. iOS와 Mac Catalyst에서는 UIView의 하위 클래스, Android에서는 View, 데스크톱에서는 AppKit, GTK 또는 Win32 뷰를 사용합니다. 앱에서 사용하는 버튼, 카드, 행, 화면은 이 요소들로 만든 컴포넌트이며, 각각의 스타일과 앱 전체의 디자인은 앱에서 결정합니다.

예제는 Rust와 TSX로 제공합니다. 탭에서 언어를 고르면 같은 페이지에 있는 다른 예제에도 적용됩니다.

use nsh_core::prelude::*;

fn app() -> impl IntoElement {
    let count = signal(0_u32);
    view()
        .flex_1()
        .items_center()
        .justify_center()
        .gap_3()
        .child(text(move || format!("Tapped {} times", count.get())).text_2xl())
        .child(
            view()
                .rounded_lg()
                .bg(rgb(0x2563eb))
                .px_4()
                .py_2()
                .active(|s| s.opacity(0.6))
                .on_press(move || count.update(|n| *n += 1))
                .child(text("Tap").text_color(white())),
        )
}

import { mount, signal, Text, View } from "nsh";

function App() {
  const count = signal(0);
  return (
    <View style={{ flex: 1, alignItems: "center", justifyContent: "center", gap: 12 }}>
      <Text style={{ fontSize: 24 }}>Tapped {count()} times</Text>
      <View onPress={() => count.update((n) => n + 1)} class="rounded-lg bg-blue-600 px-4 py-2 active:opacity-60">
        <Text class="text-white">Tap</Text>
      </View>
    </View>
  );
}

mount(App);

Rust의 기본 요소는 nsh_core::prelude의 함수(view(), text(..), image(..))이며, 기본 컴포넌트는 nsh_base 크레이트에서 가져옵니다. 스타일은 타입이 있는 메서드(.flex_1(), .gap_3(), .px(px(20.0)), .bg(..))로 지정하고, 상태별 스타일에는 클로저(.active(|s| s.opacity(0.6)))를 전달합니다. 이벤트 리스너도 클로저(.on_press(move || ..), .on_change(move |text: &str| ..))이며, 자식은 .child(..)로 추가합니다. UI를 구성하는 일반 함수는 한 번 실행되어 impl IntoElement를 반환합니다. text(move || ..), .bg(move || ..) 등의 클로저 안에서 읽은 시그널이 바뀌면 해당 바인딩이 갱신됩니다. Rust로 앱 작성하기를 참고하세요.

TSX 태그는 PascalCase로 작성하며 현재 범위에 있는 이름을 참조합니다. 기본 요소는 nsh에서, 기본 컴포넌트는 nsh/base에서 가져옵니다. 전역인 <If>와 <Each>만 가져오기 없이 쓸 수 있습니다. <view>처럼 소문자로 작성하면 빌드 오류가 발생합니다. 소문자 태그를 허용하면 TypeScript가 태그 이름마다 하나의 전역 타입을 사용하게 되어 List와 Each 같은 제네릭 컴포넌트에서 항목 타입을 추론할 수 없기 때문입니다. 컴파일러는 가져온 요소를 식별하고 사용 위치에 네이티브 뷰를 생성하므로 가져오기에 따른 런타임 비용은 없습니다. JSX와 컴포넌트에서 더 알아볼 수 있습니다.

import { Canvas, Image, List, Overlay, Scroll, Shader, Text, Video, View, WebView } from "nsh";
import { Button, Dialog, Menu, NavPage, NavStack, Popover, Sheet, Tooltip, Input } from "nsh/base";

#기본 요소

TSX에서는 nsh에서, Rust에서는 nsh_core::prelude에서 가져옵니다.

패딩과 마진에 CSS의 env()를 사용하면 시스템 UI가 콘텐츠를 가리지 않도록 여백을 확보할 수 있습니다. 가장자리의 안전 영역에는 env(safe-area-inset-top) 등 방향별 변수를, 키보드에는 env(keyboard-inset-height)를 사용합니다.

#기본 컴포넌트

TSX에서는 nsh/base에서, Rust에서는 nsh_base 크레이트에서 가져옵니다. 각 컴포넌트가 동작, 상태, 포커스, 접근성을 처리하고 앱에서 모양을 지정합니다.

#공통 속성

모든 기본 요소는 다음 속성을 받습니다. TSX에서는 CommonProps 타입에, Rust에서는 Styled, Interactive, Accessible 트레이트에 정의되어 있습니다. 각 요소의 개별 문서에서는 그 요소만의 속성을 설명합니다. 표의 Rust 열에는 빌더 메서드를 표시했습니다.

#스타일 지정

#누르기와 피드백

누르기는 네이티브에서 처리합니다. 플랫폼이 누르기를 인식하고 앱이 지정한 스타일을 적용한 뒤 앱 코드에 이벤트를 전달합니다. 누를 수 있는 뷰가 중첩되어 있으면 가장 안쪽 뷰만 반응합니다. 스크롤 뷰 안에서는 스크롤이 먼저 시작될 수 있도록 누름 시작 처리를 약 130ms 늦춥니다.

PressEvent는 { position, pagePosition, modifiers, clickCount }로 구성됩니다. 차례대로 뷰와 루트 뷰 기준 포인터 위치(Point), 누르기 시작 시점에 눌린 보조 키, 연속 클릭 수(더블 클릭은 2)입니다. 플랫폼이 포인터 위치를 제공하지 않으면 뷰의 원점, 보조 키 없음, 클릭 1회로 전달됩니다.

스타일 속성 pointerEvents(Rust에서는 .pointer_events(PointerEvents::BoxNone), 클래스는 pointer-events-*)는 뷰와 자식 뷰 중 어디에서 터치를 받을지 결정합니다. "none"이면 둘 다 받지 않지만 하위 뷰가 "auto"를 지정하면 그 뷰는 다시 받습니다. "box-none"은 자식만, "box-only"는 뷰 자신만 받습니다. 터치와 제스처를 참고하세요.

눌렀을 때의 모양은 앱이 정합니다. 뷰를 누르고 있는 동안 플랫폼이 activeStyle(또는 active: 클래스, Rust의 .active(..))을 직접 적용하므로 앱 코드를 거칠 필요가 없습니다.

#상태별 스타일

뷰가 특정 상태일 때 네이티브에서 해당 스타일을 뷰 자체의 스타일 위에 적용합니다. 각 속성은 Tailwind 변형을 객체로 표현한 것입니다. selected, checked·indeterminate, hover, focus, active 순으로 뒤에 오는 상태가 우선합니다. 비활성화된 동안에는 disabledStyle이 가장 우선하며 다른 상태 스타일을 적용하지 않습니다. 속성값은 요소에 맞는 스타일 타입을 사용합니다. <Text>는 TextStyle, <Input>은 InputStyle, <Image>는 ImageStyle, 그 밖에는 ViewStyle입니다.

view()
    .rounded_lg()
    .bg(rgb(0x2563eb))
    .px_4()
    .py_2()
    .active(|s| s.opacity(0.6))
    .hover(|s| s.bg(rgb(0x1d4ed8)))
    .on_press(save)
    .child(text("Save").text_color(white()))

<View onPress={save} activeStyle={{ opacity: 0.6 }} hoverStyle={{ backgroundColor: "#1d4ed8" }} class="rounded-lg bg-blue-600 px-4 py-2">
  <Text class="text-white">Save</Text>
</View>

#호버

앱은 포인터가 뷰에 들어오고, 그 위를 움직이고, 벗어났을 때 이벤트를 받습니다. macOS, Windows, Linux, GPUI 백엔드, 데스크톱 브라우저뿐 아니라 iPad의 포인터나 Mac의 마우스를 사용하는 iOS 환경, 마우스나 스타일러스를 사용하는 Android 환경에서도 지원합니다. 같은 환경에서 hover:, .hover(..)로 포인터가 올라간 뷰의 스타일을 지정할 수 있습니다.

CSS의 :hover나 DOM의 mouseenter와 마찬가지로 마우스가 뷰 자체 또는 그 안의 요소 위에 있으면 해당 뷰에 호버한 상태입니다. 따라서 포인터 바로 아래의 뷰뿐 아니라 이를 감싸는 뷰도 바깥쪽부터 안쪽 순으로 onMouseEnter를 받습니다. onMouseLeave는 반대 순서입니다. 두 이벤트는 상태가 바뀐 뒤에 전달되며 터치로 발생하지 않습니다. 마우스 아래 있던 뷰를 제거해도 onMouseLeave가 발생합니다. Linux와 Windows에서는 다음에 마우스가 움직일 때 전달됩니다.

MouseEvent는 GPUI의 MouseMoveEvent처럼 마우스 위치를 알려 줍니다. position은 뷰의 변환을 역으로 적용한 로컬 좌표(포인트 단위의 Point), pagePosition은 터치 이벤트와 같은 루트 뷰 기준 좌표입니다. modifiers에는 누르고 있는 보조 키(control, alt, shift, platform)가 담깁니다. platform은 Apple에서는 Command 키, 다른 플랫폼에서는 Windows 키입니다. pressedButton은 현재 누른 버튼("left", "right", "middle", "back", "forward", GPUI의 MouseButton) 또는 null입니다. Rust 필드명은 position, page_position, modifiers, pressed_button입니다. 데스크톱과 웹의 드래그는 터치(onTouchMove, 리스폰더)로도 처리되며 pressedButton이 설정된 onMouseMove도 발생합니다. 단순 호버 피드백을 그릴 때는 버튼을 누른 이동 이벤트를 건너뛰세요. iOS와 Android의 호버는 버튼을 누르지 않은 포인터를 보고합니다. 이동은 프레임당 최대 한 번, 마지막 위치만 전달하며 뒤따르는 onMouseLeave보다 먼저 전달하므로 이동할 때마다 핸들러에서 다시 그릴 수 있습니다.

// A crosshair over a chart.
let at = signal(None::<Points>);

view()
    .h(px(200.0))
    .on_mouse_move(move |e: &MouseEvent| at.set(Some(e.position.x)))
    .on_mouse_leave(move |_: &MouseEvent| at.set(None))
    .child(when(move || at.get().is_some(), move || {
        view()
            .absolute()
            .left(move || at.get().unwrap_or_default())
            .top_0()
            .bottom_0()
            .w(px(1.0))
            .bg(rgb(0x888888))
    }))

// A crosshair over a chart.
const at = signal<number | null>(null);

<View onMouseMove={(e) => at.set(e.position.x)} onMouseLeave={() => at.set(null)} style={{ height: 200 }}>
  <If when={at() !== null}>
    <View style={{ position: "absolute", left: at()!, top: 0, bottom: 0, width: 1, backgroundColor: "#888" }} />
  </If>
</View>

#툴팁

모든 요소에 tooltip으로 도움말을 지정할 수 있습니다. 데스크톱(macOS, Windows, Linux, GPUI 백엔드, 데스크톱 브라우저)에서는 포인터가 요소 위에 0.5초 머물면 위쪽에 나타나며, 포인터가 떠나거나 요소를 누르면 사라집니다. 휴대폰과 태블릿에서는 표시되지 않습니다. 툴팁은 포인터나 누르기 이벤트를 가로채지 않으므로 요소를 그대로 조작할 수 있습니다.

view()
    .on_press(save)
    .tooltip(
        tooltip()
            .rounded_md()
            .bg(rgb(0x111827))
            .px_2()
            .py_1()
            .child(text("Save the document").text_color(white())),
    )
    .child(text("💾"))

<View
  onPress={save}
  tooltip={
    <Tooltip class="rounded-md bg-gray-900 px-2 py-1">
      <Text class="text-white">Save the document</Text>
    </Tooltip>
  }
>
  <Text>💾</Text>
</View>

GPUI의 .tooltip(..)에 툴팁을 전달하듯 Tooltip 자체에서 모양, 위치, 지연 시간, 이벤트를 지정합니다. 툴팁을 여럿 쓸 때는 앱에서 텍스트를 Tooltip으로 감싸는 작은 컴포넌트를 만들어 재사용하세요.

#컨텍스트 메뉴

onContextMenu는 뷰 위에서 보조 버튼을 눌렀을 때 발생합니다. 오른쪽 클릭, macOS의 Control-클릭, 터치패드의 두 손가락 클릭, iPad 포인터의 보조 클릭, 브라우저에서 키보드의 메뉴 키를 누르는 경우가 해당합니다. 이 위치에 앱 자체 메뉴를 열 수 있고, TSX에서는 Menu.popup으로 시스템 메뉴를 열 수 있습니다.

// The app's own menu, placed where the click was.
let menu_at = signal(None::<Point<Points>>);

view()
    .on_context_menu(move |e: &ContextMenuEvent| menu_at.set(Some(e.page_position)))
    .child(text(row.name.clone()))

import { Menu } from "nsh/desktop";

<View onContextMenu={(e) => Menu.popup(rowMenu(row), e.pagePosition)}>…</View>

ContextMenuEvent에는 뷰 안의 좌표 position, 루트 뷰 기준 좌표 pagePosition, 보조 키 modifiers가 있습니다. Rust에서는 position, page_position, modifiers입니다. Menu.popup(items, e.pagePosition)은 루트 좌표에 메뉴를 표시합니다. 포인터 아래의 뷰에서 바깥쪽으로 올라가며 이벤트를 수신하는 가장 가까운 뷰가 이를 받습니다. 그보다 안쪽에 텍스트 입력란이 있거나 편집 메뉴를 가진 선택 가능 텍스트(Windows, GPUI 백엔드, 브라우저)가 있으면 자체 메뉴를 표시합니다. 플랫폼이 버튼을 누르는 시점에 현재 마운트된 뷰를 보고 결정하므로 핸들러에서는 결과를 통지받기만 하며 기본 동작을 취소할 필요가 없습니다. disabled 상태인 뷰는 가장 가까운 활성 상위 리스너에 클릭을 넘깁니다. 터치스크린에서는 길게 눌러 메뉴를 열므로 같은 함수를 onLongPress에도 연결하세요.

#키보드 포커스

macOS와 웹에서 Tab을 누르면 트리 순서에 따라 입력란, 누를 수 있는 뷰, focusable 뷰로 키보드 포커스가 이동합니다. 현재 뷰에는 focus: 또는 .focus(..) 스타일이 적용되고, 해당 뷰를 누를 수 있다면 Return이나 Space로 누릅니다. 마우스로 클릭하면 포커스를 옮기지 않고 누르기만 하므로 포커스 스타일은 키보드 포커스에만 나타납니다.

포커스와 누르기는 독립적으로 처리됩니다. 차트, 슬라이더, 방향키로 선택을 이동하는 목록처럼 포커스를 가졌을 때 키를 처리하는 뷰는 focusable을 설정하고 포커스를 유지하는 동안에만 키를 바인딩합니다(onFocus, onBlur와 keymap 사용). 그 뷰를 누르면 페이지를 여는 카드처럼 주변에서 누르기를 처리하는 뷰에 이벤트가 전달됩니다.

ref의 focus()는 Tab처럼 포커스를 이동하고 포커스 스타일과 onFocus를 활성화합니다. 예를 들어 팝업을 닫았을 때 원래 팝업을 연 요소에 포커스를 돌려줄 수 있습니다. blur()는 포커스를 해제합니다.

focus-within:(focusWithinStyle, .focus_within(..))은 뷰 자신이나 그 안의 뷰에 포커스가 있을 때 적용됩니다. 편집 중인 입력란의 테두리나 버튼에 포커스가 있는 도구 모음의 스타일을 지정할 때 쓸 수 있습니다. Overlay의 내용은 표시 위치에 상관없이 오버레이가 속한 뷰 안에 있는 것으로 처리됩니다. 따라서 팝업도 이를 여는 요소가 속한 뷰의 일부입니다. Rust 컴포넌트에서는 요소의 ref에서 on_focus_in(..), on_focus_out(..)으로 포커스가 경계를 넘나드는 시점을 감지합니다. 내부 뷰 사이에서만 이동할 때는 둘 다 발생하지 않습니다.

view()
    .rounded_lg()
    .p_3()
    .focus(|s| s.bg(rgb(0xe0f2fe)))
    .on_press(open)
    .child(text("Open"))

// An overlay's backdrop: a click closes it, Tab goes past it to the content.
view().absolute().inset_0().focusable(false).on_press(close)

// A chart in a card: Tab stops at the chart, a click opens the card's page.
view().on_press(open_page).child(
    view()
        .h(px(160.0))
        .focusable(true)
        .focus(|s| s.bg(rgb(0xe0f2fe)))
        .on_focus(move || focused.set(true))
        .on_blur(move || focused.set(false)),
)

<View class="rounded-lg p-3 focus:bg-sky-100" onPress={open}>
  <Text>Open</Text>
</View>

{/* An overlay's backdrop: a click closes it, Tab goes past it to the content. */}
<View class="absolute inset-0" focusable={false} onPress={close} />

{/* A chart in a card: Tab stops at the chart, a click opens the card's page. */}
<View onPress={openPage}>
  <View
    class="h-40 focus:bg-sky-100"
    focusable
    onFocus={() => focused.set(true)}
    onBlur={() => focused.set(false)}
  />
</View>

#레이아웃과 식별자

#제스처로 애니메이션 값 제어

다음 속성은 제스처를 UI 스레드에서 움직이는 네이티브 애니메이션 값에 연결합니다. 앱 코드가 매 프레임 값을 갱신할 필요가 없습니다. 터치와 제스처를 참고하세요.

PanEvent는 { cancelled, translation, velocity, value? } 형태입니다. Rust에서는 cancelled, translation, velocity_x, velocity_y, value_x, value_y입니다. 시스템이 드래그를 취소했는지, 시작점 기준 변위와 초당 포인트 단위의 속도(Point), 그 순간 연결된 애니메이션 값(pan에 연결한 축별 { x?, y? })을 알려 줍니다. 애니메이션이 진행되는 중에도 드래그로 값을 이어받을 수 있습니다.

#터치와 리스폰더 시스템

위 속성으로 처리하기 어려운 제스처에는 모든 요소가 지원하는 터치·리스폰더 속성을 사용하세요. onTouchStart, onTouchMove, onTouchEnd, onTouchCancel 및 이들의 …Capture 형식, onStartShouldSetResponder, onMoveShouldSetResponder 및 …Capture 형식, onResponderGrant, onResponderReject, onResponderStart, onResponderMove, onResponderEnd, onResponderRelease, onResponderTerminate, onResponderTerminationRequest가 있습니다. 각 핸들러는 GestureResponderEvent({ identifier, locationX, locationY, pageX, pageY, target, timestamp, touches, changedTouches, nativeEvent, stopPropagation() })를 받으며 …ShouldSetResponder 핸들러에는 gestureState(dx, dy, vx, vy 등)도 전달됩니다. onResponderGrant에서 true를 반환하면 네이티브 스크롤 뷰가 터치를 가져가지 않습니다. panActivation({ activeOffsetX, activeOffsetY, failOffsetX, failOffsetY })을 설정하면 플랫폼이 팬 제스처를 활성화한 뒤에야 뷰가 리스폰더가 됩니다. 그래서 스크롤 뷰 안에서 드래그할 때 다른 축의 움직임은 스크롤 뷰에 맡길 수 있습니다(스크롤 뷰 안의 팬). PanResponder는 이 시스템을 기반으로 합니다. Rust에서는 .on_touch(..)가 모든 터치(TouchEvent)를 받고 .claim_touches(..)가 뷰가 터치를 맡을 시점을 결정합니다. 이후에는 .on_responder_grant(..), .on_responder_move(..), .on_responder_release(..) 등이 리스폰더의 상태를 따라 호출됩니다.

#접근성

접근성을 참고하세요.

#플랫폼 전용 속성

TSX에서는 한 플랫폼에만 있는 속성을 해당 플랫폼 이름의 객체에 넣습니다. 공통 속성은 모든 플랫폼에서 동일하고 현재 플랫폼의 객체만 전달됩니다. Rust 빌더에서는 각 플랫폼에서만 적용되는 메서드를 사용합니다.

use nsh_core::Ripple;

view()
    .rounded_lg()
    .bg(white())
    .p_4()
    .elevation(px(2.0))
    .ripple(Ripple { color: Some(rgba(0x00000022).into()), ..Ripple::default() })
    .on_press(save)
    .child(text("Save"))

<View onPress={save} android={{ ripple: { color: "#00000022" }, elevation: 2 }} class="rounded-lg bg-white p-4">
  <Text>Save</Text>
</View>

플랫폼별 코드를 참고하세요.

#ref 메서드

TSX에서 ref는 해당 요소 고유 타입의 참조를 받습니다. View, Text, Image, Canvas, Overlay, Shader는 focus, blur, measure를 갖는 ViewRef를 사용합니다. 그 밖의 요소는 ViewRef를 확장한 타입으로 전용 메서드를 제공합니다. Input은 InputRef, Scroll은 ScrollRef, List는 ListRef, WebView는 WebViewRef, Video는 VideoRef, 네이티브 컴포넌트는 NativeComponentRef입니다. Rust의 element_ref()는 .element_ref(&handle)로 연결하는 ElementRef 핸들을 만듭니다. ref 메서드로 보낸 명령은 같은 실행 차례에서 앞서 발생한 변경에 이어 순서대로 네이티브 뷰에 전달됩니다. 각 요소의 문서에서 지원 메서드를 확인하세요. ref 변수에는 요소 고유의 타입을 지정해야 합니다(<Input>이라면 let field!: InputRef). 고유 메서드가 있는 요소의 ref를 ViewRef 타입 변수에 연결할 수 없습니다.

let field = element_ref();

view()
    .on_press(move || field.focus())
    .child(input().element_ref(&field).placeholder("Tap the row to type"))

import { type InputRef, View } from "nsh";
import { Input } from "nsh/base";

let input!: InputRef;
<View onPress={() => input.focus()}>
  <Input ref={input} placeholder="Tap the row to type" />
</View>;

#핸들러가 UI를 차단하지 않는 이유

메인 스레드는 앱 코드의 실행이 끝나기를 기다리지 않습니다. 시스템이 즉시 답을 요구하면(텍스트를 바꿀 수 있는지, 뒤로 가기 버튼으로 화면을 닫을 수 있는지, 시트를 닫아도 되는지 등) NSH가 미리 설정한 maxLength, popOnBack, closeOnSwipe 등의 속성을 기준으로 네이티브에서 판단하고 이후에 이벤트를 앱에 전달합니다. 이런 동작을 핸들러의 반환값 대신 속성으로 지정하는 이유입니다.