Elementos

Native Shell construye cada pantalla a partir de un pequeño conjunto de elementos: primitivas como View, Text y Image, y componentes base como Button, Dialog y NavStack. Cada primitiva es una vista nativa (una subclase de UIView en iOS y Mac Catalyst, un View de Android, una vista de AppKit, GTK o Win32 en los escritorios), creada y maquetada por el runtime de NSH. Todo lo que muestra una app está hecho con ellos: los botones, tarjetas, filas y pantallas de una app son sus propios componentes, dibujados con estos elementos y con el estilo que les da la app, de modo que su aspecto es enteramente suyo.

Cada ejemplo de estas páginas viene en Rust y TSX: elige una pestaña y todos los ejemplos de la página la siguen.

use nsh_core::prelude::*;

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

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

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

mount(App);

En Rust, las primitivas son funciones de nsh_core::prelude (view(), text(..), image(..)) y los componentes base provienen del crate nsh_base. Los estilos son métodos tipados (.flex_1(), .gap_3(), .px(px(20.0)), .bg(..)), los estilos de estado reciben un closure (.active(|s| s.opacity(0.6))), los listeners son closures de su evento (.on_press(move || ..), .on_change(move |text: &str| ..)) y .child(..) añade hijos. Un fragmento de UI es una función simple que devuelve impl IntoElement; se ejecuta una sola vez, y los signals que lee dentro de closures (text(move || ..), .bg(move || ..)) actualizan aquello a lo que están enlazados. Consulta Building with Rust.

En TSX, cada etiqueta va en PascalCase y nombra un binding en el ámbito: las primitivas provienen de nsh y los componentes base de nsh/base. Solo <If> y <Each> son globales que no necesitan importación. Una etiqueta en minúsculas como <view> es un error de compilación, porque TypeScript la comprobaría contra un tipo global por nombre, y componentes genéricos como List y Each no podrían inferir el tipo de sus elementos. El compilador reconoce los elementos por sus importaciones y crea las vistas nativas en el sitio, así que importarlos no cuesta nada en tiempo de ejecución. Consulta JSX and components.

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

#Primitivas

Se importan de nsh en TSX y de nsh_core::prelude en Rust.

El padding y el margin mantienen el contenido alejado de la interfaz del sistema con el env() de CSS: env(safe-area-inset-top) y los demás bordes (Safe area) y env(keyboard-inset-height) (Keyboard).

#Base

Se importan de nsh/base en TSX y del crate nsh_base en Rust. Poseen el comportamiento, el estado, el foco y la accesibilidad, y toman su aspecto de la app.

#Props comunes

Toda primitiva acepta las props siguientes (el tipo CommonProps en TSX; los traits Styled, Interactive y Accessible en Rust). Las páginas de cada elemento solo enumeran sus propias props. La columna Rust nombra el método del builder.

#Estilos

#Pulsaciones y respuesta visual

El manejo de las pulsaciones se ejecuta de forma nativa: la plataforma reconoce la pulsación y aplica los estilos de pulsación de la app, y el código de la app solo se entera después. Solo responde la vista pulsable más interna; dentro de las vistas de scroll, el inicio de una pulsación espera unos 130 ms para que un desplazamiento pueda comenzar primero.

PressEvent es { position, pagePosition, modifiers, clickCount }: dónde estaba el puntero en la vista y en su vista raíz (Points), las teclas modificadoras mantenidas cuando comenzó la pulsación y los clics consecutivos (2 para un doble clic). Cuando la plataforma no informa de ningún puntero, es el origen de la vista, sin teclas y con un clic.

La clave de estilo pointerEvents (.pointer_events(PointerEvents::BoxNone) en Rust, las clases pointer-events-*) decide qué toques reciben la vista y las vistas que contiene: "none" ninguna de las dos (una vista interior que establezca "auto" vuelve a recibirlos), "box-none" solo las vistas que contiene, "box-only" solo la propia vista (touch and gestures).

La respuesta visual de la pulsación es de la app: activeStyle (o las clases active:, .active(..) en Rust) se aplica mientras la vista está pulsada, de forma nativa, sin ida y vuelta al código de la app (más abajo).

#Estilos de estado

Estilos que se aplican mientras la vista está en un estado, sobre sus propios estilos, de forma nativa. Cada uno es la forma de objeto de una variante de Tailwind. Los estados posteriores prevalecen (selected, checked e indeterminate, luego hover, focus, active); disabledStyle prevalece sobre todos, y los demás no se aplican mientras la vista está deshabilitada. Cada uno recibe el estilo propio del elemento: un TextStyle en un <Text>, un InputStyle en un <Input>, un ImageStyle en un <Image>, un ViewStyle en cualquier otro.

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

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

