nsh

nsh هي الوحدة الأساسية: واجهة البرمجة التفاعلية (الإشارات signals، والقيم المحسوبة computed، والتأثيرات effects، والسياق context)، وmount، وtoken، وعناصر المضيف View وText وScroll وOverlay، والعروض القابلة للتحديد، والمنطقة الآمنة ولوحة المفاتيح، والرسوم المتحركة، والجهاز وبيئته، وPanResponder، والحافظة، ومنتقي الصور، والتعرف على الكلام، والتخزين، وقناة المضيف، واختصارات لوحة المفاتيح، والمكونات والوحدات الأصلية، وإمكانية الوصول، وأنواع TypeScript الخاصة بالعناصر والأنماط والأحداث. يعمل الرسم التفاعلي نفسه أصلياً بلغة Rust؛ وقراءة الإشارة هي استدعاء إلى بيئة التشغيل يكلّف بضعة نانوثوانٍ، ولا يعمل في مفسّر JavaScript سوى الدوال المغلقة (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 النموذج نفسه المستخدم في SolidJS: تعمل دالة المكوّن مرة واحدة، وتُحدَّث أجزاء الواجهة التي تقرأ الإشارات في مكانها عندما تتغير تلك الإشارات. لا يُعاد رسم المكوّن ولا يوجد DOM افتراضي. راجع التفاعلية للاطلاع على الدليل.

#signal

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

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

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

تحمل الإشارة قيمة. استدعاؤها يقرأ القيمة، وداخل نطاق التتبع (تعبيرات JSX، وcomputed، وeffect) يشترك ذلك النطاق فيها. يكتب set وupdate القيمة، ويتحدّث كل ما قرأها.

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

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

mount(Counter);

افتراضياً، لا يفعل أي شيء الإسناد الذي === للقيمة الحالية. مرّر equals: false للإشعار عند كل كتابة (مفيد عندما تعدّل كائناً في مكانه ثم تسند الكائن نفسه مرة أخرى)، أو مرّر دالة المقارنة الخاصة بك:

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

#computed

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

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

قيمة مشتقة من إشارات. يعمل fn مرة أخرى عندما تتغير إشارة قرأها؛ ولا تتحدّث الجهات القارئة للقيمة المحسوبة إلا عندما تتغير نتيجتها (بحسب equals، وهي === افتراضياً). يستقبل fn النتيجة السابقة.

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

استخدم computed عندما يكون الاشتقاق مكلفاً أو يُقرأ في عدة أماكن. أما التعبير الرخيص فدالة عادية (const full = () => first() + " " + last()) تفاعلية بالقدر نفسه.

#effect

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

يشغّل fn بعد العرض، ومرة أخرى كلما تغيّرت إشارة قرأها. استخدم التأثيرات للآثار الجانبية: التسجيل (logging)، والمؤقتات، والتخاطب مع الوحدات الأصلية. ينتمي التأثير إلى المكوّن (أو التأثير) الذي أُنشئ فيه ويُتخلص منه معه.

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

للتراجع عن شيء قبل أن يعمل التأثير مرة أخرى (أو عندما يزول مكوّنه)، استدعِ cleanup داخله.

#batch

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

يشغّل fn ويطبّق كل عمليات الكتابة فيه معاً في النهاية، فتتحدّث الجهات القارئة مرة واحدة بدلاً من مرة لكل كتابة. يعيد ما يعيده fn.

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

#untracked

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

يشغّل fn دون اشتراك النطاق الحالي فيما يقرؤه. استخدمه لقراءة إشارة داخل تأثير أو تعبير JSX دون الاعتماد عليها.

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

#cleanup

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

يسجّل fn ليعمل قبل أن يعمل التأثير الحالي مرة أخرى، أو عندما يزول المكوّن أو التأثير الحالي.

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

#context

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

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

قيمة يوفّرها مكوّن لكل ما يعرضه، مهما كان عمقه. استدعاء السياق (Theme()) يقرأ قيمة أقرب مزوّد، أو defaultValue عند عدم وجود مزوّد.

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

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

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

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

mount(App);

#mount

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

يعرض app في السطح (النافذة، أو NshAppView / NshView المضمَّن فيه التطبيق) ويعيد دالة تزيله. ينتهي ملف الدخول لكل تطبيق بـ mount(App).

mount(App);

#split

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

يقسّم كائن الخصائص إلى الخصائص المسمّاة في keys وبقية الخصائص. يبقى النصفان تفاعليين: الخصائص التي تتغير قيمها هي getters، ويحتفظ split بها كـ getters. استخدمه في مكوّن يعالج بعض الخصائص بنفسه ويمرّر الباقي. أما تفكيك الخصائص بالتفكيك (const { label } = props) فيقرؤها مرة واحدة ويفقد التحديثات.

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

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

#ErrorBoundary

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

يعرض أبناءه، أو fallback عندما يُطلق شيء تحتهم استثناءً: جسم مكوّن، أو ربط، أو تأثير، أو معالج حدث. يُزال الجزء الذي فشل ويظهر البديل مكانه. تُستدعى الدالة fallback على الصورة fallback(error, reset) مع القيمة المُطلَقة وreset الذي يعرض الأبناء مرة أخرى، مهما كانت المعاملات التي تعلنها؛ أما العنصر fallback فيُعرض كما هو. ينتقل الفشل إلى أقرب حدّ (boundary) فوقه، والفشل في البديل ينتقل إلى الحد الذي فوقه. تستخدم مكونات Rust catch_error (حدود الأخطاء).

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

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

#token

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

رمز التصميم name في سمة التطبيق ("theme" في nsh.json، فوق رموز shadcn/ui) بحسب المظهر المعروض: اللون على صورة #rrggbbaa، والطول كعدد من النقاط، والخط باسم عائلته. الأسماء هي متغيرات CSS الخاصة بالسمة دون -- (primary، muted-foreground، radius، font-mono، والرموز الخاصة بالتطبيق، مثل up). قراءته تفاعلية: يعمل المكوّن أو memo أو التأثير الذي يقرأ رمزاً مرة أخرى عندما تتغير السمة أو المظهر. يسرد Tokens رموز التطبيق مع أنواعها؛ ويكتبه NSH في .nsh/types/nsh/tokens.d.ts انطلاقاً من السمة. بالنسبة إلى الأصناف (classes)، سمِّ الرموز مباشرة (bg-primary، rounded-(--radius)): رموز السمة.

import { effect, token } from "nsh";

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

#View, Text, Scroll, Overlay

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

عناصر المضيف التي يصدّرها nsh، تُكتب كوسوم: <View>، <Text>، <Scroll>، <Overlay> (يضع أبناءه أعلى النافذة، موضوعين مقابل نقطة ارتكاز: Overlay). ينشئ المصرّف (compiler) العرض الأصلي في مكانه للوسم الذي يسمّي أحدها عبر استيراده (ويشمل ذلك الاسم المستعار)، لذا فاستيرادها لا يكلّف شيئاً وقت التشغيل. وهي مكوّنات مثل أي مكوّن آخر، فيمكن تمريرها أيضاً (const Tag = inline ? Text : View). يصدّر nsh بقية العناصر الأولية بالطريقة نفسها: List، وImage، وCanvas، وWebView وVideo، ولكل منها صفحة مرجعية خاصة. وخصائصها موثقة ضمن العناصر. أما حقل إدخال النص Input فيأتي من nsh/base.

#المنطقة الآمنة ولوحة المفاتيح

تُبقي متغيرات البيئة في CSS المحتوى بعيداً عن واجهة النظام، في الحشو (padding) والهامش (margin) لأي عرض (padding، paddingTop، …، مفاتيح margin نفسها؛ والقيم الاعتباطية p* / m* في Tailwind؛ والدوال Styled .p_safe_area()، .pt_safe_area_plus(..)، .pb_keyboard()، … في Rust). قيمها هي EnvValue: env(name)، env(name, <length>)، calc(env(name) + <length>) وcalc(<length> + env(name)).

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

#safeArea and safeAreaInsets

safeArea() هي المنطقة الآمنة للسطح (safe_area() في Rust)؛ وsafeAreaInsets() هي الهوامش حيث يُعرض المكوّن (cx.insets() في Rust)، وهي قيم المتغيرات safe-area-inset-*. كلاهما Edges تفاعلي ({ top, right, bottom, left } بالنقاط). راجع safeArea and safeAreaInsets.

#Keyboard and keyboardFrame

Keyboard.dismiss() يخفي لوحة المفاتيح البرمجية (dismiss_keyboard() في Rust) وkeyboardFrame() يخبرك بمقدار ما تغطيه من الشاشة (keyboard_height() وkeyboard_duration() في Rust). راجع إخفاء لوحة المفاتيح و ارتفاع لوحة المفاتيح.

#العروض القابلة للتحديد

<View selectable> (view().selectable(true) في Rust) يجعل النصوص داخله تُحدَّد معاً، كما في صفحة الويب: تمتد تحديدة واحدة عبر العروض وعناصر Text وعناصر TextView بترتيب القراءة. راجع تحديد النص.

#الرسوم المتحركة

تحرّك واجهة برمجة الرسوم المتحركة على خيط واجهة المستخدم. تنشئ قيمة متحركة، وتربطها (أو القيم المشتقة منها) بخاصية نمط، وتبدأ الحركة؛ ومن ذلك الحين يُحسب كل إطار أصلياً، دون تشغيل شيفرة التطبيق. ولا يمكن لمحرك مشغول أو خيط JS مشغول أن يجعل الحركة متقطعة، ولا تكلّف الحركة التطبيق أي عمل لكل إطار. تستخدم شيفرة Rust animated_value() وmotion() وAnimation وSpring وTiming وKeyframeTiming وMotionPreset وEasing من nsh_core::prelude وتربط القيم بدوال .bind_* الخاصة بالعناصر؛ أما TSX فيستوردها من nsh.

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

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

راجع الرسوم المتحركة للاطلاع على الدليل.

#ما الذي يمكن أن تقوده القيمة المتحركة

تأخذ خصائص النمط الأخرى قيماً عادية؛ ولتحريك التخطيط نفسه (الأحجام، والمواضع في التدفق)، استخدم LayoutAnimation.

#createAnimatedValue

function createAnimatedValue(value?: number): AnimatedValue;

ينشئ قيمة متحركة تبدأ من value (الافتراضي 0). في Rust: animated_value(value)، وهو مقبض Copy يحتفظ به المكوّن الذي أنشأه.

use nsh_core::prelude::*;

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

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

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

mount(App);

#AnimatedValue

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

تعيد كل دالة حركة وعداً (promise) يحلّ بـ { finished }: true عندما انتهت الحركة، وfalse عندما أُوقفت (بواسطة stop أو set أو حركة أخرى للقيمة نفسها). وفي Rust تعيد AnimationEnd، تنتظرها مهمة (task) للحصول على bool نفسه.

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

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

#AnimatedNode

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

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

عقدة في رسم الحركة الأصلي: AnimatedValue، أو قيمة مشتقة من قيم أخرى. تُقيَّم العقد المشتقة على خيط واجهة المستخدم كلما تغيّرت مدخلاتها.

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) قيمةً عبر إطارات مفتاحية (keyframes) ويُنجَز بالقيمة { finished } التي تبيّن هل اكتملت؛ Animated.keyframes(value, { keyframes, ...options }) مثل خطوة في animation مركّب. 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 المفتاحية: يشكّل الـ easing مقطعًا واحدًا (easing الإطار المفتاحي للمقطع الذي يبدأ عنده، وeasing التوقيت لكل المقاطع الأخرى)؛ والإزاحات (offsets) الغائبة من الإطارات تُوزَّع بالتساوي، فيكون الأول عند 0 والأخير عند 1؛ وتبدأ كل دورة (iteration) بقفزة إلى أول إطار مفتاحي، وإن لم يكن هناك إطار عند 0 فإن القيمة تنطلق من موضعها الحالي؛ وخلال delay تحتفظ القيمة بأول إطار مفتاحي (في CSS animation-fill-mode: backwards)؛ وتشغّل الدورات العكسية المقاطع بالاتجاه المعاكس مع عكس منحنياتها؛ وتبقى القيمة حيث تتركها الدورة الأخيرة.

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

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

