nsh

nsh ist das Kernmodul: die reaktive API (Signals, Computed Values, Effects, Context), mount, token, die Host-Elemente View, Text, Scroll und Overlay, auswählbare Views, die Safe Area und die Tastatur, Animation, das Gerät und seine Umgebung, PanResponder, die Zwischenablage, den Foto-Picker, die Spracherkennung, Storage, den Host-Kanal, Tastenkürzel, native Komponenten und Module, Barrierefreiheit sowie die TypeScript-Typen von Elementen, Styles und Events. Der reaktive Graph selbst läuft nativ in Rust; das Lesen eines Signals ist ein Aufruf in die Runtime, der wenige Nanosekunden kostet, und nur deine eigenen Closures laufen im JavaScript-Interpreter.

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

Die Reaktivität von NSH folgt demselben Modell wie SolidJS: Eine Komponentenfunktion läuft einmal, und die Teile der UI, die Signals lesen, werden an Ort und Stelle aktualisiert, wenn sich diese Signals ändern. Es gibt weder ein erneutes Rendern der Komponente noch ein Virtual DOM. Den Leitfaden findest du unter Reaktivität.

#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);
}

Ein Signal hält einen Wert. Ein Aufruf liest den Wert und abonniert dabei, innerhalb eines Tracking-Scopes (JSX-Ausdrücke, computed, effect), diesen Scope darauf. set und update schreiben es; alles, was es gelesen hat, wird aktualisiert.

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);

Standardmäßig bewirkt ein Schreibvorgang, der === zum aktuellen Wert ist, nichts. Übergib equals: false, um bei jedem Schreibvorgang zu benachrichtigen (nützlich, wenn du ein Objekt direkt veränderst und dasselbe Objekt erneut setzt), oder einen eigenen Vergleich:

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;
}

Ein aus Signals abgeleiteter Wert. fn läuft erneut, wenn sich ein gelesenes Signal ändert; Leser des Computed Value werden nur aktualisiert, wenn sich sein Ergebnis ändert (verglichen mit equals, standardmäßig ===). fn erhält das vorherige Ergebnis.

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

Verwende computed, wenn eine Ableitung aufwendig ist oder an mehreren Stellen gelesen wird. Bei einem günstigen Ausdruck ist eine einfache Funktion (const full = () => first() + " " + last()) genauso reaktiv.

#effect

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

Führt fn nach dem Rendern aus und erneut, sobald sich ein gelesenes Signal ändert. Verwende Effects für Seiteneffekte: Logging, Timer, Kommunikation mit nativen Modulen. Ein Effect gehört zu der Komponente (oder dem Effect), in der er erstellt wurde, und wird mit ihr entsorgt.

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

Um etwas rückgängig zu machen, bevor der Effect erneut läuft (oder wenn seine Komponente verschwindet), rufe darin cleanup auf.

#batch

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

Führt fn aus und wendet alle Schreibvorgänge gebündelt am Ende an, sodass Leser einmal statt einmal pro Schreibvorgang aktualisiert werden. Gibt zurück, was fn zurückgibt.

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

#untracked

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

Führt fn aus, ohne den aktuellen Scope auf das Gelesene zu abonnieren. Verwende es, um ein Signal in einem Effect oder JSX-Ausdruck zu lesen, ohne davon abhängig zu werden.

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

#cleanup

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

Registriert fn, damit es läuft, bevor der aktuelle Effect erneut läuft oder wenn die aktuelle Komponente bzw. der aktuelle Effect verschwindet.

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;
}

Ein Wert, den eine Komponente allem bereitstellt, was sie rendert, egal wie tief. Der Aufruf des Context (Theme()) liest den Wert des nächstgelegenen Providers, ohne Provider dagegen 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;

Rendert app in die Surface (das Fenster oder den NshAppView / NshView, in den die App eingebettet ist) und gibt eine Funktion zurück, die es wieder entfernt. Die Einstiegsdatei jeder App endet mit 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]>];

Teilt ein Props-Objekt in die in keys genannten Props und den Rest auf. Beide Hälften bleiben reaktiv: Props, deren Werte sich ändern, sind Getter, und split behält sie als Getter. Verwende es in einer Komponente, die einige Props selbst verarbeitet und die übrigen weitergibt. Destrukturieren von Props (const { label } = props) würde sie einmal lesen und Aktualisierungen verlieren.

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;

