nsh

nsh कोर मॉड्यूल है: reactive API (signals, computed values, effects, context), mount, token, host elements View, Text, Scroll और Overlay, चुने जा सकने वाले व्यू, safe area और कीबोर्ड, animation, डिवाइस और उसका परिवेश, PanResponder, क्लिपबोर्ड, फ़ोटो पिकर, स्पीच रिकग्निशन, स्टोरेज, host channel, कीबोर्ड शॉर्टकट, नेटिव कंपोनेंट और मॉड्यूल, एक्सेसिबिलिटी, और elements, styles और events के TypeScript टाइप। Reactive graph खुद नेटिव रूप से Rust में चलता है; किसी signal को पढ़ना runtime में एक कॉल है जिसकी लागत कुछ नैनोसेकंड है, और JavaScript interpreter में केवल आपके अपने closures चलते हैं।

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

NSH की reactivity SolidJS वाले मॉडल पर चलती है: कंपोनेंट फ़ंक्शन एक बार चलता है, और UI के जो हिस्से signals को पढ़ते हैं, वे signals बदलने पर अपनी जगह पर ही अपडेट हो जाते हैं। कंपोनेंट का कोई re-render नहीं होता और कोई virtual DOM नहीं है। गाइड के लिए Reactivity देखें।

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

Signal एक मान रखता है। उसे कॉल करने पर मान पढ़ा जाता है और, tracking scope (JSX एक्सप्रेशन, computed, effect) के अंदर, वह scope उसका subscriber बन जाता है। 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;
}

Signals से निकला हुआ मान। जब fn द्वारा पढ़ा गया कोई signal बदलता है, तो वह फिर से चलता है; computed मान को पढ़ने वाले तभी अपडेट होते हैं जब उसका नतीजा बदलता है (equals से, जो डिफ़ॉल्ट रूप से === है)। fn को पिछला नतीजा मिलता है।

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

जब कोई derivation महंगी हो या कई जगह पढ़ी जाती हो, तब computed का उपयोग करें। सस्ते एक्सप्रेशन के लिए साधारण फ़ंक्शन (const full = () => first() + " " + last()) भी उतना ही reactive है।

#effect

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

fn को रेंडरिंग के बाद चलाता है, और जब भी उसका पढ़ा हुआ कोई signal बदलता है तब फिर से चलाता है। Effects का उपयोग side effects के लिए करें: लॉगिंग, टाइमर, नेटिव मॉड्यूल से बात करना। Effect उस कंपोनेंट (या effect) का होता है जिसमें वह बनाया गया था और उसी के साथ dispose हो जाता है।

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

Effect के दोबारा चलने से पहले (या उसके कंपोनेंट के हट जाने पर) कुछ पूर्ववत करने के लिए, उसके अंदर cleanup को कॉल करें।

#batch

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

fn को चलाता है और उसकी सभी writes को अंत में एक साथ लागू करता है, ताकि पढ़ने वाले हर write पर अलग से नहीं, बल्कि केवल एक बार अपडेट हों। fn जो लौटाता है, वही यह लौटाता है।

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

#untracked

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

fn को इस तरह चलाता है कि वर्तमान scope उसके पढ़े हुए का subscriber न बने। किसी effect या JSX एक्सप्रेशन के अंदर किसी signal को उस पर निर्भर हुए बिना पढ़ने के लिए इसका उपयोग करें।

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

#cleanup

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

fn को पंजीकृत करता है ताकि वह वर्तमान effect के दोबारा चलने से पहले, या वर्तमान कंपोनेंट या effect के हट जाने पर चले।

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

