Éléments

Native Shell construit chaque écran à partir d’un petit ensemble d’éléments : des primitives comme View, Text et Image, et des composants de base comme Button, Dialog et NavStack. Chaque primitive est une vue native (une sous-classe de UIView sur iOS et Mac Catalyst, une View Android, une vue AppKit, GTK ou Win32 sur les ordinateurs de bureau), créée et disposée par le runtime NSH. Tout ce qu’une application affiche en est composé : les boutons, cartes, lignes et écrans d’une application sont ses propres composants, dessinés avec ces éléments et stylés par l’application, de sorte que son apparence lui appartient entièrement.

Chaque exemple de ces pages existe en Rust et en TSX : choisissez un onglet, et tous les exemples de la page suivent.

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, les primitives sont des fonctions de nsh_core::prelude (view(), text(..), image(..)) et les composants de base proviennent de la crate nsh_base. Les styles sont des méthodes typées (.flex_1(), .gap_3(), .px(px(20.0)), .bg(..)), les styles d’état prennent une closure (.active(|s| s.opacity(0.6))), les écouteurs sont des closures de leur événement (.on_press(move || ..), .on_change(move |text: &str| ..)) et .child(..) ajoute des enfants. Un morceau d’UI est une simple fonction qui retourne impl IntoElement ; elle s’exécute une seule fois, et les signaux qu’elle lit dans des closures (text(move || ..), .bg(move || ..)) mettent à jour ce à quoi ils sont liés. Voir Créer avec Rust.

En TSX, chaque balise est en PascalCase et désigne une liaison présente dans la portée : les primitives viennent de nsh, les composants de base de nsh/base. Seuls <If> et <Each> sont des globaux qui ne demandent aucun import. Une balise en minuscules telle que <view> est une erreur de build, car TypeScript la vérifierait par rapport à un type global unique par nom, et les composants génériques comme List et Each ne pourraient pas inférer le type de leurs éléments. Le compilateur reconnaît les éléments grâce à leurs imports et crée les vues natives sur place, de sorte que les importer ne coûte rien à l’exécution. Voir JSX et composants.

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

#Primitives

Importées depuis nsh en TSX, depuis nsh_core::prelude en Rust.

Le padding et la marge tiennent le contenu à l’écart de l’UI système grâce à env() de CSS : env(safe-area-inset-top) et les autres bords (Safe area) et env(keyboard-inset-height) (Clavier).

#Base

Importés depuis nsh/base en TSX, depuis la crate nsh_base en Rust. Ils gèrent le comportement, l’état, le focus et l’accessibilité, et tirent leur apparence de l’application.

#Props communes

Chaque primitive accepte les props ci-dessous (le type CommonProps en TSX ; les traits Styled, Interactive et Accessible en Rust). Les pages des éléments ne listent que leurs propres props. La colonne Rust indique le nom de la méthode du builder.

#Style

#Pressions et retour visuel

La gestion des pressions s’exécute nativement : la plateforme reconnaît la pression et applique les styles de pression de l’application, et le code de l’application ne l’apprend qu’ensuite. Seule la vue pressable la plus interne répond ; à l’intérieur des scroll views, un press-in attend environ 130 ms afin qu’un défilement puisse démarrer en premier.

PressEvent est { position, pagePosition, modifiers, clickCount } : l’endroit où se trouvait le pointeur dans la vue et dans sa vue racine (Points), les touches de modification maintenues au début de la pression et les clics consécutifs (2 pour un double clic). Lorsque la plateforme ne signale aucun pointeur, c’est l’origine de la vue, sans touches et avec un seul clic.

La clé de style pointerEvents (.pointer_events(PointerEvents::BoxNone) en Rust, les classes pointer-events-*) détermine quels touchers la vue et les vues qu’elle contient reçoivent : "none" aucune des deux (une vue à l’intérieur qui définit "auto" les reçoit de nouveau), "box-none" seulement les vues qu’elle contient, "box-only" seulement la vue elle-même (toucher et gestes).

Le retour visuel de pression est celui de l’application : activeStyle (ou les classes active:, .active(..) en Rust) s’applique tant que la vue est pressée, nativement, sans aller-retour avec le code de l’application (voir ci-dessous).

#Styles d’état

Des styles qui s’appliquent tant que la vue est dans un état, par-dessus ses propres styles, nativement. Chacun est la forme objet d’une variante Tailwind. Les derniers états l’emportent (selected, checked et indeterminate, puis hover, focus, active) ; disabledStyle l’emporte sur tous, et les autres ne s’appliquent pas tant que la vue est désactivée. Chacun prend le style propre à l’élément : un TextStyle sur un <Text>, un InputStyle sur un <Input>, un ImageStyle sur un <Image>, un ViewStyle ailleurs.

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>

#Survol