Rendert seine Children oder fallback, sobald darunter etwas einen Fehler wirft: der Body einer Komponente, ein Binding, ein Effect oder ein Event-Handler. Der fehlgeschlagene Teil wird entfernt, und an seiner Stelle erscheint der Fallback. Eine Funktion fallback wird als fallback(error, reset) aufgerufen, mit dem geworfenen Wert und reset, das die Children erneut rendert, unabhängig davon, welche Parameter sie deklariert; ein fallback-Element wird unverändert angezeigt. Ein Fehler geht an die nächste Boundary darüber, und ein Fehler in einem Fallback an die Boundary darüber. Rust-Komponenten verwenden catch_error (Error Boundaries).

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];

Das Design-Token name des Themes der App ("theme" in nsh.json, über den Tokens von shadcn/ui) in der angezeigten Darstellung: eine Farbe als #rrggbbaa, eine Länge als Anzahl von Punkten, eine Schrift als ihr Familienname. Die Namen sind die CSS-Variablen des Themes ohne -- (primary, muted-foreground, radius, font-mono und die eigenen der App, etwa up). Das Lesen ist reaktiv: Eine Komponente, ein Memo oder ein Effect, das bzw. der ein Token liest, läuft erneut, wenn sich das Theme oder die Darstellung ändert. Tokens listet die Tokens der App mit ihren Typen auf; NSH schreibt es aus dem Theme nach .nsh/types/nsh/tokens.d.ts. Für Klassen benennst du die Tokens direkt (bg-primary, rounded-(--radius)): Theme-Tokens.

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;

Die Host-Elemente, die nsh exportiert, als Tags geschrieben: <View>, <Text>, <Scroll>, <Overlay> (seine Children liegen über dem Fenster und werden an einem Anker ausgerichtet: Overlay). Der Compiler erzeugt die native View direkt an Ort und Stelle für ein Tag, das über seinen Import eines davon benennt (auch per Alias), sodass das Importieren zur Laufzeit nichts kostet. Sie sind Komponenten wie alle anderen und können daher auch herumgereicht werden (const Tag = inline ? Text : View). nsh exportiert die übrigen Primitive auf dieselbe Weise: List, Image, Canvas, WebView und Video, jeweils mit eigener Referenzseite. Ihre Props sind unter Elemente dokumentiert. Das Texteingabefeld, Input, stammt aus nsh/base.

#Safe Area und Tastatur

Die Umgebungsvariablen von CSS halten Inhalte frei von der System-UI, im Padding und Margin jeder View (padding, paddingTop, …, dieselben margin-Schlüssel; die beliebigen Werte p* / m* von Tailwind; die Styled-Methoden .p_safe_area(), .pt_safe_area_plus(..), .pb_keyboard(), … in Rust). Ihre Werte sind EnvValues: env(name), env(name, <length>), calc(env(name) + <length>) und calc(<length> + env(name)).

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

#safeArea und safeAreaInsets

safeArea() ist die Safe Area der Surface (safe_area() in Rust); safeAreaInsets() die Insets dort, wo eine Komponente gerendert wird (cx.insets() in Rust), die Werte der safe-area-inset-*-Variablen. Beide sind reaktive Edges ({ top, right, bottom, left } in Punkten). Siehe safeArea und safeAreaInsets.

#Tastatur und keyboardFrame

Keyboard.dismiss() blendet die Software-Tastatur aus (dismiss_keyboard() in Rust), und keyboardFrame() zeigt dir, wie viel vom Bildschirm sie verdeckt (keyboard_height() und keyboard_duration() in Rust). Siehe Die Tastatur ausblenden und Die Höhe der Tastatur.

#Auswählbare Views

<View selectable> (view().selectable(true) in Rust) sorgt dafür, dass die darin enthaltenen Texte gemeinsam ausgewählt werden, wie auf einer Webseite: Eine Auswahl läuft in Lesereihenfolge über Views, Text-Elemente und TextViews hinweg. Siehe Textauswahl.

#Animation

Die Animations-API animiert auf dem UI-Thread. Du erstellst einen animierten Wert, bindest ihn (oder davon abgeleitete Werte) an eine Style-Eigenschaft und startest eine Animation; ab dann wird jeder Frame nativ berechnet, ohne dass Code der App läuft. Eine ausgelastete Engine oder ein ausgelasteter JS-Thread kann die Animation nicht ruckeln lassen, und eine Animation verursacht der App keinen Aufwand pro Frame. Rust-Code verwendet animated_value(), motion(), Animation, Spring, Timing, KeyframeTiming, MotionPreset und Easing aus nsh_core::prelude und bindet Werte mit den .bind_*-Methoden von Elementen; TSX importiert sie aus 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";