#createMotion

function createMotion(options?: MotionOptions): Motion;

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

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

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

ينشئ حركة (motion): قيمة متحركة لكل قناة من قنوات opacity وtransform في العرض، في حالة السكون (opacity والمقاييس 1، والبقية 0)، وحركات تُشغَّل عليها بشكل native. اربطه بـ style={motion.style}، أو وزّع motion.style أو motion.transform داخل style؛ يطبّق التحويل الإزاحات أولًا ثم التدويرات ثم المقاييس، مع دمج scale في scaleX وscaleY: 7 من خطوات التحويل الثماني للعرض، مما يترك واحدة لك ([{ perspective: 600 }, ...motion.transform] للقلب ثلاثي الأبعاد). initial يحدد أين تبدأ القنوات ({ opacity: 0 }؛ وتبدأ البقية في حالة السكون). مع enter، تبدأ القنوات التي تحرّكها من حيث تبدأ تلك الحركة (خلال initial) وتُشغَّل فورًا، وتكون الخيارات الأخرى هي توقيتها (delay وduration و…). تحرّك الحركة opacity وtransform فقط: توزيع motion.style يضبط opacity للعرض، لذا اربط motion.transform فقط إن أردت الاحتفاظ بـ opacity خاصة بك، وحرّك الألوان بقيمة متحركة وinterpolate. Rust: motion()، وهو مقبض Copy يحتفظ به المكوّن الذي أنشأه، ويُربط بـ .bind_motion(&m)؛ وmotion().entering(spec) تشغّل حركة الدخول.

