要素

Native Shell は、すべての画面を少数の要素から構築します。View、Text、Image などのプリミティブと、Button、Dialog、NavStack などのベースコンポーネントです。各プリミティブはネイティブビューです（iOS と Mac Catalyst では UIView のサブクラス、Android では View、デスクトップでは AppKit、GTK、Win32 のビュー）。ビューの作成とレイアウトは NSH ランタイムが行います。アプリが表示するものはすべてこれらで構成されます。アプリのボタン、カード、行、画面はアプリ自身のコンポーネントであり、これらの要素で描画され、アプリがスタイルを定めるため、見た目は完全にアプリ独自のものになります。

このページのすべての例は 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 || ..)）で読み取られたシグナルは、バインドされた対象を更新します。Building with Rust を参照してください。

TSX では、すべてのタグは PascalCase で、スコープ内のバインディングの名前になります。プリミティブは nsh から、ベースコンポーネントは nsh/base から提供されます。インポートが不要なグローバルは <If> と <Each> だけです。<view> のような小文字のタグはビルドエラーになります。TypeScript が名前ごとに 1 つのグローバル型に照らして検査することになり、List や Each のようなジェネリックコンポーネントはアイテムの型を推論できないためです。コンパイラはインポートを通じて要素を認識し、ネイティブビューをその場で生成するため、インポートに実行時のコストはかかりません。JSX and components を参照してください。

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) とその他の辺（Safe area）、および env(keyboard-inset-height)（Keyboard）が使えます。

#ベース

TSX では nsh/base から、Rust では nsh_base クレートからインポートします。これらは動作、状態、フォーカス、アクセシビリティを担い、見た目はアプリから与えられます。

#共通プロパティ

すべてのプリミティブは、以下のプロパティを受け付けます（TSX では CommonProps 型、Rust では Styled、Interactive、Accessible トレイト）。各要素のページには、その要素固有のプロパティのみを記載しています。Rust の列にはビルダーメソッドを示しています。

#スタイリング

#押下とフィードバック

押下の処理はネイティブに実行されます。プラットフォームが押下を認識してアプリの押下スタイルを適用し、アプリのコードには事後に通知されるだけです。反応するのは最も内側の押下可能なビューだけです。スクロールビュー内では、スクロールを先に開始できるよう、押下の開始が約 130 ms 待機されます。

PressEvent は { position, pagePosition, modifiers, clickCount } です。ビュー内とそのルートビュー内（Point）でのポインターの位置、押下の開始時に押されていた修飾キー、連続クリック数（ダブルクリックなら 2）を含みます。プラットフォームがポインターを報告しない場合は、ビューの原点、キーなし、クリック 1 回になります。

スタイルキー pointerEvents（Rust では .pointer_events(PointerEvents::BoxNone)、クラスでは pointer-events-*）は、そのビューとその内部のビューがどのタッチを受け取るかを決めます。"none" はどちらも受け取らず（内部で "auto" を設定したビューは再び受け取ります）、"box-none" は内部のビューのみ、"box-only" はビュー自身のみが受け取ります（touch and gestures）。

押下フィードバックはアプリ側で定義します。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>

#Hover

アプリは、マウスがビューの上に来たこと、ビューの上を動いたこと、ビューから離れたことを受け取れます。対応するのは、macOS、Windows、Linux、GPUI バックエンド、デスクトップブラウザー、iOS での iPad のポインターまたは Mac のマウス、Android でのマウスまたはスタイラスです。ホバースタイル(hover:、.hover(..))は、同じ環境でホバーされたビューにスタイルを適用します。

CSS の :hover や DOM の mouseenter と同様に、マウスがビューの上、またはビュー内の何かの上にある間、そのビューはホバーされているものとして扱われます。そのため、マウスの真下にあるビューの周囲のビューにも onMouseEnter が届きます(外側から内側の順。onMouseLeave は内側から外側の順)。イベントは事後に届き、タッチでは発生しません。マウスの下から取り除かれたビューには onMouseLeave が届きます。Linux と Windows では、次にマウスが動いたときです。