Den Leitfaden findest du unter Animation.

#Was ein animierter Wert steuern kann

Andere Style-Eigenschaften nehmen einfache Werte an; um das Layout selbst zu animieren (Größen, Positionen im Fluss), verwende LayoutAnimation.

#createAnimatedValue

function createAnimatedValue(value?: number): AnimatedValue;

Erstellt einen animierten Wert, der bei value startet (Standard 0). Rust: animated_value(value), ein Copy-Handle, das von der Komponente gehalten wird, die ihn erzeugt hat.

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 }>;
}

Jede Animationsmethode gibt ein Promise zurück, das mit { finished } aufgelöst wird: true, wenn die Animation beendet wurde, false, wenn sie gestoppt wurde (durch stop, set oder eine andere Animation desselben Werts). In Rust gibt sie ein AnimationEnd zurück, das ein Task für dasselbe bool erwartet.

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";

Ein Node des nativen Animationsgraphen: ein AnimatedValue oder ein aus anderen abgeleiteter Wert. Abgeleitete Nodes werden auf dem UI-Thread ausgewertet, sobald sich ihre Eingaben ändern.

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) spielt einen Wert durch Keyframes ab und wird mit { finished } aufgelöst, das angibt, ob sie abgeschlossen wurden; Animated.keyframes(value, { keyframes, ...options }) entspricht einem Schritt einer Komposition. Rust: value.keyframes(frames, KeyframeTiming) und Animation::keyframes(&value, frames, KeyframeTiming) mit Keyframe::new(value) (gleichmäßig verteilt), Keyframe::at(offset, value) und .ease(easing) sowie KeyframeTiming::new(ms) mit .delay(ms), .easing(e), .iterations(Some(n)), .infinite() und .direction(PlaybackDirection::…).

Sie werden abgespielt wie CSS-Keyframes: Ein Easing formt ein Segment (das eines Keyframes ist das Segment, das bei ihm beginnt, das des Timings jedes andere); in Keyframes fehlende Offsets werden gleichmäßig verteilt, der erste bei 0 und der letzte bei 1; jede Iteration beginnt mit einem Sprung zu ihrem ersten Keyframe, und ohne Keyframe bei 0 geht der Wert von seiner aktuellen Position aus; während eines delay hält der Wert den ersten Keyframe (CSS animation-fill-mode: backwards); rückwärts laufende Iterationen spielen die Segmente rückwärts mit umgekehrten Kurven ab; der Wert bleibt dort, wo die letzte Iteration ihn zurücklässt.

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;
}

Erzeugt eine Motion: pro Kanal von Deckkraft und Transform einer View einen animierten Wert, im Ruhezustand (Deckkraft und Skalierungen 1, die übrigen 0), sowie Motions, die nativ darauf abgespielt werden. Binde sie mit style={motion.style} oder verteile motion.style oder motion.transform in einen Style; der Transform wendet zuerst seine Translationen an, dann seine Rotationen, dann seine Skalierungen, wobei scale in scaleX und scaleY eingerechnet wird: 7 der 8 Transform-Schritte einer View, sodass einer für deinen eigenen bleibt ([{ perspective: 600 }, ...motion.transform] für 3D-Flips). initial legt fest, wo die Kanäle beginnen ({ opacity: 0 }; die übrigen beginnen im Ruhezustand). Mit enter beginnen die Kanäle, die sie bewegt, dort, wo diese Motion beginnt (über initial), und sie wird sofort abgespielt, wobei die übrigen Optionen ihr Timing bilden (delay, duration, …). Eine Motion bewegt nur Deckkraft und Transform: Das Verteilen von motion.style setzt das opacity der View, binde daher nur motion.transform, um eine eigene Deckkraft zu behalten, und bewege Farben mit einem animierten Wert und interpolate. Rust: motion(), ein Copy-Handle, das die Komponente hält, die es erzeugt hat, gebunden mit .bind_motion(&m); motion().entering(spec) tritt ein.

Wenn der Nutzer weniger Bewegung wünscht (reduceMotion()), landen play, animation und enter sofort dort, wo die Bewegung endet, ohne sich zu bewegen, es sei denn, ignoreReduceMotion ist gesetzt (an den Optionen oder an der Motion).

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";
}

