nsh

nsh es el módulo principal: la API reactiva (signals, valores computed, effects, context), mount, token, los elementos host View, Text, Scroll y Overlay, las vistas seleccionables, el área segura y el teclado, la animación, el dispositivo y su entorno, PanResponder, el portapapeles, el selector de fotos, el reconocimiento de voz, el almacenamiento, el canal del host, los atajos de teclado, los componentes y módulos nativos, la accesibilidad y los tipos de TypeScript de elementos, estilos y eventos. El grafo reactivo se ejecuta de forma nativa en Rust; leer un signal es una llamada al runtime que cuesta unos pocos nanosegundos, y solo tus propias closures se ejecutan en el intérprete de 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 reactividad de NSH sigue el mismo modelo que SolidJS: una función de componente se ejecuta una sola vez, y las partes de la UI que leen signals se actualizan en su sitio cuando esos signals cambian. No hay un nuevo renderizado del componente ni DOM virtual. Consulta Reactividad para ver la guía.

#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 guarda un valor. Llamarlo lee el valor y, dentro de un ámbito de seguimiento (expresiones JSX, computed, effect), suscribe ese ámbito al signal. set y update lo escriben; todo lo que lo leyó se actualiza.

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

Por defecto, una escritura que sea === al valor actual no hace nada. Pasa equals: false para notificar en cada escritura (útil cuando modificas un objeto en su sitio y vuelves a asignar el mismo objeto), o tu propia comparación:

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 valor derivado de signals. fn se ejecuta de nuevo cuando cambia un signal que leyó; los lectores del valor computed solo se actualizan cuando cambia su resultado (según equals, === por defecto). fn recibe el resultado anterior.

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

Usa computed cuando una derivación sea costosa o se lea en varios lugares. Para una expresión barata, una función simple (const full = () => first() + " " + last()) es igual de reactiva.

#effect

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

Ejecuta fn después del renderizado, y de nuevo cada vez que cambia un signal que leyó. Usa los effects para efectos secundarios: logging, temporizadores, comunicación con módulos nativos. Un effect pertenece al componente (o effect) en el que se creó y se elimina junto con él.

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

Para deshacer algo antes de que el effect se ejecute de nuevo (o cuando su componente desaparece), llama a cleanup dentro de él.

#batch

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

Ejecuta fn y aplica todas sus escrituras juntas al final, de modo que los lectores se actualizan una vez en lugar de una vez por escritura. Devuelve lo que devuelve fn.

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

#untracked

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

Ejecuta fn sin suscribir el ámbito actual a lo que lee. Úsalo para leer un signal dentro de un effect o de una expresión JSX sin depender de él.

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

#cleanup

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

Registra fn para que se ejecute antes de que el effect actual se ejecute de nuevo, o cuando el componente o effect actual desaparece.

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 valor que un componente proporciona a todo lo que renderiza, sin importar la profundidad. Llamar al context (Theme()) lee el valor del proveedor más cercano, o defaultValue si no hay ninguno.

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;

Renderiza app en la superficie (la ventana, o el NshAppView / NshView en el que está incrustada la app) y devuelve una función que lo elimina. El archivo de entrada de toda 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 objeto de props en las props nombradas en keys y el resto. Ambas mitades siguen siendo reactivas: las props cuyos valores cambian son getters, y split las mantiene como getters. Úsalo en un componente que gestiona algunas props por sí mismo y pasa las demás. Desestructurar las props (const { label } = props) las leería una sola vez y perdería las actualizaciones.

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;

Renderiza sus hijos, o fallback cuando algo debajo de ellos lanza un error: el cuerpo de un componente, un binding, un effect o un manejador de eventos. La parte que falló se elimina y el fallback se muestra en su lugar. Una función fallback se llama como fallback(error, reset) con el valor lanzado y reset, que vuelve a renderizar los hijos, sea cual sea el número de parámetros que declare; un elemento fallback se muestra tal cual. Un fallo va al boundary más cercano por encima, y uno en un fallback va al boundary que está por encima de este. Los componentes de Rust usan 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];

