nsh

nsh はコアモジュールです。リアクティブ API(シグナル、算出値、エフェクト、コンテキスト)、mount、token、ホスト要素の View、Text、Scroll、Overlay、選択可能なビュー、セーフエリアとキーボード、アニメーション、デバイスとその環境、PanResponder、クリップボード、フォトピッカー、音声認識、ストレージ、ホストチャネル、キーボードショートカット、ネイティブコンポーネントとモジュール、アクセシビリティ、そして要素・スタイル・イベントの TypeScript 型を提供します。リアクティブグラフ自体は Rust でネイティブに動作します。シグナルの読み取りはランタイムへの呼び出しで、数ナノ秒しかかかりません。JavaScript インタプリタで実行されるのは、あなた自身のクロージャだけです。

import { batch, cleanup, computed, context, effect, ErrorBoundary, mount, Overlay, Scroll, signal, split, Text, token, untracked, View } from "nsh";
import { Input } from "nsh/base";

NSH のリアクティビティは SolidJS と同じモデルに従います。コンポーネント関数は 1 回だけ 実行され、シグナルを読み取っている UI の部分は、そのシグナルが変化したときにその場で更新されます。コンポーネントの再レンダリングも仮想 DOM もありません。ガイドは リアクティビティ を参照してください。

#signal

function signal<T>(value: T, options?: SignalOptions<T>): Signal<T>;
function signal<T = undefined>(): Signal<T | undefined>;

interface Signal<T> {
  (): T;                              // read (tracked)
  set(value: T): void;                // write
  update(fn: (value: T) => T): void;  // write from the current value
}

interface SignalOptions<T> {
  /** When a new value counts as a change (default `===`); `false`: always. */
  equals?: false | ((previous: T, next: T) => boolean);
}

シグナルは値を保持します。呼び出すと値を読み取り、追跡スコープ(JSX 式、computed、effect)の内側であれば、そのスコープをシグナルに購読させます。set と update は値を書き込み、それを読み取っていたものがすべて更新されます。

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

function Counter() {
  const count = signal(0);
  return (
    <View style={{ padding: 24, gap: 12 }}>
      <Text>Count: {count()}</Text>
      <Text onPress={() => count.update((n) => n + 1)}>Add one</Text>
    </View>
  );
}

mount(Counter);

既定では、現在の値と === な値の書き込みは何も行いません。書き込みのたびに通知したい場合(オブジェクトをその場で変更し、同じオブジェクトを再度設定するときに便利です)は equals: false を渡すか、独自の比較関数を渡してください。

const items = signal<string[]>([], { equals: false });
const point = signal({ x: 0, y: 0 }, { equals: (a, b) => a.x === b.x && a.y === b.y });

#computed

function computed<T>(fn: (previous: T | undefined) => T, options?: SignalOptions<T>): Accessor<T>;

interface Accessor<T> {
  (): T;
}

シグナルから導出される値です。読み取ったシグナルが変化すると fn が再実行されます。算出値の読み取り側は、その結果が変わったとき(既定では equals、=== による比較)にのみ更新されます。fn は直前の結果を受け取ります。

const first = signal("Ada");
const last = signal("Lovelace");
const full = computed(() => `${first()} ${last()}`);
full(); // "Ada Lovelace"

導出のコストが高い場合や複数の場所で読み取る場合は computed を使います。軽い式であれば、通常の関数(const full = () => first() + " " + last())でも同じようにリアクティブになります。

#effect

function effect(fn: () => void): void;

レンダリングの後に fn を実行し、読み取ったシグナルが変化するたびに再度実行します。エフェクトはログ出力、タイマー、ネイティブモジュールとのやり取りなどの副作用に使います。エフェクトは、それが作成されたコンポーネント(またはエフェクト)に属し、そのコンポーネントとともに破棄されます。

const query = signal("");
effect(() => {
  console.log("query is now", query());
});

エフェクトが再実行される前(またはコンポーネントが消える前)に何かを元に戻したい場合は、エフェクト内で cleanup を呼び出します。

#batch

function batch<T>(fn: () => T): T;

fn を実行し、その中のすべての書き込みを最後にまとめて適用します。これにより、読み取り側は書き込みごとではなく 1 回だけ更新されます。戻り値は fn の戻り値です。

batch(() => {
  first.set("Grace");
  last.set("Hopper");
}); // `full` recomputes once

#untracked

function untracked<T>(fn: () => T): T;

現在のスコープを読み取り対象に購読させずに fn を実行します。エフェクトや JSX 式の内側で、依存せずにシグナルを読み取りたいときに使います。

effect(() => {
  // Runs again when `query` changes, not when `page` changes.
  search(query(), untracked(() => page()));
});

#cleanup

function cleanup(fn: () => void): void;

現在のエフェクトが再実行される前、または現在のコンポーネントやエフェクトが消えるときに実行される fn を登録します。

function Clock() {
  const now = signal(new Date());
  const timer = setInterval(() => now.set(new Date()), 1000);
  cleanup(() => clearInterval(timer));
  return <Text>{now().toLocaleTimeString()}</Text>;
}

#context

function context<T>(defaultValue: T): Context<T>;

interface Context<T> extends Accessor<T> {
  Provider: (props: { value: T; children?: JSX.Element }) => JSX.Element;
}

コンポーネントが、描画するすべての要素(どれだけ深くても)へ提供する値です。コンテキストを呼び出す(Theme())と、最も近いプロバイダーの値を読み取ります。プロバイダーがない場合は defaultValue を返します。

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

const Theme = context<"light" | "dark">("light");

function Label(props: { text: string }) {
  return <Text style={{ color: Theme() === "dark" ? "#fff" : "#000" }}>{props.text}</Text>;
}

function App() {
  const dark = signal(false);
  return (
    <Theme.Provider value={dark() ? "dark" : "light"}>
      <View style={{ flex: 1, padding: 24, backgroundColor: dark() ? "#000" : "#fff" }}>
        <Label text="Hello" />
        <Text onPress={() => dark.update((d) => !d)}>Toggle</Text>
      </View>
    </Theme.Provider>
  );
}

mount(App);

#mount

function mount<P extends object>(app: Component<P>, props?: P): () => void;

app をサーフェス(ウィンドウ、またはアプリが埋め込まれている NshAppView / NshView)にレンダリングし、それを取り除く関数を返します。すべてのアプリのエントリファイルは mount(App) で終わります。

mount(App);

#split

function split<T extends object, K extends readonly (keyof T)[]>(
  props: T,
  keys: K,
): [Pick<T, K[number]>, Omit<T, K[number]>];

props オブジェクトを、keys で指定した名前の props と、それ以外に分割します。両方の結果はリアクティブなままです。値が変化する props はゲッターであり、split はそれらをゲッターとして保持します。一部の props を自分で処理し、残りを渡す場合のコンポーネントで使います。props を分割代入(const { label } = props)すると、一度だけ読み取られ、更新が失われます。

import { split, Text, View } from "nsh";
import { Input, type InputProps } from "nsh/base";

function LabeledInput(props: InputProps & { label: string }) {
  const [own, rest] = split(props, ["label"]);
  return (
    <View style={{ gap: 4 }}>
      <Text>{own.label}</Text>
      <Input {...rest} />
    </View>
  );
}

#ErrorBoundary

function ErrorBoundary(props: {
  fallback: JSX.Element | ((error: unknown, reset: () => void) => JSX.Element);
  children?: JSX.Element;
}): JSX.Element;

子要素を描画し、その配下で何かが例外を投げたとき(コンポーネントの本体、バインディング、エフェクト、イベントハンドラー)は fallback を描画します。失敗した部分は取り除かれ、その場所にフォールバックが表示されます。関数 fallback は、スローされた値と、子要素を再度描画する reset を引数として fallback(error, reset) のように呼び出されます。宣言しているパラメータが何であっても同様です。fallback 要素はそのまま表示されます。失敗は、その上にある最も近いバウンダリに渡され、フォールバック内での失敗はさらにその上のバウンダリに渡されます。Rust コンポーネントでは catch_error を使います(エラーバウンダリ)。

import { ErrorBoundary, Text, View } from "nsh";