Die vorgefertigten Motions als Daten: motion.play("shake") spielt motions.shake ab. MotionName ist eines von fadeIn, fadeInUp, fadeInDown, fadeInLeft, fadeInRight, zoomIn, popIn, bounceIn, slideInUp, slideInDown, flipInX, flipInY (Eintritt); fadeOut, fadeOutUp, fadeOutDown, fadeOutLeft, fadeOutRight, zoomOut, popOut, slideOutDown, slideOutUp (Austritt); shake, headShake, wiggle, swing, pulse, heartbeat, rubberBand, jello, tada, jump, flash (Aufmerksamkeit); spin, float, breathe, sway, bob, glow (Schleife). Animation beschreibt jede einzelne. Per Spread lässt sich ein Preset ändern: motion.play({ ...motions.fadeInUp, duration: 600 }).

Eine MotionSpec ist eine eigene Motion: die Keyframes jedes Kanals ({ opacity: [0, 1], translateY: [24, 0] }) oder eine Liste von Frames, wie die Web Animations API sie schreibt ([{ opacity: 0, translateY: 24 }, { opacity: 1, translateY: 0 }], wobei ein Frame ohne Offset anhand seiner Position in der Liste platziert wird), mit dem Keyframe-Timing. Rust: MotionSpec::new(KeyframeTiming) mit .values(channel, values) (gleichmäßig verteilt), .track(channel, keyframes) und .timing(|t| …); MotionPreset::FadeInUp (oder .spec()) ist ein Preset, und MotionChannel benennt die Kanäle.

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 baut Animationen aus Schritten auf (timing, spring, decay, sequence, parallel, …). Nichts läuft, bis start() aufgerufen wird; dann läuft der gesamte Baum nativ, und jeder Schritt startet im UI-Thread genau in dem Moment, in dem der vorherige endet (keine Frame-Lücke, kein Roundtrip zum Code der App zwischen den Schritten). Rust baut denselben Baum mit 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;
};

Ein Easing sind Daten, keine Funktion der App: Die Runtime wertet es nativ aus. In Rust ist es das Enum Easing: Linear, EaseIn, EaseOut, EaseInOut, Bezier(x1, y1, x2, y2), Steps(count, StepPosition) und Curve(curve, mode), mit einem Curve (Quad, Cubic, Poly(n), Sin, Circle, Exp, Elastic(bounciness), Back(s), Bounce) und einem EaseMode (In, Out, InOut). Zum Zeichnen liefert Easing.sample(easing, count) (Rust: nsh_core::element::sample_easing) seine Werte an count gleichmäßig verteilten Punkten von 0 bis 1; Animated.sampleSpring und Animated.sampleDecay (sample_spring, sample_decay) liefern die Werte einer Spring- bzw. Decay-Animation, einen pro Frame (bei fps, standardmäßig 60), ab from (0) bis zu ihrem Ende. Alle drei stammen aus dem nativen Code, in dem die Animationen laufen. Überall, wo in TSX ein Easing akzeptiert wird, kannst du einen Namen ("easeOut"), eine kubische Bézier-Kurve als vier Zahlen oder eine Kurve aus dem Objekt Easing übergeben.

Easing.steps(count, position) entspricht CSS steps(): Der Wert springt zwischen count Stufen, statt sich zu bewegen (ein Sprite Frame für Frame, ein tickender Zeiger). position legt fest, wo die Sprünge liegen: "jump-end" (Standard, auch "end"), "jump-start" ("start"), "jump-none" oder "jump-both"; Rust: Easing::Steps(count, StepPosition::JumpEnd), JumpStart, JumpNone, JumpBoth.

Die Kurven liegen in ihrer „in“-Form vor (langsam am Anfang). Easing.out(curve) kehrt eine um, Easing.inOut(curve) macht sie symmetrisch, Easing.in(curve) belässt sie unverändert; in Rust ist das der EaseMode von Easing::Curve.

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) animiert die Layout-Änderungen des nächsten Commits nativ: Views, die sich bewegen oder ihre Größe ändern, gleiten zu ihren neuen Frames, neue Views erscheinen (blenden ein oder skalieren ein, je nach property) und entfernte Views verschwinden. Rufe es direkt vor der Zustandsänderung auf, die das Layout ändert. Rust: animate_layout(LayoutAnimation) mit den Presets von nsh_core::element::LayoutAnimation oder dessen Übergängen create, update und 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

