nsh

nsh è il modulo core: l’API reattiva (signal, valori computed, effect, context), mount, token, gli elementi host View, Text, Scroll e Overlay, le viste selezionabili, l’area sicura e la tastiera, l’animazione, il dispositivo e il suo ambiente, PanResponder, gli appunti, il selettore di foto, il riconoscimento vocale, lo storage, il canale host, le scorciatoie da tastiera, i componenti e moduli nativi, l’accessibilità e i tipi TypeScript di elementi, stili ed eventi. Il grafo reattivo stesso viene eseguito nativamente in Rust; leggere un signal è una chiamata al runtime che costa pochi nanosecondi, e solo le tue closure vengono eseguite nell’interprete JavaScript.

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

La reattività di NSH segue lo stesso modello di SolidJS: una funzione componente viene eseguita una sola volta, e le parti della UI che leggono signal vengono aggiornate sul posto quando quei signal cambiano. Non c’è alcun nuovo render del componente e non c’è un DOM virtuale. Consulta Reattività per la guida.

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

Un signal contiene un valore. Chiamarlo legge il valore e, all’interno di uno scope di tracciamento (espressioni JSX, computed, effect), vi sottoscrive quello scope. set e update lo scrivono; tutto ciò che lo ha letto viene aggiornato.

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

Per impostazione predefinita, una scrittura === al valore corrente non fa nulla. Passa equals: false per notificare a ogni scrittura (utile quando modifichi un oggetto sul posto e imposti di nuovo lo stesso oggetto), oppure passa un tuo confronto:

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

Un valore derivato da signal. fn viene eseguita di nuovo quando cambia un signal che ha letto; i lettori del valore computed si aggiornano solo quando il suo risultato cambia (secondo equals, === per impostazione predefinita). fn riceve il risultato precedente.

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

Usa computed quando una derivazione è costosa o viene letta in più punti. Per un’espressione economica, una semplice funzione (const full = () => first() + " " + last()) è altrettanto reattiva.

#effect

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

Esegue fn dopo il rendering, e di nuovo ogni volta che cambia un signal che ha letto. Usa gli effect per gli effetti collaterali: logging, timer, comunicazione con i moduli nativi. Un effect appartiene al componente (o effect) in cui è stato creato e viene eliminato insieme a esso.

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

Per annullare qualcosa prima che l’effect venga eseguito di nuovo (o quando il suo componente scompare), chiama cleanup al suo interno.

#batch

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

Esegue fn e applica tutte le sue scritture insieme alla fine, così i lettori si aggiornano una volta sola invece che una volta per scrittura. Restituisce ciò che restituisce fn.

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

#untracked

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

Esegue fn senza sottoscrivere lo scope corrente a ciò che legge. Usalo per leggere un signal all’interno di un effect o di un’espressione JSX senza dipendere da esso.

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

#cleanup

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

Registra fn da eseguire prima che l’effect corrente venga eseguito di nuovo, o quando il componente o l’effect corrente scompare.

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

Un valore che un componente fornisce a tutto ciò che renderizza, a qualsiasi profondità. Chiamare il context (Theme()) legge il valore del provider più vicino, oppure defaultValue se non ce n’è nessuno.

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;

Renderizza app nella superficie (la finestra, oppure NshAppView / NshView in cui l’app è incorporata) e restituisce una funzione che lo rimuove. Il file di ingresso di ogni app termina con 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]>];

Divide un oggetto props nelle props indicate in keys e nel resto. Entrambe le metà restano reattive: le props i cui valori cambiano sono getter, e split le mantiene come getter. Usalo in un componente che gestisce da sé alcune props e passa le altre. Destrutturare le props (const { label } = props) le leggerebbe una sola volta e perderebbe gli aggiornamenti.

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;