#Hover

La app detecta cuándo el mouse entra en una vista, se mueve sobre ella y la abandona: en macOS, Windows, Linux, el backend de GPUI y en navegadores de escritorio, con el puntero de un iPad o el mouse de un Mac en iOS, y con un mouse o un lápiz en Android. Los estilos de hover (hover:, .hover(..)) dan estilo a las vistas bajo el cursor en esos mismos lugares.

Como :hover en CSS y mouseenter en el DOM, una vista cuenta como en hover mientras el mouse está sobre ella o sobre cualquier elemento dentro de ella, de modo que las vistas que rodean a la que está bajo el mouse también reciben onMouseEnter (de afuera hacia adentro; onMouseLeave de adentro hacia afuera). Los eventos llegan después de ocurrir el hecho y nunca con toques. Una vista que se elimina de debajo del mouse recibe onMouseLeave, en Linux y Windows en el siguiente movimiento del mouse.

MouseEvent indica dónde está el mouse, como lo hace MouseMoveEvent de GPUI: position en la vista (un Point en puntos, con sus transformaciones deshechas), pagePosition en la vista raíz que la contiene, como lo dan los toques, los modifiers presionados (control, alt, shift, platform: Command en las plataformas de Apple, la tecla Windows en las demás), y pressedButton, el botón presionado ("left", "right", "middle", "back" o "forward", el MouseButton de GPUI) o null; en Rust position, page_position, modifiers y pressed_button. En los escritorios y en la web, un arrastre también es un toque (onTouchMove, el responder), y sus movimientos llegan a onMouseMove con pressedButton activado: el feedback que solo sigue al hover los omite; en iOS y Android el hover informa del puntero sin ningún botón presionado. Los movimientos llegan como máximo una vez por fotograma, el más reciente, y siempre antes del onMouseLeave que los sigue, de modo que un manejador puede redibujar en cada movimiento:

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

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

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

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

#Tooltips

tooltip da una pista a cualquier elemento, que se muestra encima de él en los escritorios (macOS, Windows, Linux, el backend de GPUI y navegadores de escritorio) cuando el puntero ha reposado sobre él durante medio segundo, hasta que el puntero sale o lo presiona. Los teléfonos y las tabletas no muestran ninguna. La pista nunca captura el puntero ni las pulsaciones, así que el elemento funciona exactamente igual que sin ella.

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

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

El Tooltip define su propio aspecto, ubicación, retardo y eventos, como lo hace el .tooltip(..) de GPUI. Una app con muchos tooltips mantiene un pequeño componente propio que envuelve un texto en su Tooltip.

#Menús contextuales

onContextMenu indica a una vista que se presionó el botón secundario sobre ella: un clic derecho, Control-clic en macOS, un clic con dos dedos en un touchpad, el clic secundario del puntero de un iPad; en navegadores también la tecla de menú del teclado. Abre ahí el menú propio de la app; en TSX, Menu.popup muestra el del sistema:

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

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

import { Menu } from "nsh/desktop";

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

ContextMenuEvent tiene position en la vista, pagePosition en su vista raíz (donde Menu.popup ubica un menú: Menu.popup(items, e.pagePosition)) y los modifiers; en Rust position, page_position y modifiers. La vista más cercana que escucha, desde la que está bajo el puntero hacia afuera, lo recibe. Un campo de texto, o texto seleccionable con un menú de edición (Windows, el backend de GPUI, navegadores), más cercano que esa vista muestra su propio menú en su lugar. La plataforma lo decide en el momento en que el botón baja, a partir de lo que está montado, así que el manejador se entera después de ocurrir el hecho y no hay nada que cancelar. Una vista disabled deja el clic al oyente habilitado más cercano que la rodea. En pantallas táctiles, una pulsación larga abre los menús: maneja onLongPress con la misma función.

#Foco del teclado

En macOS y en la web, Tab mueve el foco del teclado entre sus paradas en el orden del árbol: los campos de texto, las vistas que aceptan pulsaciones y cada vista focusable. Los estilos de foco (focus:, .focus(..)) dan estilo a la vista con el foco, y Return o Espacio la presionan cuando acepta pulsaciones. Un clic presiona una vista sin darle el foco, de modo que los estilos de foco se muestran solo para el foco del teclado.

El foco y las pulsaciones son cosas distintas. Una vista que recibe teclas mientras tiene el foco (un gráfico, un slider, una lista que mueve su selección con las teclas de flecha) define focusable y enlaza sus teclas mientras tiene el foco (onFocus / onBlur con keymap); una pulsación sobre ella sigue llegando a un elemento presionable que la rodea, como una tarjeta que abre una página.