Die Device-API informiert die App über das Gerät und seine Umgebung. Rust-Code ruft die Funktionen von nsh_core::prelude auf (window(), dark(), font_scale(), locale(), lifecycle(), os(), idiom(), pixel_ratio(), set_color_scheme(), …); TSX importiert sie aus nsh. Die Fenstergröße, das Farbschema, die Schriftskalierung, das Pixelverhältnis, die Locale und der App-Zustand sind reaktiv: Lies sie in einem Binding (in Rust eine Closure, die an ein Element übergeben wird, in TSX JSX), computed oder effect, und alles, was sie liest, wird aktualisiert, wenn die Plattform eine Änderung meldet (Drehung, Größenänderung des Fensters, Wechsel in den Dark Mode, Änderung der Textgröße oder der Sprache, Wechsel auf einen Bildschirm mit anderer Dichte, Verlassen der App und Rückkehr).

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";

Den Leitfaden findest du unter Gerät und Umgebung.

#windowSize

const windowSize: Accessor<Size>;

Die Größe der Fläche in Punkten: das Fenster oder die eingebettete NshAppView / NshView. Reaktiv. 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">;

Das angezeigte Erscheinungsbild: das des Systems, sofern die App kein eigenes festgelegt hat (nsh.json "appearance", setColorScheme). Reaktiv. Rust: dark() -> bool; Theme-Farben (AdaptiveColor) und die Style-Variante .dark(…) folgen ihm, ohne es zu lesen. Auch die Variante dark: von Tailwind folgt ihm (siehe 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>;

Die bevorzugte Textgröße des Nutzers relativ zum Standard (1 ist die Standardgröße; Dynamic Type unter iOS, Schriftgröße unter Android) oder stattdessen die Textgröße, die die einbettende App festlegt. Reaktiv. Rust: font_scale() -> f32. Text skaliert bereits damit, außer bei allowFontScaling={false}; lies sie, wenn andere Größen folgen sollen, etwa Icons neben Text.

#locale

const locale: Accessor<string>;

Die Locale des Nutzers als BCP-47-Tag ("en-US", "zh-Hans-CN") oder stattdessen die Locale, die die einbettende App festlegt. Reaktiv. Rust: locale() -> Locale (locale().as_str() ist der Tag). Intl formatiert standardmäßig dafür; lies sie, um die Strings deiner eigenen Übersetzungen auszuwählen (Gerät und Umgebung).

#lifecycle

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

Ob die App in Benutzung ist, in den Begriffen von React Native AppState: "active" im Vordergrund und Eingaben entgegennehmend, "inactive" solange sie sichtbar ist, aber nicht den Fokus hat (eine andere App oder ein anderes Fenster hat ihn, oder das System zeigt etwas darüber an, etwa den App-Umschalter oder einen eingehenden Anruf), "background" solange sie nicht sichtbar ist (im Hintergrund, minimiert, ein verborgener Browser-Tab). Eine App, die innerhalb einer nativen App angezeigt wird, folgt deren Zustand. Reaktiv. Rust: lifecycle() -> Lifecycle (Lifecycle::Active, Inactive, Background).

Lies es in einem Effect, um Arbeit zu pausieren, die niemand sieht, und sie fortzusetzen, wenn die App zurückkommt:

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;

Zeigt die App sofort in scheme an, unabhängig vom Erscheinungsbild des Systems: colorScheme(), dark:-Klassen, das Theme der Komponenten und die Steuerelemente der Plattform (Alerts, der Standardstil der Statusleiste) folgen ihm; "system" folgt wieder dem System. nsh.json "appearance" legt es von Anfang an fest. 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;
}

Die Plattform, auf der die App läuft; sie bleibt konstant, solange die App läuft.

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;
}

Gibt den Wert für das aktuelle OS zurück (ios, android, web, …), sonst desktop oder mobile (je nach platform.desktop), sonst native (jede Plattform außer dem Web), sonst default, sonst undefined. Rust-Code matcht auf os() (und is_desktop() für mobile / 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>;

Geräte-Pixel pro Punkt (z. B. 3 auf den meisten iPhones). Reaktiv: Der Wert ändert sich, wenn das Fenster auf einen Bildschirm mit anderer Dichte wechselt (auf Mac Catalyst, den Desktops oder einem externen Display) und wenn die Einstellung für die Anzeigegröße von Android die Dichte ändert. Rust: pixel_ratio() -> f32 und round_to_nearest_pixel(points) für eine Länge in ganzen Geräte-Pixeln; in TSX ist diese Länge 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;
}

