nsh

nsh é o módulo principal: a API reativa (signals, valores computados, effects, context), mount, token, os elementos host View, Text, Scroll e Overlay, views selecionáveis, a área segura e o teclado, animação, o dispositivo e seu ambiente, PanResponder, a área de transferência, o seletor de fotos, o reconhecimento de fala, o armazenamento, o canal do host, atalhos de teclado, componentes e módulos nativos, acessibilidade e os tipos TypeScript de elementos, estilos e eventos. O grafo reativo em si roda nativamente em Rust; ler um signal é uma chamada ao runtime que custa alguns nanossegundos, e apenas as suas próprias closures rodam no interpretador JavaScript.

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

A reatividade do NSH segue o mesmo modelo do SolidJS: uma função de componente roda uma única vez, e as partes da UI que leem signals são atualizadas no lugar quando esses signals mudam. Não há nova renderização do componente nem DOM virtual. Veja Reatividade para o guia.

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

Um signal guarda um valor. Chamá-lo lê o valor e, dentro de um escopo de rastreamento (expressões JSX, computed, effect), inscreve esse escopo nele. set e update o escrevem; tudo o que o leu é atualizado.

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 padrão, uma escrita que seja === ao valor atual não faz nada. Passe equals: false para notificar a cada escrita (útil quando você muta um objeto no lugar e atribui o mesmo objeto de novo), ou a sua própria comparação:

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

Um valor derivado de signals. fn roda novamente quando um signal que ele leu muda; os leitores do valor computado só são atualizados quando o resultado muda (por equals, === por padrão). fn recebe o resultado anterior.

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

Use computed quando uma derivação for cara ou for lida em vários lugares. Para uma expressão barata, uma função simples (const full = () => first() + " " + last()) é igualmente reativa.

#effect

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

Executa fn após a renderização, e de novo sempre que um signal que ele leu mudar. Use effects para efeitos colaterais: logs, timers, comunicação com módulos nativos. Um effect pertence ao componente (ou effect) em que foi criado e é descartado junto com ele.

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

Para desfazer algo antes de o effect rodar novamente (ou quando o componente for removido), chame cleanup dentro dele.

#batch

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

Executa fn e aplica todas as suas escritas juntas no final, de modo que os leitores sejam atualizados uma vez, em vez de uma vez por escrita. Retorna o que fn retorna.

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

#untracked

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

Executa fn sem inscrever o escopo atual no que ele lê. Use-o para ler um signal dentro de um effect ou de uma expressão JSX sem depender dele.

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

#cleanup

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

Registra fn para ser executado antes de o effect atual rodar novamente, ou quando o componente ou effect atual for removido.

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

Um valor que um componente fornece a tudo o que ele renderiza, não importa a profundidade. Chamar o context (Theme()) lê o valor do provider mais próximo, ou defaultValue se não houver nenhum.

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 na superfície (a janela, ou o NshAppView / NshView no qual o app está embutido) e retorna uma função que o remove. O arquivo de entrada de todo app termina com 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 um objeto de props nas props nomeadas em keys e no restante. As duas metades continuam reativas: props cujos valores mudam são getters, e split os mantém como getters. Use-o em um componente que trata algumas props por conta própria e repassa as outras. Desestruturar as props (const { label } = props) as leria uma vez só e perderia as atualizações.

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 seus filhos, ou fallback quando algo abaixo deles lança um erro: o corpo de um componente, um binding, um effect ou um manipulador de eventos. A parte que falhou é removida e o fallback aparece em seu lugar. Uma função fallback é chamada como fallback(error, reset) com o valor lançado e reset, que renderiza os filhos novamente, independentemente dos parâmetros que ela declare; um elemento fallback é exibido como está. Uma falha vai para a boundary mais próxima acima dela, e uma falha em um fallback vai para a boundary acima dessa. Componentes Rust usam catch_error (Limites de erro).

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