عندما يطلب المستخدم حركة أقل (reduceMotion())، تصل play وanimation وenter فورًا إلى حيث تنتهي الحركة، دون أن تتحرك، ما لم يُضبط ignoreReduceMotion (في الخيارات أو في الحركة).

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

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

#motions

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

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

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

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

الحركات الجاهزة كبيانات: motion.play("shake") يشغّل motions.shake. MotionName هو أحد fadeIn أو fadeInUp أو fadeInDown أو fadeInLeft أو fadeInRight أو zoomIn أو popIn أو bounceIn أو slideInUp أو slideInDown أو flipInX أو flipInY (دخول)؛ fadeOut أو fadeOutUp أو fadeOutDown أو fadeOutLeft أو fadeOutRight أو zoomOut أو popOut أو slideOutDown أو slideOutUp (خروج)؛ shake أو headShake أو wiggle أو swing أو pulse أو heartbeat أو rubberBand أو jello أو tada أو jump أو flash (لفت الانتباه)؛ spin أو float أو breathe أو sway أو bob أو glow (تكرار). تصف صفحة Animation كل واحدة منها. وزّع preset لتعديله: motion.play({ ...motions.fadeInUp, duration: 600 }).

MotionSpec هي حركة من تصميمك: الإطارات المفتاحية لكل قناة ({ opacity: [0, 1], translateY: [24, 0] })، أو قائمة إطارات كما تكتبها Web Animations API ([{ opacity: 0, translateY: 24 }, { opacity: 1, translateY: 0 }]، والإطار بلا offset يُوضع بحسب موضعه في القائمة)، مع توقيت الإطارات المفتاحية. Rust: MotionSpec::new(KeyframeTiming) مع .values(channel, values) (موزّعة بالتساوي) و.track(channel, keyframes) و.timing(|t| …)؛ MotionPreset::FadeInUp (أو .spec()) هو preset، وMotionChannel يسمّي القنوات.

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

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

