Elements

Native Shell हर स्क्रीन को एलिमेंट के एक छोटे सेट से बनाता है: View, Text और Image जैसे प्रिमिटिव, और Button, Dialog और NavStack जैसे बेस कंपोनेंट। हर प्रिमिटिव एक नेटिव व्यू है (iOS और Mac Catalyst पर UIView की सबक्लास, Android पर View, और डेस्कटॉप पर AppKit, GTK या Win32 व्यू), जिसे NSH रनटाइम बनाता और लेआउट करता है। ऐप जो कुछ भी दिखाता है, वह इन्हीं से बनता है: ऐप के बटन, कार्ड, रो और स्क्रीन उसके अपने कंपोनेंट हैं, जो इन एलिमेंट से बनाए जाते हैं और ऐप द्वारा स्टाइल किए जाते हैं, इसलिए ऐप का लुक पूरी तरह उसका अपना होता है।

इन पेजों का हर उदाहरण Rust और TSX दोनों में दिया गया है: एक टैब चुनें, और पेज के सभी उदाहरण उसी का अनुसरण करेंगे।

use nsh_core::prelude::*;

fn app() -> impl IntoElement {
    let count = signal(0_u32);
    view()
        .flex_1()
        .items_center()
        .justify_center()
        .gap_3()
        .child(text(move || format!("Tapped {} times", count.get())).text_2xl())
        .child(
            view()
                .rounded_lg()
                .bg(rgb(0x2563eb))
                .px_4()
                .py_2()
                .active(|s| s.opacity(0.6))
                .on_press(move || count.update(|n| *n += 1))
                .child(text("Tap").text_color(white())),
        )
}

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

function App() {
  const count = signal(0);
  return (
    <View style={{ flex: 1, alignItems: "center", justifyContent: "center", gap: 12 }}>
      <Text style={{ fontSize: 24 }}>Tapped {count()} times</Text>
      <View onPress={() => count.update((n) => n + 1)} class="rounded-lg bg-blue-600 px-4 py-2 active:opacity-60">
        <Text class="text-white">Tap</Text>
      </View>
    </View>
  );
}

mount(App);

Rust में, प्रिमिटिव nsh_core::prelude (view(), text(..), image(..)) के फ़ंक्शन हैं और बेस कंपोनेंट nsh_base क्रेट से आते हैं। स्टाइल टाइप्ड मेथड हैं (.flex_1(), .gap_3(), .px(px(20.0)), .bg(..)), स्टेट स्टाइल एक क्लोज़र लेते हैं (.active(|s| s.opacity(0.6))), लिसनर अपने इवेंट के क्लोज़र हैं (.on_press(move || ..), .on_change(move |text: &str| ..)) और .child(..) चिल्ड्रन जोड़ता है। UI का एक हिस्सा impl IntoElement लौटाने वाला साधारण फ़ंक्शन है; यह एक बार चलता है, और क्लोज़र में पढ़े गए सिग्नल (text(move || ..), .bg(move || ..)) उन चीज़ों को अपडेट करते हैं जिनसे वे बंधे हैं। देखें Rust के साथ बनाना।

TSX में, हर टैग PascalCase में होता है और स्कोप में मौजूद किसी बाइंडिंग का नाम होता है: प्रिमिटिव nsh से आते हैं, बेस कंपोनेंट nsh/base से। केवल <If> और <Each> ग्लोबल हैं जिन्हें इम्पोर्ट की ज़रूरत नहीं होती। <view> जैसा लोअरकेस टैग बिल्ड एरर है, क्योंकि TypeScript उसे हर नाम के लिए एक ग्लोबल टाइप से जाँचेगा, और List और Each जैसे जेनेरिक कंपोनेंट अपने आइटम टाइप का अनुमान नहीं लगा पाएँगे। कंपाइलर एलिमेंट को उनके इम्पोर्ट से पहचानता है और नेटिव व्यू को इन-प्लेस बनाता है, इसलिए उन्हें इम्पोर्ट करने की रन टाइम पर कोई लागत नहीं है। देखें JSX और कंपोनेंट।