O design token name do tema do app ("theme" em nsh.json, sobre os tokens do shadcn/ui) na aparência exibida: uma cor como #rrggbbaa, um comprimento como um número de pontos, uma fonte como o nome da sua família. Os nomes são as variáveis CSS do tema sem -- (primary, muted-foreground, radius, font-mono, e os próprios do app, como up). A leitura é reativa: um componente, memo ou effect que lê um token roda novamente quando o tema ou a aparência muda. Tokens lista os tokens do app com seus tipos; o NSH o escreve em .nsh/types/nsh/tokens.d.ts a partir do tema. Para classes, nomeie os tokens diretamente (bg-primary, rounded-(--radius)): Tokens de 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;

Os elementos host que nsh exporta, escritos como tags: <View>, <Text>, <Scroll>, <Overlay> (seus filhos por cima da janela, posicionados em relação a uma âncora: Overlay). O compilador cria a view nativa no lugar para uma tag que nomeia um deles por meio do seu import (inclusive com alias), então importá-los não custa nada em tempo de execução. Eles são componentes como quaisquer outros, portanto também podem ser passados adiante (const Tag = inline ? Text : View). nsh exporta os demais primitivos da mesma forma: List, Image, Canvas, WebView e Video, cada um com sua própria página de referência. Suas props estão documentadas em Elementos. O campo de entrada de texto, Input, vem de nsh/base.

#Área segura e teclado

As variáveis de ambiente do CSS mantêm o conteúdo longe da UI do sistema, no padding e na margin de qualquer view (padding, paddingTop, …, as mesmas chaves de margin; os valores arbitrários p* / m* do Tailwind; os métodos Styled .p_safe_area(), .pt_safe_area_plus(..), .pb_keyboard(), … em Rust). Seus valores são EnvValues: env(name), env(name, <length>), calc(env(name) + <length>) e calc(<length> + env(name)).

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

#safeArea e safeAreaInsets

safeArea() é a área segura da superfície (safe_area() em Rust); safeAreaInsets() são os insets de onde um componente é renderizado (cx.insets() em Rust), os valores das variáveis safe-area-inset-*. Ambos são Edges reativos ({ top, right, bottom, left } em pontos). Veja safeArea e safeAreaInsets.

#Keyboard e keyboardFrame

Keyboard.dismiss() oculta o teclado virtual (dismiss_keyboard() em Rust) e keyboardFrame() informa quanto da tela ele cobre (keyboard_height() e keyboard_duration() em Rust). Veja Ocultando o teclado e A altura do teclado.

#Views selecionáveis

<View selectable> (view().selectable(true) em Rust) faz com que os textos dentro dele sejam selecionados em conjunto, como os de uma página web: uma única seleção percorre views, elementos Text e TextViews, em ordem de leitura. Veja Seleção de texto.

#Animação

A API de animação anima na thread de UI. Você cria um valor animado, o vincula (ou vincula valores derivados dele) a uma propriedade de estilo e inicia uma animação; a partir daí, cada frame é calculado nativamente, sem executar o código do app. Um engine ou uma thread JS ocupados não conseguem fazer a animação travar, e uma animação não custa ao app nenhum trabalho por frame. O código Rust usa animated_value(), motion(), Animation, Spring, Timing, KeyframeTiming, MotionPreset e Easing de nsh_core::prelude e vincula valores com os métodos .bind_* dos elementos; o TSX os 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";

Veja Animação para o guia.

#O que um valor animado pode controlar

Outras propriedades de estilo aceitam valores simples; para animar o próprio layout (tamanhos, posições no fluxo), use LayoutAnimation.

#createAnimatedValue

function createAnimatedValue(value?: number): AnimatedValue;

Cria um valor animado começando em value (padrão 0). Rust: animated_value(value), um handle Copy mantido pelo componente que o criou.

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 animação retorna uma promise que resolve com { finished }: true quando a animação terminou, false quando foi interrompida (por stop, set ou outra animação do mesmo valor). Em Rust ele retorna um AnimationEnd, que uma task aguarda para obter o mesmo 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";

Um nó do grafo de animação nativo: um AnimatedValue, ou um valor derivado de outros. Os nós derivados são avaliados na thread de UI sempre que suas entradas mudam.

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) reproduz um valor por meio de keyframes e resolve com { finished }, indicando se terminaram; Animated.keyframes(value, { keyframes, ...options }) equivale a um passo de uma composição. Rust: value.keyframes(frames, KeyframeTiming) e Animation::keyframes(&value, frames, KeyframeTiming), com Keyframe::new(value) (distribuídos uniformemente), Keyframe::at(offset, value) e .ease(easing), e KeyframeTiming::new(ms) com .delay(ms), .easing(e), .iterations(Some(n)), .infinite() e .direction(PlaybackDirection::…).