Öffnet url außerhalb der App: eine Webseite im Browser, einen mailto:-Link in der Mail-App, einen tel:-Link in der Telefon-App und jedes Schema, das eine andere App registriert hat (maps:, die eigenen lb://-Links einer Host-App). Es wird mit { opened } aufgelöst, also damit, ob etwas es geöffnet hat: false, wenn keine App das Schema behandelt. Rust: open_url(url) von nsh_core::prelude, eine Antwort, die man in einem Task awaitet (oder verwirft), dasselbe 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>

• Die URL ist absolut (sie hat ein Schema). URLs, die Code ausführen oder auf die eigenen Daten der App zugreifen würden, javascript:, data:, blob:, file:, about: und asset:, lehnen das Promise mit einem TypeError ab, ebenso relative Adressen. openUrl wirft nie: Jeder Fehler lehnt ab.
• Eine App, die Capabilities deklariert, braucht openUrl: "openUrl": true für jedes Schema oder "openUrl": { "schemes": ["https", "mailto"] } für die aufgeführten; andere URLs lehnen mit einem Error ab, dessen code "ERR_ACCESS_DENIED" ist, permission "openUrl" und resource die URL (siehe Sandbox und Capabilities). In Rust antwortet open_url dafür mit false und protokolliert den Grund.
• Die einbettende App sieht die URL zuerst und kann sie stattdessen über ihren eigenen Router leiten (Swift NshAppView.onOpenURL, Java NshView.setOpenUrlHandler, Rust AppView::host().handle_open_url; siehe iOS und Android). opened ist dann true.
• Jede Plattform öffnet sie mit ihrem eigenen Opener: UIApplication.open auf iOS (die Application der Host-App, wenn eingebettet), ein ACTION_VIEW-Intent auf Android, NSWorkspace auf macOS, ShellExecuteW auf Windows, GtkUriLauncher auf Linux, open_url von GPUI, ein neuer Tab im Web. nsh test zeichnet die URLs auf, statt sie zu öffnen.
• Ein TextView öffnet seine Links auf diese Weise mit links="open".

#Layout-Richtung

Die Layout-Richtung folgt der Sprache des Benutzers: In einer Rechts-nach-links-Sprache (Arabisch, Hebräisch, …) wird die App von rechts nach links angeordnet, Zeilen beginnen rechts, und die Style-Eigenschaften left / right (marginLeft, paddingRight, …) bedeuten Anfang und Ende. Änderungen wirken sofort, ohne Neustart.

Der Style direction einer View ("ltr", "rtl" oder "inherit", der Standard) legt die Richtung ihres eigenen Teilbaums fest; in 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>

#Siehe auch

• Safe-Area-Insets (Rust safe_area(); TSX safeArea(), safeAreaInsets()) und die Software-Tastatur (Rust keyboard_height(); TSX keyboardFrame()) stehen unter Safe Area und Tastatur.
• Einstellungen für Screenreader und reduzierte Bewegung stehen unter Barrierefreiheit.

#PanResponder

Pan Responder sind Drag-Gesten auf dem Gesture-Responder-System: Das Element beansprucht die Touches einer Geste und hört sie dann allein, zusammen mit dem Gesture-State, der den Schwerpunkt der Touches, die zurückgelegte Distanz und die Geschwindigkeit automatisch nachverfolgt. Rust-Code beansprucht sie mit .claim_touches(TouchClaim::…) und empfängt sie mit .on_responder_*-Listenern, deren ResponderEvent einen PanGesture trägt, alles in nsh_core::prelude; TSX importiert PanResponder aus nsh, dessen onPanResponder…-Callbacks das Touch-Event und den Gesture-State erhalten.

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;
}

Erstellt einen Pan Responder. Sein panHandlers wird per Spread auf die View gesetzt, die die Geste erhalten soll. In Rust beansprucht die View die Touches und hört selbst zu:

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);

#Callbacks

Jeder Callback erhält das Touch-Event (GestureResponderEvent, aus nsh) und den Gesture-State. In Rust entscheidet ein Claim mit .ask(|request: &ClaimRequest| …) und ruft request.claim() auf, um die Touches zu übernehmen (ohne ask übernimmt er sie immer), und jeder Listener erhält einen ResponderEvent, dessen gesture der State ist.

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, mit Punkten als Point<Points>.