function Feed() {
  return (
    <ErrorBoundary
      fallback={(error, reset) => (
        <View>
          <Text>{error instanceof Error ? error.message : String(error)}</Text>
          <Text onPress={reset}>Try again</Text>
        </View>
      )}
    >
      <Posts />
    </ErrorBoundary>
  );
}

#token

function token<K extends keyof Tokens>(name: K): Tokens[K];

アプリのテーマ(nsh.json の "theme"。shadcn/ui のトークンをベースにしています)のデザイントークン name を、表示中の外観(appearance)に合わせて返します。 色は #rrggbbaa、長さはポイント数、フォントはファミリー名です。名前はテーマの CSS 変数から -- を除いたもの(primary、muted-foreground、radius、font-mono、およびアプリ独自の up など)です。読み取りは リアクティブです。トークンを読み取るコンポーネント、メモ、エフェクトは、テーマや外観が変わると再実行されます。 Tokens にはアプリのトークンが型とともに列挙されており、NSH がテーマから .nsh/types/nsh/tokens.d.ts に書き出します。 クラスでは、トークンを直接指定します(bg-primary、rounded-(--radius))。詳しくは テーマトークン を参照してください。

import { effect, token } from "nsh";

effect(() => console.log("primary is", token("primary"), "radius", token("radius")));

#View, Text, Scroll, Overlay

function View(props: ViewProps): JSX.Element;
function Text(props: TextProps): JSX.Element;
function Scroll(props: ScrollProps): JSX.Element;
function Overlay(props: OverlayProps): JSX.Element;

nsh がエクスポートするホスト要素で、タグとして記述します。<View>、<Text>、<Scroll>、<Overlay>(その 子要素をウィンドウの最前面に、アンカーを基準に配置します。Overlay)です。コンパイラは、 インポート経由でこれらのいずれかを指すタグ(エイリアスも含む)に対して、その場でネイティブビューを 生成するため、インポートしても実行時のコストはかかりません。これらは他のコンポーネントと同様の コンポーネントなので、受け渡すこともできます(const Tag = inline ? Text : View)。 nsh は他のプリミティブも同じ方法でエクスポートしており、List、Image、 Canvas、WebView、Video それぞれに専用のリファレンス ページがあります。それらの props は 要素 に記載されています。テキスト入力の Input は nsh/base から提供されます。

#セーフエリアとキーボード

CSS の環境変数を使うと、任意のビューの padding と margin で、コンテンツをシステム UI から離して配置できます (padding、paddingTop など。同じ margin キー。Tailwind の p* / m* の任意値。Rust では Styled のメソッド .p_safe_area()、.pt_safe_area_plus(..)、.pb_keyboard() など)。値は EnvValue です。 env(name)、env(name, <length>)、calc(env(name) + <length>)、calc(<length> + env(name))。

<View style={{ flex: 1, paddingTop: "env(safe-area-inset-top)", paddingBottom: "env(keyboard-inset-height)" }}>…</View>

#safeArea and safeAreaInsets

safeArea() はサーフェスのセーフエリア(Rust では safe_area())、safeAreaInsets() はコンポーネントが 描画される場所のインセット(Rust では cx.insets())で、safe-area-inset-* 変数の値です。どちらもリアクティブな Edges ({ top, right, bottom, left } はポイント単位)です。詳しくは safeArea and safeAreaInsets を参照してください。

#Keyboard and keyboardFrame

Keyboard.dismiss() はソフトウェアキーボードを非表示にし(Rust では dismiss_keyboard())、keyboardFrame() は画面のどれだけが キーボードで覆われているかを返します(Rust では keyboard_height() と keyboard_duration())。詳しくは キーボードを隠す と キーボードの高さ を参照してください。

#選択可能なビュー

<View selectable>(Rust では view().selectable(true))は、内部のテキストを Web ページと同じように一緒に選択できるようにします。 1 つの選択範囲が、ビュー、Text 要素、TextView をまたいで読み順に連続します。詳しくは テキスト選択 を参照してください。

#アニメーション

アニメーション API は UI スレッド上でアニメーションを実行します。アニメーション値 を作成し、それ(またはそこから導出した値)をスタイルプロパティにバインドして、アニメーションを開始します。以降、すべてのフレームはアプリのコードを実行することなくネイティブに計算されます。エンジンや JS スレッドがビジー状態でもアニメーションがカクつくことはなく、アニメーションによるフレームごとのアプリ側の処理もありません。Rust のコードでは nsh_core::prelude の animated_value()、motion()、Animation、Spring、Timing、KeyframeTiming、MotionPreset、Easing を使い、要素の .bind_* メソッドで値をバインドします。TSX では nsh からインポートします。

use nsh_core::{element::LayoutAnimation, prelude::*}; // animated_value, motion, Animation, Spring, Timing, Keyframe, KeyframeTiming, MotionPreset, MotionSpec, Easing, animate_layout

import { Animated, createAnimatedValue, createMotion, motions, Easing, LayoutAnimation, AnimatedNode, AnimatedValue } from "nsh";

ガイドは アニメーション を参照してください。

#アニメーション値が駆動できるもの

その他のスタイルプロパティは通常の値を受け取ります。レイアウト自体(サイズ、フロー内の位置)をアニメーションさせるには、LayoutAnimation を使います。

#createAnimatedValue

function createAnimatedValue(value?: number): AnimatedValue;

value(既定は 0)から始まるアニメーション値を作成します。Rust では animated_value(value) で、作成したコンポーネントが保持する Copy ハンドルです。

use nsh_core::prelude::*;

#[component]
pub fn App() -> impl IntoElement {
    let x = animated_value(0.0);
    let right = stored(false);
    let toggle = move || {
        let to_right = !right.get();
        right.replace(to_right);
        let _ = x.spring(if to_right { 200.0 } else { 0.0 }, Spring::default());
    };
    view()
        .flex_1()
        .p_6()
        .pt_12()
        .gap_4()
        .child(view().size(px(60.0)).rounded(px(12.0)).bg(rgb(0x6366f1)).bind_translate_x(&x))
        .child(text("Move").on_press(toggle))
}

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

function App() {
  const x = createAnimatedValue(0);
  let right = false;
  const toggle = () => {
    right = !right;
    x.spring(right ? 200 : 0);
  };
  return (
    <View style={{ flex: 1, padding: 24, paddingTop: 48, gap: 16 }}>
      <View style={{ width: 60, height: 60, borderRadius: 12, backgroundColor: "#6366f1", transform: [{ translateX: x }] }} />
      <Text onPress={toggle}>Move</Text>
    </View>
  );
}

mount(App);

#AnimatedValue

class AnimatedValue extends AnimatedNode {
  constructor(value: number);
  set(value: number): void;
  stop(): Promise<{ value: number }>;
  getValue(): Promise<number>;
  setOffset(offset: number): void;
  flattenOffset(): void;
  extractOffset(): void;
  timing(to: number, options?: { duration?: number; easing?: Easing; delay?: number }): Promise<{ finished: boolean }>;
  spring(to: number, options?: { stiffness?: number; damping?: number; mass?: number; velocity?: number }): Promise<{ finished: boolean }>;
  decay(options?: { velocity?: number; deceleration?: number; clamp?: [number, number]; bounce?: number }): Promise<{ finished: boolean }>;
  keyframes(keyframes: KeyframeValue[], options?: KeyframeTiming): Promise<{ finished: boolean }>;
}

各アニメーションメソッドは、{ finished } で解決される Promise を返します。アニメーションが完了した場合は true、停止された場合(stop、set、または同じ値への別のアニメーションによる)は false です。Rust では AnimationEnd を返し、タスクが同じ bool を得るためにそれを await します。

let opacity = animated_value(1.0);
spawn(async move {
    if opacity.timing(0.0, 200.0, Easing::EaseInOut).await {
        visible.set(false);
    }
});

const opacity = createAnimatedValue(1);
const { finished } = await opacity.timing(0, { duration: 200 });
if (finished) visible.set(false);

#AnimatedNode

class AnimatedNode {
  interpolate(config: {
    inputRange: number[];
    outputRange: number[] | string[];
    extrapolate?: Extrapolation;
    extrapolateLeft?: Extrapolation;
    extrapolateRight?: Extrapolation;
    easing?: Easing;
  }): AnimatedNode;
  diffClamp(min: number, max: number, options?: { snap?: boolean }): AnimatedNode;
  add(b: AnimatedNode | number): AnimatedNode;
  sub(b: AnimatedNode | number): AnimatedNode;
  mul(b: AnimatedNode | number): AnimatedNode;
  div(b: AnimatedNode | number): AnimatedNode;
  mod(b: AnimatedNode | number): AnimatedNode;
}