Eles são reproduzidos como os keyframes de CSS: um easing molda um segmento (o de um keyframe é o segmento que começa nele; o do timing vale para todos os outros); offsets ausentes nos keyframes são distribuídos uniformemente, o primeiro em 0 e o último em 1; cada iteração começa com um salto para o seu primeiro keyframe, e sem um keyframe em 0 o valor parte de onde está; durante um delay o valor mantém o primeiro keyframe (CSS animation-fill-mode: backwards); iterações para trás executam os segmentos de trás para frente, com as curvas invertidas; o valor permanece onde a última iteração o deixa.

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

Cria um motion: um valor animado para cada canal da opacidade e da transformação de uma view, em repouso (opacidade e escalas 1, os demais 0), e motions para reproduzir nesses canais de forma nativa. Associe-o com style={motion.style}, ou aplique motion.style ou motion.transform com spread em um style; a transformação aplica suas translações, depois suas rotações, depois suas escalas, com scale incorporado em scaleX e scaleY: 7 dos 8 passos de transformação de uma view, o que deixa um para o seu ([{ perspective: 600 }, ...motion.transform] para flips 3D). initial define onde os canais começam ({ opacity: 0 }; os demais começam em repouso). Com enter, os canais que ele move começam onde esse motion começa (em initial) e ele é reproduzido imediatamente, com as demais opções como seu timing (delay, duration, …). Um motion move apenas opacidade e transformação: aplicar motion.style com spread define o opacity da view, então associe apenas motion.transform para manter uma opacidade sua, e mova cores com um valor animado e interpolate. Rust: motion(), um handle Copy mantido pelo componente que o criou, associado com .bind_motion(&m); motion().entering(spec) faz a entrada.

Quando o usuário pede menos movimento (reduceMotion()), play, animation e enter chegam de uma vez ao ponto onde o motion termina, sem se mover, a menos que ignoreReduceMotion esteja definido (nas opções ou no 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";
}

Os motions prontos como dados: motion.play("shake") reproduz motions.shake. MotionName é um entre fadeIn, fadeInUp, fadeInDown, fadeInLeft, fadeInRight, zoomIn, popIn, bounceIn, slideInUp, slideInDown, flipInX, flipInY (entrada); fadeOut, fadeOutUp, fadeOutDown, fadeOutLeft, fadeOutRight, zoomOut, popOut, slideOutDown, slideOutUp (saída); shake, headShake, wiggle, swing, pulse, heartbeat, rubberBand, jello, tada, jump, flash (atenção); spin, float, breathe, sway, bob, glow (loop). Animação descreve cada um. Aplique um preset com spread para alterá-lo: motion.play({ ...motions.fadeInUp, duration: 600 }).

Um MotionSpec é um motion seu: os keyframes de cada canal ({ opacity: [0, 1], translateY: [24, 0] }), ou uma lista de frames como a Web Animations API os escreve ([{ opacity: 0, translateY: 24 }, { opacity: 1, translateY: 0 }], com um frame sem offset posicionado pela sua posição na lista), com o timing de keyframes. Rust: MotionSpec::new(KeyframeTiming) com .values(channel, values) (distribuídos uniformemente), .track(channel, keyframes) e .timing(|t| …); MotionPreset::FadeInUp (ou .spec()) é um preset, e MotionChannel nomeia os canais.

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 monta animações a partir de passos (timing, spring, decay, sequence, parallel, …). Nada é executado até start(); então a árvore inteira é executada de forma nativa, e cada passo começa na thread de UI no exato momento em que o anterior termina (sem intervalo de frame, sem ida e volta ao código do app entre os passos). Rust monta a mesma árvore com 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;
};