import { Canvas, Image, List, Overlay, Scroll, Shader, Text, Video, View, WebView } from "nsh";
import { Button, Dialog, Menu, NavPage, NavStack, Popover, Sheet, Tooltip, Input } from "nsh/base";

#प्रिमिटिव

TSX में nsh से और Rust में nsh_core::prelude से इम्पोर्ट किए जाते हैं।

पैडिंग और मार्जिन, CSS के env() के साथ, कंटेंट को सिस्टम UI से दूर रखते हैं: env(safe-area-inset-top) और अन्य किनारे (सेफ़ एरिया) और env(keyboard-inset-height) (कीबोर्ड)।

#बेस

TSX में nsh/base से और Rust में nsh_base क्रेट से इम्पोर्ट किए जाते हैं। ये व्यवहार, स्टेट, फ़ोकस और एक्सेसिबिलिटी संभालते हैं और अपना लुक ऐप से लेते हैं।

#सामान्य props

हर प्रिमिटिव नीचे दिए गए props स्वीकार करता है (TSX में CommonProps टाइप; Rust में Styled, Interactive और Accessible ट्रेट)। एलिमेंट के पेज केवल अपने props सूचीबद्ध करते हैं। Rust कॉलम बिल्डर मेथड का नाम बताता है।

#स्टाइलिंग

#प्रेस और फ़ीडबैक

प्रेस हैंडलिंग नेटिव तरीके से चलती है: प्लेटफ़ॉर्म प्रेस को पहचानता है और ऐप की प्रेस स्टाइल लागू करता है, और ऐप का कोड इसके बारे में केवल बाद में सुनता है। केवल सबसे अंदरूनी दबाने योग्य व्यू प्रतिक्रिया देता है; स्क्रॉल व्यू के अंदर प्रेस-इन लगभग 130 ms प्रतीक्षा करता है ताकि पहले स्क्रॉल शुरू हो सके।

PressEvent है { position, pagePosition, modifiers, clickCount }: पॉइंटर व्यू में और उसके रूट व्यू में कहाँ था (Point), प्रेस शुरू होने पर दबी हुई मॉडिफ़ायर कीज़ और लगातार क्लिक (डबल क्लिक के लिए 2)। जहाँ प्लेटफ़ॉर्म कोई पॉइंटर रिपोर्ट नहीं करता, वहाँ यह व्यू का ऑरिजिन होता है, बिना कीज़ और एक क्लिक के साथ।

स्टाइल की pointerEvents (Rust में .pointer_events(PointerEvents::BoxNone), क्लास pointer-events-*) तय करती है कि व्यू और उसके अंदर के व्यू को कौन से टच मिलते हैं: "none" कोई नहीं (अंदर का कोई व्यू जो "auto" सेट करता है, उन्हें फिर से ले लेता है), "box-none" केवल उसके अंदर के व्यू, "box-only" केवल व्यू खुद (टच और जेस्चर)।

प्रेस फ़ीडबैक ऐप का अपना होता है: activeStyle (या active: क्लास, Rust में .active(..)) तब लागू होता है जब व्यू दबा हुआ हो, नेटिव तरीके से, ऐप के कोड तक गए बिना (नीचे)।

#स्टेट स्टाइल

वे स्टाइल जो व्यू के किसी स्टेट में होने पर, उसकी अपनी स्टाइल के ऊपर, नेटिव तरीके से लागू होती हैं। हर एक Tailwind वेरिएंट का ऑब्जेक्ट रूप है। बाद की स्टेट को प्राथमिकता मिलती है (selected, checked और indeterminate, फिर hover, focus, active); disabledStyle सब पर भारी पड़ता है, और व्यू के डिसेबल होने पर बाकी लागू नहीं होतीं। हर एक एलिमेंट की अपनी स्टाइल लेता है: <Text> पर TextStyle, <Input> पर InputStyle, <Image> पर ImageStyle, और अन्य जगह ViewStyle।