type Extrapolation = "extend" | "clamp" | "identity";

ネイティブのアニメーショングラフのノードです。AnimatedValue、または他の値から導出された値です。導出されたノードは、入力が変化するたびに UI スレッドで評価されます。

let scroll_y = animated_value(0.0);
let header = scroll_y.diff_clamp(0.0, 44.0);

view()
    .flex_1()
    .child(scroll().scroll_value(&scroll_y).flex_1() /* rows */)
    .child(view().h(px(44.0)).bind_translate_y(&header.mul(-1.0)))

const scroll = createAnimatedValue(0);
const header = scroll.diffClamp(0, 44);

<Scroll scrollValue={scroll} style={{ flex: 1 }}>{/* rows */}</Scroll>
<View style={{ height: 44, transform: [{ translateY: header.mul(-1) }] }} />

let progress = animated_value(0.0);
let rotate = progress.interpolate(&[0.0, 1.0], &[0.0, 360.0]); // degrees, for bind_rotate
let color = progress.interpolate_colors(&[0.0, 0.5, 1.0], &[rgb(0x22c55e), rgb(0xeab308), rgb(0xef4444)]);

const progress = createAnimatedValue(0);
const rotate = progress.interpolate({ inputRange: [0, 1], outputRange: ["0deg", "360deg"] });
const color = progress.interpolate({ inputRange: [0, 0.5, 1], outputRange: ["#22c55e", "#eab308", "#ef4444"] });

#Keyframes

interface Keyframe {
  offset?: number;          // 0..1 of an iteration; missing offsets spread evenly
  value: number | string;   // a number, or an angle ("45deg", "0.5turn") in degrees
  easing?: Easing;          // the segment that starts here
}
type KeyframeValue = number | string | Keyframe;

interface KeyframeTiming {
  duration?: number;        // one iteration, ms (300)
  delay?: number;           // before the first iteration, ms (0)
  easing?: Easing;          // segments without their own (CSS "ease")
  iterations?: number | "infinite";   // 1
  direction?: "normal" | "reverse" | "alternate" | "alternate-reverse";
}

value.keyframes(frames, options) はキーフレームを通して値を再生し、終了したかどうかを表す { finished } で解決します。Animated.keyframes(value, { keyframes, ...options }) は composite のステップと同じです。Rust: value.keyframes(frames, KeyframeTiming) と Animation::keyframes(&value, frames, KeyframeTiming)。Keyframe::new(value)(均等に配置)、Keyframe::at(offset, value)、.ease(easing)、そして KeyframeTiming::new(ms) に .delay(ms)、.easing(e)、.iterations(Some(n))、.infinite()、.direction(PlaybackDirection::…) を指定します。

再生は CSS keyframes と同じ規則に従います。イージングは1つのセグメントに作用します(キーフレームのイージングはそのキーフレームから始まるセグメント、timing のイージングはそれ以外のすべてのセグメント)。キーフレームで省略されたオフセットは均等に配置され、最初は 0、最後は 1 になります。各イテレーションは最初のキーフレームへのジャンプで始まり、0 にキーフレームがない場合、値は現在の位置から始まります。delay の間、値は最初のキーフレームを保持します(CSS の animation-fill-mode: backwards)。逆方向のイテレーションはセグメントを逆順に、カーブを反転して実行します。値は最後のイテレーションが終わった位置に留まります。

let y = animated_value(0.0);
y.keyframes(
    [Keyframe::new(0.0), Keyframe::at(0.3, -20.0).ease(Easing::EaseIn), Keyframe::new(0.0)],
    KeyframeTiming::new(600.0).iterations(Some(3)),
);

const y = createAnimatedValue(0);
y.keyframes([0, { offset: 0.3, value: -20, easing: "easeIn" }, 0], { duration: 600, iterations: 3 });

#createMotion

function createMotion(options?: MotionOptions): Motion;

interface MotionOptions extends MotionPlayOptions {
  initial?: { [C in MotionChannel]?: number };   // where channels start (the others at rest)
  enter?: MotionName | MotionSpec;   // start where it starts and play it at once
}

interface MotionPlayOptions extends KeyframeTiming {
  ignoreReduceMotion?: boolean;      // play even when the user asks for less motion
}

interface Motion {
  readonly opacity: AnimatedValue;
  readonly translateX: AnimatedValue;
  readonly translateY: AnimatedValue;
  readonly rotate: AnimatedValue;    // degrees
  readonly rotateX: AnimatedValue;
  readonly rotateY: AnimatedValue;
  readonly scale: AnimatedValue;
  readonly scaleX: AnimatedValue;
  readonly scaleY: AnimatedValue;
  readonly style: { opacity: AnimatedValue; transform: MotionTransform };
  readonly transform: MotionTransform;
  play(motion: MotionName | MotionSpec, options?: MotionPlayOptions): Promise<{ finished: boolean }>;
  animation(motion: MotionName | MotionSpec, options?: MotionPlayOptions): CompositeAnimation;
  stop(): void;
  reset(): void;
}

モーションを作成します。ビューの不透明度と transform の各チャネルに対するアニメーション値(静止状態は、不透明度とスケールが 1、それ以外が 0)と、それらをネイティブで再生するモーションです。style={motion.style} でバインドするか、motion.style または motion.transform をスタイルにスプレッドします。transform は、移動、回転、スケールの順に適用され、scale は scaleX と scaleY に畳み込まれます。これはビューの8つの transform ステップのうち7つを使い、1つはあなた用に残ります(3D フリップ用の [{ perspective: 600 }, ...motion.transform])。initial はチャネルの開始位置を設定します({ opacity: 0 }。それ以外は静止状態から始まります)。enter を指定すると、それが動かすチャネルはそのモーションの開始位置から始まり(initial の間)、すぐに再生されます。その他のオプションはタイミングとして使われます(delay、duration、…)。モーションが動かすのは不透明度と transform だけです。motion.style をスプレッドするとビューの opacity が設定されるため、独自の不透明度を保つには motion.transform だけをバインドしてください。色の変化はアニメーション値と interpolate で行います。Rust: motion()。作成したコンポーネントが保持する Copy ハンドルで、.bind_motion(&m) でバインドします。motion().entering(spec) は入場です。

ユーザーがモーションの低減を求めている場合(reduceMotion())、play、animation、enter は、動かずに即座にモーションの終点に到達します。ただし、(オプションまたはモーションで)ignoreReduceMotion が設定されている場合を除きます。

let card = motion().entering(MotionPreset::FadeInUp.spec().timing(|t| t.delay(80.0)));
view().size(px(120.0)).rounded(px(16.0)).bg(rgb(0x0969da)).bind_motion(&card).on_press(move || {
    card.play(MotionPreset::Pulse);
})

const card = createMotion({ enter: "fadeInUp", delay: 80 });
<View onPress={() => card.play("pulse")} style={{ width: 120, height: 120, borderRadius: 16, backgroundColor: "#0969da", ...card.style }} />

#motions

const motions: Readonly<Record<MotionName, MotionPreset>>;

type MotionChannel = "opacity" | "translateX" | "translateY" | "rotate" | "rotateX" | "rotateY" | "scale" | "scaleX" | "scaleY";

interface MotionSpec extends KeyframeTiming {
  keyframes: { [C in MotionChannel]?: KeyframeValue[] } | MotionFrame[];
  ignoreReduceMotion?: boolean;
}
type MotionFrame = { [C in MotionChannel]?: number | string } & { offset?: number; easing?: Easing };

interface MotionPreset extends MotionSpec {
  kind: "enter" | "exit" | "attention" | "loop";
}

既成のモーションをデータとして提供します。motion.play("shake") は motions.shake を再生します。MotionName は次のいずれかです。fadeIn、fadeInUp、fadeInDown、fadeInLeft、fadeInRight、zoomIn、popIn、bounceIn、slideInUp、slideInDown、flipInX、flipInY(入場)。fadeOut、fadeOutUp、fadeOutDown、fadeOutLeft、fadeOutRight、zoomOut、popOut、slideOutDown、slideOutUp(退場)。shake、headShake、wiggle、swing、pulse、heartbeat、rubberBand、jello、tada、jump、flash(注目)。spin、float、breathe、sway、bob、glow(ループ)。それぞれの説明は Animation を参照してください。プリセットをスプレッドすると変更できます: motion.play({ ...motions.fadeInUp, duration: 600 })。

