nsh

nsh est le module principal : l’API réactive (signaux, valeurs calculées, effets, contexte), mount, token, les éléments hôtes View, Text, Scroll et Overlay, les vues sélectionnables, la safe area et le clavier, l’animation, l’appareil et son environnement, PanResponder, le presse-papiers, le sélecteur de photos, la reconnaissance vocale, le stockage, le canal hôte, les raccourcis clavier, les composants et modules natifs, l’accessibilité, ainsi que les types TypeScript des éléments, des styles et des événements. Le graphe réactif lui-même s’exécute nativement en Rust ; lire un signal est un appel dans le runtime qui coûte quelques nanosecondes, et seules vos propres closures s’exécutent dans l’interpréteur 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 réactivité de NSH suit le même modèle que SolidJS : une fonction de composant s’exécute une seule fois, et les parties de l’interface qui lisent des signaux sont mises à jour sur place quand ces signaux changent. Il n’y a ni nouveau rendu du composant ni DOM virtuel. Voir Réactivité pour le guide.

#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 contient une valeur. L’appeler lit la valeur et, dans un scope de suivi (expressions JSX, computed, effect), y abonne ce scope. set et update l’écrivent ; tout ce qui l’a lu est mis à jour.

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

Par défaut, une écriture === à la valeur courante ne fait rien. Passez equals: false pour notifier à chaque écriture (utile quand vous modifiez un objet sur place puis réaffectez ce même objet), ou fournissez votre propre comparaison :

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

Une valeur dérivée de signaux. fn s’exécute de nouveau quand un signal qu’elle a lu change ; les lecteurs de la valeur calculée ne sont mis à jour que lorsque son résultat change (selon equals, === par défaut). fn reçoit le résultat précédent.

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

Utilisez computed quand une dérivation est coûteuse ou lue à plusieurs endroits. Pour une expression peu coûteuse, une simple fonction (const full = () => first() + " " + last()) est tout aussi réactive.

#effect

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

Exécute fn après le rendu, puis à nouveau chaque fois qu’un signal qu’il a lu change. Utilisez les effets pour les effets de bord : journalisation, minuteurs, communication avec les modules natifs. Un effet appartient au composant (ou à l’effet) dans lequel il a été créé et est libéré avec lui.

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

Pour annuler quelque chose avant que l’effet ne s’exécute de nouveau (ou quand son composant disparaît), appelez cleanup à l’intérieur.

#batch

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

Exécute fn et applique toutes ses écritures ensemble à la fin, de sorte que les lecteurs sont mis à jour une seule fois au lieu d’une fois par écriture. Renvoie ce que renvoie fn.

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

#untracked

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

Exécute fn sans abonner le scope courant à ce qu’elle lit. Utilisez-le pour lire un signal dans un effet ou une expression JSX sans en dépendre.

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

#cleanup

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

Enregistre fn pour qu’elle s’exécute avant que l’effet courant ne s’exécute de nouveau, ou quand le composant ou l’effet courant disparaît.

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

Une valeur qu’un composant fournit à tout ce qu’il affiche, quelle que soit la profondeur. Appeler le contexte (Theme()) lit la valeur du fournisseur le plus proche, ou defaultValue s’il n’y en a pas.

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;

Affiche app dans la surface (la fenêtre, ou le NshAppView / NshView dans lequel l’application est intégrée) et renvoie une fonction qui le retire. Le fichier d’entrée de chaque application se termine par 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]>];

Sépare un objet de props en les props nommées dans keys et le reste. Les deux moitiés restent réactives : les props dont la valeur change sont des getters, et split les conserve comme getters. Utilisez-le dans un composant qui gère certaines props lui-même et transmet les autres. Déstructurer les props (const { label } = props) les lirait une seule fois et perdrait les mises à jour.

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;