#Animated

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

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

يبني Animated الرسوم المتحركة من خطوات (timing وspring وdecay وsequence وparallel و…). لا يعمل شيء حتى start()؛ عندها تعمل الشجرة كلها بشكل native، وتبدأ كل خطوة على UI thread في اللحظة نفسها التي تنتهي فيها السابقة (بلا فجوة بين الإطارات، وبلا ذهاب وإياب إلى شيفرة التطبيق بين الخطوات). يبني Rust الشجرة نفسها بـ Animation.

CompositeAnimation:

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

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

#Easing

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

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

الـ easing بيانات، وليس دالة من التطبيق: يقيّمه runtime بشكل native. في 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). لرسم أحدها، يعطي Easing.sample(easing, count) (Rust: nsh_core::element::sample_easing) قيمه عند count من النقاط المتباعدة بالتساوي من 0 إلى 1؛ ويعطي Animated.sampleSpring وAnimated.sampleDecay (sample_spring وsample_decay) قيم spring أو decay، قيمة لكل إطار (عند fps، وهو 60 افتراضيًا) من from (0) حتى ينتهي. وتأتي الثلاثة من الشيفرة native التي تعمل بها الرسوم المتحركة. وفي أي مكان يُقبل فيه Easing في TSX يمكنك تمرير اسم ("easeOut")، أو منحنى Bézier تكعيبي بأربعة أرقام، أو منحنى من الكائن Easing.

Easing.steps(count, position) هو steps() في CSS: تقفز القيمة بين count من المستويات بدل أن تتحرك (sprite إطارًا بإطار، عقرب يدقّ). position يحدد مواضع القفزات: "jump-end" (الافتراضي، وكذلك "end")، أو "jump-start" ("start")، أو "jump-none" أو "jump-both"؛ Rust: Easing::Steps(count, StepPosition::JumpEnd) وJumpStart وJumpNone وJumpBoth.

المنحنيات بصيغة “in” (بطيئة في البداية). Easing.out(curve) يعكس المنحنى، وEasing.inOut(curve) يجعله متماثلًا، وEasing.in(curve) يبقيه كما هو؛ وفي Rust يكون ذلك هو EaseMode في 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) تغييرات التخطيط في الـ commit التالي بشكل native: العروض التي تتحرك أو يتغير حجمها تنزلق إلى إطاراتها الجديدة، والعروض الجديدة تظهر (بتلاشٍ أو بتكبير، بحسب property)، والعروض المحذوفة تختفي. استدعه قبل تغيير الحالة الذي يغيّر التخطيط مباشرة. Rust: animate_layout(LayoutAnimation)، مع presets الخاصة بـ nsh_core::element::LayoutAnimation أو انتقالاتها create وupdate وdelete.

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

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

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

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

#Device