Um easing é dado, não uma função do app: o runtime o avalia de forma nativa. Em Rust, é o enum Easing: Linear, EaseIn, EaseOut, EaseInOut, Bezier(x1, y1, x2, y2), Steps(count, StepPosition) e Curve(curve, mode), com Curve (Quad, Cubic, Poly(n), Sin, Circle, Exp, Elastic(bounciness), Back(s), Bounce) e EaseMode (In, Out, InOut). Para desenhar um, Easing.sample(easing, count) (Rust: nsh_core::element::sample_easing) fornece seus valores em count pontos igualmente espaçados de 0 a 1; Animated.sampleSpring e Animated.sampleDecay (sample_spring, sample_decay) fornecem os valores de uma spring ou de um decay, um por frame (a fps, 60 por padrão) a partir de from (0) até terminar. Os três vêm do código nativo que as animações executam. Onde quer que Easing seja aceito em TSX, você pode passar um nome ("easeOut"), uma Bézier cúbica como quatro números, ou uma curva do objeto Easing.

Easing.steps(count, position) equivale ao steps() do CSS: o valor salta entre count níveis em vez de se mover (um sprite quadro a quadro, um ponteiro que marca os segundos). position indica onde os saltos ocorrem: "jump-end" (o padrão, também "end"), "jump-start" ("start"), "jump-none" ou "jump-both"; Rust: Easing::Steps(count, StepPosition::JumpEnd), JumpStart, JumpNone, JumpBoth.

As curvas estão na forma “in” (lentas no início). Easing.out(curve) inverte uma, Easing.inOut(curve) a torna simétrica, Easing.in(curve) a mantém como está; em Rust, isso é o 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 as mudanças de layout do próximo commit: views que se movem ou mudam de tamanho deslizam até seus novos frames, novas views aparecem (com fade ou escala de entrada, conforme property) e views removidas desaparecem. Chame logo antes da mudança de estado que altera o layout. Rust: animate_layout(LayoutAnimation), com os presets de nsh_core::element::LayoutAnimation ou suas transições create, update e delete.

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

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

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

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

#Device

A API de device informa ao app sobre o dispositivo e seu ambiente. O código Rust chama as funções de nsh_core::prelude (window(), dark(), font_scale(), locale(), lifecycle(), os(), idiom(), pixel_ratio(), set_color_scheme(), …); TSX as importa de nsh. O tamanho da janela, o esquema de cores, a escala de fonte, a razão de pixels, o locale e o estado do app são reativos: leia-os em um binding (uma closure passada a um elemento em Rust, JSX em TSX), computed ou effect, e o que os lê é atualizado quando a plataforma reporta uma mudança (rotação, redimensionamento da janela, troca para o modo escuro, mudança do tamanho do texto ou do idioma, mudança para uma tela de outra densidade, saída do app e retorno).

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

Consulte o guia Dispositivo e ambiente.

#windowSize

const windowSize: Accessor<Size>;

O tamanho da superfície em pontos: a janela, ou o NshAppView / NshView incorporado. Reativo. 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">;

A aparência exibida: a do sistema, a menos que o app tenha definido a sua (nsh.json "appearance", setColorScheme). Reativo. Rust: dark() -> bool; as cores do tema (AdaptiveColor) e a variante de estilo .dark(…) a acompanham sem precisar lê-la. A variante dark: do Tailwind também a acompanha (veja 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>;

O tamanho de texto preferido do usuário em relação ao padrão (1 é o tamanho padrão; Dynamic Type no iOS, tamanho da fonte no Android), ou o tamanho de texto que o app hospedeiro define no lugar. Reativo. Rust: font_scale() -> f32. O texto já escala com ele, a menos que allowFontScaling={false}; leia-o quando outros tamanhos devam acompanhá-lo, como ícones ao lado de texto.

#locale

const locale: Accessor<string>;

O locale do usuário como uma tag BCP 47 ("en-US", "zh-Hans-CN"), ou o locale que o app hospedeiro define no lugar. Reativo. Rust: locale() -> Locale (locale().as_str() é a tag). Intl formata para ele por padrão; leia-o para escolher as strings das suas próprias traduções (Dispositivo e ambiente).

#lifecycle

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

Se o app está em uso, nos termos do AppState do React Native: "active" em primeiro plano e recebendo entrada, "inactive" enquanto visível sem o foco (outro app ou janela o tem, ou o sistema exibe algo sobre ele, como o seletor de apps ou uma chamada recebida), "background" enquanto não visível (em segundo plano, minimizado, uma aba de navegador oculta). Um app exibido dentro de um app nativo segue o estado desse app. Reativo. Rust: lifecycle() -> Lifecycle (Lifecycle::Active, Inactive, Background).

Leia-o em um effect para pausar trabalho que ninguém vê e retomá-lo quando o app voltar:

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;

Exibe o app em scheme independentemente da aparência do sistema, de imediato: colorScheme(), as classes dark:, o tema dos componentes e os controles da plataforma (alertas, o estilo padrão da barra de status) a acompanham; "system" volta a seguir o sistema. nsh.json "appearance" a define desde o início. 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;
}