ऐसा मान जो कोई कंपोनेंट अपने रेंडर किए हर चीज़ को देता है, चाहे वह कितनी भी गहराई पर हो। Context को कॉल करने (Theme()) पर निकटतम provider का मान पढ़ा जाता है, और provider न होने पर 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 को surface में रेंडर करता है (विंडो, या वह 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 और बाकी। दोनों हिस्से reactive रहते हैं: जिन props के मान बदलते हैं वे getters होते हैं, और split उन्हें getters ही रखता है। इसका उपयोग ऐसे कंपोनेंट में करें जो कुछ props खुद संभालता है और बाकी आगे भेज देता है। Props को destructure करने (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;

अपने children को रेंडर करता है, या जैसे ही उनके नीचे कुछ throw करता है, तब fallback को: कंपोनेंट की body, कोई binding, कोई effect या कोई event handler। जो हिस्सा विफल हुआ उसे हटा दिया जाता है और उसकी जगह fallback दिखता है। फ़ंक्शन fallback को fallback(error, reset) के रूप में throw किए गए मान और reset के साथ कॉल किया जाता है, जो children को फिर से रेंडर करता है, चाहे वह कोई भी पैरामीटर घोषित करे; fallback element को जैसा है वैसा दिखाया जाता है। विफलता अपने ऊपर के निकटतम boundary के पास जाती है, और fallback में हुई विफलता उससे ऊपर वाले boundary के पास। Rust कंपोनेंट 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];

ऐप की थीम का डिज़ाइन token name ("theme", nsh.json में, shadcn/ui के tokens के ऊपर) दिखाए जा रहे appearance में: रंग #rrggbbaa के रूप में, लंबाई points की संख्या के रूप में, फ़ॉन्ट अपने family नाम के रूप में। नाम थीम के CSS variables होते हैं, -- के बिना (primary, muted-foreground, radius, font-mono, और ऐप के अपने, जैसे up)। इसे पढ़ना reactive है: token पढ़ने वाला कंपोनेंट, memo या effect थीम या appearance बदलने पर फिर से चलता है। Tokens ऐप के tokens को उनके प्रकारों के साथ सूचीबद्ध करता है; NSH इसे थीम से .nsh/types/nsh/tokens.d.ts में लिखता है। क्लासों के लिए tokens को सीधे नाम दें (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;

वे host elements जिन्हें nsh export करता है, टैग के रूप में लिखे जाते हैं: <View>, <Text>, <Scroll>, <Overlay> (इसके children विंडो के ऊपर, किसी anchor के सापेक्ष रखे जाते हैं: Overlay)। जो टैग अपने import (alias भी) के ज़रिए इनमें से किसी का नाम लेता है, उसके लिए कंपाइलर नेटिव व्यू उसी जगह बना देता है, इसलिए इन्हें import करने की रन टाइम पर कोई लागत नहीं है। ये किसी भी अन्य कंपोनेंट की तरह कंपोनेंट हैं, इसलिए इन्हें इधर-उधर पास भी किया जा सकता है (const Tag = inline ? Text : View)। nsh अन्य primitives को इसी तरह export करता है: List, Image, Canvas, WebView और Video, हर एक का अपना रेफ़रेंस पेज है। उनके props Elements के अंतर्गत प्रलेखित हैं। टेक्स्ट इनपुट, Input, nsh/base से आता है।

#Safe area और कीबोर्ड

CSS के environment variables किसी भी व्यू के padding और margin में कंटेंट को सिस्टम UI से दूर रखते हैं (padding, paddingTop, …, वही margin keys; Tailwind के p* / m* arbitrary values; Rust में Styled methods .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 और safeAreaInsets

safeArea() surface का safe area है (Rust में safe_area()); safeAreaInsets() वे insets हैं जहां कंपोनेंट रेंडर होता है (Rust में cx.insets()), यानी safe-area-inset-* variables के मान। दोनों reactive Edges हैं ({ top, right, bottom, left } points में)। देखें safeArea और safeAreaInsets।

#Keyboard और keyboardFrame

Keyboard.dismiss() सॉफ़्टवेयर कीबोर्ड को छिपाता है (Rust में dismiss_keyboard()) और keyboardFrame() बताता है कि वह स्क्रीन का कितना हिस्सा ढकता है (Rust में keyboard_height() और keyboard_duration())। देखें कीबोर्ड छिपाना और कीबोर्ड की ऊंचाई।

#चुने जा सकने वाले व्यू

<View selectable> (Rust में view().selectable(true)) अपने अंदर के टेक्स्ट को एक साथ चुनने योग्य बनाता है, जैसा किसी वेब पेज में होता है: एक ही selection व्यू, Text elements और TextView के पार, पढ़ने के क्रम में चलता है। देखें Text selection।

#Animation

Animation API UI थ्रेड पर animate करता है। आप एक animated value बनाते हैं, उसे (या उससे निकले मानों को) किसी style property से bind करते हैं, और एक animation शुरू करते हैं; उसके बाद हर फ़्रेम नेटिव रूप से गणना किया जाता है, ऐप का कोड चलाए बिना। व्यस्त इंजन या JS थ्रेड animation को अटकने नहीं दे सकता, और animation में ऐप को प्रति फ़्रेम कोई काम नहीं करना पड़ता। Rust कोड nsh_core::prelude से animated_value(), motion(), Animation, Spring, Timing, KeyframeTiming, MotionPreset और Easing का उपयोग करता है और elements के .bind_* methods से मान bind करता है; TSX इन्हें nsh से import करता है।

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

गाइड के लिए Animation देखें।

#Animated value क्या चला सकती है

अन्य style properties साधारण मान लेती हैं; layout को ही animate करने के लिए (आकार, flow में स्थितियां), LayoutAnimation का उपयोग करें।

#createAnimatedValue

function createAnimatedValue(value?: number): AnimatedValue;

value (डिफ़ॉल्ट 0) से शुरू होने वाली animated value बनाता है। Rust: animated_value(value), एक Copy handle जो उसे बनाने वाले कंपोनेंट के पास रहता है।

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

हर animation method एक promise लौटाता है जो { finished } के साथ resolve होता है: animation के पूरा होने पर true, उसके रुकने पर false (stop, set या उसी मान की किसी दूसरी animation द्वारा)। Rust में यह एक AnimationEnd लौटाता है, जिसे कोई task उसी 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";

नेटिव animation graph का एक node: एक AnimatedValue, या दूसरों से निकला हुआ मान। Derived nodes का मूल्यांकन UI थ्रेड पर तब होता है जब भी उनके inputs बदलते हैं।

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) किसी value को keyframes के माध्यम से चलाता है और { finished } के साथ resolve होता है, जो बताता है कि वे पूरे हुए या नहीं; Animated.keyframes(value, { keyframes, ...options }) composite के एक step के समान है। 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 चलते हैं: एक easing एक segment को आकार देती है (keyframe की easing उस segment पर लागू होती है जो उसी से शुरू होता है, timing की easing बाकी सभी पर); keyframes में जिनके offset नहीं दिए गए, वे समान रूप से फैलते हैं, पहला 0 पर और आख़िरी 1 पर; हर iteration अपने पहले keyframe पर छलांग लगाकर शुरू होता है, और 0 पर keyframe न होने पर value वहीं से चलती है जहाँ वह है; delay के दौरान value पहले keyframe पर टिकी रहती है (CSS animation-fill-mode: backwards); backward iterations segments को उनके curves उलटकर पीछे की ओर चलाते हैं; value वहीं रहती है जहाँ आख़िरी iteration उसे छोड़ता है।

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

एक motion बनाता है: view की opacity और transform के हर channel के लिए एक animated value, जो rest अवस्था में होती है (opacity और scales 1, बाकी 0), और उन पर natively चलने वाले motions। इसे style={motion.style} से bind करें, या motion.style अथवा motion.transform को style में spread करें; transform पहले अपने translations लागू करता है, फिर rotations, फिर scales, जिसमें scale को scaleX और scaleY में मिला दिया जाता है: view के 8 transform steps में से 7, जिससे आपके लिए एक बचता है (3D flips के लिए [{ perspective: 600 }, ...motion.transform])। initial तय करता है कि channels कहाँ से शुरू हों ({ opacity: 0 }; बाकी rest से शुरू होते हैं)। enter के साथ, जिन channels को वह चलाता है वे वहीं से शुरू होते हैं जहाँ वह motion शुरू होता है (initial पर) और वह तुरंत चलने लगता है, बाकी options उसकी timing होते हैं (delay, duration, …)। एक motion केवल opacity और transform को चलाता है: motion.style को spread करने से view की opacity सेट हो जाती है, इसलिए अपनी opacity रखने के लिए केवल motion.transform को bind करें, और रंगों को animated value और interpolate से चलाएँ। Rust: motion(), एक Copy handle जिसे उसे बनाने वाला component अपने पास रखता है, और जिसे .bind_motion(&m) से bind किया जाता है; motion().entering(spec) enter करता है।

जब user कम motion माँगता है (reduceMotion()), तो play, animation और enter बिना चले तुरंत वहीं पहुँच जाते हैं जहाँ motion खत्म होता है, जब तक ignoreReduceMotion सेट न हो (options पर या 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";
}

तैयार motions data के रूप में: motion.play("shake") motions.shake को चलाता है। MotionName इनमें से एक है: fadeIn, fadeInUp, fadeInDown, fadeInLeft, fadeInRight, zoomIn, popIn, bounceIn, slideInUp, slideInDown, flipInX, flipInY (enter); fadeOut, fadeOutUp, fadeOutDown, fadeOutLeft, fadeOutRight, zoomOut, popOut, slideOutDown, slideOutUp (exit); shake, headShake, wiggle, swing, pulse, heartbeat, rubberBand, jello, tada, jump, flash (attention); spin, float, breathe, sway, bob, glow (loop)। Animation हर एक का वर्णन करता है। किसी preset को बदलने के लिए उसे spread करें: motion.play({ ...motions.fadeInUp, duration: 600 })।

MotionSpec आपका अपना motion है: हर channel के keyframes ({ opacity: [0, 1], translateY: [24, 0] }), या frames की एक सूची जैसी Web Animations API में लिखी जाती है ([{ opacity: 0, translateY: 24 }, { opacity: 1, translateY: 0 }], बिना offset वाला frame सूची में अपनी स्थिति के अनुसार रखा जाता है), साथ में keyframe timing। Rust: MotionSpec::new(KeyframeTiming), .values(channel, values) (समान रूप से फैला हुआ), .track(channel, keyframes) और .timing(|t| …) के साथ; MotionPreset::FadeInUp (या .spec()) एक preset है, और MotionChannel channels के नाम बताता है।

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 steps (timing, spring, decay, sequence, parallel, …) से animations बनाता है। start() तक कुछ नहीं चलता; उसके बाद पूरा tree natively चलता है, और हर step UI thread पर ठीक उसी क्षण शुरू होता है जब पिछला खत्म होता है (कोई frame gap नहीं, steps के बीच app के code तक कोई round trip नहीं)। Rust वही tree 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;
};