view()
    .rounded_lg()
    .bg(rgb(0x2563eb))
    .px_4()
    .py_2()
    .active(|s| s.opacity(0.6))
    .hover(|s| s.bg(rgb(0x1d4ed8)))
    .on_press(save)
    .child(text("Save").text_color(white()))

<View onPress={save} activeStyle={{ opacity: 0.6 }} hoverStyle={{ backgroundColor: "#1d4ed8" }} class="rounded-lg bg-blue-600 px-4 py-2">
  <Text class="text-white">Save</Text>
</View>

#Hover

ऐप को पता चलता है कि माउस किसी view के ऊपर आया, उस पर चला और उसे छोड़कर गया। यह macOS, Windows, Linux, GPUI backend और डेस्कटॉप ब्राउज़रों में होता है। iOS पर iPad के पॉइंटर या Mac के माउस से, और Android पर माउस या स्टाइलस से भी होता है। Hover स्टाइल (hover:, .hover(..)) इन्हीं जगहों पर hover किए गए views को स्टाइल करते हैं।

CSS :hover और DOM के mouseenter की तरह, कोई view तब तक hover किया हुआ गिना जाता है जब तक माउस उस पर या उसके भीतर किसी भी चीज़ पर हो। इसलिए माउस के नीचे वाले view के आसपास के views भी onMouseEnter सुनते हैं (बाहर से भीतर की ओर; onMouseLeave भीतर से बाहर की ओर)। इवेंट बाद में आते हैं और touches पर कभी नहीं आते। माउस के नीचे से हटाया गया view onMouseLeave सुनता है, Linux और Windows पर अगली माउस मूवमेंट पर।

MouseEvent बताता है कि माउस कहाँ है, जैसा GPUI का MouseMoveEvent करता है। इसमें view में position है (points में Point, उसके transforms पूर्ववत किए हुए) और उस root view में pagePosition है जिसमें वह है, जैसा touches देते हैं। इसमें दबे हुए modifiers भी हैं (control, alt, shift, platform: Apple प्लेटफ़ॉर्म पर Command, अन्यत्र Windows key) और pressedButton भी, यानी दबा हुआ बटन ("left", "right", "middle", "back" या "forward", GPUI का MouseButton) या null; Rust में position, page_position, modifiers और pressed_button। डेस्कटॉप और वेब पर drag एक touch भी है (onTouchMove, रिस्पॉन्डर), और उसकी moves onMouseMove तक pressedButton सेट के साथ पहुँचती हैं। जो फ़ीडबैक केवल hover को फ़ॉलो करता है, वह इन्हें छोड़ देता है; iOS और Android पर hover बिना किसी बटन दबे पॉइंटर को रिपोर्ट करता है। Moves प्रति फ़्रेम अधिकतम एक बार आती हैं, सबसे ताज़ा वाली, और हमेशा उस onMouseLeave से पहले जो उनके बाद आता है, इसलिए हैंडलर हर move पर redraw कर सकता है:

// A crosshair over a chart.
let at = signal(None::<Points>);

view()
    .h(px(200.0))
    .on_mouse_move(move |e: &MouseEvent| at.set(Some(e.position.x)))
    .on_mouse_leave(move |_: &MouseEvent| at.set(None))
    .child(when(move || at.get().is_some(), move || {
        view()
            .absolute()
            .left(move || at.get().unwrap_or_default())
            .top_0()
            .bottom_0()
            .w(px(1.0))
            .bg(rgb(0x888888))
    }))

// A crosshair over a chart.
const at = signal<number | null>(null);

<View onMouseMove={(e) => at.set(e.position.x)} onMouseLeave={() => at.set(null)} style={{ height: 200 }}>
  <If when={at() !== null}>
    <View style={{ position: "absolute", left: at()!, top: 0, bottom: 0, width: 1, backgroundColor: "#888" }} />
  </If>
</View>

#Tooltips