Affiche ses enfants, ou fallback dès que quelque chose en dessous lève une erreur : le corps d’un composant, une liaison, un effet ou un gestionnaire d’événement. La partie qui a échoué est retirée et le fallback s’affiche à sa place. Une fonction fallback est appelée comme fallback(error, reset) avec la valeur levée et reset, qui affiche à nouveau les enfants, quels que soient les paramètres qu’elle déclare ; un élément fallback est affiché tel quel. Une erreur remonte à la boundary la plus proche au-dessus, et une erreur dans un fallback à la boundary située encore au-dessus. Les composants Rust utilisent catch_error (Error boundaries).

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

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

#token

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

Le design token name du thème de l’application ("theme" dans nsh.json, au-dessus des tokens de shadcn/ui) dans l’apparence affichée : une couleur sous forme de #rrggbbaa, une longueur sous forme de nombre de points, une police sous forme du nom de sa famille. Les noms sont les variables CSS du thème sans -- (primary, muted-foreground, radius, font-mono, et ceux propres à l’application, comme up). Sa lecture est réactive : un composant, un memo ou un effet qui lit un token s’exécute de nouveau quand le thème ou l’apparence change. Tokens liste les tokens de l’application avec leurs types ; NSH l’écrit dans .nsh/types/nsh/tokens.d.ts à partir du thème. Pour les classes, nommez directement les tokens (bg-primary, rounded-(--radius)) : Tokens de thème.

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;

Les éléments hôtes qu’exporte nsh, écrits comme des balises : <View>, <Text>, <Scroll>, <Overlay> (ses enfants au-dessus de la fenêtre, placés par rapport à une ancre : Overlay). Le compilateur crée la vue native sur place pour une balise qui en désigne une via son import (y compris sous un alias), si bien qu’importer ces éléments ne coûte rien à l’exécution. Ce sont des composants comme les autres, ils peuvent donc aussi être transmis (const Tag = inline ? Text : View). nsh exporte les autres primitives de la même façon : List, Image, Canvas, WebView et Video, chacune avec sa propre page de référence. Leurs props sont documentées sous Éléments. Le champ de saisie de texte, Input, provient de nsh/base.

#Safe area et clavier

Les variables d’environnement de CSS maintiennent le contenu à l’écart de l’interface système, dans le padding et la marge de n’importe quelle vue (padding, paddingTop, …, les mêmes clés margin ; les valeurs arbitraires p* / m* de Tailwind ; les méthodes Styled .p_safe_area(), .pt_safe_area_plus(..), .pb_keyboard(), … en Rust). Leurs valeurs sont des EnvValue : env(name), env(name, <length>), calc(env(name) + <length>) et calc(<length> + env(name)).

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

#safeArea et safeAreaInsets

safeArea() est la safe area de la surface (safe_area() en Rust) ; safeAreaInsets() les marges à l’endroit où un composant s’affiche (cx.insets() en Rust), c’est-à-dire les valeurs des variables safe-area-inset-*. Les deux sont des Edges réactifs ({ top, right, bottom, left } en points). Voir safeArea et safeAreaInsets.

#Keyboard et keyboardFrame

Keyboard.dismiss() masque le clavier logiciel (dismiss_keyboard() en Rust) et keyboardFrame() indique quelle part de l’écran il recouvre (keyboard_height() et keyboard_duration() en Rust). Voir Masquer le clavier et La hauteur du clavier.

#Vues sélectionnables

<View selectable> (view().selectable(true) en Rust) fait en sorte que les textes qu’il contient se sélectionnent ensemble, comme ceux d’une page web : une seule sélection traverse les vues, les éléments Text et les TextView, dans l’ordre de lecture. Voir Sélection de texte.

#Animation

L’API d’animation anime sur le thread d’interface. Vous créez une valeur animée, vous la liez (ou des valeurs qui en dérivent) à une propriété de style, puis vous lancez une animation ; à partir de là, chaque image est calculée nativement, sans exécuter le code de l’application. Un moteur ou un thread JS occupé ne peut pas faire saccader l’animation, et une animation ne coûte à l’application aucun travail par image. Le code Rust utilise animated_value(), motion(), Animation, Spring, Timing, KeyframeTiming, MotionPreset et Easing de nsh_core::prelude et lie les valeurs avec les méthodes .bind_* des éléments ; TSX les importe depuis 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";