Renderizza i suoi figli, oppure fallback non appena qualcosa al di sotto di essi genera un errore: il corpo di un componente, un binding, un effect o un gestore di eventi. La parte che ha fallito viene rimossa e al suo posto compare il fallback. Una funzione fallback viene chiamata come fallback(error, reset) con il valore lanciato e con reset, che renderizza di nuovo i figli, qualunque parametro dichiari; un elemento fallback viene mostrato così com’è. Un errore va al boundary più vicino sopra di esso, e uno in un fallback va al boundary sopra quello. I componenti Rust usano catch_error (Error boundary).

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

Il design token name del tema dell’app ("theme" in nsh.json, sopra i token di shadcn/ui) nell’aspetto mostrato: un colore come #rrggbbaa, una lunghezza come numero di punti, un font come nome della sua famiglia. I nomi sono le variabili CSS del tema senza -- (primary, muted-foreground, radius, font-mono, e quelli propri dell’app, come up). La lettura è reattiva: un componente, memo o effect che legge un token viene eseguito di nuovo quando cambiano il tema o l’aspetto. Tokens elenca i token dell’app con i loro tipi; NSH lo scrive in .nsh/types/nsh/tokens.d.ts a partire dal tema. Per le classi, indica direttamente i token (bg-primary, rounded-(--radius)): Token del tema.

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;

Gli elementi host esportati da nsh, scritti come tag: <View>, <Text>, <Scroll>, <Overlay> (i suoi figli sopra la finestra, posizionati rispetto a un’ancora: Overlay). Il compilatore crea la vista nativa sul posto per un tag che ne nomina uno tramite il proprio import (anche con un alias), quindi importarli non costa nulla a run time. Sono componenti come tutti gli altri, quindi possono anche essere passati in giro (const Tag = inline ? Text : View). nsh esporta allo stesso modo le altre primitive: List, Image, Canvas, WebView e Video, ciascuna con la propria pagina di riferimento. Le loro props sono documentate in Elementi. L’input di testo, Input, proviene da nsh/base.

#Area sicura e tastiera

Le variabili d’ambiente di CSS mantengono il contenuto libero dalla UI di sistema, nel padding e nel margin di qualsiasi vista (padding, paddingTop, …, le stesse chiavi di margin; i valori arbitrari p* / m* di Tailwind; i metodi di Styled .p_safe_area(), .pt_safe_area_plus(..), .pb_keyboard(), … in Rust). I loro valori sono EnvValue: env(name), env(name, <length>), calc(env(name) + <length>) e calc(<length> + env(name)).

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

#safeArea e safeAreaInsets

safeArea() è l’area sicura della superficie (safe_area() in Rust); safeAreaInsets() sono gli inset del punto in cui un componente viene renderizzato (cx.insets() in Rust), i valori delle variabili safe-area-inset-*. Entrambi sono Edges reattivi ({ top, right, bottom, left } in punti). Consulta safeArea e safeAreaInsets.

#Keyboard e keyboardFrame

Keyboard.dismiss() nasconde la tastiera software (dismiss_keyboard() in Rust) e keyboardFrame() indica quanta parte dello schermo copre (keyboard_height() e keyboard_duration() in Rust). Consulta Nascondere la tastiera e L’altezza della tastiera.

#Viste selezionabili

<View selectable> (view().selectable(true) in Rust) fa sì che i testi al suo interno vengano selezionati insieme, come quelli di una pagina web: una sola selezione attraversa viste, elementi Text e TextView, in ordine di lettura. Consulta Selezione del testo.

#Animazione

L’API di animazione anima sul thread della UI. Crei un valore animato, lo leghi (o leghi valori derivati da esso) a una proprietà di stile e avvii un’animazione; da quel momento ogni frame viene calcolato nativamente, senza eseguire il codice dell’app. Un engine o un thread JS occupato non può far scattare l’animazione, e un’animazione non costa all’app alcun lavoro per frame. Il codice Rust usa animated_value(), motion(), Animation, Spring, Timing, KeyframeTiming, MotionPreset e Easing da nsh_core::prelude e lega i valori con i metodi .bind_* degli elementi; TSX li importa da 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";