تعرّف device API التطبيقَ بالجهاز وبيئته. تستدعي شيفرة Rust دوال nsh_core::prelude (window() وdark() وfont_scale() وlocale() وlifecycle() وos() وidiom() وpixel_ratio() وset_color_scheme() و…)؛ وتستوردها TSX من nsh. حجم النافذة ونظام الألوان ومقياس الخط ونسبة البكسل واللغة المحلية (locale) وحالة التطبيق كلها تفاعلية: اقرأها في binding (إغلاق closure يُمرَّر إلى عنصر في Rust، وJSX في TSX) أو computed أو effect، فيتحدّث كل ما يقرؤها عندما تبلّغ المنصة عن تغيير (تدوير الشاشة، تغيير حجم النافذة، التبديل إلى الوضع الداكن، تغيير حجم النص أو اللغة، الانتقال إلى شاشة بكثافة أخرى، مغادرة التطبيق والعودة إليه).

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

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

راجع الجهاز والبيئة للاطلاع على الدليل.

#windowSize

const windowSize: Accessor<Size>;

حجم السطح بالنقاط (points): النافذة، أو NshAppView / NshView المضمَّن. تفاعلي. Rust: window() -> Size<Points>.

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

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

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

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

#colorScheme

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

المظهر المعروض: مظهر النظام، ما لم يضبط التطبيق مظهره الخاص (nsh.json "appearance"، setColorScheme). تفاعلي. Rust: dark() -> bool؛ وألوان السمة (AdaptiveColor) ونسخة style ‏.dark(…) تتبعه دون قراءته. كما يتبعه متغيّر dark: في Tailwind (انظر Tailwind).

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

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

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

#fontScale

const fontScale: Accessor<number>;

حجم النص المفضّل لدى المستخدم نسبةً إلى الافتراضي (1 هو الحجم الافتراضي؛ Dynamic Type في iOS، وحجم الخط في Android)، أو حجم النص الذي يضبطه التطبيق المضيف بدلًا منه. تفاعلي. Rust: font_scale() -> f32. النص يتدرّج معه أصلًا ما لم allowFontScaling={false}؛ اقرأه عندما ينبغي أن تتبعه أحجام أخرى، مثل الأيقونات بجوار النص.

#locale

const locale: Accessor<string>;

لغة المستخدم المحلية بصيغة وسم BCP 47 ("en-US"، "zh-Hans-CN")، أو اللغة التي يضبطها التطبيق المضيف بدلًا منها. تفاعلي. Rust: locale() -> Locale (locale().as_str() هو الوسم). ينسّق Intl وفقها افتراضيًا؛ اقرأها لاختيار نصوص ترجماتك الخاصة (الجهاز والبيئة).

#lifecycle

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

هل التطبيق قيد الاستخدام، بمصطلحات AppState في React Native: "active" في المقدمة ويستقبل الإدخال، "inactive" وهو ظاهر دون التركيز (يملكه تطبيق أو نافذة أخرى، أو يعرض النظام شيئًا فوقه، كمبدّل التطبيقات أو مكالمة واردة)، "background" وهو غير ظاهر (في الخلفية، أو مصغّر، أو تبويب متصفح مخفي). والتطبيق المعروض داخل تطبيق native يتبع حالة ذلك التطبيق. تفاعلي. Rust: lifecycle() -> Lifecycle (Lifecycle::Active وInactive وBackground).

اقرأه في effect لإيقاف العمل الذي لا يراه أحد واستئنافه عند عودة التطبيق:

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

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

#setColorScheme

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

يعرض التطبيق بـ scheme مهما كان مظهر النظام، فورًا: colorScheme() وفئات dark: وسمة المكوّنات وعناصر التحكم في المنصة (التنبيهات، والنمط الافتراضي لشريط الحالة) تتبعه؛ و"system" يعيده إلى اتباع النظام. nsh.json "appearance" يضبطه منذ البداية. Rust: set_color_scheme(Appearance::Dark) (Appearance::Light وAppearance::System).

#platform

const platform: Platform;

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

المنصة التي يعمل عليها التطبيق، وهي ثابتة طوال مدة التشغيل.

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

const columns = platform.desktop ? 3 : 1;

#platform.select

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