MotionSpec は独自のモーションです。各チャネルのキーフレーム({ opacity: [0, 1], translateY: [24, 0] })、または Web Animations API の書式によるフレームのリスト([{ opacity: 0, translateY: 24 }, { opacity: 1, translateY: 0 }]。オフセットのないフレームはリスト内の位置によって配置されます)に、キーフレームのタイミングを組み合わせます。Rust: MotionSpec::new(KeyframeTiming) に .values(channel, values)(均等に配置)、.track(channel, keyframes)、.timing(|t| …) を指定します。MotionPreset::FadeInUp(または .spec())はプリセットで、MotionChannel はチャネルに名前を付けます。

let rise = MotionSpec::new(KeyframeTiming::new(400.0))
    .values(MotionChannel::Opacity, [0.0, 1.0])
    .track(MotionChannel::TranslateY, [Keyframe::at(0.0, 24.0).ease(Easing::EaseOut), Keyframe::at(1.0, 0.0)]);
card.play(rise);

card.play({ duration: 400, keyframes: [{ opacity: 0, translateY: 24, easing: "easeOut" }, { opacity: 1, translateY: 0 }] });

#Animated

const Animated: {
  timing(value: AnimatedValue, config: { toValue: number; duration?: number; easing?: Easing; delay?: number }): CompositeAnimation;
  spring(value: AnimatedValue, config: { toValue: number; stiffness?: number; damping?: number; mass?: number; velocity?: number }): CompositeAnimation;
  decay(value: AnimatedValue, config?: { velocity?: number; deceleration?: number; clamp?: [number, number]; bounce?: number }): CompositeAnimation;
  sequence(list: CompositeAnimation[]): CompositeAnimation;
  parallel(list: CompositeAnimation[], config?: { stopTogether?: boolean }): CompositeAnimation;
  stagger(ms: number, list: CompositeAnimation[], config?: { from?: "first" | "last" | "center" | number }): CompositeAnimation;
  delay(ms: number): CompositeAnimation;
  loop(animation: CompositeAnimation, config?: { iterations?: number; resetBeforeIteration?: boolean }): CompositeAnimation;
  keyframes(value: AnimatedValue, config: KeyframeTiming & { keyframes: KeyframeValue[] }): CompositeAnimation;
  add(a: AnimatedNode, b: AnimatedNode | number): AnimatedNode;
  subtract(a: AnimatedNode, b: AnimatedNode | number): AnimatedNode;
  multiply(a: AnimatedNode, b: AnimatedNode | number): AnimatedNode;
  divide(a: AnimatedNode, b: AnimatedNode | number): AnimatedNode;
  modulo(a: AnimatedNode, b: AnimatedNode | number): AnimatedNode;
  diffClamp(a: AnimatedNode, min: number, max: number, options?: { snap?: boolean }): AnimatedNode;
  sampleSpring(config: SpringConfig & { from?: number }, fps?: number): number[];
  sampleDecay(config: DecayConfig & { from?: number }, fps?: number): number[];
};

interface CompositeAnimation {
  start(callback?: (result: { finished: boolean }) => void): Promise<{ finished: boolean }>;
  stop(): void;
  reset(): void;
}

Animated は、ステップ(timing、spring、decay、sequence、parallel、…)を組み合わせてアニメーションを構築します。start() を呼ぶまで何も実行されません。呼ぶとツリー全体がネイティブで実行され、各ステップは前のステップが終わるちょうどその瞬間に UI スレッド上で開始されます(フレームの隙間も、ステップ間でのアプリのコードへの往復もありません)。Rust では Animation で同じツリーを構築します。

CompositeAnimation:

let ys: Vec<AnimatedValue> = (0..4).map(|_| animated_value(0.0)).collect();
let hop = Animation::stagger(
    80.0,
    ys.iter().map(|y| {
        Animation::sequence([
            Animation::timing(y, -36.0, Timing::new(220.0, Easing::Curve(Curve::Quad, EaseMode::Out))),
            Animation::spring(y, 0.0, Spring { stiffness: 300.0, damping: 12.0, ..Spring::default() }),
        ])
    }),
);
let run = hop.start();
spawn(async move { log::info!("{}", if run.await { "done" } else { "stopped" }) });

const ys = [0, 1, 2, 3].map(() => createAnimatedValue(0));
const hop = Animated.stagger(
  80,
  ys.map((y) =>
    Animated.sequence([
      Animated.timing(y, { toValue: -36, duration: 220, easing: Easing.out(Easing.quad) }),
      Animated.spring(y, { toValue: 0, stiffness: 300, damping: 12 }),
    ]),
  ),
);
hop.start(({ finished }) => console.log(finished ? "done" : "stopped"));

#Easing

type Easing =
  | "linear" | "ease" | "easeIn" | "easeOut" | "easeInOut"
  | [number, number, number, number]   // cubic Bézier x1, y1, x2, y2
  | EasingCurve
  | EasingSteps;                     // Easing.steps(…)

const Easing: {
  linear: Easing;
  ease: Easing;
  bezier(x1: number, y1: number, x2: number, y2: number): Easing;
  steps(count: number, position?: "jump-start" | "jump-end" | "jump-none" | "jump-both" | "start" | "end"): EasingSteps;
  in(e: Easing): Easing;
  out(e: Easing): Easing;
  inOut(e: Easing): Easing;
  sample(easing: Easing, count: number): number[];
  quad: EasingCurve;
  cubic: EasingCurve;
  poly(n?: number): EasingCurve;
  sin: EasingCurve;
  circle: EasingCurve;
  exp: EasingCurve;
  elastic(bounciness?: number): EasingCurve;
  back(s?: number): EasingCurve;
  bounce: EasingCurve;
};

イージングはデータであり、アプリの関数ではありません。ランタイムがネイティブで評価します。Rust では列挙型 Easing で、Linear、EaseIn、EaseOut、EaseInOut、Bezier(x1, y1, x2, y2)、Steps(count, StepPosition)、Curve(curve, mode) があり、Curve(Quad、Cubic、Poly(n)、Sin、Circle、Exp、Elastic(bounciness)、Back(s)、Bounce)と EaseMode(In、Out、InOut)を持ちます。カーブを描画するには、Easing.sample(easing, count)(Rust: nsh_core::element::sample_easing)が 0 から 1 までの count 個の等間隔の点での値を返します。Animated.sampleSpring と Animated.sampleDecay(sample_spring、sample_decay)は、from(0)から終了するまでの、スプリングまたは減衰の値をフレームごとに1つ返します(fps で指定し、デフォルトは 60)。3つともアニメーションが実行されるネイティブコードから得られます。TSX で Easing を受け付ける場所ではどこでも、名前("easeOut")、4つの数値による3次ベジェ曲線、または Easing オブジェクトのカーブを渡せます。

Easing.steps(count, position) は CSS の steps() です。値は動く代わりに count 段階の間でジャンプします(コマ送りのスプライト、時を刻む針など)。position はジャンプの位置を指定します。"jump-end"(デフォルト、"end" も同じ)、"jump-start"("start")、"jump-none"、または "jump-both"。Rust では Easing::Steps(count, StepPosition::JumpEnd)、JumpStart、JumpNone、JumpBoth です。

カーブは「in」形式(始まりがゆっくり)です。Easing.out(curve) は反転し、Easing.inOut(curve) は対称にし、Easing.in(curve) はそのままにします。Rust では Easing::Curve の EaseMode がこれに当たります。

let _ = value.timing(1.0, 600.0, Easing::Curve(Curve::Back(1.70158), EaseMode::Out));
let _ = value.timing_with(1.0, Timing { easing: Easing::Bezier(0.2, 0.0, 0.0, 1.0), ..Timing::default() });
let _ = value.timing_with(1.0, Timing { easing: Easing::EaseOut, ..Timing::default() });

value.timing(1, { duration: 600, easing: Easing.out(Easing.back()) });
value.timing(1, { easing: Easing.bezier(0.2, 0, 0, 1) });
value.timing(1, { easing: "easeOut" });