Consulta Animazione per la guida.

#Cosa può pilotare un valore animato

Le altre proprietà di stile accettano valori semplici; per animare il layout stesso (dimensioni, posizioni nel flusso), usa LayoutAnimation.

#createAnimatedValue

function createAnimatedValue(value?: number): AnimatedValue;

Crea un valore animato che parte da value (predefinito 0). Rust: animated_value(value), un handle Copy mantenuto dal componente che lo ha creato.

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

Ogni metodo di animazione restituisce una promise che si risolve con { finished }: true quando l’animazione è terminata, false quando è stata interrotta (da stop, set o da un’altra animazione dello stesso valore). In Rust restituisce un AnimationEnd, che un task attende per lo stesso 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";

Un nodo del grafo di animazione nativo: un AnimatedValue, oppure un valore derivato da altri. I nodi derivati vengono valutati sul thread della UI ogni volta che cambiano i loro input.

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) riproduce un valore attraverso i keyframe e si risolve con { finished }, che indica se sono terminati; Animated.keyframes(value, { keyframes, ...options }) equivale a un passo di una composizione. Rust: value.keyframes(frames, KeyframeTiming) e Animation::keyframes(&value, frames, KeyframeTiming), con Keyframe::new(value) (distribuiti uniformemente), Keyframe::at(offset, value) e .ease(easing), e KeyframeTiming::new(ms) con .delay(ms), .easing(e), .iterations(Some(n)), .infinite() e .direction(PlaybackDirection::…).

Vengono riprodotti come i keyframe CSS: un easing modella un segmento (quello di un keyframe è il segmento che parte da esso, quello del timing è ogni altro segmento); gli offset mancanti nei keyframe vengono distribuiti uniformemente, il primo a 0 e l’ultimo a 1; ogni iterazione inizia con un salto al suo primo keyframe, e senza un keyframe a 0 il valore parte da dove si trova; durante un delay il valore mantiene il primo keyframe (CSS animation-fill-mode: backwards); le iterazioni all’indietro eseguono i segmenti al contrario, con le curve invertite; il valore resta dove lo lascia l’ultima iterazione.

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

Crea un motion: un valore animato per ciascun canale di opacità e transform di una view, a riposo (opacità e scale a 1, gli altri a 0), e motion da riprodurre su di essi in modo nativo. Si associa con style={motion.style}, oppure si fa lo spread di motion.style o motion.transform in uno stile; il transform applica prima le traslazioni, poi le rotazioni, poi le scale, con scale inglobato in scaleX e scaleY: 7 degli 8 passi di transform di una view, il che ne lascia uno per il tuo ([{ perspective: 600 }, ...motion.transform] per i flip 3D). initial imposta da dove partono i canali ({ opacity: 0 }; gli altri partono a riposo). Con enter, i canali che muove partono da dove parte quel motion (su initial) e viene riprodotto subito, con le altre opzioni come timing (delay, duration, …). Un motion muove solo opacità e transform: lo spread di motion.style imposta il opacity della view, quindi associa solo motion.transform per mantenere un’opacità tua, e muovi i colori con un valore animato e interpolate. Rust: motion(), un handle Copy conservato dal componente che lo ha creato, associato con .bind_motion(&m); motion().entering(spec) entra.

Quando l’utente chiede meno movimento (reduceMotion()), play, animation e enter arrivano subito dove termina il motion, senza muoversi, a meno che ignoreReduceMotion sia impostato (nelle opzioni o sul 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";
}