El focus() de una ref mueve el foco del teclado a una parada como lo hace Tab (se muestran sus estilos de foco y se dispara onFocus), por ejemplo para devolverlo al disparador de un popup que se cerró, y blur() lo quita.

Una vista que rodea al foco se da estilo a sí misma con focus-within: (focusWithinStyle, .focus_within(..)) mientras el foco está en ella o en cualquier vista dentro de ella: el marco de un campo alrededor del input que edita, una barra de herramientas mientras uno de sus botones tiene el foco. El contenido de un Overlay está dentro de la vista en la que está el overlay, se muestre donde se muestre, así que un popup cuenta como parte de la vista que contiene su disparador. En Rust, un componente detecta cuándo el foco entra en un elemento y sale de él con los on_focus_in(..) y on_focus_out(..) de su ref: moverse entre vistas dentro de él no es ninguna de las dos cosas.

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

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

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

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

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

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

#Layout e identidad

#Gestos que controlan valores animados

Estas props enlazan un gesto a valores animados nativos que se mueven en el hilo de la UI, sin trabajo en el código de la app en cada fotograma. Consulta toques y gestos.

PanEvent es { cancelled, translation, velocity, value? } (en Rust cancelled, translation, velocity_x, velocity_y, value_x, value_y): si el sistema canceló el arrastre, la traslación desde el inicio y la velocidad en puntos por segundo (Points), y los valores enlazados en ese momento, { x?, y? } para los ejes que enlaza pan (un arrastre puede tomar un valor en mitad de una animación).

#Toques sin procesar y el sistema responder

Para los gestos que las props anteriores no cubren, cada elemento acepta las props de toque y de responder: onTouchStart, onTouchMove, onTouchEnd, onTouchCancel (y sus formas …Capture), onStartShouldSetResponder, onMoveShouldSetResponder (y …Capture), onResponderGrant, onResponderReject, onResponderStart, onResponderMove, onResponderEnd, onResponderRelease, onResponderTerminate y onResponderTerminationRequest. Cada manejador recibe un GestureResponderEvent ({ identifier, locationX, locationY, pageX, pageY, target, timestamp, touches, changedTouches, nativeEvent, stopPropagation() }); the …ShouldSetResponder handlers also get a gestureState (dx, dy, vx, vy, …). Devolver true desde onResponderGrant impide que las scroll views nativas se queden con los toques. panActivation ({ activeOffsetX, activeOffsetY, failOffsetX, failOffsetY }) convierte a la vista en responder solo cuando la plataforma activa su pan, de modo que los arrastres dentro de scroll views dejan el otro eje a estas (Toques y gestos). PanResponder en PanResponder se construye sobre ellos. En Rust, .on_touch(..) recibe cada toque (TouchEvent), .claim_touches(..) decide cuándo la vista los toma, y .on_responder_grant(..), .on_responder_move(..), .on_responder_release(..) y los demás siguen al responder.

#Accesibilidad

Consulta accesibilidad.

#Props específicas de una plataforma

Las props que existen en una sola plataforma van en un objeto con su nombre en TSX, de modo que las props compartidas sean las mismas en todas partes. Solo se envía el objeto de la plataforma actual; los demás se ignoran. Los builders de Rust las aceptan como métodos que se aplican en su plataforma.

use nsh_core::Ripple;

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

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

Consulta código específico de plataforma.

#Métodos de ref

En TSX, ref recibe la ref del elemento, cuyo tipo es el propio del elemento: ViewRef (focus, blur, measure) para View, Text, Image, Canvas, Overlay y Shader, y un tipo sobre ViewRef con los métodos del elemento para los demás: InputRef (Input), ScrollRef (Scroll), ListRef (List), WebViewRef (WebView), VideoRef (Video) y NativeComponentRef (componentes nativos). En Rust, element_ref() crea un handle ElementRef que .element_ref(&handle) adjunta. Sus métodos envían comandos a la vista nativa, en orden con los cambios realizados antes de ellos en el mismo turno. La página de cada elemento indica cuáles le corresponden. Tipa una variable de ref con el tipo propio de su elemento (let field!: InputRef para un <Input>): una variable tipada como ViewRef no encaja con un elemento cuya ref tiene métodos propios.

let field = element_ref();

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

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

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

#Por qué los manejadores nunca bloquean la UI

El hilo principal nunca espera al código de la app. Cuando el sistema necesita una respuesta al instante (si puede cambiar este texto, si el botón de retroceso puede quitar la pantalla, si se puede cerrar esta hoja), NSH la responde de forma nativa a partir de props definidas de antemano (maxLength, popOnBack, closeOnSwipe, …), y el evento llega a la app después. Por eso ese comportamiento es una prop y no el valor de retorno de un manejador.