El design token name del tema de la app ("theme" en nsh.json, sobre los tokens de shadcn/ui) en la apariencia mostrada: un color como #rrggbbaa, una longitud como un número de puntos, una fuente como el nombre de su familia. Los nombres son las variables CSS del tema sin -- (primary, muted-foreground, radius, font-mono, y los propios de la app, como up). Leerlo es reactivo: un componente, memo o effect que lee un token se ejecuta de nuevo cuando cambia el tema o la apariencia. Tokens lista los tokens de la app con sus tipos; NSH lo escribe en .nsh/types/nsh/tokens.d.ts a partir del tema. Para las clases, nombra los tokens directamente (bg-primary, rounded-(--radius)): Tokens 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;

Los elementos host que exporta nsh, escritos como etiquetas: <View>, <Text>, <Scroll>, <Overlay> (sus hijos encima de la ventana, colocados respecto a un ancla: Overlay). El compilador crea la vista nativa en su sitio para una etiqueta que nombra a uno de ellos mediante su import (también con alias), de modo que importarlos no cuesta nada en tiempo de ejecución. Son componentes como cualquier otro, así que también se pueden pasar como valores (const Tag = inline ? Text : View). nsh exporta las demás primitivas del mismo modo: List, Image, Canvas, WebView y Video, cada una con su propia página de referencia. Sus props están documentadas en Elementos. El campo de entrada de texto, Input, proviene de nsh/base.

#Área segura y teclado

Las variables de entorno de CSS mantienen el contenido despejado de la UI del sistema, en el padding y el margin de cualquier vista (padding, paddingTop, …, las mismas claves de margin; los valores arbitrarios p* / m* de Tailwind; los métodos Styled .p_safe_area(), .pt_safe_area_plus(..), .pb_keyboard(), … en Rust). Sus valores son EnvValues: env(name), env(name, <length>), calc(env(name) + <length>) y calc(<length> + env(name)).

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

#safeArea and safeAreaInsets

safeArea() es el área segura de la superficie (safe_area() en Rust); safeAreaInsets() son los insets del lugar donde se renderiza un componente (cx.insets() en Rust), los valores de las variables safe-area-inset-*. Ambos son Edges reactivos ({ top, right, bottom, left } en puntos). Consulta safeArea y safeAreaInsets.

#Keyboard and keyboardFrame

Keyboard.dismiss() oculta el teclado de software (dismiss_keyboard() en Rust) y keyboardFrame() te dice cuánto de la pantalla cubre (keyboard_height() y keyboard_duration() en Rust). Consulta Ocultar el teclado y La altura del teclado.

#Vistas seleccionables

<View selectable> (view().selectable(true) en Rust) hace que los textos que contiene se seleccionen juntos, como los de una página web: una sola selección recorre vistas, elementos Text y TextViews, en orden de lectura. Consulta Selección de texto.

#Animación

La API de animación anima en el hilo de la UI. Creas un valor animado, lo enlazas (o enlazas valores derivados de él) a una propiedad de estilo e inicias una animación; a partir de ahí cada fotograma se calcula de forma nativa, sin ejecutar el código de la app. Un motor o un hilo de JS ocupado no puede hacer que la animación se entrecorte, y una animación no le cuesta a la app trabajo por fotograma. El código Rust usa animated_value(), motion(), Animation, Spring, Timing, KeyframeTiming, MotionPreset y Easing de nsh_core::prelude y enlaza valores con los métodos .bind_* de los elementos; TSX los importa de 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 Animación para ver la guía.

#Qué puede controlar un valor animado

Las demás propiedades de estilo aceptan valores simples; para animar el propio layout (tamaños, posiciones en el flujo), usa LayoutAnimation.

#createAnimatedValue

function createAnimatedValue(value?: number): AnimatedValue;

Crea un valor animado que empieza en value (por defecto 0). Rust: animated_value(value), un handle Copy que conserva el componente que lo creó.

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

Cada método de animación devuelve una promesa que se resuelve con { finished }: true cuando la animación terminó, false cuando se detuvo (por stop, set u otra animación del mismo valor). En Rust devuelve un AnimationEnd, que una task espera para obtener el mismo 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 de animación nativo: un AnimatedValue, o un valor derivado de otros. Los nodos derivados se evalúan en el hilo de la UI cada vez que cambian sus entradas.

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) reproduce un valor a través de keyframes y se resuelve con { finished }, que indica si terminaron; Animated.keyframes(value, { keyframes, ...options }) equivale a un paso de una composición. Rust: value.keyframes(frames, KeyframeTiming) y Animation::keyframes(&value, frames, KeyframeTiming), con Keyframe::new(value) (repartidos uniformemente), Keyframe::at(offset, value) y .ease(easing), y KeyframeTiming::new(ms) con .delay(ms), .easing(e), .iterations(Some(n)), .infinite() y .direction(PlaybackDirection::…).