تعيد القيمة الخاصة بنظام التشغيل الحالي (ios، android، web، …)، وإلا desktop أو mobile (بحسب platform.desktop)، وإلا native (كل المنصات عدا الويب)، وإلا default، وإلا undefined. يعتمد كود Rust على المطابقة مع os() (ومع is_desktop() لـ 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>;

عدد بكسلات الجهاز لكل نقطة (مثل 3 في معظم أجهزة iPhone). وهي تفاعلية: تتغير عندما تنتقل النافذة إلى شاشة ذات كثافة مختلفة (على 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 }، أي هل فتحها شيء ما: false عندما لا يعالج أي تطبيق المخطط. في Rust: open_url(url) من nsh_core::prelude، وهي نتيجة يُنتظر اكتمالها داخل مهمة (أو تُهمل)، وهي نفس 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>

• يجب أن يكون الرابط مطلقًا (له مخطط). الروابط التي قد تنفّذ كودًا أو تصل إلى بيانات التطبيق نفسه، javascript: وdata: وblob: وfile: وabout: وasset:، ترفض الوعد بـ TypeError، وكذلك العناوين النسبية. لا ترمي openUrl استثناءً أبدًا: كل فشل يرفض الوعد.
• يحتاج التطبيق الذي يعلن القدرات إلى openUrl: "openUrl": true لكل المخططات، أو "openUrl": { "schemes": ["https", "mailto"] } للمخططات المدرجة؛ وترفض الروابط الأخرى بـ Error تكون code فيه "ERR_ACCESS_DENIED"، وpermission "openUrl" وresource الرابط (انظر الصندوق الرملي والقدرات). في Rust، تُجيب open_url بـ false في هذه الحالات وتسجّل السبب.
• يرى التطبيق المضيف الرابط أولًا ويمكنه توجيهه عبر موجّهه الخاص بدلًا من ذلك (Swift NshAppView.onOpenURL، Java NshView.setOpenUrlHandler، Rust AppView::host().handle_open_url؛ انظر iOS وAndroid). وتكون opened عندئذ true.
• تفتحه كل منصة بفاتحها الخاص: UIApplication.open في iOS (تطبيق المضيف عند التضمين)، وintent من نوع ACTION_VIEW في Android، وNSWorkspace في macOS، وShellExecuteW في Windows، وGtkUriLauncher في Linux، وopen_url من GPUI، وعلامة تبويب جديدة في الويب. أما nsh test فتسجّل الروابط بدلًا من فتحها.
• يفتح TextView روابطه بهذه الطريقة باستخدام links="open".

#اتجاه التخطيط

يتبع اتجاه التخطيط لغة المستخدم: في اللغات التي تُكتب من اليمين إلى اليسار (العربية والعبرية وغيرهما) يُخطَّط التطبيق من اليمين إلى اليسار، وتبدأ الصفوف من اليمين، وتعني خصائص الأنماط left / right (marginLeft، paddingRight، …) البداية والنهاية. تُطبَّق التغييرات فورًا دون إعادة تشغيل.

يحدد نمط direction في العرض ("ltr" أو "rtl" أو "inherit"، وهو الافتراضي) اتجاه شجرته الفرعية؛ وفي Rust: .direction(LayoutDirection::..).

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

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

#ذات صلة

• هوامش المنطقة الآمنة (Rust safe_area()؛ TSX safeArea()، safeAreaInsets()) ولوحة المفاتيح البرمجية (Rust keyboard_height()؛ TSX keyboardFrame()) موصوفة في المنطقة الآمنة ولوحة المفاتيح.
• إعدادات قارئ الشاشة وتقليل الحركة موصوفة في إمكانية الوصول.

#PanResponder

مستجيبات السحب (Pan responders) هي إيماءات سحب مبنية فوق نظام مستجيب الإيماءات: يستحوذ العنصر على لمسات الإيماءة، ثم يسمعها وحده مع حالة الإيماءة، التي تتتبع مركز اللمسات والمسافة المقطوعة والسرعة نيابةً عنك. يستحوذ كود Rust عليها بـ .claim_touches(TouchClaim::…) ويسمعها بمستمعي .on_responder_* الذين يحمل ResponderEvent فيهم PanGesture، وكل ذلك في nsh_core::prelude؛ أما TSX فيستورد PanResponder من nsh، وتتلقى دوال onPanResponder… فيه حدث اللمس وحالة الإيماءة.

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

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

#PanResponder.create

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

interface PanResponderInstance {
  panHandlers: TouchProps;
}

تنشئ مستجيب سحب. وزّع panHandlers الخاصة به على العرض الذي يجب أن يستقبل الإيماءة. في Rust، يستحوذ العرض على اللمسات ويستمع بنفسه:

use nsh_core::prelude::*;

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

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

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

mount(App);

#دوال الاستدعاء

تتلقى كل دالة استدعاء حدث اللمس (GestureResponderEvent، من nsh) وحالة الإيماءة. في Rust، يقرر الاستحواذ عبر .ask(|request: &ClaimRequest| …)، مستدعيًا request.claim() لأخذ اللمسات (وبدون ask يأخذها دائمًا)، ويتلقى كل مستمع ResponderEvent تكون gesture فيه هي الحالة.

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

#PanResponderGestureState

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

في Rust: PanGesture، مع النقاط على شكل Point<Points>.

#داخل عروض التمرير

بينما يكون مستجيب السحب هو المستجيب، لا تتمرر عروض التمرير الأصلية المحيطة به (onShouldBlockNativeResponder افتراضيًا true). ولكي تتعايش إيماءة سحب أفقية مع التمرير العمودي، لا تصبح المستجيب إلا عند الحركات الأفقية:

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

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

بالنسبة إلى السحب الذي تتعرف عليه المنصة، يقرر TouchClaim::on_pan(PanActivation::horizontal(10.0, 10.0)) على الخيط الرئيسي أثناء حركة الأصابع. ويمكن أيضًا استخدام خصائص المستجيب الأساسية (onStartShouldSetResponder، onResponderGrant، onTouchStart، …) مباشرة على أي عنصر؛ انظر العناصر.

#Clipboard

تقرأ واجهة الحافظة (Clipboard) حافظة النظام وتكتب فيها: النص في كل مكان (UIPasteboard في iOS، ClipboardManager في Android، NSPasteboard وGDK وحافظة Win32 في أنظمة سطح المكتب، navigator.clipboard في الويب)، والصور في iOS وأنظمة سطح المكتب والويب، والملفات المنسوخة في مدير الملفات في أنظمة سطح المكتب وMac Catalyst. يستدعي كود Rust دوال nsh_core::prelude (set_clipboard، clipboard_string، …)؛ أما TSX فيستورد Clipboard من 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
}