A plataforma em que o app é executado, constante enquanto ele roda.

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

Retorna o valor para o SO atual (ios, android, web, …); senão desktop ou mobile (conforme platform.desktop); senão native (todas as plataformas, exceto a web); senão default; senão undefined. O código Rust usa match em os() (e em 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>;

Pixels do dispositivo por ponto (p. ex. 3 na maioria dos iPhones). É reativo: muda quando a janela vai para uma tela de outra densidade (no Mac Catalyst, nos desktops ou em um monitor externo) e quando a configuração de tamanho de exibição do Android altera a densidade. Rust: pixel_ratio() -> f32, e round_to_nearest_pixel(points) para um comprimento em pixels inteiros do dispositivo; em TSX, esse comprimento é 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 fora do app: uma página web no navegador, um link mailto: no app de e-mail, um link tel: no app de telefone e qualquer esquema que outro app tenha registrado (maps:, os links lb:// próprios de um app host). Resolve com { opened }, indicando se algo o abriu: false quando nenhum app trata o esquema. Rust: open_url(url) de nsh_core::prelude, uma resposta para aguardar em uma task (ou descartar), o mesmo 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>

• A URL é absoluta (tem um esquema). URLs que executariam código ou acessariam os dados do próprio app, javascript:, data:, blob:, file:, about: e asset:, rejeitam a promise com um TypeError, assim como endereços relativos. openUrl nunca lança exceção: toda falha rejeita.
• Um app que declara capabilities precisa de openUrl: "openUrl": true para todos os esquemas, ou "openUrl": { "schemes": ["https", "mailto"] } para os listados; as demais URLs rejeitam com um Error cujo code é "ERR_ACCESS_DENIED", permission "openUrl" e resource a URL (veja Sandbox e capabilities). Em Rust, open_url responde false nesses casos e registra o motivo no log.
• O app que embute o Native Shell vê a URL primeiro e pode encaminhá-la ao seu próprio roteador (Swift NshAppView.onOpenURL, Java NshView.setOpenUrlHandler, Rust AppView::host().handle_open_url; veja iOS e Android). opened então é true.
• Cada plataforma a abre com seu próprio mecanismo: UIApplication.open no iOS (o application do app host quando embutido), uma intent ACTION_VIEW no Android, NSWorkspace no macOS, ShellExecuteW no Windows, GtkUriLauncher no Linux, o open_url do GPUI e uma nova aba na web. nsh test registra as URLs em vez de abri-las.
• Um TextView abre seus links dessa forma com links="open".

#Direção do layout

A direção do layout segue o idioma do usuário: em um idioma da direita para a esquerda (árabe, hebraico, …), o app é disposto da direita para a esquerda, as linhas partem da direita, e as propriedades de estilo left / right (marginLeft, paddingRight, …) significam início e fim. As mudanças se aplicam imediatamente, sem reiniciar.

O estilo direction de uma view ("ltr", "rtl" ou "inherit", o padrão) define a direção da sua própria subárvore; em 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>

#Relacionados

• Os safe area insets (Rust safe_area(); TSX safeArea(), safeAreaInsets()) e o teclado virtual (Rust keyboard_height(); TSX keyboardFrame()) estão em Safe area e teclado.
• As configurações de leitor de tela e de redução de movimento estão em Acessibilidade.

#PanResponder

Pan responders são gestos de arrastar construídos sobre o sistema de gesture responder: o elemento reivindica os toques de um gesto e passa a recebê-los sozinho, junto com o estado do gesto, que acompanha para você o centroide dos toques, a distância percorrida e a velocidade. O código Rust os reivindica com .claim_touches(TouchClaim::…) e os escuta com listeners .on_responder_* cujo ResponderEvent carrega um PanGesture, tudo em nsh_core::prelude; o TSX importa PanResponder de nsh, cujos callbacks onPanResponder… recebem o evento de toque e o estado do 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;
}

Cria um pan responder. Espalhe seu panHandlers na view que deve receber o gesto. Em Rust, a view reivindica os toques e escuta por conta própria:

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

Todo callback recebe o evento de toque (GestureResponderEvent, de nsh) e o estado do gesto. Em Rust, uma reivindicação decide com .ask(|request: &ClaimRequest| …), chamando request.claim() para assumir os toques (sem ask ela sempre os assume), e cada listener recebe um ResponderEvent cujo gesture é o 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, com pontos como Point<Points>.

#Dentro de scroll views

Enquanto um pan responder é o responder, as scroll views nativas ao redor dele não rolam (onShouldBlockNativeResponder tem como padrão true). Para que um deslize horizontal conviva com a rolagem vertical, torne-se o responder apenas em movimentos horizontais:

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 um pan que a plataforma reconhece, TouchClaim::on_pan(PanActivation::horizontal(10.0, 10.0)) decide na thread principal conforme os dedos se movem. As props de responder subjacentes (onStartShouldSetResponder, onResponderGrant, onTouchStart, …) também podem ser usadas diretamente em qualquer elemento; veja Elementos.

#Clipboard

A API Clipboard lê e grava a área de transferência do sistema: texto em todo lugar (UIPasteboard no iOS, ClipboardManager no Android, NSPasteboard, GDK e a área de transferência do Win32 nos desktops, navigator.clipboard na web), imagens no iOS, nos desktops e na web, e os arquivos copiados em um gerenciador de arquivos nos desktops e no Mac Catalyst. O código Rust chama as funções de nsh_core::prelude (set_clipboard, clipboard_string, …); o 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
}