tooltip किसी भी element को एक संकेत (hint) देता है। यह डेस्कटॉप (macOS, Windows, Linux, GPUI backend और डेस्कटॉप ब्राउज़र) पर element के ऊपर तब दिखता है जब पॉइंटर उस पर आधा सेकंड टिका रहे। यह तब तक रहता है जब तक पॉइंटर हट न जाए या उसे दबा न दे। फ़ोन और टैबलेट कोई संकेत नहीं दिखाते। संकेत कभी पॉइंटर या प्रेस नहीं लेता, इसलिए element ठीक वैसे ही काम करता है जैसे उसके बिना करता।

view()
    .on_press(save)
    .tooltip(
        tooltip()
            .rounded_md()
            .bg(rgb(0x111827))
            .px_2()
            .py_1()
            .child(text("Save the document").text_color(white())),
    )
    .child(text("💾"))

<View
  onPress={save}
  tooltip={
    <Tooltip class="rounded-md bg-gray-900 px-2 py-1">
      <Text class="text-white">Save the document</Text>
    </Tooltip>
  }
>
  <Text>💾</Text>
</View>

Tooltip अपना रूप, placement, delay और events खुद तय करता है, जैसे GPUI का .tooltip(..) करता है। बहुत से tooltips वाला ऐप अपना एक छोटा component रखता है, जो किसी टेक्स्ट को उसके Tooltip में लपेटता है।

#Context menus

onContextMenu view को बताता है कि उस पर secondary बटन दबाया गया। यह right click, macOS पर Control-click, touchpad पर दो-उँगली click या iPad के पॉइंटर का secondary click हो सकता है; ब्राउज़रों में कीबोर्ड की menu key भी। वहाँ ऐप का अपना मेनू खोलें; TSX में Menu.popup सिस्टम का मेनू दिखाता है:

// The app's own menu, placed where the click was.
let menu_at = signal(None::<Point<Points>>);

view()
    .on_context_menu(move |e: &ContextMenuEvent| menu_at.set(Some(e.page_position)))
    .child(text(row.name.clone()))

import { Menu } from "nsh/desktop";

<View onContextMenu={(e) => Menu.popup(rowMenu(row), e.pagePosition)}>…</View>

ContextMenuEvent में view में position, उसके root view में pagePosition (जहाँ Menu.popup मेनू रखता है: Menu.popup(items, e.pagePosition)) और modifiers होते हैं; Rust में position, page_position और modifiers। जो सबसे नज़दीकी view इसे सुनता है, पॉइंटर के नीचे वाले से बाहर की ओर गिनते हुए, उसे यह मिलता है। उस view से नज़दीक कोई text input, या edit मेनू वाला selectable text (Windows, GPUI backend, ब्राउज़र), इसके बजाय अपना मेनू दिखाता है। प्लेटफ़ॉर्म यह बटन दबते ही, जो कुछ mount है उसके आधार पर तय करता है। इसलिए हैंडलर को बाद में बताया जाता है और कुछ रद्द नहीं करना पड़ता। disabled view क्लिक को अपने आसपास के सबसे नज़दीकी enabled listener पर छोड़ देता है। टचस्क्रीन पर long press मेनू खोलता है: onLongPress को उसी function से हैंडल करें।

#Keyboard focus

macOS और वेब पर Tab कीबोर्ड फ़ोकस को उसके stops के बीच tree order में ले जाता है: inputs, प्रेस लेने वाले views, और हर focusable view। Focus स्टाइल (focus:, .focus(..)) फ़ोकस वाले view को स्टाइल करते हैं, और प्रेस लेने वाले view को Return या Space दबाता है। क्लिक view को फ़ोकस किए बिना उसे दबाता है, इसलिए focus स्टाइल केवल कीबोर्ड फ़ोकस पर दिखते हैं।

Focus और प्रेस अलग-अलग हैं। जो view फ़ोकस रहते हुए keys लेता है (चार्ट, slider, या ऐसी सूची जो तीर कुंजियों से अपना selection हिलाती है), वह focusable सेट करता है और फ़ोकस रहते हुए अपनी keys bind करता है (onFocus / onBlur के साथ keymap)। उस पर प्रेस फिर भी उसके आसपास के pressable तक पहुँचता है, जैसे कोई कार्ड जो पेज खोलता है।