تعيد عمليات القراءة في Rust نتائج يُنتظر اكتمالها داخل مهمة (spawn، أو دالة في وحدة async)؛ وClipboardImage هي nsh_core::element::ClipboardImage، مع url وsize (وهي Size<DevicePixels>).

تمر الصور عبر الحافظة في iOS وأنظمة سطح المكتب والويب. أما في Android فتحمل الحافظة النص فقط: تُرفض writeImage و readImage بـ Error تكون code فيه "ERR_FEATURE_UNAVAILABLE_ON_PLATFORM"، وتُحلّ hasImage بالقيمة false. في Rust، تترك set_clipboard_image الحافظة كما هي هناك، وتُجيب clipboard_image بـ None.

يستطيع المستخدم أيضًا النسخ بنفسه من نص قابل للتحديد؛ وواجهة الحافظة مخصصة للنسخ من الكود، مثل زر “نسخ”.

#Clipboard.writeText

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

تضع text في الحافظة، مستبدلة ما كان فيها. في Rust: set_clipboard(text).

use nsh_core::prelude::*;

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

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

const copied = signal(false);

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

#Clipboard.readText

readText(): Promise<string>;

تُحلّ بنص الحافظة، أو بـ "" عندما لا تحتوي على نص. في Rust: clipboard_string(). في iOS، قد تُظهر قراءة الحافظة إشعار اللصق من النظام (“App pasted from …”)، وفي Android 10 وما بعده لا يستطيع القراءة إلا التطبيق الموجود في المقدمة. اقرأها عندما يطلب المستخدم اللصق، وليس في كل شاشة.

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

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

#Clipboard.hasText

hasText(): Promise<boolean>;

تُحلّ بما إذا كانت الحافظة تحتوي على نص، دون قراءته: لا إشعار لصق في iOS. في Rust: clipboard_has_string(). استخدمها لتقرر هل تُظهر زر “لصق”. في الويب، لا تعرف المتصفحات إلا بالقراءة، لذا قد يُطلب من المستخدم إذن.

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

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

#Clipboard.readImage

readImage(): Promise<ClipboardImage | null>;

تُحلّ بصورة الحافظة، أو بـ null عندما لا تحتوي على صورة: لقطة شاشة ملصقة، أو صورة نُسخت في متصفح أو محرر صور. في Rust: clipboard_image()، وNone عندما لا تحتوي على صورة. url هو رابط الصورة (PNG، أو JPEG أو GIF أو WebP أو BMP الخاصة بالحافظة) الذي يعرضه Image بوصفه src وتقرؤه fetch: fetch(url) تعطي بايتاتها، لرفعها. وsize (width وheight) هو حجمها بالبكسل، كما فُكّ ترميزها. وكما في readText، اقرأها عندما يطلب المستخدم اللصق. تُقرأ الصور حتى 48 ميغابايت (مرمّزة) كي تتسع الصورة في ذاكرة التطبيق؛ وترفض الصورة الأكبر بـ Error تكون code فيه "ERR_NSH_QUOTA_EXCEEDED" (وتذكر رسالته حجم الصورة والحد الأقصى)، بينما تُحلّ hasImage بـ true. في Rust: تُجيب clipboard_image() بـ None في هذه الحالة.

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

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

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

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

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

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

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

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

يربط تطبيق على نمط الدردشة، يلصق فيه المستخدمون لقطات الشاشة في مربع الكتابة، اختصار اللصق ما دام حقل الإدخال في التركيز، ويأخذ الصورة إن وجدت:

use nsh_core::keymap::When;

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

import { keymap } from "nsh";

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

#Clipboard.hasImage

hasImage(): Promise<boolean>;

تُحلّ بما إذا كانت الحافظة تحتوي على صورة، دون قراءتها: لا إشعار لصق في iOS. في Rust: clipboard_has_image(). في Android تُحلّ بالقيمة false.

#Clipboard.writeImage

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

تضع صورة src، وهو رابط data: بترميز base64 أو url الذي أعطته readImage، في الحافظة، مستبدلة ما فيها. في Rust: set_clipboard_image(src). في Windows تقبل PNG، وهو التنسيق الذي تقرؤه المتصفحات وOffice وأداة القص. في Android تُرفض بـ "ERR_FEATURE_UNAVAILABLE_ON_PLATFORM".

set_clipboard_image(image.url.clone());

await Clipboard.writeImage(image.url);

#Clipboard.readFiles

readFiles(): Promise<string[]>;

تُحلّ بروابط file: للملفات والمجلدات المنسوخة في مدير الملفات (Finder وExplorer وFiles)، بترتيبها، أو بـ []: وهي نفس الروابط التي يعطيها إسقاط الملفات. في Rust: clipboard_files(). حلّل الرابط للحصول على مساره.

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 أداة اختيار الصور في النظام ويمنح التطبيق الصور التي يختارها المستخدم: أداة Photos picker على iOS (PHPickerViewController)، وأداة Photo Picker على Android، ولوحة فتح أو مربع حوار ملفات على أنظمة سطح المكتب، وحقل إدخال ملف (file input) في المتصفح. على iOS وAndroid تعمل الأداة خارج التطبيق وتسلّم فقط ما يختاره المستخدم، ولذلك لا تحتاج إلى إذن الوصول إلى مكتبة الصور. تصل كل صورة مختارة على شكل File (في TSX) أو PickedFile (في Rust) تبقى بايتاتها في الطبقة الأصلية (native): اعرضها باستخدام URL.createObjectURL(file) داخل Image، وارفعها باستخدام fetch وFormData. يستدعي كود Rust الدالة pick_images من nsh_core::prelude؛ أما TSX فيستورد Picker من 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[]>;

تعرض أداة الاختيار ثم تُنجَز بالصور التي اختارها المستخدم، بالترتيب الذي اختارها به، أو بالقيمة [] عندما يلغي المستخدم. في Rust: pick_images(request)، وهي نتيجة تُنتظر داخل مهمة (task) (spawn، أو دالة وحدة (module) من async). pickImages لا ترمي استثناءً أبدًا: الخيارات خارج النطاق (limit: 0، أو quality خارج المجال من 0 إلى 1) ترفض الوعد (promise) بـ RangeError، والاختيار الذي لا تمنحه صلاحيات التطبيق (capabilities) يُرفض بـ ERR_ACCESS_DENIED (انظر أدناه). الإلغاء هو جواب المستخدم وليس فشلًا: فهو يُنجز بالقيمة [].

تصل الصور جاهزة للإرسال:

• صيغ يقبلها كل متصفح وكل خادم. تصل صور JPEG وPNG وGIF وWebP كما هي؛ أما الصورة المخزّنة بصيغة أخرى (HEIC على أجهزة iPhone، وHEIF، وTIFF) فتصل بصيغة JPEG. format: "current" تُبقي الصيغة المخزّنة.
• تصغير أصلي (native). مع maxDimension، تُصغَّر الصورة التي يزيد ضلعها الأطول على هذا الحد لتناسبه، وتُعدَّل لتكون قائمة، ثم تُرمَّز من جديد: PNG بصيغة PNG، وأي صيغة أخرى بصيغة JPEG بجودة quality. صور الهواتف بدقة 12 إلى 48 ميغابكسل؛ وتصغيرها إلى 2048 بكسل قبل الرفع يجعل حجمها بضع مئات من الكيلوبايتات. كما يعيد quality ترميز صور JPEG.
• ما تعرضه. size هو حجم الصورة بالبكسل كما تظهر، بعد تطبيق اتجاه الكاميرا. الصورة التي يعيد NSH ترميزها لا تحمل أي بيانات وصفية (ولا الموقع)؛ أما التي تصل كما هي فتحتفظ ببياناتها.

على Windows وLinux وفي نوافذ GPUI، يعرض مربع الحوار الصيغ التي يقبلها الطلب (مع "compatible": ‏JPEG وPNG وGIF وWebP) وتصل الملفات كما هي مخزّنة وبحجمها الأصلي.

يرفق مُحرِّر الدردشة صورة، ويعرضها أثناء كتابة الرسالة، ثم يرفعها عند الإرسال:

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

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

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

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

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

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

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

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