As leituras em Rust retornam respostas para aguardar em uma task (spawn, ou uma função de módulo async); ClipboardImage é nsh_core::element::ClipboardImage, com url e size (um Size<DevicePixels>).

As imagens passam pela área de transferência no iOS, nos desktops e na web. No Android, a área de transferência carrega texto: writeImage e readImage rejeitam com um Error cujo code é "ERR_FEATURE_UNAVAILABLE_ON_PLATFORM", e hasImage resolve false. Em Rust, set_clipboard_image deixa a área de transferência como está nesse caso e clipboard_image responde None.

O usuário também pode copiar por conta própria de um texto selecionável; a API Clipboard serve para copiar a partir do código, como em um botão Copiar.

#Clipboard.writeText

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

Coloca text na área de transferência, substituindo o que havia nela. 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>;

Resolve com o texto da área de transferência, ou "" quando ela não contém nenhum. Rust: clipboard_string(). No iOS, ler a área de transferência pode exibir o aviso de colagem do sistema (“App colou de …”), e no Android 10 e posteriores somente o app em primeiro plano pode lê-la. Leia-a quando o usuário pedir para colar, não em toda tela.

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

Resolve com a informação de se a área de transferência contém texto, sem lê-la: sem aviso de colagem no iOS. Rust: clipboard_has_string(). Use-o para decidir se deve exibir um botão Colar. Na web, os navegadores só informam isso lendo o conteúdo, então pode ser solicitada permissão ao usuário.

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

Resolve com a imagem da área de transferência, ou null quando ela não contém nenhuma: uma captura de tela colada, ou uma imagem copiada em um navegador ou em um editor de imagens. Rust: clipboard_image(), None quando não contém nenhuma. url é uma URL da imagem (PNG, ou o JPEG, GIF, WebP ou BMP da própria área de transferência) que uma Image exibe como seu src e que fetch lê: fetch(url) fornece seus bytes, para um upload. size (width e height) é seu tamanho em pixels, como decodificada. Assim como em readText, leia-a quando o usuário pedir para colar. Imagens de até 48 MB (codificadas) são lidas, de modo que a imagem caiba na memória do app; uma imagem maior rejeita com um Error cujo code é "ERR_NSH_QUOTA_EXCEEDED" (sua mensagem informa o tamanho da imagem e o limite), enquanto hasImage resolve true. Rust: clipboard_image() responde None nesse 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>;