#LayoutAnimation

const LayoutAnimation: {
  configureNext(config: LayoutAnimationConfig, onEnd?: () => void): void;
  create(duration: number, type?: LayoutAnimationType, property?: LayoutAnimationProperty): LayoutAnimationConfig;
  Types: { easeInEaseOut; spring; linear; easeIn; easeOut; keyboard };
  Properties: { opacity; scaleXY };
  Presets: { easeInEaseOut: LayoutAnimationConfig; linear: LayoutAnimationConfig; spring: LayoutAnimationConfig };
  easeInEaseOut(onEnd?: () => void): void;
  linear(onEnd?: () => void): void;
  spring(onEnd?: () => void): void;
};

interface LayoutAnimationConfig {
  duration: number;                // ms
  create?: LayoutAnimationAnimation;    // views inserted
  update?: LayoutAnimationAnimation;    // views moved or resized
  delete?: LayoutAnimationAnimation;    // views removed
}

interface LayoutAnimationAnimation {
  type?: "easeInEaseOut" | "spring" | "linear" | "easeIn" | "easeOut" | "keyboard";
  property?: "opacity" | "scaleXY" | "scale";
  duration?: number;
  delay?: number;
  springDamping?: number;          // 0..1, default 0.7
}

LayoutAnimation.configureNext(config) は、次のコミットでのレイアウト変更をネイティブでアニメーションさせます。移動またはリサイズするビューは新しいフレームへ滑らかに移り、新しいビューは(property に応じて、フェードインまたはスケールインで)現れ、削除されたビューは消えます。レイアウトを変える状態変更の直前に呼び出してください。Rust: animate_layout(LayoutAnimation)。nsh_core::element::LayoutAnimation のプリセット、または create、update、delete のトランジションを使います。

let open = signal(false);
let toggle = move || {
    animate_layout(LayoutAnimation::SPRING);
    open.update(|o| *o = !*o);
};

view()
    .child(text("Details").on_press(toggle))
    .child(when(move || open.get(), || text("Shown with a spring.")))

const open = signal(false);
const toggle = () => {
  LayoutAnimation.configureNext(LayoutAnimation.Presets.spring);
  open.update((o) => !o);
};

<View>
  <Text onPress={toggle}>Details</Text>
  <If when={open()}>
    <Text>Shown with a spring.</Text>
  </If>
</View>

#Device

Device API は、デバイスとその環境についてアプリに伝えます。Rust コードは nsh_core::prelude の関数(window()、dark()、font_scale()、locale()、lifecycle()、os()、idiom()、pixel_ratio()、set_color_scheme()、…)を呼び出し、TSX は nsh からそれらをインポートします。ウィンドウサイズ、カラースキーム、フォントスケール、ピクセル比、ロケール、アプリの状態はリアクティブです。バインディング(Rust では要素に渡すクロージャ、TSX では JSX)、computed、または effect の中で読み取ると、プラットフォームが変更を通知したとき(回転、ウィンドウのリサイズ、ダークモードへの切り替え、文字サイズや言語の変更、別の密度の画面への移動、アプリを離れて戻ってきたとき)に、それを読み取っているものが更新されます。

use nsh_core::{
    platform::{Appearance, Idiom, Lifecycle, Os},
    prelude::*, // window, dark, font_scale, locale, lifecycle, os, idiom, pixel_ratio, set_color_scheme, ...
};

import { colorScheme, fontScale, lifecycle, locale, openUrl, pixelRatio, platform, setColorScheme, windowSize } from "nsh";

ガイドは デバイスと環境 を参照してください。

#windowSize

const windowSize: Accessor<Size>;

サーフェスのサイズ(ポイント単位)です。ウィンドウ、または埋め込まれた NshAppView / NshView のサイズを指します。リアクティブです。Rust: window() -> Size<Points>。

let wide = move || window().width >= px(600.0);

view().style_when(wide, |s| s.flex_row())

const wide = () => windowSize().width >= 600;

<View style={{ flexDirection: wide() ? "row" : "column" }}>{/* ... */}</View>

#colorScheme

const colorScheme: Accessor<"light" | "dark">;

表示されている外観です。アプリが独自に設定していない限り、システムの外観になります(nsh.json "appearance"、setColorScheme)。リアクティブです。Rust: dark() -> bool。テーマカラー(AdaptiveColor)と .dark(…) スタイルバリアントは、これを読み取らなくても追従します。Tailwind の dark: バリアントも追従します(Tailwind を参照)。

view().flex_1().bg(move || if dark() { black() } else { white() })

const dark = () => colorScheme() === "dark";

<View style={{ flex: 1, backgroundColor: dark() ? "#000" : "#fff" }} />

#fontScale

const fontScale: Accessor<number>;

デフォルトに対するユーザーの希望する文字サイズです(1 がデフォルトのサイズ。iOS では Dynamic Type、Android ではフォントサイズ)。または、その代わりに埋め込み側のアプリが設定した文字サイズです。リアクティブです。Rust: font_scale() -> f32。allowFontScaling={false} を指定しない限り、テキストはすでにこれに合わせて拡大縮小されます。テキストの横のアイコンなど、他のサイズも追従させたい場合に読み取ってください。

#locale

const locale: Accessor<string>;

BCP 47 タグ("en-US"、"zh-Hans-CN")で表されるユーザーのロケールです。または、その代わりに埋め込み側のアプリが設定したロケールです。リアクティブです。Rust: locale() -> Locale(locale().as_str() がタグです)。Intl はデフォルトでこれに合わせてフォーマットします。独自の翻訳の文字列を選ぶために読み取ってください(デバイスと環境)。

#lifecycle

const lifecycle: Accessor<"active" | "inactive" | "background">;

アプリが使われているかどうかを、React Native の AppState の用語で表します。"active" は前面にあり入力を受け付けている状態、"inactive" は表示されているがフォーカスがない状態(別のアプリやウィンドウがフォーカスを持っている、またはアプリスイッチャーや着信など、システムが上に何かを表示している)、"background" は表示されていない状態(バックグラウンド、最小化、非表示のブラウザタブ)です。ネイティブアプリの中に表示されている場合は、そのアプリの状態に従います。リアクティブです。Rust: lifecycle() -> Lifecycle(Lifecycle::Active、Inactive、Background)。

誰にも見えない処理を一時停止し、アプリが戻ってきたら再開するには、effect の中で読み取ります。

effect(move || {
    if lifecycle() == Lifecycle::Background {
        feed.pause();
    } else {
        feed.resume();
    }
});

effect(() => {
  if (lifecycle() === "background") feed.pause();
  else feed.resume();
});

#setColorScheme

function setColorScheme(scheme: "light" | "dark" | "system"): void;

システムの外観に関係なく、アプリを scheme で即座に表示します。colorScheme()、dark: クラス、コンポーネントのテーマ、プラットフォームのコントロール(アラート、ステータスバーのデフォルトスタイル)が追従します。"system" を指定すると、再びシステムに従います。nsh.json "appearance" は最初から設定します。Rust: set_color_scheme(Appearance::Dark)(Appearance::Light、Appearance::System)。

#platform

const platform: Platform;

interface Platform {
  readonly os: "ios" | "android" | "macos" | "windows" | "linux" | "web";
  readonly version: string;
  readonly idiom: "phone" | "pad" | "mac" | "tv" | "desktop";
  readonly desktop: boolean;
  readonly catalyst: boolean;
  select<T>(spec: PlatformSelectSpec<T>): T | undefined;
}

アプリが動作しているプラットフォームです。実行中は変化しません。

let columns = if is_desktop() { 3 } else { 1 };

const columns = platform.desktop ? 3 : 1;

#platform.select

interface PlatformSelectSpec<T> {
  ios?: T;
  android?: T;
  macos?: T;
  windows?: T;
  linux?: T;
  web?: T;
  mobile?: T;   // platform.desktop false: iOS (Mac Catalyst included), Android, phone and tablet browsers
  desktop?: T;  // platform.desktop true: macOS, Windows, Linux, desktop browsers
  native?: T;   // every platform but the web
  default?: T;
}