I motion predefiniti come dati: motion.play("shake") riproduce motions.shake. MotionName è uno tra fadeIn, fadeInUp, fadeInDown, fadeInLeft, fadeInRight, zoomIn, popIn, bounceIn, slideInUp, slideInDown, flipInX, flipInY (ingresso); fadeOut, fadeOutUp, fadeOutDown, fadeOutLeft, fadeOutRight, zoomOut, popOut, slideOutDown, slideOutUp (uscita); shake, headShake, wiggle, swing, pulse, heartbeat, rubberBand, jello, tada, jump, flash (attenzione); spin, float, breathe, sway, bob, glow (ciclo). Animation descrive ciascuno di essi. Fai lo spread di un preset per modificarlo: motion.play({ ...motions.fadeInUp, duration: 600 }).

Un MotionSpec è un motion tutto tuo: i keyframe di ogni canale ({ opacity: [0, 1], translateY: [24, 0] }), oppure un elenco di frame come li scrive la Web Animations API ([{ opacity: 0, translateY: 24 }, { opacity: 1, translateY: 0 }], un frame senza offset viene collocato in base alla sua posizione nell’elenco), con il timing dei keyframe. Rust: MotionSpec::new(KeyframeTiming) con .values(channel, values) (distribuiti uniformemente), .track(channel, keyframes) e .timing(|t| …); MotionPreset::FadeInUp (o .spec()) è un preset, e MotionChannel nomina i canali.

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 costruisce animazioni a partire da passi (timing, spring, decay, sequence, parallel, …). Nulla viene eseguito finché non si chiama start(); a quel punto l’intero albero viene eseguito in modo nativo, e ogni passo parte sul thread UI nell’istante esatto in cui termina il precedente (nessun intervallo tra i frame, nessun round trip verso il codice dell’app tra un passo e l’altro). Rust costruisce lo stesso albero con 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;
};

Un easing è un dato, non una funzione dell’app: il runtime lo valuta in modo nativo. In Rust è l’enum Easing: Linear, EaseIn, EaseOut, EaseInOut, Bezier(x1, y1, x2, y2), Steps(count, StepPosition) e Curve(curve, mode), con un Curve (Quad, Cubic, Poly(n), Sin, Circle, Exp, Elastic(bounciness), Back(s), Bounce) e un EaseMode (In, Out, InOut). Per disegnarne uno, Easing.sample(easing, count) (Rust: nsh_core::element::sample_easing) restituisce i suoi valori in count punti equidistanti da 0 a 1; Animated.sampleSpring e Animated.sampleDecay (sample_spring, sample_decay) restituiscono i valori di una spring o di un decay, uno per frame (a fps, 60 per impostazione predefinita) da from (0) fino alla sua fine. Tutti e tre provengono dal codice nativo su cui girano le animazioni. Ovunque in TSX sia accettato un Easing puoi passare un nome ("easeOut"), una Bézier cubica come quattro numeri, o una curva dall’oggetto Easing.

Easing.steps(count, position) è il CSS steps(): il valore salta tra count livelli invece di muoversi (uno sprite frame per frame, una lancetta che scatta). position indica dove cadono i salti: "jump-end" (il valore predefinito, anche "end"), "jump-start" ("start"), "jump-none" o "jump-both"; Rust: Easing::Steps(count, StepPosition::JumpEnd), JumpStart, JumpNone, JumpBoth.

Le curve sono nella loro forma “in” (lente all’inizio). Easing.out(curve) ne inverte una, Easing.inOut(curve) la rende simmetrica, Easing.in(curve) la lascia così com’è; in Rust si tratta del EaseMode di 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) anima in modo nativo le modifiche di layout del commit successivo: le view che si spostano o cambiano dimensione scivolano verso i nuovi frame, le nuove view compaiono (con dissolvenza o scala in ingresso, in base a property) e quelle rimosse scompaiono. Chiamalo subito prima del cambio di stato che modifica il layout. Rust: animate_layout(LayoutAnimation), con i preset di nsh_core::element::LayoutAnimation o le sue transizioni create, update e 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