Voir Animation pour le guide.

#Ce qu’une valeur animée peut piloter

Les autres propriétés de style acceptent des valeurs simples ; pour animer la mise en page elle-même (tailles, positions dans le flux), utilisez LayoutAnimation.

#createAnimatedValue

function createAnimatedValue(value?: number): AnimatedValue;

Crée une valeur animée qui démarre à value (par défaut 0). Rust : animated_value(value), un handle Copy conservé par le composant qui l’a créé.

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

Chaque méthode d’animation renvoie une promesse qui se résout avec { finished } : true quand l’animation s’est terminée, false quand elle a été arrêtée (par stop, set ou une autre animation de la même valeur). En Rust, elle renvoie un AnimationEnd, qu’une tâche attend pour obtenir le même 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 nœud du graphe d’animation natif : un AnimatedValue, ou une valeur dérivée d’autres. Les nœuds dérivés sont évalués sur le thread d’interface chaque fois que leurs entrées changent.

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) fait parcourir à une valeur des keyframes et se résout avec { finished }, selon qu’elles sont allées à leur terme ; Animated.keyframes(value, { keyframes, ...options }) est identique à une étape d’une composite. Rust : value.keyframes(frames, KeyframeTiming) et Animation::keyframes(&value, frames, KeyframeTiming), avec Keyframe::new(value) (réparties uniformément), Keyframe::at(offset, value) et .ease(easing), et KeyframeTiming::new(ms) avec .delay(ms), .easing(e), .iterations(Some(n)), .infinite() et .direction(PlaybackDirection::…).

Elles se jouent comme les keyframes CSS : un easing façonne un segment (celui d’une keyframe vaut pour le segment qui part d’elle, celui du timing pour tous les autres) ; les offsets absents des keyframes sont répartis uniformément, le premier à 0 et le dernier à 1 ; chaque itération commence par un saut vers sa première keyframe, et sans keyframe à 0 la valeur part de là où elle se trouve ; pendant un delay la valeur reste sur la première keyframe (CSS animation-fill-mode: backwards) ; les itérations en sens inverse parcourent les segments à rebours, avec leurs courbes inversées ; la valeur reste là où la dernière itération la laisse.

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

Crée un motion : une valeur animée pour chaque canal de l’opacité et de la transformation d’une vue, au repos (opacité et échelles à 1, les autres à 0), ainsi que des motions à jouer dessus nativement. Liez-le avec style={motion.style}, ou étalez motion.style ou motion.transform dans un style ; la transformation applique ses translations, puis ses rotations, puis ses échelles, avec scale intégré à scaleX et scaleY : 7 des 8 étapes de transformation d’une vue, ce qui en laisse une pour les vôtres ([{ perspective: 600 }, ...motion.transform] pour les retournements 3D). initial définit où les canaux démarrent ({ opacity: 0 } ; les autres démarrent au repos). Avec enter, les canaux qu’il anime démarrent là où ce motion démarre (sur initial) et il se joue aussitôt, les autres options servant de timing (delay, duration, …). Un motion n’anime que l’opacité et la transformation : étaler motion.style définit le opacity de la vue, donc ne liez que motion.transform pour garder une opacité à vous, et animez les couleurs avec une valeur animée et interpolate. Rust : motion(), un handle Copy conservé par le composant qui l’a créé, lié avec .bind_motion(&m) ; motion().entering(spec) joue l’entrée.

Lorsque l’utilisateur demande moins de mouvement (reduceMotion()), play, animation et enter arrivent aussitôt là où le motion se termine, sans bouger, sauf si ignoreReduceMotion est défini (sur les options ou sur le 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";
}