L’app détecte l’arrivée de la souris sur une vue, son déplacement au-dessus d’elle et sa sortie : sur macOS, Windows, Linux, le backend GPUI et dans les navigateurs de bureau, avec le pointeur d’un iPad ou la souris d’un Mac sous iOS, et avec une souris ou un stylet sous Android. Les styles de survol (hover:, .hover(..)) stylent les vues survolées aux mêmes endroits.

Comme le :hover de CSS et le mouseenter du DOM, une vue est considérée comme survolée tant que la souris est sur elle ou sur n’importe quelle vue à l’intérieur : les vues qui entourent celle située sous la souris reçoivent donc aussi onMouseEnter (de l’extérieur vers l’intérieur ; onMouseLeave de l’intérieur vers l’extérieur). Les événements arrivent après coup et jamais pour les touchers. Une vue retirée de sous la souris reçoit onMouseLeave, sous Linux et Windows au prochain mouvement de la souris.

MouseEvent indique où se trouve la souris, comme le MouseMoveEvent de GPUI : position dans la vue (un Point en points, ses transformations annulées), pagePosition dans la vue racine où elle se trouve, comme le fournissent les touchers, les modifiers maintenues (control, alt, shift, platform : Command sur les plateformes Apple, la touche Windows ailleurs), et pressedButton, le bouton maintenu enfoncé ("left", "right", "middle", "back" ou "forward", le MouseButton de GPUI) ou null ; en Rust position, page_position, modifiers et pressed_button. Sur les ordinateurs de bureau et le web, un glissement est aussi un toucher (onTouchMove, le responder), et ses mouvements parviennent à onMouseMove avec pressedButton activé : un retour visuel qui ne suit que le survol les ignore ; sous iOS et Android, le survol signale le pointeur sans bouton enfoncé. Les mouvements arrivent au plus une fois par image, le dernier seulement, et toujours avant le onMouseLeave qui les suit, de sorte qu’un gestionnaire peut redessiner à chaque mouvement :

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

#Infobulles

tooltip donne un indice à n’importe quel élément, affiché au-dessus de lui sur les ordinateurs de bureau (macOS, Windows, Linux, le backend GPUI et les navigateurs de bureau) une fois que le pointeur est resté une demi-seconde dessus, jusqu’à ce que le pointeur parte ou appuie dessus. Les téléphones et les tablettes n’en affichent aucune. L’indice ne capte jamais le pointeur ni les appuis : l’élément fonctionne exactement comme sans lui.

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>

Le Tooltip définit lui-même son apparence, son placement, son délai et ses événements, comme le .tooltip(..) de GPUI en reçoit un. Une app qui a beaucoup d’infobulles garde un petit composant à elle qui enveloppe un texte dans son Tooltip.

#Menus contextuels

onContextMenu indique à une vue que le bouton secondaire a été pressé sur elle : un clic droit, un Control-clic sur macOS, un clic à deux doigts sur un pavé tactile, le clic secondaire du pointeur d’un iPad ; dans les navigateurs, aussi la touche menu du clavier. Ouvrez-y le menu propre à l’app ; en TSX, Menu.popup affiche celui du système :

// 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 contient position dans la vue, pagePosition dans sa vue racine (là où Menu.popup place un menu : Menu.popup(items, e.pagePosition)) et les modifiers ; en Rust position, page_position et modifiers. La vue la plus proche qui écoute, depuis celle située sous le pointeur vers l’extérieur, le reçoit. Un champ de saisie, ou un texte sélectionnable avec un menu d’édition (Windows, le backend GPUI, les navigateurs), plus proche que cette vue affiche à la place son propre menu. La plateforme en décide au moment où le bouton est enfoncé, d’après ce qui est monté : le gestionnaire est donc informé après coup et rien n’a à être annulé. Une vue disabled laisse le clic au plus proche écouteur activé qui l’entoure. Sur les écrans tactiles, un appui long ouvre les menus : gérez onLongPress avec la même fonction.

#Focus clavier

Sur macOS et le web, Tab déplace le focus clavier entre ses arrêts dans l’ordre de l’arbre : les champs de saisie, les vues qui prennent les appuis, et chaque vue focusable. Les styles de focus (focus:, .focus(..)) stylent la vue qui a le focus, et Retour ou Espace l’actionne lorsqu’elle prend les appuis. Un clic appuie sur une vue sans lui donner le focus, de sorte que les styles de focus ne s’affichent que pour le focus clavier.

Le focus et les appuis sont distincts. Une vue qui prend les touches tant qu’elle a le focus (un graphique, un curseur, une liste qui déplace sa sélection avec les flèches) définit focusable et lie ses touches pendant qu’elle a le focus (onFocus / onBlur avec keymap) ; un appui sur elle atteint tout de même un élément pressable qui l’entoure, comme une carte qui ouvre une page.