L’API Device informa l’app sul dispositivo e sul suo ambiente. Il codice Rust chiama le funzioni di nsh_core::prelude (window(), dark(), font_scale(), locale(), lifecycle(), os(), idiom(), pixel_ratio(), set_color_scheme(), …); TSX le importa da nsh. La dimensione della finestra, lo schema di colori, la scala del font, il rapporto di pixel, il locale e lo stato dell’app sono reattivi: leggili in un binding (una closure passata a un elemento in Rust, JSX in TSX), computed o effect, e ciò che li legge si aggiorna quando la piattaforma segnala un cambiamento (rotazione, ridimensionamento della finestra, passaggio alla modalità scura, modifica della dimensione del testo o della lingua, spostamento su uno schermo di densità diversa, uscita dall’app e ritorno).

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

Vedi Device e ambiente per la guida.

#windowSize

const windowSize: Accessor<Size>;

La dimensione della superficie in punti: la finestra, oppure l’elemento NshAppView / NshView incorporato. Reattivo. 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">;

L’aspetto mostrato: quello del sistema, a meno che l’app non ne imposti uno proprio (nsh.json "appearance", setColorScheme). Reattivo. Rust: dark() -> bool; i colori del tema (AdaptiveColor) e la variante di stile .dark(…) lo seguono senza bisogno di leggerlo. Anche la variante dark: di Tailwind lo segue (vedi 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>;

La dimensione del testo preferita dall’utente rispetto a quella predefinita (1 è la dimensione predefinita; Dynamic Type su iOS, dimensione del font su Android), oppure la dimensione del testo impostata al suo posto dall’app che incorpora. Reattivo. Rust: font_scale() -> f32. Il testo si adatta già ad essa a meno che allowFontScaling={false}; leggila quando altre dimensioni devono seguirla, come le icone accanto al testo.

#locale

const locale: Accessor<string>;

Il locale dell’utente come tag BCP 47 ("en-US", "zh-Hans-CN"), oppure il locale impostato al suo posto dall’app che incorpora. Reattivo. Rust: locale() -> Locale (locale().as_str() è il tag). Intl formatta per esso in modo predefinito; leggilo per scegliere le stringhe delle tue traduzioni (Device e ambiente).

#lifecycle

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

Indica se l’app è in uso, nei termini di AppState di React Native: "active" in primo piano e in grado di ricevere input, "inactive" mentre è visibile senza il focus (un’altra app o finestra lo ha, oppure il sistema mostra qualcosa sopra di essa, come il selettore delle app o una chiamata in arrivo), "background" mentre non è visibile (in background, ridotta a icona, una scheda del browser nascosta). Un’app mostrata all’interno di un’app nativa segue quella di quest’ultima. Reattivo. Rust: lifecycle() -> Lifecycle (Lifecycle::Active, Inactive, Background).

Leggilo in un effect per mettere in pausa il lavoro che nessuno vede e riprenderlo quando l’app torna:

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;

Mostra l’app in scheme qualunque sia l’aspetto del sistema, subito: colorScheme(), le classi dark:, il tema dei componenti e i controlli della piattaforma (gli alert, lo stile predefinito della status bar) lo seguono; "system" torna a seguire il sistema. nsh.json "appearance" lo imposta fin dall’inizio. 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;
}

La piattaforma su cui gira l’app, costante per tutta l’esecuzione.

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

Restituisce il valore per il sistema operativo corrente (ios, android, web, …), altrimenti desktop o mobile (in base a platform.desktop), altrimenti native (ogni piattaforma tranne il web), altrimenti default, altrimenti undefined. Il codice Rust usa il match su os() (e su is_desktop() per 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>;

Pixel del dispositivo per punto (ad es. 3 sulla maggior parte degli iPhone). Reattivo: cambia quando la finestra si sposta su uno schermo di densità diversa (su Mac Catalyst, sui desktop o su un display esterno) e quando l’impostazione della dimensione dello schermo di Android cambia la densità. Rust: pixel_ratio() -> f32, e round_to_nearest_pixel(points) per una lunghezza in pixel interi del dispositivo; in TSX quella lunghezza è 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;
}