Les motions prêts à l’emploi, sous forme de données : motion.play("shake") joue motions.shake. MotionName est l’un de fadeIn, fadeInUp, fadeInDown, fadeInLeft, fadeInRight, zoomIn, popIn, bounceIn, slideInUp, slideInDown, flipInX, flipInY (entrée) ; fadeOut, fadeOutUp, fadeOutDown, fadeOutLeft, fadeOutRight, zoomOut, popOut, slideOutDown, slideOutUp (sortie) ; shake, headShake, wiggle, swing, pulse, heartbeat, rubberBand, jello, tada, jump, flash (attention) ; spin, float, breathe, sway, bob, glow (boucle). Animation décrit chacun d’eux. Étalez un preset pour le modifier : motion.play({ ...motions.fadeInUp, duration: 600 }).

Un MotionSpec est un motion qui vous est propre : les keyframes de chaque canal ({ opacity: [0, 1], translateY: [24, 0] }), ou une liste de frames telle que l’écrit la Web Animations API ([{ opacity: 0, translateY: 24 }, { opacity: 1, translateY: 0 }], une frame sans offset étant placée selon sa position dans la liste), avec le timing des keyframes. Rust : MotionSpec::new(KeyframeTiming) avec .values(channel, values) (réparties uniformément), .track(channel, keyframes) et .timing(|t| …) ; MotionPreset::FadeInUp (ou .spec()) est un preset, et MotionChannel nomme les canaux.

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 construit des animations à partir d’étapes (timing, spring, decay, sequence, parallel, …). Rien ne s’exécute avant start() ; ensuite l’arbre entier s’exécute nativement, et chaque étape démarre sur le thread d’UI à l’instant exact où la précédente se termine (aucun écart d’une frame, aucun aller-retour vers le code de l’app entre les étapes). Rust construit le même arbre avec 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 est une donnée, et non une fonction de l’app : le runtime l’évalue nativement. En Rust, c’est l’enum Easing : Linear, EaseIn, EaseOut, EaseInOut, Bezier(x1, y1, x2, y2), Steps(count, StepPosition) et Curve(curve, mode), avec un Curve (Quad, Cubic, Poly(n), Sin, Circle, Exp, Elastic(bounciness), Back(s), Bounce) et un EaseMode (In, Out, InOut). Pour en tracer un, Easing.sample(easing, count) (Rust : nsh_core::element::sample_easing) donne ses valeurs en count points régulièrement espacés de 0 à 1 ; Animated.sampleSpring et Animated.sampleDecay (sample_spring, sample_decay) donnent les valeurs d’un spring ou d’un decay, une par frame (à fps, 60 par défaut) à partir de from (0) jusqu’à sa fin. Les trois proviennent du code natif qu’exécutent les animations. Partout où un Easing est accepté en TSX, vous pouvez passer un nom ("easeOut"), une courbe de Bézier cubique sous forme de quatre nombres, ou une courbe de l’objet Easing.

Easing.steps(count, position) est le steps() de CSS : la valeur saute entre count niveaux au lieu de se déplacer (un sprite image par image, une aiguille qui tictaque). position indique où tombent les sauts : "jump-end" (par défaut, aussi "end"), "jump-start" ("start"), "jump-none" ou "jump-both" ; Rust : Easing::Steps(count, StepPosition::JumpEnd), JumpStart, JumpNone, JumpBoth.

Les courbes sont sous leur forme « in » (lentes au début). Easing.out(curve) en inverse une, Easing.inOut(curve) la rend symétrique, Easing.in(curve) la conserve telle quelle ; en Rust, c’est le EaseMode de 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) anime nativement les changements de mise en page du prochain commit : les vues qui se déplacent ou se redimensionnent glissent vers leurs nouveaux cadres, les nouvelles vues apparaissent (en fondu ou en zoom avant, selon property) et les vues supprimées disparaissent. Appelez-le juste avant le changement d’état qui modifie la mise en page. Rust : animate_layout(LayoutAnimation), avec les presets de nsh_core::element::LayoutAnimation ou ses transitions create, update et 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 renseigne l’app sur l’appareil et son environnement. Le code Rust appelle les fonctions de nsh_core::prelude (window(), dark(), font_scale(), locale(), lifecycle(), os(), idiom(), pixel_ratio(), set_color_scheme(), …) ; TSX les importe depuis nsh. La taille de la fenêtre, le jeu de couleurs, l’échelle de police, le ratio de pixels, la locale et l’état de l’app sont réactifs : lisez-les dans une liaison (une closure passée à un élément en Rust, du JSX en TSX), computed ou effect, et ce qui les lit se met à jour lorsque la plateforme signale un changement (rotation, redimensionnement de la fenêtre, passage en mode sombre, changement de la taille du texte ou de la langue, passage à un écran d’une autre densité, sortie de l’app puis retour).

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