Se reproducen igual que los keyframes de CSS: un easing da forma a un segmento (el de un keyframe es el segmento que empieza en él; el del timing, todos los demás); los offsets que faltan en los keyframes se reparten uniformemente, el primero en 0 y el último en 1; cada iteración empieza con un salto a su primer keyframe, y sin un keyframe en 0 el valor parte de donde está; durante un delay el valor mantiene el primer keyframe (CSS animation-fill-mode: backwards); las iteraciones hacia atrás recorren los segmentos al revés con sus curvas invertidas; el valor se queda donde lo deja la última iteración.

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 valor animado para cada canal de la opacidad y la transformación de una vista, en reposo (opacidad y escalas a 1, los demás a 0), y motions para reproducir sobre ellos de forma nativa. Enlázalo con style={motion.style}, o expande motion.style o motion.transform en un estilo; la transformación aplica sus traslaciones, luego sus rotaciones y después sus escalas, con scale integrado en scaleX y scaleY: 7 de los 8 pasos de transformación de una vista, lo que deja uno para el tuyo ([{ perspective: 600 }, ...motion.transform] para giros 3D). initial establece dónde empiezan los canales ({ opacity: 0 }; los demás empiezan en reposo). Con enter, los canales que mueve empiezan donde empieza ese motion (durante initial) y se reproduce de inmediato, con las demás opciones como su timing (delay, duration, …). Un motion solo mueve la opacidad y la transformación: expandir motion.style establece el opacity de la vista, así que enlaza solo motion.transform para conservar una opacidad propia, y mueve los colores con un valor animado y interpolate. Rust: motion(), un handle Copy que conserva el componente que lo creó, enlazado con .bind_motion(&m); motion().entering(spec) entra.

Cuando el usuario pide menos movimiento (reduceMotion()), play, animation y enter llegan de inmediato a donde termina el motion, sin moverse, salvo que ignoreReduceMotion esté activado (en las opciones o en el 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";
}

Los motions prediseñados como datos: motion.play("shake") reproduce motions.shake. MotionName es uno de fadeIn, fadeInUp, fadeInDown, fadeInLeft, fadeInRight, zoomIn, popIn, bounceIn, slideInUp, slideInDown, flipInX, flipInY (entrada); fadeOut, fadeOutUp, fadeOutDown, fadeOutLeft, fadeOutRight, zoomOut, popOut, slideOutDown, slideOutUp (salida); shake, headShake, wiggle, swing, pulse, heartbeat, rubberBand, jello, tada, jump, flash (atención); spin, float, breathe, sway, bob, glow (bucle). Animation describe cada uno. Expande un preset para modificarlo: motion.play({ ...motions.fadeInUp, duration: 600 }).

Un MotionSpec es un motion propio: los keyframes de cada canal ({ opacity: [0, 1], translateY: [24, 0] }), o una lista de frames tal como los escribe la Web Animations API ([{ opacity: 0, translateY: 24 }, { opacity: 1, translateY: 0 }], un frame sin offset se coloca según su posición en la lista), con el timing de los keyframes. Rust: MotionSpec::new(KeyframeTiming) con .values(channel, values) (repartidos uniformemente), .track(channel, keyframes) y .timing(|t| …); MotionPreset::FadeInUp (o .spec()) es un preset, y MotionChannel nombra los canales.

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 construye animaciones a partir de pasos (timing, spring, decay, sequence, parallel, …). No se ejecuta nada hasta start(); entonces todo el árbol se ejecuta de forma nativa, y cada paso empieza en el hilo de la UI en el momento exacto en que termina el anterior (sin hueco entre frames y sin ida y vuelta al código de la app entre pasos). Rust construye el mismo árbol 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 es un dato, no una función de la app: el runtime lo evalúa de forma nativa. En Rust es el enum Easing: Linear, EaseIn, EaseOut, EaseInOut, Bezier(x1, y1, x2, y2), Steps(count, StepPosition) y Curve(curve, mode), con un Curve (Quad, Cubic, Poly(n), Sin, Circle, Exp, Elastic(bounciness), Back(s), Bounce) y un EaseMode (In, Out, InOut). Para dibujar uno, Easing.sample(easing, count) (Rust: nsh_core::element::sample_easing) da sus valores en count puntos equidistantes de 0 a 1; Animated.sampleSpring y Animated.sampleDecay (sample_spring, sample_decay) dan los valores de un spring o de un decay, uno por frame (a fps, 60 por defecto) desde from (0) hasta que termina. Los tres provienen del código nativo con el que se ejecutan las animaciones. En cualquier lugar donde TSX acepte un Easing puedes pasar un nombre ("easeOut"), una curva Bézier cúbica como cuatro números, o una curva del objeto Easing.