Apre url fuori dall’app: una pagina web nel browser, un link mailto: nell’app di posta, un link tel: nell’app del telefono e qualsiasi schema registrato da un’altra app (maps:, i link lb:// propri di un’app host). Si risolve con { opened }, cioè se qualcosa l’ha aperto: false quando nessuna app gestisce lo schema. Rust: open_url(url) di nsh_core::prelude, una risposta da attendere (await) in un task (o da scartare), lo stesso 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>

• L’URL è assoluto (ha uno schema). Gli URL che eseguirebbero codice o raggiungerebbero i dati dell’app stessa, javascript:, data:, blob:, file:, about: e asset:, rifiutano la promise con un TypeError, così come gli indirizzi relativi. openUrl non lancia mai eccezioni: ogni errore rifiuta la promise.
• Un’app che dichiara capability richiede openUrl: "openUrl": true per ogni schema, oppure "openUrl": { "schemes": ["https", "mailto"] } per quelli elencati; gli altri URL vengono rifiutati con un Error il cui code è "ERR_ACCESS_DENIED", permission "openUrl" e resource l’URL (vedi Sandbox e capability). In Rust, open_url risponde false per questi e registra il motivo nel log.
• L’app che incorpora vede l’URL per prima e può instradarlo invece tramite il proprio router (Swift NshAppView.onOpenURL, Java NshView.setOpenUrlHandler, Rust AppView::host().handle_open_url; vedi iOS e Android). opened è allora true.
• Ogni piattaforma lo apre con il proprio opener: UIApplication.open su iOS (l’application dell’app host quando è incorporata), un intent ACTION_VIEW su Android, NSWorkspace su macOS, ShellExecuteW su Windows, GtkUriLauncher su Linux, open_url di GPUI, una nuova scheda sul web. nsh test registra gli URL invece di aprirli.
• Un TextView apre i suoi link in questo modo con links="open".

#Direzione del layout

La direzione del layout segue la lingua dell’utente: in una lingua da destra a sinistra (arabo, ebraico, …) l’app viene disposta da destra a sinistra, le righe partono da destra e le proprietà di stile left / right (marginLeft, paddingRight, …) significano inizio e fine. Le modifiche si applicano subito, senza riavvio.

Lo stile direction di una view ("ltr", "rtl" o "inherit", il valore predefinito) imposta la direzione del proprio sottoalbero; in Rust, .direction(LayoutDirection::..).

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

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

#Correlati

• Gli inset dell’area sicura (Rust safe_area(); TSX safeArea(), safeAreaInsets()) e la tastiera software (Rust keyboard_height(); TSX keyboardFrame()) sono in Area sicura e tastiera.
• Le impostazioni dello screen reader e della riduzione del movimento sono in Accessibilità.

#PanResponder

I pan responder sono gesture di trascinamento costruite sul sistema dei gesture responder: l’elemento rivendica i tocchi di una gesture, poi li ascolta da solo insieme allo stato della gesture, che traccia per te il centroide dei tocchi, la distanza percorsa e la velocità. Il codice Rust li rivendica con .claim_touches(TouchClaim::…) e li ascolta con listener .on_responder_* il cui ResponderEvent porta un PanGesture, il tutto in nsh_core::prelude; TSX importa PanResponder da nsh, i cui callback onPanResponder… ricevono l’evento di tocco e lo stato della gesture.

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

Crea un pan responder. Applica il suo panHandlers con lo spread sulla view che deve ricevere la gesture. In Rust, la view rivendica i tocchi e ascolta da sé:

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

Ogni callback riceve l’evento di tocco (GestureResponderEvent, da nsh) e lo stato della gesture. In Rust, una rivendicazione decide con .ask(|request: &ClaimRequest| …), chiamando request.claim() per prendere i tocchi (senza ask li prende sempre), e ogni listener riceve un ResponderEvent il cui gesture è lo stato.

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, con i punti come Point<Points>.

#Dentro le scroll view

Mentre un pan responder è il responder, le scroll view native che lo circondano non scorrono (onShouldBlockNativeResponder vale true per impostazione predefinita). Per far coesistere uno swipe orizzontale con lo scorrimento verticale, diventa il responder solo sui movimenti orizzontali:

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

Per un pan che la piattaforma riconosce, TouchClaim::on_pan(PanActivation::horizontal(10.0, 10.0)) decide sul main thread mentre le dita si muovono. Le prop responder sottostanti (onStartShouldSetResponder, onResponderGrant, onTouchStart, …) possono anche essere usate direttamente su qualsiasi elemento; vedi Elementi.

#Clipboard

L’API clipboard legge e scrive gli appunti di sistema: testo ovunque (UIPasteboard su iOS, ClipboardManager su Android, NSPasteboard, GDK e gli appunti Win32 sui desktop, navigator.clipboard sul web), immagini su iOS, sui desktop e sul web, e i file copiati in un file manager sui desktop e su Mac Catalyst. Il codice Rust chiama le funzioni di nsh_core::prelude (set_clipboard, clipboard_string, …); TSX importa Clipboard da 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
}