#In Scroll Views

Solange ein Pan Responder der Responder ist, scrollen native Scroll Views um ihn herum nicht (onShouldBlockNativeResponder ist standardmäßig true). Damit ein horizontaler Swipe mit vertikalem Scrollen koexistieren kann, wird die View nur bei horizontalen Bewegungen zum Responder:

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),
});

Bei einem Pan, den die Plattform erkennt, entscheidet TouchClaim::on_pan(PanActivation::horizontal(10.0, 10.0)) im Main-Thread, während sich die Finger bewegen. Die zugrunde liegenden Responder-Props (onStartShouldSetResponder, onResponderGrant, onTouchStart, …) lassen sich auch direkt auf jedem Element verwenden; siehe Elemente.

#Clipboard

Die Clipboard-API liest und schreibt die System-Zwischenablage: Text überall (UIPasteboard auf iOS, ClipboardManager auf Android, NSPasteboard, GDK und die Win32-Zwischenablage auf Desktops, navigator.clipboard im Web), Bilder auf iOS, den Desktops und im Web sowie die in einem Dateimanager kopierten Dateien auf den Desktops und Mac Catalyst. Rust-Code ruft die Funktionen von nsh_core::prelude auf (set_clipboard, clipboard_string, …); TSX importiert Clipboard aus nsh.

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
}

Die Rust-Lesefunktionen liefern Antworten, die man in einem Task awaitet (spawn oder eine Modulfunktion von async); ClipboardImage ist nsh_core::element::ClipboardImage, mit url und size (ein Size<DevicePixels>).

Bilder laufen auf iOS, den Desktops und im Web über die Zwischenablage. Auf Android enthält die Zwischenablage Text: writeImage und readImage lehnen mit einem Error ab, dessen code "ERR_FEATURE_UNAVAILABLE_ON_PLATFORM" ist, und hasImage wird mit false aufgelöst. In Rust lässt set_clipboard_image dort die Zwischenablage unverändert, und clipboard_image antwortet None.

Der Benutzer kann auch selbst aus einem auswählbaren Text kopieren; die Clipboard-API dient dem Kopieren aus Code, etwa für einen Kopieren-Button.

#Clipboard.writeText

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

Legt text in die Zwischenablage und ersetzt deren bisherigen Inhalt. 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>;

Wird mit dem Text der Zwischenablage aufgelöst, oder mit "", wenn sie keinen enthält. Rust: clipboard_string(). Auf iOS kann das Lesen der Zwischenablage den System-Hinweis zum Einfügen anzeigen („App pasted from …“), und auf Android 10 und höher kann nur die App im Vordergrund sie lesen. Sie sollte gelesen werden, wenn der Benutzer das Einfügen anfordert, nicht auf jedem Screen.

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>;

Wird damit aufgelöst, ob die Zwischenablage Text enthält, ohne ihn zu lesen: kein Einfüge-Hinweis auf iOS. Rust: clipboard_has_string(). Damit lässt sich entscheiden, ob ein Einfügen-Button angezeigt wird. Im Web erfahren Browser es nur durch Lesen, daher kann dabei der Benutzer um Erlaubnis gefragt werden.

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>;

Wird mit dem Bild der Zwischenablage aufgelöst, oder mit null, wenn sie keines enthält: ein eingefügter Screenshot oder ein in einem Browser oder Bildeditor kopiertes Bild. Rust: clipboard_image(), None, wenn sie keines enthält. url ist eine URL des Bildes (PNG oder das eigene JPEG, GIF, WebP oder BMP der Zwischenablage), das ein Image als sein src anzeigt und fetch liest: fetch(url) liefert seine Bytes, für einen Upload. size (width und height) ist seine Größe in Pixeln, wie dekodiert. Wie bei readText sollte es gelesen werden, wenn der Benutzer das Einfügen anfordert. Bilder bis 48 MB (kodiert) werden gelesen, damit das Bild in den Speicher der App passt; ein größeres lehnt mit einem Error ab, dessen code "ERR_NSH_QUOTA_EXCEEDED" ist (die Meldung nennt die Größe des Bildes und das Limit), während hasImage mit true aufgelöst wird. Rust: clipboard_image() antwortet dafür 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>;

Eine Chat-App, in der Benutzer Screenshots in ein Eingabefeld einfügen, bindet den Einfügen-Shortcut, solange ihr Input den Fokus hat, und übernimmt das Bild, falls vorhanden:

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>;