Easing.steps(count, position) es el steps() de CSS: el valor salta entre count niveles en lugar de moverse (un sprite fotograma a fotograma, una aguja que marca los segundos). position indica dónde caen los saltos: "jump-end" (el valor por defecto, también "end"), "jump-start" ("start"), "jump-none" o "jump-both"; Rust: Easing::Steps(count, StepPosition::JumpEnd), JumpStart, JumpNone, JumpBoth.

Las curvas están en su forma «in» (lentas al principio). Easing.out(curve) invierte una, Easing.inOut(curve) la hace simétrica, Easing.in(curve) la deja tal cual; en Rust eso es el 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) anima de forma nativa los cambios de layout del siguiente commit: las vistas que se mueven o cambian de tamaño se deslizan hasta sus nuevos frames, las vistas nuevas aparecen (con fundido o escala de entrada, según property) y las vistas eliminadas desaparecen. Llámalo justo antes del cambio de estado que modifica el layout. Rust: animate_layout(LayoutAnimation), con los presets de nsh_core::element::LayoutAnimation o sus transiciones create, update y 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

La API de device informa a la app sobre el dispositivo y su entorno. El código Rust llama a las funciones de nsh_core::prelude (window(), dark(), font_scale(), locale(), lifecycle(), os(), idiom(), pixel_ratio(), set_color_scheme(), …); TSX las importa desde nsh. El tamaño de la ventana, el esquema de color, la escala de fuente, la proporción de píxeles, el locale y el estado de la app son reactivos: léelos en un binding (un closure que se pasa a un elemento en Rust, JSX en TSX), computed o effect, y lo que los lee se actualiza cuando la plataforma informa de un cambio (rotación, redimensionar la ventana, pasar al modo oscuro, cambiar el tamaño del texto o el idioma, moverse a una pantalla de otra densidad, salir de la app y volver).

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

Consulta Dispositivo y entorno para ver la guía.

#windowSize

const windowSize: Accessor<Size>;

El tamaño de la superficie en puntos: la ventana, o el NshAppView / NshView embebido. Reactivo. 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">;