Easing data है, app का function नहीं: runtime इसे natively evaluate करता है। Rust में यह enum 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)। किसी को draw करने के लिए, Easing.sample(easing, count) (Rust: nsh_core::element::sample_easing) 0 से 1 तक count समान दूरी वाले बिंदुओं पर उसकी values देता है; Animated.sampleSpring और Animated.sampleDecay (sample_spring, sample_decay) spring या decay की values प्रति frame एक देते हैं (fps पर, default 60) from (0) से उसके खत्म होने तक। तीनों उसी native code से आते हैं जिस पर animations चलती हैं। TSX में जहाँ भी Easing स्वीकार किया जाता है, आप एक नाम ("easeOut"), चार संख्याओं के रूप में एक cubic Bézier, या Easing object से एक curve दे सकते हैं।

Easing.steps(count, position) CSS steps() है: value चलने के बजाय count स्तरों के बीच छलांग लगाती है (frame-by-frame sprite, टिक-टिक करती सुई)। position बताता है कि छलांगें कहाँ पड़ती हैं: "jump-end" (default, साथ ही "end"), "jump-start" ("start"), "jump-none" या "jump-both"; Rust: Easing::Steps(count, StepPosition::JumpEnd), JumpStart, JumpNone, JumpBoth।

Curves अपने “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) अगले commit के layout बदलावों को natively animate करता है: जो views खिसकते या आकार बदलते हैं वे अपने नए frames तक सरकते हैं, नए views दिखाई देते हैं (property के अनुसार fade या scale होकर) और हटाए गए views गायब हो जाते हैं। इसे उस state change से ठीक पहले call करें जो layout बदलता है। Rust: animate_layout(LayoutAnimation), nsh_core::element::LayoutAnimation के presets या उसके create, update और delete transitions के साथ।

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 app को device और उसके परिवेश के बारे में बताता है। Rust code nsh_core::prelude के functions (window(), dark(), font_scale(), locale(), lifecycle(), os(), idiom(), pixel_ratio(), set_color_scheme(), …) call करता है; TSX उन्हें nsh से import करता है। Window size, color scheme, font scale, pixel ratio, locale और app state reactive हैं: उन्हें binding (Rust में element को दिया गया closure, TSX में JSX), computed या effect में पढ़ें, और जो उन्हें पढ़ता है वह तब update हो जाता है जब platform बदलाव की सूचना देता है (rotation, window resize, dark mode में स्विच करना, text size या भाषा बदलना, किसी दूसरी density वाली screen पर जाना, app छोड़कर वापस आना)।

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