MouseEvent は、GPUI の MouseMoveEvent と同様にマウスの位置を表します。ビュー内での position(ポイント単位の Point。変換は打ち消されています)、属するルートビュー内での pagePosition(タッチと同じ形式)、押されている modifiers(control、alt、shift、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 では、ホバーはボタンが押されていないポインターを報告します。移動イベントは 1 フレームにつき最大 1 回、最新のものだけが届き、後に続く 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>

#Tooltips

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>

Tooltip は、GPUI の .tooltip(..) がそうであるように、見た目、配置、遅延、イベントを自分で設定します。ツールチップを多く使うアプリでは、テキストを Tooltip で包む小さな独自コンポーネントを 1 つ用意しておくとよいでしょう。

#Context menus

onContextMenu は、ビューの上でセカンダリボタンが押されたことを伝えます。右クリック、macOS での Control-click、タッチパッドでの 2 本指クリック、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(Menu.popup がメニューを配置する基準:Menu.popup(items, e.pagePosition))、そして modifiers が含まれます。Rust では position、page_position、modifiers です。リスナーを持つ最も近いビュー(ポインターの下のビューから外側へ向かって探します)がイベントを受け取ります。そのビューよりも近くにテキスト入力、または編集メニューを持つ選択可能なテキスト(Windows、GPUI バックエンド、ブラウザー)がある場合は、代わりにそちらが独自のメニューを表示します。これはボタンが押された時点で、マウントされているものをもとにプラットフォームが判断します。そのためハンドラーには事後に通知され、何かをキャンセルする必要はありません。disabled のビューは、クリックを周囲にある最も近い有効なリスナーに任せます。タッチスクリーンでは長押しでメニューが開くので、同じ関数で onLongPress を処理してください。

#Keyboard focus

macOS とウェブでは、Tab キーでキーボードフォーカスがツリー順にストップ間を移動します。ストップとなるのは、入力、押下を受け取るビュー、そしてすべての focusable ビューです。フォーカススタイル(focus:、.focus(..))はフォーカスされたビューにスタイルを適用し、押下を受け取るビューでは Return または Space でそのビューが押されます。クリックはビューにフォーカスを移さずに押下するため、フォーカススタイルが表示されるのはキーボードフォーカスのときだけです。

フォーカスと押下は別のものです。フォーカスがある間にキーを受け取るビュー(チャート、スライダー、矢印キーで選択を移動するリストなど)は、focusable を設定し、フォーカス中のキーをバインドします(keymap と組み合わせた onFocus / onBlur)。そのビューへの押下は、周囲にある押下可能なビュー、たとえばページを開くカードにも引き続き届きます。

ref の focus() は、Tab と同じようにキーボードフォーカスをストップに移します(フォーカススタイルが表示され、onFocus が発火します)。たとえば、閉じたポップアップのトリガーにフォーカスを戻すときに使います。blur() はフォーカスを外します。

フォーカスの周囲にあるビューは、フォーカスがそのビュー自身、またはその内側のいずれかのビューにある間、focus-within:(focusWithinStyle、.focus_within(..))で自身のスタイルを設定できます。たとえば、編集中の入力を囲むフィールドの枠や、ボタンの 1 つにフォーカスがある間のツールバーです。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>

#Layout and identity

#Gestures driving animated values

これらの Prop は、ジェスチャーを、UI スレッド上で動くネイティブのアニメーション値にバインドします。フレームごとのアプリコードによる処理は不要です。タッチとジェスチャーも参照してください。

PanEvent は { cancelled, translation, velocity, value? } です(Rust では cancelled、translation、velocity_x、velocity_y、value_x、value_y)。システムがドラッグをキャンセルしたかどうか、開始からの移動量、秒あたりのポイントで表した速度(Point)、そしてその時点でのバインドされた値が含まれます。バインドされた値は、pan がバインドする軸については { x?, y? } です(ドラッグはアニメーション中の値をつかむことができます)。

#Raw touches and the responder system

上の Prop ではカバーできないジェスチャーのために、すべての要素がタッチ系とレスポンダー系の Prop を受け付けます。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() }); the …ShouldSetResponder handlers also get a gestureState (dx, dy, vx, vy, …)。onResponderGrant から true を返すと、ネイティブのスクロールビューがタッチを奪わなくなります。panActivation({ activeOffsetX, activeOffsetY, failOffsetX, failOffsetY })は、プラットフォームがパンを有効にした後にはじめてビューをレスポンダーにするため、スクロールビュー内でのドラッグでは、もう一方の軸がスクロールビューに任されます(タッチとジェスチャー)。PanResponder の PanResponder は、これらをもとに作られています。Rust では、.on_touch(..) がすべてのタッチを受け取り(TouchEvent)、.claim_touches(..) がビューがタッチを引き受けるタイミングを決め、.on_responder_grant(..)、.on_responder_move(..)、.on_responder_release(..) などがレスポンダーに従います。

#Accessibility

アクセシビリティを参照してください。

#Platform-only props

1 つのプラットフォームにしかない Prop は、TSX ではそのプラットフォーム名のオブジェクトに入れるため、共通の Prop はどこでも同じままです。送られるのは現在のプラットフォームのオブジェクトだけで、それ以外は無視されます。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 は要素の ref を受け取ります。その型は要素固有のものです。View、Text、Image、Canvas、Overlay、Shader には ViewRef（focus、blur、measure）が使われ、それ以外の要素には、その要素のメソッドを持つ ViewRef ベースの型が使われます。具体的には InputRef（Input）、ScrollRef（Scroll）、ListRef（List）、WebViewRef（WebView）、VideoRef（Video）、NativeComponentRef（ネイティブコンポーネント）です。Rust では、element_ref() が ElementRef ハンドルを作成し、.element_ref(&handle) がそれをアタッチします。これらのメソッドは、ネイティブビューにコマンドを送ります。コマンドは、同じターン内でそれより前に行われた変更と同じ順序で送られます。各要素のページに、その要素で使えるメソッドが記載されています。ref 変数には、その要素固有の型（<Input> なら let field!: InputRef）を指定してください。ViewRef 型の変数は、固有のメソッドを持つ ref の要素には適合しません。

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 をブロックしない理由

メインスレッドは、アプリのコードを待つことはありません。システムがその場で答えを必要とする場合（このテキストを変更してよいか、戻るボタンで pop してよいか、このシートを閉じてよいか）、NSH は事前に設定された props（maxLength、popOnBack、closeOnSwipe など）に基づいてネイティブ側で応答し、イベントはその後でアプリに届きます。このような動作が、ハンドラの戻り値ではなく prop になっているのはそのためです。