La apariencia que se muestra: la del sistema, salvo que la app establezca la suya (nsh.json "appearance", setColorScheme). Reactivo. Rust: dark() -> bool; los colores del tema (AdaptiveColor) y la variante de estilo .dark(…) la siguen sin necesidad de leerla. La variante dark: de Tailwind también la sigue (véase 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>;

El tamaño de texto preferido del usuario relativo al predeterminado (1 es el tamaño predeterminado; Dynamic Type en iOS, tamaño de fuente en Android), o el tamaño de texto que establece en su lugar la app anfitriona. Reactivo. Rust: font_scale() -> f32. El texto ya escala con él salvo que allowFontScaling={false}; léelo cuando otros tamaños deban seguirlo, como los iconos junto al texto.

#locale

const locale: Accessor<string>;

El locale del usuario como etiqueta BCP 47 ("en-US", "zh-Hans-CN"), o el locale que establece en su lugar la app anfitriona. Reactivo. Rust: locale() -> Locale (locale().as_str() es la etiqueta). Intl formatea según él por defecto; léelo para elegir las cadenas de tus propias traducciones (Dispositivo y entorno).

#lifecycle

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

Indica si la app está en uso, en los términos de AppState de React Native: "active" en primer plano y recibiendo entrada, "inactive" mientras es visible sin el foco (otra app o ventana lo tiene, o el sistema muestra algo encima, como el selector de apps o una llamada entrante), "background" mientras no es visible (en segundo plano, minimizada, una pestaña del navegador oculta). Una app mostrada dentro de una app nativa sigue el estado de esa app. Reactivo. Rust: lifecycle() -> Lifecycle (Lifecycle::Active, Inactive, Background).

Léelo en un efecto para pausar el trabajo que nadie ve y reanudarlo cuando la app vuelva:

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;

Muestra la app en scheme sea cual sea la apariencia del sistema, de inmediato: colorScheme(), las clases dark:, el tema de los componentes y los controles de la plataforma (alertas, el estilo predeterminado de la barra de estado) la siguen; "system" vuelve a seguir al sistema. nsh.json "appearance" lo establece desde el inicio. 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 plataforma en la que se ejecuta la app, constante mientras se ejecuta.

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

Devuelve el valor para el SO actual (ios, android, web, …); si no, desktop o mobile (según platform.desktop); si no, native (todas las plataformas excepto la web); si no, default; si no, undefined. El código Rust hace match sobre os() (y is_desktop() para 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>;

Píxeles de dispositivo por punto (p. ej. 3 en la mayoría de los iPhone). Reactivo: cambia cuando la ventana se mueve a una pantalla de otra densidad (en Mac Catalyst, los escritorios o una pantalla externa) y cuando el ajuste de tamaño de pantalla de Android cambia la densidad. Rust: pixel_ratio() -> f32, y round_to_nearest_pixel(points) para una longitud en píxeles de dispositivo enteros; en TSX esa longitud es 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;
}

Abre url fuera de la app: una página web en el navegador, un enlace mailto: en la app de correo, un enlace tel: en la app de teléfono, y cualquier esquema que otra app haya registrado (maps:, los enlaces lb:// propios de una app anfitriona). Se resuelve con { opened }, que indica si algo lo abrió: false cuando ninguna app gestiona el esquema. Rust: open_url(url) de nsh_core::prelude, una respuesta que se espera con await en una tarea (o que se descarta), el mismo 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>

• La URL es absoluta (tiene un esquema). Las URL que ejecutarían código o accederían a los datos propios de la app, javascript:, data:, blob:, file:, about: y asset:, rechazan la promesa con un TypeError, igual que las direcciones relativas. openUrl nunca lanza una excepción: todo fallo se rechaza.
• Una app que declara capacidades necesita openUrl: "openUrl": true para todos los esquemas, o "openUrl": { "schemes": ["https", "mailto"] } para los indicados; las demás URL se rechazan con un Error cuyo code es "ERR_ACCESS_DENIED", permission "openUrl" y resource la URL (véase Sandbox y capacidades). En Rust, open_url responde false en esos casos y registra el motivo.
• La app anfitriona ve la URL primero y puede enrutarla por su propio router en su lugar (Swift NshAppView.onOpenURL, Java NshView.setOpenUrlHandler, Rust AppView::host().handle_open_url; véanse iOS y Android). En ese caso opened es true.
• Cada plataforma la abre con su propio mecanismo: UIApplication.open en iOS (la aplicación de la app anfitriona cuando está incrustada), un intent ACTION_VIEW en Android, NSWorkspace en macOS, ShellExecuteW en Windows, GtkUriLauncher en Linux, open_url de GPUI, una pestaña nueva en la web. nsh test registra las URL en lugar de abrirlas.
• Un TextView abre sus enlaces de esta manera con links="open".

#Dirección del diseño

La dirección del diseño sigue el idioma del usuario: en un idioma de derecha a izquierda (árabe, hebreo, …) la app se dispone de derecha a izquierda, las filas parten desde la derecha, y las propiedades de estilo left / right (marginLeft, paddingRight, …) significan inicio y fin. Los cambios se aplican al instante, sin reiniciar.

El estilo direction de una vista ("ltr", "rtl" o "inherit", el valor predeterminado) fija la dirección de su propio subárbol; 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>

#Relacionado

• Los márgenes de área segura (Rust safe_area(); TSX safeArea(), safeAreaInsets()) y el teclado de software (Rust keyboard_height(); TSX keyboardFrame()) están en Área segura y teclado.
• Los ajustes de lector de pantalla y de movimiento reducido están en Accesibilidad.

#PanResponder

Los pan responders son gestos de arrastre sobre el sistema de gesture responder: el elemento reclama los toques de un gesto y luego los escucha en exclusiva junto con el estado del gesto, que sigue por ti el centroide de los toques, la distancia recorrida y la velocidad. El código Rust los reclama con .claim_touches(TouchClaim::…) y los escucha con listeners .on_responder_* cuyo ResponderEvent lleva un PanGesture, todo en nsh_core::prelude; TSX importa PanResponder de nsh, cuyos callbacks onPanResponder… reciben el evento táctil y el estado del gesto.

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. Aplica su panHandlers con spread en la vista que debe recibir el gesto. En Rust, la vista reclama los toques y escucha por sí misma:

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

Cada callback recibe el evento táctil (GestureResponderEvent, de nsh) y el estado del gesto. En Rust, un claim decide con .ask(|request: &ClaimRequest| …), llamando a request.claim() para tomar los toques (sin ask los toma siempre), y cada listener recibe un ResponderEvent cuyo gesture es el estado.

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 los puntos como Point<Points>.

#Dentro de scroll views

Mientras un pan responder es el responder, las scroll views nativas que lo rodean no se desplazan (onShouldBlockNativeResponder es true por defecto). Para que un deslizamiento horizontal conviva con el desplazamiento vertical, conviértete en el responder solo en los movimientos horizontales:

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

Para un pan que la plataforma reconoce, TouchClaim::on_pan(PanActivation::horizontal(10.0, 10.0)) decide en el hilo principal mientras se mueven los dedos. Las props de responder subyacentes (onStartShouldSetResponder, onResponderGrant, onTouchStart, …) también se pueden usar directamente en cualquier elemento; véase Elementos.

#Clipboard

La API de Clipboard lee y escribe el portapapeles del sistema: texto en todas partes (UIPasteboard en iOS, ClipboardManager en Android, NSPasteboard, GDK y el portapapeles de Win32 en escritorio, navigator.clipboard en la web), imágenes en iOS, escritorio y la web, y los archivos copiados en un administrador de archivos en escritorio y Mac Catalyst. El código Rust llama a las funciones de nsh_core::prelude (set_clipboard, clipboard_string, …); TSX importa Clipboard de 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
}

Las lecturas de Rust devuelven respuestas que se esperan con await en una tarea (spawn, o una función de módulo async); ClipboardImage es nsh_core::element::ClipboardImage, con url y size (un Size<DevicePixels>).

Las imágenes pasan por el portapapeles en iOS, escritorio y la web. En Android el portapapeles transporta texto: writeImage y readImage se rechazan con un Error cuyo code es "ERR_FEATURE_UNAVAILABLE_ON_PLATFORM", y hasImage se resuelve false. En Rust, set_clipboard_image deja el portapapeles como está allí y clipboard_image responde None.

El usuario también puede copiar por sí mismo desde un texto seleccionable; la API de Clipboard sirve para copiar desde el código, por ejemplo con un botón Copiar.

#Clipboard.writeText

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

Pone text en el portapapeles, reemplazando lo que hubiera. 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 resuelve con el texto del portapapeles, o con "" cuando no contiene ninguno. Rust: clipboard_string(). En iOS, leer el portapapeles puede mostrar el aviso de pegado del sistema (“App pegó desde …”), y en Android 10 y posteriores solo la app en primer plano puede leerlo. Léelo cuando el usuario pida pegar, no en cada pantalla.

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 resuelve con un valor que indica si el portapapeles contiene texto, sin leerlo: sin aviso de pegado en iOS. Rust: clipboard_has_string(). Úsalo para decidir si mostrar un botón Pegar. En la web, los navegadores solo lo saben leyendo, por lo que puede pedir permiso al usuario.

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 resuelve con la imagen del portapapeles, o con null cuando no contiene ninguna: una captura de pantalla pegada, o una imagen copiada en un navegador o en un editor de imágenes. Rust: clipboard_image(), None cuando no contiene ninguna. url es una URL de la imagen (PNG, o el JPEG, GIF, WebP o BMP propio del portapapeles) que un Image muestra como su src y que fetch lee: fetch(url) da sus bytes, para una subida. size (width y height) es su tamaño en píxeles, tal como se decodifica. Igual que con readText, léela cuando el usuario pida pegar. Se leen imágenes de hasta 48 MB (codificadas), de modo que la imagen quepa en la memoria de la app; una mayor se rechaza con un Error cuyo code es "ERR_NSH_QUOTA_EXCEEDED" (su mensaje indica el tamaño de la imagen y el límite), mientras que hasImage se resuelve true. Rust: clipboard_image() responde None en ese 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>;

Una app de estilo chat donde los usuarios pegan capturas de pantalla en un compositor enlaza el atajo de pegado mientras su input tiene el foco y toma la imagen cuando hay 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>;

Se resuelve con un valor que indica si el portapapeles contiene una imagen, sin leerla: sin aviso de pegado en iOS. Rust: clipboard_has_image(). En Android se resuelve false.

#Clipboard.writeImage

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

Pone en el portapapeles la imagen de src, una URL data: en base64 o la url que dio readImage, reemplazando lo que contiene. Rust: set_clipboard_image(src). En Windows toma un PNG, el formato que leen los navegadores, Office y la Herramienta Recortes. En Android se rechaza con "ERR_FEATURE_UNAVAILABLE_ON_PLATFORM".

set_clipboard_image(image.url.clone());

await Clipboard.writeImage(image.url);

#Clipboard.readFiles

readFiles(): Promise<string[]>;

Se resuelve con las URL file: de los archivos y carpetas copiados en un administrador de archivos (Finder, Explorer, Files), en su orden, o []: las mismas URL que da un file drop. Rust: clipboard_files(). Analiza una URL para obtener su ruta.

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

La API de picker muestra el selector de fotos del sistema y entrega a la app las imágenes que elige el usuario: el selector de Photos en iOS (PHPickerViewController), el Photo Picker en Android, un panel de apertura o un diálogo de archivos en los escritorios y un file input en un navegador. En iOS y Android el selector se ejecuta fuera de la app y entrega solo lo que el usuario elige, por lo que no necesita permiso para la fototeca. Cada imagen elegida llega como un File (TSX) o un PickedFile (Rust) cuyos bytes permanecen nativos: muéstrala con URL.createObjectURL(file) en un Image, súbela con fetch y FormData. El código Rust llama a pick_images de nsh_core::prelude; TSX importa Picker de 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[]>;

Muestra el selector y se resuelve con las imágenes que el usuario eligió, en el orden en que las eligió, o con [] cuando el usuario cancela. Rust: pick_images(request), una respuesta que se espera en una tarea (spawn, o una función de módulo de async). pickImages nunca lanza excepciones: las opciones fuera de rango (limit: 0, un quality fuera de 0 a 1) rechazan la promesa con un RangeError, y una selección que las capacidades de la app no permiten la rechaza con ERR_ACCESS_DENIED (más abajo). Cancelar es una respuesta del usuario, no un fallo: se resuelve con [].

Las imágenes llegan listas para enviar:

• Formatos que aceptan todos los navegadores y servidores. JPEG, PNG, GIF y WebP llegan tal cual; una foto almacenada en otro formato (HEIC en los iPhone, HEIF, TIFF) llega como JPEG. format: "current" conserva el formato almacenado.
• Reducidas de forma nativa. Con maxDimension, una imagen cuyo lado más largo supere ese valor se reduce para ajustarse a él, en posición vertical, y se codifica de nuevo: un PNG como PNG, cualquier otro como JPEG de quality. Las fotos de teléfono tienen de 12 a 48 megapíxeles; reducirlas a 2048 píxeles antes de subirlas las deja en unos cientos de kilobytes. Un quality también vuelve a codificar los JPEG.
• Lo que muestra. size es el tamaño de la imagen en píxeles tal como se ve, con su orientación de cámara aplicada. Una imagen que NSH codifica de nuevo no lleva metadatos (ni ubicación); una que llega tal cual conserva los suyos.

En Windows, Linux y en las ventanas GPUI, el diálogo ofrece los formatos que admite la solicitud (con "compatible": JPEG, PNG, GIF y WebP) y los archivos llegan tal como están almacenados, con su propio tamaño.

Un compositor de chat adjunta una foto, la muestra mientras se escribe el mensaje y la sube cuando se envía:

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