Le focus() d’une ref déplace le focus clavier vers un arrêt comme le fait Tab (ses styles de focus s’affichent et onFocus se déclenche), par exemple pour le rendre au déclencheur d’une popup qui s’est fermée, et blur() le retire.

Une vue qui entoure le focus se stylise avec focus-within: (focusWithinStyle, .focus_within(..)) tant que le focus est sur elle ou sur n’importe quelle vue à l’intérieur : le cadre d’un champ autour de l’entrée qui édite, une barre d’outils pendant que l’un de ses boutons a le focus. Le contenu d’un Overlay est à l’intérieur de la vue dans laquelle se trouve la superposition, où qu’il s’affiche : une popup compte donc comme faisant partie de la vue qui contient son déclencheur. En Rust, un composant détecte l’arrivée du focus dans un élément et sa sortie avec les on_focus_in(..) et on_focus_out(..) de sa ref : passer d’une vue à une autre à l’intérieur n’est ni l’un ni l’autre.

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>

#Mise en page et identité

#Gestes pilotant des valeurs animées

Ces props lient un geste à des valeurs animées natives qui évoluent sur le thread d’interface, sans aucun travail dans le code de l’app à chaque image. Voir toucher et gestes.

PanEvent est { cancelled, translation, velocity, value? } (en Rust cancelled, translation, velocity_x, velocity_y, value_x, value_y) : indique si le système a annulé le glissement, la translation depuis le début et la vitesse en points par seconde (Points), ainsi que les valeurs liées à cet instant, { x?, y? } pour les axes que pan lie (un glissement peut saisir une valeur en cours d’animation).

#Touchers bruts et système de responder

Pour les gestes que les props ci-dessus ne couvrent pas, chaque élément accepte les props de toucher et de responder : onTouchStart, onTouchMove, onTouchEnd, onTouchCancel (et leurs formes …Capture), onStartShouldSetResponder, onMoveShouldSetResponder (et …Capture), onResponderGrant, onResponderReject, onResponderStart, onResponderMove, onResponderEnd, onResponderRelease, onResponderTerminate et onResponderTerminationRequest. Chaque gestionnaire reçoit un GestureResponderEvent ({ identifier, locationX, locationY, pageX, pageY, target, timestamp, touches, changedTouches, nativeEvent, stopPropagation() }); the …ShouldSetResponder handlers also get a gestureState (dx, dy, vx, vy, …). Renvoyer true depuis onResponderGrant empêche les vues de défilement natives de prendre les touchers. panActivation ({ activeOffsetX, activeOffsetY, failOffsetX, failOffsetY }) ne fait de la vue le responder qu’une fois que la plateforme a activé son panoramique, de sorte que les glissements à l’intérieur des vues de défilement laissent l’autre axe à celles-ci (Toucher et gestes). PanResponder dans PanResponder s’appuie sur eux. En Rust, .on_touch(..) reçoit chaque toucher (TouchEvent), .claim_touches(..) décide quand la vue les prend, et .on_responder_grant(..), .on_responder_move(..), .on_responder_release(..) et les autres suivent le responder.

#Accessibilité

Voir accessibilité.

#Props propres à une plateforme

Les props qui n’existent que sur une plateforme vont dans un objet portant son nom en TSX, de sorte que les props partagées restent les mêmes partout. Seul l’objet de la plateforme courante est envoyé ; les autres sont ignorés. Les builders Rust les reçoivent sous forme de méthodes qui s’appliquent sur leur plateforme.

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>

Voir code spécifique à une plateforme.

#Méthodes de ref

En TSX, ref reçoit la ref de l’élément, dont le type est propre à l’élément : ViewRef (focus, blur, measure) pour View, Text, Image, Canvas, Overlay et Shader, et un type construit sur ViewRef avec les méthodes de l’élément pour les autres : InputRef (Input), ScrollRef (Scroll), ListRef (List), WebViewRef (WebView), VideoRef (Video) et NativeComponentRef (composants natifs). En Rust, element_ref() crée un handle ElementRef que .element_ref(&handle) attache. Leurs méthodes envoient des commandes à la vue native, dans l’ordre avec les changements effectués avant elles au cours du même tour. Chaque page d’élément indique celles qui s’y appliquent. Typez une variable de ref avec le type propre à son élément (let field!: InputRef pour un <Input>) : une variable typée ViewRef ne convient pas à un élément dont la ref possède ses propres méthodes.

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

#Pourquoi les handlers ne bloquent jamais l’UI

Le thread principal n’attend jamais le code de l’app. Lorsque le système a besoin d’une réponse immédiate (ce texte peut-il changer, le bouton retour peut-il dépiler, cette sheet peut-elle se fermer), NSH y répond nativement à partir de props définies au préalable (maxLength, popOnBack, closeOnSwipe, …), et l’événement parvient à l’app ensuite. C’est pourquoi un tel comportement est une prop, et non la valeur de retour d’un handler.