Um app no estilo chat em que os usuários colam capturas de tela em um campo de composição associa o atalho de colar enquanto seu input tem o foco e pega a imagem quando houver uma:

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

Resolve com a informação de se a área de transferência contém uma imagem, sem lê-la: sem aviso de colagem no iOS. Rust: clipboard_has_image(). No Android, resolve false.

#Clipboard.writeImage

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

Coloca na área de transferência a imagem de src, uma URL data: em base64 ou a url que readImage forneceu, substituindo o que ela contém. Rust: set_clipboard_image(src). No Windows, aceita um PNG, o formato que navegadores, o Office e a Ferramenta de Captura leem. No Android, rejeita com "ERR_FEATURE_UNAVAILABLE_ON_PLATFORM".

set_clipboard_image(image.url.clone());

await Clipboard.writeImage(image.url);

#Clipboard.readFiles

readFiles(): Promise<string[]>;

Resolve com as URLs file: dos arquivos e pastas copiados em um gerenciador de arquivos (Finder, Explorer, Files), na mesma ordem, ou []: as mesmas URLs que um drop de arquivos fornece. Rust: clipboard_files(). Faça o parse de uma URL para obter seu caminho.

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

A API de picker mostra o seletor de fotos do sistema e entrega ao app as imagens escolhidas pelo usuário: o Photos picker no iOS (PHPickerViewController), o Photo Picker no Android, um painel de abertura ou diálogo de arquivo nos desktops e um file input em um navegador. No iOS e no Android o seletor roda fora do app e entrega apenas o que o usuário escolhe, então não precisa de permissão para a biblioteca de fotos. Cada imagem escolhida chega como um File (TSX) ou um PickedFile (Rust) cujos bytes permanecem nativos: mostre-a com URL.createObjectURL(file) em um Image, envie-a com fetch e FormData. O código Rust chama pick_images de nsh_core::prelude; o 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[]>;

Mostra o seletor e resolve com as imagens escolhidas pelo usuário, na ordem em que foram escolhidas, ou com [] quando o usuário cancela. Rust: pick_images(request), uma resposta para aguardar em uma task (spawn, ou uma função de módulo de async). pickImages nunca lança exceção: opções fora do intervalo (limit: 0, um quality fora de 0 a 1) rejeitam a promise com um RangeError, e uma escolha que as capabilities do app não permitem rejeita com ERR_ACCESS_DENIED (abaixo). Um cancelamento é a resposta do usuário, não uma falha: ele resolve [].

As imagens chegam prontas para envio:

• Formatos que todo navegador e servidor aceitam. JPEG, PNG, GIF e WebP chegam como estão; uma foto armazenada em outro formato (HEIC em iPhones, HEIF, TIFF) chega como JPEG. format: "current" mantém o formato armazenado.
• Reduzidas nativamente. Com maxDimension, uma imagem cujo lado maior é maior que esse valor é reduzida para caber nele, na vertical, e codificada novamente: um PNG como PNG, qualquer outro como JPEG de quality. Fotos de celular têm de 12 a 48 megapixels; reduzi-las para 2048 pixels antes de um upload as deixa com algumas centenas de kilobytes. Um quality também recodifica JPEGs.
• O que ela exibe. size é o tamanho da imagem em pixels como ela aparece, com a orientação da câmera aplicada. Uma imagem que o NSH recodifica não carrega metadados (nem localização); uma que chega como está mantém os seus.

No Windows, no Linux e em janelas GPUI, o diálogo oferece os formatos que a requisição aceita (com "compatible": JPEG, PNG, GIF e WebP) e os arquivos chegam como estão armazenados, no tamanho original.

Um compositor de chat anexa uma foto, a exibe enquanto a mensagem é escrita e a envia quando a mensagem é enviada:

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