Voir Appareil et environnement pour le guide.

#windowSize

const windowSize: Accessor<Size>;

La taille de la surface en points : la fenêtre, ou le NshAppView / NshView intégré. Réactif. 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’apparence affichée : celle du système, sauf si l’app a défini la sienne (nsh.json "appearance", setColorScheme). Réactif. Rust : dark() -> bool ; les couleurs du thème (AdaptiveColor) et la variante de style .dark(…) la suivent sans la lire. La variante dark: de Tailwind la suit aussi (voir 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 taille de texte préférée de l’utilisateur par rapport à celle par défaut (1 est la taille par défaut ; Dynamic Type sur iOS, taille de police sur Android), ou la taille de texte que définit à la place l’app hôte. Réactif. Rust : font_scale() -> f32. Le texte s’y adapte déjà sauf si allowFontScaling={false} ; lisez-la lorsque d’autres tailles doivent suivre, comme des icônes à côté du texte.

#locale

const locale: Accessor<string>;

La locale de l’utilisateur sous forme de balise BCP 47 ("en-US", "zh-Hans-CN"), ou la locale que définit à la place l’app hôte. Réactif. Rust : locale() -> Locale (locale().as_str() est la balise). Intl formate selon elle par défaut ; lisez-la pour choisir les chaînes de vos propres traductions (Appareil et environnement).

#lifecycle

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

Indique si l’app est utilisée, dans les termes de AppState de React Native : "active" au premier plan et recevant les entrées, "inactive" lorsqu’elle est visible sans le focus (une autre app ou fenêtre l’a, ou le système affiche quelque chose par-dessus, comme le sélecteur d’apps ou un appel entrant), "background" lorsqu’elle n’est pas visible (en arrière-plan, réduite, un onglet de navigateur masqué). Une app affichée dans une app native suit l’état de cette dernière. Réactif. Rust : lifecycle() -> Lifecycle (Lifecycle::Active, Inactive, Background).

Lisez-le dans un effet pour mettre en pause le travail que personne ne voit et le reprendre au retour de l’app :

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;

Affiche aussitôt l’app en scheme quelle que soit l’apparence du système : colorScheme(), les classes dark:, le thème des composants et les contrôles de la plateforme (alertes, style par défaut de la barre d’état) la suivent ; "system" suit de nouveau le système. nsh.json "appearance" la définit dès le départ. 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 plateforme sur laquelle l’app s’exécute, constante pendant son exécution.

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

Renvoie la valeur pour l’OS courant (ios, android, web, …), sinon desktop ou mobile (selon platform.desktop), sinon native (toutes les plateformes sauf le web), sinon default, sinon undefined. Le code Rust utilise un match sur os() (et is_desktop() pour 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>;

Pixels de l’appareil par point (par ex. 3 sur la plupart des iPhone). Réactif : il change quand la fenêtre passe sur un écran d’une autre densité (sur Mac Catalyst, les bureaux, ou un écran externe) et quand le réglage de taille d’affichage d’Android change la densité. Rust : pixel_ratio() -> f32, et round_to_nearest_pixel(points) pour une longueur en pixels entiers de l’appareil ; en TSX, cette longueur est 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;
}

Ouvre url en dehors de l’app : une page web dans le navigateur, un lien mailto: dans l’app de messagerie, un lien tel: dans l’app téléphone, et tout schéma qu’une autre app a enregistré (maps:, les liens lb:// propres à une app hôte). Elle se résout avec { opened }, selon qu’une app l’a ouvert ou non : false quand aucune app ne gère le schéma. Rust : open_url(url) de nsh_core::prelude, une réponse à attendre dans une tâche (ou à abandonner), le même 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 est absolue (elle a un schéma). Les URL qui exécuteraient du code ou atteindraient les données propres de l’app, javascript:, data:, blob:, file:, about: et asset:, rejettent la promesse avec une TypeError, de même que les adresses relatives. openUrl ne lève jamais d’exception : tout échec rejette la promesse.
• Une app qui déclare des capabilities a besoin de openUrl : "openUrl": true pour tous les schémas, ou "openUrl": { "schemes": ["https", "mailto"] } pour ceux listés ; les autres URL rejettent avec une Error dont code vaut "ERR_ACCESS_DENIED", permission "openUrl" et resource l’URL (voir Sandbox et capabilities). En Rust, open_url répond false dans ces cas et journalise la raison.
• L’app hôte qui embarque voit l’URL en premier et peut la router à la place via son propre routeur (Swift NshAppView.onOpenURL, Java NshView.setOpenUrlHandler, Rust AppView::host().handle_open_url ; voir iOS et Android). opened vaut alors true.
• Chaque plateforme l’ouvre avec son propre ouvreur : UIApplication.open sur iOS (l’application de l’app hôte lorsqu’elle est embarquée), une intention ACTION_VIEW sur Android, NSWorkspace sur macOS, ShellExecuteW sur Windows, GtkUriLauncher sur Linux, open_url de GPUI, un nouvel onglet sur le web. nsh test enregistre les URL au lieu de les ouvrir.
• Un TextView ouvre ses liens de cette façon avec links="open".

#Direction de mise en page

La direction de mise en page suit la langue de l’utilisateur : dans une langue s’écrivant de droite à gauche (arabe, hébreu, …), l’app se met en page de droite à gauche, les lignes partent de la droite, et les propriétés de style left / right (marginLeft, paddingRight, …) désignent le début et la fin. Les changements s’appliquent immédiatement, sans redémarrage.

Le style direction d’une vue ("ltr", "rtl" ou "inherit", la valeur par défaut) définit la direction de son propre sous-arbre ; en 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>

#Voir aussi

• Les safe area insets (Rust safe_area() ; TSX safeArea(), safeAreaInsets()) et le clavier logiciel (Rust keyboard_height() ; TSX keyboardFrame()) sont décrits dans Safe area et clavier.
• Les réglages de lecteur d’écran et de réduction des animations sont décrits dans Accessibilité.

#PanResponder

Les pan responders sont des gestes de glissement construits sur le système de gesture responder : l’élément revendique les touches d’un geste, puis les entend seul avec l’état du geste, qui suit pour vous le centroïde des touches, la distance parcourue et la vitesse. Le code Rust les revendique avec .claim_touches(TouchClaim::…) et les entend avec des listeners .on_responder_* dont ResponderEvent porte un PanGesture, le tout dans nsh_core::prelude ; TSX importe PanResponder depuis nsh, dont les callbacks onPanResponder… reçoivent l’événement tactile et l’état du geste.

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

Crée un pan responder. Propagez son panHandlers sur la vue qui doit recevoir le geste. En Rust, la vue revendique les touches et écoute elle-même :

use nsh_core::prelude::*;

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

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

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

mount(App);

#Callbacks

Chaque callback reçoit l’événement tactile (GestureResponderEvent, de nsh) et l’état du geste. En Rust, une revendication décide avec .ask(|request: &ClaimRequest| …), en appelant request.claim() pour prendre les touches (sans ask, elle les prend toujours), et chaque listener reçoit un ResponderEvent dont gesture est l’état.

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, avec des points sous forme de Point<Points>.

#Dans les scroll views

Tant qu’un pan responder est le responder, les scroll views natives qui l’entourent ne défilent pas (onShouldBlockNativeResponder vaut par défaut true). Pour faire coexister un balayage horizontal avec un défilement vertical, ne devenez le responder que lors des déplacements horizontaux :

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

Pour un glissement que la plateforme reconnaît, TouchClaim::on_pan(PanActivation::horizontal(10.0, 10.0)) décide sur le thread principal pendant que les doigts bougent. Les props de responder sous-jacentes (onStartShouldSetResponder, onResponderGrant, onTouchStart, …) peuvent aussi être utilisées directement sur n’importe quel élément ; voir Éléments.

#Clipboard

L’API Clipboard lit et écrit le presse-papiers du système : du texte partout (UIPasteboard sur iOS, ClipboardManager sur Android, NSPasteboard, GDK et le presse-papiers Win32 sur les bureaux, navigator.clipboard sur le web), des images sur iOS, les bureaux et le web, et les fichiers copiés dans un gestionnaire de fichiers sur les bureaux et Mac Catalyst. Le code Rust appelle les fonctions de nsh_core::prelude (set_clipboard, clipboard_string, …) ; TSX importe Clipboard depuis 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
}

Les lectures Rust renvoient des réponses à attendre dans une tâche (spawn, ou une fonction de module async) ; ClipboardImage est nsh_core::element::ClipboardImage, avec url et size (un Size<DevicePixels>).

Les images passent par le presse-papiers sur iOS, les bureaux et le web. Sur Android, le presse-papiers transporte du texte : writeImage et readImage rejettent avec une Error dont code vaut "ERR_FEATURE_UNAVAILABLE_ON_PLATFORM", et hasImage se résout avec false. En Rust, set_clipboard_image laisse le presse-papiers en l’état sur cette plateforme et clipboard_image répond None.

L’utilisateur peut aussi copier lui-même depuis un texte sélectionnable ; l’API Clipboard sert à copier depuis le code, par exemple pour un bouton Copier.

#Clipboard.writeText

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

Place text dans le presse-papiers, en remplaçant son contenu. 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>;

Se résout avec le texte du presse-papiers, ou "" s’il n’en contient pas. Rust : clipboard_string(). Sur iOS, la lecture du presse-papiers peut afficher l’avis de collage du système (« L’app a collé depuis … »), et sur Android 10 et versions ultérieures, seule l’app au premier plan peut le lire. Lisez-le quand l’utilisateur demande de coller, pas à chaque écran.

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

Se résout avec un booléen indiquant si le presse-papiers contient du texte, sans le lire : pas d’avis de collage sur iOS. Rust : clipboard_has_string(). Utilisez-le pour décider d’afficher ou non un bouton Coller. Sur le web, les navigateurs ne le savent qu’en lisant, ce qui peut donc demander une autorisation à l’utilisateur.

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

Se résout avec l’image du presse-papiers, ou null s’il n’en contient pas : une capture d’écran collée, ou une image copiée dans un navigateur ou un éditeur d’images. Rust : clipboard_image(), None s’il n’en contient pas. url est une URL de l’image (PNG, ou le JPEG, GIF, WebP ou BMP propre au presse-papiers) qu’une Image affiche comme son src et que fetch lit : fetch(url) donne ses octets, pour un envoi. size (width et height) est sa taille en pixels, une fois décodée. Comme pour readText, lisez-le quand l’utilisateur demande de coller. Les images jusqu’à 48 Mo (encodées) sont lues, afin que l’image tienne dans la mémoire de l’app ; une image plus grande rejette avec une Error dont code vaut "ERR_NSH_QUOTA_EXCEEDED" (son message indique la taille de l’image et la limite), tandis que hasImage se résout avec true. Rust : clipboard_image() répond None dans ce cas.

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

Une app de type messagerie où les utilisateurs collent des captures d’écran dans une zone de saisie lie le raccourci de collage tant que son champ a le focus et prend l’image s’il y en a une :

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

Se résout avec un booléen indiquant si le presse-papiers contient une image, sans la lire : pas d’avis de collage sur iOS. Rust : clipboard_has_image(). Sur Android, elle se résout avec false.

#Clipboard.writeImage

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

Place dans le presse-papiers l’image de src, une URL data: en base64 ou le url que readImage a donné, en remplaçant son contenu. Rust : set_clipboard_image(src). Sous Windows, elle accepte un PNG, le format que lisent les navigateurs, Office et l’Outil Capture d’écran. Sur Android, elle rejette avec "ERR_FEATURE_UNAVAILABLE_ON_PLATFORM".

set_clipboard_image(image.url.clone());

await Clipboard.writeImage(image.url);

#Clipboard.readFiles

readFiles(): Promise<string[]>;

Se résout avec les URL file: des fichiers et dossiers copiés dans un gestionnaire de fichiers (Finder, Explorer, Files), dans leur ordre, ou [] : ce sont les mêmes URL que fournit un dépôt de fichiers. Rust : clipboard_files(). Analysez une URL pour obtenir son chemin.

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 affiche le sélecteur de photos du système et remet à l’app les images que l’utilisateur choisit : le sélecteur Photos sur iOS (PHPickerViewController), le Photo Picker sur Android, un panneau d’ouverture ou une boîte de dialogue de fichiers sur les ordinateurs de bureau et un champ de fichier (file input) dans un navigateur. Sur iOS et Android, le sélecteur s’exécute en dehors de l’app et ne transmet que ce que l’utilisateur choisit ; il ne requiert donc aucune autorisation d’accès à la photothèque. Chaque image choisie arrive sous la forme d’un File (TSX) ou d’un PickedFile (Rust) dont les octets restent natifs : affichez-la avec URL.createObjectURL(file) dans un Image, envoyez-la avec fetch et FormData. Le code Rust appelle pick_images de nsh_core::prelude ; TSX importe Picker depuis 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[]>;

Affiche le sélecteur et se résout avec les images choisies par l’utilisateur, dans l’ordre du choix, ou avec [] lorsque l’utilisateur annule. Rust : pick_images(request), une réponse à attendre dans une tâche (spawn, ou une fonction de module async). pickImages ne lève jamais d’exception : des options hors limites (limit: 0, un quality hors de 0 à 1) rejettent la promesse avec une RangeError, et un choix que les capacités de l’app n’autorisent pas la rejette avec ERR_ACCESS_DENIED (ci-dessous). Une annulation est une réponse de l’utilisateur, pas un échec : la promesse se résout avec [].

Les images arrivent prêtes à être envoyées :

• Des formats que tous les navigateurs et serveurs acceptent. JPEG, PNG, GIF et WebP arrivent tels quels ; une photo stockée dans un autre format (HEIC sur iPhone, HEIF, TIFF) arrive en JPEG. format: "current" conserve le format stocké.
• Réduites nativement. Avec maxDimension, une image dont le grand côté est plus long est réduite pour tenir dans cette limite, redressée, puis réencodée : un PNG en PNG, tout le reste en JPEG de quality. Les photos de téléphone font de 12 à 48 mégapixels ; les réduire à 2048 pixels avant un envoi les ramène à quelques centaines de kilo-octets. Un quality réencode aussi les JPEG.
• Ce qu’elle affiche. size est la taille de l’image en pixels telle qu’elle s’affiche, son orientation d’appareil photo appliquée. Une image que NSH réencode ne porte aucune métadonnée (pas de localisation) ; une image qui arrive telle quelle conserve les siennes.

Sous Windows, sous Linux et dans les fenêtres GPUI, la boîte de dialogue propose les formats que la requête accepte (avec "compatible" : JPEG, PNG, GIF et WebP) et les fichiers arrivent tels qu’ils sont stockés, à leur taille d’origine.

Un champ de saisie de messagerie joint une photo, l’affiche pendant la rédaction du message et l’envoie lorsque le message part :

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