गाइड के लिए Device and environment देखें।

#windowSize

const windowSize: Accessor<Size>;

Surface का आकार points में: window, या embedded NshAppView / NshView। Reactive। 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">;

दिखाई जा रही appearance: system की, जब तक app ने अपनी सेट न की हो (nsh.json "appearance", setColorScheme)। Reactive। Rust: dark() -> bool; theme colors (AdaptiveColor) और .dark(…) style variant इसे पढ़े बिना ही इसका अनुसरण करते हैं। Tailwind का dark: variant भी इसका अनुसरण करता है (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>;

User का पसंदीदा text size, default की तुलना में (1 default size है; iOS पर Dynamic Type, Android पर font size), या उसके स्थान पर वह text size जो embedding app सेट करता है। Reactive। Rust: font_scale() -> f32। Text पहले से इसके साथ scale होता है, जब तक allowFontScaling={false} न हो; जब दूसरे sizes को भी इसके अनुसार चलना चाहिए, जैसे text के बगल के icons, तब इसे पढ़ें।

#locale

const locale: Accessor<string>;

User का locale BCP 47 tag के रूप में ("en-US", "zh-Hans-CN"), या उसके स्थान पर वह locale जो embedding app सेट करता है। Reactive। Rust: locale() -> Locale (locale().as_str() tag है)। Intl default रूप से उसी के अनुसार format करता है; अपने अनुवादों की strings चुनने के लिए इसे पढ़ें (Device and environment)।

#lifecycle

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

क्या app उपयोग में है, React Native के AppState की शर्तों में: "active" foreground में और input ले रहा है, "inactive" दिखाई देते हुए लेकिन focus के बिना (कोई दूसरा app या window उसके पास है, या system उसके ऊपर कुछ दिखाता है, जैसे app switcher या आती हुई call), "background" जब दिखाई नहीं दे रहा (background में, minimized, छिपा हुआ browser tab)। किसी native app के अंदर दिखाया गया app उस app की स्थिति का अनुसरण करता है। Reactive। Rust: lifecycle() -> Lifecycle (Lifecycle::Active, Inactive, Background)।

जिस काम को कोई नहीं देख रहा उसे रोकने और app के लौटने पर दोबारा शुरू करने के लिए इसे 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;

System की appearance चाहे जो हो, app को तुरंत scheme में दिखाता है: colorScheme(), dark: classes, components का theme और platform के controls (alerts, status bar की default style) इसका अनुसरण करते हैं; "system" फिर से 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 (वेब को छोड़कर हर प्लेटफ़ॉर्म), अन्यथा default, अन्यथा undefined। Rust कोड os() पर match करता है (और 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>;

प्रति पॉइंट डिवाइस पिक्सेल (जैसे अधिकांश 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 को ऐप के बाहर खोलता है: वेब पेज ब्राउज़र में, mailto: लिंक मेल ऐप में, tel: लिंक फ़ोन ऐप में, और कोई भी स्कीम जिसे किसी अन्य ऐप ने रजिस्टर किया हो (maps:, होस्ट ऐप के अपने lb:// लिंक)। यह { opened } के साथ resolve होता है, यानी कुछ ने उसे खोला या नहीं: जब कोई ऐप उस स्कीम को नहीं संभालता तो false। Rust: nsh_core::prelude का open_url(url), एक उत्तर जिसे किसी task में await किया जाता है (या drop कर दिया जाता है), वही 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 निरपेक्ष (absolute) होता है (उसमें स्कीम होती है)। जो URL कोड चलाएँगे या ऐप के अपने डेटा तक पहुँचेंगे, यानी javascript:, data:, blob:, file:, about: और asset:, वे promise को TypeError के साथ reject करते हैं, जैसे सापेक्ष (relative) पते करते हैं। openUrl कभी throw नहीं करता: हर विफलता reject होती है।
• जो ऐप capabilities घोषित करता है उसे openUrl चाहिए: हर स्कीम के लिए "openUrl": true, या सूचीबद्ध स्कीमों के लिए "openUrl": { "schemes": ["https", "mailto"] }; अन्य URL Error के साथ reject होते हैं जिसका code "ERR_ACCESS_DENIED" है, permission "openUrl" है और resource URL है (Sandbox and capabilities देखें)। Rust में open_url उनके लिए false लौटाता है और कारण लॉग करता है।
• एम्बेड करने वाला ऐप URL को पहले देखता है और उसे अपने राउटर से भेज सकता है (Swift NshAppView.onOpenURL, Java NshView.setOpenUrlHandler, Rust AppView::host().handle_open_url; iOS और Android देखें)। तब opened का मान true होता है।
• हर प्लेटफ़ॉर्म इसे अपने opener से खोलता है: iOS पर UIApplication.open (एम्बेड होने पर होस्ट ऐप का application), Android पर ACTION_VIEW intent, macOS पर NSWorkspace, Windows पर ShellExecuteW, Linux पर GtkUriLauncher, GPUI का open_url, वेब पर नया टैब। nsh test URL को खोलने के बजाय रिकॉर्ड करता है।
• TextView अपने लिंक इसी तरह links="open" से खोलता है।

#लेआउट दिशा

लेआउट की दिशा उपयोगकर्ता की भाषा का अनुसरण करती है: दाएँ-से-बाएँ लिखी जाने वाली भाषा (अरबी, हिब्रू, …) में ऐप दाएँ से बाएँ लेआउट होता है, पंक्तियाँ दाईं ओर से चलती हैं, और left / right स्टाइल प्रॉपर्टीज़ (marginLeft, paddingRight, …) का अर्थ start और end होता है। बदलाव तुरंत लागू होते हैं, पुनः आरंभ की आवश्यकता नहीं।

किसी view की direction स्टाइल ("ltr", "rtl" या "inherit", जो डिफ़ॉल्ट है) उसके अपने subtree की दिशा तय करती है; 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>

#संबंधित

• Safe area insets (Rust safe_area(); TSX safeArea(), safeAreaInsets()) और सॉफ़्टवेयर कीबोर्ड (Rust keyboard_height(); TSX keyboardFrame()) Safe area and keyboard में हैं।
• स्क्रीन रीडर और reduced motion सेटिंग्स Accessibility में हैं।

#PanResponder

Pan responders जेस्चर रिस्पॉन्डर सिस्टम के ऊपर बने ड्रैग जेस्चर हैं: element किसी जेस्चर के touches को claim करता है, फिर उन्हें अकेले सुनता है, साथ में जेस्चर state भी मिलती है, जो touches का centroid, तय की गई दूरी और velocity आपके लिए ट्रैक करती है। Rust कोड उन्हें .claim_touches(TouchClaim::…) से claim करता है और .on_responder_* listeners से सुनता है, जिनका ResponderEvent एक PanGesture लिए होता है, सब nsh_core::prelude में; TSX nsh से PanResponder import करता है, जिसके onPanResponder… callbacks को touch event और जेस्चर state मिलती है।

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 को उस view पर spread करें जिसे जेस्चर मिलना चाहिए। Rust में, view touches को claim करता है और खुद सुनता है:

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

#कॉलबैक

हर callback को touch event (GestureResponderEvent, nsh से) और जेस्चर state मिलती है। Rust में, claim .ask(|request: &ClaimRequest| …) से निर्णय लेता है, touches लेने के लिए request.claim() को बुलाता है (ask के बिना वह उन्हें हमेशा लेता है), और हर listener को एक ResponderEvent मिलता है जिसका gesture state है।

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, जिसमें points Point<Points> के रूप में हैं।

#स्क्रॉल व्यू के अंदर

जब तक कोई pan responder responder है, उसके आसपास के नेटिव scroll views स्क्रॉल नहीं करते (onShouldBlockNativeResponder का डिफ़ॉल्ट true है)। क्षैतिज swipe को ऊर्ध्वाधर स्क्रॉलिंग के साथ चलने देने के लिए, केवल क्षैतिज moves पर 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),
});

उस pan के लिए जिसे प्लेटफ़ॉर्म पहचानता है, TouchClaim::on_pan(PanActivation::horizontal(10.0, 10.0)) उँगलियों के हिलने के साथ main thread पर निर्णय लेता है। अंतर्निहित responder props (onStartShouldSetResponder, onResponderGrant, onTouchStart, …) को किसी भी element पर सीधे भी इस्तेमाल किया जा सकता है; Elements देखें।

#Clipboard

Clipboard API सिस्टम क्लिपबोर्ड को पढ़ता और लिखता है: हर जगह टेक्स्ट (iOS पर UIPasteboard, Android पर ClipboardManager, डेस्कटॉप पर NSPasteboard, GDK और Win32 क्लिपबोर्ड, वेब पर navigator.clipboard), iOS, डेस्कटॉप और वेब पर इमेज, और डेस्कटॉप तथा Mac Catalyst पर फ़ाइल मैनेजर में कॉपी की गई फ़ाइलें। Rust कोड nsh_core::prelude के फ़ंक्शन (set_clipboard, clipboard_string, …) बुलाता है; TSX nsh से Clipboard import करता है।

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 के read फ़ंक्शन ऐसे उत्तर लौटाते हैं जिन्हें task में await किया जाता है (spawn, या async मॉड्यूल का फ़ंक्शन); ClipboardImage nsh_core::element::ClipboardImage है, जिसमें url और size (एक Size<DevicePixels>) हैं।

इमेज iOS, डेस्कटॉप और वेब पर क्लिपबोर्ड से होकर जाती हैं। Android पर क्लिपबोर्ड टेक्स्ट ले जाता है: writeImage और readImage Error के साथ reject होते हैं जिसका code "ERR_FEATURE_UNAVAILABLE_ON_PLATFORM" है, और hasImage false के साथ resolve होता है। Rust में, set_clipboard_image क्लिपबोर्ड को वैसा ही छोड़ देता है जैसा वह वहाँ है और clipboard_image None लौटाता है।

उपयोगकर्ता किसी selectable text से खुद भी कॉपी कर सकता है; Clipboard API कोड से कॉपी करने के लिए है, जैसे Copy बटन।

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

क्लिपबोर्ड के टेक्स्ट के साथ resolve होता है, या जब उसमें कोई टेक्स्ट न हो तो "" के साथ। Rust: clipboard_string()। iOS पर, क्लिपबोर्ड पढ़ने से सिस्टम का paste notice (“App pasted from …”) दिख सकता है, और Android 10 और बाद के संस्करणों पर केवल foreground वाला ऐप ही इसे पढ़ सकता है। इसे तब पढ़ें जब उपयोगकर्ता paste करने को कहे, हर स्क्रीन पर नहीं।

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

इसे पढ़े बिना, resolve होता है इस जानकारी के साथ कि क्लिपबोर्ड में टेक्स्ट है या नहीं: iOS पर कोई paste notice नहीं। Rust: clipboard_has_string()। इसका उपयोग यह तय करने के लिए करें कि Paste बटन दिखाना है या नहीं। वेब पर, ब्राउज़र केवल पढ़कर ही बताते हैं, इसलिए यह उपयोगकर्ता से अनुमति माँग सकता है।

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

क्लिपबोर्ड की इमेज के साथ resolve होता है, या जब उसमें कोई इमेज न हो तो null के साथ: चिपकाया गया स्क्रीनशॉट, या ब्राउज़र या इमेज एडिटर में कॉपी की गई इमेज। Rust: clipboard_image(), जब उसमें कोई इमेज न हो तो None। url इमेज का URL है (PNG, या क्लिपबोर्ड का अपना JPEG, GIF, WebP या BMP) जिसे एक Image अपने src के रूप में दिखाता है और fetch पढ़ता है: fetch(url) इसके bytes देता है, अपलोड के लिए। size (width और height) डिकोड के अनुसार पिक्सेल में इसका आकार है। readText की तरह, इसे तब पढ़ें जब उपयोगकर्ता paste करने को कहे। 48 MB (encoded) तक की इमेज पढ़ी जाती हैं, ताकि इमेज ऐप की मेमोरी में समा सके; इससे बड़ी इमेज Error के साथ reject होती है जिसका code "ERR_NSH_QUOTA_EXCEEDED" है (उसका संदेश इमेज का आकार और सीमा बताता है), जबकि hasImage true के साथ resolve होता है। 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>;

चैट-शैली का ऐप, जहाँ उपयोगकर्ता composer में स्क्रीनशॉट paste करते हैं, अपने input के focus में रहते हुए paste शॉर्टकट को bind करता है और इमेज होने पर उसे ले लेता है:

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

इसे पढ़े बिना, resolve होता है इस जानकारी के साथ कि क्लिपबोर्ड में इमेज है या नहीं: iOS पर कोई paste notice नहीं। Rust: clipboard_has_image()। Android पर यह false के साथ resolve होता है।

#Clipboard.writeImage

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

src की इमेज, यानी base64 data: URL या वह जो url readImage ने दी, क्लिपबोर्ड पर रखता है, और जो उसमें था उसे बदल देता है। 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: URLs के साथ, उनके क्रम में, resolve होता है, या [] के साथ: वही URLs जो file drop देता है। Rust: clipboard_files()। उसका path पाने के लिए URL को parse करें।

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 सिस्टम का फ़ोटो picker दिखाता है और उपयोगकर्ता की चुनी हुई इमेज ऐप को देता है: iOS पर Photos picker (PHPickerViewController), Android पर Photo Picker, डेस्कटॉप पर open panel या file dialog और ब्राउज़र में file input। iOS और Android पर picker ऐप के बाहर चलता है और ऐप को सिर्फ़ वही देता है जो उपयोगकर्ता चुनता है, इसलिए इसे फ़ोटो लाइब्रेरी की अनुमति की ज़रूरत नहीं होती। चुनी गई हर इमेज File (TSX) या PickedFile (Rust) के रूप में आती है, जिसके bytes नेटिव ही रहते हैं: इसे Image में URL.createObjectURL(file) से दिखाएँ, और 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[]>;

यह picker दिखाता है और उपयोगकर्ता की चुनी हुई इमेज, चुनने के क्रम में, लेकर resolve होता है; उपयोगकर्ता के रद्द करने पर यह [] के साथ resolve होता है। Rust में: pick_images(request), जो ऐसा उत्तर है जिसका task में await किया जाता है (spawn, या async मॉड्यूल फ़ंक्शन)। pickImages कभी throw नहीं करता: सीमा से बाहर के options (limit: 0, यानी 0 से 1 के बाहर का quality) promise को RangeError के साथ reject करते हैं, और ऐसा pick जिसकी अनुमति ऐप की capabilities नहीं देतीं, ERR_ACCESS_DENIED (नीचे देखें) के साथ reject होता है। रद्द करना उपयोगकर्ता का उत्तर है, विफलता नहीं: यह [] के साथ resolve होता है।

इमेज भेजने के लिए तैयार मिलती हैं:

• ऐसे फ़ॉर्मेट जो हर ब्राउज़र और सर्वर समझता है। JPEG, PNG, GIF और WebP जैसी हैं वैसी ही आती हैं; किसी और फ़ॉर्मेट (iPhone पर HEIC, HEIF, TIFF) में सहेजी गई फ़ोटो JPEG बनकर आती है। format: "current" सहेजा हुआ फ़ॉर्मेट ही रखता है।
• नेटिव रूप से छोटी की गई। maxDimension देने पर, जिस इमेज की लंबी भुजा उससे बड़ी हो, उसे उस सीमा में फ़िट होने तक छोटा किया जाता है, सीधी (upright) करके, और दोबारा encode किया जाता है: PNG को PNG के रूप में, बाकी सबको quality वाले JPEG के रूप में। फ़ोन की फ़ोटो 12 से 48 मेगापिक्सल की होती हैं; अपलोड से पहले उन्हें 2048 पिक्सल तक छोटा करने पर वे कुछ सौ किलोबाइट की रह जाती हैं। quality भी JPEG को दोबारा encode करता है।
• जैसी दिखती है। size इमेज का पिक्सल में आकार है, जैसी वह दिखती है, यानी कैमरे का orientation लागू होने के बाद। जिस इमेज को NSH दोबारा encode करता है उसमें कोई metadata (जैसे लोकेशन) नहीं रहता; जो इमेज जैसी है वैसी आती है, उसका अपना metadata बना रहता है।

Windows, Linux और GPUI विंडो में डायलॉग वे फ़ॉर्मेट दिखाता है जो अनुरोध स्वीकार करता है ("compatible" के साथ: JPEG, PNG, GIF और WebP), और फ़ाइलें वैसी ही आती हैं जैसी सहेजी गई हैं, अपने मूल आकार में।

एक चैट composer फ़ोटो जोड़ता है, संदेश लिखे जाने के दौरान उसे दिखाता है, और संदेश भेजे जाने पर उसे अपलोड करता है:

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