ref का focus() कीबोर्ड फ़ोकस को किसी stop पर ले जाता है, जैसे Tab करता है (उसके focus स्टाइल दिखते हैं और onFocus चलता है)। इसका उपयोग, जैसे, बंद हुए popup के trigger को फ़ोकस वापस देने के लिए किया जा सकता है। blur() फ़ोकस को हटा देता है।

आसपास का view focus-within: (focusWithinStyle, .focus_within(..)) से फ़ोकस को स्टाइल करता है, जब फ़ोकस उस पर या उसके भीतर के किसी view पर हो। जैसे edit करने वाले input के चारों ओर फ़ील्ड का frame, या टूलबार जब उसका कोई बटन फ़ोकस में हो। Overlay की सामग्री उस view के भीतर मानी जाती है जिसमें overlay है, चाहे वह कहीं भी दिखे, इसलिए popup को उस view का हिस्सा गिना जाता है जिसमें उसका trigger है। Rust में, component फ़ोकस के element में आने और उससे जाने को उसके ref के on_focus_in(..) और on_focus_out(..) से सुनता है: उसके भीतर के views के बीच फ़ोकस जाना इनमें से कुछ नहीं है।

view()
    .rounded_lg()
    .p_3()
    .focus(|s| s.bg(rgb(0xe0f2fe)))
    .on_press(open)
    .child(text("Open"))

// An overlay's backdrop: a click closes it, Tab goes past it to the content.
view().absolute().inset_0().focusable(false).on_press(close)

// A chart in a card: Tab stops at the chart, a click opens the card's page.
view().on_press(open_page).child(
    view()
        .h(px(160.0))
        .focusable(true)
        .focus(|s| s.bg(rgb(0xe0f2fe)))
        .on_focus(move || focused.set(true))
        .on_blur(move || focused.set(false)),
)

<View class="rounded-lg p-3 focus:bg-sky-100" onPress={open}>
  <Text>Open</Text>
</View>

{/* An overlay's backdrop: a click closes it, Tab goes past it to the content. */}
<View class="absolute inset-0" focusable={false} onPress={close} />

{/* A chart in a card: Tab stops at the chart, a click opens the card's page. */}
<View onPress={openPage}>
  <View
    class="h-40 focus:bg-sky-100"
    focusable
    onFocus={() => focused.set(true)}
    onBlur={() => focused.set(false)}
  />
</View>

#Layout and identity

#Animated values को चलाने वाले gestures

ये props किसी gesture को native animated values से बाँधते हैं, जो UI thread पर चलते हैं और इनके लिए ऐप के कोड में प्रति फ़्रेम कोई काम नहीं करना पड़ता। touch and gestures देखें।

PanEvent है { cancelled, translation, velocity, value? } (Rust में cancelled, translation, velocity_x, velocity_y, value_x, value_y)। इसमें यह होता है कि सिस्टम ने drag रद्द किया या नहीं, शुरुआत से अब तक translation, points प्रति सेकंड में velocity (Points), और उस क्षण के bound values। { x?, y? } उन axes के लिए होता है जिन्हें pan बाँधता है (drag animation के बीच किसी value को पकड़ सकता है)।

#Raw touches और responder सिस्टम

जिन gestures को ऊपर के props कवर नहीं करते, उनके लिए हर element touch और responder props लेता है: onTouchStart, onTouchMove, onTouchEnd, onTouchCancel (और उनके …Capture रूप), onStartShouldSetResponder, onMoveShouldSetResponder (और …Capture), onResponderGrant, onResponderReject, onResponderStart, onResponderMove, onResponderEnd, onResponderRelease, onResponderTerminate और onResponderTerminationRequest। हर हैंडलर को एक GestureResponderEvent ({ identifier, locationX, locationY, pageX, pageY, target, timestamp, touches, changedTouches, nativeEvent, stopPropagation() }); the …ShouldSetResponder handlers also get a gestureState (dx, dy, vx, vy, …) मिलता है। onResponderGrant से true लौटाना native scroll views को touches लेने से रोकता है। panActivation ({ activeOffsetX, activeOffsetY, failOffsetX, failOffsetY }) view को responder तभी बनाता है जब प्लेटफ़ॉर्म उसका pan सक्रिय करता है, इसलिए scroll views के भीतर drags दूसरे axis को उन्हीं पर छोड़ देते हैं (Touch and gestures)। PanResponder में PanResponder इन्हीं पर बना है। Rust में, .on_touch(..) हर touch सुनता है (TouchEvent), .claim_touches(..) तय करता है कि view उन्हें कब ले, और .on_responder_grant(..), .on_responder_move(..), .on_responder_release(..) और बाकी responder को फ़ॉलो करते हैं।