Wird damit aufgelöst, ob die Zwischenablage ein Bild enthält, ohne es zu lesen: kein Einfüge-Hinweis auf iOS. Rust: clipboard_has_image(). Auf Android wird mit false aufgelöst.

#Clipboard.writeImage

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

Legt das Bild von src, einer base64-data:-URL oder der url, die readImage lieferte, in die Zwischenablage und ersetzt deren Inhalt. Rust: set_clipboard_image(src). Auf Windows nimmt es ein PNG, das Format, das Browser, Office und das Snipping Tool lesen. Auf Android lehnt es mit "ERR_FEATURE_UNAVAILABLE_ON_PLATFORM" ab.

set_clipboard_image(image.url.clone());

await Clipboard.writeImage(image.url);

#Clipboard.readFiles

readFiles(): Promise<string[]>;

Wird mit den file:-URLs der in einem Dateimanager (Finder, Explorer, Files) kopierten Dateien und Ordner aufgelöst, in ihrer Reihenfolge, oder mit []: dieselben URLs, die ein Datei-Drop liefert. Rust: clipboard_files(). Eine URL lässt sich parsen, um ihren Pfad zu erhalten.

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

Die Picker-API zeigt den Foto-Picker des Systems an und gibt der App die Bilder, die der Nutzer auswählt: den Photos-Picker unter iOS (PHPickerViewController), den Photo Picker unter Android, einen Öffnen-Dialog bzw. Dateidialog auf den Desktop-Plattformen und ein File-Input im Browser. Unter iOS und Android läuft der Picker außerhalb der App und übergibt nur das, was der Nutzer auswählt. Deshalb braucht er keine Berechtigung für die Fotomediathek. Jedes ausgewählte Bild kommt als File (TSX) bzw. PickedFile (Rust) an, dessen Bytes nativ bleiben: Zeige es mit URL.createObjectURL(file) in einem Image an, lade es mit fetch und FormData hoch. Rust-Code ruft pick_images von nsh_core::prelude auf; TSX importiert Picker aus nsh.

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[]>;

Zeigt den Picker an und löst mit den Bildern auf, die der Nutzer ausgewählt hat, in der Reihenfolge der Auswahl, oder mit [], wenn der Nutzer abbricht. Rust: pick_images(request), eine Antwort, auf die in einem Task gewartet wird (spawn oder eine Modulfunktion von async). pickImages wirft nie: Optionen außerhalb des gültigen Bereichs (limit: 0, ein quality außerhalb von 0 bis 1) lehnen das Promise mit einem RangeError ab, und eine Auswahl, die die Capabilities der App nicht erlauben, lehnt mit ERR_ACCESS_DENIED ab (siehe unten). Ein Abbruch ist die Antwort des Nutzers, kein Fehler: Das Promise wird dann mit [] aufgelöst.

Die Bilder kommen versandfertig an:

• Formate, die jeder Browser und Server akzeptiert. JPEG, PNG, GIF und WebP kommen unverändert an; ein Foto, das in einem anderen Format gespeichert ist (HEIC auf iPhones, HEIF, TIFF), kommt als JPEG an. format: "current" behält das gespeicherte Format bei.
• Nativ verkleinert. Mit maxDimension wird ein Bild, dessen längere Seite größer ist, aufrecht auf diesen Wert verkleinert und neu kodiert: ein PNG als PNG, alles andere als JPEG mit quality. Handyfotos haben 12 bis 48 Megapixel; wenn man sie vor einem Upload auf 2048 Pixel verkleinert, werden daraus wenige hundert Kilobyte. Auch ein quality kodiert JPEGs neu.
• Was angezeigt wird. size ist die Größe des Bildes in Pixeln, wie es angezeigt wird, mit angewendeter Kameraausrichtung. Ein Bild, das NSH neu kodiert, enthält keine Metadaten (keinen Standort); ein Bild, das unverändert ankommt, behält seine eigenen.

Unter Windows, Linux und in GPUI-Fenstern bietet der Dialog die Formate an, die die Anfrage akzeptiert (mit "compatible": JPEG, PNG, GIF und WebP), und die Dateien kommen so an, wie sie gespeichert sind, in ihrer eigenen Größe.

Ein Chat-Composer hängt ein Foto an, zeigt es an, während die Nachricht geschrieben wird, und lädt es hoch, wenn sie gesendet wird:

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>;