Le letture Rust restituiscono risposte da attendere (await) in un task (spawn, o una funzione di modulo async); ClipboardImage è nsh_core::element::ClipboardImage, con url e size (un Size<DevicePixels>).

Le immagini passano dagli appunti su iOS, sui desktop e sul web. Su Android gli appunti trasportano testo: writeImage e readImage vengono rifiutate con un Error il cui code è "ERR_FEATURE_UNAVAILABLE_ON_PLATFORM", e hasImage si risolve con false. In Rust, set_clipboard_image lascia gli appunti com’erano e clipboard_image risponde None.

L’utente può anche copiare da un testo selezionabile per conto proprio; l’API clipboard serve per copiare dal codice, ad esempio con un pulsante Copia.

#Clipboard.writeText

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

Mette text negli appunti, sostituendo ciò che c’era. 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>;

Si risolve con il testo degli appunti, oppure con "" quando non ne contengono. Rust: clipboard_string(). Su iOS, leggere gli appunti può mostrare l’avviso di incolla del sistema (“App ha incollato da …”), e su Android 10 e successivi solo l’app in primo piano può leggerli. Leggili quando l’utente chiede di incollare, non a ogni schermata.

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

Si risolve indicando se gli appunti contengono testo, senza leggerlo: nessun avviso di incolla su iOS. Rust: clipboard_has_string(). Usalo per decidere se mostrare un pulsante Incolla. Sul web i browser lo sanno solo leggendo, quindi può chiedere il permesso all’utente.

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

Si risolve con l’immagine degli appunti, oppure con null quando non ne contengono: uno screenshot incollato, o un’immagine copiata in un browser o in un editor di immagini. Rust: clipboard_image(), None quando non ne contengono. url è un URL dell’immagine (PNG, oppure il JPEG, GIF, WebP o BMP degli appunti) che un Image mostra come src e che fetch legge: fetch(url) ne restituisce i byte, per un upload. size (width e height) è la sua dimensione in pixel, dopo la decodifica. Come per readText, leggila quando l’utente chiede di incollare. Vengono lette immagini fino a 48 MB (codificate), così che l’immagine stia nella memoria dell’app; una più grande viene rifiutata con un Error il cui code è "ERR_NSH_QUOTA_EXCEEDED" (il suo messaggio indica la dimensione dell’immagine e il limite), mentre hasImage si risolve con true. Rust: clipboard_image() risponde None in questo caso.

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