#Accessibility

accessibility देखें।

#केवल एक प्लेटफ़ॉर्म के props

जो props किसी एक प्लेटफ़ॉर्म पर ही होते हैं, वे TSX में उसी प्लेटफ़ॉर्म के नाम वाले object में जाते हैं, इसलिए साझा props हर जगह एक जैसे रहते हैं। केवल मौजूदा प्लेटफ़ॉर्म का object भेजा जाता है; बाकी अनदेखे किए जाते हैं। Rust builders इन्हें ऐसे methods के रूप में लेते हैं जो अपने प्लेटफ़ॉर्म पर लागू होते हैं।

use nsh_core::Ripple;

view()
    .rounded_lg()
    .bg(white())
    .p_4()
    .elevation(px(2.0))
    .ripple(Ripple { color: Some(rgba(0x00000022).into()), ..Ripple::default() })
    .on_press(save)
    .child(text("Save"))

<View onPress={save} android={{ ripple: { color: "#00000022" }, elevation: 2 }} class="rounded-lg bg-white p-4">
  <Text>Save</Text>
</View>

platform-specific code देखें।

#Ref मेथड

TSX में, ref को एलिमेंट का ref मिलता है, जिसका टाइप एलिमेंट का अपना होता है: View, Text, Image, Canvas, Overlay और Shader के लिए ViewRef (focus, blur, measure), और बाकी के लिए ViewRef के ऊपर एक टाइप, जिसमें एलिमेंट के अपने मेथड होते हैं: InputRef (Input), ScrollRef (Scroll), ListRef (List), WebViewRef (WebView), VideoRef (Video) और NativeComponentRef (नेटिव कॉम्पोनेंट)। Rust में, element_ref() एक ElementRef हैंडल बनाता है जिसे .element_ref(&handle) अटैच करता है। इनके मेथड नेटिव व्यू को कमांड भेजते हैं, और उसी टर्न में उनसे पहले किए गए बदलावों के क्रम में ही भेजते हैं। हर एलिमेंट के पेज पर बताया गया है कि उस पर कौन-से लागू होते हैं। ref वेरिएबल को उसके एलिमेंट के अपने टाइप से टाइप करें (<Input> के लिए let field!: InputRef): ViewRef टाइप वाला वेरिएबल ऐसे एलिमेंट के साथ फिट नहीं होता जिसके ref में अपने मेथड हों।

let field = element_ref();

view()
    .on_press(move || field.focus())
    .child(input().element_ref(&field).placeholder("Tap the row to type"))

import { type InputRef, View } from "nsh";
import { Input } from "nsh/base";

let input!: InputRef;
<View onPress={() => input.focus()}>
  <Input ref={input} placeholder="Tap the row to type" />
</View>;

#हैंडलर UI को कभी ब्लॉक क्यों नहीं करते

मुख्य थ्रेड ऐप के कोड का इंतज़ार कभी नहीं करता। जब सिस्टम को उसी समय जवाब चाहिए होता है (क्या यह टेक्स्ट बदल सकता है, क्या बैक बटन पेज को पॉप कर सकता है, क्या यह शीट बंद हो सकती है), तब NSH पहले से सेट किए गए प्रॉप्स (maxLength, popOnBack, closeOnSwipe, …) के आधार पर उसका जवाब नेटिव रूप से देता है, और इवेंट ऐप तक बाद में पहुँचता है। इसीलिए ऐसा व्यवहार प्रॉप होता है, हैंडलर का रिटर्न वैल्यू नहीं।