現在の OS(ios、android、web など)に対応する値を返します。なければ desktop または mobile(platform.desktop による)、次に native(Web 以外のすべてのプラットフォーム)、次に default、最後に undefined を返します。Rust のコードでは os()(mobile / desktop には is_desktop())でマッチさせます。

use nsh_core::platform::Os;

let card = view().p_4();
let card = match os() {
    Os::Ios => card.shadow([BoxShadow {
        offset_y: px(2.0),
        blur: px(8.0),
        color: rgba(0x00000026).into(),
        ..BoxShadow::default()
    }]),
    Os::Android => card.elevation(px(4.0)),
    _ => card,
};

const shadow = platform.select({
  ios: { boxShadow: "0px 2px 8px rgb(0 0 0 / 0.15)" },
  android: { elevation: 4 },
});

#pixelRatio

const pixelRatio: Accessor<number>;

1 ポイントあたりのデバイスピクセル数です(例: 多くの iPhone では 3)。リアクティブな値で、ウィンドウが別の密度の画面に移動したとき(Mac Catalyst、デスクトップ、外部ディスプレイ)や、Android のディスプレイサイズ設定で密度が変わったときに更新されます。Rust では pixel_ratio() -> f32、デバイスピクセル単位の長さには round_to_nearest_pixel(points) を使います。TSX ではその長さは Math.round(x * pixelRatio()) / pixelRatio() です。

let hairline = move || px(1.0 / pixel_ratio());

const hairline = () => 1 / pixelRatio();

#openUrl

function openUrl(url: string): Promise<OpenUrlResult>;

interface OpenUrlResult {
  opened: boolean;
}