Un’app in stile chat in cui gli utenti incollano screenshot in un composer associa la scorciatoia di incolla mentre il suo input ha il focus e prende l’immagine quando ce n’è una:

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

Si risolve indicando se gli appunti contengono un’immagine, senza leggerla: nessun avviso di incolla su iOS. Rust: clipboard_has_image(). Su Android si risolve con false.

#Clipboard.writeImage

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

Mette negli appunti l’immagine di src, un URL data: in base64 o il url restituito da readImage, sostituendo ciò che contengono. Rust: set_clipboard_image(src). Su Windows accetta un PNG, il formato che leggono i browser, Office e lo Strumento di cattura. Su Android viene rifiutata con "ERR_FEATURE_UNAVAILABLE_ON_PLATFORM".

set_clipboard_image(image.url.clone());

await Clipboard.writeImage(image.url);

#Clipboard.readFiles

readFiles(): Promise<string[]>;

Si risolve con gli URL file: dei file e delle cartelle copiati in un file manager (Finder, Explorer, Files), nel loro ordine, oppure con []: gli stessi URL che fornisce un file drop. Rust: clipboard_files(). Analizza un URL per ottenerne il percorso.

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

L’API picker mostra il selettore di sistema per le foto e consegna all’app le immagini scelte dall’utente: il Photos picker su iOS (PHPickerViewController), il Photo Picker su Android, un pannello di apertura o una finestra di dialogo file sui desktop e un file input in un browser. Su iOS e Android il selettore viene eseguito fuori dall’app e consegna solo ciò che l’utente sceglie, quindi non richiede alcun permesso per la libreria foto. Ogni immagine scelta arriva come File (TSX) o PickedFile (Rust) i cui byte restano nativi: mostrala con URL.createObjectURL(file) in un Image, caricala con fetch e FormData. Il codice Rust chiama pick_images di nsh_core::prelude; TSX importa Picker da 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[]>;

Mostra il selettore e si risolve con le immagini scelte dall’utente, nell’ordine di scelta, oppure con [] quando l’utente annulla. Rust: pick_images(request), una risposta da attendere in un task (spawn, o una funzione di modulo async). pickImages non lancia mai eccezioni: le opzioni fuori intervallo (limit: 0, un quality fuori dall’intervallo da 0 a 1) rifiutano la promise con un RangeError, e una selezione che le capability dell’app non consentono la rifiuta con ERR_ACCESS_DENIED (sotto). Un annullamento è una risposta dell’utente, non un fallimento: si risolve con [].

Le immagini arrivano pronte per essere inviate:

• Formati accettati da ogni browser e server. JPEG, PNG, GIF e WebP arrivano così come sono; una foto memorizzata in un altro formato (HEIC su iPhone, HEIF, TIFF) arriva come JPEG. format: "current" mantiene il formato memorizzato.
• Ridimensionate in modo nativo. Con maxDimension, un’immagine il cui lato più lungo supera il valore viene ridimensionata per rientrarvi, in posizione verticale, e codificata di nuovo: un PNG come PNG, qualsiasi altro formato come JPEG con quality. Le foto dei telefoni sono da 12 a 48 megapixel; ridimensionarle a 2048 pixel prima di un upload le riduce a poche centinaia di kilobyte. Anche quality codifica di nuovo i JPEG.
• Ciò che mostra. size è la dimensione in pixel dell’immagine come appare, con l’orientamento della fotocamera applicato. Un’immagine che NSH codifica di nuovo non contiene metadati (nessuna posizione); quella che arriva così com’è mantiene i propri.

Su Windows, Linux e nelle finestre GPUI, la finestra di dialogo offre i formati accettati dalla richiesta (con "compatible": JPEG, PNG, GIF e WebP) e i file arrivano così come sono memorizzati, alla loro dimensione originale.

Un composer di chat allega una foto, la mostra mentre il messaggio viene scritto e la carica quando il messaggio viene inviato:

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