url をアプリの外で開きます。Web ページはブラウザで、mailto: リンクはメールアプリで、tel: リンクは電話アプリで、そのほか他のアプリが登録した任意のスキーム(maps:、ホストアプリ独自の lb:// リンク)も開きます。何かが開いたかどうかを表す { opened } で解決され、そのスキームを処理するアプリがない場合は false になります。Rust では nsh_core::prelude の open_url(url) を返します。これはタスク内で await する(または破棄する)ための応答で、意味は同じ bool です。

button()
    .child(text("Contact us"))
    .on_press(|| {
        spawn(async {
            if !open_url("mailto:help@example.com").await {
                log::warn!("no mail app");
            }
        });
    })

<Button
  onPress={async () => {
    const { opened } = await openUrl("mailto:help@example.com");
    if (!opened) {
      console.warn("no mail app");
    }
  }}
>
  <Text>Contact us</Text>
</Button>

• URL は絶対 URL(スキームを持つもの)でなければなりません。コードを実行したり、アプリ自身のデータにアクセスしたりする URL(javascript:、data:、blob:、file:、about:、asset:)は、相対アドレスと同様に、TypeError で Promise を reject します。openUrl は決して throw しません。すべての失敗は reject になります。
• capabilities を宣言しているアプリには openUrl が必要です。すべてのスキームには "openUrl": true、列挙したスキームのみには "openUrl": { "schemes": ["https", "mailto"] } を指定します。それ以外の URL は、code が "ERR_ACCESS_DENIED"、permission "openUrl"、resource が URL である Error で reject されます(Sandbox and capabilitiesを参照)。Rust では、open_url はこれらに対して false を返し、理由をログに出力します。
• 組み込み先のアプリが最初に URL を受け取り、代わりに独自のルーターで処理することができます(Swift の NshAppView.onOpenURL、Java の NshView.setOpenUrlHandler、Rust の AppView::host().handle_open_url。iOSと Androidを参照)。その場合、opened は true になります。
• 各プラットフォームは、それぞれ固有の方法で開きます。iOS では UIApplication.open(組み込み時はホストアプリのアプリケーション)、Android では ACTION_VIEW インテント、macOS では NSWorkspace、Windows では ShellExecuteW、Linux では GtkUriLauncher、GPUI では open_url、Web では新しいタブです。nsh test は URL を開く代わりに記録します。
• TextViewは、links="open" を使ってこの方法でリンクを開きます。

#レイアウト方向

レイアウト方向はユーザーの言語に従います。右から左へ書く言語(アラビア語、ヘブライ語など)では、アプリは右から左にレイアウトされ、行は右から始まり、left / right のスタイルプロパティ(marginLeft、paddingRight など)は開始側と終了側を意味します。変更は再起動なしですぐに反映されます。

ビューの direction スタイル("ltr"、"rtl"、またはデフォルトの "inherit")は、そのサブツリーの方向を設定します。Rust では .direction(LayoutDirection::..) です。

view().direction(LayoutDirection::Rtl).flex_row().gap_2().child(text("First")).child(text("Second"))

<View style={{ direction: "rtl", flexDirection: "row", gap: 8 }}>
  <Text>First</Text>
  <Text>Second</Text>
</View>

#関連項目

• セーフエリアのインセット(Rust では safe_area()、TSX では safeArea()、safeAreaInsets())とソフトウェアキーボード(Rust では keyboard_height()、TSX では keyboardFrame())については、Safe area and keyboardを参照してください。
• スクリーンリーダーとモーション低減の設定については、Accessibilityを参照してください。

#PanResponder

Pan responder は、ジェスチャーレスポンダーシステムの上に構築されたドラッグジェスチャーです。要素がジェスチャーのタッチを占有し、その後はそのタッチだけを、ジェスチャー状態とともに受け取ります。ジェスチャー状態には、タッチの重心、移動距離、速度が含まれ、自動的に追跡されます。Rust のコードでは .claim_touches(TouchClaim::…) でタッチを占有し、.on_responder_* リスナーで受け取ります。リスナーの ResponderEvent は PanGesture を持ち、すべて nsh_core::prelude にあります。TSX では nsh から PanResponder をインポートし、その onPanResponder… コールバックがタッチイベントとジェスチャー状態を受け取ります。

use nsh_core::prelude::*; // TouchClaim, ClaimRequest, ResponderEvent, PanGesture

import { PanResponder, type PanResponderGestureState } from "nsh";

#PanResponder.create

const PanResponder: { create(config: PanResponderCallbacks): PanResponderInstance };

interface PanResponderInstance {
  panHandlers: TouchProps;
}

Pan responder を作成します。ジェスチャーを受け取るビューに panHandlers をスプレッドしてください。Rust では、ビュー自身がタッチを占有し、リッスンします。

use nsh_core::prelude::*;

#[component]
pub fn App() -> impl IntoElement {
    let pos = signal((0.0_f32, 0.0_f32));
    let start = stored((0.0_f32, 0.0_f32));
    view().flex_1().child(
        view()
            .size(px(64.0))
            .rounded(px(32.0))
            .bg(rgb(0x6366f1))
            .style_with(move |s| {
                let (x, y) = pos.get();
                s.translate_x(px(x)).translate_y(px(y))
            })
            .claim_touches(TouchClaim::on_start())
            .on_responder_grant(move |_: &ResponderEvent| {
                start.replace(pos.get_untracked());
            })
            .on_responder_move(move |e: &ResponderEvent| {
                let (x, y) = start.get();
                pos.set((x + e.gesture.delta.x.0, y + e.gesture.delta.y.0));
            })
            .on_responder_release(move |e: &ResponderEvent| {
                log::info!("released at {:.0} pt/s", e.gesture.vx);
            }),
    )
}

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

function App() {
  const pos = signal({ x: 0, y: 0 });
  let start = { x: 0, y: 0 };
  const pan = PanResponder.create({
    onStartShouldSetPanResponder: () => true,
    onPanResponderGrant: () => (start = pos()),
    onPanResponderMove: (_, g) => pos.set({ x: start.x + g.dx, y: start.y + g.dy }),
    onPanResponderRelease: (_, g) => console.log(`released at ${g.vx.toFixed(0)} pt/s`),
  });
  return (
    <View style={{ flex: 1 }}>
      <View
        {...pan.panHandlers}
        style={{
          width: 64,
          height: 64,
          borderRadius: 32,
          backgroundColor: "#6366f1",
          transform: [{ translateX: pos().x }, { translateY: pos().y }],
        }}
      />
    </View>
  );
}

mount(App);

#コールバック

すべてのコールバックは、タッチイベント(GestureResponderEvent、nsh由来)とジェスチャー状態を受け取ります。Rust では、占有の可否を .ask(|request: &ClaimRequest| …) で判断し、タッチを取得するには request.claim() を呼び出します(ask がない場合は常に取得します)。各リスナーは、状態を gesture に持つ ResponderEvent を受け取ります。

type PanHandler<R = void> = (e: GestureResponderEvent, gestureState: PanResponderGestureState) => R;

#PanResponderGestureState

interface PanResponderGestureState {
  stateID: number;
  moveX: number;               // latest centroid of the touches (surface points)
  moveY: number;
  x0: number;                  // the centroid when the responder was granted
  y0: number;
  dx: number;                  // distance moved since the grant
  dy: number;
  vx: number;                  // velocity, points per second
  vy: number;
  numberActiveTouches: number;
}

Rust では PanGesture で、ポイントは Point<Points> です。

#スクロールビュー内

Pan responder がレスポンダーである間は、その周囲のネイティブのスクロールビューはスクロールしません(onShouldBlockNativeResponder のデフォルトは true)。横スワイプと縦スクロールを共存させるには、横方向の移動のときにのみレスポンダーになります。

view()
    .claim_touches(TouchClaim::on_move().ask(|request: &ClaimRequest| {
        let d = request.event.gesture.delta;
        if d.x.0.abs() > 10.0 && d.x.0.abs() > d.y.0.abs() {
            request.claim();
        }
    }))
    .on_responder_move(move |e: &ResponderEvent| offset.set(e.gesture.delta.x.0))
    .on_responder_release(move |e: &ResponderEvent| {
        if e.gesture.delta.x.0.abs() > 120.0 { remove() } else { offset.set(0.0) }
    })
    .on_responder_terminate(move |_: &ResponderEvent| offset.set(0.0))

const swipe = PanResponder.create({
  onMoveShouldSetPanResponder: (_, g) => Math.abs(g.dx) > 10 && Math.abs(g.dx) > Math.abs(g.dy),
  onPanResponderMove: (_, g) => offset.set(g.dx),
  onPanResponderRelease: (_, g) => (Math.abs(g.dx) > 120 ? remove() : offset.set(0)),
  onPanResponderTerminate: () => offset.set(0),
});

プラットフォームが認識するパンについては、TouchClaim::on_pan(PanActivation::horizontal(10.0, 10.0)) が指の動きに合わせてメインスレッドで判断します。基盤となるレスポンダー props(onStartShouldSetResponder、onResponderGrant、onTouchStart など)も、任意の要素で直接使用できます。Elementsを参照してください。

#Clipboard

Clipboard API は、システムのクリップボードの読み書きを行います。テキストはすべての環境で扱え(iOS では UIPasteboard、Android では ClipboardManager、デスクトップでは NSPasteboard、GDK、Win32 クリップボード、Web では navigator.clipboard)、画像は iOS、デスクトップ、Web で、ファイルマネージャーでコピーしたファイルはデスクトップと Mac Catalyst で扱えます。Rust のコードでは nsh_core::prelude の関数(set_clipboard、clipboard_string など)を呼び出します。TSX では nsh から Clipboard をインポートします。

use nsh_core::prelude::*; // set_clipboard, clipboard_string, clipboard_image, ...
use nsh_core::element::ClipboardImage;

import { Clipboard } from "nsh";

const Clipboard: {
  writeText(text: string): Promise<void>;
  readText(): Promise<string>;
  hasText(): Promise<boolean>;
  writeImage(src: string): Promise<void>;
  readImage(): Promise<ClipboardImage | null>;
  hasImage(): Promise<boolean>;
  readFiles(): Promise<string[]>;
};

interface ClipboardImage {
  url: string; // a URL that Image shows and fetch reads
  size: PixelSize; // in pixels
}

Rust の読み取り関数は、タスク内で await する応答を返します(spawn、または async モジュールの関数)。ClipboardImage は nsh_core::element::ClipboardImage で、url と size(Size<DevicePixels>)を持ちます。

画像は、iOS、デスクトップ、Web ではクリップボード経由で扱えます。Android のクリップボードで扱えるのはテキストです。writeImage と readImage は、code が "ERR_FEATURE_UNAVAILABLE_ON_PLATFORM" である Error で reject し、hasImage は false で解決されます。Rust では、set_clipboard_image はクリップボードをそのままにし、clipboard_image は None を返します。

ユーザーは選択可能なテキストから自分でコピーすることもできます。Clipboard API は、コピーボタンのように、コードからコピーする場合のためのものです。

#Clipboard.writeText

writeText(text: string): Promise<void>;

text をクリップボードに置き、元の内容を置き換えます。Rust では set_clipboard(text) です。

use nsh_core::prelude::*;

fn copy_button(code: Signal<String>) -> impl IntoElement {
    let copied = signal(false);
    view()
        .role(AccessibilityRole::Button)
        .on_press(move || {
            set_clipboard(code.get());
            copied.set(true);
        })
        .child(text(move || if copied.get() { "Copied" } else { "Copy" }))
}

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

const copied = signal(false);

<View
  onPress={async () => {
    await Clipboard.writeText(code());
    copied.set(true);
  }}
>
  <Text>{copied() ? "Copied" : "Copy"}</Text>
</View>;

#Clipboard.readText

readText(): Promise<string>;

クリップボードのテキストで解決され、テキストがない場合は "" で解決されます。Rust では clipboard_string() です。iOS では、クリップボードの読み取り時にシステムのペースト通知(「App pasted from …」)が表示されることがあります。Android 10 以降では、フォアグラウンドのアプリだけが読み取れます。画面ごとに読み取るのではなく、ユーザーがペーストを求めたときに読み取ってください。

spawn(async move {
    let pasted = clipboard_string().await;
    if !pasted.is_empty() {
        code.set(pasted.trim().to_string());
    }
});

const pasted = await Clipboard.readText();
if (pasted) code.set(pasted.trim());

#Clipboard.hasText

hasText(): Promise<boolean>;

クリップボードにテキストがあるかどうかを、内容を読み取らずに返して解決されます。iOS ではペースト通知は表示されません。Rust では clipboard_has_string() です。ペーストボタンを表示するかどうかの判断に使います。Web では、ブラウザは読み取らないと判断できないため、ユーザーに許可を求める場合があります。

let can_paste = signal(false);
spawn(async move { can_paste.set(clipboard_has_string().await) });

const canPaste = signal(false);
Clipboard.hasText().then((has) => canPaste.set(has));

#Clipboard.readImage

readImage(): Promise<ClipboardImage | null>;

クリップボードの画像で解決され、画像がない場合は null で解決されます。貼り付けられたスクリーンショットや、ブラウザや画像エディタでコピーされた画像が対象です。Rust では clipboard_image() で、画像がない場合は None です。url は画像の URL(PNG、またはクリップボード自体の JPEG、GIF、WebP、BMP)で、Imageがその src として表示し、fetch が読み取ります。fetch(url) はアップロード用にそのバイト列を返します。size(width と height)は、デコード後のピクセル単位のサイズです。readText と同様に、ユーザーがペーストを求めたときに読み取ってください。最大 48 MB(エンコード後)までの画像が読み取られ、画像はアプリのメモリに収まります。それより大きい画像は、code が "ERR_NSH_QUOTA_EXCEEDED" である Error で reject されます(メッセージには画像のサイズと上限が含まれます)。一方、hasImage は true で解決されます。Rust では、clipboard_image() がこの場合に None を返します。

use base64::Engine as _;
use nsh_core::{element::ClipboardImage, prelude::*};

fn attachments() -> impl IntoElement {
    let attachments = signal(Vec::<ClipboardImage>::new());
    let paste = move || {
        spawn(async move {
            if let Some(image) = clipboard_image().await {
                attachments.update(|list| list.push(image));
            }
        });
    };
    view()
        .flex_row()
        .gap_2()
        .child(text("Paste").on_press(paste))
        .child(each(
            attachments,
            |shot: &ClipboardImage| shot.url.clone(),
            |shot, _| image(move || shot.with(|s| s.url.clone())).size(px(64.0)).rounded(px(8.0)),
        ))
}

async fn upload(image: &ClipboardImage) -> Result<HttpResponse, String> {
    let (_, data) = image.url.split_once(',').ok_or("not a data: URL")?;
    let bytes = base64::engine::general_purpose::STANDARD
        .decode(data)
        .map_err(|e| e.to_string())?;
    let request = HttpRequest::post("https://example.com/upload", bytes).header("Content-Type", "image/png");
    fetch(request).await
}

import { Image, signal, View } from "nsh";
import { Clipboard, type ClipboardImage } from "nsh";

const attachments = signal<ClipboardImage[]>([]);

async function paste() {
  const image = await Clipboard.readImage();
  if (image) attachments.set([...attachments(), image]);
}

async function upload(image: ClipboardImage) {
  const body = new FormData();
  body.append("file", await (await fetch(image.url)).blob(), "screenshot.png");
  await fetch("https://example.com/upload", { method: "POST", body });
}

<View class="flex-row gap-2">
  <Each of={attachments()}>
    {(image) => <Image src={image().url} style={{ width: 64, height: 64, borderRadius: 8 }} />}
  </Each>
</View>;

ユーザーがコンポーザーにスクリーンショットを貼り付けるチャット形式のアプリでは、入力欄にフォーカスがある間ペーストのショートカットをバインドし、画像があればそれを取得します。

use nsh_core::keymap::When;

on_key_with("mod+v", KeyOptions { when: When::Always, ..KeyOptions::default() }, move |_| {
    spawn(async move {
        if clipboard_has_image().await {
            paste().await;
        } else {
            insert_text(&clipboard_string().await);
        }
    });
});

import { keymap } from "nsh";

keymap.bind("mod+v", async () => {
  if (await Clipboard.hasImage()) return paste();
  insertText(await Clipboard.readText());
}, { when: "always" });

#Clipboard.hasImage

hasImage(): Promise<boolean>;

クリップボードに画像があるかどうかを、内容を読み取らずに返して解決されます。iOS ではペースト通知は表示されません。Rust では clipboard_has_image() です。Android では false で解決されます。

#Clipboard.writeImage

writeImage(src: string): Promise<void>;

src(base64 の data: URL、または readImage が返した url)の画像をクリップボードに置き、元の内容を置き換えます。Rust では set_clipboard_image(src) です。Windows では PNG を受け付けます。これはブラウザ、Office、Snipping Tool が読み取る形式です。Android では "ERR_FEATURE_UNAVAILABLE_ON_PLATFORM" で reject されます。

set_clipboard_image(image.url.clone());

await Clipboard.writeImage(image.url);

#Clipboard.readFiles

readFiles(): Promise<string[]>;

ファイルマネージャー(Finder、Explorer、Files)でコピーされたファイルとフォルダの file: URL を、その順序のまま返して解決されます。何もなければ [] で解決されます。これらはファイルドロップが返すものと同じ URL です。Rust では clipboard_files() です。パスを取得するには URL をパースしてください。

let paths: Vec<std::path::PathBuf> = clipboard_files()
    .await
    .iter()
    .filter_map(|file| url::Url::parse(file).ok()?.to_file_path().ok())
    .collect();

const files = await Clipboard.readFiles();
const names = files.map((url) => decodeURIComponent(new URL(url).pathname.split("/").pop()!));

#Picker

picker API は、システムの写真ピッカーを表示し、ユーザーが選んだ画像をアプリに渡します。iOS では Photos ピッカー(PHPickerViewController)、Android では Photo Picker、デスクトップでは open panel またはファイルダイアログ、ブラウザーではファイル入力を使います。iOS と Android ではピッカーはアプリの外で動作し、ユーザーが選んだものだけを渡すため、フォトライブラリの権限は不要です。選ばれた各画像は File(TSX)または PickedFile(Rust)として届き、そのバイト列はネイティブ側に残ります。URL.createObjectURL(file) で Image に表示し、fetch と FormData でアップロードします。Rust コードは nsh_core::prelude の pick_images を呼び出し、TSX は nsh から Picker をインポートします。

use nsh_core::picker::{PickRequest, PickedFile};
use nsh_core::prelude::*; // pick_images

import { Picker, type PickedImage } from "nsh";

const Picker: {
  pickImages(options?: PickImagesOptions): Promise<PickedImage[]>;
};

interface PickImagesOptions {
  multiple?: boolean; // let the user pick several (false: one)
  limit?: number; // at most this many when multiple (up to 100)
  maxDimension?: number; // scale images whose longer side is longer, in pixels
  quality?: number; // JPEG quality from 0 to 1 (0.9)
  format?: "compatible" | "current"; // "compatible": HEIC and the like as JPEG
}

interface PickedImage {
  file: File; // name, type, size in bytes and the bytes
  size: PixelSize; // upright
}

#Picker.pickImages

pickImages(options?: PickImagesOptions): Promise<PickedImage[]>;

ピッカーを表示し、ユーザーが選んだ画像を選んだ順に解決します。ユーザーがキャンセルした場合は [] で解決します。Rust: pick_images(request)。タスク(spawn、または async モジュール関数)内で await する応答です。pickImages は決して throw しません。範囲外のオプション(limit: 0、0〜1 の範囲外の quality)は RangeError で promise を reject し、アプリの capability が許可していない pick は ERR_ACCESS_DENIED で reject します(後述)。キャンセルはユーザーの回答であり失敗ではないため、[] で解決します。

画像はそのまま送信できる状態で届きます。

• あらゆるブラウザーとサーバーが扱える形式。 JPEG、PNG、GIF、WebP はそのまま届き、別の形式(iPhone の HEIC、HEIF、TIFF)で保存された写真は JPEG として届きます。format: "current" は保存された形式を保持します。
• ネイティブでの縮小。 maxDimension を指定すると、長辺がそれを超える画像は収まるように縮小され、向きを正した上で再エンコードされます。PNG は PNG、それ以外は quality の JPEG になります。スマートフォンの写真は 12〜48 メガピクセルありますが、アップロード前に 2048 ピクセルへ縮小すると数百キロバイトになります。quality を指定した場合も JPEG は再エンコードされます。
• 表示されるとおりの情報。 size は、カメラの向きを適用した、表示されるとおりの画像のピクセル単位のサイズです。NSH が再エンコードした画像にはメタデータ(位置情報)が含まれません。そのまま届く画像は元のメタデータを保持します。

Windows、Linux、および GPUI ウィンドウでは、ダイアログにリクエストが受け付ける形式("compatible" では JPEG、PNG、GIF、WebP)が表示され、ファイルは保存されたまま、元のサイズで届きます。

チャットの入力欄で写真を添付し、メッセージを書いている間それを表示し、送信時にアップロードする例です。

use nsh_core::geometry::{DevicePixels, Percentage};
use nsh_core::picker::{PickRequest, PickedFile};
use nsh_core::prelude::*;

fn attach_button(attached: Signal<Option<PickedFile>>) -> impl IntoElement {
    view()
        .role(AccessibilityRole::Button)
        .accessibility_label("Choose a photo")
        .on_press(move || {
            let mut request = PickRequest::new(false, 1);
            request.max_dimension = Some(DevicePixels(2048));
            request.quality = Some(Percentage(0.85));
            let picked = pick_images(request);
            spawn(async move {
                if let Some(file) = picked.await.into_iter().next() {
                    attached.set(Some(file));
                }
            });
        })
        .child(text("Photo"))
}

async fn upload(file: &PickedFile) -> Result<HttpResponse, String> {
    let request = HttpRequest::post("https://example.com/upload", file.data.to_vec())
        .header("Content-Type", file.mime.as_str());
    fetch(request).await
}

import { Image, signal, Text, View } from "nsh";
import { Picker } from "nsh";

const attached = signal<{ file: File; src: string } | null>(null);

async function choosePhoto() {
  const [picked] = await Picker.pickImages({ maxDimension: 2048, quality: 0.85 });
  if (picked) attached.set({ file: picked.file, src: URL.createObjectURL(picked.file) });
}

async function send(text: string) {
  const body = new FormData();
  body.append("text", text);
  if (attached()) body.append("photo", attached()!.file);
  await fetch("https://example.com/messages", { method: "POST", body });
  if (attached()) URL.revokeObjectURL(attached()!.src);
  attached.set(null);
}

<View class="flex-row items-center gap-2">
  <View role="button" accessibilityLabel="Choose a photo" onPress={choosePhoto}>
    <Text>Photo</Text>
  </View>
  <If when={attached()}>
    <Image src={attached()!.src} style={{ width: 48, height: 48, borderRadius: 8 }} />
  </If>
</View>;