# Native Shell

> Native Shell is a Rust-first native UI framework: build one app for iOS, Android, macOS, Windows, Linux and the web, with each platform’s own UI and interaction.

Apps are written in Rust (compiled to native code) or TSX (run by QuickJS, and by the browser's JavaScript engine on the web), or both, on one native Rust runtime; the toolchain is the single `nsh` binary (`nsh init my-app --template rust|ts`, `nsh run my-app`, `nsh package my-app --target <target>`). Every page below is also served as Markdown at its URL plus `.md`.

---

# Introduction

Native Shell (NSH for short) is a native UI framework for every platform. You build an app once, with one app model — components, signals, styles and the same API everywhere — and NSH runs it on **iOS, Android, macOS, Windows, Linux and the web**, each time as an app of that platform: made of its own views, edited with its own text system, used the way its users expect. Write the whole app in **Rust**, write screens in **TSX**, or combine both on one engine. On top of the same engine, apps you have shipped can take new UI at run time — written by your team or generated by a model — as signed modules, in a sandbox the host configures.

> [!IMPORTANT]
> NSH provides native views and interaction; the app owns its visual design. Components, state and APIs are shared across platforms, while colors, typography, spacing and shapes come from the app. Text input, focus and menus follow each device’s interaction conventions. See [Goals and design principles](https://nsh.dev/versions/main/docs/goals.md).

## What native means

Native in NSH has two layers: the platform's foundations, and the platform's interaction.

**The platform's foundations.** Each platform has a backend of its own, built on the UI that platform already has:

| Platform | Views | Text | Text input |
|---|---|---|---|
| iOS | UIKit | CoreText | The system's text fields and text views |
| Android | Android views | `StaticLayout` | `EditText` |
| macOS | AppKit, Core Animation | CoreText | `NSTextField`, `NSTextView` |
| Windows | Win32 windows drawn with Direct2D | DirectWrite | NSH's editor, with the system's input methods (IMM32) |
| Linux | GTK 4 | Pango | GTK's `Text` and `TextView` |
| Web | HTML elements styled with CSS | The browser's fonts | The browser's inputs |

Text selection and its menu, input methods, accessibility and scrolling come from the platform, and what a new OS release brings to them reaches the app with it. Native components — a map, a web view, a video player, any view the host registers — are one more view in the same hierarchy, laid out, clipped and scrolled with the rest ([Native components](https://nsh.dev/versions/main/docs/native-components.md)).

**The platform's interaction.** The components NSH provides in [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md) behave as each device's users expect, so the app writes them once:

| | Desktops (and desktop browsers) | Phones and tablets |
|---|---|---|
| `Menu` | A popup at its trigger; submenus cascade beside their item | A sheet from the bottom; a submenu replaces its menu's items |
| `ContextMenu` | A right click opens it at the pointer | A finger held on the trigger opens it as a sheet |
| `Tooltip` | Shown when the pointer rests on the trigger | Shown when the app opens it |
| `Popover` | A press outside closes it and reaches what is under the pointer | A press outside closes it |

Pages, dialogs, the keyboard and the status bar follow the same idea: navigation stacks push and pop with each platform's motion, and the back button, Escape and swipe-back do what they do there ([Navigation](https://nsh.dev/versions/main/docs/navigation.md)).

## From phone to desktop to web

Cross-platform in NSH means each device gets the app it expects, not the same screen scaled up or down:

- **One app model.** The app's components, state, business logic and screens are shared; each backend maps them to its platform.
- **Layouts that reshape.** Flexbox and CSS grid are laid out by [Taffy](https://github.com/DioxusLabs/taffy) on every platform, and Tailwind's breakpoints (`md:`, `lg:`) and the window's size (`window()` in Rust) change the structure, not only the size: a chat app shows its sidebar, conversations and messages side by side in a wide window, and one screen at a time on a phone ([Layout](https://nsh.dev/versions/main/docs/layout.md), [Tailwind](https://nsh.dev/versions/main/docs/tailwind.md)).
- **The input each device expects.** A pointer, hover, right clicks, shortcuts and focus on the desktop; touches, gestures, the software keyboard and page navigation on phones. Where an app wants something of its own per platform, `desktop={{…}}` props and `platform.select` say so ([Platform-specific code](https://nsh.dev/versions/main/docs/platform-specific.md)).
- **Checked on every target.** `nsh test` runs the app's tests headless, and the same tests in macOS, Windows, Linux and GPUI windows, an iOS simulator, an Android device or a browser, with the platform's own input ([Testing and tracing](https://nsh.dev/versions/main/docs/testing-and-trace.md)).

Take an app like a chat client. Its developer builds it on the desktop with `nsh run`, opens it in an iOS simulator with `nsh run --target ios` to check the phone layout, then in a browser with `nsh run --target web` — the same project each time — and `nsh package` makes the installable apps and the website. One engineer can carry what used to take a team per platform, while the backend is built alongside.

## Rust first

NSH is built in Rust, and Rust is a first-class language for writing apps with it:

- **Whole apps in Rust.** UI, logic and components are Rust, compiled to native code on every platform, with Rust's ownership, types, threads and the crates.io ecosystem. Computation runs at native speed, and large data, parsing and system work stay in the language best suited to them ([Building with Rust](https://nsh.dev/versions/main/docs/rust.md)).
- **TSX as the second path.** TSX suits screens written quickly, plugins, small apps and UI delivered at run time. It runs on the same engine as Rust, with the same primitives, base components and signals.
- **Both together.** A Rust app can take TSX screens, and TSX screens import the app's Rust components, modules and classes.
- **One toolchain.** A single `nsh` executable creates, builds, type-checks, runs with hot reload, tests, packages and signs apps for every target. It brings its own TSX bundler and TypeScript checker, so a developer coming from Rust, Swift, Kotlin or C++ installs Rust and `nsh`, and works ([Installation](https://nsh.dev/versions/main/docs/installation.md), [CLI](https://nsh.dev/versions/main/docs/cli.md)).

## An app

The same counter, in Rust and in TSX:

```rust
use nsh_core::prelude::*;

#[component]
pub fn Counter() -> impl IntoElement {
    let count = signal(0);
    view()
        .flex_1()
        .items_center()
        .justify_center()
        .gap_3()
        .child(text(move || count.get().to_string()).text_5xl().font_weight(FontWeight::BOLD))
        .child(
            view()
                .rounded_lg()
                .bg(rgb(0x2563eb))
                .px_5()
                .py_3()
                .active(|s| s.opacity(0.6))
                .on_press(move || count.update(|n| *n += 1))
                .child(text("Tap").text_lg().text_color(white())),
        )
}
```

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

function Counter() {
  const count = signal(0);
  return (
    <View style={{ flex: 1, alignItems: "center", justifyContent: "center", gap: 12 }}>
      <Text style={{ fontSize: 48, fontWeight: "700" }}>{count()}</Text>
      <View
        onPress={() => count.update((n) => n + 1)}
        activeStyle={{ opacity: 0.6 }}
        class="rounded-lg bg-blue-600 px-5 py-3"
      >
        <Text class="text-white text-lg">Tap</Text>
      </View>
    </View>
  );
}

mount(Counter);
```

A view (`view()`, `<View>`) becomes a `UIView` on iOS, a `ViewGroup` on Android, an `NSView` on macOS, a GTK widget on Linux, a retained view drawn with Direct2D on Windows and an HTML element on the web; a text becomes a native text view, and the button's press feedback (`.active(..)`, `activeStyle`) runs on the main thread. When you tap, `count.update` changes one signal, and only the text that reads it is updated: the component function does not run again. The Rust app is native code from start to end; in the TSX app, only the module's own code is JavaScript.

## Retained views

NSH is retained: every element is a view the platform keeps, and an update changes only what changed.

- **Fine-grained updates.** [Signals](https://nsh.dev/versions/main/docs/reactivity.md) like Solid's, implemented natively: components run once, and a change runs again only the expressions that read the changed signal.
- **Only what changed crosses threads.** The changes of one turn are laid out together and handed to the main thread as one batch of view operations per frame; unchanged styles and frames are not sent, and the views nothing touched stay as they are.
- **Animations run natively.** Timing, spring and decay animations, gestures and scroll-linked values are evaluated on the platform's frame clock, without calling into JS per frame ([Animation](https://nsh.dev/versions/main/docs/animation.md)).

That suits the screens most apps are made of — chats, mail, forms, lists, documents, settings, an AI reply streaming in — where a few views change at a time and the rest wait. Such screens sit near idle between updates, and scrolling and animation hold 120 FPS on ProMotion displays. In the [NSH performance benchmark](https://github.com/longbridge/nsh-perf-bench), a 500-row quote table updated 1,000 times a second uses 18% of a core on Linux in NSH Rust, against 20% for the same screen written directly on [GPUI Fast](https://github.com/longbridge/gpui-fast). Heavy computation belongs in Rust: TSX runs in QuickJS, an interpreter, while a Rust module runs at native speed even when TSX calls it — sorting 100,000 rows takes about 3 ms that way, as in plain Rust ([Performance](https://nsh.dev/versions/main/docs/performance.md)).

## How it runs

The toolchain is a single `nsh` binary. An app is written in Rust, in TSX, or both, and each takes its own path to the same Rust engine.

### Rust apps

A Rust app is a crate, built entirely with Rust and Native, with no JavaScript runtime:

1. **Build.** `nsh` builds the runner of each target — the iOS, Android, macOS, Windows, Linux or web app — with your crate linked in. Components, state, handlers and the engine are compiled together into native code.
2. **Run.** The app's root component runs on the engine thread as Rust. The runner has no JavaScript engine: QuickJS is not part of a Rust app on any platform.

### TSX apps

A TSX app (a module) is a set of `.tsx` / `.ts` files with an entry, usually `App.tsx`:

1. **Build.** `nsh` bundles the module's files (with rolldown and Oxc) and compiles the JSX with its own compiler. Imports of `nsh` and `nsh/*` stay imports: the runtime serves them natively, so the bundle holds only your code. The bundle is compiled to QuickJS bytecode.
2. **Run.** The engine thread runs the bytecode in [QuickJS](https://github.com/quickjs-ng/quickjs), one VM per view. Compiled JSX calls the native renderer directly, and JavaScript only describes the UI and handles events; parsing styles, resolving Tailwind classes, diffing, layout and text all happen in Rust.

### The difference

| | Rust app | TSX app |
|---|---|---|
| Written in | Rust | TSX (TypeScript and JSX) |
| Built into | Native code, linked into each target's runner | QuickJS bytecode, loaded by the runtime |
| JavaScript engine | None | QuickJS, one VM per view |
| While developing (`nsh run`) | Rebuilt and restarted on each save | Hot updates on each save |
| After release | Ships with the app | Also delivered at run time as signed packages, in a sandbox |
| Suits | Whole apps, heavy computation, system work | Screens written quickly, plugins, AI-generated UI |

The two combine: a Rust app can take TSX screens, and TSX screens import its Rust components, modules and classes; such an app links QuickJS to run them ([Building with Rust](https://nsh.dev/versions/main/docs/rust.md)).

### The shared engine

From the engine on, both paths are the same. Changes are collected per turn, laid out with Taffy (flexbox and CSS grid), and handed to the main thread as one batch of view operations per frame; the main thread applies the batch to native views. Text is measured and laid out once on the engine thread (CoreText on Apple platforms, `StaticLayout` on Android, DirectWrite on Windows, Pango on Linux, the browser's font metrics on the web) and only drawn on the main thread.

On the web, the same engine runs in the page: the browser shows HTML elements styled with CSS, scrolls them, selects their text and handles input, and `nsh package --target web` publishes the app as a static site whose files are named by content, ready for any CDN ([Web](https://nsh.dev/versions/main/docs/web.md)).

> [!NOTE]
> The main thread never waits for the app's code. Questions the system asks synchronously (may this input accept another character, may the user swipe back, may this sheet close) are answered natively from props set beforehand, such as `maxLength`, `popOnBack` or `closeOnSwipe`. Events reach the app's handlers afterwards.

## Dynamic UI and AI-generated UI

NSH began as a way for native apps to take UI after release, and that stays one of its main uses. An app embeds an `NshAppView` (iOS), `NshView` (Android), `AppView` (macOS, Windows, Linux and GPUI apps) or `createPlayer` (a web page) wherever a module should appear, and NSH runs TSX modules inside it:

- **Delivered after release.** A module is a signed package (`.nshpkg`) the app downloads at run time. The app checks its signature against the keys it trusts and against a revocation list before running it ([Signed packages](https://nsh.dev/versions/main/docs/signed-packages.md)). The host app ships the runtime; teams build modules against its API and deliver them on their own schedule.
- **The host stays in control.** Each module runs in its own QuickJS VM, with memory, call-time and node limits, and reaches only what the host grants: network hosts, web pages, the status bar ([Sandbox and capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md)). Several modules run side by side.
- **It looks like the rest of the app.** Modules render with the platform's own UI, and the host can register its own native views — a map, a player, a design-system component — for modules to use ([Native components](https://nsh.dev/versions/main/docs/native-components.md)).

The same mechanism lets an app **answer with an interface**. A model writes a small TSX module (a form, a chart, a booking card), your server checks, builds and signs it, and the app shows it natively:

![From a prompt to native UI: a model writes a TSX module; your server builds, checks and signs it; across the trust boundary, the app verifies the package, runs it in a sandbox with the limits and capabilities it set, and shows it with the platform's own UI.](https://nsh.dev/versions/main/diagrams/ai-flow-light.svg)

On iOS, the host's part is a few lines:

```swift
let app = NshAppView()                         // a UIView: place it anywhere
try app.grantCapabilities(#"{ "network": { "hosts": ["api.example.com"] } }"#)
let info = try await app.loadPackage(at: downloadedFile, trust: trust)   // verified, then run
```

## AI-friendly

NSH is designed for software written with AI, whole apps as much as generated screens:

- **One app model for every platform.** A model learns one way to write UI, and the result runs on phones, desktops and the web; NSH adapts the interaction per platform, so nothing is generated six times.
- **Rust or TSX, by task.** Rust for whole apps and performance-critical modules, TSX for screens, plugins and UI generated per request — on one engine.
- **A precise, generated contract.** Every element, prop, style key and module has TypeScript declarations generated from the Rust sources (`.nsh/types`), and Rust APIs are typed, so generated code is checked by a compiler. These docs are served as plain text for models ([`llms.txt`](/llms.txt), [`llms-full.txt`](/llms-full.txt)).
- **One command line for the whole loop.** An agent creates the app, builds it, runs it on a target, runs its tests, reads the result, fixes and packages it, all through `nsh`. `nsh test` runs headless, without a device, and reports errors and the views produced; the compiler also runs in-process (`nsh_bundler::compile_module`) and in the browser ([Playground](/playground)).
- **Safe to run when it is not trusted.** Generated code delivered at run time is untrusted code: it arrives signed, runs in a VM with limits and reaches only the capabilities the host grants.

## Where it runs

| Platform | Requires | Backend | Embedded with |
|---|---|---|---|
| [iOS](https://nsh.dev/versions/main/docs/ios.md) | iOS 15.0+ | UIKit | `NativeShell.xcframework` |
| [Android](https://nsh.dev/versions/main/docs/android.md) | Android 9+ | Android views | `nsh.aar` |
| [macOS](https://nsh.dev/versions/main/docs/macos.md) | macOS 14+ | AppKit | `AppView` |
| [Windows](https://nsh.dev/versions/main/docs/windows.md) | Windows 10 1809+ | Win32, Direct2D | `AppView` |
| [Linux](https://nsh.dev/versions/main/docs/linux.md) | GTK 4.14+ | GTK 4 | `AppView` |
| [Web](https://nsh.dev/versions/main/docs/web.md) | Modern browsers | HTML | `createPlayer`, iframe |
| [GPUI](https://nsh.dev/versions/main/docs/gpui.md) | Desktops | GPUI | `AppView` (GPUI, GPUI Kit apps) |
| Mac Catalyst | macOS | UIKit | For development (`--target catalyst`) |

![One module, many hosts: the same bundle and Rust runtime on iOS, Android, Linux, macOS with AppKit and Windows with Win32 / Direct2D, GPUI on all three desktops, and web pages drawn with HTML.](https://nsh.dev/versions/main/diagrams/platforms-light.svg)

## Native Shell and GPUI Shell

[Longbridge](https://longbridge.com) builds NSH for its own clients. The first need was a plugin layer for the mobile client, and [GPUI Shell](https://gpui-kit.com/shell), which makes [GPUI](https://gpui-kit.com) desktop apps extensible in JavaScript, was the starting point. On phones, UI drawn by GPUI itself would have had to rebuild what the platform already does — text selection and its menu (Copy, Share, Translate, Look Up), input methods, accessibility, the visual materials each iOS release brings — and every mobile team would have taken on a new UI stack. NSH therefore renders with each platform's own UI, and it grew from that plugin layer into a framework for whole apps on every platform.

The two are positioned differently. GPUI Shell extends GPUI desktop applications; Native Shell is a framework for native apps on phones, desktops and the web, and its GPUI backend embeds NSH apps in GPUI and GPUI Kit apps ([GPUI](https://nsh.dev/versions/main/docs/gpui.md)).

## How it compares

For whole apps, NSH sits among cross-platform frameworks such as React Native, Flutter, Qt, GPUI, Slint, Electron and Tauri; for UI delivered after release, among web views, server-driven UI and mini-program containers. Its choice is each platform's own UI and interaction under one app model, with Rust as the app language and TSX beside it. [Comparing approaches](https://nsh.dev/versions/main/docs/comparison.md) goes through each.

## Next steps

- [Installation](https://nsh.dev/versions/main/docs/installation.md) and [Getting started](https://nsh.dev/versions/main/docs/getting-started.md): get `nsh`, write a first app in Rust or TSX and run it on each platform.
- [Building with Rust](https://nsh.dev/versions/main/docs/rust.md): apps written in Rust, and TSX on top of them.
- [Platforms](https://nsh.dev/versions/main/docs/platforms.md): what runs where, and how to run, package and embed on each platform.
- [JSX and components](https://nsh.dev/versions/main/docs/jsx-and-components.md) and [Reactivity](https://nsh.dev/versions/main/docs/reactivity.md): the two ideas everything else builds on, in Rust and TSX.
- [Signed packages](https://nsh.dev/versions/main/docs/signed-packages.md) and [Sandbox and capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md): deliver modules and decide what they may do.

Source: https://nsh.dev/versions/main/docs

---

# Goals and design principles

Native Shell provides native views and interaction across iOS, Android, macOS, Windows, Linux and the web. The app owns its visual design. One component model serves whole apps, embedded features and dynamically delivered UI.

## Native foundations, app-owned design

NSH builds on each platform's views, text and input infrastructure, and adapts interaction to the device: keyboard navigation, pointer and touch input, text editing, scrolling and accessibility ([Introduction](https://nsh.dev/versions/main/docs.md#what-native-means)).

The app defines colors, typography, spacing, shapes, state feedback and animation. A settings screen can follow the app's brand on iOS and Android while input and navigation follow each device's conventions. Designers refine that visual language through styles and component parts.

A native view is the rendering foundation. A system-styled control is a particular visual and behavioral choice. NSH's common controls expose shared behavior and customizable parts so applications can build their own design systems.

## Native integration in practice

The native foundation includes rendering, frame-driven animation, input and accessibility semantics. On iOS and Android, [Input](https://nsh.dev/versions/main/elements/input.md) uses platform text fields: the platform handles editing, selection menus, input methods and supported autofill services. The app describes the field through `autoComplete`, for example `current-password` or `postal-code`, and the system provides the available suggestions according to its settings and services ([Forms and keyboard](https://nsh.dev/versions/main/docs/forms-and-keyboard.md)). Styling the field is compatible with keeping this system integration.

This is an architectural distinction from drawing a text field entirely within a custom renderer: a custom renderer supplies its own integration with system editing and accessibility services, while NSH uses platform text controls where its backend provides them. Each backend's documentation defines its integration, including NSH's own editor on Windows and the GPUI embedding backend ([Platforms](https://nsh.dev/versions/main/docs/platforms.md)).

[GPUI Kit](https://gpui-kit.com)'s separation of component behavior from visual design informs NSH's layers. NSH builds on that principle with platform view and input infrastructure. Native integration and app-owned design work together throughout this model.

## One component model across platforms

A switch means the same thing on a phone, a desktop and the web. [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md) provides state, input handling, focus and accessibility; the app styles the [Switch](https://nsh.dev/versions/main/elements/switch.md)'s track, thumb and states. Buttons, checkboxes and radios follow the same principle.

| Responsibility | Home | Example |
|---|---|---|
| Rendering, layout, reactivity and environment | `nsh-core`, `nsh` and runtime modules | Views, text, signals, styles |
| Shared behavior and accessible structure | `nsh-base`, imported as `nsh/base` in TSX | `Button`, `Checkbox`, `Switch`, `Tabs` |
| Visual design and styled components | The app or a community library | Branded controls, cards, form rows |
| Platform-specific capabilities | `nsh/mobile`, `nsh/desktop` | Mobile navigation bar, desktop window controls |

Common controls have one cross-platform home in `nsh/base`. Platform modules are scoped by purpose and platform semantics. [`TabBar`](https://nsh.dev/versions/main/modules/nsh-mobile.md#tabbar) serves mobile top-level navigation; [`Tabs`](https://nsh.dev/versions/main/elements/tabs.md) switches tabbed content across platforms. Their roles are distinct. `nsh/mobile` accepts capabilities with mobile-specific interaction semantics; differences in a common control’s appearance, size, tint or animation belong within its shared component and app styling. A notification or toast with a shared role should first be designed around one cross-platform contract, with presentation adapted internally.

A shared component can adapt its interaction internally: a menu opens as a popup on a desktop and a sheet on a phone, while the app uses one API and supplies its appearance. System-managed presentations such as navigation headers and alerts follow their documented platform presentation rules. Apps can expose their own native components and services through the [embedding interfaces](https://nsh.dev/versions/main/docs/native-components.md).

## The unstyled foundation and the component-library layer

NSH owns the primitives and the unstyled foundation (`nsh-core` and `nsh-base`). Applications and third-party libraries own the styled component-library layer — the role `gpui-component` plays in [GPUI Kit](https://gpui-kit.com). This division gives each product control over its visual language while reusing the difficult parts of component implementation.

The experience behind this choice comes from [GPUI Kit](https://gpui-kit.com). Its styled components grew from work on Longbridge Pro. As applications needed increasingly different designs, customization pressure led users to fork components. Extracting the shared foundation into `gpui-base` made behavior reusable across those designs. Styled components remain useful as a design reference and for applications whose needs fit their customization surface; the foundation gives other applications direct control over presentation.

NSH applies this lesson from the start. `nsh/base` owns complex behavior, interaction, reactive state, focus, accessibility and adaptive presentation, with tests at the layer that owns each behavior. This includes larger structures such as [Dock](https://nsh.dev/versions/main/elements/dock.md). Applications build diverse designs on that foundation through styles, states, slots and parts. Component contributions follow the same boundary: visual defaults and branded variants belong to application or third-party components. The documented system-managed presentations and `TextView` reading defaults retain their specific contracts ([Architecture](https://nsh.dev/versions/main/docs/architecture.md#three-layers)).

### What the Gallery demonstrates

The website demos and Gallery are styled example applications. Their gradients, shadows, rounded corners, transitions and motion exercise NSH's customization capabilities and provide source examples. Those choices belong to the demos and Gallery; the reusable base components expose the behavior and parts underneath them. Applications can borrow the examples or build a different visual language.

An independently distributed styled library would belong to the application/community layer described above. Gallery styling illustrates one design direction; suitability for a particular product is a design decision for that product.

## Rust and TSX on one engine

Rust apps, TSX screens and mixed projects share primitives, base components, signals and layout. Rust provides compiled application logic and reusable native components. TSX supports rapid iteration and modules delivered at run time ([Building with Rust](https://nsh.dev/versions/main/docs/rust.md)).

The engine updates bindings that depend on changed signals and batches view operations. Text layout, native animations and input belong to the engine and its platform backends ([Architecture](https://nsh.dev/versions/main/docs/architecture.md)). Performance is evaluated with reproducible application workloads ([Performance](https://nsh.dev/versions/main/docs/performance.md)).

## Embedding, dynamic delivery and AI

An existing native app places an NSH view where a feature belongs and exposes its own native components and host services. Standalone apps use the same runtime and component model ([Platforms](https://nsh.dev/versions/main/docs/platforms.md)).

Dynamically delivered TSX modules own their state, logic and layout. Signed packages establish which publishers the host trusts; sandbox limits and capabilities define what modules may do. The host chooses both trust and permissions ([Signed packages](https://nsh.dev/versions/main/docs/signed-packages.md), [Sandbox and capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md)).

AI-generated UI follows that contract: generate TSX against declared APIs, check and test it, build and sign the module, then verify and run it under host policy. Generated declarations, model-readable documentation and CLI tests make the workflow inspectable and repeatable ([Testing and tracing](https://nsh.dev/versions/main/docs/testing-and-trace.md)).

## How these goals guide additions

1. Establish the user behavior and whether it is shared across platforms.
2. Put shared behavior in the existing primitive or base component, exposing state and parts for app customization.
3. Put capabilities with platform-specific semantics in their platform module, documenting applicability and composition with shared UI.
4. Build styled components in the app or community library.
5. Verify behavior, accessibility, layout and input on affected platforms, and document the public contract in both languages.

These principles keep visual design flexible, shared component APIs coherent and platform integration explicit as NSH grows.

Source: https://nsh.dev/versions/main/docs/goals

---

# Comparing approaches

NSH is a framework for whole apps on iOS, Android, macOS, Windows, Linux and the web, and a runtime for UI delivered to apps after release. This page compares it first with the cross-platform frameworks people write apps in, then with the ways apps take UI they did not ship with. Green means the capability is available, yellow that it needs more of the app's own work or a separate project, and red that it is not provided; the marks describe availability, not performance. Versions are each framework's documented minimums at the time of writing: check them for the release you use.

Legend: <span class="status status--yes" role="img" aria-label="Yes"></span> Yes · <span class="status status--partial" role="img" aria-label="Partial"></span> Partial · <span class="status status--no" role="img" aria-label="No"></span> No.

## Cross-platform frameworks

| Capability | NSH | React Native | Flutter | Qt 6 | GPUI | GPUI Fast | Slint |
|---|---|---|---|---|---|---|---|
| Drawn by | Platform UI | Platform views | Own engine | Scene graph | Own, GPU | Own, GPU | Own renderer |
| UI model | Retained | Retained | Retained | Retained | Immediate | Immediate + Retained | Reactive, retained |
| Language | Rust, TSX | JS, TS | Dart | C++, QML | Rust | Rust | Slint + Rust, C++ |
| iOS | <span class="status status--yes" role="img" aria-label="Yes"></span> 15+ | <span class="status status--yes" role="img" aria-label="Yes"></span> 15.1+ | <span class="status status--yes" role="img" aria-label="Yes"></span> 15+ | <span class="status status--yes" role="img" aria-label="Yes"></span> 17+ | <span class="status status--no" role="img" aria-label="No"></span> | <span class="status status--no" role="img" aria-label="No"></span> | <span class="status status--partial" role="img" aria-label="Partial"></span> Rust |
| Android | <span class="status status--yes" role="img" aria-label="Yes"></span> 9+ | <span class="status status--yes" role="img" aria-label="Yes"></span> 7+ | <span class="status status--yes" role="img" aria-label="Yes"></span> 7+ | <span class="status status--yes" role="img" aria-label="Yes"></span> 9+ | <span class="status status--no" role="img" aria-label="No"></span> | <span class="status status--no" role="img" aria-label="No"></span> | <span class="status status--yes" role="img" aria-label="Yes"></span> |
| macOS | <span class="status status--yes" role="img" aria-label="Yes"></span> 14+ | <span class="status status--partial" role="img" aria-label="Partial"></span> Separate | <span class="status status--yes" role="img" aria-label="Yes"></span> 12+ | <span class="status status--yes" role="img" aria-label="Yes"></span> 13+ | <span class="status status--yes" role="img" aria-label="Yes"></span> 12+ | <span class="status status--yes" role="img" aria-label="Yes"></span> 12+ | <span class="status status--yes" role="img" aria-label="Yes"></span> 13+ |
| Windows | <span class="status status--yes" role="img" aria-label="Yes"></span> 10 1809+ | <span class="status status--partial" role="img" aria-label="Partial"></span> Separate | <span class="status status--yes" role="img" aria-label="Yes"></span> 10+ | <span class="status status--yes" role="img" aria-label="Yes"></span> 10 1809+ | <span class="status status--yes" role="img" aria-label="Yes"></span> 10+ | <span class="status status--yes" role="img" aria-label="Yes"></span> 10+ | <span class="status status--yes" role="img" aria-label="Yes"></span> 10+ |
| Linux | <span class="status status--yes" role="img" aria-label="Yes"></span> GTK 4.14+ | <span class="status status--no" role="img" aria-label="No"></span> | <span class="status status--yes" role="img" aria-label="Yes"></span> Debian 10+ | <span class="status status--yes" role="img" aria-label="Yes"></span> Debian 11+ | <span class="status status--yes" role="img" aria-label="Yes"></span> Vulkan | <span class="status status--yes" role="img" aria-label="Yes"></span> Vulkan | <span class="status status--yes" role="img" aria-label="Yes"></span> |
| Web | <span class="status status--yes" role="img" aria-label="Yes"></span> HTML | <span class="status status--partial" role="img" aria-label="Partial"></span> Library | <span class="status status--yes" role="img" aria-label="Yes"></span> Canvas | <span class="status status--yes" role="img" aria-label="Yes"></span> Canvas | <span class="status status--no" role="img" aria-label="No"></span> | <span class="status status--no" role="img" aria-label="No"></span> | <span class="status status--yes" role="img" aria-label="Yes"></span> Canvas |
| System text | <span class="status status--yes" role="img" aria-label="Yes"></span> | <span class="status status--yes" role="img" aria-label="Yes"></span> | <span class="status status--partial" role="img" aria-label="Partial"></span> | <span class="status status--partial" role="img" aria-label="Partial"></span> | <span class="status status--partial" role="img" aria-label="Partial"></span> | <span class="status status--partial" role="img" aria-label="Partial"></span> | <span class="status status--partial" role="img" aria-label="Partial"></span> |
| Per-device UX | <span class="status status--yes" role="img" aria-label="Yes"></span> | <span class="status status--partial" role="img" aria-label="Partial"></span> | <span class="status status--partial" role="img" aria-label="Partial"></span> | <span class="status status--partial" role="img" aria-label="Partial"></span> | <span class="status status--no" role="img" aria-label="No"></span> | <span class="status status--no" role="img" aria-label="No"></span> | <span class="status status--partial" role="img" aria-label="Partial"></span> |
| No JS runtime | <span class="status status--yes" role="img" aria-label="Yes"></span> Rust apps | <span class="status status--no" role="img" aria-label="No"></span> | <span class="status status--yes" role="img" aria-label="Yes"></span> | <span class="status status--partial" role="img" aria-label="Partial"></span> C++ | <span class="status status--yes" role="img" aria-label="Yes"></span> | <span class="status status--yes" role="img" aria-label="Yes"></span> | <span class="status status--yes" role="img" aria-label="Yes"></span> |
| Signed delivery | <span class="status status--yes" role="img" aria-label="Yes"></span> | <span class="status status--partial" role="img" aria-label="Partial"></span> OTA | <span class="status status--no" role="img" aria-label="No"></span> | <span class="status status--partial" role="img" aria-label="Partial"></span> QML | <span class="status status--partial" role="img" aria-label="Partial"></span> Shell | <span class="status status--partial" role="img" aria-label="Partial"></span> Shell | <span class="status status--no" role="img" aria-label="No"></span> |
| License | Apache-2.0 | MIT | BSD-3-Clause | LGPL, GPL, commercial | Apache-2.0 | Apache-2.0 | GPL, commercial |

Immediate mode builds the UI description again every frame; retained mode keeps it and updates only what changed. GPUI Fast combines the two on GPUI and runs where GPUI runs. "Shell" is [GPUI Shell](https://gpui-kit.com/shell).

NSH is the one framework here that brings all of these together: each platform's own UI and text input, phones, desktops and the web from one app — the web as HTML — Rust apps with no JavaScript runtime, and signed, sandboxed UI delivered after release.

### What the rows mean

- **Drawn by, UI model.** NSH mounts each platform's own views and keeps them (retained mode): a change updates only the views it touched. React Native also mounts platform views, on iOS and Android. Flutter, Qt Quick, GPUI and Slint draw with their own renderers; GPUI builds the element tree each frame (immediate mode), and [GPUI Fast](https://github.com/longbridge/gpui-fast) reuses what did not change.
- **Platforms.** NSH's minimums are its own ([Platforms](https://nsh.dev/versions/main/docs/platforms.md)). The others come from [React Native 0.76](https://reactnative.dev/blog/2024/10/23/release-0.76-new-architecture) (iOS 15.1, Android 7 / API 24; macOS and Windows through the separate react-native-macos and react-native-windows projects, the web through the react-native-web library), [Flutter 3.47](https://docs.flutter.dev/reference/supported-platforms), [Qt 6.10](https://doc.qt.io/qt-6.10/supported-platforms.html), [Zed's requirements](https://zed.dev/docs/installation) for GPUI, and [Slint's platform guides](https://docs.slint.dev/latest/docs/slint/guide/platforms/mobile/general/) (iOS from Rust). "Canvas" means the framework draws into a canvas on the page; NSH's web apps are HTML elements styled with CSS, which the browser scrolls, selects and edits ([Web](https://nsh.dev/versions/main/docs/web.md)).
- **System text.** NSH's text fields are the platform's editors — `UITextView`, `EditText`, `NSTextView`, GTK's `TextView`, the browser's — with the system's input methods, selection handles and editing menus; on Windows, NSH's own editor works with DirectWrite and the system's input methods (IMM32). React Native also uses the platform's text inputs. The self-drawn frameworks implement text editing themselves and connect it to the system's input methods.
- **Per-device UX.** NSH's base components follow the device: the same `Menu` is a popup at its trigger with a pointer and a sheet from the bottom on a phone, and a `ContextMenu` opens on a right click or a held finger. In the others, adapting interaction per device is mostly the app's own work.
- **No JS runtime.** A Rust app's runners link no JavaScript engine on any platform; TSX is the second path, on the same engine. Qt Quick's QML runs on Qt's JavaScript engine; Qt Widgets in C++ do not.
- **Signed delivery.** NSH verifies signed `.nshpkg` packages against the keys it trusts and a revocation list, and runs each in a VM with the limits and capabilities the host grants ([Signed packages](https://nsh.dev/versions/main/docs/signed-packages.md), [Sandbox and capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md)). React Native's over-the-air updates ship trusted app code; Qt can load QML files; GPUI apps take JavaScript modules through [GPUI Shell](https://gpui-kit.com/shell).

### What sets NSH apart

- **Native on every platform, in both senses.** Each backend builds on its platform's own views, text and input methods — UIKit, Android views, AppKit, Win32 with Direct2D, GTK 4, HTML — and each platform's interaction comes with them. Text selection, input methods and accessibility are the system's, and what a new OS release brings to them reaches the app ([Introduction](https://nsh.dev/versions/main/docs.md#what-native-means)).
- **Phones, desktops and the web from one app.** Six platforms are backends of one framework, with layouts that reshape and input that follows the device; on the web, the app is HTML, published as a static site.
- **Rust first, with no JavaScript runtime.** A whole app can be Rust from start to end, compiled to native code with Rust's types, threads and crates. TSX is the second path, on the same engine, for screens written quickly ([Building with Rust](https://nsh.dev/versions/main/docs/rust.md)).
- **Retained views for everyday apps.** Chats, forms, lists and documents sit near idle at rest, because a change sends only the views it touched ([Introduction](https://nsh.dev/versions/main/docs.md#retained-views)).
- **UI delivered after release, signed and sandboxed.** Apps built with NSH — and native apps written with each platform's own tools — take TSX modules at run time, written by a team or generated by AI ([Dynamic UI](https://nsh.dev/versions/main/docs.md#dynamic-ui-and-ai-generated-ui)).
- **One toolchain, for people and agents.** One `nsh` executable creates, runs, tests on real platforms, packages and signs apps for every target.

### React Native

React Native is the closest in intent: both reduce duplicated client work and use the platform's views. React Native's center is JavaScript or TypeScript with React and its package ecosystem, on iOS and Android, with desktop support in separate projects. NSH's center is Rust: its runtime, renderer and modules are Rust, Rust is an app language of its own, and TSX is one path among two; its six platforms, the desktops and the web included, are backends of the same framework.

### Flutter

Flutter draws every pixel with its own engine, so an app looks the same on every platform. NSH takes the other path: the views, text and text input of each platform, and on the web HTML elements and the browser's own scrolling, selection and input. Text editing, input methods and selection are the platform's, rather than reimplemented per platform.

### Qt

Qt is a mature toolkit with two UI technologies, Qt Widgets and Qt Quick, and long-standing tools and platform support. NSH differs in its base and its model: Rust as the core language with a TSX path, a toolchain designed for automated (and AI-driven) development, the web rendered as HTML, and mobile, desktop and web interaction adapted inside one component model.

### GPUI and GPUI Fast

[GPUI](https://gpui-kit.com) is a Rust UI framework that draws with the GPU, built for demanding desktop apps; [GPUI Fast](https://github.com/longbridge/gpui-fast) is Longbridge's fork with retained rendering — it reuses unchanged views, layout and text measurements — scroll layers and native window composition. NSH builds on each platform's views instead, so text input, selection, input methods and system interaction are the platform's own, and it covers phones and the web as well; NSH's GPUI backend embeds NSH apps in GPUI and GPUI Kit apps ([GPUI](https://nsh.dev/versions/main/docs/gpui.md)).

The two suit different loads. In the [NSH performance benchmark](https://github.com/longbridge/nsh-perf-bench) (Linux, a 500-row quote table, NSH on its GTK 4 backend), everyday loads cost the same: at 1,000 quotes a second, NSH Rust uses 18% of a core and GPUI Fast 20%. Under sustained, dense updates GPUI Fast is ahead: at 20,000 quotes a second it uses 25% of a core where NSH uses 73–78%, and frame-by-frame animation of 1,000 boxes costs it about a third of NSH's CPU.

### Slint

Slint is a declarative UI toolkit with its own language and light renderers, for desktops and embedded devices, used from Rust, C++, JavaScript or Python. Both value native performance; NSH's route is each platform's own UI and interaction, HTML on the web, Rust and TSX as app languages, and AI-driven development across six platforms.

### Electron and Tauri

Electron bundles Chromium and Tauri uses the system's web view: both build desktop apps (and, with Tauri, mobile apps) from web content, with the browser's text and input. NSH builds each platform's own views instead, and renders HTML only on the web itself.

## UI delivered after release

An app that wants UI it did not ship with — answers generated by a model, features from partners or other teams, screens that change without a release — has a handful of established options, on phones and desktops alike. They differ in what draws the UI, what the delivered code may do, and how much of the app has to change to host them.

| Capability | NSH | Web view | Server-driven UI | Mini-programs | OTA updates |
|---|---|---|---|---|---|
| Drawn by | Platform UI | Browser engine | The app's views | Web engine + layer | Framework renderer |
| Native look and behavior | <span class="status status--yes" role="img" aria-label="Yes"></span> | <span class="status status--no" role="img" aria-label="No"></span> | <span class="status status--yes" role="img" aria-label="Yes"></span> | <span class="status status--partial" role="img" aria-label="Partial"></span> | <span class="status status--yes" role="img" aria-label="Yes"></span> |
| Own state, logic and layout | <span class="status status--yes" role="img" aria-label="Yes"></span> | <span class="status status--yes" role="img" aria-label="Yes"></span> | <span class="status status--no" role="img" aria-label="No"></span> | <span class="status status--yes" role="img" aria-label="Yes"></span> | <span class="status status--yes" role="img" aria-label="Yes"></span> |
| Host's native components | <span class="status status--yes" role="img" aria-label="Yes"></span> | <span class="status status--partial" role="img" aria-label="Partial"></span> Bridge | <span class="status status--yes" role="img" aria-label="Yes"></span> | <span class="status status--partial" role="img" aria-label="Partial"></span> | <span class="status status--yes" role="img" aria-label="Yes"></span> |
| Sandbox the host configures | <span class="status status--yes" role="img" aria-label="Yes"></span> | <span class="status status--partial" role="img" aria-label="Partial"></span> Same-origin | <span class="status status--yes" role="img" aria-label="Yes"></span> Schema | <span class="status status--yes" role="img" aria-label="Yes"></span> | <span class="status status--no" role="img" aria-label="No"></span> |
| Signed, revocable packages | <span class="status status--yes" role="img" aria-label="Yes"></span> | <span class="status status--no" role="img" aria-label="No"></span> | <span class="status status--no" role="img" aria-label="No"></span> | <span class="status status--partial" role="img" aria-label="Partial"></span> | <span class="status status--partial" role="img" aria-label="Partial"></span> |
| Fit for AI-generated UI | <span class="status status--yes" role="img" aria-label="Yes"></span> | <span class="status status--partial" role="img" aria-label="Partial"></span> Web pages | <span class="status status--partial" role="img" aria-label="Partial"></span> | <span class="status status--partial" role="img" aria-label="Partial"></span> | <span class="status status--no" role="img" aria-label="No"></span> |
| Cost to the host app | One view and a library | A browser engine per view | A renderer per component | A container SDK | The whole app in the framework |

- **Web view (H5).** A page in a browser engine: anything HTML can express, with the browser's look and a hand-written bridge to native code.
- **Server-driven UI.** JSON that recombines the components and actions the app already ships: easy to generate, with no local state or logic beyond what the schema provides.
- **Mini-program containers.** A platform-specific framework and API on a web engine, inside a large container SDK.
- **Over-the-air updates** (React Native with a code-push service, for example). The whole framework, but updates are trusted app code, and the app has to be written in that framework.
- **NSH.** A TSX module with its own state, logic, animation and layout, rendered with the platform's own UI, that can use the host's registered native views. It arrives as a signed package the app verifies, runs in its own VM with memory, call-time and node limits, and reaches only the network hosts, web pages and system settings the host grants ([Sandbox and capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md)). The host adds one view where the module appears ([Platforms](https://nsh.dev/versions/main/docs/platforms.md#embed-in-a-native-app)), and the same bundle runs on every platform. This is the reason NSH exists next to [GPUI Shell](https://nsh.dev/versions/main/docs.md#native-shell-and-gpui-shell).

## When another option fits better

- The screen is dominated by sustained, dense updates of thousands of views — a market-data terminal streaming tens of thousands of quotes a second, a custom visualization redrawn every frame: GPUI Fast's retained GPU rendering uses a fraction of the CPU (see [GPUI and GPUI Fast](#gpui-and-gpui-fast)).
- The app must look pixel-identical on every platform: a framework that draws everything itself, such as Flutter or Slint, gives that by design.
- You need a large ecosystem of third-party packages today: React Native, Flutter and Qt have years of them.
- The UI is a document or an existing web page: a web view shows it as it is.
- The set of screens is fixed and small, and only content and order change: server-driven UI needs no runtime at all.

## See also

- [Introduction](https://nsh.dev/versions/main/docs.md): what NSH is, and what native means in it.
- [Architecture](https://nsh.dev/versions/main/docs/architecture.md): what runs where inside NSH.
- [Performance](https://nsh.dev/versions/main/docs/performance.md): the rules NSH follows, and how to measure an app.

Source: https://nsh.dev/versions/main/docs/comparison

---

# Installation

Everything NSH does goes through one command, `nsh`. It builds apps written in Rust or TSX, runs them on every platform, serves TSX to development hosts with hot updates, and packages installable apps. You can use it from a prebuilt distribution or build it from a checkout of the repository.

Apps written in Rust also need a Rust toolchain ([below](#for-apps-written-in-rust)); TSX apps need `nsh` alone. On top of that, each platform needs its own tools:

| Platform | Develop and package on | Needs |
|---|---|---|
| iOS | macOS | Xcode and an iOS simulator runtime |
| Android | macOS, Windows or Linux | The Android SDK and a JDK; an emulator or a device |
| macOS | macOS | Xcode's command line tools; apps run on macOS 14+ |
| Windows | Windows | Windows 10 1809+; the WebView2 Runtime for web views |
| Linux | Linux | GTK 4.14+ (and its development packages to build the runtime) |
| [GPUI](https://nsh.dev/versions/main/docs/gpui.md) (embedding in GPUI apps) | macOS, Windows or Linux | A GPU (Metal, DirectX or Vulkan); on Linux, Wayland or X11 |

The AppKit host is the default on macOS. Mac Catalyst (`--target catalyst`) needs Xcode like iOS. Details are under [Platform tools](#platform-tools).

## Installing a release

Each [GitHub release](https://github.com/longbridge/nsh/releases) carries the prebuilt distribution (below) for macOS (Apple silicon), Linux x86_64 and Windows x86_64. Every way of installing it puts the same `nsh` command on your `PATH`.

**macOS and Linux**, with the install script:

```sh
curl -fsSL https://nsh.dev/install.sh | sh
```

It installs the distribution to `~/.nsh` and links `~/.local/bin/nsh` to it; running it again updates it. `NSH_VERSION=v0.1.0` pins a release, `NSH_INSTALL_DIR` picks another directory.

**Windows**, in PowerShell:

```powershell
irm https://nsh.dev/install.ps1 | iex
```

It installs to `%LOCALAPPDATA%\nsh` and adds its `bin` to your user `PATH` (open a new terminal afterwards). `$env:NSH_VERSION` and `$env:NSH_INSTALL_DIR` work as above.

**Homebrew** (macOS and Linux):

```sh
brew install longbridge/tap/nsh
```

**Scoop** (Windows):

```powershell
scoop install https://github.com/longbridge/nsh/releases/latest/download/nsh.json
```

**mise** (all three):

```sh
mise use -g github:longbridge/nsh
```

The archives (`nsh-macos-arm64.tar.gz`, `nsh-linux-x86_64.tar.gz`, `nsh-windows-x86_64.zip`, each with a `.sha256`) carry no version in their names, so `https://github.com/longbridge/nsh/releases/latest/download/<archive>` always fetches the latest. The embedding SDKs are also released alone, for native apps that need no CLI: `nsh-embed-ios.zip` and `nsh-embed-android.zip`.

> [!NOTE]
> The binaries are not signed yet. macOS quarantines files downloaded by a browser; the install script, Homebrew and mise download with `curl` and are not affected, otherwise run `xattr -dr com.apple.quarantine <dir>`. The Linux runtime needs glibc 2.39 and GTK 4.14 or newer (Ubuntu 24.04 and later). There is no Intel Mac or arm64 Linux / Windows build: build those from a checkout.

## For apps written in Rust

Install Rust through [rustup](https://rustup.rs). [huacnlee/cargo](#building-from-a-checkout) is recommended for development. `nsh` builds a Rust app's runner for each target with Cargo, from your crate and NSH's crates on crates.io at the CLI's version, so add the Rust targets of the platforms you run on:

```sh
rustup target add aarch64-apple-ios-sim aarch64-apple-ios aarch64-apple-ios-macabi   # iOS simulator, devices, Mac Catalyst
rustup target add aarch64-linux-android armv7-linux-androideabi x86_64-linux-android # Android (with the SDK's NDK)
rustup target add wasm32-unknown-unknown                                             # the web
```

The desktops build for the machine you are on. `cargo run` in a Rust app's directory starts it on the desktop backend directly, which builds with the backend's development libraries ([Platform tools](#platform-tools)). Android builds also use an **NDK** from the SDK, as [building the Android runtime](#building-the-android-runtime) does.

## The prebuilt distribution

The distribution is a directory, `dist/nsh`, with the CLI and the prebuilt native runtimes it packages apps with:

```sh
dist/nsh/bin/nsh                                             # the CLI
dist/nsh/runtime/ios/iphoneos/nsh-ios-app                    # runs packaged apps on iOS devices
dist/nsh/runtime/ios/iphonesimulator/{nsh-ios-app,nsh-ios-host}
dist/nsh/runtime/ios/maccatalyst/nsh-ios-host                # the Mac Catalyst development host
dist/nsh/runtime/android/{release,dev}/                      # classes.dex, lib/<abi>/libnsh.so, symbols/<abi>/libnsh.so
dist/nsh/runtime/macos/{nsh-macos-host,nsh-macos-app}        # the macOS (AppKit) development host and release runner
dist/nsh/runtime/linux/{nsh-linux-host,nsh-linux-app}        # the Linux development host and release runner
dist/nsh/runtime/windows/{nsh-windows-host,nsh-windows-app}.exe  # the Windows development host and release runner
dist/nsh/runtime/gpui/nsh-gpui-host[.exe]                    # the GPUI development host, for this OS
dist/nsh/runtime/web/{nsh.wasm,nsh-dev.wasm,nsh.js}          # the web runtimes (nsh package / run --target web)
dist/nsh/embed/ios/{NativeShell,NativeShellDev}.xcframework  # embedding in iOS apps
dist/nsh/embed/android/{nsh,nsh-dev}.aar                     # embedding in Android apps
```

Put `dist/nsh/bin` on your `PATH` (or call `dist/nsh/bin/nsh` directly) and keep the directory together: `nsh` finds the runtimes next to itself, in `bin/../runtime` (through a symlink to it, as the installers make, too).

```sh
export PATH="$PWD/dist/nsh/bin:$PATH"
nsh --version
```

The distribution is made with `cargo xtask dist` in a checkout (below). The `nsh` binary it contains is built for that machine. On a Mac with Xcode it includes the iOS and macOS runtimes (Apple Silicon); on Linux it includes the Linux runtime instead, built for that machine; on Windows the Windows runtime, with `bin\nsh.exe`. Each also includes the [GPUI](https://nsh.dev/versions/main/docs/gpui.md) development host, built for that machine. All include the Android runtime (on Windows only when the Android SDK is found).

## Installing the latest source

On macOS and Linux, install the latest `main` with Git, Rust and the platform build dependencies below:

```sh
curl -fsSL https://nsh.dev/install.sh | sh -s -- --source
nsh -V # nsh 0.1.1 (abcdef0)
```

The installer keeps the checkout in `~/.nsh/source`, builds the release CLI and links it into `~/.local/bin`. Re-run the command to update; local source changes must be saved first. The retained checkout lets NSH build native runtimes on demand. Cargo uses its existing configuration and target directory. `NSH_INSTALL_DIR` changes the installation prefix; `NSH_VERSION` selects prebuilt releases only. Both `-V` and `--version` show the version and seven-character source revision.

## Building from a checkout

You need Rust through [rustup](https://rustup.rs). The repository's `rust-toolchain.toml` selects the stable toolchain and installs the iOS and Android targets on first use.

For development we recommend [huacnlee/cargo](https://github.com/huacnlee/cargo), a drop-in Cargo fork: your Git worktrees share one build directory that stays under a size limit on its own, with nothing to configure. It replaces `~/.cargo/bin/cargo`, keeps `rust-toolchain.toml` and `cargo +nightly` working, and updates itself; its README says how to put rustup's back.

```sh
curl -fsSL https://huacnlee.github.io/cargo/install.sh | sh     # Windows: irm https://huacnlee.github.io/cargo/install.ps1 | iex
```

```sh
git clone https://github.com/longbridge/nsh.git
cd nsh
cargo build -p nsh-cli          # ./target/debug/nsh
```

Then build the development host of each target you want to run on, once, and again after you update the checkout:

```sh
cargo build -p nsh-ios-host --target aarch64-apple-ios-macabi   # nsh run (Mac Catalyst window)
cargo build -p nsh-ios-host --target aarch64-apple-ios-sim      # nsh run --target ios
cargo xtask android --dev                                       # nsh run --target android
cargo build -p nsh-macos-host                                   # nsh run --target macos (built for you in a checkout)
cargo build -p nsh-linux-host                                   # nsh run on Linux (built for you in a checkout)
cargo build -p nsh-windows-host                                 # nsh run on Windows (built for you in a checkout)
cargo build --manifest-path crates/gpui/Cargo.toml --target-dir target -p nsh-gpui-host   # nsh run --target gpui (built for you in a checkout)
cargo build --profile web -p nsh-platform-web --target wasm32-unknown-unknown   # nsh run --target web (built for you in a checkout)
```

For `nsh package`, build the release runners as well:

```sh
cargo build -p nsh-ios-app --target aarch64-apple-ios-sim       # nsh package --target ios-simulator
cargo build -p nsh-ios-app --target aarch64-apple-ios           # nsh package --target ios
cargo xtask android                                             # nsh package --target android
cargo build -p nsh-macos-app                                    # nsh package --target macos
cargo build -p nsh-linux-app                                    # nsh package --target linux
cargo build -p nsh-windows-app                                  # nsh package --target windows
# nsh package --target web uses the same web runtime as nsh run --target web
```

A CLI built from a checkout looks for the runtimes in `target/<triple>/<profile>` (the macOS, Linux, Windows and GPUI ones, built for this machine, in `target/<profile>`) and `target/android/<profile>[-dev]`, using its own profile: `./target/debug/nsh` uses debug runtimes, `./target/release/nsh` release ones. Build both with the same profile (add `--release` to all of them for faster apps).

> [!TIP]
> `NSH_RUNTIME=/path/to/runtime` makes `nsh` use a runtime directory laid out like the distribution's `runtime/`, wherever the CLI itself lives.

## Platform tools

### iOS and Mac Catalyst

- **Xcode** (with its command line tools). `nsh run` uses `xcrun simctl` to boot simulators and install the development host; `nsh package` uses `actool` for app icons and `codesign` for signing.
- An iOS simulator runtime. If none is installed, install one with `xcodebuild -downloadPlatform iOS`.
- Apps target iOS 15.0 and later.

### Android

- **The Android SDK**, found through `ANDROID_HOME`, `ANDROID_SDK_ROOT` or Android Studio's default place (`~/Library/Android/sdk`, `%LOCALAPPDATA%\Android\Sdk` on Windows), with:
  - `platforms;android-35` and a recent `build-tools` (NSH uses `aapt2`, `zipalign` and `apksigner` from it, no Gradle);
  - `platform-tools` (`adb`).
- **A JDK** (`keytool` creates the debug keystore in `~/.android/debug.keystore` the first time you package, `apksigner` needs Java).
- A running emulator or a device connected over `adb`. Apps need Android 9 (API 28) or later.

```sh
sdkmanager "platforms;android-35" "build-tools;35.0.1" "platform-tools"
```

### macOS

- **Xcode's command line tools** (`xcode-select --install`): the SDK and clang to build the runtime, `codesign` and `sips` to package apps.
- Apps need macOS 14 or later.

See [macOS](https://nsh.dev/versions/main/docs/macos.md).

### Linux

- **GTK 4.14** or later, with their development packages and clang to build the runtime: `libgtk-4-dev clang` (Debian, Ubuntu 24.04 or later), `gtk4 clang` (Arch), `gtk4-devel clang` (Fedora).
- **WebKitGTK 6.0** (2.40 or later) for web views: `libwebkitgtk-6.0-dev` (Debian, Ubuntu), `webkitgtk-6.0` (Arch), `webkitgtk6.0-devel` (Fedora) to build the runtime; apps then need it where they run. Without it, `cargo xtask dist` builds the runtime with placeholders for web views.
- **GStreamer** plugins for the video formats apps play.

See [Linux](https://nsh.dev/versions/main/docs/linux.md).

### Windows

- **Windows 10 1809** or later, or Windows 11. The WebView2 Runtime (part of Windows 11, installed with Edge on Windows 10) for web views.
- To build the runtime: **Visual Studio Build Tools** with the "Desktop development with C++" workload and the Windows SDK, and **LLVM** (libclang, for QuickJS' bindings; found in `C:\Program Files\LLVM`, else set `LIBCLANG_PATH`).

See [Windows](https://nsh.dev/versions/main/docs/windows.md).

### Building the Android runtime

Building the Android runtime from a checkout (`cargo xtask android`) additionally needs an **NDK** from the SDK (`ndk;<version>`; set `ANDROID_NDK_HOME` if the newest one installed is incomplete) and `javac`.

## What works where

| Command | macOS | Linux | Windows |
|---|---|---|---|
| `nsh init`, `nsh build`, `nsh test`, `nsh dev`, `nsh check` | Yes | Yes | Yes |
| `nsh run --target catalyst` (Mac Catalyst) | Yes | No | No |
| `nsh run --target macos`, `nsh package --target macos` | Yes | No | No |
| `nsh run --target linux` (the default on Linux), `nsh package --target linux` | No | Yes | No |
| `nsh run --target windows` (the default on Windows), `nsh package --target windows` | No | No | Yes |
| `nsh run --target gpui` (the backend GPUI apps embed) | Yes | Yes | Yes |
| `nsh run --target ios`, `nsh package --target ios` / `ios-simulator` | Yes, with Xcode | No | No |
| `nsh run --target android`, `nsh package --target android` | Yes | Yes, from a checkout | Yes, with the Android runtime |
| `nsh keygen`, `certify`, `publish`, `verify`, `revoke` | Yes | Yes | Yes |

On Linux, build the CLI and the Android runtime from a checkout (`cargo build -p nsh-cli` and `cargo xtask android --dev`); the NDK's Linux toolchain is used automatically. On Windows the NDK's Windows toolchain is used the same way, and `cargo xtask dist` includes the Android runtime when it finds the Android SDK.

## Editor setup

A Rust app is a Cargo project: rust-analyzer (VS Code, Zed, Neovim, RustRover) checks it and completes NSH's API, with its doc comments, as for any crate.

For TSX, NSH needs no NPM. `nsh init` writes a `tsconfig.json` and the type declarations of everything NSH provides into `.nsh/types`, and every command that builds the app keeps them up to date. Any editor that uses the TypeScript language server (VS Code, Zed, Neovim, WebStorm) type-checks the app with them. See [Project structure](https://nsh.dev/versions/main/docs/project-structure.md#tsconfigjson-and-nshtypes).

## Next steps

Continue with [Getting started](https://nsh.dev/versions/main/docs/getting-started.md) to create an app and run it.

Source: https://nsh.dev/versions/main/docs/installation

---

# Getting started

This guide creates an NSH app, runs it on the platforms you target, and ships it. NSH apps are written in Rust or TSX,
on the same engine: Rust compiles your app into native code with no JavaScript VM, and TSX runs on QuickJS with hot
updates, as modules a native app can load at run time. The guide follows a Rust app first, then the same app in TSX.
It assumes `nsh` is installed and on your `PATH` ([Installation](https://nsh.dev/versions/main/docs/installation.md)); in a checkout, use
`./target/debug/nsh` instead.

> [!TIP]
> No app project at hand? The first two sections need none: `nsh run` shows the app in a window on your computer, in
> the iOS simulator, on an Android device or in the browser. You can stop there, or [package it as a standalone
> app](#or-ship-it-as-a-standalone-app).

## Create an app

On a terminal, `nsh init` asks what the app is written in: `rust`, `ts` or `mixed` (TSX with a Rust crate of its own).
`--template` chooses without asking.

### In Rust

```sh
nsh init my-app --template rust
```

`nsh init` creates the directory and writes a Cargo project:

| File | What it is |
|---|---|
| `src/lib.rs` | The app: its root component, state and handlers |
| `src/main.rs` | Mounts the same root on macOS, Windows or Linux for `cargo run` |
| `Cargo.toml` | The crate, depending on `nsh-core` and `nsh-base` at the CLI's version |
| `nsh.json` | The app's name, id, version and build number, its crate (`"rust": "."`) and root component (`"root": "App"`) ([Project structure](https://nsh.dev/versions/main/docs/project-structure.md#nshjson)) |
| `App.test.tsx` | The root's test, in TypeScript (`nsh test`), with `tsconfig.json` and `.nsh/types` for your editor |
| `README.md` | How to run, test and package the app, and how to add a TSX entry later |
| `.gitignore` | Ignores `.nsh/` and `target/` |

Rust development needs a Rust toolchain ([rustup](https://rustup.rs), and we recommend
[huacnlee/cargo](https://github.com/huacnlee/cargo) for building); the `nsh` commands build the app's runners
from NSH's crates on crates.io, at the CLI's version.

### In TSX

```sh
nsh init my-app --template ts
```

A TSX app is one or more `.tsx` files with an entry: what `nsh run` runs, and what a host app loads as a module.

| File | What it is |
|---|---|
| `App.tsx` | The entry module: renders the app with `mount` |
| `App.test.tsx` | Its test (`nsh test`) |
| `nsh.json` | The app's name, id, version and build number ([Project structure](https://nsh.dev/versions/main/docs/project-structure.md#nshjson)) |
| `tsconfig.json` | Extends `.nsh/tsconfig.json`, NSH's TypeScript settings, which resolve `nsh` to the declarations in `.nsh/types` |
| `.gitignore` | Ignores `.nsh/` and `target/` |
| `.nsh/types/` | Generated declarations of every NSH module, for your editor |

Files that already exist are kept, so you can run it in a directory that has some of them; a Rust app is created in
a new directory.

For both, the display name defaults to the directory's name; pass `--name "My App"` to choose another. The id becomes
`com.example.<name>`: change it in `nsh.json` before you ship. `nsh init my-app --template mixed` creates a TSX app
that is also a Rust crate (`Cargo.toml` and `src/lib.rs` beside `App.tsx`), whose component, module and class
`App.tsx` imports ([Building with Rust](https://nsh.dev/versions/main/docs/rust.md)).

### The root component

The two templates make the same app, a counter:

```rust
// src/lib.rs
use nsh_base::theme;
use nsh_core::prelude::*;

/// The crate's UI set: what a TSX entry may import from `my-app/native`.
#[native_module("my-app/native")]
fn native(registry: &mut Registry) {
    registry.register::<App>();
}

/// The application's root component.
#[component]
pub fn App() -> impl IntoElement {
    let count = signal(0_u32);
    view()
        .flex_1()
        .bg(move || theme().background)
        .text_color(move || theme().foreground)
        .child(
            view()
                .flex_1()
                .p_safe_area()
                .child(
                    view()
                        .flex_1()
                        .items_center()
                        .justify_center()
                        .gap_4()
                        .child(text(move || format!("Count: {}", count.get())).text_size(px(28.0)))
                        .child(
                            view()
                                .px_5()
                                .py_3()
                                .rounded(px(10.0))
                                .bg(move || theme().primary)
                                .active(|s| s.opacity(0.6))
                                .on_press(move || count.update(|value| *value += 1))
                                .child(
                                    text("Tap")
                                        .text_size(px(17.0))
                                        .text_color(move || theme().primary_foreground),
                                ),
                        ),
                ),
        )
}
```

```tsx
// App.tsx
import { mount, signal, Text, View } from "nsh";

function App() {
  const count = signal(0);
  return (
    <View class="flex-1 items-center justify-center gap-4 bg-background pt-[env(safe-area-inset-top)] pb-[env(safe-area-inset-bottom)]">
      <Text class="text-3xl font-semibold text-foreground">{count()}</Text>
      <View
        onPress={() => count.update((c) => c + 1)}
        role="button"
        class="rounded-(--radius) bg-primary px-5 py-3 active:bg-primary/90"
      >
        <Text class="text-lg text-primary-foreground">Tap</Text>
      </View>
    </View>
  );
}

mount(App);
```

In Rust:

- **`use nsh_core::prelude::*`** brings the primitives (`view()`, `text()`, `scroll()`, `input()`, `image()`, ...),
  [signals](https://nsh.dev/versions/main/docs/reactivity.md) and the typed style methods (`.p_safe_area()` pads a view by the [safe area](https://nsh.dev/versions/main/elements/safe-area.md)); **`nsh_base`** has the unstyled base components
  (`button()`, the keyboard, dialogs) and `theme()`, the colors and
  radii the app's components draw with ([Theme](https://nsh.dev/versions/main/docs/rust.md#theme)).
- **`#[component] pub fn App()`** is a component: a function that runs **once** and returns its elements.
  `nsh.json`'s `"root": "App"` names it, and `nsh run` mounts it. `signal(0_u32)` makes a value that changes over time.
- **`text(move || format!(…, count.get()))`** binds the text to the signal: when `count` changes, NSH runs this
  closure again and updates this one text, nothing else. Styles take closures the same way:
  `.bg(move || theme().primary)` follows the theme into dark mode.
- **`.on_press(..)`** makes the view answer presses; `.active(|s| s.opacity(0.6))` is its style while pressed, applied
  natively. The button is the app's own: NSH provides the primitives and the capabilities, and the app draws its UI
  from them.
- **`.px_5()`, `.rounded(px(10.0))`, `.gap_4()`** are typed style methods named as Tailwind's utilities are, in
  points (`px`). Layout is flexbox, and children stack in a column by default ([Layout](https://nsh.dev/versions/main/docs/layout.md)).
- **`#[native_module("my-app/native")]`** names what a TSX entry may import from the crate, for when you add TSX
  screens on top ([Building with Rust](https://nsh.dev/versions/main/docs/rust.md#extending-a-rust-app-with-tsx)).

In TSX:

- **`import { mount, signal, Text, View } from "nsh"`**: `nsh` is the core module: signals, `mount`, the other
  reactive primitives, and the host elements. It is served by the native runtime, not bundled. **`nsh/base`** has the
  base components, as `nsh_base` does in Rust.
- **`function App()`** is a component that runs **once**. **`{count()}`** reads the signal inside JSX: the compiler
  sees a call and makes this text follow the signal.
- **`<View onPress>`** is a native view that reacts to presses; `active:` classes are its style while pressed. `View`,
  `Text`, `Image`, `Scroll` and the other [host elements](https://nsh.dev/versions/main/elements.md) are imported from `nsh` (`Input` from `nsh/base`); only
  `If` and `Each` need no import.
- **`class`** takes [Tailwind](https://nsh.dev/versions/main/docs/tailwind.md) classes; `style={{ … }}` takes an object of camelCase style
  properties, with numbers in points. `bg-background`, `bg-primary`, `text-primary-foreground` and
  `rounded-(--radius)` name the tokens of the app's theme ([Theme tokens](https://nsh.dev/versions/main/docs/tailwind.md#theme-tokens)): they follow
  dark mode by themselves, and `"theme"` in `nsh.json` restyles them.
- **`mount(App)`** renders the component into the app's surface.

> [!IMPORTANT]
> Text shows in a text element: `text(..)` in Rust, `<Text>` in TSX. In TSX, text written straight in a `<View>`
> (`<View>Hello</View>`) is a build error that points at it, and a string an expression puts there
> (`<View>{name}</View>`) is reported in the log.

## Develop it

### Run it

`nsh run` builds the app, launches it and rebuilds while you edit; the app's logs appear in the terminal. Give it the
app's directory: it runs a Rust app's root, or a TSX app's `App.tsx` (`nsh run my-app/App.tsx` names another entry).

For a Rust app, `nsh run` builds the app's own runner for the target, with your crate and the root mounted and no
QuickJS, and starts it; a change to the Rust code builds it again and restarts the app. `cargo run` in the app's
directory starts the same root straight on the desktop backend. For a TSX app, `nsh run` starts a dev server and a
development host that loads the app from it, and patches the running app on every save.

Without `--target`, `nsh run` uses the machine you are on: an AppKit window on macOS, a Win32 window on Windows and a
GTK window on Linux. Pick another platform with `--target`:

| Target | Command | Runs from |
|---|---|---|
| iOS simulator | `nsh run my-app --target ios` | macOS with Xcode |
| Android | `nsh run my-app --target android` | macOS, Windows, Linux |
| macOS (AppKit) | `nsh run my-app` | macOS (the default) |
| Windows | `nsh run my-app` | Windows (the default) |
| Linux (GTK 4) | `nsh run my-app` | Linux (the default) |
| Web | `nsh run my-app --target web` | macOS, Windows, Linux |
| Mac Catalyst | `nsh run my-app --target catalyst` | macOS |

#### iOS simulator

```sh
nsh run my-app --target ios
nsh run my-app --target ios --device "iPhone 16 Pro"
```

`nsh` uses a booted simulator, or boots the newest iPhone if none is running, and installs the app (a Rust app's
runner, or the development host) into it. `--device` picks a simulator by name or UDID.

#### Android

```sh
nsh run my-app --target android
```

Start an emulator or connect a device first (`adb devices` lists them; NSH uses the first one). `nsh` installs the app
on it: a Rust app's own `libnsh.so`, or a development host APK (rebuilt only when the runtime changes) whose dev server
port is forwarded to the device with `adb reverse`, so it works over USB without a shared network.

#### macOS (AppKit)

```sh
nsh run my-app --target macos
```

The app opens as a desktop Mac app (AppKit, in a resizable window), with mouse, trackpad and keyboard input instead of
touches. It needs macOS 14 or later; see [macOS](https://nsh.dev/versions/main/docs/macos.md).

#### Windows (default on Windows)

```sh
nsh run my-app
```

The app opens in a desktop window (1200×800 points), with mouse, touchpad, touch and keyboard input. It needs Windows
10 1809 or later; see [Windows](https://nsh.dev/versions/main/docs/windows.md).

#### Linux (default on Linux)

```sh
nsh run my-app
```

The app opens in a GTK window (390×844 points). It needs GTK 4.14 or later; see [Linux](https://nsh.dev/versions/main/docs/linux.md).

#### Web

```sh
nsh run my-app --target web
```

`nsh` prints the page's address; open it in a browser. A Rust app runs as WebAssembly with your crate, and the open
page loads the new build by itself after a change; see [Web](https://nsh.dev/versions/main/docs/web.md).

#### Mac Catalyst

```sh
nsh run my-app --target catalyst
```

The app opens in an iPhone-sized window (390×844 points) on your Mac. This is the quickest way to see an app as a phone
shows it: no simulator to boot. It uses UIKit like iOS, so what you see is what an iPhone shows, apart from Mac-specific
behavior such as scrolling with a mouse wheel. For the Mac app itself, use `--target macos`.

### Edit it

Leave `nsh run` running and change the button's label:

```rust
text("Add one")
    .text_size(px(17.0))
    .text_color(move || theme().primary_foreground)
```

```tsx
<Text style={{ color: "white", fontSize: 17 }}>Add one</Text>
```

Save. A Rust app is built again and restarts with the new label; the count starts over. A TSX app gets a hot update:
the CLI rebuilds and sends a patch, and the host runs the changed module again and renders again only the components
whose code changed. Here that is `App`, which owns the `count` signal, so the count starts over too.

Pieces of UI move into components of their own, or plain functions that return elements:

```rust
/// The app's button: a view that answers presses.
fn tap_button(on_press: impl Fn() + 'static) -> impl IntoElement {
    view()
        .p_3()
        .rounded(px(10.0))
        .bg(move || theme().primary)
        .active(|s| s.opacity(0.6))
        .on_press(on_press)
        .child(text("Tap").text_size(px(17.0)).text_color(move || theme().primary_foreground))
}

// In App: .child(tap_button(move || count.update(|value| *value += 1)))
```

```tsx
function TapButton(props: { onPress: () => void }) {
  return (
    <View onPress={props.onPress} activeStyle={{ opacity: 0.6 }} style={{ padding: 12, borderRadius: 10, backgroundColor: "#0969da" }}>
      <Text style={{ color: "white", fontSize: 17 }}>Tap</Text>
    </View>
  );
}

// In App: <TapButton onPress={() => count.update((c) => c + 1)} />
```

In TSX, state survives when you edit a component that does not own it: tap a few times, then change `TapButton`'s
color, and the button updates while the count stays. Hot replacement works per top-level component: a function with a
capitalized name whose body contains JSX. A component renders again when its own code changes, or when the module's
code outside components changes (a constant it uses, a helper). If an edit cannot be applied in place (for example, it
imports an NSH module the running app did not import yet, or changes `nsh.json`'s capabilities), the host reloads the
whole app.

#### Errors

A Rust compile error is printed in the terminal with cargo's output, and `nsh run` builds again with the next save. A
TSX build error is printed in the terminal and shown on the device as a red overlay with the file, line and
column; the app keeps running the last good build. The overlay disappears with the next successful build (tap it to
dismiss it earlier). An exception thrown at run time is shown the same way, with its stack mapped back to your `.tsx`
source.

## Host it in your app

A native app shows NSH in a view of its own: `NshAppView` (a `UIView`) on iOS, `NshView` (an Android `View`) on
Android, `AppView` on macOS, Windows, Linux and in GPUI apps. Place it like any other view, on any screen, as many
times as you need.

A Rust root is part of the app's build: the app links your crate and mounts the root with `AppSource::Rust` on the
`AppView` of macOS, Windows, Linux, GPUI and iOS ([Building with Rust](https://nsh.dev/versions/main/docs/rust.md#an-app-written-in-rust)). A TSX app is
a module the view loads: during development from the dev server, in a release from a built bundle or a downloaded,
signed package. The sections below load TSX modules.

### iOS

Link `NativeShellDev.xcframework` in Debug and `NativeShell.xcframework` in Release ([Embedding in iOS
apps](https://nsh.dev/versions/main/docs/ios.md)), then:

```swift
import NativeShell

let app = NshAppView()
app.onError = { message in print("nsh error: \(message)") }
view.addSubview(app)   // and constrain it like any view

#if DEBUG
try app.connectDevServer(URL(string: "ws://127.0.0.1:8790/ws")!)   // `nsh dev my-app` on your Mac
#else
try app.loadBundle(at: Bundle.main.url(forResource: "bundle", withExtension: "nshc", subdirectory: "nsh")!)
#endif
```

`nsh dev my-app` serves the module to the app and pushes every save, as `nsh run` does with its own host. For the
release build, `nsh build my-app --release --out MyApp/nsh` writes the bundle into a folder you add to the app's
resources.

### Android

Add `nsh-dev.aar` for debug builds and `nsh.aar` for release builds ([Embedding in Android
apps](https://nsh.dev/versions/main/docs/android.md)), then:

```kotlin
val nsh = NshView(this)
nsh.setErrorListener { message -> Log.e("nsh", message) }
setContentView(nsh)   // or add it to any layout

if (BuildConfig.DEBUG) {
    nsh.connectDevServer("ws://127.0.0.1:8790/ws")   // with `adb reverse tcp:8790 tcp:8790`
} else {
    nsh.loadAssetBundle("nsh")   // assets/nsh, from `nsh build my-app --release --out app/src/main/assets/nsh`
}
```

### macOS, Windows and Linux

Desktop apps written in Rust embed NSH with `AppView`, from the `nsh-platform-macos`, `nsh-platform-windows`,
`nsh-platform-linux` and `nsh-platform-gpui` crates: an `NSView`, a child window, a GTK widget or a GPUI view that
mounts a Rust root or loads a built bundle. See [macOS](https://nsh.dev/versions/main/docs/macos.md#embedding-in-a-mac-app),
[Windows](https://nsh.dev/versions/main/docs/windows.md#embedding-in-a-win32-app), [Linux](https://nsh.dev/versions/main/docs/linux.md#embedding-in-a-gtk-app) and [GPUI](https://nsh.dev/versions/main/docs/gpui.md),
and [Platforms](https://nsh.dev/versions/main/docs/platforms.md#embed-in-a-native-app) for every host side by side.

### What the module may do

On iOS and Android, the host decides before loading what a module may do: `grantCapabilities` sets the network hosts
and other capabilities it may reach, and limits cap its memory, call time and node count ([Sandbox and
capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md)). To give modules your own native views (a map, a chart, a design-system
component), register them as [native components](https://nsh.dev/versions/main/docs/native-components.md).

## Ship updates as signed packages

A TSX module the app downloads after release comes as a signed package. Create a root key once and keep it offline,
certify a release key with it, and publish:

```sh
nsh keygen keys/root && nsh keygen keys/release
nsh certify --root keys/root.secret --key keys/release.pub --apps 'com.example.*' -o keys/release.cert
nsh publish my-app --key keys/release.secret --cert keys/release.cert --build 2
```

The app trusts the root's public key and loads what it downloads; NSH verifies the signature, the certificate and the
revocation list before running anything:

```swift
let support = FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask)[0]
let trust = try NshTrust(stateDirectory: support.appendingPathComponent("nsh"))
try trust.addRoot(rootPublicKey)   // the contents of keys/root.pub
let info = try await app.loadPackage(at: downloadedFile, trust: trust)
```

Android has the same flow with `NshTrust` and `NshPackage`. Hosting, delivery and revocation in detail: [Signed
packages](https://nsh.dev/versions/main/docs/signed-packages.md).

## Or ship it as a standalone app

`nsh package` builds an installable app, Rust or TSX, with no Xcode project or Gradle build of your own:

```sh
nsh package my-app --target ios-simulator --run
nsh package my-app --target android
nsh package my-app --target macos
nsh package my-app --target linux
nsh package my-app --target windows
nsh package my-app --target web
```

A Rust app is packaged with its own runner, built from your crate and NSH's crates, its root mounted; a TSX app with
the prebuilt runtime. Options, signing and icons: [Packaging](https://nsh.dev/versions/main/docs/packaging.md).

## Try it in the terminal

`nsh test` runs an app headless, with no device or window. Given a Rust app's `nsh.json` or a TSX app's entry, it
opens the app, lets it run and prints what it mounts; with `--trace`, also the native view operations and the time of
every commit ([Testing](https://nsh.dev/versions/main/docs/testing-and-trace.md)):

```sh
nsh test my-app/nsh.json --trace     # a Rust app's root
nsh test my-app/App.tsx --trace      # a TSX app's entry
```

Given a directory, it runs the app's tests: each template's `App.test.tsx` opens the app, presses its button and
checks what it shows (`nsh test my-app`). A Rust app's opens its root (`open(".")`); it can also be tested in `cargo test` with
`nsh_testing::Headless` ([Building with Rust](https://nsh.dev/versions/main/docs/rust.md#testing)).

## Next steps

- [Building with Rust](https://nsh.dev/versions/main/docs/rust.md): Rust apps, their theme, and TSX on top of a Rust crate.
- [JSX and components](https://nsh.dev/versions/main/docs/jsx-and-components.md) and [Reactivity](https://nsh.dev/versions/main/docs/reactivity.md): components and signals, in Rust and
  TSX.
- [Platforms](https://nsh.dev/versions/main/docs/platforms.md): what each platform supports, and its own page ([iOS](https://nsh.dev/versions/main/docs/ios.md),
  [Android](https://nsh.dev/versions/main/docs/android.md), [macOS](https://nsh.dev/versions/main/docs/macos.md), [Windows](https://nsh.dev/versions/main/docs/windows.md), [Linux](https://nsh.dev/versions/main/docs/linux.md)).
- [Signed packages](https://nsh.dev/versions/main/docs/signed-packages.md) and [Sandbox and capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md): delivery and
  what modules may do.
- [Project structure](https://nsh.dev/versions/main/docs/project-structure.md): what goes in `nsh.json`, assets, files.

Source: https://nsh.dev/versions/main/docs/getting-started

---

# Project structure

An NSH app is a directory with an `nsh.json` and its code: a Rust crate whose root component `nsh.json` names, or a TSX entry module, or both. Everything else (more modules, images, fonts, JSON files) is found from there: a crate's modules and its `assets/` directory, or the files the TSX entry imports, so there is no file list to maintain.

An app written in Rust is a Cargo project:

```text
my-app/
├── nsh.json           name, id, version, icon, the crate ("rust") and its root component ("root"), theme
├── Cargo.toml         the crate: nsh-core, nsh-base and your dependencies
├── src/
│   ├── lib.rs         the root component and the crate's UI set (#[native_module])
│   ├── main.rs        cargo run: the root on this machine's desktop backend
│   └── screens/       your own modules (any layout you like)
├── assets/            files the crate ships: asset!("logo@2x.png"), fonts
├── .gitignore         .nsh/ and target/
├── .nsh/              generated: the runners' sources, test entries, build output (.nsh/out)
└── target/            Cargo's build directory
```

A TSX app is an entry and the modules it imports:

```text
my-app/
├── App.tsx            the entry module: calls mount()
├── App.test.tsx       its tests (nsh test)
├── nsh.json           name, id, version, icon, Tailwind theme, capabilities
├── tsconfig.json      TypeScript settings for editors
├── .gitignore         .nsh/ and target/
├── components/        your own modules (any layout you like)
│   └── Header.tsx
├── assets/
│   ├── logo@2x.png    imported images
│   └── Inter.ttf      imported fonts
└── .nsh/              generated: type declarations, development host builds, test entries, build output (.nsh/out)
```

An app with both lists its crates in `"rust"` and has a TSX entry that imports them ([Building with Rust](https://nsh.dev/versions/main/docs/rust.md#extending-a-rust-app-with-tsx)).

Every command takes the app's directory or its entry as its argument (`nsh run my-app`, `nsh run my-app/App.tsx`). The directory of `nsh.json` and the entry is the app's root: `nsh.json` is read from there, asset paths are relative to it, and `.nsh/` is written there. In a Rust app (`nsh.json` `"root"`), the directory runs the root component; naming a TSX entry runs that instead.

## The root component

A Rust app's root is a component of its crate, which `nsh.json`'s `"root"` names by its path in the crate (`App`, `shell::Gallery`). A TSX entry is a normal module that ends by rendering the root component:

```rust
// src/lib.rs; nsh.json: { "rust": ".", "root": "App" }
mod screens;

use nsh_core::prelude::*;

/// What a TSX entry may import from the crate.
#[native_module("my-app/native")]
fn native(registry: &mut Registry) {
    registry.register::<App>().assets(assets!());
}

#[component]
pub fn App() -> impl IntoElement {
    screens::home()
}
```

```tsx
// App.tsx
import { mount } from "nsh";
import { Home } from "./components/Home";

function App() {
  return <Home />;
}

mount(App);
```

`nsh run` and `nsh package` mount a Rust root on every platform, with no QuickJS. In TSX, `mount(component, props?)` renders the component into the app's surface and returns a function that removes it again; an app calls it once. Code at the top level of the entry runs when the bundle loads, before the first frame.

## nsh.json

`nsh.json` sits in the app's root. `nsh init` writes `name`, `id`, `version` and `build`, and for a Rust app the crate and its root component:

```json
{
  "name": "Gallery",
  "id": "com.example.gallery",
  "version": "1.0.0",
  "build": 1,
  "rust": ".",
  "root": "App",
  "theme": "theme.json"
}
```

Every other key is optional; a TSX app may also leave out the four. A TSX app's `nsh.json` might read:

```json
{
  "name": "Gallery",
  "id": "com.example.gallery",
  "version": "1.0.0",
  "build": 1,
  "icon": "icon.png",
  "tailwind": {
    "colors": { "brand": { "500": "#7c3aed", "600": "#6d28d9" } },
    "radius": { "card": 14 }
  },
  "capabilities": {
    "network": { "hosts": ["api.example.com", "*.cdn.example.com"] }
  }
}
```

| Key | Type | Used by | Description |
|---|---|---|---|
| `name` | string | `package` | The display name under the app icon. Default: the entry directory's name. |
| `id` | string | `package`, `publish`, `Storage` | Bundle identifier / application id in reverse-DNS form, e.g. `com.yourcompany.app`; required by `package` and `publish`. `nsh run` uses `com.example.<name>` without one. |
| `version` | string | `package`, `publish` | The user-visible version, e.g. `1.2.0` (`CFBundleShortVersionString`, Android `versionName`). |
| `build` | number | `package`, `publish` | The build number (`CFBundleVersion`, Android `versionCode`). Signed packages require it to grow with every release. |
| `minRuntime` | string | `publish` | The lowest NSH runtime that runs the signed package, e.g. `0.2.0`. Default: the CLI's version ([Signed packages](https://nsh.dev/versions/main/docs/signed-packages.md#which-runtimes-run-a-package)). |
| `icon` | string | `package` | A square PNG, ideally 1024×1024, relative to `nsh.json`. |
| `tailwind` | object | every build | Extends the Tailwind theme your `class` strings resolve against ([Tailwind](https://nsh.dev/versions/main/docs/tailwind.md#theme)). |
| `appearance` | string | every build, `package` | `"light"`, `"dark"` or `"system"` (the default): an app that is always light or dark says so here. `colorScheme()`, `dark:` classes, the components' theme and the platform's controls follow it from the start ([Device and environment](https://nsh.dev/versions/main/docs/device-and-environment.md#dark-mode)). |
| `theme` | string or object | every build | The app's design tokens (shadcn/ui's `cssVars`, over the default `neutral` theme), which token classes, `token()` and Rust components draw with: a theme file's path relative to `nsh.json`, or the theme inline ([Building with Rust](https://nsh.dev/versions/main/docs/rust.md#theme), [Theme tokens](https://nsh.dev/versions/main/docs/tailwind.md#theme-tokens)). |
| `statusBar` | object | every build, `package` | The status bar's default under every page and dialog (iOS and Android): `{ "foreground": "auto" \| "light" \| "dark", "hidden": boolean }`, both optional. Packaged iOS apps show it from the launch screen on ([Status bar](https://nsh.dev/versions/main/modules/nsh-base.md#status-bar)). |
| `capabilities` | object | every build | What the app may reach outside its VM: network hosts, web view hosts, the status bar ([Sandbox and capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md)). |
| `resolve` | object | every build | How bare imports resolve: the export conditions of npm packages and aliases ([npm packages](#npm-packages)). |
| `rust` | string or string[] | every command | The app's Rust crate, or a list of them, relative to `nsh.json`: their components and modules, which TSX imports by each crate's `#[native_module]` specifier ([Building with Rust](https://nsh.dev/versions/main/docs/rust.md#several-crates)). |
| `web` | object | `package` | What a web package adds to its page. `web.host`: a JS module relative to `nsh.json` exporting `createHost(player)`, which answers the app's [`host`](https://nsh.dev/versions/main/modules/nsh.md#host) calls; `web.connect`: the hosts that module's own requests reach, as patterns of `capabilities.network.hosts`, which the page's Content-Security-Policy allows ([Web](https://nsh.dev/versions/main/docs/web.md#the-hosts-functions)). |
| `root` | string | `run`, `package` | A Rust app's root component, its path in the `rust` crate, the first one of a list (`App`, `shell::Gallery`): `nsh run` and `nsh package` of the app's directory mount it with no QuickJS, on every platform; `nsh run App.tsx` still runs the TSX entry ([Building with Rust](https://nsh.dev/versions/main/docs/rust.md)). |

The flags of `nsh package` and `nsh publish` (`--name`, `--id`, `--app-version`, `--build`, `--icon`, `--min-runtime`) override the file's values ([CLI](https://nsh.dev/versions/main/docs/cli.md)).

`tailwind`, `theme`, `appearance`, `statusBar`, `capabilities` and `resolve` are checked when the app is built. A typo is a build error rather than a setting that silently does nothing:

```text
error building App.tsx failed
nsh.json: tailwind: unknown theme key `colours`
```


### capabilities

Without a `capabilities` key, an app may use the network, web views and the status bar freely: a standalone app is its developer's own. With the key, everything not listed is denied, both in development and in packaged apps:

```json
"capabilities": {
  "network": {
    "hosts": ["api.example.com", "*.cdn.example.com"],
    "http": [{ "host": "quotes.example.com", "methods": ["GET"], "pathPrefix": "/v1/" }]
  },
  "webview": { "hosts": ["*.example.com"] },
  "statusBar": true
}
```

`network` covers `fetch`, remote images and video sources; local assets are always allowed. An app that embeds NSH may grant less than an app declares. The details are in [Sandbox and capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md).

## tsconfig.json and .nsh/types

NSH does not need `node_modules`. Instead, every command that builds the app (`init`, `build`, `test`, `dev`, `run`, `package`, `publish`, `check`) writes the TypeScript declarations of everything NSH provides into `.nsh/types`, and NSH's TypeScript settings into `.nsh/tsconfig.json`. The app's `tsconfig.json` extends them:

```json
{
  "extends": "./.nsh/tsconfig.json",
  "include": ["**/*.ts", "**/*.tsx"]
}
```

`.nsh/tsconfig.json` points the `nsh` imports and your app's crates to `.nsh/types`, includes the globals, asset and token declarations, and sets the compiler options NSH apps use (`lib`, `jsx`, `strict`, ...). NSH keeps it current: when a new version adds a library or a path, your app has it with the next build, and your `tsconfig.json` stays as you wrote it. Options you add to `tsconfig.json` apply over NSH's.

| File in `.nsh/types/nsh/` | Declares |
|---|---|
| `index.d.ts` | `nsh`: `signal`, `computed`, `effect`, `mount`, `View`, `Text`, ... and re-exports the types below |
| `types.d.ts` | Styles (`ViewStyle`, `TextStyle`, ...), every element's props and events, the refs (`ViewRef`, `InputRef`, ...: what a `ref` receives) |
| `jsx-runtime.d.ts` | The JSX runtime TypeScript resolves through `jsxImportSource` (the `JSX` namespace) |
| `globals.d.ts` | `If` and `Each`; `console`, timers, `requestAnimationFrame`, `fetch` and the other [global APIs](https://nsh.dev/versions/main/modules/globals.md) |
| `assets.d.ts` | What importing an image or font gives |
| `tokens.d.ts` | `Tokens`: the app's design tokens, from its `"theme"`, which type [`token()`](https://nsh.dev/versions/main/modules/nsh.md#token) |
| `mobile.d.ts`, `desktop.d.ts` | One file per module (`nsh/mobile`, `nsh/desktop`) |
| `base.d.ts` | `nsh/base` |

`lib` is `ES2023` without `DOM`: there is no `document` or `window`. The files in `.nsh` are regenerated (only when their contents change), so do not edit them and do not commit them; `.gitignore` already excludes `.nsh/`. If your editor shows `nsh` as missing after cloning a project, run any build command once, e.g. `nsh check`.

`.nsh/tsconfig.json` adds `"ESNext.Disposable"`, which declares `using` declarations and `Symbol.dispose`, which the runtime has: `using account = new Account()` frees a [Rust class](https://nsh.dev/versions/main/docs/rust.md)'s value at the end of the block. Its `jsxImportSource: "nsh"` and `jsx: "preserve"` only matter to the editor: NSH compiles JSX with its own compiler, whatever the `tsconfig.json` says. TypeScript is checked by your editor or by `nsh check`; the other commands strip types without checking them.

An app made by an earlier `nsh init` gets the new `tsconfig.json` with its next build when its own is NSH's template, unchanged; NSH prints a line saying so. A `tsconfig.json` you changed is yours: `nsh check` points out when it does not extend `./.nsh/tsconfig.json`, and you add the `extends` line and remove the options it sets.

## Modules

A Rust app's code is its crate's modules (`mod screens;`), and its dependencies come from crates.io like any crate's; NSH's own crates are `nsh-core` (the primitives, signals and typed styles, `use nsh_core::prelude::*`) and `nsh-base` (the base components and the theme).

In TSX, split the app into as many `.ts` and `.tsx` modules as you like and import them with relative paths; the extension may be left out:

```tsx
import { Header } from "./components/Header";
import { formatPrice } from "./lib/format";
import strings from "./strings.json";
```

All of them are bundled into one script. JSON files import as their parsed value.

### Leaving parts out of the binary

If you build your own executable with Cargo (embedding NSH, or your own `main`), you can leave optional parts out: the platform crates turn all of them on by default, so set `default-features = false` on the platform crate (and on `nsh-base`) and name what you keep from `js`, `shader`, `editor` (with `DiffView`), `rich-editor`, `plot`, `highlight`, `math`, `zlib` and `crypto`. An app that imports a part its build left out fails when it loads. What `nsh package` builds always includes everything.

### Loading code on demand

`import()` of one of the app's modules returns a promise of its exports, as in a browser:

```tsx
const open = async () => {
  const { Settings } = await import("./screens/Settings");
  screen.set(() => Settings);
};
```

Apps on devices ship one bundle, so the module is already there and the promise resolves at once. A web app published split (`nsh build --split`) gets the module, and what only it uses, as a separate file that is downloaded the first time `import()` asks for it ([Web](https://nsh.dev/versions/main/docs/web.md#split-bundles)). The specifier must be a literal relative path: the bundler has to see which module is meant.

### NSH's modules

Imports of `nsh` and `nsh/...` are not bundled: the runtime provides them natively.

| Module | What it has |
|---|---|
| `nsh` | Reactivity (`signal`, `computed`, `effect`, ...), `mount`, `split`, `context`; the primitives `View`, `Text`, `Scroll`, `Image`, `List`, `Canvas`, `WebView`, `Video` (`View`'s `selectable` for text selection); safe area insets (`safeArea`, `safeAreaInsets`) and the software keyboard (`Keyboard`, `keyboardFrame`); native animations; `PanResponder`; the environment (`platform`, `windowSize`, `colorScheme`, `fontScale`, `pixelRatio`, `locale`); screen reader and reduce motion state, announcements; the clipboard, the photo picker, storage, the host channel, keyboard shortcuts; components and functions the embedding app registers ([reference](https://nsh.dev/versions/main/modules/nsh.md)) |
| `nsh/base` | The unstyled foundation of an app's UI: navigation stacks and their pages (`NavStack`, `NavPage`, `createNavStack`), dialogs (`Dialog`), a press target (`Button`), a text input (`Input`) and the system's alert dialog (`AlertDialog`); pages and dialogs set the status bar (`statusBar`) ([reference](https://nsh.dev/versions/main/modules/nsh-base.md)) |
| `nsh/mobile` | What iOS and Android have: `TabBar`, `InputAccessoryView` (iOS), `BackHandler` (Android) ([reference](https://nsh.dev/versions/main/modules/nsh-mobile.md)) |
| `nsh/desktop` | What macOS, Windows and Linux have: `Window`, `titleBar`, `Menu` ([reference](https://nsh.dev/versions/main/modules/nsh-desktop.md)) |

The [modules reference](https://nsh.dev/versions/main/modules.md) documents each one. Importing a module NSH does not have (`nsh/foo`) is a build error. So is a name your code uses that the module does not export (`import { Buton } from "nsh/base"`): the error points at the import and names the closest export (``did you mean `Button`?``). Names used only as types are checked by `nsh check`.

### npm packages

NSH needs nothing from npm, but the bundler resolves bare imports from a `node_modules` directory if you install packages with a package manager. Packages resolve their browser builds, because the runtime provides web APIs (`fetch`, streams, `URL`, `TextEncoder`, ...) and not Node's (`fs`, `Buffer`, `process`). Packages that touch the DOM do not work: there is none.

A package whose browser build uses the DOM often has another build for workers or React Native. `resolve.conditions` picks the export conditions packages resolve with, in place of the default `["browser"]`: `import`, `require`, `module` and `default` always apply, and without `browser` packages resolve through their `module` and `main` fields. `resolve.alias` replaces an import: by a path relative to `nsh.json` (`./` or `../`), another package, or `false` for an empty module. TypeScript (`nsh check`, editors) types the import as written: a name that is not an installed package gets its types from a `.d.ts` file of the app.

```json
"resolve": {
  "conditions": ["worker"],
  "alias": { "dom-only-helper": "./shims/helper.ts", "node-polyfill": false }
}
```

```ts
// shims/aliases.d.ts
declare module "node-polyfill";
```

`solid-js` cannot be imported: the bundler refuses it and points to `nsh`'s own `signal`, `computed` and `effect`, which replace it.

## Assets

Images and fonts ship with the app. A Rust crate reads each file of its `assets/` directory at compile time with `asset!`, and ships them all with `registry.assets(assets!())` in its `#[native_module]` function; TSX imports them like modules, and the bundler records each imported file (and an image's pixel-density variants). `nsh build` copies them to `.nsh/out/assets/`, `nsh package` puts them in the app, and during development they are served to the app.

```rust
use nsh_core::element::{FontAsset, ImageAsset, asset};

const LOGO: ImageAsset = asset!("logo@2x.png");      // its url, and its size: 64×64 points
const INTER: FontAsset = asset!("Inter.ttf");        // its uri, and its family: "Inter"

image(LOGO)
text("Hello").font_family(INTER.family)
```

```tsx
import { Image, Text } from "nsh";
import logo from "./assets/logo@2x.png";   // { url: "asset:/assets/logo@2x.png", size: { width: 64, height: 64 } }
import Inter from "./assets/Inter.ttf";     // "Inter"

<Image src={logo} />
<Text style={{ fontFamily: Inter }}>Hello</Text>
```

| Extension | Import gives |
|---|---|
| `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.heic` | An `ImageAsset`: `{ url, size, scales? }`, sized in points. An `@2x` / `@3x` suffix divides the pixel size by 2 / 3. A file without a suffix also ships its `@1.5x`–`@4x` siblings, listed in `scales`, and the screen's variant is loaded ([pixel densities](https://nsh.dev/versions/main/docs/images-and-assets.md#pixel-densities)). |
| `.svg` | An `ImageAsset` sized in points by the SVG's `width` and `height` (or `viewBox`). |
| `.ttf`, `.otf`, `.woff`, `.woff2` | The font's family name, a string. The font is registered before the first frame. |
| `.json` | The parsed JSON |

See [Images and assets](https://nsh.dev/versions/main/docs/images-and-assets.md) and [Fonts](https://nsh.dev/versions/main/docs/fonts.md).

## Generated directories

- **`.nsh/`**: everything NSH generates: the type declarations (`.nsh/types`), the sources of a Rust app's runners (`.nsh/rust`), what `nsh run` installs on simulators and devices (the Catalyst host app, the Android development APK), and `.nsh/out`, the default output of `nsh build` (`bundle.js`, `bundle.js.map`, `bundle.nshc`, `capabilities.json`, `assets/`; for a Rust app, `app.json` and `assets/`) and `nsh package` (`.app`, `.ipa`, `.apk`, a site); `-o` writes elsewhere. Safe to delete; it is recreated.
- **`target/`**: Cargo's build directory for an app's crates and runners (or `CARGO_TARGET_DIR`).

Source: https://nsh.dev/versions/main/docs/project-structure

---

# Building with Rust

Native Shell apps are written in Rust, in TSX, or in both. All three run on the same engine: the reactive graph, the
renderer, Taffy layout and the native modules (navigation, dialogs, the keyboard, the status bar) are Rust in every case, and every platform renders with its
own UI. What differs is the language of your own code, and with it whether the app carries a JavaScript VM.

| | Rust | TSX | Rust with TSX |
|---|---|---|---|
| Your UI, state and handlers | Rust | TSX on QuickJS | Rust components and modules, TSX screens that use them |
| The app runs | the engine and your crate only, on every platform and in the browser | QuickJS and the engine (in the browser, its JavaScript engine) | QuickJS and the engine, with your crate (in the browser, its JavaScript engine) |
| Suits | Medium and large apps with demanding business logic | Apps and modules delivered at run time, quick iteration | A Rust core with parts that change often |
| Edits | Rebuild and restart | Hot updates | Hot updates for TSX, rebuild and restart for Rust |
| Start | `nsh init my-app --template rust` | `nsh init my-app --template ts` | `nsh init my-app --template mixed` |

## Choosing

**Rust** suits apps whose business logic is large and demanding: trading, editors, data-heavy tools. You get Rust's
type system and compile-time checks across the whole app, the crates.io ecosystem, native performance for your own
code (not only for NSH's), and headless tests of the real UI with `cargo test`. The app is Rust and native code from
start to end: no JavaScript VM ships with it or runs in it, on iOS, Android, macOS, Windows, Linux, GPUI and the web.
Components are functions that run once and bind signals to what they show, as in TSX ([Reactivity](https://nsh.dev/versions/main/docs/reactivity.md)),
written with typed styles instead of class strings.

**TSX** suits UI that arrives after the app ships: modules a native app loads at run time, generated by a model or
written by another team, delivered as [signed packages](https://nsh.dev/versions/main/docs/signed-packages.md) and run in a sandbox the host configures,
with hot updates while you develop.

**Rust with TSX** keeps the Rust core and adds TSX where it pays off: screens, settings, onboarding, experiments,
anything you iterate on with hot updates or deliver at run time as a [signed package](https://nsh.dev/versions/main/docs/signed-packages.md). TSX
imports your Rust components and modules like any NSH module, so the two halves meet at typed interfaces. The TSX
runs on QuickJS, which the app then carries.

## An app written in Rust

```sh
nsh init my-app --template rust
cd my-app
nsh run                        # this machine's backend; --target ios, android, web, macos, linux or windows
nsh package --target web       # or ios, ios-simulator, android, macos, linux, windows
```

`src/lib.rs` holds the app: components, state, handlers, tasks.

```rust
use nsh_base::{button, theme};
use nsh_core::prelude::*;

/// The components available to TSX through `app/native`.
#[native_module("app/native")]
fn native(registry: &mut Registry) {
    registry.register::<App>();
}

#[component]
pub fn App() -> impl IntoElement {
    let count = signal(0_u32);
    let quote = signal(SharedString::from("…"));
    // Async work runs in tasks; requests go through NSH's network stack.
    spawn(async move {
        if let Ok(response) = fetch("https://api.example.com/quote").await {
            quote.set(response.text().into());
        }
    });
    view()
        .flex_1()
        .items_center()
        .justify_center()
        .gap_4()
        .child(text(move || format!("Count: {}", count.get())))
        .child(text(quote))
        .child(
            // nsh_base's unstyled button, drawn with the theme's colors.
            button()
                .px(px(20.0))
                .py(px(12.0))
                .rounded(move || theme().radius)
                .bg(move || theme().primary)
                .active(|s| s.bg(move || theme().primary.opacity(0.9)))
                .on_press(move || count.update(|c| *c += 1))
                .child(text("Tap").text_color(move || theme().primary_foreground)),
        )
}
```

Elements and components are made the same way: a function makes one (`view()`, `text(..)`, `nsh_base`'s
`button()`, your `#[component] fn Chart`'s `chart()`), and its methods set its props, one setter per prop (a value,
a signal or a closure), and its listeners, one method per event. Listeners are closures of their event
(`move |text: &str| ..`), and `move || ..` for an event without data; `.child(..)` takes an element, or an
`Option`, a `Vec`, an array or an iterator of elements (`.child(rows.iter().map(|r| row(r)))`).

`nsh.json` names the root, and `nsh` mounts it:

```json
{
  "name": "My App",
  "rust": ".",
  "root": "App",
  "theme": "theme.json",
  "appearance": "system"
}
```

`"root"` is the component's path in the crate (`App`, `shell::Gallery`; in the first one with
[several crates](#several-crates)); `"theme"` is the [theme](#theme) its components draw with, and `"appearance"` applies to it as it does to a TSX app. With it,
`nsh run` and `nsh package` of the app's directory build the app's own runner for the target, with the root mounted
and no QuickJS linked in:

| Target | What runs |
|---|---|
| macOS, Windows, Linux | The release runner with your crate, in a window; `nsh run` runs a debug build and shows the app's logs in the terminal |
| iOS, the iOS simulator, Mac Catalyst | The iOS runner with your crate, in an app |
| Android | The app's `libnsh.so` with your crate, started by the runtime's activity |
| Web | `nsh.wasm` with the engine and your crate (3.3 MB for the whole Rust gallery, 0.75 MB with brotli); the page mounts the root |

`nsh` builds what your crate needs and nothing more: a small program of your crate and NSH's core that describes its
components and modules to the CLI, which then does the rest itself, and the runner of each target you run or
package. The first build of a new Rust app compiles your crate and NSH's core, about 60 crates. `nsh test` runs
the app's tests headless in a runner of your crate built the same way.

On Linux, your crate selects optional platform features. Enable `webview` on your
`nsh-platform-linux` dependency to use web views; this links WebKitGTK 6.0, which must be installed to build and run
the app. The generated runner inherits that choice through Cargo feature unification.

During `nsh run`, a change to the crate's Rust code builds the runner again and restarts the app; in the browser,
the open page loads the new runtime by itself. `cargo run` starts the same root directly on the desktop backend
(`src/main.rs`), and native apps that embed NSH mount a Rust root with `AppSource::Rust` on the `AppView` of macOS,
Windows, Linux, GPUI and iOS.

Code for every platform, the web included, uses NSH's services: `fetch` for HTTP
([Networking](https://nsh.dev/versions/main/docs/networking.md#from-rust-components)), `timer`, `set_timeout` and `set_interval` for waiting,
`nsh_core::time::Instant` and `nsh_core::time::unix_ms()` for the clock. `background` and `blocking` run work on the
native targets' threads.

## Desktop title bars

Rust apps draw their own title bars with `nsh_core::element::desktop`. Call
`set_title_bar(TitleBarStyle::Hidden, Some(height))`, mark the bar's background
with `.window_drag(true)`, and reserve the native window controls' space with
`title_bar()`. Its `top` is the bar's height, and `left` and `right` are the widths
occupied by the system controls. Reading it subscribes to changes, including full
screen. The platform handles window dragging and the user's title-bar double-click
behavior; `.window_drag(false)` keeps a child out of its parent's drag region.

```rust
use nsh_core::{
    desktop::TitleBarStyle,
    element::{desktop::{close_window, set_title_bar, title_bar}}, prelude::*,
};

fn window_bar() -> impl IntoElement {
    set_title_bar(TitleBarStyle::Hidden, Some(px(42.0)));
    view()
        .h(px(42.0))
        .flex_row()
        .items_center()
        .window_drag(true)
        .pl(move || title_bar().left + px(12.0))
        .pr(move || title_bar().right + px(12.0))
        .child(text("My app").flex_1())
        .child(text("Close").window_drag(false).on_press(close_window))
}
```

`set_title_bar(TitleBarStyle::Default, None)` restores the system title bar.
`close_window()` follows the embedding host's normal window-close behavior.
The module has the window's other functions (`set_title`, `minimize`,
`toggle_full_screen`, ...) and the menus (`set_application_menu`,
`popup_menu`) too: [nsh/desktop](https://nsh.dev/versions/main/modules/nsh-desktop.md).

## Files and folders

On the desktops, Rust code shows the system's file dialogs and hands local paths to
the system, each answer awaited in a task: `pick_paths` with an `OpenDialog`
(`OpenDialog::files()`, `::folders()` or `::files_and_folders()`), `pick_save_path`
with a `SaveDialog`, `open_path` (the file's default app), `reveal_path` (the item
selected in Finder, File Explorer or the file manager) and `move_to_trash` (where the
item went, when macOS says). The dialogs answer `Ok(None)` when the user cancels and
an error when they cannot show (on Linux without a file chooser portal, and on iOS,
Android and the web, where `open_path`, `reveal_path` and `move_to_trash` answer
an error too). Every request that fails answers its error, never `false`.

```rust
use nsh_core::{
    file_dialog::{FileFilter, OpenDialog},
    prelude::*,
};

fn open_notes() {
    let picked = pick_paths(
        OpenDialog::files()
            .multiple(true)
            .filter(FileFilter::new("Markdown", ["md", "markdown"]))
            .button_label("Open"),
    );
    spawn(async move {
        match picked.await {
            Ok(Some(paths)) => {
                for path in paths {
                    let _ = reveal_path(path).await;
                }
            }
            Ok(None) => {} // Cancelled.
            Err(error) => log::warn!("no file dialog: {error}"),
        }
    });
}
```

## Extending a Rust app with TSX

The crate's `#[native_module("app/native")]` function names what TSX may import: components
(`registry.register::<Chart>()`), modules of functions (`registry.module::<Portfolio>()`, `#[module]` on a unit struct and its `impl`),
classes (`registry.class::<Ledger>()`, `#[class]` on a struct and its `impl`) and assets; the attribute also makes
`pub fn registry()` at the crate's root, the same set for your tests and other Rust code (`my_app_native::registry()`,
next to `nsh_base::registry()`). In a `#[module]` or
`#[class]` `impl`, the `pub fn`s are exported (`pub(crate)` too); functions without a visibility are helpers that
stay in Rust. Their TypeScript
declarations, doc comments included, are generated from the Rust types into `.nsh/types`, so TSX is checked against
them by `nsh check` and your editor:

```rust
/// A price chart.
#[derive(Clone, PartialEq, Props)]
pub struct ChartProps {
    /// The symbol to chart.
    pub symbol: Prop<SharedString>,
    /// The range shown.
    #[prop(default = SharedString::from("1D"))]
    pub range: Prop<SharedString>,
}

#[derive(Event)]
pub enum ChartEvent {
    /// A price was selected.
    #[args(price)]
    Select(f64),
}

/// A price chart; a press selects the last price.
#[component]
pub fn Chart(props: ChartProps, cx: Scope<ChartEvent>) -> impl IntoElement {
    view()
        .h(px(160.0))
        .bg(move || theme().muted)
        .on_press(move || cx.emit(ChartEvent::Select(101.5)))
        .child(text(move || format!("{} · {}", props.symbol.get(), props.range.get())))
}

/// A ledger kept in Rust.
#[class]
pub struct Ledger {
    entries: Vec<f64>,
}

#[class]
impl Ledger {
    /// An empty ledger.
    pub fn new() -> Self {
        Ledger { entries: Vec::new() }
    }

    /// Adds `amount`; the new balance.
    pub fn add(&mut self, amount: f64) -> f64 {
        self.entries.push(amount);
        self.balance()
    }

    /// The balance.
    #[getter]
    pub fn balance(&self) -> f64 {
        self.entries.iter().sum()
    }

    /// Uploads the entries; resolves when the server has them.
    pub async fn upload(this: Instance<Ledger>, url: String) -> Result<(), String> {
        let body = this.with(|l| format!("{:?}", l.entries));
        fetch(HttpRequest::post(url, body)).await.map(|_| ())
    }
}

/// The app's holdings.
#[module]
pub struct Portfolio;

#[module]
impl Portfolio {
    /// The value of the holdings.
    pub fn total() -> f64 {
        1250.0
    }
}
```

```tsx
import { mount, signal, View, Text } from "nsh";
import { Chart, Ledger, Portfolio } from "app/native";   // Rust

const ledger = new Ledger();   // its state lives in Rust

function Overview() {
  const balance = signal(ledger.add(Portfolio.total()));   // Rust, called at once
  return (
    <View class="gap-2 p-4">
      <Text>Balance: {balance()}</Text>
      <Chart symbol="NSH" range="1M" onSelect={(e) => balance.set(ledger.add(e.price))} />
      <View onPress={() => ledger.upload("https://example.com/ledger")} role="button" class="rounded-lg bg-blue-600 px-4 py-2 active:bg-blue-700">
        <Text class="text-white">Upload</Text>
      </View>
    </View>
  );
}

mount(() => <Overview />);
```

Each export is documented in TypeScript by the doc comment of the Rust item that names it: a component by its
`#[component] fn` (`Chart`), a module and a class by their struct (`Portfolio`, `Ledger`), and props, events,
functions and members by their own (a setter needs none beside its getter). The `Props` struct's and the event
enum's own doc comments, and those of `impl` blocks, stay in Rust; a doc comment on a `#[module]` or `#[class]`
`impl` block is a compile error, since TypeScript would not show it. Each command that writes `.nsh/types` warns
about an export TSX sees without a doc comment, naming it (`Ledger.add`, `Chart.range`).

TypeScript shows a doc comment up to its first heading. Notes for Rust callers, such as what `&self` borrows or
why a function takes `cx`, go under a heading, `# Rust` (or rustdoc's `# Panics`, `# Examples`), and stay in the
Rust docs:

```rust
/// Puts `text` on the clipboard; resolves with the number of characters copied.
///
/// # Rust
///
/// Taking `cx` makes it an op, run in order with the UI changes TS made before it.
pub fn copy(text: String, cx: &mut ModuleCx) -> u32 {
    let count = text.chars().count() as u32;
    cx.set_clipboard(text);
    count
}
```

Props are the fields of the component's `Props` struct and events the variants of its `Event` enum (`onSelect`),
both in camel case. Rust code places the same component with its constructor, a setter per prop and a listener
method per event: `chart().symbol("NSH").range("1M").on_select(move |price: &f64| last.set(*price))`. A Rust component's own content, events and state stay in Rust; TSX passes props in and hears
events. A prop of the wrong type (`level={1.5}` for a `u32` prop) is a warning, as on a built-in element: the
prop keeps its value and the rest of the component renders.

A function or a member runs the way its Rust signature says. One that is not `async` runs inside the TSX call and
returns its value (`Portfolio.total()` is a number, `ledger.balance` a property): it computes and keeps state. An
`async fn` returns a Promise and runs as a task with NSH's services (`fetch`, `timer`, dialogs). A module function
taking `cx: &mut ModuleCx` reaches the platform in order with the UI (a toast, the status bar), and so does a
component's ref method; their return type decides what TSX gets: one returning `()` gives `void`, with no reply
(TSX calls it and moves on); one returning `Result<(), E>` gives `Promise<void>`, which rejects with the `Err`'s
message (the call runs with the UI's changes, after the TSX call returned, so the Promise carries its error; one
nobody awaits or catches is logged as an [unhandled rejection](https://nsh.dev/versions/main/docs/dev-server-and-debugging.md#logs)); one
returning a value gives `Promise<T>`. Arguments and results are typed from the signature: numbers, strings, `Option`, `Vec`, your
`#[derive(JsObject)]` structs and `#[derive(PropEnum)]` enums, instances of your classes, and TSX functions
(`Callback<A, R>`, which Rust calls at once inside a call, or later with `post` and `call_async`; TS sees
`(value: number) => void` for a `Callback<f64>`, and `#[args(balance)] listener: Callback<f64>` names the argument,
`(balance: number) => void`). A function that starts listening is named `on(event, listener)` and returns `Stop`
(`Stop::new(|| …)`), which TSX gets as a function that stops it (`() => void`); it runs once, when TSX calls it or
when what called `on` goes (a component, or the module's run under hot reload). An event's handler gets one object: a variant's value is its field `value`, which
`#[args(price)]` on the variant names (`onSelect({ price })`), and `#[args(open, reason)]` names the fields of a
variant of several. An argument of
the wrong type throws a `TypeError` in the call, or rejects the Promise of one that returns a Promise; an `Err`
throws (or rejects) with its message. A class's object owns its Rust value: it is freed when the object is collected, or at
once with `ledger.dispose()` (also `using ledger = new Ledger()`). Name the TSX entry to run it, `nsh run App.tsx` or `nsh package App.tsx --target …`: TSX edits are hot
updates, Rust edits rebuild and restart the app. The CLI bundles and compiles the TSX itself, knowing your crate's
exports from its description; the development hosts and `nsh test`'s headless runner are built with your crate and
QuickJS.

`examples/rust-exports` in the repository is the reference for exporting: a small TSX app whose crate exports one
component (props required, defaulted and optional, an event, children), one module (a function of each kind) and
one class (a constructor, methods, a getter and a setter, a static, an `async` member, another instance as an
argument, a callback Rust posts to, `dispose()` and `using`), each with a short doc comment, and tests, in Rust and
in TypeScript (`App.test.tsx`), that press through the app and check what each one shows.

`examples/gallery-rs` in the repository is a complete Rust app: every demo is Rust, `nsh run examples/gallery-rs
--target web` (or `ios`, `android`, …) runs its root, `nsh test examples/gallery-rs` runs its tests headless, and
`cargo run -p gallery-native` starts it on the desktop backend.

### Render functions and the app's classes

A component draws content of the app's for values it has (a row of its data, a code block of a document) with a
render function: a prop `Option<Renderer<T>>`, in TypeScript `(value: T) => JSX.Element`. The component calls
`render(key, value)` where the content goes and gets a view it styles and places as any other (inside a `text(..)`, an
inline view). The content is kept per key while the value stays equal, and rendered again when it changes. A Rust
parent passes a closure to the prop's setter (`quote().render_badge(|symbol| ..)`), which makes the
`Renderer` of it.

Styles in a component are typed; the app's Tailwind classes reach one of its parts through a prop of classes and
`.app_class(..)` on that part's element. They apply after the element's own styles, with the app's theme, `dark:` and
the states, as `class` on an element does.

```rust
/// A quote: its symbol, then content of the app's.
#[derive(Clone, Copy, PartialEq, Props)]
pub struct QuoteProps {
    /// The symbol.
    pub symbol: Prop<SharedString>,
    /// Tailwind classes of the symbol's text.
    pub symbol_class: Prop<Option<SharedString>>,
    /// Content of the app's after the symbol (a change, a badge).
    pub render_badge: Prop<Option<Renderer<SharedString>>>,
}

/// A quote of a symbol.
#[component]
pub fn Quote(props: QuoteProps) -> impl IntoElement {
    view()
        .flex_row()
        .items_center()
        .gap_2()
        .child(text(props.symbol).app_class(props.symbol_class))
        .child(dynamic(move || {
            props.render_badge.get().map(|r| r.render("badge", props.symbol.get()).flex_1())
        }))
}
```

```tsx
<Quote
  symbol="NSH"
  symbolClass="text-lg font-semibold"
  renderBadge={(symbol) => <Text class="text-green-600">{`${symbol} ▲ 2.4%`}</Text>}
/>
```

`TextView` in `nsh/base` is built this way: its `renderCodeBlock`, `renderMath`, ... are render functions, and its
`classes` are the app's classes by part ([TextView](https://nsh.dev/versions/main/elements/text-view.md)).

## Testing

A Rust app's tests run it headless, in `cargo test` or in `nsh test`, with the same driver: on the real engine,
without a window, with display frames at 60 Hz, so timers, tasks and animations run as on screen. The driver starts
the app, keeps a model of the views it shows and takes steps (`press`, `type_text`, `submit`, `scroll`, `wait_for`)
on views named by selectors (a text, an accessibility label or a test id; `text:`, `label:`, `id:`); a step that
cannot be taken fails with the texts on screen.

In `cargo test`, `nsh_testing::Headless` (nsh-testing's default features, without QuickJS) runs the root
(`app.screen()`: the texts on screen, the commands it sent); `EngineConfig::new` is a phone-sized engine with nothing
else set. `nsh test` runs TypeScript tests ([Testing](https://nsh.dev/versions/main/docs/testing-and-trace.md)) in a headless runner built with your
crates, where `open(".")` starts a Rust app's root:

```toml
[dev-dependencies]
nsh-engine = "0.1"
nsh-testing = "0.1"
```

```rust
// tests/app.rs: cargo test
use nsh_engine::{EngineConfig, Root};
use nsh_testing::Headless;

#[test]
fn a_tap_counts() {
    let mut app = Headless::start(EngineConfig::new(Root::of::<my_app::App>())).unwrap();
    app.wait_for("Count: 0").unwrap();
    app.press("Tap").unwrap();
    app.wait_for("Count: 1").unwrap();
}
```

```tsx
// App.test.tsx, next to nsh.json: nsh test
import { expect, open, test } from "nsh/test";

test("a tap counts", async () => {
  const app = await open(".");
  await app.press("Tap");
  expect(app.texts()).toContain("Count: 1");
});
```

A TSX entry is built with `nsh-testing`'s feature `bundle` as `nsh run` builds it, against the UI sets its hosts
serve: NSH's, and each crate's `registry()`, which `#[native_module]` makes:

```toml
[dev-dependencies]
nsh-testing = { version = "0.1", features = ["bundle"] }
nsh-base = "0.1"
```

```rust
#[test]
fn the_module_formats_money() {
    let sets = vec![nsh_base::registry(), my_app_native::registry()];
    let mut app = nsh_testing::tsx("../App.tsx", sets).unwrap();
    app.wait_for("Formatted at once: $1,234.50").unwrap();
}
```

`nsh_testing::compile_tsx` builds the entry once for several tests, and `nsh_testing::start` hands the
batches to a test that keeps its own model of the screen. `examples/rust-exports` tests its TSX entry this way;
`examples/gallery-rs` tests its Rust root in TypeScript, a test file for about each demo.

## Theme

The look of an app is the app's own: NSH provides the primitives and the unstyled base components of `nsh_base`, and
your crate is the styled layer on top, the app's own component library ([Three layers](https://nsh.dev/versions/main/docs/architecture.md#three-layers)). Rust components take their colors, corner radius and fonts from a theme, `theme()` from
`nsh_base`, so one file restyles every component of the app. Each color has a light and a dark value;
when the system switches appearance, a binding such as `.bg(move || theme().primary)` changes color natively, with no
render.

The theme has the design tokens of [shadcn/ui](https://ui.shadcn.com/docs/theming), and its default is shadcn's
`neutral` theme, a black-and-white palette with a 10 pt corner radius. To use your own, set `"theme"` in `nsh.json`
to the path of a theme file, relative to `nsh.json`, or to the theme's content inline:

```json
{
  "name": "My App",
  "rust": ".",
  "theme": "brand-theme.json"
}
```

A theme file is shadcn's `cssVars`, the format of shadcn's themes and registry items, so a theme exported from
[shadcn's themes](https://ui.shadcn.com/themes) or [tweakcn](https://tweakcn.com) works as it is. `light` sets the
values of the light appearance, `dark` those of the dark one, and `theme` those of both:

```json
{
  "cssVars": {
    "theme": {
      "radius": "0.5rem",
      "font-sans": "Inter, sans-serif"
    },
    "light": {
      "primary": "oklch(0.541 0.281 293.009)",
      "primary-foreground": "oklch(0.969 0.016 293.756)",
      "ring": "var(--primary)",
      "up": "#16a34a"
    },
    "dark": {
      "primary": "oklch(0.702 0.183 293.541)",
      "primary-foreground": "oklch(0.283 0.141 291.089)",
      "up": "#4ade80"
    }
  }
}
```

- Your theme is applied over the default theme, so you list only what you change. A value `light` sets and `dark`
  leaves out is used in both appearances.
- Values are written as in CSS. Colors are any CSS color (`#7c3aed`, `rgb(…)`, `hsl(…)`, `oklch(…)`, `white`),
  `color-mix(in oklab, var(--primary) 80%, white)`, or another token of the same appearance, `var(--primary)` (with a
  fallback: `var(--brand, #7c3aed)`). Lengths are `rem` (16 points) or `px` (points). Fonts are font family lists:
  the first family that is not a generic one is used, and a generic first family (`system-ui`, `sans-serif`) is the
  system font.
- **Your own tokens.** Any other name is a token of the app, as a variable in Tailwind's `@theme` is: `"up"` above is
  `theme().color("up")` in Rust, `bg-up` / `text-up/70` in classes and `token("up")` in TSX
  ([Theme tokens](https://nsh.dev/versions/main/docs/tailwind.md#theme-tokens)). A number such as `"radius-card": "14px"` is `theme().number("radius-card")`
  and `rounded-(--radius-card)`.
- The bundler checks the theme when it builds: a missing file, invalid JSON or a theme other than `cssVars` fails the
  build with an `nsh.json: theme: …` error.

The tokens, with their default light and dark values (shadcn's `neutral`):

| Token | `theme()` | Light | Dark | Role |
|---|---|---|---|---|
| `background` / `foreground` | `background` / `foreground` | `oklch(1 0 0)` / `oklch(0.145 0 0)` | `oklch(0.145 0 0)` / `oklch(0.985 0 0)` | The app's background, and the text on it |
| `card` / `card-foreground` | `card` / `card_foreground` | `oklch(1 0 0)` / `oklch(0.145 0 0)` | `oklch(0.205 0 0)` / `oklch(0.985 0 0)` | Cards and grouped surfaces, and the text on them |
| `popover` / `popover-foreground` | `popover` / `popover_foreground` | `oklch(1 0 0)` / `oklch(0.145 0 0)` | `oklch(0.205 0 0)` / `oklch(0.985 0 0)` | Popovers, menus and tooltips, and the text on them |
| `primary` / `primary-foreground` | `primary` / `primary_foreground` | `oklch(0.205 0 0)` / `oklch(0.985 0 0)` | `oklch(0.922 0 0)` / `oklch(0.205 0 0)` | The main action (a primary button), and the text on it |
| `secondary` / `secondary-foreground` | `secondary` / `secondary_foreground` | `oklch(0.97 0 0)` / `oklch(0.205 0 0)` | `oklch(0.269 0 0)` / `oklch(0.985 0 0)` | Secondary actions, and the text on them |
| `muted` / `muted-foreground` | `muted` / `muted_foreground` | `oklch(0.97 0 0)` / `oklch(0.556 0 0)` | `oklch(0.269 0 0)` / `oklch(0.708 0 0)` | Quiet surfaces; secondary text: captions, labels, placeholders |
| `accent` / `accent-foreground` | `accent` / `accent_foreground` | `oklch(0.97 0 0)` / `oklch(0.205 0 0)` | `oklch(0.269 0 0)` / `oklch(0.985 0 0)` | A hovered or highlighted item, such as a menu item or list row, and its text |
| `destructive` | `destructive` | `oklch(0.577 0.245 27.325)` | `oklch(0.704 0.191 22.216)` | Destructive actions and errors |
| `border` | `border` | `oklch(0.922 0 0)` | `oklch(1 0 0 / 10%)` | Dividers and borders |
| `input` | `input` | `oklch(0.922 0 0)` | `oklch(1 0 0 / 15%)` | The border of inputs |
| `ring` | `ring` | `oklch(0.708 0 0)` | `oklch(0.556 0 0)` | Focus rings |
| `chart-1` … `chart-5` | `chart_1` … `chart_5` | `oklch(0.87 0 0)` … `oklch(0.269 0 0)` | the same | The series of a chart |
| `sidebar`, `sidebar-foreground`, `sidebar-primary`, `sidebar-primary-foreground`, `sidebar-accent`, `sidebar-accent-foreground`, `sidebar-border`, `sidebar-ring` | `sidebar`, `sidebar_foreground`, ... | `sidebar` `oklch(0.985 0 0)`, `sidebar-primary` `oklch(0.205 0 0)` | `sidebar` `oklch(0.205 0 0)`, `sidebar-primary` `oklch(0.488 0.243 264.376)` | A sidebar's surface, its main action, its highlighted item, borders and focus ring |
| `radius` | `radius` | `0.625rem` (10 pt) | | The corner radius |
| `font-sans` | `font_sans` | the system font | | The app's font: every text that sets no family of its own |
| `font-mono` | `font_mono` | the system monospace font | | The monospaced font: `font-mono`, code in `TextView` |

## Several crates

An app's Rust code can be split into crates, each imported by its own specifier: `"rust"` takes a list of crate
paths, and each crate in it has its own `#[native_module]` function.

```json
{
  "rust": ["native/charts", "native/storage"],
  "root": "App"
}
```

```tsx
import { Chart } from "app/charts";        // native/charts: #[native_module("app/charts")]
import { Store } from "app/storage";       // native/storage: #[native_module("app/storage")]
```

Every runner and host links all of them, and `.nsh/types` declares each specifier. Crates share code through Cargo
path dependencies (`shared = { path = "../shared" }`): a crate of company components can be used by several crates
and listed by several apps, and only the crates listed in `"rust"` export to TSX. Each listed crate has a package
name and a specifier of its own; `nsh` reports a repeated one with the two paths that share it. A Rust app's
`"root"` is a component of the first crate listed. During `nsh run` and `nsh dev`, a change to any of them, or to a
crate they depend on by path, rebuilds the app and restarts it.

## Browser APIs on the web

On the web, a crate can call the browser's APIs (a WebSocket, `IndexedDB`, …) through wasm-bindgen and `web-sys`;
`nsh` builds the glue they need with the runtime. See [Web](https://nsh.dev/versions/main/docs/web.md#browser-apis-from-rust).

## See also

- [Project structure](https://nsh.dev/versions/main/docs/project-structure.md): every key of `nsh.json`.
- [Web](https://nsh.dev/versions/main/docs/web.md#apps-with-rust-components): Rust apps in the browser.
- [Networking](https://nsh.dev/versions/main/docs/networking.md#from-rust-components): `fetch` from Rust.
- [CLI](https://nsh.dev/versions/main/docs/cli.md#nsh-init): `nsh init --template rust` and `--template mixed`.

Source: https://nsh.dev/versions/main/docs/rust

---

# CLI

`nsh` is the tool an NSH app is built with, in Rust or TSX. Every subcommand that builds an app takes `[ENTRY]`: the app's directory (default: the current one, so `cd my-app && nsh run` works), which runs a Rust app's root component (`nsh.json` `"root"`) or a TSX app's `App.tsx`, or a TSX entry module. It reads `nsh.json` in the app's root and refreshes the type declarations in `.nsh/types`.

```text
nsh <COMMAND>

  init         Create an app in Rust or TSX
  build        Build an app: describe a Rust app's crates, or bundle a TSX app and compile it to QuickJS bytecode
  test         Run an app's tests headless, and its Rust crates' with cargo test
  check        Type check an app with TypeScript's native compiler, and its Rust crates with cargo check
  dev          Serve an app to dev hosts (simulators, devices) and push rebuilds
  run          Like dev, and also run the app in a development host
  package      Package an installable app from the prebuilt runtime
  keygen       Create a signing key
  certify      Certify a release key with a root key
  publish      Build an app in release mode and sign it into a package (.nshpkg)
  verify       Verify a package
  symbolicate  Map the positions in a reported error stack to the app's sources
  revoke       Sign a revocation list
```

`nsh <command> --help` prints the flags of a command; `nsh -V` (`--version`) prints the version and the Git revision it was built from.

## Output

Every command prints one line per step, and the details only when something fails:

```text
✓ built the Rust crate gallery-native (5.0s)
✓ built App.tsx (500 B js, 809 B bytecode, 21ms)
✓ built the development host for the iOS simulator (12.7s)
• iOS Simulator (iPhone 16 Plus) connected, build 1
warn iOS Simulator: image failed: An SSL error has occurred and a secure connection to the server cannot be made.
✓ rebuilt App.tsx (18ms), 1 device
```

`✓` is a finished step, `→` where to connect, `•` what a device did; `warn` and `error` lines are problems, and
plain lines are your app's own output (`console.log`). On a terminal a spinner shows the step that is running, and
lines are colored (unless `NO_COLOR` is set); redirected to a file, only the result lines are written, without colors.
The output of the tools NSH runs (cargo for an app's Rust crate, the development hosts) is printed below an `error`
line when one of them fails.

`-v, --verbose` (any command; also `NSH_VERBOSE=1`) prints everything as it comes: every log line with its level and
source, cargo's output and the hosts' own.

## nsh init

```sh
nsh init [DIR] [--name <NAME>] [--template <ts|rust|mixed>] [--nsh-source <DIR>]
```

Creates an app in `DIR` (default: the current directory, created if missing) from a template. Without `--template`, `nsh init` asks which one on a terminal (Enter picks `ts`) and takes `ts` elsewhere (a script, CI).

| Template | What it creates |
|---|---|
| `rust` | An app written in Rust: a Cargo project (`Cargo.toml`, `src/lib.rs` with the root component, `src/main.rs` for `cargo run`), `nsh.json` with `"rust": "."` and `"root": "App"`, the root's test `App.test.tsx` with `tsconfig.json` and `.nsh/types`, `.gitignore` and a README, which also says how to add a TSX entry later. `nsh run` and `nsh package` mount the root with no QuickJS on every target (`nsh test` opens it for TypeScript tests), the browser included ([Building with Rust](https://nsh.dev/versions/main/docs/rust.md)); `cargo run` starts it on macOS, Windows or Linux directly. |
| `ts` | A TSX app: `App.tsx`, its test `App.test.tsx` (`nsh test`), `nsh.json`, `tsconfig.json`, `.gitignore` and `.nsh/types`. Files that exist are kept; it fails only if all of them exist already. |
| `mixed` | A TSX app with a Rust crate of its own at its root: `App.tsx`, its test `App.test.tsx`, `tsconfig.json`, `nsh.json` with `"rust": "."`, `.gitignore`, `.nsh/types`, a README, and the crate beside `App.tsx` (`Cargo.toml`, `src/lib.rs`), whose `#[native_module("<name>/native")]` exports a component, a module and a class that `App.tsx` uses. With no `"root"`, `App.tsx` is the entry. |

| Flag | Description |
|---|---|
| `--name <NAME>` | Display name written to `nsh.json`. Default: the directory's name. The id becomes `com.example.<name>` (letters and digits only, lower case), and the crates' import specifier `<name>/native` (lower case, words joined by `-`). |
| `--template <TEMPLATE>` | `rust`, `ts` or `mixed` (above). `rust` and `mixed` need Rust; `cargo run` also needs the native desktop backend's development libraries. |
| `--nsh-source <DIR>` | With `rust` or `mixed`: the crates depend on the NSH crates of the checkout in `DIR`, by path, to build the app against NSH's sources. |

The crates of `rust` and `mixed` depend on NSH's crates on crates.io at the CLI's version (with `--nsh-source`, on a checkout's), and the `nsh` commands build the app's runners and hosts from the same crates. Before each command on such an app, `nsh` builds a small program of the app's crates and NSH's core that describes their components, modules and classes, and runs it when the crates changed; with that description the CLI itself bundles, compiles, type-checks, serves and packages the app. A Rust app's builds compile its crates and NSH's core alone. Create them in a new app directory: any of their files existing is reported as a conflict before anything is written.

Apps whose Rust crates depend on NSH through Git use the checkout Cargo resolves in the app’s lockfile. Generated hosts share that checkout, including NSH dependencies redirected by the app’s Cargo patches.

## nsh run

```sh
nsh run [ENTRY] [--target catalyst|ios|android|macos|linux|windows|gpui|tui|web] [--device <DEVICE>] [--port <PORT>] [--release] [--limits [<LIMITS>]] [--trace] [--fps] [--name <NAME>] [--points-per-cell <WIDTHxHEIGHT>] [--window-size <WIDTHxHEIGHT>] [--display <N>]
```

```sh
nsh run my-app                     # a Rust app's root, or a TSX app's App.tsx, on this machine's backend
nsh run my-app --target ios        # in the iOS simulator
nsh run my-app/App.tsx --target web
```

For a TSX entry, `nsh run` starts the dev server (as `nsh dev`), launches a development host that loads the app from it, and rebuilds on every save. Hot module replacement patches the running app in place; logs and errors from the app are printed in the terminal. Stop it with Ctrl-C (or by closing the Catalyst, macOS, Linux, Windows or GPUI window). However it ends (Ctrl-C, `kill` / `pkill`, an error), it stops the host it started: the Catalyst app, the macOS, Linux, Windows or GPUI host, the development host in the simulator, or on the Android device.

On the native window and mobile targets, a Rust app (`nsh.json` `"root"`, [Building with Rust](https://nsh.dev/versions/main/docs/rust.md)) runs with no dev server and no QuickJS: `nsh run` builds the app's runner for the target with its root mounted, starts it (on the desktops a debug build, its logs in the terminal; in the simulator and on Android, the app installed), and on a change to the crate's Rust code builds it again and restarts it. With `--target web` it prints the page's address, and the open page loads the new runtime by itself. Name the TSX entry (`nsh run App.tsx`) to run that instead.

| Flag | Default | Description |
|---|---|---|
| `--target <TARGET>` | `macos` on macOS, `linux` on Linux, `windows` on Windows | `catalyst`: the Mac Catalyst host, an iPhone-sized window (390×844). `ios`: the host in an iOS simulator. `android`: the host on an Android device or emulator. `macos`: the AppKit host, a 1200×800 window ([macOS](https://nsh.dev/versions/main/docs/macos.md)). `linux`: the GTK host, a 390×844 window ([Linux](https://nsh.dev/versions/main/docs/linux.md)). `windows`: the Win32 host, a 1200×800 window ([Windows](https://nsh.dev/versions/main/docs/windows.md)). `gpui`: the GPUI host, a 1200×800 window, on macOS, Windows or Linux, showing a TSX app as GPUI apps that embed it show it ([GPUI](https://nsh.dev/versions/main/docs/gpui.md)). `tui`: the host in the current terminal ([Terminal](https://nsh.dev/versions/main/docs/tui.md)). `web`: the dev server's page, at the address it prints ([Web](https://nsh.dev/versions/main/docs/web.md#develop-in-the-browser)). |
| `--device <DEVICE>` | | iOS simulator to use, by name (`"iPhone 16 Pro"`) or UDID. Default: a booted one, else the newest iPhone, which is booted. |
| `--port <PORT>` | `8790` | Dev server port. Replaces the previous NSH development session on this port after its cleanup completes. |
| `--release` | | Minify and strip debug info. Release bundles have no hot module replacement: every save reloads the app. |
| `--limits [<LIMITS>]` | | Runs the app as an app embedded in another one, within the limits its host app sets: `memory` and `stack` (in `KB`, `MB` or `GB`), `load` and `call` (in `ms` or `s`) and `nodes`, such as `--limits memory=128MB,call=500ms`. The ones left out keep the embedding defaults, which `--limits` alone runs with ([Sandbox and capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md#limits)). Without it the app runs on its own, as a packaged app does. TSX entries. |
| `--trace` | | The host logs the timing of every commit (JS, layout, mount items) to the terminal. |
| `--fps` | | The performance monitor: frame rate, what frames and commits cost, CPU, GPU and memory, shown over the app on macOS ([macOS](https://nsh.dev/versions/main/docs/macos.md#performance-monitor)) and logged once a second on macOS, Linux, Windows and iOS. On `tui`, a corner line shows FPS/idle, frame p95, apply/draw/flush times, bytes and changed Cells; `C-h p` toggles it. |
| `--name <NAME>` | `nsh.json` name | Application display name in the menu bar and initial window title (`--target macos`, TSX entries). |
| `--points-per-cell <WIDTHxHEIGHT>` | `nsh.json` `tui.pointsPerCell`, otherwise `8x16` | Terminal Cell width and height in points (`--target tui`). |
| `--window-size <WIDTHxHEIGHT>` | Host default | Initial window size in points, such as `800x600` (`--target macos`, `linux`, `windows` and `gpui`, TSX entries). |
| `--display <N>` | The main display | The display the window opens on, centered: `1` is the primary display (the one with the menu bar), `2` the next, and so on; a number with no display opens it on the main one (`--target macos`, TSX entries). |

With `--target android`, the first device `adb devices` lists is used; the dev server's port is forwarded to it with `adb reverse`. See [Getting started](https://nsh.dev/versions/main/docs/getting-started.md#run-it) and [Dev server and debugging](https://nsh.dev/versions/main/docs/dev-server-and-debugging.md).

A replacement waits up to ten seconds for the previous session to finish cleanup. A port occupied by another program, or an older NSH CLI, produces an error naming the port. Use distinct `--port` values to run several apps together; `--port 0` asks the OS for a free port.
With `--target tui`, the app runs in the current terminal with hot updates on save. CLI and host diagnostics go to the app's `.nsh/tui.log`. Press `C-h e` for logs and errors, Escape or `C-g` to close the panel, and `r` to reload. App errors open the panel automatically; an update restores the app display. Each Cell defaults to 8×16 points. `--points-per-cell 10x20` takes precedence over `"tui": { "pointsPerCell": "10x20" }` in `nsh.json`; both dimensions must be finite and positive, and apply when the run starts. Rust apps run their root in a generated terminal development host and rebuild/restart when Rust code changes.

On Unix, the terminal host exits on SIGHUP, SIGTERM, SIGINT or terminal disconnection and restores the terminal settings that remain accessible. Idle apps sleep between input checks; interactive runs use live terminal input, and `--headless` accepts redirected input for tests.

## nsh dev

```sh
nsh dev [ENTRY] [--target catalyst|ios|android|macos|linux|windows|gpui|tui|web] [--device <DEVICE>] [--server-only] [--port <PORT>] [--release] [--limits [<LIMITS>]]
```

Starts the dev server and opens this system’s native host: AppKit on macOS, GTK on Linux, Win32 on Windows. Choose `--target ios` or `--target android` explicitly for mobile development. `--server-only` serves hosts you start yourself. The server builds the app, watches the entry’s directory, and pushes every rebuild to connected hosts. With `--server-only`, it prints the URL for hosts on this machine and one per LAN address for devices, and, when the web runtime is there, the page browsers open to run the app ([Web](https://nsh.dev/versions/main/docs/web.md#develop-in-the-browser)):

```text
✓ built App.tsx (3.2 KB js, 9.8 KB bytecode, 21ms)
→ dev server ws://127.0.0.1:8790/ws
  browsers: http://127.0.0.1:8790/
  devices on this network: ws://192.168.1.20:8790/ws
  browsers on this network: http://192.168.1.20:8790/
```

Use `nsh dev --server-only` with an app that embeds the development SDK (`NativeShellDev.xcframework`, `nsh-dev.aar`). `--target`, `--device`, `--port`, `--release` and `--limits` work as for `nsh run`; `--server-only` selects a server without a launched host.

## nsh test

```sh
nsh test [PATH] [--filter <NAME>] [--trace] [--fps] [--junit <FILE>] [--target <TARGET>] [--browser <PATH>] [--web-host <JS>] [--display <N>]
```

Runs the app's tests headless ([Testing](https://nsh.dev/versions/main/docs/testing-and-trace.md)): the test files (`*.test.tsx`, `*.test.ts`, importing `nsh/test`) in `PATH`, a directory (default: the current one; hidden directories, `node_modules` and `target` are skipped), or the test file `PATH`. Given a directory of an app with Rust crates of its own (`nsh.json` `"rust"`: a Rust app or a TSX app with a crate), it first runs `cargo test` for each crate in the directory, in the crate's own directory, and shows and counts each Rust test with the TypeScript tests, under the file of its test target (`src/lib.rs › tests::adds`); a Rust app with only Rust tests is tested this way too. Each test file runs on an engine of its own and each app its tests open on another, fresh one. It prints a line per test, and for a failure what was thrown, where in the test file and the texts on screen; any failure makes it exit with a non-zero code. Given the app's entry (`nsh test App.tsx`; a Rust app's: `nsh test nsh.json`), it opens the app on the network, lets it run for 1.2 s and takes the steps standard input gives (`await app.press("Add")`, with `app` the app). A TSX app runs in the CLI's own process; an app with Rust crates of its own runs in a headless runner built with them, which the CLI builds the entries for. Headless runs behave as iOS unless a test opens the app as Android (`open`'s `platform`): `platform.os` is `"ios"`, and `ios:` classes and `ios={{…}}` props apply.

```text
✓ App.test.tsx › counts taps (321ms)
✓ 1 test: 1 passed, 0 failed (343ms)
```

| Flag | Description |
|---|---|
| `--filter <NAME>` | Runs only the tests whose name (after the names of the `describe` blocks it is in) contains `NAME`; for the crates, `cargo test <NAME>`. |
| `--trace` | Prints every mount batch of the apps the tests open, under the step it came in (`── press(Add): 7 items`), and the time of every commit: what the first frame, a step or a frame of scrolling costs. With `--target`, the host's batches and timings. |
| `--fps` | With `--target linux`, `macos`, `windows` or `ios`: the host logs its performance monitor's readings once a second (frame rate, frame phases, commits, CPU, memory), shown with `-v`. |
| `--junit <FILE>` | Also writes the results to `FILE` as a JUnit XML report, the format CI services show test results from: a `testsuite` per test file, a `testcase` per test. |
| `--target <TARGET>` | Runs the apps the tests open on this platform's development host instead of headless (`macos`, `linux`, `windows`, `gpui`, `tui`, `web`, `ios` and `android`; `tui` runs them in an in-memory terminal, `web` in a headless Chrome, Edge or Chromium): the steps act with the platform's own input ([Testing](https://nsh.dev/versions/main/docs/testing-and-trace.md#on-a-real-platform)), and `open` checks its options against the platform, rejecting one it cannot honor (`ERR_NSH_TEST_UNSUPPORTED`: `width` and `height` on iOS and Android, a `platform` of another kind of device). The crates' Rust tests run on this machine, in runs without `--target`. |
| `--browser <PATH>` | The Chrome, Edge or Chromium executable `--target web` runs the apps in (default: the one installed on this machine). |
| `--display <N>` | With `--target macos`: the display the apps' windows open on, centered: `1` is the primary display (the one with the menu bar), `2` the next, and so on; a number with no display opens them on the main one. By default they open on a secondary display (the first besides the primary one, not a mirror of it), so a test run keeps to a screen of its own, and on the primary one when it is the only one. The tests run the same on every display. |
| `--web-host <JS>` | The web page's host module the apps opened headless get (default: `nsh.json` `web.host`; it exports `createHost(player)`): it answers their [`host`](https://nsh.dev/versions/main/modules/nsh.md#host) calls and its `player.hostEvent` reaches `host.on` ([Testing](https://nsh.dev/versions/main/docs/testing-and-trace.md#the-pages-host)). Headless runs only; `--target web` runs `nsh.json`'s `web.host`. |

## nsh check

```sh
nsh check [ENTRY] [--tsc <TSC>] [-- <TSC ARGS>...]
```

Type checks the app. An app with Rust crates of its own (`nsh.json` `"rust"`) has each crate checked first with `cargo check --all-targets` in the crate's directory, its tests included; Cargo's errors make it exit with a non-zero code. A Rust app (`"root"`) is then checked as far as it has TypeScript: with a `tsconfig.json` (the one `nsh init --template rust` writes for `App.test.tsx`) its test files are type checked too. The TypeScript check refreshes `.nsh/types` and `.nsh/tsconfig.json`, then runs `tsc -p <app directory> --noEmit` with the app's `tsconfig.json`. It uses TypeScript 7, the native compiler, which needs no Node: the first run downloads it from the npm registry (about 9 MB), checks it against the checksum NSH records, and keeps it in NSH's cache (`~/Library/Caches/nsh` on macOS, `~/.cache/nsh` on Linux, `%LOCALAPPDATA%\nsh` on Windows, or `NSH_CACHE`). Type errors make it exit with a non-zero code. It warns when `tsconfig.json` does not extend `./.nsh/tsconfig.json`, where NSH keeps its TypeScript settings ([Project structure](https://nsh.dev/versions/main/docs/project-structure.md#tsconfigjson-and-nshtypes)).

| Flag | Description |
|---|---|
| `--tsc <TSC>` | Run this `tsc` instead (also `NSH_TSC`), for example one from `node_modules` or a copy for machines without network. |
| `-- <TSC ARGS>` | Passed on to `tsc`, e.g. `nsh check -- --pretty false`. |

NSH-generated files stay under `.nsh/`: declarations, runner sources, and default build/package outputs in
`.nsh/out/`. Cargo keeps its normal `target/` cache and existing `CARGO_TARGET_DIR` behavior; NSH does not
add Cargo configuration to relocate it. `--out` still overrides the output location.

## nsh build

```sh
nsh build [ENTRY] [-o <OUT>] [--release] [--split]
```

Builds the app. For a Rust app (`nsh.json` `"root"`), it builds and describes the app's crates and writes `app.json` and the files they ship (`assets/`): its runners mount the root. For a TSX app, it bundles the app and compiles it to QuickJS bytecode, for apps that embed NSH and ship the bundle themselves.

| Flag | Default | Description |
|---|---|---|
| `-o, --out <OUT>` | `.nsh/out` | Output directory. |
| `--release` | | Minify and strip debug info. |
| `--split` | | Put what `import()` loads into chunk files of its own, downloaded when first imported (web apps, see [Split bundles](https://nsh.dev/versions/main/docs/web.md#split-bundles)). Without it, the bundle holds the whole app. |

It writes:

| File | Content |
|---|---|
| `bundle.js` | The bundle as JavaScript |
| `bundle.js.map` | Its source map (stack traces are mapped back to your sources) |
| `bundle.nshc` | The bundle as compiled bytecode: what apps load |
| `<Chunk>.js`, `<Chunk>.js.map`, `<Chunk>.nshc` | With `--split`: each chunk, its source map and its bytecode (`Screen.js` for `import("./Screen")`) |
| `capabilities.json` | The `capabilities` of `nsh.json`, if declared (removed otherwise) |
| `assets/` | Every imported image and font, at its path relative to the app root |

## nsh package

```sh
nsh package [ENTRY] --target ios|ios-simulator|android|macos|linux|windows|web [-o <OUT>] [flags]
```

Builds an installable app in release mode. A Rust app (`nsh.json` `"root"`) is packaged with its own runner, built with Cargo from your crates and NSH's, its root mounted with no QuickJS ([Building with Rust](https://nsh.dev/versions/main/docs/rust.md)); a TSX app with the prebuilt runtime. No Xcode project or Gradle build is involved: NSH assembles the app bundle itself and uses Xcode's `actool` and `codesign` (iOS) or the SDK's `aapt2`, `zipalign` and `apksigner` (Android); for macOS it assembles an ad hoc signed `.app` with `codesign` (and `sips` for the icon); for Linux it copies the runner and writes a `.tar.gz` with `tar`; for Windows it copies the runner, embeds the icon and writes a `.zip`, with no tools; for the web it writes a static site, with no tools. Metadata comes from `nsh.json`, overridden by the flags.

| Flag | Description |
|---|---|
| `--target <TARGET>` | Required. `ios`: iOS devices, a signed `.ipa` (or an unsigned `.app` without `--sign`). `ios-simulator`: an ad hoc signed `.app`. `android`: a signed `.apk`. `macos`: an ad hoc signed `.app` ([macOS](https://nsh.dev/versions/main/docs/macos.md#packaging)). `linux`: a directory `<Name>/` (the executable, `nsh/`, a `.desktop` file) and `<Name>.tar.gz` ([Linux](https://nsh.dev/versions/main/docs/linux.md#packaging)). `windows`: a directory `<Name>\` (`<Name>.exe`, `nsh\`) and `<Name>.zip` ([Windows](https://nsh.dev/versions/main/docs/windows.md#packaging)). `web`: a directory `<Name>/`, a static site (`index.html` and files named by their content) ([Web](https://nsh.dev/versions/main/docs/web.md#publish-an-app)). |
| `-o, --out <OUT>` | Output directory (default `.nsh/out`). |
| `--name <NAME>` | Display name. |
| `--id <ID>` | Bundle identifier, e.g. `com.example.app`. |
| `--app-version <VERSION>` | Version, e.g. `1.2.0`. |
| `--build <BUILD>` | Build number. |
| `--icon <ICON>` | App icon: a square PNG, ideally 1024×1024. |
| `--sign <IDENTITY>` | iOS devices: code signing identity, e.g. `"Apple Development: …"`. |
| `--profile <FILE>` | iOS devices: provisioning profile (`.mobileprovision`). Entitlements come from it. |
| `--keystore <FILE>` | Android: release keystore. Default: the debug key in `~/.android/debug.keystore` (created if missing). |
| `--key-alias <ALIAS>` | Android: key alias in the keystore. |
| `--keystore-password <PASSWORD>` | Android: keystore password. Also read from `NSH_KEYSTORE_PASSWORD`. |
| `--abi <ABI>` | Android: the ABIs of the APK (`arm64-v8a`, `armeabi-v7a`, `x86_64`), repeated or separated by commas. Default: `arm64-v8a` and `armeabi-v7a`, plus the device's with `--run`. |
| `--run` | Install and launch the app afterwards: in the simulator (`ios-simulator`) or on the connected Android device; `macos`, `linux` and `windows` launch it; `web` serves the site on this machine at the address it prints. |

```sh
nsh package my-app --target ios-simulator --run
nsh package my-app --target ios --sign "Apple Development: Jane Doe (ABCDE12345)" --profile dev.mobileprovision
nsh package my-app --target android --keystore release.jks --key-alias upload
nsh package my-app --target macos
nsh package my-app --target linux
nsh package my-app --target windows
nsh package my-app --target web
```

See [Packaging](https://nsh.dev/versions/main/docs/packaging.md).

## Signing commands

These commands make and check signed packages (`.nshpkg`): app bundles that apps embedding NSH download and verify before running them. [Signed packages](https://nsh.dev/versions/main/docs/signed-packages.md) explains the model (an offline root key certifies release keys for some app ids).

### nsh keygen

```sh
nsh keygen <NAME>
```

Creates an Ed25519 key pair: `<NAME>.secret` and `<NAME>.pub` (e.g. `nsh keygen keys/root`). Keep a root's `.secret` offline; apps trust its `.pub`.

### nsh update-manifest

```sh
nsh update-manifest <ARCHIVE>... [--entry <DIR>] [--key <FILE>] [--notes <FILE>] [--link ios=<URL>] [--link android=<URL>] [--base-url <URL>] [-o <DIR>]
```

Writes `latest.json` (and `latest.json.sig` with `--key`) for the archives `nsh package` made on each platform: see [App Updates](/docs/app-updates).

### nsh certify

```sh
nsh certify --root <ROOT.secret> --key <KEY.pub> --apps <PATTERN>... [--days <DAYS>] -o <OUT>
```

Certifies a release key with a root key for some app ids and a time window; packages carry the certificate.

| Flag | Description |
|---|---|
| `--root <ROOT>` | The root's secret key. |
| `--key <KEY>` | The release key's public key. |
| `--apps <APPS>` | App ids it may sign for: `*`, `com.example.*` or an id. Repeatable. |
| `--days <DAYS>` | How long it may sign, from now (default 365). |
| `-o, --out <OUT>` | The certificate to write. |

### nsh publish

```sh
nsh publish [ENTRY] --key <KEY.secret> --cert <CERT> [-o <OUT>] [--id <ID>] [--app-version <V>] [--build <N>]
            [--source-map package|file|none] [--strip-debug] [--min-runtime <VERSION>]
```

Builds the app in release mode and signs it into a package. Metadata comes from `nsh.json`, overridden by the flags.

Given a package (`ENTRY` is a `.nshpkg` file), it signs that package again with this key, as a platform does that signs
the packages of its apps with one key of its own. The package's files and header stay as they are; its certificate,
signing time and signature become the new key's ([Signed packages](https://nsh.dev/versions/main/docs/signed-packages.md#sign-a-package-again)). `-o`
may name the package read, and only `--key`, `--cert` and `-o` apply.

| Flag | Description |
|---|---|
| `--key <KEY>` | The release key's secret key. |
| `--cert <CERT>` | Its certificate (`nsh certify`). |
| `-o, --out <OUT>` | The package to write. Default: `.nsh/out/<id>-<build>.nshpkg`. |
| `--id <ID>` | App id. |
| `--app-version <VERSION>` | Version. |
| `--build <BUILD>` | Build number: must grow with every release. |
| `--source-map <WHERE>` | Where the source map goes: `package` (default), `file` (`<package>.map` next to the package) or `none` ([Signed packages](https://nsh.dev/versions/main/docs/signed-packages.md#errors-from-published-packages)). |
| `--strip-debug` | Leave the line and column tables out of the bytecode: smaller, but error stacks have no positions. |
| `--min-runtime <VERSION>` | The lowest runtime that runs the package, e.g. `0.2.0`; older runtimes refuse it. Default: this CLI's version ([Signed packages](https://nsh.dev/versions/main/docs/signed-packages.md#which-runtimes-run-a-package)). |

### nsh verify

```sh
nsh verify <PACKAGE> [--root <ROOT.pub>]... [--revocations <LIST>]
```

Verifies a package as an app trusting the given roots would. Without `--root`, only the package's own signature is checked. It prints the package's SHA-256, which `nsh revoke --package` takes.

### nsh symbolicate

```sh
nsh symbolicate <MAP> [INPUT]
```

Rewrites the bundle positions (`bundle.js:LINE:COL`) of an error a package reported to your sources and prints the
result. `MAP` is a source map (`<package>.map` from `nsh publish --source-map file`, `bundle.js.map`) or a package that
holds one; `INPUT` is the error text (default: standard input).

### nsh revoke

```sh
nsh revoke --root <ROOT.secret> [--extend <LIST>] [--sequence <N>] [--key <ID>]... [--package <SHA256>]... -o <OUT>
```

Signs a revocation list: release keys and packages that must not load any more.

| Flag | Description |
|---|---|
| `--root <ROOT>` | The root's secret key. |
| `--extend <EXTEND>` | Keep the entries of this list (the last one published). |
| `--sequence <N>` | The list's number, higher than any published before. Default with `--extend`: that list's plus one. |
| `--key <ID>` | A release key id to revoke. Repeatable. |
| `--package <SHA256>` | A package SHA-256 to revoke. Repeatable. |
| `-o, --out <OUT>` | The list to write. |

## Environment variables

| Variable | Used by | Description |
|---|---|---|
| `ANDROID_HOME`, `ANDROID_SDK_ROOT` | Android targets | The Android SDK. Fallback: `~/Library/Android/sdk`. |
| `CARGO_TARGET_DIR` | apps with Rust crates | Where the app's runners build. Default: the app's `target/`. |
| `NSH_KEYSTORE_PASSWORD` | `package --target android` | The keystore password. |
| `NSH_RUNTIME` | `run`, `package` | A runtime directory to use instead of the one next to the CLI. |
| `NSH_VERBOSE` | every command | `1`: as `--verbose`. |
| `NSH_WASM_BINDGEN` | `run`, `package` (`--target web`) | The `wasm-bindgen` CLI for an app whose crates [call browser APIs](https://nsh.dev/versions/main/docs/web.md#browser-apis-from-rust). Default: the one on `PATH`. |
| `NO_COLOR` | every command | Set: no colors on terminals. |

Source: https://nsh.dev/versions/main/docs/cli

---

# Platform overview

NSH runs on phones, desktops, terminals and the web: iOS, Android, macOS, Windows, Linux, GPUI, the terminal and web pages. Each has a backend of its own that draws with the platform's own UI, so an app is UIKit views on an iPhone, AppKit views on a Mac, GTK 4 widgets on Linux, GPUI elements in a GPUI app, character Cells in a terminal and HTML in a browser, with the platform's text, input, accessibility and dark mode. Everything above the backend is shared: the reactive graph, the renderer, Taffy layout, the components and the native modules are the same Rust code everywhere, so one app runs on all of them. An app written in Rust is that code and your crate, with no JavaScript VM; a TSX app runs its modules on QuickJS on top of it ([Building with Rust](https://nsh.dev/versions/main/docs/rust.md)).

On every platform, an app is used the same two ways: packaged as an installable app of that platform (`nsh package`), or embedded in a native app of your own, whether the host links a Rust root or loads TSX at run time. You develop it with `nsh run` (Rust edits rebuild and restart the app, TSX edits are hot updates).

## At a glance

| Platform | Backend; text | Runs on | Develop | Package |
|---|---|---|---|---|
| [iOS](https://nsh.dev/versions/main/docs/ios.md) | UIKit; CoreText | iOS 15.0+, devices and the simulator | `nsh run --target ios` | `.app` (simulator), signed `.ipa` |
| [Android](https://nsh.dev/versions/main/docs/android.md) | Android views; `StaticLayout` | Android 9 (API 28)+, `arm64-v8a`, `armeabi-v7a` and `x86_64` | `nsh run --target android` | signed `.apk` |
| [macOS](https://nsh.dev/versions/main/docs/macos.md) | AppKit and Core Animation; CoreText | macOS 14+ | `nsh run --target macos` | ad hoc signed `.app` |
| [Windows](https://nsh.dev/versions/main/docs/windows.md) | Win32 windows drawn with Direct2D; DirectWrite | Windows 10 1809+, Windows 11 | `nsh run` (the default on Windows) | a directory and a `.zip` |
| [Linux](https://nsh.dev/versions/main/docs/linux.md) | GTK 4 widgets; Pango | GTK 4.14+ | `nsh run` (the default on Linux) | a directory and a `.tar.gz` |
| [GPUI](https://nsh.dev/versions/main/docs/gpui.md) | GPUI; GPUI's text system | macOS, Windows, Linux (Vulkan) | in your GPUI app; TSX also with `nsh run --target gpui` | inside the GPUI app that embeds it |
| [Terminal](https://nsh.dev/versions/main/docs/tui.md) | ratatui on the terminal's Cell grid; the terminal's font | terminals on macOS, Windows and Linux | `nsh run --target tui` | inside the terminal app that embeds it |
| [Web](https://nsh.dev/versions/main/docs/web.md) | HTML and CSS; the browser's fonts | modern browsers, desktop and phone | `nsh run --target web` | a static site |

- **[GPUI](https://nsh.dev/versions/main/docs/gpui.md)** draws apps with [GPUI](https://gpui-kit.com), the framework of the sibling project GPUI Kit, on macOS, Windows and Linux alike: it is the backend for embedding in GPUI and GPUI Kit apps, whose `AppView` they place in their own element tree. Standalone desktop apps run and are packaged with each OS's own backend (AppKit, Win32, GTK 4).
- **[Terminal](https://nsh.dev/versions/main/docs/tui.md)** draws apps on the terminal's grid of character Cells, in the terminal's own colors, keyboard first and with the mouse: `nsh run --target tui` runs an app in the current terminal, and a ratatui app embeds one with `AppView`.
- **[Web](https://nsh.dev/versions/main/docs/web.md)** renders apps as HTML in a browser page: `nsh package --target web` publishes a static site for any web server or CDN, with a Rust app's engine and crate compiled to WebAssembly, and a page of your own embeds an app with `createPlayer` or an iframe. It also runs the live demos and the [playground](/playground) on this site.
- **Mac Catalyst** runs the iOS backend in an iPhone-sized window (390×844) on a Mac, for development. Select it with `--target catalyst` to see how an app looks on a phone.

## Develop and package

`nsh run` picks the machine's own platform when you give no `--target`: AppKit on macOS, the GTK window on Linux and the Win32 window on Windows. Phones are reached from a computer: iOS from a Mac with Xcode, Android from macOS, Linux or Windows with the Android SDK ([Installation](https://nsh.dev/versions/main/docs/installation.md#what-works-where)).

A Rust app (its `nsh.json` names the `"root"` component) runs and packages from its directory: `nsh` builds the app's own runner for the target, with your crate and no QuickJS. A TSX app names its entry:

```sh
# A Rust app, from its directory
nsh run --target macos             # or ios, android, windows, linux, tui, web, catalyst
nsh package --target macos         # or ios, ios-simulator, android, windows, linux, web

# A TSX app
nsh run App.tsx --target macos     # or ios, android, windows, linux, gpui, tui, web, catalyst
nsh package App.tsx --target macos
```

Each desktop OS packages apps with its own backend, built for the machine it runs on: package a Mac app on a Mac, a Windows app on Windows and a Linux app on Linux. [Packaging](https://nsh.dev/versions/main/docs/packaging.md) covers every target's output, signing and icons.

## Embed in a native app

| Platform | Host view | Runs | Ships as | Host language |
|---|---|---|---|---|
| macOS | `AppView` (an `NSView`) | a Rust root, TSX bundles | the `nsh-platform-macos` crate | Rust |
| Windows | `AppView` (a child window) | a Rust root, TSX bundles | the `nsh-platform-windows` crate | Rust |
| Linux | `AppView` (a GTK widget) | a Rust root, TSX bundles | the `nsh-platform-linux` crate | Rust |
| GPUI (macOS, Windows, Linux) | `AppView` (a GPUI view) | a Rust root, TSX bundles, signed packages | the `nsh-platform-gpui` crate | Rust |
| iOS | `AppView` (a `UIView`) | a Rust root, TSX bundles | the `nsh-platform-ios` crate | Rust |
| iOS | `NshAppView` (a `UIView`) | TSX bundles, signed packages | `NativeShell.xcframework` | Swift |
| Android | `NshView` (a `FrameLayout`) | TSX bundles, signed packages | `nsh.aar` | Java or Kotlin |
| Terminal | `AppView` (an area of a ratatui frame) | a Rust root, TSX bundles | the `nsh-platform-tui` crate | Rust |
| Web | `createPlayer` (a page element) or an iframe | TSX bundles; a Rust app as its published site | the runtime files from `nsh package --target web` | JavaScript or HTML |

A Rust host mounts a Rust root (`Root::of::<App>()`) as `AppSource::Rust` or `App::Rust`, and gives its engines the app's UI sets with `set_ui_sets`, so TSX it loads imports the app's own components and modules. Each view is one engine, and an app can show several. The host registers its own native views for apps to use on every platform ([Native components](https://nsh.dev/versions/main/docs/native-components.md)).

> [!NOTE]
> Rust hosts embed NSH with the platform crates from the NSH repository; the `AppView` of macOS, Windows and Linux loads bundles from the app's own files (or source code), with the default limits. The GPUI crate and the iOS and Android SDKs also load [signed packages](https://nsh.dev/versions/main/docs/signed-packages.md) and set limits and capabilities per view ([Sandbox and capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md)).

## Writing for every platform

Most of an app needs no platform checks: elements, styles, layout and modules behave the same everywhere. Where platforms differ, NSH gives the difference one place ([Platform-specific code](https://nsh.dev/versions/main/docs/platform-specific.md)):

- **The environment says where the app runs**: in Rust `os()`, `idiom()` and `is_desktop()` (`nsh_core::prelude`), in TSX `platform.os`, `platform.idiom`, `platform.desktop` and `platform.select` from `nsh`. The OS is iOS, Android, macOS, Windows, Linux or the web; in a terminal, the idiom is `"terminal"` and the OS the machine's own.
- **Platform-only props** go in `ios={{…}}`, `android={{…}}`, `web={{…}}` or `desktop={{…}}` in TSX (`desktop`: macOS, Windows, Linux, desktop browsers and terminals).
- **Input follows the platform.** Phones get touches and the software keyboard; desktops get the mouse, the trackpad and the keyboard.

An app's components are drawn with NSH's primitives, so they run on desktops as well as on phones, looking the same on both. A desktop layout is built from the primitives (`view`, `text`, `scroll`, `virtual_list`, …; `View`, `Text`, `Scroll`, `List`, … in TSX) and a check for the desktop, as the gallery's desktop layout is:

```rust
use nsh_core::prelude::*;

#[component]
pub fn Shell() -> impl IntoElement {
    // macOS, Windows, Linux and desktop browsers get a sidebar; phones get tabs.
    view()
        .flex_1()
        .child(if is_desktop() { sidebar_layout() } else { tab_layout() })
}

fn sidebar_layout() -> AnyElement {
    view().flex_1().flex_row().into_element()
}

fn tab_layout() -> AnyElement {
    view().flex_1().flex_col().into_element()
}
```

```tsx
import { View } from "nsh";
import { platform } from "nsh";

export function Shell() {
  // macOS, Windows, Linux and desktop browsers get a sidebar; phones get tabs.
  return <View class="flex-1">{platform.desktop ? <SidebarLayout /> : <TabLayout />}</View>;
}

function SidebarLayout() {
  return <View class="flex-1 flex-row" />;
}

function TabLayout() {
  return <View class="flex-1 flex-col" />;
}
```

Each backend lists what it does its own way: [macOS](https://nsh.dev/versions/main/docs/macos.md#what-differs-on-macos), [Windows](https://nsh.dev/versions/main/docs/windows.md#what-differs-on-windows), [Linux](https://nsh.dev/versions/main/docs/linux.md#what-differs-on-linux), [GPUI](https://nsh.dev/versions/main/docs/gpui.md#differences), [Terminal](https://nsh.dev/versions/main/docs/tui.md).

## See also

- [Getting started](https://nsh.dev/versions/main/docs/getting-started.md): a first app, run on each platform.
- [Building with Rust](https://nsh.dev/versions/main/docs/rust.md): apps written in Rust, and Rust with TSX.
- [Installation](https://nsh.dev/versions/main/docs/installation.md): the tools each platform needs.
- [Architecture](https://nsh.dev/versions/main/docs/architecture.md): what is shared and what each backend does.

Source: https://nsh.dev/versions/main/docs/platforms

---

# iOS

NSH apps run on iOS with UIKit views and CoreText text, on devices and in the simulator, from iOS 15.0. Whole apps run
and package as on the other platforms, and an existing app can show NSH apps in its own views, a Rust root it links
or TSX it loads, including signed packages it downloads, under limits and capabilities it sets. On iOS, `os()` is `Os::Ios` (`platform.os` is `"ios"` in TSX) and TSX's `ios={{…}}` props apply.

## Requirements

- **Xcode** on a Mac, with an iOS simulator runtime (`xcodebuild -downloadPlatform iOS` installs one). See
  [Installation](https://nsh.dev/versions/main/docs/installation.md#ios-and-mac-catalyst).
- Apps need **iOS 15.0** or later, on iPhone and iPad.

## Running an app

A Rust app runs from its directory, a TSX app names its entry:

```sh
nsh run --target ios                                  # a Rust app
nsh run --target ios --device "iPhone 16 Pro"
nsh run App.tsx --target ios                          # a TSX app
```

`nsh` uses a booted simulator, or boots the newest iPhone. For a Rust app it builds the app's own runner with your
crate, installs it and shows its logs in the terminal; a change to the crate's Rust code builds it again and restarts
the app. For a TSX app it installs the development host and keeps the app up to date as you save, with logs in the
terminal. `--device` picks a simulator by name or UDID. For a quicker loop
without a simulator, `nsh run --target catalyst` on a Mac opens the same UIKit backend in an iPhone-sized
[Mac Catalyst](https://nsh.dev/versions/main/docs/getting-started.md#mac-catalyst) window.

## Packaging

```sh
nsh package --target ios-simulator --run      # .nsh/out/<Name>.app, installed and launched in the simulator
nsh package --target ios --sign "Apple Distribution: Example Inc (ABCDE12345)" --profile AppStore.mobileprovision
```

From a Rust app's directory, the app is the iOS runner built with your crate; a TSX app names its entry
(`nsh package App.tsx --target ios-simulator --run`).

`--target ios` writes a signed `.ipa` for devices, TestFlight or the App Store. Signing identities, provisioning
profiles and icons: [Packaging](https://nsh.dev/versions/main/docs/packaging.md#ios-devices).

## Embedding in an iOS app

An existing iOS app can show NSH apps inside its own UI. An iOS app with Rust code links your crate and the
`nsh-platform-ios` crate and shows your root in an `AppView` ([Embedding a Rust app](#embedding-a-rust-app)). A Swift
app links `NativeShell.xcframework`, a framework with a Swift module: you create an `NshAppView` (a `UIView`),
add it anywhere in your view hierarchy and load a TSX app or a signed package into it. Your native screens,
navigation and the NSH app live side by side in one UIKit hierarchy.

Each view is one independent engine; there are no global singletons, so an app can show several NSH apps at once, for
example one per tab.

![One host app with two NshAppView regions: each is its own engine with its own thread, VM, limits and capabilities; the host grants capabilities, sets limits and registers native components such as a map.](https://nsh.dev/versions/main/diagrams/host-app-light.svg)

## Embedding a Rust app

`nsh_platform_ios::AppView` is one engine as a `UIView` for an iOS app built with Rust: it mounts your crate's root
component, with no JavaScript VM involved.

```rust
use nsh_platform_ios::{set_ui_sets, AppView, Root, SurfaceOptions};
use objc2::MainThreadMarker;
use objc2_ui_kit::UIView;

fn show(container: &UIView) -> AppView {
    // Once, before the first view: the UI sets the apps import (NSH's and your crate's).
    set_ui_sets(vec![nsh_base::registry(), my_app::registry()]);
    let mtm = MainThreadMarker::new().expect("main thread");
    let app = AppView::new(mtm, container.bounds(), SurfaceOptions::default());
    container.addSubview(app.view());
    app.run(Root::of::<my_app::App>());
    // Keep the AppView: dropping it stops the app.
    app
}
```

The view resizes with its superview. `AppView::run` replaces whatever ran; `AppView::load` runs a TSX bundle instead
(`Bundle::source`, or `unsafe { Bundle::bytecode(bytes) }` for a `bundle.nshc` in the app bundle). `SurfaceOptions`
holds the limits, the granted capabilities, the data directory and the native components, as `NshAppView`'s members
below do; `AppView::set_locale`, `set_font_scale` and `set_error_handler` match `locale`, `fontScale` and `onError`.
`nsh package --target ios` builds this kind of app for you, with your root mounted.

## Get the framework

The distribution contains both variants:

```text
dist/nsh/embed/ios/NativeShell.xcframework      release: bundles and signed packages
dist/nsh/embed/ios/NativeShellDev.xcframework   also connects to a `nsh dev` server
```

From a checkout of NSH you can build just the frameworks:

```sh
cargo xtask ios-embed    # writes dist/nsh/embed/ios/{NativeShell,NativeShellDev}.xcframework
```

The default build produces static frameworks. To build dynamic frameworks, use:

```sh
cargo xtask ios-embed --dynamic
```

Dynamic frameworks give the runtime its own library image and unwind table, supporting host apps that already link
other Rust runtimes. Choose the Xcode embedding setting below to match the framework you build.

By default, each XCFramework has three arm64 slices: iOS devices, the iOS simulator (Apple silicon) and Mac Catalyst. The minimum
deployment target is iOS 15.0. The Swift module is compiled with library evolution, so apps built with other Swift
compiler versions can import it, and the framework links everything it needs: you add nothing else.

## Add it to an Xcode project

1. Drag `NativeShell.xcframework` (or `NativeShellDev.xcframework` for development builds) into the app target's
   **Frameworks, Libraries, and Embedded Content**. Choose **Do Not Embed** for the default static frameworks,
   or **Embed & Sign** for dynamic frameworks built with `--dynamic`.
2. In Swift, `import NativeShell`.
3. In the app's `Info.plist`, set `CADisableMinimumFrameDurationOnPhone` to `YES`: on ProMotion iPhones the app's
   animations then move at 120 Hz, as scrolling does (apps built by `nsh package` have it).

> [!TIP]
> Link `NativeShellDev.xcframework` in the Debug configuration and `NativeShell.xcframework` in Release, so only
> development builds can connect to a dev server.

## Ship a bundle with the app

A Swift app ships TSX apps as bundles. Build the NSH app into a folder and add that folder to the app's resources as a folder reference named `nsh`:

```sh
nsh build App.tsx --release --out MyApp/nsh
```

`nsh build` writes:

| File | Contents |
|---|---|
| `bundle.nshc` | The app compiled to bytecode: the fastest to load. |
| `bundle.js` | The same app as JS source. |
| `bundle.js.map` | Its source map (stack traces point at your `.tsx` files). |
| `capabilities.json` | The [capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md) the app declares, when `nsh.json` has any. |
| `assets/` | Images and fonts the app imports, at their paths relative to the entry. |

## Show the app

```swift
import NativeShell
import UIKit

final class EmbedController: UIViewController {
    private let app = NshAppView()

    override func viewDidLoad() {
        super.viewDidLoad()
        app.translatesAutoresizingMaskIntoConstraints = false
        app.onError = { message in print("nsh error: \(message)") }
        view.addSubview(app)
        NSLayoutConstraint.activate([
            app.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor),
            app.leadingAnchor.constraint(equalTo: view.leadingAnchor),
            app.trailingAnchor.constraint(equalTo: view.trailingAnchor),
            app.bottomAnchor.constraint(equalTo: view.bottomAnchor),
        ])

        guard let url = Bundle.main.url(forResource: "bundle", withExtension: "nshc", subdirectory: "nsh") else { return }
        do {
            try app.loadBundle(at: url)
        } catch {
            print("cannot load: \(error)")
        }
    }

    // Let the embedded app's pages and dialogs decide the status bar.
    override var preferredStatusBarStyle: UIStatusBarStyle { NshAppView.preferredStatusBarStyle }
    override var prefersStatusBarHidden: Bool { NshAppView.prefersStatusBarHidden }
    override var preferredStatusBarUpdateAnimation: UIStatusBarAnimation {
        NshAppView.preferredStatusBarUpdateAnimation
    }
}
```

The view's size is the app's window: NSH lays the app out at the view's bounds and again whenever they change. Loading
again replaces the running app; the app stops when the view is deallocated.

The complete sample, a UIKit app that shows an NSH app below its own native header, is `examples/embed-ios/main.swift`.

## `NshAppView`

`NshAppView` is a `UIView` subclass isolated to the main actor.

| Member | Description |
|---|---|
| `init(frame: CGRect = .zero, trace: Bool = false)` | Creates the view. `trace` logs the time of every commit. `init?(coder:)` supports storyboards and nibs. |
| `onError: ((String) -> Void)?` | Receives fatal app errors (a bundle that fails to load, uncaught JS exceptions, a VM stopped by a limit) on the main thread. Errors are always logged; development builds also show them over the app. |
| `limits: NshLimits` | The VM limits of the apps loaded from now on. |
| `grantCapabilities(_ json: String?) throws` | The most the apps loaded from now on may do, as JSON in the form of `nsh.json`'s `capabilities`; `nil` grants what each app declares. Throws `NshError` for invalid JSON. |
| `locale: Locale?` | The app's language and region in place of the user's: `Intl`, `locale()` and the components follow it at once, and the apps loaded later start in it. `nil` follows the system's. |
| `fontScale: CGFloat?` | The text size in place of Dynamic Type's (1 is the default): texts and inputs are laid out again at it and `fontScale()` reads it, at once and for the apps loaded later; lengths keep their size. `nil` follows the system's. |
| `setThemeOverrides(_ json: String?) throws` | The host's brand over the app's [theme](https://nsh.dev/versions/main/docs/tailwind.md#theme-tokens): a theme file in the format of `nsh.json`'s `"theme"`. Its tokens win over the app's of the same names, in light and dark mode, and the app's others stay. Applies at once and to the apps loaded later; `nil` gives the app its own theme back. Throws `NshError` for a file that does not parse. |
| `storageDirectory: URL?` | Where the apps loaded from now on keep their [storage](https://nsh.dev/versions/main/modules/nsh.md#storage); `nil`: `Library/Application Support/nsh/<app id>`, by the app's own id. |
| `cacheOptions: NshCacheOptions` | Where the apps loaded from now on keep their caches, the [images they download](https://nsh.dev/versions/main/docs/images-and-assets.md#kept-on-disk), and how much each keeps: `location` `.system` (`Library/Caches/nsh`, each app in `<app id>`), `.directory(URL)` or `.off`; `images` `.default` (256 MB), `.maxSize(megabytes:)` or `.off`. |
| `loadBundle(at url: URL) throws` | Runs a bundle written by `nsh build`. Assets come from `assets/` next to it; `bundle.js.map` and `capabilities.json` next to it are read too. |
| `run(_ package: NshPackage)` | Runs a verified signed package (see below). A package runs once. |
| `loadPackage(at:trust:) async throws -> NshPackage.Info` | Verifies the package at a URL off the main thread, then runs it. Throws why it was refused; the running app stays. |
| `connectDevServer(_ url: URL) throws` | Development: loads from a `nsh dev` server and reloads on every change. Throws with `NativeShell.xcframework`, which has no development support. |
| `register(component:_:)` | Registers a [native component](https://nsh.dev/versions/main/docs/native-components.md). |
| `params: [String: Any]` | The launch parameters of the apps loaded from now on: the app reads them at start as `host.params` ([`host`](https://nsh.dev/versions/main/modules/nsh.md#host)). |
| `send(_ name: String, _ data: Any? = nil)` | Sends an event to the app (`host.on(name, …)`); kept until it listens, or for the next app while none runs. |
| `handle(_ name: String, _ handler:)` | Handles the app's calls (`host.call`) and posts (`host.post`) of `name` on the main thread: `{ data, reply in … }`, or an `async throws` function `{ data in … }` whose result answers the call. |
| `removeHandler(_ name: String)` | Removes the handler of `name`: the app's calls of it fail at once. |
| `static preferredStatusBarStyle`, `prefersStatusBarHidden`, `preferredStatusBarUpdateAnimation` | What the running apps asked for (their pages' and dialogs' `statusBar`, `nsh.json`'s default): return them from the hosting view controller's overrides. |

> [!IMPORTANT]
> `bundle.nshc` (bytecode) loads only from inside the app bundle. QuickJS does not validate bytecode, so bytecode from
> anywhere else could corrupt memory: for a file outside the app bundle, load `bundle.js` (JS source), or better, a
> [signed package](https://nsh.dev/versions/main/docs/signed-packages.md).

`limits`, `grantCapabilities`, `storageDirectory` and `cacheOptions` apply from the next load: set them before `loadBundle` / `run`.

Each app keeps its storage under its own id with no setting: a signed package under the id its release key's certificate vouches for, a bundle under the `id` of its `nsh.json` (`app.json` next to it, written by `nsh build`). Set `storageDirectory` to keep an app's data somewhere of the host's choosing:

```swift
app.storageDirectory = FileManager.default
    .urls(for: .applicationSupportDirectory, in: .userDomainMask)[0]
    .appendingPathComponent("nsh/com.example.orders")
try app.loadBundle(at: url)
```

## Talking to the app

The view and the app it runs talk through a channel of their own ([`host`](https://nsh.dev/versions/main/modules/nsh.md#host)): launch
parameters the app reads at start, events from the host app, and calls and posts from the app, with JSON data
(Foundation objects on this side). It needs no view in the app and no native component.

```swift
// Before loading: what the app opens first (`host.params` in TSX).
app.params = ["conversation": notification.conversationID]
try app.loadBundle(at: url)

// The app's `await host.call("user.profile", { id })`: return the answer, or throw to reject it.
app.handle("user.profile") { data in
    let id = (data as? [String: Any])?["id"] as? Int ?? 0
    let profile = try await api.profile(id: id)
    return ["id": id, "name": profile.name]
}

// A handler that answers later, from any thread, with its reply.
app.handle("photo.pick") { _, reply in
    picker.present { url in
        if let url { reply.resolve(url.absoluteString) } else { reply.reject("cancelled") }
    }
}

// The app's `host.post("analytics", …)`: no answer.
app.handle("analytics") { data, _ in analytics.log(data) }

// Later: the app hears `host.on("conversation.open", …)`.
app.send("conversation.open", ["id": tapped.conversationID])
```

Handlers run on the main thread; a call waits for its answer in the app without blocking either side. A reply
released unanswered fails the call, and a call of a name with no handler fails at once. Events of names the app does
not listen to yet are kept until it does, and events sent while no app runs (before `loadBundle`, during a reload) go
to the next one, so a notification tapped while the app starts still reaches it.
## Theme overrides

One app embedded in several branded host apps takes each host's brand: the host gives the tokens its brand changes,
as a theme file in the format of `nsh.json`'s `"theme"` (shadcn/ui's `cssVars`, values as CSS writes them). They win
over the app's tokens of the same names; the app's other tokens stay. Give a token its dark-mode value under `dark`
(one set only under `light` or `theme` is that color in both modes):

```swift
try app.setThemeOverrides("""
{ "cssVars": {
    "theme": { "radius": "0.75rem" },
    "light": { "primary": "#e11d48", "primary-foreground": "#ffffff" },
    "dark": { "primary": "#fb7185", "primary-foreground": "#1c1917" }
} }
""")
try app.loadBundle(at: url)
```

Call it before or after loading: classes such as `bg-primary` and `rounded-(--radius)` restyle at once, and every app
loaded later starts with the overrides in its first frame. `setThemeOverrides(nil)` gives the app its own theme back.

## Links the app opens

The URLs the app opens ([`openUrl`](https://nsh.dev/versions/main/modules/nsh.md#openurl), a `TextView`'s links with `links="open"`)
reach `onOpenURL` first, on the main thread: return `true` when the host app handled the URL, such as by routing it
through its own router, and `false` for the system to open it with `UIApplication.open`. Without `onOpenURL` the
system opens every URL. URLs reach it after the app's `openUrl` capability allowed them.

```swift
app.onOpenURL = { url in
    // The host app's own links open in the host app.
    if url.scheme == "lb" || url.host == "longbridge.com" {
        router.open(url)
        return true
    }
    return false
}
```

## Limits

```swift
app.limits = NshLimits(memoryMB: 128, callBudget: 1, maxNodes: 50_000)
```

| `NshLimits` field | Default | Meaning |
|---|---|---|
| `memoryMB: UInt32?` | 256 | JS heap in MB. Running out stops the app. |
| `stackKB: UInt32?` | 4096 (also the maximum) | Interpreter stack in KB. Deeper recursion throws a `RangeError`. |
| `loadBudget: TimeInterval?` | 10 s | Time to evaluate the bundle. |
| `callBudget: TimeInterval?` | 2 s | Time of any other call into JS (one event, one timer, one frame). An overrun call is cut off. |
| `maxNodes: UInt32?` | 200 000 | Nodes the app may keep. |

`nil` keeps the default. What each limit does when it is hit: [Sandbox and capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md).

## Capabilities

An app declares what it may reach in its `nsh.json`; the embedding app can grant less. A request must be allowed by
both:

```swift
try app.grantCapabilities("""
{
  "network": { "hosts": ["api.example.com", "*.cdn.example.com"] },
  "webview": { "hosts": ["help.example.com"] }
}
""")
try app.loadBundle(at: url)
```

Here the app may not set the status bar (no `statusBar`), even if its `nsh.json` asks for it. Details:
[Sandbox and capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md).

## Signed packages

To run code the app downloads (updates, third-party mini apps), use [signed packages](https://nsh.dev/versions/main/docs/signed-packages.md):
`nsh publish` writes a `.nshpkg` signed by a release key that your root key certified, and the app verifies it before
running it.

```swift
let support = FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask)[0]
let trust = try NshTrust(stateDirectory: support.appendingPathComponent("nsh"))
try trust.addRoot(rootPublicKey)   // the contents of root.pub from `nsh keygen`

Task {
    do {
        let info = try await app.loadPackage(at: downloadedFile, trust: trust)
        print("running \(info.id) \(info.version) (build \(info.build))")
    } catch {
        print("refused: \(error)")   // the running app stays
    }
}
```

To verify first and run later, split the two steps:

```swift
let package = try await trust.openPackage(at: downloadedFile)   // verifies off the main thread
// ... decide, ask the user, ...
app.run(package)
```

| API | Description |
|---|---|
| `NshTrust(stateDirectory: URL) throws` | Opens or creates the trust store. Its state (newest revocation list, highest build accepted per app) persists there, and packages' assets are extracted under it. Trusts no key until `addRoot`. Thread-safe. |
| `addRoot(_ publicKey: String) throws` | Trusts a root public key (base64, the contents of a `.pub` file). Several roots may be trusted. |
| `updateRevocations(_ json: String) throws` | Applies a revocation list written by `nsh revoke`, signed by a trusted root and newer than the one the store has. |
| `openPackage(at: URL) async throws -> NshPackage` | Verifies, extracts assets and accepts the package (older builds of that app are refused from then on). |
| `NshPackage.info` | `id`, `name`, `version`, `build` of the app inside. |
| `NshError` | The error every throwing call throws; `message` says why. |

## Development

With `NativeShellDev.xcframework`, point the view at a dev server instead of a bundle:

```swift
#if DEBUG
try app.connectDevServer(URL(string: "ws://127.0.0.1:8790/ws")!)
#else
try app.loadBundle(at: bundledURL)
#endif
```

Run `nsh dev App.tsx` on your Mac. The simulator shares the Mac's network, so `127.0.0.1` reaches the server; a
device uses the LAN address `nsh dev` prints (`devices on this network: ws://192.168.1.20:8790/ws`). Every save
updates the app in place, logs appear in the `nsh dev` terminal, and errors show over the app. See
[Dev server and debugging](https://nsh.dev/versions/main/docs/dev-server-and-debugging.md).

> [!NOTE]
> On a device, the connection to your Mac is ordinary local network traffic over plain `ws://` and `http://` (assets).
> iOS may ask the user for local network access, and the app's App Transport Security settings must allow it.

## Notes

- **Threads.** `NshAppView` is main-actor isolated. `NshTrust`, `NshPackage` and `NshComponentContext` are thread-safe.
  The JS engine runs on its own thread; the main thread never waits for it.
- **Status bar.** The embedded app's pages and dialogs (`statusBar`) change what `NshAppView.preferredStatusBarStyle` and friends return;
  the hosting view controller must forward them, as in the example above.
- **Safe area.** Apps use `safe_area()` in Rust, and `env(safe-area-inset-*)` in padding or
  `safeAreaInsets()` from [`nsh`](https://nsh.dev/versions/main/modules/nsh.md#safe-area-and-keyboard) in TSX, as usual. An `NshAppView` placed below your own header gets the insets that apply to it, not the window's.
- **Mac Catalyst.** The same framework works in Catalyst apps.

## See also

- [Building with Rust](https://nsh.dev/versions/main/docs/rust.md)
- [Embedding in Android apps](https://nsh.dev/versions/main/docs/android.md)
- [Native components](https://nsh.dev/versions/main/docs/native-components.md)
- [Signed packages](https://nsh.dev/versions/main/docs/signed-packages.md)
- [Sandbox and capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md)

Source: https://nsh.dev/versions/main/docs/ios

---

# Android

NSH apps run on Android with ordinary Android views and `StaticLayout` text, from Android 9 (API 28), on `arm64-v8a`,
`armeabi-v7a` and `x86_64`. Whole apps written in Rust and in TSX run and package as on the other platforms, and an existing app
can embed modules in an `NshView` and load signed packages it downloads, under limits and capabilities it sets. On Android, `os()` is `Os::Android` (`platform.os` is `"android"` in TSX) and TSX's
`android={{…}}` props apply.

## Requirements

- **The Android SDK** (with `platforms;android-35`, build tools and `platform-tools`) and **a JDK**, on macOS, Windows
  or Linux. See [Installation](https://nsh.dev/versions/main/docs/installation.md#android).
- An emulator, or a device connected over `adb`.

## Running an app

A Rust app runs from its directory, a TSX app names its entry:

```sh
nsh run --target android               # a Rust app
nsh run App.tsx --target android       # a TSX app
```

Start an emulator or connect a device first (`adb devices` lists them; NSH uses the first one). For a Rust app, `nsh`
builds the app's `libnsh.so` with your crate, installs the APK and starts it; a change to the crate's Rust code builds
and installs it again. For a TSX app, it installs a development host APK (rebuilt only when the runtime changes) and
forwards the dev server's port with `adb reverse`, so it works over USB without a shared network; the app updates as
you save, with logs in the terminal.

## Packaging

```sh
nsh package --target android --run             # a Rust app: .nsh/out/<Name>.apk, installed and launched
nsh package App.tsx --target android --run     # a TSX app
```

A Rust app's APK holds its own `libnsh.so`, built with your crate, whose activity mounts the root.

The APK is built with the SDK's build tools, without Gradle, and signed with the debug key unless you pass a release
keystore. Signing for release and icons: [Packaging](https://nsh.dev/versions/main/docs/packaging.md#android).

NSH builds `libnsh.so` with 16 KB ELF alignment and packages the uncompressed native libraries on 16 KB ZIP boundaries.
A release APK carries `libnsh.so` without its symbol tables and debug info. The complete library sits next to the
runtime in `symbols/<abi>/libnsh.so` (a Rust app's in `.nsh/rust/android-rust-release/symbols/<abi>/`): give it to
`ndk-stack` or upload it to Play Console as native debug symbols to read native crash stacks.

## Embedding in an Android app

An existing Android app can show NSH apps inside its own UI. The runtime ships as an Android library, `nsh.aar`: you
create a `com.longbridge.nsh.NshView` (a `FrameLayout`), add it to any layout and load a TSX app or a signed package
into it. An app written in Rust ships on Android as the APK `nsh package --target android` builds. The NSH app
renders with ordinary Android views next to your own.

Each `NshView` is one independent engine with its own JS VM; there are no global singletons, so several can run at
once.

![One host app with two nsh views (NshAppView on iOS, NshView on Android): each is its own engine with its own thread, VM, limits and capabilities; the host grants capabilities, sets limits and registers native components such as a map.](https://nsh.dev/versions/main/diagrams/host-app-light.svg)

## Get the library

The distribution contains both variants:

```text
dist/nsh/embed/android/nsh.aar       release: bundles and signed packages
dist/nsh/embed/android/nsh-dev.aar   also connects to a `nsh dev` server
```

The AAR holds the Java runtime and `libnsh.so` for `arm64-v8a`, `armeabi-v7a` and `x86_64`, with their symbols: the
app's Gradle build strips them when it packages the app and keeps the symbols for its crash reports. It declares the
`INTERNET` permission and needs **API 28** (Android 9) or newer. It carries its R8 rules (`proguard.txt`), which a
minified build applies on its own: the native library finds the runtime's classes by name, so `com.longbridge.nsh`
stays as it is.

Add it to the app module, for example from a `libs` folder:

```kotlin
// app/build.gradle.kts
dependencies {
    debugImplementation(files("libs/nsh-dev.aar"))
    releaseImplementation(files("libs/nsh.aar"))
}
```

## Ship a bundle with the app

Build the TSX app into the app's assets:

```sh
nsh build App.tsx --release --out app/src/main/assets/nsh
```

This writes `bundle.nshc` (bytecode), `bundle.js` (source), `bundle.js.map`, `capabilities.json` (when `nsh.json`
declares [capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md)) and `assets/` (the images and fonts the app imports).

## Show the app

```java
import android.app.Activity;
import android.os.Bundle;
import android.util.Log;
import com.longbridge.nsh.NshView;

public final class MainActivity extends Activity {
    private NshView nsh;

    @Override
    protected void onCreate(Bundle state) {
        super.onCreate(state);
        nsh = new NshView(this);
        nsh.setErrorListener(message -> Log.e("nsh", message));
        setContentView(nsh);
        nsh.loadAssetBundle("nsh");   // runs assets/nsh/bundle.nshc
    }

    @Override
    protected void onDestroy() {
        nsh.destroy();
        super.onDestroy();
    }
}
```

In Kotlin:

```kotlin
class MainActivity : Activity() {
    private lateinit var nsh: NshView

    override fun onCreate(state: Bundle?) {
        super.onCreate(state)
        nsh = NshView(this)
        nsh.setErrorListener { message -> Log.e("nsh", message) }
        setContentView(nsh)
        nsh.loadAssetBundle("nsh")
    }

    override fun onDestroy() {
        nsh.destroy()
        super.onDestroy()
    }
}
```

`NshView` can also sit inside any layout, below your own toolbar for example:

```java
LinearLayout column = new LinearLayout(this);
column.setOrientation(LinearLayout.VERTICAL);
column.addView(toolbar);
column.addView(nsh, new LinearLayout.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, 0, 1));
setContentView(column);
```

The view's size is the app's window: NSH lays the app out at the view's size and again whenever it changes. Loading
again replaces the running app. The complete sample is
`examples/embed-android/src/com/longbridge/nsh/embeddemo/MainActivity.java`.

## `NshView`

| Method | Description |
|---|---|
| `NshView(Context context)`, `NshView(Context context, boolean trace)` | Creates an empty view. `trace` logs the time of every commit. |
| `setErrorListener(ErrorListener listener)` | Receives fatal app errors (load failures, uncaught JS exceptions, a VM stopped by a limit) on the UI thread. They are always logged. |
| `setLimits(int memoryMb, int stackKb, int loadMs, int callMs, int maxNodes)` | VM limits of the apps loaded next; 0 keeps a default. |
| `setGrantedCapabilities(String json)` | The most the apps loaded next may do, as JSON in the form of `nsh.json`'s `capabilities`; `null` grants what each app declares. Returns `false` (and is ignored) for an invalid grant. |
| `setLocale(Locale locale)` | The app's language and region in place of the user's: `Intl`, `locale()` and the components follow it at once, and the apps loaded later start in it. `null` follows the system's. |
| `setFontScale(float scale)` | The text size in place of the system's font size (1 is the default): texts and inputs are laid out again at it and `fontScale()` reads it, at once and for the apps loaded later; lengths keep their size. `0` follows the system's. |
| `setThemeOverrides(String json)` | The host's brand over the app's [theme](https://nsh.dev/versions/main/docs/tailwind.md#theme-tokens): a theme file in the format of `nsh.json`'s `"theme"`. Its tokens win over the app's of the same names, in light and dark mode, and the app's others stay. Applies at once and to the apps loaded later; `null` gives the app its own theme back. Throws `IllegalArgumentException` for a file that does not parse. |
| `setStorageDirectory(File dir)` | Where the apps loaded next keep their [storage](https://nsh.dev/versions/main/modules/nsh.md#storage); `null`: `files/nsh/<app id>` in the app's private directory, by the app's own id. |
| `setCacheOptions(NshCacheOptions options)` | Where the apps loaded next keep their caches, the [images they download](https://nsh.dev/versions/main/docs/images-and-assets.md#kept-on-disk), and how much each keeps. Build one with `NshCacheOptions.builder()`: `location(File)`, `systemLocation()` (the default: `nsh` in the cache directory, each app in `<app id>`) or `noDiskCache()`; `imagesMaxMegabytes(int)` (256 by default) or `imagesOff()`. |
| `loadAssetBundle(String dir)` | Runs `dir/bundle.nshc` from the APK's assets; app assets come from `dir/assets/`. Returns `false` if it cannot be read (also reported to the error listener). |
| `loadBundleFile(File file)` | Runs a `bundle.js` file; assets come from `assets/` next to it. Refuses `.nshc` files. |
| `runPackage(NshPackage pkg)` | Runs a verified signed package, replacing the running app. A package runs once. |
| `registerComponent(String name, NshComponent.Factory factory)` | Registers a [native component](https://nsh.dev/versions/main/docs/native-components.md). |
| `setParams(Object params)` | The launch parameters of the apps loaded next (a `Map` or `JSONObject`): the app reads them at start as `host.params` ([`host`](https://nsh.dev/versions/main/modules/nsh.md#host)). Returns `false` when they are not a JSON object. |
| `send(String name, Object data)` | Sends an event to the app (`host.on(name, …)`); kept until it listens, or for the next app while none runs. Any thread; returns `false` after `destroy()`. |
| `handle(String name, HostHandler handler)` | Handles the app's calls (`host.call`) and posts (`host.post`) of `name` on the UI thread; `null` removes the handler. The handler answers through its `NshHostReply`, once, from any thread. |
| `connectDevServer(String url)` | Development: loads from a `nsh dev` server and reloads on every change. Returns `false` with the release AAR. |
| `handleBack()` | Lets the app handle a back press (closes dialogs, pops pages, runs `BackHandler` listeners); returns whether it did. |
| `destroy()` | Stops the app and calls `destroy()` on each of its native components. The view can no longer be used. |

> [!IMPORTANT]
> Compiled bytecode (`.nshc`) only loads from the APK's own assets or from a signed package. Files on storage can be replaced,
> and QuickJS does not validate bytecode, so `loadBundleFile` takes JS source only. Code the app downloads should come
> as a [signed package](https://nsh.dev/versions/main/docs/signed-packages.md).

`setLimits`, `setGrantedCapabilities`, `setStorageDirectory` and `setCacheOptions` apply from the next load: call them before `loadAssetBundle` and friends.

Each app keeps its storage under its own id with no setting: a signed package under the id its release key's certificate vouches for, a bundle under the `id` of its `nsh.json` (`nsh/app.json` among the APK's assets, written by `nsh package`). Call `setStorageDirectory` to keep an app's data somewhere of the host's choosing:

```java
nsh.setStorageDirectory(new File(getFilesDir(), "nsh/com.example.orders"));
nsh.loadAssetBundle("orders");
```

## Talking to the app

The view and the app it runs talk through a channel of their own ([`host`](https://nsh.dev/versions/main/modules/nsh.md#host)): launch
parameters the app reads at start, events from the host app, and calls and posts from the app, with JSON data (maps,
lists, strings, numbers and booleans on this side). It needs no view in the app and no native component.

```java
// Before loading: what the app opens first (`host.params` in TSX).
nsh.setParams(Map.of("conversation", intent.getStringExtra("conversation")));
nsh.loadAssetBundle("nsh");

// The app's `await host.call("user.profile", { id })`, on the UI thread.
nsh.handle("user.profile", (data, reply) -> {
    Object id = ((Map<?, ?>) data).get("id");
    api.profile(id, profile -> reply.resolve(Map.of("id", id, "name", profile.name)),
            error -> reply.reject(error.getMessage()));
});

// The app's `host.post("analytics", …)`: no answer.
nsh.handle("analytics", (data, reply) -> analytics.log(data));

// Later: the app hears `host.on("conversation.open", …)`.
nsh.send("conversation.open", Map.of("id", tappedConversation));
```

In Kotlin:

```kotlin
nsh.handle("user.profile") { data, reply ->
    val id = (data as Map<*, *>)["id"]
    lifecycleScope.launch {
        runCatching { api.profile(id) }
            .onSuccess { reply.resolve(mapOf("id" to id, "name" to it.name)) }
            .onFailure { reply.reject(it.message ?: "failed") }
    }
}
```

Handlers run on the UI thread; a call waits for its answer in the app without blocking either side. A reply that is
never given fails the call once it is collected, and a call of a name with no handler fails at once. Events of names
the app does not listen to yet are kept until it does, and events sent while no app runs (before `loadAssetBundle`,
during a reload) go to the next one.
## Theme overrides

One app embedded in several branded host apps takes each host's brand: the host gives the tokens its brand changes,
as a theme file in the format of `nsh.json`'s `"theme"` (shadcn/ui's `cssVars`, values as CSS writes them). They win
over the app's tokens of the same names; the app's other tokens stay. Give a token its dark-mode value under `dark`
(one set only under `light` or `theme` is that color in both modes):

```java
nsh.setThemeOverrides("{ \"cssVars\": {"
        + " \"theme\": { \"radius\": \"0.75rem\" },"
        + " \"light\": { \"primary\": \"#e11d48\", \"primary-foreground\": \"#ffffff\" },"
        + " \"dark\": { \"primary\": \"#fb7185\", \"primary-foreground\": \"#1c1917\" } } }");
nsh.loadAssetBundle("orders");
```

Call it before or after loading: classes such as `bg-primary` and `rounded-(--radius)` restyle at once, and every app
loaded later starts with the overrides in its first frame. `setThemeOverrides(null)` gives the app its own theme back.

## Links the app opens

The URLs the app opens ([`openUrl`](https://nsh.dev/versions/main/modules/nsh.md#openurl), a `TextView`'s links with `links="open"`)
reach the view's `OpenUrlHandler` first, on the UI thread: return `true` when the host app handled the URL, such as by
routing it through its own router, and `false` for the system to open it with an `ACTION_VIEW` intent. Without a
handler the system opens every URL. URLs reach it after the app's `openUrl` capability allowed them.

```java
nsh.setOpenUrlHandler(url -> {
    Uri uri = Uri.parse(url);
    // The host app's own links open in the host app.
    if ("lb".equals(uri.getScheme()) || "longbridge.com".equals(uri.getHost())) {
        router.open(uri);
        return true;
    }
    return false;
});
```

## Limits

```java
// 128 MB heap, default stack, 10 s to load, 1 s per call, 50 000 nodes
nsh.setLimits(128, 0, 10_000, 1_000, 50_000);
```

The defaults are a 256 MB heap, a 4096 KB stack, 10 s to load, 2 s per call and 200 000 nodes. What each limit does
when it is hit: [Sandbox and capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md).

## Capabilities

```java
nsh.setGrantedCapabilities(
    "{\"network\": {\"hosts\": [\"api.example.com\"]}, \"webview\": {\"hosts\": [\"help.example.com\"]}}");
nsh.loadAssetBundle("nsh");
```

A request must be allowed both by what the app declares in its `nsh.json` and by the grant. See
[Sandbox and capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md).

## Signed packages

Verify downloaded packages off the UI thread, then run them on it:

```java
NshTrust trust = new NshTrust(new File(getFilesDir(), "nsh"));
trust.addRoot(rootPublicKey);   // the contents of root.pub from `nsh keygen`

executor.execute(() -> {
    try {
        NshPackage pkg = trust.openPackage(downloadedFile);
        runOnUiThread(() -> nsh.runPackage(pkg));
    } catch (NshPackage.RefusedException e) {
        Log.w("nsh", "refused: " + e.getMessage());   // the running app stays
    }
});
```

| API | Description |
|---|---|
| `new NshTrust(File stateDir)` | Opens or creates the trust store. Its state (newest revocation list, highest build accepted per app) persists there and packages' assets are extracted under it. Trusts no key until `addRoot`. Usable from any thread; `close()` when done. |
| `boolean addRoot(String publicKey)` | Trusts a root public key (base64, the contents of a `.pub` file). `false` for an invalid key. |
| `boolean updateRevocations(String json)` | Applies a revocation list from `nsh revoke`, signed by a trusted root and newer than the store's. |
| `NshPackage openPackage(File file) throws NshPackage.RefusedException` | Verifies, extracts the assets and accepts the package (older builds of the app are refused from then on). Slow for large packages: call it off the UI thread. |
| `NshPackage` | `appId`, `appName`, `version`, `build`; `close()` if it will not run. |

How keys, certificates and revocation work: [Signed packages](https://nsh.dev/versions/main/docs/signed-packages.md).

## Development

With `nsh-dev.aar`:

```java
if (BuildConfig.DEBUG) {
    nsh.connectDevServer("ws://127.0.0.1:8790/ws");
} else {
    nsh.loadAssetBundle("nsh");
}
```

Run `nsh dev App.tsx` on your computer. For an emulator or a USB device, forward the port so the device's own
`127.0.0.1` reaches the server:

```sh
adb reverse tcp:8790 tcp:8790
```

Otherwise use the LAN address `nsh dev` prints. Assets come from the dev server over plain HTTP, so `nsh-dev.aar`
declares `android:usesCleartextTraffic="true"`, which the manifest merger applies to the app (a network security
config of the app may override it). The release `nsh.aar` does not.

## Activity setup

- **Back button.** `NshView` gets back presses by itself while the app wants them (an open dialog, a pushed page, a
  `BackHandler` listener), and leaves them to the activity otherwise. With `android:enableOnBackInvokedCallback="true"`
  on Android 13 and newer it registers an `OnBackInvokedCallback`; elsewhere (Android 12 and older, or the attribute
  off) it takes the back key before the activity's `onBackPressed`, so before AndroidX's `OnBackPressedDispatcher`
  and the fragments' callbacks. No forwarding is needed, in an activity or a fragment. A host that already forwards
  presses to `handleBack()` keeps working: a press goes to the app once.

  For predictive back on Android 13+, set `android:enableOnBackInvokedCallback="true"` on the `<application>`, as
  packaged NSH apps do.
- **Keyboard.** `NshView` scrolls focused inputs clear of the keyboard itself. Leave `android:windowSoftInputMode` unset
  or use `adjustResize`; with `adjustPan` the system moves the whole window instead.
- **Safe area.** The view reports as insets only the parts of the system bars and the keyboard that overlap it, so an
  `NshView` below a toolbar gets no top inset. For edge-to-edge content, draw behind the system bars and let the app use
  `env(safe-area-inset-*)` padding / `safeAreaInsets()` (`safe_area()` in Rust).
- **Configuration changes.** An activity recreated on rotation or a theme change destroys the view, and the app starts
  again from scratch. To keep it running, declare the changes the activity handles itself; packaged NSH apps use:

  ```xml
  <activity android:name=".MainActivity"
      android:configChanges="orientation|screenSize|screenLayout|smallestScreenSize|keyboard|keyboardHidden|navigation|uiMode|density|fontScale|locale|layoutDirection"
      android:windowSoftInputMode="adjustResize" />
  ```

  `NshView` follows the new size, color scheme, font scale, display density and layout direction itself; the app keeps
  its state. Scroll positions are restored in logical coordinates within the new content bounds. Sticky views and
  open modal windows follow the new density too.
- **Lifecycle.** Call `destroy()` when the hosting activity or fragment goes away.

## See also

- [Building with Rust](https://nsh.dev/versions/main/docs/rust.md)
- [Embedding in iOS apps](https://nsh.dev/versions/main/docs/ios.md)
- [Native components](https://nsh.dev/versions/main/docs/native-components.md)
- [Signed packages](https://nsh.dev/versions/main/docs/signed-packages.md)
- [Packaging](https://nsh.dev/versions/main/docs/packaging.md): a standalone APK without writing any Java

Source: https://nsh.dev/versions/main/docs/android

---

# macOS

NSH apps also run as native Mac apps. The macOS backend renders them with AppKit views and Core Animation and lays out
text with CoreText; the core, the reactive graph, the renderer, Taffy layout and the native modules are the
same as on iOS and Android, so one app runs everywhere. On macOS, `os()` is `Os::MacOs` (`platform.os` is `"macos"`
in TSX) and TSX's `desktop={{…}}` props apply. The window's title, a title bar of the app's own, the menu bar and
context menus come from `nsh_core::element::desktop` in Rust ([Desktop title bars](https://nsh.dev/versions/main/docs/rust.md#desktop-title-bars)) and
[`nsh/desktop`](https://nsh.dev/versions/main/modules/nsh-desktop.md) in TSX.

The macOS backend behaves like a desktop app: mouse, trackpad and keyboard input, resizable windows, dialogs
over the window and a menu bar.

## Requirements

- **macOS 14** or later, where the app runs.
- Xcode's command line tools (`xcode-select --install`), to build Rust apps' runners and NSH's macOS runtime from a
  checkout, and to package apps (`codesign`, `sips`). The distribution made with `cargo xtask dist` on a Mac ships the
  runtime of TSX apps in `runtime/macos/`.

## Running an app

A Rust app runs from its directory:

```sh
nsh run --target macos         # the default on a Mac
```

`nsh` builds a debug runner with your crate and opens the app in a window, with its logs (`log::info!` and the rest)
in the terminal; a change to the crate's Rust code builds the runner again and restarts the app. `cargo run` starts
the same root from the crate's `src/main.rs`, which `nsh init --template rust` writes: [`run_app`](#embedding-in-a-mac-app)
with `AppSource::Rust`.

A TSX app names its entry:

```sh
nsh run App.tsx --target macos
```

The app opens in an AppKit window (1200×800 by default), with hot reload, logs in the terminal and the error overlay as
on the other targets; Cmd+R reloads the latest build. The menu bar and the window show the app's name (nsh.json
`"name"`, else its directory's). In a checkout, `nsh run` builds the development host
(`nsh-macos-host`) first. Stopping `nsh run` closes the window, and closing the window ends `nsh run`. The host also
runs a built bundle on its own:

```sh
nsh build my-app --release -o build
dist/nsh/runtime/macos/nsh-macos-host --bundle build/bundle.nshc --window-size 1200x800   # in a checkout: target/debug/nsh-macos-host
```

`--window-size` is the window's initial size (TSX apps); the window can be resized. `--display <n>` (`nsh run` / `nsh test
--target macos --display <n>`) centers it on display `n`: `1` is the primary display, the one with the menu bar.

`nsh test --target macos` runs a TSX app's tests in macOS windows, on a secondary display when there is one (the main
screen stays yours; `--display <n>` picks another): each app a test opens gets a window of its own, at the size the
test asks for even on a display shorter than it, and
the steps click, type and scroll with the system's input at the views their selectors name
([Testing](https://nsh.dev/versions/main/docs/testing-and-trace.md#on-a-real-platform)).

### Performance monitor

`--fps` (`AppOptions { fps: true, .. }` in a Rust app's `run_app`, `AppView::set_fps_monitor(true)` when embedding,
`nsh run App.tsx --target macos --fps`, the host's `--fps`, or a packaged TSX app's `open -a MyApp --args --fps`) shows a panel at the top right of the
app that updates twice a second:

| Row | Measures |
|---|---|
| `FPS` | Frames shown over the last second: display refreshes in which the app changed (an idle app reads low; that is not slowness). `max` is what the main thread could keep up with, then the display's rate (120 Hz on ProMotion screens). |
| `TICK` | The gaps between display refreshes as they arrived (mean, p95) and `gap`, the p95 gap between shown frames: one refresh (8.3 ms at 120 Hz) when nothing is late. |
| `MAIN` | Main-thread time per frame (applying the engine's changes, drawing text and canvases, animations, input), its 95th percentile, and `drop`: the share of frames that took longer than one refresh. |
| `JS` / `CORE` | Per commit: your code (handlers, timers, list rows) and NSH's core (layout, text, diffing); commits per second, native view changes per commit. |
| `HOP` | How long changes wait between the engine thread and the main thread; how busy the engine thread is. |
| `CPU` / `GPU` / `MEM` | The process: CPU (100% is one core), its GPU share, its memory footprint (Activity Monitor's figure). |

The bars below are the last 120 frames' main-thread time against one refresh (the line): green within half of it, amber
within it, red over. While the panel shows, the readings are also logged once a second (target `nsh::perf`, in the
Linux backend's shape with macOS's frame phases `tick`, `drain` and `canvas`; milliseconds as mean/p50/p95/max), which
`nsh test --fps -v` shows and `examples/gallery/tools/perf.py` reads. Measure release builds; the monitor costs nothing
while it is off.

## Packaging

```sh
nsh package --target macos [--run]           # a Rust app, from its directory
nsh package App.tsx --target macos [--run]   # a TSX app
```

Writes an app bundle:

```text
.nsh/out/<Name>.app/Contents/
  Info.plist
  MacOS/<Name>               the executable: a Rust app's own runner, built with its crate; nsh's release runner for TSX
  Resources/nsh/bundle.nshc  a TSX app, compiled
  Resources/nsh/assets/…     the assets it imports (a Rust crate's `assets!()` too)
  Resources/nsh/app.json     the window title and the app's appearance
  Resources/AppIcon.icns     the icon, when nsh.json names one (converted with sips)
```

The `.app` is signed ad hoc, so it runs on the Mac that built it. To distribute it, sign it with a Developer ID and
notarize it. `--run` opens the app after packaging it.

## Embedding in a Mac app

The `nsh-platform-macos` crate (from the NSH repository) gives a Rust Mac app `AppView`: one NSH engine as an `NSView`.
Each `AppView` is independent; several can run at once. It runs a Rust root, the root component of your crate:

```rust
use std::rc::Rc;
use nsh_platform_macos::{
    objc2::MainThreadMarker, objc2_app_kit::NSWindow, set_ui_sets, AppOptions, AppView, Root,
};

fn show(window: &NSWindow) -> Rc<AppView> {
    // Once, before the first view: the UI sets the apps import (NSH's and your crate's).
    set_ui_sets(vec![nsh_base::registry(), my_app::registry()]);
    let mtm = MainThreadMarker::new().expect("main thread");
    let view = AppView::new(mtm, AppOptions::default());
    // register native components here, before loading
    view.load(Root::of::<my_app::App>().into());
    window.setContentView(Some(&view.view()));
    // Keep the view while the window shows it; `stop` it when the window closes.
    view
}
```

`Root::tokens` gives the root its [theme](https://nsh.dev/versions/main/docs/rust.md#theme) (`nsh_base::Theme::from_json(json)?.into_tokens()`) and
`Root::app_id` the id its data is kept under. A TSX bundle that `nsh build` wrote loads into the same view:

```rust
use nsh_platform_macos::{AppOptions, AppView, AssetBase, Bundle};

let view = AppView::new(mtm, AppOptions {
    asset_base: Some(AssetBase::Directory("app/assets".into())),
    ..AppOptions::default()
});
let code = std::fs::read_to_string("app/bundle.js").expect("bundle");
view.load(Bundle::source(code).into());
```

`AppView::load` replaces whatever ran; `stop` ends the app. `asset_base` tells it where `asset:/` URIs resolve
(`AssetBase::Directory` or `AssetBase::Http`). Bytecode bundles (`bundle.nshc`) load with
`unsafe { Bundle::bytecode(bytes) }`: bytecode is trusted input, so only load it from your own app's files.
For an app that is only an NSH app, `run_app(source, options)` (`AppSource::Rust(root)` or `AppSource::Bundle(bundle)`) opens one `AppView` in a window with a standard menu
(About, Hide, Quit, Edit, Minimize, Zoom, Enter Full Screen, Close), which the app can replace with
`Menu.setApplicationMenu` ([`nsh/desktop`](https://nsh.dev/versions/main/modules/nsh-desktop.md)), and runs until the window closes.
By default, closing the window or choosing Quit stops the engine and returns from `run_app`;
the caller can then finish cleanup or relaunch its executable.

Set `AppOptions { keep_alive_on_close: true, ..Default::default() }` to keep the
standalone session alive when its window closes. Closing hides the window;
reopening from the Dock shows that same window and engine. For an explicit Exit
or update relaunch, call `nsh_platform_macos::quit_app()` from any thread. It
closes the retained window, stops the engine and returns from `run_app`.
`nsh_core::element::desktop::close_window()` follows the chosen window-close policy.


`AppOptions::cache` (or `AppView::set_cache`, for the apps loaded next) sets where the apps keep their caches, the
[images they download](https://nsh.dev/versions/main/docs/images-and-assets.md#kept-on-disk), and how much each keeps (`CacheOptions`: the system's
cache directory and 256 MiB of images by default).

`AppView::set_locale(Some(locale))` and `AppView::set_font_scale(Some(scale))` give the app your app's language and
text size in place of the system's (`None` follows the system's again): `locale()`, `Intl`, `fontScale()` and text
follow at once ([Device and environment](https://nsh.dev/versions/main/docs/device-and-environment.md#in-an-embedding-app)).

`AppView::set_theme_overrides(Some(json))` puts your app's brand over the app's [theme](https://nsh.dev/versions/main/docs/tailwind.md#theme-tokens): a theme file
in the format of `nsh.json`'s `"theme"`, whose tokens win over the app's of the same names in light and dark mode
while the app's others stay; classes such as `bg-primary` restyle at once, and apps loaded later start with it
(`None` gives the app its own theme back; a file that does not parse is an error and changes nothing).

Native components are registered with `AppView::register_component`; see
[Native components](https://nsh.dev/versions/main/docs/native-components.md#registering-on-macos-rust). `set_ui_sets(sets)` sets the UI sets every
engine serves: NSH's (`nsh_base::registry()`) and your crates' (`my_app::registry()`, which `#[native_module]`
makes), so the TSX a view loads imports your Rust components and modules too.

## What differs on macOS

The environment is a desktop's: the safe area and the keyboard height are 0, `idiom()` is the desktop
(`platform.idiom` is `"desktop"`), `os_version()` (`platform.version`) is the macOS version, and dark mode follows the system's appearance live. See
[Device and environment](https://nsh.dev/versions/main/docs/device-and-environment.md).

Input is a desktop's: the mouse, the trackpad (scrolling with momentum, pinch and rotation) and the keyboard.
Selectable text is selected by dragging, double- and triple-clicking, and copied with Cmd+C. Escape, Option+Left,
Cmd+[ and the mouse's back button close the newest dialog or go back in a stack (Escape in a focused field or web page
only leaves it; a page gets these keys first, and keeps those it uses); a `Dialog` is a layer over the whole window
that shows the app's popup and backdrop. Pages show their `header` at the top. A click anywhere in an `Input`, its padding too, puts the caret at the nearest
point. `AlertDialog` shows an `NSAlert` sheet on the window: up to two alert actions in a row (the cancel
action leftmost, the last regular one the default for Return), more actions and an action sheet's actions stacked in
their order with the cancel action last and no default; Escape chooses the cancel action.

### Keyboard

| Keys | Do |
|---|---|
| Return | In an `Input`, what `submitBehavior` says: submit (`onSubmit`), submit and leave the field, or a new line (multiline inputs) |
| Return, keypad Enter, Space | Activate a focused view with `onPress` once on key-down; auto-repeat is consumed |
| Shift+Return, Option+Return, Ctrl+Return | A new line in a multiline input whose return submits |
| Tab, Shift+Tab (Ctrl too) | The next / previous field or pressable view in screen order, within the newest dialog; Option+Tab types a tab in a multiline input |
| Escape | Leaves the focused field; else clears a text selection, then closes the newest dialog or goes back |
| Option+Left, Cmd+[, mouse back button | Go back (not while a field has the focus: there Option+Left moves the caret) |
| Option / Cmd + arrows, with Shift; Option+Delete, Cmd+Delete; Ctrl+A / E / K | Move, select and delete by word and line in a field, as in every Mac app |
| Cmd+Z, Shift+Cmd+Z, Cmd+X / C / V / A | Undo, redo, cut, copy, paste, select all (a `masked` field refuses cut and copy); Cmd+A / Cmd+C select and copy selectable text |
| Arrows; Page Up / Down, Space, Shift+Space, Option+Up / Down; Home / End, Cmd+Up / Down | Scroll the scroll view around the focused view or under the mouse by a line, a page, to the start / end (not while a field has the focus) |
| Cmd+W, Cmd+M, Ctrl+Cmd+F, Cmd+H, Option+Cmd+H, Cmd+Q | Close, minimize, full screen, hide, hide others, quit (`nsh package` and `nsh run` apps' menus) |
| Cmd+R | Reloads the latest build (`nsh run`) |

The app's own shortcuts ([`keymap`](https://nsh.dev/versions/main/modules/nsh.md#keymap)) come before these, except activation keys addressed to a focused pressable view, Quit, Hide,
Minimize and Full Screen, which cannot be bound.

Shortcuts work with any keyboard layout (on a Cyrillic or Greek one, Cmd+C is the key that types C on a US layout).
A return that commits an input method's composition (Chinese, Japanese, ...) never submits. `onKeyPress` reports
what React Native reports: the typed text, `"Enter"`, `"Backspace"`, and `"Escape"`.

Not supported, or different:

- **Zooming scroll views** (`zoomTo`, the zoom props).
- **`mixBlendMode`**, and `brightness()` above 1.
- **Inputs**: content types and autofill, keyboard types, autocapitalization, letter spacing; input accessory views
  are never shown (there is no software keyboard) and `keyboardShouldPersistTaps` is ignored.
- **`WebView`'s `scrollable={false}`** keeps the mouse wheel and the trackpad from scrolling the page: they scroll
  the app's scroll views around it, as on iOS. The page still scrolls with its keyboard (Space, the arrows) and its own
  scripts, and trackpad swipes between its pages (`allowsBackForwardNavigationGestures`) stop as well.
- **Accessibility**: custom `accessibilityActions`.
- **The status bar** and **haptics** (no desktop equivalent).

## See also

- [CLI](https://nsh.dev/versions/main/docs/cli.md): `nsh run --target macos`, `nsh package --target macos`
- [Packaging](https://nsh.dev/versions/main/docs/packaging.md)
- [Platform-specific code](https://nsh.dev/versions/main/docs/platform-specific.md)

Source: https://nsh.dev/versions/main/docs/macos

---

# Windows

NSH apps also run on Windows. The Windows backend draws them in Win32 windows with Direct2D and lays out text with
DirectWrite; the core, the reactive graph, the renderer, Taffy layout and the native modules are the same
as on iOS and Android, so one app runs everywhere. On Windows, `os()` is `Os::Windows` (`platform.os` is `"windows"`
in TSX) and TSX's `desktop={{…}}` props apply. The window's title, a title bar of the app's own, the menu bar and
context menus come from `nsh_core::element::desktop` in Rust ([Desktop title bars](https://nsh.dev/versions/main/docs/rust.md#desktop-title-bars)) and
[`nsh/desktop`](https://nsh.dev/versions/main/modules/nsh-desktop.md) in TSX.

## Requirements

- **Windows 10 1809** or later, or Windows 11.
- The **WebView2 Runtime** for web views. It comes with Windows 11 and with Microsoft Edge on Windows 10; without it a
  `WebView` shows a placeholder.
- **Media Foundation codecs** for the video formats your app plays (videos play through Windows' own media stack).
- To build a Rust app's runner: Visual Studio Build Tools with the C++ workload and the Windows SDK. To build NSH's
  Windows runtime (from a checkout, or `cargo xtask dist` on Windows) also LLVM (for QuickJS' bindings).

## Running an app

On Windows, `nsh run` opens the app in a window. A Rust app runs from its directory:

```sh
nsh run                        # --target windows is the default on Windows
```

`nsh` builds a debug runner with your crate and opens the app, with its logs (`log::info!` and the rest) in the
terminal; a change to the crate's Rust code builds the runner again and restarts the app. `cargo run` starts the same
root from the crate's `src/main.rs`, which `nsh init --template rust` writes: [`run_app`](#embedding-in-a-win32-app)
with `AppSource::Rust`.

A TSX app names its entry, and opens in a 1200×800 window by default, with hot reload, logs in the terminal and the
error overlay as on the other targets:

```sh
nsh run App.tsx
```

In a checkout, `nsh run` builds the development host (`nsh-windows-host.exe`) first; the distribution made on Windows
ships it in `runtime\windows\`. Ctrl-C closes the window, and closing the window ends `nsh run`; the host never
outlives `nsh`, however it ends. The host also runs a built bundle on its own:

```sh
nsh build my-app --release -o build
dist\nsh\runtime\windows\nsh-windows-host --bundle build\bundle.nshc --window-size 390x844   # in a checkout: target\debug\nsh-windows-host
```

`--window-size` is the window's size in points (`<width>x<height>`; TSX apps).

### Performance monitor

`--fps` (`nsh run App.tsx --target windows --fps`, `nsh test --target windows --fps`, the host's `--fps`, or
`AppOptions { fps: true, .. }` in a Rust app's `run_app`) logs the performance monitor's readings once a second
(target `nsh::perf`): frames shown over the display's rate, the main thread's time per frame and its phases (`tick`,
`drain`, `paint`, `present`, `canvas`), the engine's commits, CPU and memory, in the shape the other desktops log
(milliseconds as mean/p50/p95/max). `nsh test --fps -v` shows them and `examples/gallery/tools/perf.py` reads them
([Performance report](https://nsh.dev/versions/main/docs/performance-report.md#windows-win32-direct2d)). Measure release builds; the monitor costs
nothing while it is off.

## Packaging

```sh
nsh package --target windows [--run]           # a Rust app, from its directory
nsh package App.tsx --target windows [--run]   # a TSX app
```

Writes a directory and the same as an archive:

```text
.nsh\out\<Name>\
  <Name>.exe             the executable, with the app's icon: a Rust app's own runner, built with its crate; nsh's release runner for TSX
  nsh\bundle.nshc         a TSX app, compiled
  nsh\assets\…           the assets it imports (a Rust crate's `assets!()` too)
  nsh\app.json           the window title, the app id, the version and the appearance
.nsh\out\<Name>.zip
```

The executable finds `nsh\` next to itself; copy the whole directory (or unpack the `.zip`) wherever the app should
live: nothing is installed. The icon from `nsh.json` is embedded in the executable (Explorer and the taskbar show it)
without any extra tools; packaging on another system keeps the default icon. The app id groups the app's windows in
the taskbar. `--run` launches the app after packaging it. The executable is not signed: sign it with your own
certificate (`signtool`) to distribute it.

## Embedding in a Win32 app

The `nsh-platform-windows` crate (from the NSH repository) gives a Rust Win32 app `AppView`: one NSH engine in a child
window of a window of yours. Each `AppView` is independent; several can run at once. It runs a Rust root, the root
component of your crate:

```rust
use std::rc::Rc;
use nsh_platform_windows::{
    windows::{self, Win32::{Foundation::HWND, System::Ole::OleInitialize, UI::WindowsAndMessaging::MoveWindow}},
    set_ui_sets, AppOptions, AppView, Root,
};

/// Called on the thread that runs your message loop, with your window.
fn embed(parent: HWND) -> windows::core::Result<Rc<AppView>> {
    // Once per thread: COM and OLE (the clipboard, image decoding).
    unsafe { OleInitialize(None)? };
    // Once, before the first view: the UI sets the apps import (NSH's and your crate's).
    set_ui_sets(vec![nsh_base::registry(), my_app::registry()]);
    let view = AppView::new(
        Some(parent),
        AppOptions {
            app_id: "com.example.host".into(),
            ..AppOptions::default()
        },
    )?;
    // register native components here, before loading
    view.load(Root::of::<my_app::App>().into());
    Ok(view)
}

// On WM_SIZE of `parent`:
// unsafe { MoveWindow(view.hwnd(), 0, 0, width, height, true) };
```

A TSX bundle that `nsh build` wrote loads into the same view, with `asset_base` set to its `assets` directory:

```rust
let code = std::fs::read_to_string("app/bundle.js").expect("bundle");
view.load(Bundle::source(code).into());
```

The view is a child window: your message loop runs it, and you place it with `MoveWindow` on its `hwnd()` when the
parent resizes. Make it on the thread of the window it is in: its lifecycle follows that window's top-level
window, the one it was made under. `AppView::load` replaces whatever ran; `stop` (or destroying the window) ends the app. `asset_base`
tells it where `asset:/` URIs resolve (`AssetBase::Directory` or `AssetBase::Http`). Bytecode bundles (`bundle.nshc`)
load with `unsafe { Bundle::bytecode(bytes) }` (or `Bundle::read_trusted(path)`, unsafe too): QuickJS bytecode is trusted input, so
only load it from your own app's files. A standalone window is `nsh_platform_windows::run_app(source, options)`, with
`AppSource::Rust(root)` or `AppSource::Bundle(bundle)`. `Root::tokens` gives a root its [theme](https://nsh.dev/versions/main/docs/rust.md#theme) and
`Root::app_id` the id its data is kept under.

`AppOptions::cache` (or `AppView::set_cache`, for the apps loaded next) sets where the apps keep their caches, the
[images they download](https://nsh.dev/versions/main/docs/images-and-assets.md#kept-on-disk), and how much each keeps (`CacheOptions`: the system's
cache directory and 256 MiB of images by default).

`AppView::set_locale(Some(locale))` and `AppView::set_font_scale(Some(scale))` give the app your app's language and
text size in place of the system's (`None` follows the system's again): `locale()`, `Intl`, `fontScale()` and text
follow at once ([Device and environment](https://nsh.dev/versions/main/docs/device-and-environment.md#in-an-embedding-app)).

`AppView::set_theme_overrides(Some(json))` puts your app's brand over the app's [theme](https://nsh.dev/versions/main/docs/tailwind.md#theme-tokens): a theme file
in the format of `nsh.json`'s `"theme"`, whose tokens win over the app's of the same names in light and dark mode
while the app's others stay; classes such as `bg-primary` restyle at once, and apps loaded later start with it
(`None` gives the app its own theme back; a file that does not parse is an error and changes nothing).

Native components are registered with `AppView::register_component`; see
[Native components](https://nsh.dev/versions/main/docs/native-components.md#registering-on-windows-rust). `set_ui_sets(sets)` sets the UI sets every
engine serves: NSH's (`nsh_base::registry()`) and your crates' (`my_app::registry()`, which `#[native_module]`
makes), so the TSX a view loads imports your Rust components and modules too.

## What differs on Windows

The environment is a desktop's: the safe area and the keyboard height are 0, `idiom()` is the desktop
(`platform.idiom` is `"desktop"`) and `os_version()` (`platform.version`) is `"10.0"` (on Windows 11 too: Windows kept the version number). Dark mode
follows Settings > Personalization > Colors live, `fontScale()` the Text size setting, reduce motion the animation
effects setting and the locale the user's regional format. See [Device and environment](https://nsh.dev/versions/main/docs/device-and-environment.md).

The `cursor` style follows updates while the mouse rests over a view. When a batch changes the cursor,
Windows applies the new shape or `"none"` after the whole batch, using the view under the pointer.
The title bar and resize borders keep their system cursors.

### Keyboard

| Keys | Do |
|---|---|
| Return | In an `Input`, what `submitBehavior` says: submit (`onSubmit`), submit and leave the field, or a new line (multiline inputs) |
| Shift+Return, Alt+Return | A new line in a multiline input whose return submits (Ctrl+Return submits) |
| Tab, Shift+Tab | The next / previous text field, within the newest dialog; the field's text is selected, as in Windows' dialogs |
| Escape | Leaves the focused field; else clears a text selection, then closes the newest dialog or goes back |
| Alt+Left, Browser Back key, mouse back button | Go back (also from a field) |
| Ctrl+arrows, Home / End, Ctrl+Home / End, with Shift; Ctrl+Backspace / Delete | Move, select and delete by word and line in a field, as in every Windows app |
| Ctrl+Z, Ctrl+Y, Ctrl+X / C / V / A; Shift+Delete, Ctrl+Insert, Shift+Insert | Undo, redo, cut, copy, paste, select all (a `masked` field refuses cut and copy); Ctrl+A / Ctrl+C select and copy selectable text |
| Arrows; Page Up / Down, Space, Shift+Space; Home / End, Ctrl+Home / End | Scroll the scroll view around the focused view or under the mouse by a line, a page, to the start / end (not while a field has the focus) |
| F11, Alt+F4 | Full screen, close the window (`nsh package` and `nsh run` apps) |
| Ctrl+R, F5 | Reload the latest build (`nsh run`) |

Shortcuts work with any keyboard layout (on a Cyrillic or Greek one, Ctrl+C is the key that types C on a US layout).
A return that commits an input method's composition (Chinese, Japanese, ...) never submits. `onKeyPress` reports
what React Native reports: the typed text, `"Enter"`, `"Backspace"`, and `"Escape"`; pasted text is not reported.

The app's own shortcuts ([`keymap`](https://nsh.dev/versions/main/modules/nsh.md#keymap)) come before a focused field's keys, navigation
and scrolling; Alt+F4, F11 and Ctrl+Q cannot be bound.

Different, or not supported:

- **`WebView`**: a page inside a view with a 3D transform (perspective) is not shown, and a `backdropFilter` over a
  page does not blur it. `baseUrl` takes `http(s)` URLs. A native component that brings a window of its own
  stays above everything NSH draws.
- **Video**: the formats the installed codecs decode; no poster; the control bar always shows with `controls`.
- **Zooming scroll views** (`zoomTo`, the zoom props); the scroll indicator cannot be dragged.
- **`mixBlendMode` and `backdropFilter`** are drawn, but not inside a view that has a `filter` or a 3D transform;
  `borderCurve: "continuous"` draws circular corners.
- **Text**: head and middle ellipses on a single line only (more lines get a tail ellipsis); color emoji from COLR
  fonts only; small caps only where the font has them.
- **Text inputs**: keyboard types and autofill do not apply (there is no software keyboard); Tab moves between text
  fields. A right click opens the edit menu (Undo, Cut, Copy, Paste, Delete, Select All), as on selectable text (Copy,
  Select All).
- **Accessibility** (UI Automation): alert dialogs and toasts are not exposed; headings report
  level 1.
- **Input accessory views** and the **status bar** (no desktop equivalent).

## See also

- [CLI](https://nsh.dev/versions/main/docs/cli.md): `nsh run --target windows`, `nsh package --target windows`
- [Packaging](https://nsh.dev/versions/main/docs/packaging.md)
- [Platform-specific code](https://nsh.dev/versions/main/docs/platform-specific.md)

Source: https://nsh.dev/versions/main/docs/windows

---

# Linux

NSH apps also run on Linux. The Linux backend renders them with GTK 4 widgets and lays out text with Pango; the core,
the reactive graph, the renderer, Taffy layout and the native modules are the same as on iOS and Android,
so one app runs everywhere. On Linux, `os()` is `Os::Linux` (`platform.os` is `"linux"` in TSX) and TSX's
`desktop={{…}}` props apply. The window's title, a title bar of the app's own, the menu bar and context menus come
from `nsh_core::element::desktop` in Rust ([Desktop title bars](https://nsh.dev/versions/main/docs/rust.md#desktop-title-bars)) and
[`nsh/desktop`](https://nsh.dev/versions/main/modules/nsh-desktop.md) in TSX.

## Requirements

- **GTK 4.14** or later. To build a Rust app's runner or NSH's Linux runtime (from a checkout, or `cargo xtask
  dist` on Linux) you need their development packages and clang: `libgtk-4-dev clang` on Debian and Ubuntu (24.04 or
  later), `gtk4 clang` on Arch, `gtk4-devel clang` on Fedora.
- **WebKitGTK 6.0** (2.40 or later) for web views: `libwebkitgtk-6.0-dev` on Debian and Ubuntu, `webkitgtk-6.0` on
  Arch, `webkitgtk6.0-devel` on Fedora to build the runtime. The development host and the release runner use it by
  default, so packaged apps need WebKitGTK 6.0 where they run (`libwebkitgtk-6.0-4` on Debian and Ubuntu; GNOME
  desktops have it). `cargo xtask dist` on a machine without its development files builds a runtime whose web views
  are placeholders, and whose apps need only GTK.
- **GStreamer** plugins for the video formats your app plays (GTK plays video through GStreamer).

## Running an app

On Linux, `nsh run` opens the app in a GTK window. A Rust app runs from its directory:

```sh
nsh run                        # --target linux is the default on Linux
```

`nsh` builds a debug runner with your crate and opens the app, with its logs (`log::info!` and the rest) in the
terminal; a change to the crate's Rust code builds the runner again and restarts the app. `cargo run` starts the same
root from the crate's `src/main.rs`, which `nsh init --template rust` writes: [`run_app`](#embedding-in-a-gtk-app)
with `AppSource::Rust`.

A TSX app names its entry, and opens in a 390×844 window by default, with hot reload, logs in the terminal and the
error overlay as on the other targets:

```sh
nsh run App.tsx
```

In a checkout, `nsh run` builds the development host (`nsh-linux-host`) first; the distribution made on Linux ships
it in `runtime/linux/`. Ctrl-C closes the window, and closing the window ends `nsh run`. The host also runs a built
bundle on its own:

```sh
nsh build my-app --release -o build
dist/nsh/runtime/linux/nsh-linux-host --bundle build/bundle.nshc --window-size 1024x768   # in a checkout: target/debug/nsh-linux-host
```

`--window-size` is the window's default size (TSX apps); tiling window managers may give the window another one.

## Packaging

```sh
nsh package --target linux [--run]           # a Rust app, from its directory
nsh package App.tsx --target linux [--run]   # a TSX app
```

Writes a directory and the same as an archive:

```text
.nsh/out/<Name>/
  <Name>                 the executable: a Rust app's own runner, built with its crate; nsh's release runner for TSX
  nsh/bundle.nshc        a TSX app, compiled
  nsh/assets/…           the assets it imports (a Rust crate's `assets!()` too)
  nsh/app.json           the window title and the application id
  <id>.desktop           a desktop entry (StartupWMClass is the id)
  <id>.png               the icon, when nsh.json names one
.nsh/out/<Name>.tar.gz
```

The executable finds `nsh/` next to itself (a symbolic link to it, in `~/.local/bin` say, works too). GTK 4, Pango and
WebKitGTK 6.0 must be installed where the app runs. To show the app in a desktop's launcher, put the executable (or a link) on the
`PATH`, the `.desktop` file in `~/.local/share/applications` and the icon in an icon theme directory. `--run` launches
the app after packaging it.

## Embedding in a GTK app

The `nsh-platform-linux` crate (from the NSH repository) gives a Rust GTK app `AppView`: one NSH engine as a GTK widget.
Each `AppView` is independent; several can run at once. It runs a Rust root, the root component of your crate:

```rust
use std::rc::Rc;
use nsh_platform_linux::{gtk4 as gtk, set_ui_sets, AppOptions, AppView, Root};
use gtk::prelude::*;

fn main() -> gtk::glib::ExitCode {
    // Once, before the first view: the UI sets the apps import (NSH's and your crate's).
    set_ui_sets(vec![nsh_base::registry(), my_app::registry()]);
    let app = gtk::Application::builder().application_id("com.example.host").build();
    app.connect_activate(|app| {
        let window = gtk::ApplicationWindow::builder().application(app).default_width(390).default_height(844).build();
        let view = AppView::new(AppOptions::default());
        // register native components here, before loading
        view.load(Root::of::<my_app::App>().into());
        window.set_child(Some(&view.widget()));
        // The window keeps the view; closing it stops the app.
        let keep = std::cell::RefCell::new(Some(Rc::clone(&view)));
        window.connect_destroy(move |_| if let Some(view) = keep.take() { view.stop() });
        window.present();
    });
    app.run()
}
```

`Root::tokens` gives the root its [theme](https://nsh.dev/versions/main/docs/rust.md#theme) and `Root::app_id` the id its data is kept under. A TSX
bundle that `nsh build` wrote loads into the same view, with `asset_base` set to its `assets` directory:

```rust
use nsh_platform_linux::{AppOptions, AppView, AssetBase, Bundle};

let view = AppView::new(AppOptions {
    asset_base: Some(AssetBase::Directory("app/assets".into())),
    ..AppOptions::default()
});
let code = std::fs::read_to_string("app/bundle.js").expect("bundle");
view.load(Bundle::source(code).into());
```

`AppView::load` replaces whatever ran; `stop` ends the app. `asset_base` tells it where `asset:/` URIs resolve
(`AssetBase::Directory` or `AssetBase::Http`). Bytecode bundles (`bundle.nshc`) load with `unsafe { Bundle::bytecode(bytes) }`:
QuickJS bytecode is trusted input, so only load it from your own app's files. A standalone window is
`nsh_platform_linux::run_app(source, options)`, with `AppSource::Rust(root)` or `AppSource::Bundle(bundle)`.

`AppOptions::cache` (or `AppView::set_cache`, for the apps loaded next) sets where the apps keep their caches, the
[images they download](https://nsh.dev/versions/main/docs/images-and-assets.md#kept-on-disk), and how much each keeps (`CacheOptions`: the system's
cache directory and 256 MiB of images by default).

`AppView::set_locale(Some(locale))` and `AppView::set_font_scale(Some(scale))` give the app your app's language and
text size in place of the system's (`None` follows the system's again): `locale()`, `Intl`, `fontScale()` and text
follow at once ([Device and environment](https://nsh.dev/versions/main/docs/device-and-environment.md#in-an-embedding-app)).

`AppView::set_theme_overrides(Some(json))` puts your app's brand over the app's [theme](https://nsh.dev/versions/main/docs/tailwind.md#theme-tokens): a theme file
in the format of `nsh.json`'s `"theme"`, whose tokens win over the app's of the same names in light and dark mode
while the app's others stay; classes such as `bg-primary` restyle at once, and apps loaded later start with it
(`None` gives the app its own theme back; a file that does not parse is an error and changes nothing).

Native components are registered with `AppView::register_component`; see [Native components](https://nsh.dev/versions/main/docs/native-components.md#registering-on-linux-rust).
`set_ui_sets(sets)` sets the UI sets every engine serves: NSH's (`nsh_base::registry()`) and your crates'
(`my_app::registry()`, which `#[native_module]` makes), so the TSX a view loads imports your Rust components and
modules too.

## What differs on Linux

The environment is a desktop's: the safe area and the keyboard height are 0, `idiom()` is the desktop
(`platform.idiom` is `"desktop"`), `os_version()` (`platform.version`) is the kernel's major and minor version, and dark mode follows the desktop's setting
(through the XDG settings portal) live. See [Device and environment](https://nsh.dev/versions/main/docs/device-and-environment.md).

### Keyboard

| Keys | Do |
|---|---|
| Return | In an `Input`, what `submitBehavior` says: submit (`onSubmit`), submit and leave the field, or a new line (multiline inputs) |
| Shift+Return, Alt+Return | A new line in a multiline input whose return submits (Ctrl+Return submits) |
| Tab, Shift+Tab | The next / previous field in screen order, within the newest dialog |
| Escape | Leaves the focused field; else clears a text selection, then closes the newest dialog or goes back |
| Alt+Left, Back key, mouse back button | Go back (also from a field) |
| Ctrl+arrows, Home / End, with Shift; Ctrl+Backspace / Delete | Move, select and delete by word and line in a field, as in every GTK app |
| Ctrl+Z, Ctrl+Shift+Z, Ctrl+X / C / V / A | Undo, redo, cut, copy, paste, select all (a `masked` field refuses cut and copy); Ctrl+A / Ctrl+C select and copy selectable text |
| Arrows; Page Up / Down, Space, Shift+Space; Home / End | Scroll the scroll view around the focused view or under the mouse by a line, a page, to the start / end (not while a field has the focus) |
| Ctrl+W, F11, Ctrl+Q | Close the window, full screen, quit (`nsh package` and `nsh run` apps) |
| Ctrl+R | Reloads the latest build (`nsh run`) |

The app's own shortcuts ([`keymap`](https://nsh.dev/versions/main/modules/nsh.md#keymap)) are a window-wide shortcut controller; Ctrl+Q and
F11 cannot be bound.

Shortcuts work with any keyboard layout (on a Cyrillic or Greek one, Ctrl+C is the key that types C on a US layout).
A return that commits an input method's composition (Chinese, Japanese, ...) never submits. `onKeyPress` reports
what React Native reports: the typed text, `"Enter"`, `"Backspace"`, and `"Escape"`; pasted text is not reported.

Web views are WebKitGTK pages, drawn inside NSH's views: sheets, dialogs, toasts and views after them draw over a page,
and parents clip it and fade it. Their website data (cookies, storage, the cache) is kept per app, under
`~/.local/share/<app id>/webkit` and `~/.cache/<app id>/webkit`. The `webview` capability also applies to the pages of
frames: an `iframe` of a host your app was not granted stays empty. Escape in a page leaves it, as in a text field
(unless the page uses it); Alt+Left and the mouse's back button go back in the page while it has a history.

Not supported:

- **Video `rate`**: GTK plays at normal speed only. `onEnd` only comes for videos that do not loop.
- **Zooming scroll views** (`zoomTo`, the zoom props).
- **`mixBlendMode` and `backdropFilter`** (the background color still draws). Backdrop blur is not implemented;
  experiments using GTK 4.22's copy and paste nodes are not part of the renderer.
- **Input accessory views** and the **status bar** (no desktop equivalent).
- **Accessibility**: `accessible` grouping, custom `accessibilityActions`; live regions are announced instead.

## See also

- [CLI](https://nsh.dev/versions/main/docs/cli.md): `nsh run --target linux`, `nsh package --target linux`
- [Packaging](https://nsh.dev/versions/main/docs/packaging.md)
- [Platform-specific code](https://nsh.dev/versions/main/docs/platform-specific.md)

Source: https://nsh.dev/versions/main/docs/linux

---

# GPUI

The GPUI backend draws NSH apps with [GPUI](https://gpui-kit.com) (GPUI Fast), the GPU-accelerated UI framework that
GPUI Kit is built on, on macOS, Windows and Linux alike. It is the backend for embedding in GPUI and GPUI Kit apps: an
`AppView` is a GPUI view, so a GPUI or GPUI Kit app shows NSH apps, a Rust root of its own or TSX it loads, anywhere
in its own element tree. Standalone apps
run and are packaged with each desktop's own backend: [macOS](https://nsh.dev/versions/main/docs/macos.md) (AppKit), [Windows](https://nsh.dev/versions/main/docs/windows.md) (Win32)
and [Linux](https://nsh.dev/versions/main/docs/linux.md) (GTK). The core, the reactive graph, the renderer,
Taffy layout and the native modules are the same as on every other platform, so one app runs
everywhere. `os()` (`platform.os` in TSX) is the OS it runs on (macOS, Windows or Linux) and TSX's `desktop={{…}}`
props apply.

Every element and module of the [macOS](https://nsh.dev/versions/main/docs/macos.md) (AppKit), [Windows](https://nsh.dev/versions/main/docs/windows.md) (Win32) and
[Linux](https://nsh.dev/versions/main/docs/linux.md) (GTK) backends is there; where GPUI draws something its own way, [Differences](#differences)
says how.

## How it works

- **One element per surface.** A surface is one GPUI element that fills the space its parent gives it and paints the
  whole view tree with GPUI's primitives: quads, shadows, paths, glyphs and images. NSH keeps one retained view per
  node, as on Windows, and redraws only when a commit changed something.
- **Text is shaped on the engine thread** with GPUI's text system (the app's own fonts), broken into lines by NSH;
  the main thread only paints the glyphs.
- **One hop per commit.** The engine runs on its own thread; each commit is one closure sent to GPUI's main thread,
  which notifies the view.
- **Input** comes from GPUI's mouse, scroll, key and input method events; hit testing, presses, the responder system,
  scrolling and text editing are the same logic as the Windows backend's.

## Requirements

- macOS, Windows or Linux, with a GPU GPUI can draw with (Metal on macOS, DirectX on Windows, Vulkan on Linux).
- On macOS, building your GPUI app or the runtime from a checkout uses Xcode's Metal Toolchain (`xcodebuild -downloadComponent
  MetalToolchain`), which compiles GPUI's shaders ahead of time. On a Mac without it, `nsh run` builds
  the runtime with GPUI's `runtime-shaders` feature and say so: the shaders are compiled when the app starts (a fraction
  of a second the first time, cached by macOS after that).
- On Linux: a Vulkan driver, Wayland or X11 with `libxkbcommon`, GTK 3 and WebKitGTK 4.1 (web views) and GStreamer
  1.20 or later with its base and good plug-ins (videos). Web views need X11: on a Wayland desktop run the app under
  Xwayland (`WAYLAND_DISPLAY=` empty), else they show a placeholder. Building the runtime from a checkout also needs
  the development packages; on Debian and Ubuntu:

  ```sh
  sudo apt-get install clang libclang-dev pkg-config libfontconfig-dev libfreetype-dev libwayland-dev libx11-xcb-dev \
    libxcb1-dev libxkbcommon-dev libxkbcommon-x11-dev libzstd-dev libvulkan1 libgtk-3-dev libwebkit2gtk-4.1-dev \
    libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev gstreamer1.0-plugins-good
  ```

## Running an app

A Rust app runs inside your GPUI app: embed its root with `AppView` ([Embedding in a GPUI app](#embedding-in-a-gpui-app))
and `cargo run` the GPUI app; your crate and the app are one Cargo build. On its own, a Rust app runs on this OS's own
backend (`nsh run --target macos`, `windows` or `linux`).

A TSX app runs in the GPUI development host:

```sh
nsh run App.tsx --target gpui
```

It opens the app in a GPUI window (1200×800 by default), as a GPUI app that embeds it shows it, with hot reload, logs in
the terminal and the error overlay as on the other targets. The development host (`nsh-gpui-host`) runs in place on
every OS, with no app bundle around it. In a checkout, `nsh run` builds it first; the distribution ships it in `runtime/gpui/`. The host also runs a built
bundle on its own:

```sh
nsh build my-app --release -o build
dist/nsh/runtime/gpui/nsh-gpui-host --bundle build/bundle.nshc --window-size 390x844   # in a checkout: target/debug/nsh-gpui-host
```

`--window-size` is the window's size in points (`<width>x<height>`).

## Packaging

A GPUI app ships NSH inside its own executable: it embeds the app's Rust root or TSX bundle with `AppView` ([Embedding in a GPUI
app](#embedding-in-a-gpui-app)) and is built and distributed as the GPUI app it is. A standalone NSH app is packaged
with this OS's own target: [`--target macos`](https://nsh.dev/versions/main/docs/macos.md#packaging), [`--target windows`](https://nsh.dev/versions/main/docs/windows.md#packaging) or
[`--target linux`](https://nsh.dev/versions/main/docs/linux.md#packaging) ([Packaging](https://nsh.dev/versions/main/docs/packaging.md)).

On Linux, a GPUI app with web views and videos links WebKitGTK 4.1 and GStreamer dynamically, so the machines it runs
on need them installed, with GTK 3 and GStreamer's base and good plug-ins (Debian / Ubuntu: `libwebkit2gtk-4.1-0`,
`libgstreamer1.0-0`, `libgstreamer-plugins-base1.0-0`, `gstreamer1.0-plugins-good`), besides a Vulkan driver and
`libxkbcommon`.

## Embedding in a GPUI app

The `nsh-platform-gpui` crate (from the NSH repository) gives a Rust GPUI app `AppView`: one NSH engine as a GPUI
view (`Entity<AppView>`), which fills the space its parent element gives it. Each `AppView` is independent; several
can run at once. It runs a Rust root, the root component of your crate:

```rust
use gpui::{AppContext, WindowOptions};
use nsh_platform_gpui::{set_ui_sets, App, AppOptions, AppView, Root};

// Once, before the first view: the UI sets the apps import (NSH's and your crate's).
set_ui_sets(vec![nsh_base::registry(), my_app::registry()]);
gpui_platform::application().run(|cx| {
    cx.open_window(WindowOptions::default(), |window, cx| {
        cx.new(|cx| {
            let view = AppView::new(AppOptions::default(), window, cx);
            view.load(App::Rust(Root::of::<my_app::App>()));
            view
        })
    })
    .unwrap();
});
```

`Root::tokens` gives the root its [theme](https://nsh.dev/versions/main/docs/rust.md#theme) (`nsh_base::Theme::from_json(json)?.into_tokens()`,
`Theme` is re-exported here) and `Root::app_id` the id its data is kept under. A TSX bundle that `nsh build` wrote
loads into the same view:

```rust
use nsh_platform_gpui::{App, Bundle};

let code = std::fs::read_to_string("app/bundle.js").expect("bundle");
view.load(App::Js(Bundle::source(code)));
```

Put the entity in your element tree like any other view (a GPUI Kit `Root`, a panel, a dock). `AppView::load`
replaces whatever ran; `stop` (or dropping the view) ends the app. `AppOptions::asset_base` tells it where `asset:/`
URIs resolve (`AssetBase::Directory` or `AssetBase::Http`). Bytecode bundles (`bundle.nshc`) load with
`unsafe { Bundle::bytecode(bytes) }` (or `Bundle::read_trusted(path)`, unsafe too): QuickJS bytecode is trusted input,
so only load it from your own app's files.

- `open_app_window(source, options, cx)` opens a window with one `AppView` in a running GPUI app.
- `run_app(source, options)` starts GPUI and runs one app in a window until it closes (what the development host does).
- `AppView::register_component(name, factory)` registers a native component of yours before loading
  ([Native components](https://nsh.dev/versions/main/docs/native-components.md)).
- `AppOptions::cache` (or `AppView::set_cache`, for the apps loaded next) sets where the apps keep their caches, the
  [images they download](https://nsh.dev/versions/main/docs/images-and-assets.md#kept-on-disk), and how much each keeps: `CacheOptions { location,
  images }`, `CacheLocation::System` (the default), `Dir(path)` or `Off`, `CachePolicy::Default` (256 MiB),
  `MaxSize(ByteSize::mib(n))` or `Off`.
- `AppView::host()` is the view's channel with the apps it runs ([`host`](https://nsh.dev/versions/main/modules/nsh.md#host)), a
  `HostChannel` any thread may use: `set_params(map)` before loading gives the app its launch parameters
  (`host.params`), `send(name, data)` an event (`host.on`), and `handle(name, |call| …)` answers its
  `host.call(name, data)` and hears its `host.post` (`call.resolve(json)`, `call.reject(message)`, at once or later
  from any thread). Handlers run on the engine thread: hand the call to your GPUI entities (a channel that a
  `cx.spawn` task reads) and answer from there. The macOS, Windows and Linux `AppView`s have the same `host()`.
  Its `handle_open_url(|request| …)` sees the URLs the app opens ([`openUrl`](https://nsh.dev/versions/main/modules/nsh.md#openurl))
  before the system does: `request.handled()` when your app routed the URL itself, `request.decline()` (or dropping
  the request) for the system to open it with GPUI's `open_url`.
- `AppOptions::limits` (or `AppView::set_limits`, for the apps loaded next) sets the VM limits: the JS heap, the
  stack, the time budgets and the node quota ([Sandbox and capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md)). Embedded apps get `Limits::default()` (a
  256 MB heap); the development host runs apps on its own, with `Limits::standalone()`.
- `AppOptions::transparent` makes the view see-through: it draws no window background, and `open_app_window` /
  `run_app` open a transparent window, so what the app leaves unpainted shows what is behind the window (desktop
  widgets, overlays). False by default.
- `AppView::connect_dev_server(url, cx)` (feature `dev`) loads the app from `nsh dev` and reloads it as you edit,
  with the error overlay over the view; `AppView::on_error` keeps hearing the app's errors.
- `AppView::on_app_error(|error| …)` hears the app's errors: `error.kind` (the app failed to load, an uncaught
  exception, the VM stopped), `error.is_fatal()` when no JS of the app runs again, `error.message`, `error.stack`
  and `error.package` (the id and build of the signed package it came from). `AppView::on_error` gets the same
  errors as text.
- `AppView::set_locale(locale, cx)` and `AppView::set_font_scale(scale, cx)` give the app your app's language and
  text size in place of the system's (`None` follows the system's again): `locale()`, `Intl`, `fontScale()` and text
  follow at once ([Device and environment](https://nsh.dev/versions/main/docs/device-and-environment.md#in-an-embedding-app)).
- `AppView::run_package(&package)` runs a [signed package](https://nsh.dev/versions/main/docs/signed-packages.md#loading-packages-in-a-host-app)
  from `verify_package` or `load_package`; `accept_package` records it once your app decided it is healthy.
- `set_ui_sets(sets)` sets the UI sets every engine serves: NSH's (`nsh_base::registry()`) and your crates'
  (`my_app::registry()`, which `#[native_module]` makes; [Building with Rust](https://nsh.dev/versions/main/docs/rust.md)), and gives your app's own sets: an app reaches the functions and classes of one by name with
  [`nativeModule`](https://nsh.dev/versions/main/modules/nsh.md#nativemodule) and is built with the stock `nsh build`. The repository's
  `examples/embed-gpui` keeps a trading desk in the host this way, which two embedded order tickets and the host's
  own widgets share.

## Differences

What draws or behaves differently from the native desktop backends:

- **Transforms**: rotated, skewed and projected views turn their backgrounds, borders and shadows, but text stays
  upright, and images, videos and canvases draw at their bounds.
- **Opacity** applies to each color rather than to a group, so overlapping children of a translucent view show
  through each other; an image's opacity (a fade-in, a translucent view) changes in sixteenths.
- **Rounded clips** (`overflow: "hidden"` with a radius) round the backgrounds and images of the children, but text,
  borders, videos and native components are cut by the rectangle.
- **Not drawn**: `filter: blur()`, `backdropFilter` and `mixBlendMode`; shadows show through translucent fills;
  `borderCurve: "continuous"` draws circular corners.
- **Canvas text** is approximated: upright under rotations, made smaller rather than narrower for `maxWidth`,
  gradients paint it in one color, `strokeText` fills, its shadows are not blurred, and composite operations and
  `clearRect` do not apply to it.
- **Scroll views** do not zoom (`zoomTo` and the zoom props are ignored).
- **Video** plays on Linux (GStreamer); on macOS and Windows a video shows a placeholder and reports `onError`.
- **Web views** are native views above everything NSH draws at their place. On Linux they need X11 (see
  [Requirements](#requirements)); where pages stay black under Xwayland ("Failed to create GBM buffer" in the log),
  run the app with `WEBKIT_DISABLE_DMABUF_RENDERER=1`. On macOS and Windows clipping ancestors do not cut them and
  failed loads report no `onError`. `baseUrl`, `scrollable` and `allowsBackForwardNavigationGestures` are
  not supported.
- **Accessibility** goes through AccessKit: screen readers can activate, focus, set values and scroll elements into
  view everywhere; custom actions and the context-menu action are not passed on yet.

For comparison, each native backend's own list: [macOS](https://nsh.dev/versions/main/docs/macos.md#what-differs-on-macos),
[Windows](https://nsh.dev/versions/main/docs/windows.md#what-differs-on-windows), [Linux](https://nsh.dev/versions/main/docs/linux.md#what-differs-on-linux).

## See also

- [Building with Rust](https://nsh.dev/versions/main/docs/rust.md): the crate whose root a GPUI app embeds
- [CLI](https://nsh.dev/versions/main/docs/cli.md): `nsh run --target gpui`
- [Packaging](https://nsh.dev/versions/main/docs/packaging.md): standalone apps, with each OS's own target
- [Platform overview](https://nsh.dev/versions/main/docs/platforms.md)

Source: https://nsh.dev/versions/main/docs/gpui

---

# Terminal

NSH apps also run in a terminal. The terminal backend draws an app on the terminal's grid of character Cells with
[ratatui](https://ratatui.rs), in the terminal's own font and colors, and takes its input from the keyboard and the
mouse. The core, the reactive graph, the renderer, the components and the native modules are the same as on every
other platform, so the app that runs in a window runs in a terminal too: the gallery's demos are the same code here
as on a phone.

The terminal is a device form of its own, as a phone and a desktop are: `idiom()` is `Idiom::Terminal`
(`nsh_core::platform::Idiom`; `platform.idiom` is `"terminal"` in TSX), and `os()` (`platform.os`) is the machine's own system, macOS, Windows or
Linux, so `fs/promises` and `process` work as on that desktop. Desktop behavior applies: `desktop={{…}}` props,
`platform.select`'s `desktop` key, `platform.desktop`, keyboard shortcuts, hover, tooltips and context menus. The
application menu (`Menu.setApplicationMenu`) is a menu bar on the top row, as in mc and htop: F10 or a click on a title
opens its menu, and its items' shortcuts work with the bar closed.

## Running an app

```sh
nsh run App.tsx --target tui        # a TSX app
nsh run --target tui                # a Rust app, from its directory
```

The app fills the terminal it was started in, with hot updates on save; a Rust app's root runs in a terminal
development host built with its crate, rebuilt and restarted when its Rust code changes. In a checkout, `nsh run`
builds the development host (`nsh-tui-host`) first.

The terminal shows the app alone. Diagnostics (the CLI's output, the host's logs, `console.log`) go to the app's
`.nsh/tui.log`, and `C-h e` (Ctrl+H, then E) opens them in a panel over the app: the arrows and Page Up / Page Down
scroll it, `r` reloads the latest build, and Escape, `C-g` or `q` closes it. An error in the app opens the panel by
itself, and the next update closes it. Ctrl+C copies a text selection, and otherwise quits; the terminal is restored
as it was.

`--fps` shows a performance line in the top right corner (frame rate, frame times, the bytes and Cells each frame
writes); `C-h p` shows and hides it.

```sh
nsh run App.tsx --target tui --fps
nsh run App.tsx --target tui --points-per-cell 10x20
```

## Cells

The core lays the app out in points, as everywhere, and the terminal maps points to Cells: one Cell is **8 × 16
points** by default. Set another size in `nsh.json`, or for one run with `--points-per-cell`, which wins:

```json
{ "tui": { "pointsPerCell": "10x20" } }
```

In a terminal the core lays out with an algorithm made for the grid, the way terminal apps lay themselves out: every
frame is whole Cells, and spacing designed in points for a screen becomes the Cells a terminal can give it.

- **Spacing.** A gap in a row is one column, two from 24 points. In a column, gaps and margins of 16 points or more
  are one blank row. Horizontal padding is one Cell from 8 points and two from 24 points; vertical padding is a row
  from 24 points.
- **Borders.** A card (a container padded 12 points or more, or around two or more rows of content) keeps its border,
  one Cell on each side that has one, drawn in box-drawing lines: `─` and `│`, rounded corners `╭╮╰╯` where a radius
  is set, square ones `┌┐└┘` otherwise, dashed `╌╎` and dotted `┈┊`. A control (a button, a tab, a text field) is its
  label row.
- **Flex and grid.** `flexDirection`, `flexGrow`, `justifyContent`, `alignItems`, `flexWrap`, grid templates and spans
  divide whole Cells. When a row is short of room, gaps give first, then the texts wrap.
- **Text** is one row per line in the terminal's font at any font size, weight 600 and above bold, with italic,
  underline and strike-through kept. Wide characters (CJK, emoji) take two Cells and grapheme clusters stay whole.
  `numberOfLines` and ellipses work as elsewhere, the ellipsis taking one Cell.
- **Layouts** report points: frames, `onLayout`, hit testing, overlays and scroll offsets work as on other
  platforms.

## Keyboard

Every control is reachable from the keyboard. Tab and Shift+Tab visit pressable and editable views in document order,
as on the desktops; the arrows move to the nearest control in that direction, scrolling to reach it. A control
scrolled into view by the keyboard is centered in its scroll view. While a dialog or a sheet is open over its
backdrop, Tab stays in it, and closing it gives the focus back to the control it came from. Tab always moves to the
next control: in a `DataTable` it leaves the table, and the arrows move between its columns. A click gives the focus
to the control it is on, or the one around it, and Tab goes on from there.

| Keys | Do |
|---|---|
| Tab, Ctrl+N / Shift+Tab, Ctrl+P | The next / previous control, wrapping at the ends |
| Down / Up | The nearest control below / above, scrolling to reach it |
| Right, Ctrl+F / Left, Ctrl+B | The nearest control to the right / left on the same row |
| Enter, Space | Press the focused control |
| Escape, Ctrl+G | Leave the focused field; otherwise go back: the app's `onBackPress`, then the newest dialog or the navigation stack |
| Page Down, Ctrl+V / Page Up, Alt+V | Scroll the scroll view around the focused control by a page |
| Home, Alt+< / End, Alt+> | The first / last control of that scroll view |
| Ctrl+S / Ctrl+R | Search the text on screen forward / backward |
| Ctrl+C | Copy the selection (so do Ctrl+Shift+C, Cmd+C, Ctrl+Insert and Alt+W); with none, quit |
| Ctrl+A, Cmd+A | With text selected, select all the text of its selectable view |
| F10 | The application menu's bar: Left / Right between the titles, Down, Enter or a title's initial opens its menu, Escape closes it, then leaves the bar |

The app's own shortcuts ([`keymap`](https://nsh.dev/versions/main/modules/nsh.md#keymap)) come first, and so do the keys a focused component
binds (a slider's arrows, a list's), so a component gets its keys before they move the focus. Terminals that speak
the kitty keyboard protocol report Ctrl+I, Ctrl+M and Ctrl+[ apart from Tab, Enter and Escape, key repeats and
releases, and Super as Cmd, so `cmd+` shortcuts work there; on macOS terminals without it, a Ctrl shortcut that no
binding takes is tried again as Cmd, and menus and hints (`keymap.label`, `Command`) show those shortcuts with
Ctrl, the key to press there (`⌃O` for `mod+o`).

**Search.** Ctrl+S and Ctrl+R search the text on screen as you type, as readline and Emacs do. The query shows on the
bottom row after `/` (forward) or `?` (backward), the match is highlighted and focus moves to the control it belongs
to. Ctrl+S / Ctrl+R go to the next / previous match, Backspace or Ctrl+H takes back the last key, Enter ends the
search there, and Escape or Ctrl+G puts focus and scrolling back as they were.

**Text fields** take readline's keys as well as the desktop's:

| Keys in a field | Do |
|---|---|
| Ctrl+A / Ctrl+E, Home / End | Start / end of the line |
| Ctrl+Home / Ctrl+End, Alt+< / Alt+> | Start / end of the text |
| Ctrl+F / Ctrl+B, Alt+F / Alt+B | A character, a word forward / back |
| Ctrl+Right / Ctrl+Left, Alt+Right / Alt+Left | A word forward / back, as on the desktops |
| Ctrl+N / Ctrl+P, Down / Up | The next / previous line of a multiline field |
| Ctrl+K / Ctrl+U, Ctrl+W, Alt+Backspace, Alt+D | Kill to the end / start of the line, a word back, a word forward |
| Ctrl+Y | Insert the last killed text |
| Ctrl+T | Swap the characters beside the caret |
| Ctrl+D, Delete / Ctrl+H, Backspace | Delete forward / back |
| Ctrl+Delete / Ctrl+Backspace | Delete a word forward / back |
| Shift with the movement keys | Extend the selection |
| Ctrl+Shift+A, Cmd+A | Select all |
| Ctrl+Z / Ctrl+Shift+Z, Cmd+Z / Cmd+Shift+Z | Undo / redo |
| Ctrl+Shift+C, Cmd+C, Ctrl+Insert, Alt+W | Copy |
| Ctrl+Shift+X, Cmd+X, Shift+Delete | Cut |
| Ctrl+V, Ctrl+Shift+V, Cmd+V, Shift+Insert | Paste |
| Enter | What `submitBehavior` says: submit, submit and leave, or a new line |
| Shift+Enter, Alt+Enter | A new line in a multiline field that submits on Enter |
| Escape, Ctrl+G | Leave the field |

While a field is edited, the terminal's cursor is a bar at the caret. Input methods compose in the terminal
emulator, and the committed text enters the field; a paste is one insertion. Copied text goes to the system clipboard
through the terminal (OSC 52, over SSH too, where the terminal allows it).

## Mouse

The terminal reports the mouse at Cell precision, and NSH turns each Cell into the point at its middle.

- **Clicks** press what is under the pointer; double and triple clicks select a word and a line in fields and
  selectable text, and a drag after them extends by words or lines. A right click opens the context menu
  (`onContextMenu`) of the nearest view that listens for one.
- **The wheel** scrolls the scroll view under the pointer by three rows (six columns sideways; Shift turns a vertical
  wheel sideways), and leaves the keyboard focus where it is.
- **Hover** tracks the pointer Cell by Cell: the view under it and its ancestors take `hover:` styles and
  `onMouseEnter` / `onMouseMove` / `onMouseLeave`, a hovered control stands on a lighter band, and tooltips and hover
  cards open on the views under it. Leaving the terminal, or the terminal losing focus, clears hover.
- **Dragging** follows the pointer Cell by Cell:
  - a `Slider` (and a `ColorSlider` or `ColorArea`): a press on the track moves the nearest thumb there, and a drag
    moves it with the pointer; a range slider's thumbs stay within each other;
  - a scroll bar: a press on the track jumps the thumb there, and a held thumb follows the pointer;
  - the handle lines of a `ResizablePanelGroup` or `DockArea` resize their panes, and a `DockArea` tab dragged over a
    group outlines where it lands;
  - text in selectable views and fields is selected; Shift+click extends the selection, and Ctrl+C, Ctrl+Shift+C or
    Cmd+C copies it; a selection held past the edge of its scroll view (or on the terminal's own edge row) scrolls it
    row by row, faster the farther past the pointer is;
  - content that nothing else claims scrolls with the drag, and the app's gestures (`panActivation`, the responder
    system) get every move; a drag keeps its target while the pointer is outside the app.

  A drag never presses what it started on.

## Colors and themes

The app is drawn in the terminal's own theme. When it starts, the host asks the terminal for its default foreground
and background, and the app's light or dark mode follows the background (dark when the terminal does not say). The
color depth comes from the environment: `COLORTERM=truecolor` (or a terminal known for 24-bit color) is true color, a
`TERM` with `256color` is 256 colors, and anything else is the 16 standard colors. `NO_COLOR` draws without colors:
states are shown with reverse video, underlines, bold and strike-through. `NSH_TUI_COLORS=truecolor`, `256`, `16`
or `mono` sets it.

The app's colors are read as meanings, so an app designed for screens reads well on any terminal theme:

- a saturated color (a primary button, an error, a link) is the terminal's accent of its hue: red, yellow, green,
  cyan, blue or magenta;
- a neutral color is the terminal's foreground, and a low-contrast one (secondary text, placeholders, separators) a
  fade of it;
- canvases, color swatches and syntax highlighting keep their own colors, at the terminal's color depth.

With 256 colors or more and a known background, fills are **surfaces**: steps of the terminal's own background mixed
toward its foreground, so a card, a sidebar or a selected row stands on a band a shade lighter or darker than what is
around it, and the page itself is the terminal's background, transparency included. On a 16-color terminal the same
app, laid out the same, is drawn in lines, bold, dim and reverse video, and its small fills in the standard colors:
a chip or a tag on the dark gray, a primary button in its color; panels and cards are set apart by their space.

The terminal shows state in its own way: a selected row and a focused control are a highlighted band and bold, a
hovered control a lighter band, a disabled one faint; the selected row of the pane that has the focus is in the
accent. The app's focus styles still apply on top.

## Components and popups

`nsh/base`'s controls take the terminal's own forms, one row each, with the app's labels, values and events:

| Component | In the terminal |
|---|---|
| `Checkbox` | `[✓]`, `[ ]` or `[–]`, then its label |
| `Radio` | `(●)` or `( )`, then its label |
| `Switch` | `[✓]` on, `[ ]` off, as a checkbox |
| `Slider` | a row of `─`, filled with `━` up to the value, a `●` per thumb |
| `Progress` | a heavy line `━` in the indicator's color, then a light `─` in the line color |
| `Select`, `Combobox`, `DatePicker` | the value (a `Select`'s `placeholder` while none is chosen, or the app's `trigger`) with `▾` near the right end of its band, a blank Cell after it as before the text, and `×` before it while there is a value to clear, muted, in the accent while focused or open; the list opens under it. An app's own `trigger` leaves the band's last three Cells free for them (six with `×`) |
| `Tabs` | the tabs in a row, the selected one bold |
| `Calendar`, `DatePicker` | `cal`'s month: the days' numbers right-aligned in columns, today bold, the selected days banded; the months and the years to pick centered in the month's width |
| `OtpInput` | the cells in a row, the terminal's cursor in the middle of the cell that takes the next digit; an empty cell shows `·`, muted, a masked digit `●`; a cell with a border and no fill is a framed box (`┌───┐`), its digit in the middle, the next cell's line in the accent |
| `Pagination` | Previous, the pages, `…` and Next as words in a row, the current page banded |
| `MenuItem`, `Submenu` | the title from the row's start; `✓` at the row's end on a checked item (`●` on a radio item), ` ›` on a submenu's trigger |
| `Select`, `Combobox` lists | each title from the row's start, `✓` at the end of the chosen row |
| `Accordion`, `Collapsible`, `Tree` | `▸` closed, `▾` open |
| `Scrollbar` | the terminal's own scroll bar |
| `TextView` | a terminal reader's document: blocks a blank row apart, headings without `#` in bold (h1 ruled), quotes behind `▎`, code in a band under its language, alerts as one tinted band with their icon, tables in box lines fitted to the view, tasks `☐` / `☑` |

**Popups** (popovers, menus, a select's list, a command palette) open beside their anchor, framed by a
rounded line, with the label of their first surface as a title in the top border (`╭─ Title ─`). With surfaces they
stand raised on a band and cast a one-Cell shadow; the item under the keyboard or the pointer is a full-row band in
the accent. **Dialogs** center a framed box and fade what is behind them; focus stays inside the newest one, Escape
asks it to close, and closing it gives the focus back to the control that opened it. `AlertDialog` is drawn
the same way, its buttons `Cancel  OK` in a row (`< Cancel >  < OK >` on 16 colors).

**Toasts** show on the status line, the screen's bottom row, one at a time: the newest toast's content in a row, and a
new toast takes the line from the last. Nothing stacks or animates; Escape closes the toast there, as its own buttons
and its timeout do. A tooltip shares the line and shows there while no toast does.

**Scroll views** that overflow show a one-Cell scroll bar, `│` with a `┃` thumb, on their inner edge, or on the line of
the pane they fill. **Canvases** draw in braille dots, two across and four down per Cell, with text on whole Cells;
chart demos and drawings keep their shapes. An **icon button** (a button whose content is an icon) shows its
accessibility label as its text, and a popup's trigger shows `▾`.

**Marks you press** (a trigger's `▾`, a clear `×`, a stepper's `−` / `+`) each take a slot of three Cells with the
mark in the middle, ` ▾ `, and a press anywhere in the slot counts. Slots sit side by side (` ×  ▾ `), so the mark at a
band's end has a blank Cell after it. The mark is muted and turns the accent while its control is focused or open,
while it is pressed and while the pointer is over its slot. For a mark of your own, make a pressable `View`
three Cells wide and one Cell high (24 × 16 points at the default size) with the glyph centered. With `controlsRight`,
`NumberInput` sets its steppers side by side in a terminal, the decrement first (` −  + `).

**Media elements keep their space in the layout.** An `Image`, `Video`, `WebView` or shader view larger than an icon
keeps its box, so the text and controls around it stay where the design puts them; the terminal shows text and
lines, so the box is blank Cells. Images, videos, web views, shaders and canvases of icon size (48 × 48 points or
smaller) give their room to the content around them. With surfaces, a view in the image role whose background is a color (a color
swatch) shows that color.

## Laying out for the terminal

Most apps need no change: desktop behavior applies, and the layout rules above fit a desktop design to the grid.
Where the terminal should get a layout of its own, the idiom says so:

```rust
use nsh_core::{platform::Idiom, prelude::*};

#[component]
pub fn Shell() -> impl IntoElement {
    // The terminal gets one compact column; windows get a sidebar.
    view()
        .flex_1()
        .child(if idiom() == Idiom::Terminal { compact_layout() } else { sidebar_layout() })
}

fn compact_layout() -> AnyElement {
    view().flex_1().flex_col().into_element()
}

fn sidebar_layout() -> AnyElement {
    view().flex_1().flex_row().into_element()
}
```

```tsx
import { View, platform } from "nsh";

export function Shell() {
  // The terminal gets one compact column; windows get a sidebar.
  return (
    <View class="flex-1">
      {platform.idiom === "terminal" ? <CompactLayout /> : <SidebarLayout />}
    </View>
  );
}

function CompactLayout() {
  return <View class="flex-1 flex-col" />;
}

function SidebarLayout() {
  return <View class="flex-1 flex-row" />;
}
```

`platform.desktop` is `true` in a terminal, and `platform.idiom === "desktop"` matches windows and desktop browsers,
so code that asks for a pointer and a wide window with the idiom keeps the terminal on its own branch. Window chrome
an app draws itself for `nsh/desktop` (a title bar of its own) is the app's content in a terminal; leave it out for
`platform.idiom === "terminal"`. The environment reports reduced motion: navigation and layout transitions take their
final state at once, and the app's own animations run as written. The safe area and the keyboard height are 0.

## Testing

```sh
nsh test --target tui
```

runs the app's tests through the terminal development host, on an in-memory terminal, so it needs no terminal of its
own and runs in CI. The steps press, type and scroll with the terminal's input; `open(entry, { width, height })` sets
the viewport in points (390 × 844 by default), rounded up to whole Cells. `app.screenshot("cells.json")` returns the
screen as UTF-8 JSON, one entry per Cell with its symbol, colors and modifiers, so a test can compare renders exactly
([Testing](https://nsh.dev/versions/main/docs/testing-and-trace.md#on-a-real-platform)).

## Running a bundle

The development host also runs a built bundle on its own, or connects to a development server you start yourself:

```sh
nsh build my-app --out build
nsh-tui-host --bundle build/bundle.js                       # in a checkout: target/debug/nsh-tui-host
nsh-tui-host --dev-server ws://127.0.0.1:8790/ws
```

| Option | Does |
|---|---|
| `--points-per-cell <WIDTHxHEIGHT>` | The size of one Cell in points (`8x16` by default) |
| `--no-mouse` | Leaves the mouse to the terminal emulator and its own text selection; the keyboard works as above |
| `--fps` | Shows the performance line (`C-h p` toggles it) |
| `--log-file <PATH>` | Where diagnostics go (by default a file in the system's temporary directory, shown by `C-h e`) |
| `--data-dir <PATH>` | Where the app keeps its data |
| `--trace` | Adds the engine's timings to the log |

The bundle's assets are read from the `assets/` directory next to it.

## Embedding in a terminal app

The `nsh-platform-tui` crate gives a Rust [ratatui](https://ratatui.rs) app `AppView`: one NSH engine drawn into any
area of the app's own frame. The app keeps its terminal, its event loop and its layout; each `AppView` is
independent, and several can share a screen.

```rust
use nsh_platform_tui::{AppOptions, AppView, Input, Root};

let mut options = AppOptions::default();
options.ui_sets = vec![nsh_base::registry(), my_app::registry()];
let mut view = AppView::new(options);
view.load(Root::of::<my_app::App>())?;

// In the app's draw: the view takes the area it is given.
terminal.draw(|frame| view.render(frame, frame.area()))?;

// In the app's event loop: keys, pastes and mouse events, at absolute Cells.
view.handle(input);

// Draw again when the view asks: `next_frame_deadline()` is when its next frame is due.
let due = view.next_frame_deadline();
```

`load` also takes a `Bundle` (`Bundle::read(path)`, a TSX app that `nsh build` wrote). `AppView::set_wake_callback`
tells the app's loop that the view has a frame to draw, from the engine's thread; `set_focused` gives or takes the
keyboard focus; `set_appearance` sets light or dark mode; `register_component` adds the app's own native components,
drawn into their Cells. `AppOptions` sets the Cell size (`cells`), the terminal's colors and depth (`capabilities`),
the limits, storage, assets and clipboard. With feature `run-app`, `run_app(&mut terminal, &mut view, poll)` is a
ready loop for an app that gives the whole terminal to one view, as the development host does.

## See also

- [CLI](https://nsh.dev/versions/main/docs/cli.md): `nsh run --target tui`, `nsh test --target tui`
- [Platform-specific code](https://nsh.dev/versions/main/docs/platform-specific.md)
- [Device and environment](https://nsh.dev/versions/main/docs/device-and-environment.md)

Source: https://nsh.dev/versions/main/docs/tui

---

# Web

Build web apps with Native Shell using the same components, styles and application logic as on native platforms. NSH renders the interface as HTML elements and CSS: text, images, inputs, scrolling, visual styles and interactions use the browser's DOM and web APIs.

`nsh package --target web` publishes the app as a static site for any web server or CDN ([Publish an app](#publish-an-app)), and `nsh run --target web` runs it in the browser while you edit it ([Develop in the browser](#develop-in-the-browser)). Every live demo on this site uses this web backend.

Published TSX apps use the browser JavaScript engine. Packaging links each app its own runtime, holding only the `nsh/base` components and standard modules the app imports: an app built from the core components downloads about 1.1 MB. Syntax highlighting data loads when code is first highlighted.

## What runs where

The page is built from HTML elements styled with CSS. NSH turns component updates into batches of DOM changes, while the browser displays the interface and handles scrolling, text selection and input. WebAssembly hosts the shared Rust engine for component state, layout and updates: with a Rust app's crate compiled in, or alongside the browser's JavaScript engine, which runs a TSX app's code as ES modules: published apps, the dev server's page, this site's demos and the playground alike.

On every native platform the engine has its own thread and hands one `MountBatch` per commit to the main thread. A browser page has one thread, so the web build drives the same engine step by step from the page's event loop (`nsh_engine::LocalEngine`):

```text
pointer / keyboard / scroll events ─┐
setTimeout (the engine's deadline) ─┼─▶ nsh.wasm: engine turn (Rust or JS, core, layout) ─▶ one JSON batch ─▶ nsh.js: DOM
requestAnimationFrame ──────────────┘                                                 ▲
                                                          native animation outputs ───┘
```

- **Layout is the core's.** Every view is an absolutely positioned element at the frame Taffy computed, so flexbox, grid, `aspectRatio` and percentages behave exactly as on devices. The browser's own layout is not involved.
- **Styles are turned into CSS in Rust.** Background, borders, radii, shadows (`boxShadow`, `textShadow`), gradients, filters, `backdropFilter`, transforms, `transformOrigin`, `outline`, `mixBlendMode`, transitions and the built-in keyframe animations become CSS properties. Tailwind classes, `active:`, `hover:` and `focus:` states and `dark:` all resolve natively, as they do on devices.
- **Text is laid out in Rust** with font measurements from the browser (`CanvasRenderingContext2D.measureText`) and drawn run by run at the positions the layout chose, so what was measured is what is drawn. Lines break after spaces, around CJK characters and at `\n`; `numberOfLines` truncates with an ellipsis.
- **Native animations run in Rust** on `requestAnimationFrame`: `Animated` timing, spring and decay, `interpolate`, animated values bound to `opacity`, `translate`, `rotate`, `scale`, the steps of `transform` and `backgroundColor`, drags bound with `pan`, scroll-linked values and canvas arguments. JS is not involved per frame, as on devices. `LayoutAnimation`, style transitions, the `animate-*` keyframes and screen transitions move as on the desktop backends, and `prefers-reduced-motion` turns them off (screens fade).
- **Input:** presses with `activeStyle` / `active:` feedback and long presses, the responder system (`onTouch*`, `PanResponder`), native drags and two-finger pinch and rotation, scroll views (the browser's scrolling), pull to refresh, zooming scroll views (pinch, ctrl+wheel and touchpad pinches, `zoomTo`), `<Input>` with controlled values, focus and submit, `Canvas`, `NavStack` and `NavPage` with the page's `header`, `Dialog`.
- **System UI is drawn in the page:** `AlertDialog` looks like the desktop backends' dialogs on desktop browsers and like iOS's on phones (with the `desktop` idiom, see below). Custom fonts are measured again once the browser has loaded them, and an app waits for the fonts it imports before its first frame shows.
- **Dialogs** are a layer over the whole app that shows the app's popup and backdrop, as on the desktop backends. Escape, the browser's back button and a press on the backdrop close them (`closeOnEscape`, `closeOnBackdropPress`), and `animation`, `onOpen`, `onClose`, `onCancel` and `onOpenChange` work as on devices. A page that [embeds the app](#embed-it-in-a-page) in part of its layout can show dialogs and alerts over the whole browser window instead (`dialogs: "viewport"`), as iOS and Android show them over the whole screen.

## Keyboard, mouse and touch

Published apps behave as desktop apps in desktop browsers and as phone apps in phone browsers:

- **Wheels and touchpads** scroll the innermost scroll view along their axis that can still move (a vertical wheel scrolls a horizontal list when nothing vertical can), and stay on it until the scroll ends; wheel notches glide, paging and snapping views move one page per scroll. Ctrl + wheel and touchpad pinches pinch views with native pinch values instead of zooming the page. Dragging with the mouse does not scroll, as on the desktop platforms: mouse drags go to pans, the responder system and text selection. Scroll views report `onScrollDragStart` / `onScrollDragEnd`, `onMomentumStart` / `End` and `onScrollEnd` as on the desktop platforms.
- **Keyboard**: Tab and Shift+Tab move between pressables and inputs (the app's `focus:` styles show the keyboard focus); Return presses the focused pressable, Space presses it when released; arrows, Page Up / Page Down, Space, Home and End scroll the scroll view around the focus or under the mouse; Escape leaves a field, closes the dialog, then goes back. `keymap` shortcuts work in the browser, matched on the spot (`mod` is Command in Safari and Chrome on a Mac, Control elsewhere).
- **Going back**: Escape, Alt+Left (Cmd+[ on a Mac) and the mouse's back button close the newest dialog or pop the innermost stack, as the Android back button does; `popOnBack` and `onBackPress` work as there. When the app is the whole page, every pushed page and open dialog is a browser history entry, so the browser's back button goes back in the app.
- **Touch**: only scroll views pan; the page itself never scrolls, zooms or pulls to refresh under the app, and taps have no delay. In an iframe, swipes the app does not take scroll the embedding page. Drags on views with native pans, pinches and the responder system are the app's.
- **Accessibility**: `role`, `accessibilityLabel`, `accessibilityHint`, `accessibilityState`, `accessibilityValue`, `accessibilityLiveRegion` and `accessibilityElementsHidden` become ARIA; `announce` speaks through a live region and `setAccessibilityFocus` moves the focus. Views under a dialog or alert are inert.
- **Selection and menus**: in desktop browsers text is selectable by default, as on a web page, except inside interactive elements (views with press or touch handlers: buttons, pressable rows, tabs) and text with `userSelect: "none"` or `select-none`; dragging the mouse over it selects it, Ctrl/Cmd+C copies it line by line and Ctrl/Cmd+A selects all of the text the selection is in. In phone and tablet browsers only text with `userSelect: "text"` is selectable, as in native apps. The browser's context menu appears only in selectable text and inputs.


## Apps with Rust components

An app written in Rust ([Building with Rust](https://nsh.dev/versions/main/docs/rust.md)) publishes and runs in the browser from its directory:

```sh
nsh package --target web           # .nsh/out/<Name>/: the app's own nsh.wasm, with its crate
nsh run --target web               # the dev server's page; editing the Rust code builds it again
```

When `nsh.json` names the app's root component (`"root"`), the page is the app's Rust and NSH's page script, and
nothing else: `nsh.wasm` holds the engine, the components and the app's crate, the site has no
`app.js`, and the page mounts the root as soon as the runtime and the fonts are in. The whole Rust
gallery is 3.3 MB (1.06 MB gzipped, 0.75 MB with brotli), less than the runtime of TSX apps. Under its TSX entry
(`nsh package App.tsx --target web`), the same app runs as TSX apps do, on the browser's JavaScript engine, and imports the crate's
components and modules.

Either way the crate's assets (`assets!()`) are published with the app's, and its fonts load before the first frame.
During `nsh run --target web`, a change to the crate's Rust code builds the runtime again and the open page loads it by
itself; TSX edits stay hot updates. The development runtime builds incrementally, so a change to the crate is ready in
about a second; `nsh package` builds the published one optimized for size.

Rust code that runs on every platform, the web included, uses the engine's services: `fetch(url).await` makes
HTTP requests through the same network stack as JS's `fetch` (the browser's here, with its CORS rules); `timer`,
`set_timeout` and `set_interval` wait; and `nsh_core::time::Instant` and `nsh_core::time::unix_ms()` read the clock.
`background` and `blocking` run work on the native targets' threads.

The build needs the Rust target and a clang that compiles to WebAssembly, as the runtime's own build does:
`rustup target add wasm32-unknown-unknown`, plus `clang` and `llvm-ar` (on macOS, an LLVM toolchain such as
Homebrew's `llvm`, through `CC_wasm32_unknown_unknown` and `AR_wasm32_unknown_unknown`).

### Browser APIs from Rust

A crate can call the browser's own APIs through [wasm-bindgen](https://wasm-bindgen.github.io/wasm-bindgen/) and
its `web-sys` and `js-sys` crates, behind `#[cfg(target_arch = "wasm32")]`: a WebSocket, `IndexedDB`, the
clipboard, any Web API, and JS of the crate's own (`#[wasm_bindgen(inline_js = …)]`, `module = "/js/…"`). When the
app's web runtime calls JS this way (including `JsValue` conversions), `nsh` runs the `wasm-bindgen` CLI on it and
ships its glue and the crate's JS next to the runtime, in development and in published sites alike. The CLI's version is the one of the `wasm-bindgen`
crate the runtime links, which `nsh` names: `cargo install wasm-bindgen-cli --version <version> --locked` installs it
(`NSH_WASM_BINDGEN` names a CLI elsewhere than on `PATH`). A runtime that links wasm-bindgen and calls no JS through
it (through a dependency's default features) builds as every other runtime does.

The crate names the APIs it uses as `web-sys` features, and pinning `wasm-bindgen` keeps its version, and so the
CLI's, the same from build to build:

```toml
[target.'cfg(target_arch = "wasm32")'.dependencies]
wasm-bindgen = "=0.2.129"
web-sys = { version = "0.3", features = ["WebSocket", "MessageEvent"] }
futures-channel = "0.3"
```

The browser's callbacks (a message arriving, a timer of the page's) wake the app's tasks, which run at once:

```rust
#[cfg(target_arch = "wasm32")]
async fn echo(url: &str, text: String) -> Result<String, String> {
    use wasm_bindgen::{JsCast, prelude::*};
    let ws = web_sys::WebSocket::new(url).map_err(|e| format!("{e:?}"))?;
    let (tx, rx) = futures_channel::oneshot::channel();
    let tx = std::cell::RefCell::new(Some(tx));
    let on_message = Closure::<dyn FnMut(web_sys::MessageEvent)>::new(move |e: web_sys::MessageEvent| {
        if let (Some(tx), Some(data)) = (tx.borrow_mut().take(), e.data().as_string()) {
            let _ = tx.send(data);
        }
    });
    ws.set_onmessage(Some(on_message.as_ref().unchecked_ref()));
    on_message.forget();
    let open = ws.clone();
    let on_open = Closure::<dyn FnMut()>::new(move || {
        let _ = open.send_with_str(&text);
    });
    ws.set_onopen(Some(on_open.as_ref().unchecked_ref()));
    on_open.forget();
    rx.await.map_err(|_| "closed".to_owned())
}
```

A crate's calls of browser APIs run with the page's own permissions, as a crate's native code runs with the app's
on the other platforms: the capabilities of `nsh.json` govern what goes through the engine (`fetch`, the app's JS),
and the browser's rules (CORS, the page's Content-Security-Policy) govern every request the page makes.

## Publish an app

```sh
# A Rust app, from its directory
nsh package --target web                   # .nsh/out/<Name>/: a static site
nsh package --target web --run             # and serve it on this machine (open the address it prints)

# A TSX app
nsh package App.tsx --target web
nsh package App.tsx --target web --run
```

`nsh package --target web` writes `.nsh/out/<Name>/` (`--out` for another directory), laid out like a frontend build: one
page and files named after their content.

| File | What it is |
|---|---|
| `index.html` | The app's page: its name as the title, the icons, the colors of its `appearance`, a loading indicator, and a message when the app cannot load or start |
| `manifest.webmanifest` | The name, id, icons and colors browsers install the app with |
| `nsh.<digest>.js` | The DOM runtime, minified (79 KB, 22.5 KB with brotli) |
| `nsh.<digest>.wasm` | The Rust engine, layout and components, plus a Rust app’s own crate. TSX runs in browser JavaScript; packaging links it with only the components and standard modules the app's first screen imports. |
| `nsh-<name>.<digest>.wasm` | Components, standard modules and shaders the app uses beyond its first screen: downloaded in the background after it shows |
| `<file>.br`, `<file>.gz` | Each file compressed ahead of time, for hosts that send precompressed files |
| `nsh-syntaxes.<digest>.bin` | The syntaxes code is highlighted with (bat's set: 0.92 MB, 0.8 MB with brotli), downloaded the first time a code block, an `Editor` or a `DiffView` shows code in a language |
| `nsh-bindgen.<digest>.js` | The wasm-bindgen glue of an app whose crates call [browser APIs from Rust](#browser-apis-from-rust), minified |
| `snippets.<digest>/<crate>-<hash>/…` | The JS of those crates that the glue imports (`inline_js`, `module = "/js/…"`), under the paths wasm-bindgen gives it |
| `app.<digest>.js` | The compiled TSX entry as an ES module, loaded by the browser. |
| `host.<digest>.js` | The page's host, `nsh.json` `web.host` ([the host's functions](#the-hosts-functions)) |
| `<name>.<digest>.js` | ES modules loaded on demand by `import()`. |
| `assets/<path>.<digest>.<ext>` | Every asset the app imports, loaded from its URL when it is used (fonts before the code that registers them runs, as text is measured with them: before the app starts, or with the chunk that imports them) |
| `icons/<size>.<digest>.png` | The icon of `nsh.json` at 32 (favicon), 180 (`apple-touch-icon`), 192 and 512 pixels |

`<digest>` is the start of the SHA-256 of the file's content: a file's name changes exactly when its content does, so a
new release changes only `index.html` and the files that really changed. Everything uses relative URLs, so the site
works from any directory of any host (`https://example.com/apps/counter/`).

### Runtime size

Packaging links each app its own `nsh.<digest>.wasm`, holding the engine and the `nsh/base` components, standard
modules and shaders the app's first screen imports. What the app's other screens import is downloaded in the
background once the first screen shows. An app whose crates call [browser APIs from Rust](#browser-apis-from-rust)
gets the whole runtime, its crates included, in its `nsh.<digest>.wasm`. Measured with `nsh package --target web`
(MB = 10^6 bytes):

| App | Uses | `nsh.<digest>.wasm` | gzip | Brotli |
|---|---|---|---|---|
| `examples/counter` | The core components | 3.96 MB | 1.32 MB | 0.97 MB |
| `examples/gallery` | Every component, `zlib` and shaders | 4.13 MB | 1.36 MB | 1.01 MB |

### Deploy it

Upload the directory to any static host: an object store behind a CDN, Cloudflare Pages, Netlify, GitHub Pages,
nginx. Two rules make it load fast and update reliably:

| Files | `Cache-Control` |
|---|---|
| `index.html`, `manifest.webmanifest` | `no-cache` (revalidated on every load, so a release shows at once) |
| everything else | `public, max-age=31536000, immutable` |

Serve `.wasm` as `application/wasm` (browsers then compile it while it downloads), and send the precompressed
copies to browsers that accept them: nginx's `brotli_static on; gzip_static on;`, Caddy's `file_server {
precompressed br gzip }`, or a CDN that compresses with Brotli. With Brotli the runtime is about a quarter smaller
than with gzip. `nsh package --target web --run` serves the site this way on `http://127.0.0.1:4173/`.

An app published for the web runs like a packaged native app: as a release, with the capabilities its `nsh.json` declares
([Sandbox and capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md)), a TSX app on the browser's JavaScript engine. When they restrict `network`, the page also carries a
Content-Security-Policy `connect-src` with the declared hosts (and the page's own origin), so the browser itself
refuses requests and redirect hops to any other host. An error that keeps it from starting is shown on the page;
later errors go to the browser's console.

### Embed it with an iframe

There is no embedding API on the web: embed the published app with an `<iframe>`. Its size is the app's window:

```html
<iframe src="https://apps.example.com/counter/" title="Counter"
        style="width: 390px; height: 844px; border: 0"></iframe>
```

## Develop in the browser

```sh
nsh run --target web               # a Rust app, from its directory
nsh run App.tsx --target web       # a TSX app
```

starts the dev server and prints its page's address, `http://127.0.0.1:8790/`: open it in any browser. The page is a development host
like the others: it runs each build of the app, shows build errors and runtime errors over the app, and sends the app's
logs to the terminal. A change to a Rust app's crate builds its runtime again and the open page loads it by itself;
TSX edits are applied in place (hot updates). Phones on the same network open the
address `nsh run` prints under it (`on this network: http://192.168.…:8790/`). `nsh dev` serves the same page once the
web runtime is there (in the distribution, always).

## Build the website's player

```sh
cargo xtask web                       # nsh.wasm, nsh.js, the player and website/demos/*.tsx
cargo xtask web --out target/play     # somewhere else
```

The output directory holds:

| File | What it is |
|---|---|
| `gallery/nsh.<digest>.wasm` | The gallery's runtime, linked for it by `nsh package` (it uses every component and `zlib`: about 11.8 MB, 3.6 MB gzipped) |
| `gallery/nsh-syntaxes.<digest>.bin` | The syntaxes the runtime highlights code with, fetched the first time a demo shows code in a language |
| `nsh-playground.wasm` | The same plus NSH's TSX compiler, for the [playground](#the-playground) (about 8 MB, 2.4 MB gzipped) |
| `gallery/nsh.<digest>.js` | The DOM runtime (minified): loads the wasm, applies batches, turns input into events |
| `index.html` | A player page: runs `demos/<name>.js` for `#<name>` |
| `nsh.wasm`, `nsh.js`, `browser/` | The runtime the player loads: the engine, the DOM runtime and the browser host's modules |
| `demos/<name>.js` | Each demo compiled by `nsh build --release`: an ES module |
| `gallery/` | The gallery app published with `nsh package --target web`, shown on the [Gallery](/gallery) page |

Serve the directory with any static server (it needs the `application/wasm` MIME type for streaming compilation) and open `index.html#counter`.

## The playground

The [Playground](/playground) edits and runs an app in the browser: the page compiles the TSX with NSH's own JSX compiler (built into `nsh-playground.wasm`, without rolldown) and runs it on the browser's JavaScript engine on every pause in typing. Every demo on this site has an **Edit in Playground** link, and **Share** puts the code in the link itself, so nothing is stored on a server.

A playground app is one module: it imports NSH's modules (`nsh` and `nsh/*`) but no other files or packages. `console.log` output and errors appear below the phone.

The compiler is also a Rust function, `nsh_bundler::compile_module(name, source, ui_sets)`, available without the crate's `bundle` feature.

## Embed it in a page

A Rust app is embedded as its published site, in an [iframe](#embed-it-with-an-iframe). For TSX, `nsh.js` is an ES
module. `createPlayer` loads the runtime into a container; `runModule(url)` starts a bundle that `nsh build` writes
(`bundle.js`, an ES module) on the browser's JavaScript engine, in a realm of the app's own, replacing what ran. It
returns a promise that resolves once the module has loaded and rejects with the error that stopped it, which the
player also reports (`onError`):

```js
import { createPlayer } from "./nsh.js";

const player = await createPlayer(document.querySelector("#phone"), {
  wasm: "./nsh.wasm",
  assetBase: "./assets/",   // where `asset:/…` URIs (image imports) are served from
  // dark: true,            // force an appearance; otherwise it follows the system
  // idiom: "phone",        // force "phone", "pad" or "desktop"; otherwise the pointer and the size decide
  // history: false,        // pages and dialogs as browser history entries; by default only when the app is the page, not in an iframe
  // dialogs: "viewport",   // Dialog, Sheet and AlertDialog over the whole browser window; by default over the container
});
await player.runModule(new URL("./bundle.js", location.href).href);
```

`assets` (a map from `asset:/` paths to URLs) replaces `assetBase`, `readAsset(uri)` returns the bytes of an asset the engine needs at once (a font) or `null`, `data` maps the files the runtime fetches when it first needs them to their URLs (`syntaxes`: `nsh-syntaxes.<digest>.bin`; by default `nsh-<name>.bin` next to `nsh.js`), and `glue` is the URL of the wasm-bindgen glue of a runtime whose crates call [browser APIs from Rust](#browser-apis-from-rust) (`nsh-bindgen.<digest>.js`), which the player loads with the runtime; `player.runModule(url, { capabilities, appId })` runs the app under the capabilities it declares (its `capabilities.json`) and keeps its storage under its `nsh.json` id (without one, under the page's path). The page `nsh package --target web` writes uses all of them.

`runModule(url, { chunks })` also takes where the chunks of a [split bundle](#split-bundles) are.

`player.runSource(code, { name, sourceMap, capabilities, appId })` runs an ES module given as source text, with the same options. With `nsh-playground.wasm`, `player.compileAndRun(tsx, name, options)` compiles TSX first, runs it with `runSource`'s options and resolves to the compile error, or `null`; `player.compile(tsx)` returns `{ code }` or `{ error }`.

The container's size is the app's window (`windowSize()`); resizing the container resizes the app. `player.setDark(true)` switches the appearance at run time, which apps observe through `colorScheme()` and `dark:` classes.

Dialogs and alerts cover the container. With `dialogs: "viewport"` they cover the whole browser window, as a page's own modal dialogs do, while the app keeps the container as its window: a `Dialog` lays out at the window's size and safe area and slides in from its bottom edge, its backdrop covers the whole page, and the mouse wheel over it leaves the page in place. The dialog shows in the browser's top layer (Chrome 114, Safari 17, Firefox 125 and later), so it is above the rest of the page wherever the container is; in earlier browsers it covers the container.


`Sheet` follows the same presentation setting as `Dialog` and `AlertDialog`. In a same-origin iframe,
viewport presentation automatically covers the outer page, while the app keeps its original layout size.
The iframe returns to its original position and size when the last popup closes; its engine and state stay alive.
The documentation demos enable this presentation.

For a cross-origin or sandboxed iframe, the embedding page registers the host before loading the player:

```js
import { hostPlayerFrame } from "./nsh.js";
const frame = document.querySelector("iframe");
const disconnect = hostPlayerFrame(frame);
frame.src = "https://apps.example.com/player.html"; // player uses dialogs: "viewport"
// When removing the embedding: disconnect();
```

The host accepts requests from this iframe's window, keeps the surrounding page inert and locks its scrolling
while a popup is visible, and restores both on close. Each cross-origin embedding boundary requires its host's
cooperation; without it, presentation remains within that document and the player reports a warning.

## The host's functions

On the web the page is the app's host: it answers [`host`](https://nsh.dev/versions/main/modules/nsh.md#host)'s `host.call(name, args)` and sends the events `host.on` listens to. `createPlayer`'s `host` is an object whose `call(name, args)` returns the result, or a promise of it; a throw or a rejection rejects the app's call with the error's message. `player.hostEvent(event, payload)` sends an event with a JSON payload (a payload that is not JSON throws). With a `host`, `host.available()` is `true`.

```js
const player = await createPlayer(container, {
  wasm: "./nsh.wasm",
  host: {
    async call(name, args) {
      if (name === "user.info") return { name: "Ada" };
      throw new Error(`no host function ${name}`);
    },
  },
});
player.hostEvent("theme", { dark: true });
```

A published app gets its host from `nsh.json`: `web.host` names a JS module in the app's directory, relative to `nsh.json`, that exports `createHost(player)`. `nsh package --target web` copies it into the site as `host.<digest>.js`, and the page runs `createHost` with the player before the app starts; what it returns (or resolves with) must have a `call` function, or the page shows that the app could not be loaded. The player `createHost` receives sends events from then on:

```json
{
  "capabilities": {
    "host": ["user.*"]
  },
  "web": { "host": "./host.js", "connect": ["api.example.com"] }
}
```

```js
// host.js
const post = (url) => (args) =>
  fetch(url, { method: "POST", body: JSON.stringify(args) }).then((r) => r.json());

// The functions the app may call, by their exact names.
const functions = new Map([
  ["user.info", post("https://api.example.com/user/info")],
  ["user.settings", post("https://api.example.com/user/settings")],
]);

export async function createHost(player) {
  addEventListener("online", () => player.hostEvent("online", {}));
  return {
    call(name, args) {
      const f = functions.get(name);
      if (!f) throw new Error(`no host function ${name}`);
      return f(args);
    },
  };
}
```

The host looks each name up as it is in a table of its functions, as above, and keeps its URLs and paths its own: `capabilities.host` grants names by their beginning (`user.*`), so a name the host turned into a path could reach what the grant leaves out. The runtime passes on names of 1 to 128 characters from `A`–`Z`, `a`–`z`, `0`–`9`, `_`, `.`, `:` and `-`, without `..`, and rejects the call of any other name. A prefix grant ends with a separator (`bridge.*`): `bridge*` matches `bridgeAdmin` too.

Events sent before the app runs, such as from `createHost` itself, are delivered in order as soon as it starts, so the app's top-level `host.on` listeners receive them. An event sent before a listener registers is not replayed to it: an app reads the state it starts with through a call (`host.call("user.info")`) and follows its changes through events.

The host module runs in the app's page and shares its Content-Security-Policy: when the app's capabilities restrict `network`, the page's `connect-src` holds the page's origin, the hosts `capabilities.network` lists and the hosts `web.connect` lists. `web.connect` names the hosts the host module's own requests (`fetch`, `XMLHttpRequest`, `WebSocket`) reach, as patterns like those of `capabilities.network.hosts` (`api.example.com`, `*.example.com`, `"*"`), as `api.example.com` above; the app's own requests stay checked against its `capabilities`.

The module is copied as it is, so it imports other code by absolute URL. The app still needs its `host` [capability](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md) for each function it calls. `nsh run --target web` runs it on the development page, and `nsh test` runs the same module for every app its tests open, headless or in a browser (`--target web`), so the app and its host are tested together ([Testing](https://nsh.dev/versions/main/docs/testing-and-trace.md#the-pages-host)).

## The browser as a platform

`platform.os` is `"web"`. What kind of device the browser is on decides how the app behaves, as `platform.idiom`:

- `"desktop"`: a mouse (a fine pointer that hovers) and a container at least 600 points wide. `platform.desktop` is `true`, `platform.select` picks `desktop` and `desktop={{…}}` props apply.
- `"pad"`: a touch screen whose short side is at least 600 points; `"phone"` otherwise. These are mobile: `platform.select` picks `mobile`.

The idiom is decided when the app starts and stays the same while it runs, as on every platform; a narrow desktop window is still a desktop, laid out for its `windowSize()`. `web={{…}}` props, `platform.select({ web })` and `web:` classes apply in browsers only; `ios={{…}}`, `native` and `ios:` do not apply there.

The page reports the rest of the environment, and keeps it current:

| Value | From the browser |
|---|---|
| Locale (`Intl`'s default) | `navigator.languages[0]` |
| Time zone (`Date`'s local time, `Intl`'s default `timeZone`) | the browser's (`Intl.DateTimeFormat().resolvedOptions().timeZone`), daylight saving time included |
| The layout direction (`rtl:` / `ltr:`) | `<html dir>` when set, else the locale's script |
| `reduceMotion()` | `prefers-reduced-motion` |
| `fontScale()` | the root element's font size / 16 px (the browser's text size setting) |
| `pixelRatio()` | `devicePixelRatio` (it changes with zoom and screens) |
| `colorScheme()` | `prefers-color-scheme` |
| `safeArea()` | `env(safe-area-inset-*)` where it overlaps the container (`viewport-fit=cover` pages on phones) |
| `keyboardFrame()` | how much of the container the on-screen keyboard covers (`visualViewport`) |

`platform.version` is `"0.0"`, and `screenReaderEnabled()` stays `false` (browsers do not tell). The browser's bars around the page are the browser's; a page's [`statusBar`](https://nsh.dev/versions/main/modules/nsh-base.md#status-bar) is for the phones.

## Networking

`fetch` (with streams, `AbortController` and `FormData`) and `<Image>` URLs go through the browser's own network stack, after NSH has checked the app's [capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md). Since the requests are the browser's, the browser's rules apply:

- **Relative URLs** resolve against the page's URL, as in the browser: a published app reaches its own API with `fetch("/api/items")`, and `<Image src="/photos/a.jpg" />` loads from its own server. (Native platforms have no page, so they need absolute URLs.)
- **CORS.** A request to another origin than the page's only succeeds if that server allows the page's origin (`Access-Control-Allow-Origin`); otherwise `fetch` rejects with a network error. Only the response headers the server exposes are visible.
- **Cookies** (and HTTP authentication) are sent to the page's own origin only (`credentials: "same-origin"`), and headers browsers forbid (`Cookie`, `User-Agent`, `Host`, ...) are dropped.
- **Redirects** are followed by the browser. A redirected request that must not follow it fails: `redirect: "manual"` and `"error"`, and requests of an app whose capabilities restrict `network` (NSH checks every hop, and browsers do not reveal a redirect before following it).
- **Request bodies** that are a `ReadableStream` are collected first and sent in one piece; response bodies stream as they arrive.

## Split bundles

A TSX web app does not need to download all of its code before the first screen shows (a Rust app is one `nsh.wasm`,
which the browser compiles while it downloads). `nsh package --target web` publishes TSX apps split, with each chunk as `<name>.<digest>.js` and the page mapping chunks to those files. To split a bundle yourself, `nsh build --split` puts the modules that `import()` loads into chunks of their own, next to `bundle.js`:

```sh
nsh build --release --split -o site/app
# bundle.js        the app up to its first screen
# Screen.js        import("./Screen") and what only it uses
# detail.js        what two chunks share, when they do (made by the bundler)
```

The first `import("./Screen")` downloads `Screen.js` and the chunks it imports, all at once, then evaluates them; later imports of it resolve at once. The page says where the chunks are: by default next to the bundle, or one URL per chunk, for files renamed with a content digest so a CDN can cache them forever:

```js
await player.runModule(entry, {
  chunks: { "Screen.js": "/app.3f2a9c.js", "detail.js": "/app.81bb07.js" },
});
```

A chunk that cannot be downloaded rejects the `import()` with a `TypeError` naming it; the next `import()` tries again. Chunk names are fixed file names from the bundle: the app cannot make the page download anything else.

The [gallery](/gallery) loads each demo this way: `lazy` (in `examples/gallery/ui.tsx`) makes a component that starts the import the first time it renders, shows a placeholder until it resolves, then renders what it loaded. Its first load is the index and the demo shown first; a font a demo imports comes with that demo's chunk. Native builds hold every module, so there the import resolves at once:

```tsx
const Stocks = lazy(() => import("./demos/Stocks").then((m) => m.Stocks));
```

## Limits

The browser decides these, and the web backend follows it:

- **Web views of other sites**: `WebView` is an `<iframe>`. Inline HTML (`html`) gets everything: `onMessage`, `postMessage`, `injectJavaScript`, the injected scripts and load events (it runs with an origin of its own, apart from the page). A page of another site only gets `postMessage` and load events with the URL it was given: browsers hide its navigations, title, history and errors from the page around it, and `userAgent` cannot be set.
- **Videos with sound that start on their own**: `Video` is a `<video>` with every prop and event, but browsers only start a video with sound after a user gesture (muted videos play).
- **Native components**: registered native components belong to the native apps that embed NSH; on the web their view stays empty, with a warning in the console.
- **Platform services**: reading the clipboard (`Clipboard.readText`, also `hasText`) needs a secure context (HTTPS) and may ask the user. Images do not report `onProgress`.
- **Text shaping details**: line breaking is a subset of UAX #14 (spaces, CJK, hyphens, and the line start and end rules of CJK punctuation: closing marks such as `。`, `，` and `」` stay off the start of a line, opening marks such as `（` and `「` off its end), with no hyphenation and no bidirectional reordering beyond the paragraph direction.

The player and the dev server run apps with development settings; published apps run as releases. Both run a TSX app's code on the browser's JavaScript engine, in a realm of the app's own.

## See also

- [Packaging](https://nsh.dev/versions/main/docs/packaging.md): the other targets of `nsh package`.
- [Architecture](https://nsh.dev/versions/main/docs/architecture.md): the engine, the core and the mount batches the web build reuses.
- [Testing](https://nsh.dev/versions/main/docs/testing-and-trace.md): `nsh test` runs the same engine headless, with an approximate text engine.

Source: https://nsh.dev/versions/main/docs/web

---

# Platform-specific code

One NSH bundle runs on iOS, Android, macOS, Windows and Linux (and in Mac Catalyst), and in browsers through the [web runtime](https://nsh.dev/versions/main/docs/web.md). Most of an app needs no platform checks at all: elements, styles, layout and modules behave the same everywhere, and the components you draw from them look the same everywhere. When something really is specific to one platform, NSH gives it a clear place, so platform code stays visible and contained:

| Rust | TSX | For |
|---|---|---|
| [Builder methods (`.ripple(..)`, `.input_accessory(..)`)](#platform-only-props) | [`ios={{…}}`, `android={{…}}`, `desktop={{…}}`, `web={{…}}`](#platform-only-props) | Props only one platform has. |
| [`on_back_press`, `nsh_core::element::desktop`](#platform-modules) | [`nsh/mobile`, `nsh/desktop`](#platform-modules) | APIs only mobile platforms or only desktops have. |
| [`os()`, `idiom()`, `is_desktop()`](#platformos-and-platformselect) | [`platform.os`, `platform.desktop`, `platform.select`](#platformos-and-platformselect) | Choosing values or code per platform. |
| [`.when(os() == Os::Ios, ..)`](#platform-variants-in-tailwind) | [`ios:` / `android:` / `web:` classes](#platform-variants-in-tailwind) | Styles per platform. |

## Desktop and mobile

Every platform is desktop or mobile, by one rule. Desktop is macOS, Windows, Linux, and browsers in the desktop idiom (a mouse and a wide window, [the web](https://nsh.dev/versions/main/docs/web.md)). Mobile is iOS, Android, and browsers in the phone or tablet idiom; Mac Catalyst runs the iOS backend, so it is mobile too, with `ios={{…}}` props. `desktop={{…}}` props, `platform.select({ desktop, mobile })`, `platform.desktop` and `platform.idiom === "desktop"` all follow this rule, as do `nsh/base`'s components (a menu is a popup on desktops and a sheet on mobile) and, in Rust, `is_desktop()`.

`nsh/desktop`'s `isAvailable` answers a narrower question: whether that module's window and menu APIs work, which they do on macOS, Windows and Linux. Gate layout, density and input on `platform.desktop`, and calls of `Window` and `Menu` on `isAvailable`.

## Platform-only props

In Rust, a prop one platform has is a builder method like any other (`.ripple(..)`, `.elevation(..)` for Android, `.input_accessory(..)` for iOS, `.window_drag(..)` for the desktops); the other platforms leave it aside. In TSX, props that exist on one platform only are grouped in an object named after it. Each element accepts `ios`, `android`, `desktop` (macOS, Windows, Linux, and browsers in the desktop idiom) and `web` (browsers); on other platforms the object is ignored, and on its own platform only its keys are applied. A desktop browser applies both `desktop` and `web`.

```rust
use nsh_base::dialog;
use nsh_core::{
    Ripple,
    element::{AutoFill, Orientation}, prelude::*,
};

view()
    .on_press(open)
    .active(|s| s.opacity(0.6))
    .ripple(Ripple {
        color: Some(rgba(0x0000001f).into()),
        ..Ripple::default()
    })
    .elevation(px(4.0))
    .p_4()
    .rounded(px(12.0))
    .bg(white())
    .child(text("Open"))

input().placeholder("Code").auto_fill(AutoFill::OneTimeCode)

when(shown, || {
    dialog()
        .supported_orientations([Orientation::Portrait])
        .status_bar_translucent(true)
        .child(…)
})
```

```tsx
<View
  onPress={open}
  activeStyle={{ opacity: 0.6 }}
  android={{ ripple: { color: "rgba(0,0,0,0.12)" }, elevation: 4 }}
  style={{ padding: 16, borderRadius: 12, backgroundColor: "#ffffff" }}
>
  <Text>Open</Text>
</View>

<Input
  placeholder="Code"
  ios={{ textContentType: "oneTimeCode" }}
/>

<Dialog open={open()} ios={{ supportedOrientations: ["portrait"] }} android={{ statusBarTranslucent: true }}>
  …
</Dialog>
```

The TSX objects are reactive like any prop; a key removed from the object is cleared.

What exists today:

| Rust | TSX | On | Description |
|---|---|---|---|
| `.ripple(Ripple { .. })` | `android={{ ripple }}` | every element | The material ripple while pressed: color, borderless, radius, foreground. |
| `.elevation(..)` | `android={{ elevation }}` | every element | The material shadow, in points, from the view's shape. |
| | `android={{ accessibilityLiveRegion }}` | every element | `"none"`, `"polite"` or `"assertive"`: TalkBack announces the view's changes. |
| `.status_bar_translucent(..)` | `android={{ statusBarTranslucent }}` | `Dialog` | The dialog's content reaches under the status bar. |
| `.input_accessory(..)` | `ios={{ inputAccessoryViewID }}` | `Input` | The `InputAccessoryView` shown over the keyboard. |
| `.auto_fill(..)` | `ios={{ textContentType }}` | `Input` | iOS's names for autofill types (Rust's `AutoFill` covers both platforms). |
| `.supported_orientations(..)` | `ios={{ supportedOrientations }}` | `Dialog` | The orientations it allows. |
| `.back_forward_gestures(..)` | `ios={{ allowsBackForwardNavigationGestures }}` | `WebView` | Swipe back and forward in the page history. |
| `.header_right_system_item(..)` | `ios={{ headerRightSystemItem }}` | `NavPage` | UIKit's own bar button at the end of the header, pressing `headerRight`. |
| `.header_left_system_item(..)` | `ios={{ headerLeftSystemItem }}` | `NavPage` | UIKit's own bar button at the start of the header, pressing `headerLeft`. |
| `.header_right_symbol(..)` | `ios={{ headerRightSymbol }}` | `NavPage` | UIKit's own bar button showing an SF Symbol at the end of the header, pressing `headerRight`. |
| `.header_left_symbol(..)` | `ios={{ headerLeftSymbol }}` | `NavPage` | UIKit's own bar button showing an SF Symbol at the start of the header, pressing `headerLeft`. |
| `.back_forward_gestures(..)` | `desktop={{ allowsBackForwardNavigationGestures }}` | `WebView` | macOS: two-finger trackpad swipes go back and forward in the page history; Windows: touchscreen swipes; Linux: touchpad swipes. |
| `.window_drag(..)` | `desktop={{ windowDrag }}` | every element | Pressing it drags the window, as the system's title bar would (see [nsh/desktop](https://nsh.dev/versions/main/modules/nsh-desktop.md#a-title-bar-of-your-own)). |

In TSX, `desktop={{…}}` and `web={{…}}` are accepted everywhere. The types (`IOSProps`, `AndroidProps`, `DesktopProps` and their per-element forms) tell your editor what each element takes.

What an element means on every platform is a top-level prop (in Rust a method of the same name), applied where it means something: `NavPage`'s `title`, `headerStyle`, `headerLargeTitle` and `headerBackTitle` set up the system header of iOS and Android, its `header` slot is the header of the desktops and the web, and `Dialog`'s `presentation` picks iOS's sheets. `AlertDialog.show`'s `closeOnBackdropPress`, `pagingEnabled`, `refreshing`, `hitSlop` and the rest work on every platform. A platform's own system feature goes in its object, and when several platforms have it, in each of theirs under the same name: `WebView`'s `allowsBackForwardNavigationGestures`, the system's swipes through the page history, is in `ios={{…}}` and `desktop={{…}}`.

## Platform modules

In Rust, the APIs only one platform has are functions of `nsh_core::prelude` (`on_back_press`, `input_accessory_view`) and of `nsh_core::element::desktop` (the window: `set_title`, `set_title_bar`, `title_bar`, `minimize`, `toggle_maximize`, `toggle_full_screen`, `set_frame`, `set_level`, `order_front`, `close_window`; menus: `set_application_menu`, `popup_menu`); elsewhere they do nothing. In TSX, `nsh/mobile` holds the APIs of iOS and Android (some of them one platform's), `nsh/desktop` those of the desktops. Both can be imported on every platform, so one bundle runs everywhere: on other platforms their functions return at once and their components take no room. Each exports `isAvailable`, which is `true` on its own platforms; `platform.os` tells them apart.

### nsh/mobile

`isAvailable` is `true` on iOS (with Mac Catalyst) and Android. Both platforms have [`TabBar`](https://nsh.dev/versions/main/modules/nsh-mobile.md#tabbar), the system's tab bar.

#### BackHandler (Android)

| Rust | TSX | Description |
|---|---|---|
| `on_back_press(listener)` | `BackHandler.on("press", listener)` | Listens to the back button after dialogs, before stacks; return `true` when handled. The listener goes with the component (or effect) that added it; in TSX the call also returns a function that stops it earlier. |
| | `BackHandler.exitApp()` | Leaves the app. |

```rust
use nsh_core::prelude::*;

fn player() -> impl IntoElement {
    let full_screen = signal(false);
    // Back leaves full screen before it leaves the page. The listener goes
    // with the view.
    on_back_press(move || {
        if !full_screen.get_untracked() {
            return false;
        }
        full_screen.set(false);
        true
    });
    // …
}
```

```tsx
import { BackHandler } from "nsh/mobile";

function Player() {
  // Back leaves full screen before it leaves the page. The listener goes
  // with the component.
  BackHandler.on("press", () => {
    if (!fullScreen()) return false;
    fullScreen.set(false);
    return true;
  });
  // …
}
```

The back button is handled by the top dialog first, then the back listeners (most recent first), then the top navigation stack, and the app exits when nothing handled it. See [Navigation](https://nsh.dev/versions/main/docs/navigation.md#the-android-back-button).

#### InputAccessoryView (iOS)

| Rust | TSX | Description |
|---|---|---|
| `input_accessory_view(native_id)` | `InputAccessoryView` | A bar over the keyboard of the inputs naming its native id (`.input_accessory(..)`, `ios={{ inputAccessoryViewID }}`). |

See [Forms and the keyboard](https://nsh.dev/versions/main/docs/forms-and-keyboard.md#a-bar-over-the-keyboard-ios-inputaccessoryview).

### nsh/desktop

Rust apps draw their own title bars with `nsh_core::element::desktop` ([Building with Rust](https://nsh.dev/versions/main/docs/rust.md#desktop-title-bars)). TSX's module:

| Export | Description |
|---|---|
| `Window` | The window: `setTitle`, `setTitleBar({ style: "hidden" })` for a title bar of the app's own, `minimize`, `toggleMaximize`, `toggleFullScreen`, `close`. |
| `titleBar` | The hidden title bar's height and the room the system's window controls take (reactive). |
| `Menu` | `setApplicationMenu(items)` (the menu bar, with shortcuts) and `popup(items, at?)` (context menus). An item's `icon` is an image as `<Image>`'s `src` takes it, so menus show the app's own icon set: an SVG takes the color of the menu's text, a bitmap keeps its colors. macOS and Windows show it; GTK's menus show no icon beside a label. |
| `isAvailable` | `true` where the window and menu APIs work: macOS, Windows and Linux. Desktop browsers have `platform.desktop` and keep the browser's window and menus. |

See [nsh/desktop](https://nsh.dev/versions/main/modules/nsh-desktop.md).

### The status bar

On both platforms the status bar belongs to the page or dialog on top, as in UIKit, where the topmost view controller decides it: [`NavPage` and `Dialog` take `statusBar`](https://nsh.dev/versions/main/modules/nsh-base.md#status-bar) (in Rust `.status_bar(StatusBarStyle::Light)`, or a `StatusBarSetting` for the other fields) with `foreground` (`"auto"`, `"light"` for dark backgrounds, `"dark"` for light ones), `hidden` and `animated`. The page or dialog shown most recently wins, field by field, and the one below it applies again when it goes away. `nsh.json`'s `"statusBar"` is the app's default under them.

```rust
use nsh_base::nav_page;
use nsh_core::prelude::*;

fn photo_viewer() -> impl IntoElement {
    nav_page()
        .header_visible(false)
        .status_bar(StatusBarStyle::Light)
        .child(view().flex_1().bg(black()))
}
```

```tsx
import { View } from "nsh";
import { NavPage } from "nsh/base";

function PhotoViewer() {
  return (
    <NavPage headerVisible={false} statusBar={{ foreground: "light" }}>
      <View style={{ flex: 1, backgroundColor: "#000000" }}>…</View>
    </NavPage>
  );
}
```

In an app embedded in a native one, the host app's view controller decides the status bar on iOS. An app that declares `"capabilities"` in `nsh.json` needs `"statusBar": true` to change it.

## platform.os and platform.select

`os()` in Rust and the `platform` constant from `nsh` in TSX tell you where the app runs: `Os::Ios`, `Os::Android`, `Os::MacOs`, `Os::Windows`, `Os::Linux` or `Os::Web`, and `platform.os` `"ios"`, `"android"`, `"macos"`, `"windows"`, `"linux"` or `"web"` (Mac Catalyst is `"ios"`, with `platform.catalyst` in either of its idioms; the [macOS backend](https://nsh.dev/versions/main/docs/macos.md) is `"macos"`, the [Linux backend](https://nsh.dev/versions/main/docs/linux.md) `"linux"` and the [Windows backend](https://nsh.dev/versions/main/docs/windows.md) `"windows"`, and their elements apply their `desktop` props; [browsers](https://nsh.dev/versions/main/docs/web.md) are `"web"`, and apply `desktop` props too when `platform.desktop` is `true`). See [Device and environment](https://nsh.dev/versions/main/docs/device-and-environment.md#the-platform) for the version, the idiom and the rest.

```rust
use nsh_core::{element::Os, prelude::*};

if os() == Os::Android {
    // …
}
```

```tsx
import { platform } from "nsh";

if (platform.os === "android") {
  // …
}
```

### platform.select

In Rust a `match os()` chooses the value, with `is_desktop()` for the desktops. In TSX, `platform.select(spec)` returns the value for this platform. It looks for the OS's own key, then `desktop` or `mobile` by [the rule above](#desktop-and-mobile) (`platform.desktop`), then `native` (every platform but the web), then `default`:

```rust
use nsh_core::{element::Os, prelude::*};

fn card() -> View {
    let card = view().rounded(px(12.0)).bg(white());
    match os() {
        Os::Ios => card.shadow_md(),
        Os::Android => card.border_1().border_color(rgb(0xe5e7eb)),
        _ => card,
    }
}

let hint = match os() {
    Os::Ios => "Swipe down to close",
    Os::Android => "Press back to close",
    _ => "Close",
};
```

```tsx
const styles = {
  card: {
    borderRadius: 12,
    backgroundColor: "#ffffff",
    ...platform.select({
      ios: { boxShadow: "0px 2px 8px rgb(0 0 0 / 0.12)" },
      android: { borderWidth: 1, borderColor: "#e5e7eb" },
    }),
  },
};

const hint = platform.select({ ios: "Swipe down to close", android: "Press back to close", default: "Close" });
```

It returns `undefined` when nothing matches and there is no `default`.

### Rendering different components

Choose components the same way, at module level (TSX) when the choice never changes:

```rust
fn spinner() -> AnyElement {
    if os() == Os::Ios {
        ios_spinner().into_element()
    } else {
        material_spinner().into_element()
    }
}
```

```tsx
const Spinner = platform.select({ ios: IosSpinner, default: MaterialSpinner })!;
```

or inline with [`when` / `<If>`](https://nsh.dev/versions/main/elements/control-flow.md):

```rust
when(os() == Os::Ios, || input_accessory_view("bar").child(…))
    .otherwise(|| text("Android has no input accessories."))
```

```tsx
<If when={platform.os === "ios"} else={<Text>Android has no input accessories.</Text>}>
  <InputAccessoryView nativeID="bar">…</InputAccessoryView>
</If>
```

## Platform variants in Tailwind

Rust styles per platform with `.when(os() == Os::Ios, |v| ..)`; in TSX, the `ios:`, `android:` and `web:` variants apply classes on one platform:

```rust
view()
    .rounded_xl()
    .bg(white())
    .p_4()
    .when(os() == Os::Ios, |v| v.shadow_md())
    .when(os() == Os::Android, |v| v.border_1().border_color(rgb(0xe4e4e7)))
```

```tsx
<View class="rounded-xl bg-white p-4 ios:shadow-md android:border android:border-zinc-200">…</View>
<Text class="text-base android:font-medium">Title</Text>
```

## Prefer shared behavior

Before reaching for a platform check, consider whether the difference matters to your users. Elements and styles already map to each platform's native behavior where it should differ (scroll physics, text rendering, keyboards, accessibility), while staying the same where users expect consistency (your app's own look). Platform checks are best kept for platform conventions users rely on: Android's back button and toasts, iOS's sheets and large titles, autofill names, Android's ripple.

## Related

- [`InputAccessoryView`](https://nsh.dev/versions/main/modules/nsh-mobile.md#inputaccessoryview) and [`BackHandler`](https://nsh.dev/versions/main/modules/nsh-mobile.md#backhandler): the references.
- [`nsh`'s device API](https://nsh.dev/versions/main/modules/nsh.md#device): `platform`.
- [Native components](https://nsh.dev/versions/main/docs/native-components.md): using views your host app provides on each platform.
- [Tailwind](https://nsh.dev/versions/main/docs/tailwind.md): every variant.

Source: https://nsh.dev/versions/main/docs/platform-specific

---

# Native Components

A native component is a view the **embedding app** registers by name: a map, a camera preview, a chart library, any
`UIView` on iOS, `android.view.View` on Android, `NSView` on macOS, `gtk::Widget` on Linux, or Direct2D drawing or a
child `HWND` on Windows. The NSH app uses it like any other element: a Rust app makes it with `native(name)` from
`nsh_core::prelude`, a TSX app declares it with `nativeComponent()` from [`nsh`](https://nsh.dev/versions/main/modules/nsh.md#nativecomponent-and-nativemodule). NSH lays it out with the rest of the
app, sends it props, delivers its events to handlers and forwards commands from a `ref`.

Because NSH renders with the system's own views, a native component is just one more subview in the same hierarchy:
there is no layering problem, it clips, scrolls and receives touches like a `<View>`.

> [!NOTE]
> Native components are registered by the app that embeds NSH ([iOS](https://nsh.dev/versions/main/docs/ios.md), [Android](https://nsh.dev/versions/main/docs/android.md),
> [macOS](https://nsh.dev/versions/main/docs/macos.md#embedding-in-a-mac-app), [Linux](https://nsh.dev/versions/main/docs/linux.md#embedding-in-a-gtk-app),
> [Windows](https://nsh.dev/versions/main/docs/windows.md#embedding-in-a-win32-app)), or on Windows, macOS, Linux and iOS by the app's own Rust crate,
> whose components the development host and the packaged app (`nsh package`) register
> ([Registering from the app's crate](#registering-from-the-apps-crate)). A name nothing registered renders an empty
> view (the name is logged once as unknown).

## How it fits together

1. The host app registers a factory under a name, such as `"embed.badge"`, on its `NshAppView` (iOS) or `NshView`
   (Android). Each view has its own registry; there is nothing global.
2. The NSH app declares a component for that name with the props and events it uses.
3. When the element is created, NSH creates a container view (decorated, framed and hit-tested like any view), then
   asks the factory for a component and puts the component's view inside the container, filling it.
4. The component receives every prop right after it is made, then each prop again when it changes.
5. The component emits events and may report its own size; the app calls its commands through a `ref`.

## Using the component in the app

In Rust, `native(name)` makes the element: `.prop(name, value)` gives it a prop (a `serde_json::Value`, or a signal or a
closure of one, sent again when it changes), `.on_native_event(..)` hears its events as `NativeEvent { name, data }`, and the methods of an
`element_ref()` put on it with `.element_ref(&r)` send its commands. In TSX, `nativeComponent()` declares a component
for the name with the props and events it uses.

```rust
use nsh_core::prelude::*;
use serde_json::json;

const COLORS: [&str; 4] = ["#8250df", "#0969da", "#1a7f37", "#cf222e"];

#[component]
pub fn App() -> impl IntoElement {
    let taps = signal(0_u64);
    let badge = element_ref();
    view()
        .flex_1()
        .p(px(20.0))
        .pt_safe_area_plus(px(20.0))
        .pb_safe_area_plus(px(20.0))
        .gap(px(16.0))
        .bg(rgb(0xf6f8fa))
        .child(text("Rendered by nsh").text_size(px(22.0)).font_weight(FontWeight::BOLD))
        .child(
            // The host app's badge: a label it draws, sized to its text.
            native("embed.badge")
                .element_ref(&badge)
                .prop("text", move || match taps.get() {
                    0 => json!("Tap the native badge"),
                    n => json!(format!("Tapped {n}×")),
                })
                .prop("color", move || json!(COLORS[taps.get() as usize % COLORS.len()]))
                .on_native_event(move |e: &NativeEvent| {
                    if &*e.name == "tap" {
                        taps.set(e.data["count"].as_u64().unwrap_or(0));
                        badge.command("pulse", json!(null));
                    }
                })
                .self_start()
                .rounded(px(8.0))
                .overflow_hidden(),
        )
        .child(text(move || format!("Rust saw {} taps", taps.get())))
}
```

```tsx
import { mount, type NativeComponentRef, signal, Text, View } from "nsh";
import { nativeComponent } from "nsh";

/** The host app's badge: a label it draws, sized to its text. */
const Badge = nativeComponent<{ text: string; color?: string }, { tap: { count: number } }>("embed.badge", {
  props: ["text", "color"],
  events: ["tap"],
});

const colors = ["#8250df", "#0969da", "#1a7f37", "#cf222e"];

function App() {
  const taps = signal(0);
  let badge: NativeComponentRef | undefined;
  return (
    <View style={{ flex: 1, padding: 20, paddingTop: "calc(env(safe-area-inset-top) + 20px)", paddingBottom: "calc(env(safe-area-inset-bottom) + 20px)", gap: 16, backgroundColor: "#f6f8fa" }}>
      <Text style={{ fontSize: 22, fontWeight: "700" }}>Rendered by nsh</Text>
      <Badge
        ref={(node) => (badge = node)}
        text={taps() === 0 ? "Tap the native badge" : `Tapped ${taps()}×`}
        color={colors[taps() % colors.length]}
        onTap={(e) => {
          taps.set(e.count);
          badge?.command("pulse");
        }}
        style={{ alignSelf: "flex-start", borderRadius: 8, overflow: "hidden" }}
      />
      <Text>{`JS saw ${taps()} taps`}</Text>
    </View>
  );
}

mount(App);
```

The TSX version is `examples/embedded/App.tsx`, which both embedding samples in the repository run.

### `nativeComponent(name, spec)`

```ts
function nativeComponent<P extends object = {}, E extends object = {}>(
  name: string,
  spec: NativeComponentSpec<P, E>,
): (props: NativeComponentProps<P, E>) => JSX.Element;
```

| Parameter | Type | Description |
|---|---|---|
| `name` | `string` | The name the host app registered. Use a prefix of your own (`"maps.view"`, `"acme.chart"`) so names stay unique. |
| `spec.props` | `readonly (keyof P & string)[]` | The component's own props. Only the props listed here are sent to the native side. |
| `spec.events` | `readonly (keyof E & string)[]` | The events it emits. Optional. |

The type parameters describe the props (`P`) and the payload of each event (`E`). The returned component accepts:

- the component's own props `P`;
- a handler per event: event `tap` is handled by `onTap`, `regionChange` by `onRegionChange` (the first letter is
  capitalized and `on` prepended);
- everything a `<View>` takes except children: `style`, `class` / `classList` ([Tailwind](https://nsh.dev/versions/main/docs/tailwind.md)), layout,
  accessibility props, `testID`, `onLayout`, `ref`. These belong to the container NSH draws, not to the component.

A native component is a leaf: it takes no children.

## Props

Each own prop is sent as JSON, so its value can be any JSON value: strings, numbers, booleans, `null`, arrays and
plain objects. Props are reactive like any other: when a Rust prop's closure (`.prop("text", move || json!(label.get()))`)
or a TSX `text={label()}` reads a signal, the new value is sent when the signal changes, and only then.

| What happens in the app | What the component receives |
|---|---|
| The element is created | Every own prop that is set, right after the component is made |
| A prop's value changes | That prop with its new value |
| A prop becomes `undefined` | That prop with no value (`nil` in Swift, `null` in Java) |
| A prop bound to an animated value moves | `setAnimatedNumber` / `setAnimatedColor`, on the frames it changes |

Props carry JSON values; keep the interface to data (functions and class instances stay in the app).

### Animated props

A prop can also be an animated value: an `AnimatedValue`, or a node derived from one (`interpolate`, a scroll view's
`scrollValue` or `pullValue`). It is then not sent as JSON: NSH binds it, and the component is handed the value on the UI
thread on every frame it changes, without going through JS, so it can follow a drag or a pull to refresh.

```tsx
const pull = createAnimatedValue(0);
<Scroll pullValue={pull} refreshIndicator={{ height: 72 }} refreshing={refreshing()} onRefresh={refresh}>
  <Spinner progress={pull.interpolate({ inputRange: [0, 72], outputRange: [0, 1] })} />
</Scroll>
```

The component receives numbers with `setAnimatedNumber(name, value)` and colors with `setAnimatedColor(name, argb)`
(`0xAARRGGBB`); by default both call `setProp` with the number, so a component that does not implement them still
gets the value. Rust components implement `set_animated_number` and `set_animated_color`, and Rust code binds a prop
with `native(name).bind_animated_prop("progress", &value)`. Giving the prop a plain value again unbinds it and sends that
value. The web has no registered components.

## Events

The component emits an event by name with an optional JSON payload. NSH delivers it to the engine thread and calls the
matching handler with the payload (in Rust, the one `on_native_event` listener with the event's `name` and `data`):

```rust
use serde_json::json;

native("acme.map")
    .prop("latitude", json!(52.52))
    .prop("longitude", json!(13.405))
    .on_native_event(move |e: &NativeEvent| match &*e.name {
        "regionChange" => center.set((
            e.data["latitude"].as_f64().unwrap_or_default(),
            e.data["longitude"].as_f64().unwrap_or_default(),
        )),
        "markerPress" => open(e.data["id"].as_str().unwrap_or_default()),
        _ => {}
    })
    .flex_1()
```

```tsx
const MapView = nativeComponent<
  { latitude: number; longitude: number; zoom?: number },
  { regionChange: { latitude: number; longitude: number }; markerPress: { id: string } }
>("acme.map", {
  props: ["latitude", "longitude", "zoom"],
  events: ["regionChange", "markerPress"],
});

<MapView
  latitude={52.52}
  longitude={13.405}
  onRegionChange={(region) => center.set(region)}
  onMarkerPress={({ id }) => open(id)}
  style={{ flex: 1 }}
/>;
```

Events are asynchronous: the main thread never waits for the app's code. A component that must decide something on the spot (may
this gesture start, may this region change) has to decide it natively, from props it received earlier.

## Commands

Imperative calls (zoom to a point, start playback, pulse an animation) go through the element's ref (`element_ref()` in Rust, `ref` in TSX):

```rust
let map = element_ref();

native("acme.map")
    .element_ref(&map)
    .prop("latitude", json!(52.52))
    .prop("longitude", json!(13.405))
    .flex_1()

map.command("zoomTo", json!({ "level": 3 }));
```

```tsx
let map: NativeComponentRef | undefined;

<MapView ref={(node) => (map = node)} latitude={52.52} longitude={13.405} style={{ flex: 1 }} />;

map?.command("zoomTo", { level: 3 });
```

`command(name, args)` (TSX: `command(name, args?)`) sends the name and the arguments (any JSON value) to the component's `command` method. Commands
are applied in order with the changes made before them, so a command issued right after a prop change sees the new prop.

## Sizing

The container is laid out like a `<View>`:

- Where the style gives a dimension (`width`, `height`, `flex: 1`, `alignSelf: "stretch"`, ...), that dimension wins.
- Where the style leaves a dimension open, the container takes the size the component reported with `setSize`, like an
  image takes its natural size. A component that never reports a size measures 0 along open dimensions.

Report the size in points (iOS) or dp (Android) whenever the content changes. The badge above measures its label each
time `text` changes and reports the label's size plus padding, so `alignSelf: "flex-start"` makes the badge exactly as
wide as its text.

## Registering on iOS (Swift)

Implement `NshComponent` and register a factory on the `NshAppView`:

```swift
import NativeShell
import UIKit

/// `embed.badge`: props `text` and `color`; emits `tap`; command `pulse`.
final class Badge: NshComponent {
    let view = UIView()
    private let label = UILabel()
    private let context: NshComponentContext
    private var taps = 0

    init(_ context: NshComponentContext) {
        self.context = context
        label.textColor = .white
        label.font = .boldSystemFont(ofSize: 17)
        label.textAlignment = .center
        label.frame = view.bounds
        label.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        view.addSubview(label)
        view.addGestureRecognizer(UITapGestureRecognizer(target: self, action: #selector(tapped)))
    }

    func setProp(_ name: String, _ value: Any?) {
        switch name {
        case "text":
            label.text = value as? String
            let size = label.intrinsicContentSize
            context.setSize(CGSize(width: size.width + 32, height: size.height + 20))
        case "color":
            view.backgroundColor = (value as? String).flatMap(UIColor.init(hex:)) ?? .systemPurple
        default:
            break
        }
    }

    func command(_ name: String, _ args: Any?) {
        guard name == "pulse" else { return }
        view.alpha = 0.3
        UIView.animate(withDuration: 0.6) { self.view.alpha = 1 }
    }

    @objc private func tapped() {
        taps += 1
        context.emit("tap", ["count": taps])
    }
}

// Before loading the bundle:
app.register(component: "embed.badge") { context in Badge(context) }
```

(`UIColor(hex:)` is a small helper of the sample, not part of NativeShell.)

| API | Description |
|---|---|
| `NshAppView.register(component:_:)` | Registers a factory `(NshComponentContext) -> NshComponent` under a name. It makes one component per element created from then on. Registering a name again replaces the factory. |
| `protocol NshComponent` | `var view: UIView` (fills the container), `setProp(_:_:)`, `command(_:_:)` (optional: the default ignores commands). Main-actor isolated. |
| `setProp(_ name: String, _ value: Any?)` | Values are Foundation JSON objects: `String`, `NSNumber`, `[Any]`, `[String: Any]`, `NSNull`; `nil` when the prop was removed. |
| `NshComponentContext.emit(_:_:)` | Emits an event; the data must be something `JSONSerialization` accepts (or `nil`). Thread-safe. |
| `NshComponentContext.setSize(_:)` | Reports the component's own size in points. Thread-safe. |

## Registering on Android (Java / Kotlin)

Implement `com.longbridge.nsh.NshComponent` and register a factory on the `NshView`:

```java
import com.longbridge.nsh.NshComponent;
import com.longbridge.nsh.NshComponentContext;

final class Badge implements NshComponent {
    private final TextView label;
    private final NshComponentContext context;
    private final float density;
    private int taps;

    Badge(Context app, NshComponentContext context) {
        this.context = context;
        density = app.getResources().getDisplayMetrics().density;
        label = new TextView(app);
        label.setTextColor(Color.WHITE);
        label.setTextSize(17);
        label.setGravity(Gravity.CENTER);
        label.setOnClickListener(v -> context.emit("tap", Collections.singletonMap("count", ++taps)));
    }

    @Override
    public View view() {
        return label;
    }

    @Override
    public void setProp(String name, Object value) {
        if (name.equals("text")) {
            label.setText(value instanceof String ? (String) value : "");
            label.measure(0, 0);
            // Sizes are in dp.
            context.setSize(label.getMeasuredWidth() / density + 32, label.getMeasuredHeight() / density + 12);
        } else if (name.equals("color")) {
            label.setBackgroundColor(value instanceof String ? Color.parseColor((String) value) : 0xff8250df);
        }
    }

    @Override
    public void command(String name, Object args) {
        if (!name.equals("pulse")) return;
        label.setAlpha(0.3f);
        label.animate().alpha(1).setDuration(600).start();
    }
}

// Before loading the bundle:
nsh.registerComponent("embed.badge", context -> new Badge(this, context));
```

The same in Kotlin:

```kotlin
nsh.registerComponent("embed.badge") { context -> Badge(this, context) }
```

| API | Description |
|---|---|
| `NshView.registerComponent(String name, NshComponent.Factory factory)` | Registers a factory under a name; it makes one component per element created from then on (UI thread). |
| `interface NshComponent` | `View view()`, `void setProp(String, Object)`, `default void command(String, Object)`, `default void destroy()` (the element is gone: removed, or its app stopped by `NshView.destroy()` or replaced by another load; called once per component). Called on the UI thread. |
| `setProp` values | `String`, `Number`, `Boolean`, `java.util.List`, `java.util.Map`, or `null` when removed (or JSON `null`). |
| `NshComponentContext.emit(String event, Object data)` | Emits an event; `data` as the same Java types, or `null`. Any thread. |
| `NshComponentContext.setSize(float width, float height)` | Reports the component's own size in dp. Any thread. |

## Registering from Rust

Apps that embed the iOS runtime from Rust (`nsh-platform-ios`) register a `NativeComponent` on an `AppView`:

```rust
use std::rc::Rc;
use nsh_core::JsonValue;
use nsh_platform_ios::{AppView, ComponentContext, NativeComponent};
use objc2_ui_kit::UIView;

struct Badge {
    view: objc2::rc::Retained<UIView>,
    context: ComponentContext,
}

impl NativeComponent for Badge {
    fn view(&self) -> &UIView {
        &self.view
    }

    fn set_prop(&mut self, name: &str, value: Option<&JsonValue>) {
        // ... update the view, then report its size in points:
        self.context.set_size(120.0, 40.0);
    }

    fn command(&mut self, name: &str, args: &JsonValue) {
        // optional
    }
}

fn register(app: &AppView, make_view: impl Fn() -> objc2::rc::Retained<UIView> + 'static) {
    app.register_component(
        "embed.badge",
        Rc::new(move |context: ComponentContext| -> Box<dyn NativeComponent> {
            Box::new(Badge { view: make_view(), context })
        }),
    );
}
```

`ComponentContext::emit(name, data)` sends an event (`data` is a `serde_json::Value`) and `set_size(width, height)`
reports the size; both work from any thread.

## Registering on macOS (Rust)

On macOS the component is an `NSView`, registered on the [`AppView`](https://nsh.dev/versions/main/docs/macos.md#embedding-in-a-mac-app) of
`nsh-platform-macos`:

```rust
use std::rc::Rc;
use nsh_core::JsonValue;
use nsh_platform_macos::{
    objc2::{rc::Retained, MainThreadMarker},
    objc2_app_kit::{NSTextField, NSView},
    objc2_foundation::NSString,
    AppView, ComponentContext, NativeComponent,
};

struct Badge {
    label: Retained<NSTextField>,
    context: ComponentContext,
}

impl NativeComponent for Badge {
    fn view(&self) -> Retained<NSView> {
        Retained::into_super(Retained::into_super(self.label.clone()))
    }

    fn set_prop(&mut self, name: &str, value: Option<&JsonValue>) {
        if name == "text" {
            let text = value.and_then(|v| v.as_str()).unwrap_or("");
            self.label.setStringValue(&NSString::from_str(text));
            self.context.set_size(120.0, 40.0);
        }
    }

    fn command(&mut self, name: &str, args: &JsonValue) {
        // optional
    }
}

fn register(app: &AppView, mtm: MainThreadMarker) {
    app.register_component(
        "embed.badge",
        Rc::new(move |context: ComponentContext| -> Box<dyn NativeComponent> {
            Box::new(Badge { label: NSTextField::labelWithString(&NSString::new(), mtm), context })
        }),
    );
}
```

The view fills the container NSH lays out; `ComponentContext::emit` and `set_size` (points) work from any thread, as
on iOS. Register before `AppView::load`; a registry belongs to one `AppView` (and the views made from the same
`AppOptions`).

## Registering on Linux (Rust)

On Linux the component is a GTK widget, registered on the [`AppView`](https://nsh.dev/versions/main/docs/linux.md#embedding-in-a-gtk-app) of
`nsh-platform-linux`:

```rust
use std::rc::Rc;
use nsh_core::JsonValue;
use nsh_platform_linux::{gtk4 as gtk, AppView, ComponentContext, NativeComponent};
use gtk::prelude::*;

struct Badge {
    label: gtk::Label,
    context: ComponentContext,
}

impl NativeComponent for Badge {
    fn widget(&self) -> gtk::Widget {
        self.label.clone().upcast()
    }

    fn set_prop(&mut self, name: &str, value: Option<&JsonValue>) {
        if name == "text" {
            self.label.set_text(value.and_then(|v| v.as_str()).unwrap_or(""));
            self.context.set_size(120.0, 40.0);
        }
    }

    fn command(&mut self, name: &str, args: &JsonValue) {
        // optional
    }
}

fn register(app: &AppView) {
    app.register_component(
        "embed.badge",
        Rc::new(|context: ComponentContext| -> Box<dyn NativeComponent> {
            Box::new(Badge { label: gtk::Label::new(None), context })
        }),
    );
}
```

The widget fills the container NSH lays out; `ComponentContext::emit` and `set_size` (points) work from any thread,
as on iOS. Register before `AppView::load`. A registry belongs to one `AppView` (and the views made from the same
`AppOptions`, whose `components` field it is).

## Registering on Windows (Rust)

On Windows NSH draws every view itself with Direct2D, so a component either draws into its container with Direct2D
(`draw`) or brings a window of its own (`window`: a map control, a third-party view), registered on the
[`AppView`](https://nsh.dev/versions/main/docs/windows.md#embedding-in-a-win32-app) of `nsh-platform-windows`:

```rust
use std::rc::Rc;
use nsh_core::JsonValue;
use nsh_platform_windows::{
    windows::Win32::Graphics::Direct2D::{
        Common::{D2D1_COLOR_F, D2D_RECT_F},
        ID2D1DeviceContext,
    },
    AppView, ComponentContext, NativeComponent,
};

/// A box filled with the color of its `on` prop.
struct Badge {
    on: bool,
    context: ComponentContext,
}

impl NativeComponent for Badge {
    fn draw(&self, dc: &ID2D1DeviceContext, size: (f32, f32)) {
        let color = if self.on {
            D2D1_COLOR_F { r: 0.2, g: 0.7, b: 0.3, a: 1.0 }
        } else {
            D2D1_COLOR_F { r: 0.6, g: 0.6, b: 0.6, a: 1.0 }
        };
        // SAFETY: Direct2D calls on the context nsh draws with.
        unsafe {
            if let Ok(brush) = dc.CreateSolidColorBrush(&color, None) {
                let rect = D2D_RECT_F { left: 0.0, top: 0.0, right: size.0, bottom: size.1 };
                dc.FillRectangle(&rect, &brush);
            }
        }
    }

    fn set_prop(&mut self, name: &str, value: Option<&JsonValue>) {
        if name == "on" {
            self.on = value.and_then(|v| v.as_bool()).unwrap_or(false);
            self.context.set_size(120.0, 40.0);
            self.context.redraw();
        }
    }

    fn command(&mut self, name: &str, args: &JsonValue) {
        // optional
    }
}

fn register(app: &AppView) {
    app.register_component(
        "embed.badge",
        Rc::new(|context: ComponentContext| -> Box<dyn NativeComponent> {
            Box::new(Badge { on: false, context })
        }),
    );
}
```

`draw` runs with every frame of the window, in the view's coordinates (points), clipped to its bounds; call
`ComponentContext::redraw` when what it shows changes. A drawn component is covered, clipped and transformed like any
view, and its container gets the touches. A component that returns a child window from `window` is moved, clipped and
hidden with its view, receives its own input, and sits above everything NSH draws (NSH content over it is hidden, as
with web views). `ComponentContext::emit`, `set_size` (points) and `redraw` work from any thread. Register before
`AppView::load`; a registry belongs to one `AppView` (and the views made from the same `AppOptions`).

A component also takes the mouse wheel and touchpad scrolls over it with `wheel` (an image viewer zooms with them). The
`Wheel` it gets holds the pointer (`x`, `y`, the component's points), the distance in points (`dx`, `dy`, positive
toward the right and down, as scroll views move their content) and in wheel notches (`notches_x`, `notches_y`, with
fractions from precision touchpads and high-resolution wheels), whether it came in fine steps (`precise`) and the
modifiers held (`shift`, `ctrl`, `alt`). It returns `true` for a scroll it took; the scroll views around it scroll with
the rest, and by default with all of them. A scroll a scroll view has begun stays on that view. Ctrl + wheel is also a
precision touchpad's pinch, and Shift + wheel arrives as the wheel sent it (`dy`, with `shift`):

```rust
use nsh_platform_windows::Wheel;

impl NativeComponent for ImageView {
    // draw, set_prop, ...

    fn wheel(&mut self, event: &Wheel) -> bool {
        if !event.ctrl {
            return false; // the scroll views around it scroll
        }
        // √2 per notch, about the pointer.
        let factor = 2f32.powf(-event.notches_y / 2.0);
        self.zoom_about(event.x, event.y, factor);
        self.context.redraw();
        true
    }
}
```

## Registering from the app's crate

An app with a Rust crate of its own (`nsh.json` `"rust"`, [Rust](https://nsh.dev/versions/main/docs/rust.md)) registers native components in that
crate, so they work in the hosts NSH builds for the app: the development host of `nsh run` and `nsh test --target`, and
the app `nsh package` makes. A function with `#[native_components(<platform>)]` at the crate's root (`lib.rs`) registers
them on that platform's `Components`, and the host calls it for every view it makes, as an embedding app registers on
its `AppView`:

```rust
use std::rc::Rc;
use nsh_core::prelude::*;

#[native_components(windows)]
fn components(components: &nsh_platform_windows::Components) {
    use nsh_platform_windows::{ComponentContext, NativeComponent};
    components.register(
        "embed.badge",
        Rc::new(|context: ComponentContext| -> Box<dyn NativeComponent> {
            Box::new(Badge { on: false, context })
        }),
    );
}
```

The platform is `windows`, `macos`, `linux` or `ios`, and the components are those of
`nsh_platform_windows`, `nsh_platform_macos`, `nsh_platform_linux` or `nsh_platform_ios` (the sections above). The
function compiles only on its platform, so a crate has one per platform it supports, each registering the same names,
and depends on each platform's crate for that platform only, at the version and from the source of its other NSH
crates (`nsh-core` and the rest; the CLI checks that they all match):

```toml
[target.'cfg(windows)'.dependencies]
nsh-platform-windows = { version = "0.3", default-features = false }

[target.'cfg(target_os = "macos")'.dependencies]
nsh-platform-macos = { version = "0.3", default-features = false }
```

The host registers the crate's components when it makes each view, before the code holding the view registers its
own: a name registered on the view after that (`AppView::register_component`) replaces the crate's.

## Rules and limits

- **Register before loading.** Factories apply to elements created after the registration. Register every name before
  `loadBundle` / `loadAssetBundle` / `run`, so the first frame finds them.
- **The container owns decoration and touches.** Background, borders, corner radius, shadows, opacity, transforms and
  `overflow: "hidden"` apply to the container NSH draws. Your view fills it and receives the touches that land inside.
- **Capabilities do not apply.** A registered component is the host app's own code; the
  [capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md) an app declares do not restrict what it does. If you embed apps you
  do not trust, only register components that are safe for them to use.
- **Keep the interface to data.** Props, event payloads and command arguments cross as JSON text; send identifiers and
  small values, not large blobs, on every change.
- **One bundle, both platforms.** Register the same names with the same props and events on iOS and Android, so one
  bundle runs on both.
- **Names under `nsh/` are NSH's.** NSH's own components (the system's tab bar of `nsh/mobile`'s `TabBar`) are
  registered under `nsh/`; name yours after your app or company (`embed.badge`), and a registration under `nsh/` logs
  a warning and keeps NSH's.

## See also

- [`nativeComponent` reference](https://nsh.dev/versions/main/modules/nsh.md#nativecomponent-and-nativemodule)
- [Embedding in iOS apps](https://nsh.dev/versions/main/docs/ios.md) and [in Android apps](https://nsh.dev/versions/main/docs/android.md)
- [Architecture](https://nsh.dev/versions/main/docs/architecture.md): how props and events cross threads

Source: https://nsh.dev/versions/main/docs/native-components

---

# Packaging

`nsh package` turns an app into something you can install: a `.app` for the iOS simulator, a signed `.ipa` for iOS
devices, a signed `.apk` for Android, an ad hoc signed `.app` for macOS, a directory and `.tar.gz` for Linux, a directory and `.zip` for Windows, or a static site for the web. It needs no Xcode project and no Gradle.

- **A Rust app** (`nsh.json` names its `"root"`) is packaged from its directory. `nsh` builds the target's runner in
  release mode with your crate compiled in and the root mounted, with no QuickJS: Cargo, the Rust target of the
  platform (`rustup target add …`), and for Android the NDK.
- **A TSX app** names its entry. Its release build (minified, compiled to QuickJS bytecode, exactly as
  `nsh build --release` builds it) goes next to the **prebuilt runtime** that ships with NSH, so it needs no Rust
  toolchain. An app with a crate of its own (`"rust"` without `"root"`) gets runners built with its crate.

```sh
# A Rust app, from its directory
nsh package --target ios-simulator --run     # build, install and launch in the simulator
nsh package --target android --run           # build, install and launch on a device or emulator
nsh package --target macos --run             # build and launch on this Mac
nsh package --target linux --run             # build and launch on this machine
nsh package --target windows --run           # build and launch on this machine
nsh package --target web --run               # build, serve on this machine and open in the browser
nsh package --target ios --sign "Apple Development: Jane Doe (ABCDE12345)" --profile Dev.mobileprovision

# A TSX app: the same with its entry
nsh package App.tsx --target ios-simulator --run
```

Output goes to `.nsh/out/` unless you pass `--out`. The sections below give each target's command for a Rust app; a
TSX app adds its entry (`nsh package App.tsx --target …`).

> [!NOTE]
> To put NSH *inside* an existing native app instead, see [Platforms](https://nsh.dev/versions/main/docs/platforms.md#embed-in-a-native-app), and for a
> GPUI or GPUI Kit app [GPUI](https://nsh.dev/versions/main/docs/gpui.md#embedding-in-a-gpui-app). To ship updates that apps download and verify, see
> [Signed packages](https://nsh.dev/versions/main/docs/signed-packages.md).

## App metadata: `nsh.json`

`nsh package` reads `nsh.json` in the app's directory (next to the entry file of a TSX app). `nsh init` writes one:

```json
{
  "name": "Gallery",
  "id": "com.example.gallery",
  "version": "1.0.0",
  "build": 1,
  "icon": "icon.png"
}
```

| Key | Type | Default | Used for |
|---|---|---|---|
| `name` | string | the entry's directory name | The display name under the icon (`CFBundleDisplayName`, Android `android:label`) and the output file name. |
| `id` | string | required | The bundle identifier / Android package name, in reverse-DNS form under a domain you own. It also names where the app keeps its [storage](https://nsh.dev/versions/main/modules/nsh.md#storage), so each app has its own. `nsh package` and `nsh publish` warn about the `com.example.` placeholder. |
| `version` | string | `"1.0.0"` | The user-visible version (`CFBundleShortVersionString`, `versionName`). |
| `build` | number | `1` | The build number (`CFBundleVersion`, `versionCode`). Raise it for every release you upload. |
| `icon` | string | none | A square PNG, ideally 1024×1024, relative to `nsh.json`. |

`nsh.json` also holds `rust` and `root` (the app's crates and its root component, [Building with Rust](https://nsh.dev/versions/main/docs/rust.md)),
`theme` and `appearance`, `tailwind` (see [Tailwind](https://nsh.dev/versions/main/docs/tailwind.md)) and `capabilities` (see
[Sandbox and capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md)); [Project structure](https://nsh.dev/versions/main/docs/project-structure.md#nshjson) lists
every key. Unknown keys are an error.

Every key above can be overridden on the command line, which is handy in CI:

```sh
nsh package --target android --app-version 1.4.0 --build 42
```

## Options

| Flag | Description |
|---|---|
| `--target <ios \| ios-simulator \| android \| macos \| linux \| windows \| web>` | What to build for (required). |
| `-o, --out <dir>` | Output directory. Default `.nsh/out`. |
| `--name <name>` | Display name. |
| `--id <id>` | Bundle identifier, such as `com.example.app`. |
| `--app-version <version>` | Version, such as `1.2.0`. |
| `--build <n>` | Build number. |
| `--icon <png>` | App icon: a square PNG, ideally 1024×1024. |
| `--sign <identity>` | iOS: the code signing identity for devices. |
| `--profile <file>` | iOS: the provisioning profile for devices (`.mobileprovision`). |
| `--keystore <file>` | Android: a release keystore (default: the debug key). |
| `--key-alias <alias>` | Android: the key alias in the keystore. |
| `--keystore-password <password>` | Android: the keystore password; also read from `NSH_KEYSTORE_PASSWORD`. |
| `--abi <abi>` | Android: the ABIs of the APK, repeated or separated by commas (default: `arm64-v8a` and `armeabi-v7a`). |
| `--run` | Install and launch afterwards: in the iOS simulator, or on the Android device or emulator `adb` sees; macOS, Linux and Windows apps are launched on this machine; a web site is served on this machine and opened in the browser. Not for `--target ios`. |

## iOS simulator

```sh
nsh package --target ios-simulator --run
```

Writes `.nsh/out/<Name>.app`, signed ad hoc (the simulator needs a signature but no identity). With `--run` it boots a
simulator if none is running, installs the app and launches it. Requires Xcode.

## iOS devices

```sh
nsh package --target ios \
  --sign "Apple Distribution: Example Inc (ABCDE12345)" \
  --profile AppStore.mobileprovision
```

Writes `.nsh/out/<Name>.ipa`, ready for TestFlight, App Store upload tools or direct installation (depending on the
profile). What happens:

- The provisioning profile is copied into the app as `embedded.mobileprovision`.
- The entitlements come from the profile. NSH checks that the profile's application identifier covers the app's `id`
  (wildcard profiles such as `TEAMID.*` or `TEAMID.com.example.*` work) and stops with an error otherwise.
- The app is signed with `codesign` using the identity, then zipped into an `.ipa` (`Payload/<Name>.app`).

Find your identities with:

```sh
security find-identity -v -p codesigning
```

Without `--sign` and `--profile`, NSH writes an unsigned `.nsh/out/<Name>.app` and tells you so; it cannot be installed on a
device as it is.

The app supports iPhone and iPad, portrait and landscape (portrait upside down on iPad only), and needs iOS 15.0 or
newer.

## Android

```sh
nsh package --target android --run
```

Writes `.nsh/out/<Name>.apk`. The APK is assembled directly with the SDK's build tools (`aapt2`, `zipalign`, `apksigner`),
without Gradle. Requirements:

- The Android SDK, found through `ANDROID_HOME` (or `ANDROID_SDK_ROOT`, or `~/Library/Android/sdk`), with build tools
  and the `platforms;android-35` package. NSH tells you the `sdkmanager` command when one is missing.
- A JDK, to create the debug keystore the first time.
- For a Rust app, the Android NDK (`sdkmanager "ndk;<version>"`, or `ANDROID_NDK_HOME`), which builds its
  `libnsh.so`.

The app targets API 35 and needs API 28 (Android 9) or newer. It contains native code for the ABIs of phones,
`arm64-v8a` and `armeabi-v7a`; with `--run`, also the device's, such as an emulator's `x86_64`. `--abi` picks them
yourself, for example `--abi arm64-v8a` for 64-bit phones only, the smallest APK:

```sh
nsh package --target android --abi arm64-v8a
```

### Signing for release

Without `--keystore`, the APK is signed with the standard debug key (`~/.android/debug.keystore`, created if missing),
and NSH warns that it is not for store releases. For a release, create a keystore once and pass it:

```sh
keytool -genkeypair -v -keystore release.jks -alias upload -keyalg RSA -keysize 2048 -validity 10000

NSH_KEYSTORE_PASSWORD=… nsh package --target android \
  --keystore release.jks --key-alias upload
```

Prefer the environment variable over `--keystore-password` so the password does not end up in your shell history.

## macOS

```sh
nsh package --target macos --run
```

Writes `.nsh/out/<Name>.app`: the executable in `Contents/MacOS/`, and `nsh/assets/…`, `nsh/app.json` (the window
title and the app's appearance) and a TSX app's `nsh/bundle.nshc` in `Contents/Resources/`. The app is signed ad hoc and needs macOS 14 or
later; to distribute it, sign it with a Developer ID and notarize it. See [macOS](https://nsh.dev/versions/main/docs/macos.md#packaging).

## Linux

```sh
nsh package --target linux --run
```

Writes `.nsh/out/<Name>/` (the executable `<Name>`, `nsh/assets/…`, `nsh/app.json` with the window title and the
application id, a TSX app's `nsh/bundle.nshc`, `<id>.desktop` and the icon `<id>.png`) and the same as
`.nsh/out/<Name>.tar.gz`. Package on
Linux: the runner is built for the machine it is built on. GTK 4 (4.14 or later), Pango and WebKitGTK 6.0 (for web
views) must be installed where the app runs. Installing it and the desktop entry: [Linux](https://nsh.dev/versions/main/docs/linux.md#packaging).

## Windows

```sh
nsh package --target windows --run
```

Writes `.nsh\out\<Name>\` (the executable `<Name>.exe` with the app's icon, `nsh\assets\…`, `nsh\app.json` with the
window title, the app id, the version and the appearance, and a TSX app's `nsh\bundle.nshc`) and the same as
`.nsh\out\<Name>.zip`. A TSX app needs no tools; a Rust app's runner is built with Visual Studio Build Tools. Package on Windows: the runner is built for the machine it is built on, and only Windows can
embed the icon. The app runs from wherever its directory is copied; nothing is installed. See
[Windows](https://nsh.dev/versions/main/docs/windows.md#packaging).

## Web

```sh
nsh package --target web --run
```

Writes `.nsh/out/<Name>/`, a static site: `index.html`, `manifest.webmanifest`, the page script (`nsh.<digest>.js`)
and `nsh.<digest>.wasm` (a Rust app's engine and crate; for a TSX app the runtime, next to the app's ES module
`app.<digest>.js`), its assets and icons, each named after its content
so hosts can cache them for good. Deploy the directory to any web server or CDN; `--run` serves it on
`http://127.0.0.1:4173/` for you to open. Cache headers and embedding: [Web](https://nsh.dev/versions/main/docs/web.md#publish-an-app).

## Icons

Give one square PNG, ideally 1024×1024, in `nsh.json` (`"icon": "icon.png"`) or with `--icon`:

- **iOS:** compiled by Xcode's `actool` into the app's asset catalog (`Assets.car`), which derives every size iOS
  needs.
- **Android:** resized to 192×192 and used as the launcher icon (`mipmap-xxxhdpi`).
- **macOS:** converted by `sips` to `AppIcon.icns`.
- **Linux:** copied as `<id>.png`, which the `.desktop` file names as its `Icon`.
- **Windows:** resized to 16 to 64 pixels and 256 pixels and embedded in the executable as its icon, which the window,
  Explorer and the taskbar show.
- **Web:** resized to 32 pixels (the favicon), 180 (`apple-touch-icon`), 192 and 512 (the web app manifest).

Without an icon, the system shows its default.

## Camera, Bluetooth and other hardware

NSH has no API for the camera, video recording, Bluetooth or location, and `nsh package` cannot make an app that uses
them: NSH writes the app's `Info.plist` and Android manifest, `nsh.json` has no key that adds to them, and a packaged
Android app cannot add Java code. Its own [Rust crate](https://nsh.dev/versions/main/docs/rust.md) does not change this. iOS ends an app that reaches
protected hardware without a usage description in `Info.plist`, and the Android manifest of a packaged app declares
only `INTERNET`.

An app that needs them embeds NSH in its own Xcode or Gradle project ([iOS](https://nsh.dev/versions/main/docs/ios.md#embedding-in-an-ios-app),
[Android](https://nsh.dev/versions/main/docs/android.md#embedding-in-an-android-app)). That project owns `Info.plist` and `AndroidManifest.xml`, so it
declares what it uses there and writes the platform code itself: a camera preview is a
[native component](https://nsh.dev/versions/main/docs/native-components.md), and the app reaches everything else through
[`host.call`](https://nsh.dev/versions/main/docs/ios.md#talking-to-the-app) ([on Android](https://nsh.dev/versions/main/docs/android.md#talking-to-the-app)).

## What is inside

A Rust app's package is its runner, built with your crate and its root mounted, and the assets its crates register
(`assets!()`). A TSX app's package holds its bytecode, its `capabilities.json` (when it declares capabilities) and the
assets it imports, next to the prebuilt runtime:

| Target | Runtime | A TSX app |
|---|---|---|
| iOS | the `nsh-ios-app` executable | `<Name>.app/nsh/bundle.nshc`, `nsh/assets/…` |
| Android | `classes.dex`, `lib/<abi>/libnsh.so` (without symbols, stored uncompressed, 16 KB aligned) | `assets/nsh/bundle.nshc`, `assets/nsh/assets/…` |
| macOS | the `nsh-macos-app` executable, renamed `<Name>` | `<Name>.app/Contents/Resources/nsh/bundle.nshc`, `nsh/assets/…` |
| Linux | the `nsh-linux-app` executable, renamed `<Name>` | `<Name>/nsh/bundle.nshc`, `nsh/assets/…` |
| Windows | the `nsh-windows-app.exe` executable, renamed `<Name>.exe` | `<Name>\nsh\bundle.nshc`, `nsh\assets\…` |
| Web | `nsh.<digest>.wasm`, `nsh.<digest>.js` | `<Name>/app.<digest>.js`, `assets/…`, `index.html` |

A packaged app registers no [native components](https://nsh.dev/versions/main/docs/native-components.md); for those, embed NSH in your own app.

## Finding the runtime

A Rust app builds its own runners. For TSX apps, `nsh package` looks for the prebuilt runtime next to the CLI (`bin/../runtime` in the distribution). In a checkout of
NSH it uses `target/<triple>/<profile>` and `target/android/<profile>`, with the CLI's own profile (a debug CLI uses
debug runtimes): build them with `cargo build -p nsh-ios-app --target aarch64-apple-ios-sim` (or `aarch64-apple-ios`
for devices) and `cargo xtask android` (add `--release` for a release CLI); `nsh-macos-app` (on macOS), `nsh-linux-app` (on Linux) and `nsh-windows-app` (on Windows) are built for this
machine in `target/<profile>` (`cargo build -p nsh-macos-app`, `cargo build -p nsh-linux-app`, `cargo build -p nsh-windows-app`); the web runtime is built with the `web` profile whatever the CLI's, into `target/wasm32-unknown-unknown/web/`. The environment variable `NSH_RUNTIME`
points the CLI at another directory laid out like the distribution's `runtime/` (`ios/iphoneos`,
`ios/iphonesimulator`, `android/release`, `macos`, `linux`, `windows`, `gpui`, `web`, ...).

## See also

- [CLI](https://nsh.dev/versions/main/docs/cli.md): every command
- [Signed packages](https://nsh.dev/versions/main/docs/signed-packages.md): updates apps download
- [Project structure](https://nsh.dev/versions/main/docs/project-structure.md): `nsh.json` and the files of an app
- [Native components](https://nsh.dev/versions/main/docs/native-components.md): views of the host app inside an NSH app

Source: https://nsh.dev/versions/main/docs/packaging

---

# Signed Packages

A signed package (`.nshpkg`) is how a host app runs NSH code it did not ship with: an update to its own NSH screens,
or a third-party mini app. `nsh publish` builds the app and signs it; the host app verifies the signature, the
certificate chain, revocations and the build number before anything runs.

A package holds TSX. The host app's Rust code (an app written in Rust, its crates' components, modules and classes)
is part of the host app itself and is delivered with it, and the TSX of a package imports it by its specifiers, as
any TSX does ([Building with Rust](https://nsh.dev/versions/main/docs/rust.md#extending-a-rust-app-with-tsx)). So a Rust app keeps its core in Rust and
delivers the screens that change often as signed packages.

![Signed packages: an offline root key certifies a release key for app ids; nsh publish signs the package with it; on the device, NshTrust trusts only the root and the newest revocation list, checks the certificate, revocations, signature, app id, file hashes and build number, then runs the module or refuses it.](https://nsh.dev/versions/main/diagrams/signed-packages-light.svg)

> [!NOTE]
> NSH verifies and runs packages; it does not deliver them. Where packages come from (your update server, a CDN, a
> store of mini apps) and when the app downloads them is up to the host app.

## Why packages are signed

The JS a host app runs can reach everything the app [grants](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md), so it must come from
someone the app trusts. There is a second reason: NSH ships apps as QuickJS bytecode, which loads faster than source,
but QuickJS does not validate bytecode, and crafted bytecode can corrupt memory. So NSH loads bytecode only from the
app's own (system-signed) resources, from the dev server the developer connected to, and from verified packages.
Anything else must be JS source.

## Keys: two levels

- A **root key** stays offline. Host apps trust its public key; they can trust several roots, which is how a root is
  rotated.
- A root **certifies release keys**: a certificate names the release key, the app ids it may sign for and a time
  window.
- **Packages are signed by a release key** and carry its certificate. Release keys can therefore be rotated (or
  revoked) without updating the host apps, which only know the root.

Every key has an id derived from its public key (the first 8 bytes of its SHA-256, in hex), printed by every command.

### Create the keys

```sh
nsh keygen keys/root
nsh keygen keys/release
```

```text
key 4e0b637f5e10f6a6: keys/root.secret (keep it secret), keys/root.pub
key 3428d7136788c9ee: keys/release.secret (keep it secret), keys/release.pub
```

Each key is two files: `<name>.secret` (readable by its owner only) and `<name>.pub`, both one line of base64. `nsh
keygen` never overwrites an existing key.

> [!CAUTION]
> Keep `root.secret` offline, for example on an encrypted drive in a safe. Whoever has it can certify keys that every
> host app trusting the root accepts. Release keys belong on the build machine or in CI secrets.

### Certify a release key

```sh
nsh certify --root keys/root.secret --key keys/release.pub --apps 'com.example.*' -o keys/release.cert
```

```text
keys/release.cert: key 3428d7136788c9ee certified by root 4e0b637f5e10f6a6 for com.example.* until 365 days from now
```

| Flag | Description |
|---|---|
| `--root <file>` | The root's secret key. |
| `--key <file>` | The release key's public key. |
| `--apps <pattern>` | App ids it may sign for: `*` (any), `com.example.*` (ids under `com.example.`) or an exact id. Repeatable. |
| `--days <n>` | How long it may sign, from now. Default 365. |
| `-o, --out <file>` | The certificate to write. |

The certificate is a small JSON file; it is not secret.

## Publish a package

```sh
nsh publish App.tsx --key keys/release.secret --cert keys/release.cert
```

```text
.nsh/out/com.example.counter-2.nshpkg: com.example.counter 1.0.0 (build 2), 0 assets, 12 KB, signed by 3428d7136788c9ee, for runtime 0.1.1 or newer
```

`nsh publish` builds the app in release mode and signs it. The app id, name, version and build come from `nsh.json`
next to the entry, overridden by the flags:

| Flag | Description |
|---|---|
| `--key <file>` | The release key's secret key. |
| `--cert <file>` | Its certificate. |
| `-o, --out <file>` | The package to write. Default `.nsh/out/<id>-<build>.nshpkg`. |
| `--id <id>` | App id, such as `com.example.app`. |
| `--app-version <version>` | Version, such as `1.2.0`. |
| `--build <n>` | Build number. Required (here or in `nsh.json`); it must grow with every release. |
| `--source-map <where>` | `package` (the default): in the package. `file`: in `<package>.map` next to it, not in the package. `none`: left out. See [Errors from published packages](#errors-from-published-packages). |
| `--strip-debug` | Leave the line and column tables out of the bytecode: a smaller package whose error stacks have no positions. |
| `--min-runtime <version>` | The lowest runtime that runs the package, such as `0.2.0` (`nsh.json` `minRuntime`). Default: this CLI's version. See [Which runtimes run a package](#which-runtimes-run-a-package). |

`nsh publish` refuses to sign what a device would refuse: the certificate must cover the app id and the current time.

```text
error the release key's certificate does not cover this package: it does not cover app `com.example.counter` (only com.other.app)
```

### Which runtimes run a package

A package names the lowest NSH runtime that runs it, and host apps with an older runtime refuse it before anything
runs:

```text
error the package needs runtime 0.2.0 or newer; this runtime is 0.1.1
```

By default this is the version of the CLI that built the package: the bundle is compiled against that CLI's modules,
so that runtime is the one known to run it. When host apps in the field have an older runtime and the app uses only
what that runtime has, publish for it with `--min-runtime` (or `minRuntime` in `nsh.json`):

```sh
nsh publish App.tsx --key keys/release.secret --cert keys/release.cert --min-runtime 0.1.0
```

The version is `MAJOR.MINOR.PATCH`; a pre-release suffix (`0.2.0-beta.1`) counts as its version without it. It cannot
be newer than the CLI. Try the package on a host app with that runtime before you upload it: an import or a function
the older runtime lacks fails when the module loads.

### What a package holds

A package is one file: a JSON header (app id, name, version, build, the declared capabilities, the bytecode version,
the minimum runtime, the signing time, the release key's certificate and a table of files with their SHA-256), then
the files, then the release key's Ed25519 signature over everything before it. The files are:

- the app's JS source (always),
- its bytecode, used only when the device's runtime has the same bytecode version (otherwise the source runs, so a
  package keeps working on newer runtimes),
- its source map (unless it was published with `--source-map file` or `none`),
- the assets it imports (images, fonts).

The package's identity, used for revocation, is the SHA-256 of the whole file.

### Packages from newer versions of NSH

A host app runs packages that a newer `nsh publish` signed, as long as its runtime is at least the package's [minimum
runtime](#which-runtimes-run-a-package). What a newer version adds and the host's runtime does not know is left out, and never widens what the
package may do:

- header fields and files it does not know are ignored (they are still covered by the signature and their hashes),
  unless the package marks a field as one its runtime must understand: then older runtimes refuse it;
- [capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md) it does not know are not granted, and a capability or `http` grant
  with a key it does not know is dropped as a whole, since that key may restrict it.

What was left out is logged when the package loads.

## Sign a package again

A platform that distributes the packages of several apps can sign them all with one key of its own: CI builds each
package and signs it with a key its test apps trust, and the platform signs it again with the key the production apps
trust.

```sh
nsh publish ci/com.example.counter-2.nshpkg --key keys/platform.secret --cert keys/platform.cert -o com.example.counter-2.nshpkg
```

```text
com.example.counter-2.nshpkg: com.example.counter 1.0.0 (build 2), signed again by d0eb0d3cb453b71b, for runtime 0.3.0 or newer
```

| Flag | Description |
|---|---|
| `--key <file>` | The release key's secret key. |
| `--cert <file>` | Its certificate. |
| `-o, --out <file>` | The package to write. It may be the package read. Default: `.nsh/out/<id>-<build>.nshpkg`. |

The package keeps everything CI put in it: the files, the app id, version and build, the declared capabilities, the
[minimum runtime](#which-runtimes-run-a-package) and what a [newer version of NSH](#packages-from-newer-versions-of-nsh)
wrote. The certificate, the signing time and the signature become the new key's, so the package has a SHA-256 of its
own, the one to [revoke](#revoke-keys-and-packages) it by.

Before it signs, `nsh publish` checks that the package is intact (signed by the key its certificate names, its file
table covering the data, every file matching its hash) and that the new certificate covers the app id and the current
time. From then on the new signature vouches for the package, its bytecode included, so a platform signs again the
packages its own builds made. Rust tools sign again with `nsh_package::resign(&bytes, &key, &certificate)`.

## Verify a package

`nsh verify` checks a package exactly as a host app trusting the given roots would:

```sh
nsh verify .nsh/out/com.example.counter-2.nshpkg --root keys/root.pub
```

```text
valid: com.example.counter 1.0.0 (build 2), release key 3428d7136788c9ee, sha256 f40565358c13fafce369792e41125fea7f93fe87dd1bc24fd575dabc09b34fd4, 0 assets, bytecode for this runtime
```

| Flag | Description |
|---|---|
| `--root <file>` | A trusted root's public key. Repeatable. Without any, only the package's own signature is checked. |
| `--revocations <file>` | A revocation list to apply first. |

A device checks, in order:

1. the certificate's signature by a trusted root;
2. that the release key is not revoked;
3. the package's signature by the release key;
4. that the certificate covers the app id and the signing time;
5. the minimum runtime the package needs;
6. that the file table covers the data exactly and each file matches its hash;
7. that the package itself is not revoked;
8. that its build is not older than the highest build of that app accepted before (rollback protection).

A refused package raises an error that says which check failed; the app that was running keeps running.

## Revoke keys and packages

A root signs **revocation lists**: release keys and packages that must not load any more.

```sh
# The first list.
nsh revoke --root keys/root.secret --sequence 1 \
  --package f40565358c13fafce369792e41125fea7f93fe87dd1bc24fd575dabc09b34fd4 -o revocations.json

# Later: keep everything in the last list and add a release key (sequence becomes 2).
nsh revoke --root keys/root.secret --extend revocations.json --key 3428d7136788c9ee -o revocations-2.json
```

| Flag | Description |
|---|---|
| `--root <file>` | The root's secret key. |
| `--extend <file>` | Keep the entries of this list (the last one published). |
| `--sequence <n>` | The list's number, higher than any published before. With `--extend`, defaults to that list's plus one. |
| `--key <id>` | A release key id to revoke. Repeatable. |
| `--package <sha256>` | A package's SHA-256 (as `nsh verify` prints it) to revoke. Repeatable. |
| `-o, --out <file>` | The list to write. |

A trust store only accepts a list with a higher sequence number than the one it has, so an old list cannot be
replayed to un-revoke something. Publish the newest list where your apps fetch it, and apply it with
`updateRevocations` before opening packages.

## Rollback protection

When a host app accepts a package, its trust store records the build number for that app id and from then on refuses
older builds. An attacker who obtained an older, signed package with a known vulnerability cannot make the app run it.
The record persists in the store's state directory (`nsh-trust.json`), so it survives restarts. On GPUI a host app may
record it later, once the new package proved healthy (`verify_package`, then `accept_package`; see below).

## Loading packages in a host app

Verification hashes the whole package and extracts its assets (once per package, under the trust store's directory),
so it runs off the UI thread; running the result happens on it.

**GPUI (Rust)**, where the host app can also accept a package only once it proved healthy:

```rust
use nsh_platform_gpui::{accept_package, package::{PublicKey, TrustStore}, verify_package};

let mut trust = TrustStore::open(state_dir)?;
trust.add_root(PublicKey::from_base64(ROOT_PUB)?);

// Off the main thread: verified as strictly as ever, but the build is not recorded yet.
let package = verify_package(&trust, &bytes, &packages_dir)?;
view.read(cx).run_package(&package);
// Later, once its first frame showed and no fatal error came for a while:
accept_package(&mut trust, &package)?;
```

**iOS (Swift)**:

```swift
let trust = try NshTrust(stateDirectory: applicationSupport.appendingPathComponent("nsh"))
try trust.addRoot(rootPublicKey)                // the contents of root.pub
try trust.updateRevocations(latestListJSON)     // when you have one

let info = try await app.loadPackage(at: downloaded, trust: trust)   // verify off the main thread, then run
```

**Android (Java)**:

```java
NshTrust trust = new NshTrust(new File(getFilesDir(), "nsh"));
trust.addRoot(rootPublicKey);
trust.updateRevocations(latestListJson);

NshPackage pkg = trust.openPackage(downloaded);   // off the UI thread; throws NshPackage.RefusedException
runOnUiThread(() -> nsh.runPackage(pkg));
```

Until a package is accepted, the build accepted before still verifies, so a host app whose new package fails can go
back to the one it ran (`AppView::on_error`'s fatal errors, or a crash before accepting, are the signals). Builds
older than the accepted one stay refused, and a package revoked in between is not accepted. `load_package` verifies and
accepts at once, as `openPackage` does on iOS and Android.

The package's declared [capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md) travel with it: a package can do only what it
declares, and only what the host app grants on top.

Full API: [GPUI](https://nsh.dev/versions/main/docs/gpui.md#embedding-in-a-gpui-app), [Embedding in iOS apps](https://nsh.dev/versions/main/docs/ios.md#signed-packages),
[Embedding in Android apps](https://nsh.dev/versions/main/docs/android.md#signed-packages).

## Errors from published packages

The bytecode of a package keeps its line and column tables, so its errors have positions, and the runtime maps them
to your sources with the package's source map before it hands them to the host app's error handler:

```text
Error: boom
    at n (App.tsx:5:3)
```

The source map holds your app's original sources and is often the largest file in a package: about half of the
gallery example's 2.6 MB. To keep it to yourself, publish it next to the package instead:

```sh
nsh publish App.tsx --key keys/release.secret --cert keys/release.cert --source-map file
```

```text
✓ wrote the source map to .nsh/out/com.example.counter-2.nshpkg.map (6.1 KB)
```

Devices then report the bundle's positions (`at n (bundle.js:1:80)`). Keep the map with the package it belongs to,
and map what the host app reported with `nsh symbolicate`:

```sh
nsh symbolicate .nsh/out/com.example.counter-2.nshpkg.map report.txt
```

```text
Error: boom
    at n (App.tsx:5:3)
```

`nsh symbolicate` reads the error text from a file or standard input and takes a map file or a package that holds
one. The line tables add about a fifth to the bytecode (3–5% of a package with its map); `--strip-debug` leaves them
out, and stacks then read `at n (<null>:0:1)`, with nothing to map.

## Trying a package in development

The development hosts that `nsh run` installs can run a package the way an embedding app would.

On iOS, the host executable takes `--package <file>` and one or more `--root <root.pub>`. After `nsh run` has
installed the host in the simulator (`--target ios`):

```sh
xcrun simctl launch booted com.longbridge.nsh.host \
  --package "$PWD/.nsh/out/com.example.counter-2.nshpkg" --root "$PWD/keys/root.pub"
```

On Android, the development host (`DevActivity`, installed by `nsh run --target android`) takes the extras `package`
(a path on the device) and `root` (base64 public keys, comma-separated):

```sh
adb push .nsh/out/com.example.counter-2.nshpkg /sdcard/Android/data/com.longbridge.nsh.host/files/app.nshpkg
adb shell am start -S -n com.longbridge.nsh.host/com.longbridge.nsh.DevActivity \
  --es package /sdcard/Android/data/com.longbridge.nsh.host/files/app.nshpkg \
  --es root "$(cat keys/root.pub)"
```

Their trust state lives in the temporary (iOS) or cache (Android) directory, so builds older than one they accepted are
refused there too.

## A release checklist

1. Keep the root key offline; certify a release key per team or per app family, for a year or less.
2. Raise `build` in `nsh.json` for every release; `nsh publish` refuses a package without one.
3. Run `nsh verify --root root.pub` on the package before uploading it.
4. Ship `root.pub` inside the host app; ship revocation lists separately, so you can revoke without an app update.
5. If a release key leaks, revoke it (`nsh revoke --extend … --key <id>`), certify a new one and publish again.
6. With a platform that signs for its apps, give CI a root of its own that only the test apps trust, and ship the
   platform's root in the production apps; the platform signs CI's packages again (`nsh publish <package>`).

## See also

- [Sandbox and capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md)
- [Embedding in iOS apps](https://nsh.dev/versions/main/docs/ios.md), [Embedding in Android apps](https://nsh.dev/versions/main/docs/android.md)
- [CLI](https://nsh.dev/versions/main/docs/cli.md)

Source: https://nsh.dev/versions/main/docs/signed-packages

---

# App Updates

`nsh/updater` lets a packaged app check for a newer version, download it and replace itself. The UI is yours: the module
gives you the state and the actions. It updates the whole app; to deliver only NSH screens to a host app, see
[Signed Packages](/docs/signed-packages).

| Platform | What it does |
| --- | --- |
| macOS, Windows, Linux | Checks, downloads, replaces the app and restarts it |
| iOS, Android | Checks, and gives you the link to send the user to |
| Web | Nothing to do: a deploy updates the app, `checkForUpdate` resolves `null` |

## Set the source

From GitHub Releases, in `nsh.json`:

```json
{ "version": "1.2.0", "updater": { "github": "owner/repo" } }
```

From your own host, which needs a signing key, because whoever controls the host would otherwise control what your app
runs (`nsh keygen keys/update`, keep the `.secret` out of your repository):

```json
{
  "version": "1.2.0",
  "updater": {
    "url": "https://dl.example.com/app/latest.json",
    "publicKey": "<contents of keys/update.pub>"
  }
}
```

`publicKey` also works with `github`: unsigned manifests are then refused.

## Use it

```tsx
import { checkForUpdate, downloadUpdate, installAndRestart } from "nsh/updater";
import { openUrl } from "nsh";

const update = await checkForUpdate(); // null when up to date
if (update?.canInstall) {
  await downloadUpdate(({ received, total }) => setProgress(received / (total ?? 1)));
  await installAndRestart();
} else if (update) {
  await openUrl(update.url);
}
```

`update` has `version`, `notes`, `url` and `canInstall`. `canInstall` is false on iOS and Android, and on the desktop when
the app is installed where the user cannot write, such as by a system package. In a development run `checkForUpdate`
resolves `null`.

`installAndRestart` exits this run, so save what you need first. If it fails, the app stays as it was.

## Publish a release

`version` in `nsh.json` must be [semver](https://semver.org) and grow with each release. With `"updater"` set,
`nsh package` also writes an archive named for its platform. Package on each platform, then write the manifest:

```sh
nsh package --target linux   # My-App-1.3.0-linux-x86_64.tar.gz
nsh package --target macos   # My-App-1.3.0-macos-aarch64.tar.gz
nsh package --target windows # My-App-1.3.0-windows-x86_64.zip

nsh update-manifest *.tar.gz *.zip \
  --notes CHANGES.md \
  --key keys/update.secret \
  --link ios=https://apps.apple.com/app/id000000000
```

Upload the archives, `latest.json` and `latest.json.sig` (with `--key`) as assets of the GitHub Release, or to your host
next to each other. A release marked as a draft or prerelease on GitHub is not offered.

## What is checked

- The manifest's signature, when there is a `publicKey`.
- The manifest's app id: it must be this app's.
- The version: only a newer one is offered, so an old manifest cannot downgrade the app.
- URLs: HTTPS only (plain HTTP only to this machine, for local tests).
- The archive's size and SHA-256.
- The new app: its id and executable, and on macOS its code signature.
- That this run is the package itself: an NSH module running inside another app cannot replace it.

On macOS, `nsh package` signs ad hoc, which is fine to test, but Gatekeeper may stop it on other Macs. To distribute, sign
the `.app` with your Developer ID, notarize it, and archive it again under the same name (`tar -czf <archive> <Name>.app`)
before `nsh update-manifest`.

## Rust apps

A native Rust app uses `nsh-updater` directly and supplies its own HTTP transport.
Use `Config::check` to verify the manifest and `Download` to verify the archive.
Then call `Installation::install_and_launch` and exit only if it succeeds; this
keeps the old installation until the new process can be launched and rolls back
on launch failure. Calling `install` followed by `launch` separately does not
provide that rollback. This detects launch errors, not a crash after a process
has already started.

The `Config`, `Manifest`, `Asset` and `Available` records are non-exhaustive.
Construct them with `Default::default()` and assign the fields you need.

Source: https://nsh.dev/versions/main/docs/app-updates

---

# Sandbox and Capabilities

An app written in Rust is native code compiled into the app that ships it, as the rest of that app is, and runs with
its trust; its calls into NSH's services (`fetch`, images, web views, the status bar) go through the same native
checks as TSX's, under what a host grants. The TSX and JavaScript an app runs, its own or a [signed
package](https://nsh.dev/versions/main/docs/signed-packages.md) it downloads, run in a QuickJS VM per view, and everything they can do outside that VM
goes through NSH's native runtime. That makes it possible to run code you did not write, such as third-party mini apps
or downloaded updates, under rules the host app controls:

- **Limits** bound the memory, time and native resources one app can use.
- **Hardening** removes the ways to turn strings into code in release builds.
- **Capabilities** list what an app may reach: which hosts it may fetch from, which pages a web view may show, whether
  it may change the status bar. The app declares them; a host app may grant less.

A bundle holds only the app's code: the reactive graph, the renderer and every module the app imports are native. So
nothing in JS is trusted, and every limit and check is enforced in Rust; there is no JS code an app could patch to get
around them.

## Limits

Limits bound a VM: they apply to TSX and JavaScript. An app embedded in another app runs within limits its host app decides. An app on its own (packaged with
`nsh package`, the web included, or run with `nsh run`) is your own code, as a native app is: it uses the memory and
time the device gives it, and its interpreter stack of 4096 KB turns deep recursion into a `RangeError` the app can
catch.

An embedded app has these limits:

| Limit | Default | When it is hit |
|---|---|---|
| JS heap | 256 MB | The VM stops. |
| Interpreter stack | 4096 KB (also the maximum) | Deep recursion throws a `RangeError`, which the app can catch. |
| Time to evaluate the bundle | 10 s | The evaluation is cut off. |
| Time of any other call into JS | 2 s | The call is cut off; the app goes on. |
| Nodes kept | 200 000 | The VM stops. |
| Changes at once (queued operations) | 8 000 000 values | The VM stops. |
| Operations in one canvas drawing | 1 000 000 | The VM stops. |

**Time is budgeted per call, not per app.** A "call" is one thing the runtime asks JS to do: handle one event
(including the rendering it causes), bind one list row, run one timer, run one frame's `requestAnimationFrame`
callbacks, drain the microtask queue. A long-running app never accumulates time toward a limit; only a single call
that does not return in time is interrupted. Calls nested inside another share the outer call's budget.

An interrupted call ends with an exception that no `catch` can swallow, and the error is reported with the budget it
exceeded:

```text
the script was interrupted: a call into JS exceeded its budget of 2000 ms
```

The VM keeps running: the next event, timer or frame runs normally.

**Running out of memory or going over a quota stops the VM.** The error is reported once (to the host app's error
handler, and in development builds over the app), no JS runs after that, and the views stay as they were. The node
and operation quotas exist because native views and queued changes live in native memory, which the JS heap limit does
not cover: without them, an app could exhaust the device's memory through the UI.

> [!TIP]
> These limits are generous for normal apps. If you hit the 2 s call budget, the work is too long for one event
> anyway: it would freeze the app's updates for that long. Split it with `setTimeout`, or move it out of the event
> handler.

Host apps set the limits per view: `NshAppView.limits` on [iOS](https://nsh.dev/versions/main/docs/ios.md#limits),
`NshView.setLimits` on [Android](https://nsh.dev/versions/main/docs/android.md#limits), `AppOptions::limits` / `AppView::set_limits` in a
[GPUI app](https://nsh.dev/versions/main/docs/gpui.md#embedding-in-a-gpui-app). They apply from the next load.

To see in development what a TSX app does within a host app's limits, run it with
[`--limits`](https://nsh.dev/versions/main/docs/cli.md#nsh-run): `nsh run App.tsx --limits` uses the defaults above, and
`nsh run --limits memory=128MB,call=500ms` sets those two as a host app would, the rest keeping their defaults.

## Hardening

Release builds (everything not loaded from a dev server) are hardened when they load:

- `eval` is removed, and the `Function`, `AsyncFunction`, `GeneratorFunction` and `AsyncGeneratorFunction`
  constructors throw. NSH runs no code made from strings:

  ```text
  TypeError: the Function constructor is disabled: nsh runs no code from strings (development builds allow it)
  ```

- The prototypes all modules share (`Object`, `Array`, `Function`, `String`, `Number`, `Promise`, `Map`, typed arrays
  and the rest) are frozen, so one module (or one library) cannot change `Array.prototype` for everyone else.
  `Error.prototype` stays writable, so error subclasses can set `this.name`.

Freezing prototypes would normally break a common pattern, the "override mistake": assigning
`Sub.prototype.constructor = Sub` or `obj.toString = …` throws when the inherited property is frozen. NSH turns the
commonly overridden members (`constructor`, `toString`, `valueOf`, `toJSON`, ...) into accessors whose setter defines
the property on the object assigned to, so such code (and libraries like axios that use it) keeps working.

Bundles served by `nsh dev` / `nsh run` (with or without `--release`) are not hardened, so you can debug with `eval`. Test the release
behavior with `nsh test` (which hardens) or a packaged build before shipping code that relies on dynamic code.

## Capabilities

An app declares what it may reach outside its VM in `nsh.json`:

```json
{
  "name": "Quotes",
  "id": "com.example.quotes",
  "version": "1.0.0",
  "build": 3,
  "capabilities": {
    "network": {
      "hosts": ["api.example.com", "*.cdn.example.com"],
      "http": [{ "host": "quotes.example.com", "methods": ["GET"], "pathPrefix": "/v1/" }],
      "sockets": ["feed.example.com:7000"]
    },
    "webview": { "hosts": ["*.example.com"], "input": true },
    "statusBar": true,
    "clipboard": true,
    "picker": true,
    "speech": true,
    "notifications": true,
    "host": ["getUserInfo", "bridge.*"],
    "openUrl": { "schemes": ["https", "mailto"] }
  }
}
```

**An app without `"capabilities"` may do everything**: a standalone app is its developer's own, and nothing is
restricted. Raw TCP sockets are granted by name in every app, through `network.sockets`, and the host's functions
through `host`. **An app with `"capabilities"` may do only what it lists**: everything else is denied. Unknown keys are
build errors, so a typo is caught when you build instead of becoming a missing permission at runtime. A [signed
package](https://nsh.dev/versions/main/docs/signed-packages.md#packages-from-newer-versions-of-nsh) from a newer NSH may declare capabilities an older
runtime does not know: they are not granted there.

### `network`

Covers `fetch` (including every redirect), WebSockets, remote images (`<Image>`, `placeholder`, canvas images,
`Image.getSize` / `Image.prefetch`), video sources and raw TCP sockets (`net.connect`).

| Key | Type | Description |
|---|---|---|
| `hosts` | `string[]` | Hosts the app may reach with any method and scheme (`http`, `https`, `ws`, `wss`). |
| `http` | `object[]` | Finer grants: a host, narrowed by any of the keys below. |
| `http[].host` | `string` | The host or host pattern (required). |
| `http[].methods` | `string[]` | Allowed methods, such as `["GET", "HEAD"]`. Missing: any. |
| `http[].schemes` | `string[]` | Allowed schemes (`scheme`: one, as a string). Missing: any of `http`, `https`, `ws`, `wss`. |
| `http[].port` | `number` | The port; a URL without one has its scheme's default (443 for `https`). Missing: any. |
| `http[].paths` | `string[]` | Exact paths, such as `["/v1/quote"]` (the query is not part of the path). |
| `http[].pathPrefixes` | `string[]` | Path prefixes covering whole segments: `/v1` covers `/v1` and `/v1/quote`, `/v1/` what follows it. `pathPrefix` (one, as a string) and `path_prefixes` read the same. |
| `sockets` | `string[]` | Raw TCP destinations for [`net.connect`](https://nsh.dev/versions/main/modules/standard-modules.md), each an exact `"host:port"` (`"[::1]:9000"` for IPv6). |

An `http` rule covers every path when it lists no `paths` or `pathPrefixes`, and with both a path matching either.

Host patterns are `*` (any host), `*.example.com` (any subdomain of `example.com`, not `example.com` itself) or an
exact host name. Matching ignores case and the port. The host is taken after the last `@`, so
`https://api.example.com@evil.io/` is checked as `evil.io`.

A WebSocket handshake is an HTTP GET: `ws://` is checked as `http://` and `wss://` as `https://`, so the hosts and
`http` grants that allow a GET of the URL allow the WebSocket. A raw socket reaches past every HTTP rule, so
`sockets` lists each host and port exactly, and only `sockets` grants them.

`asset:` URIs (the app's own files) are always allowed; images and videos may also use `data:` URIs and relative
paths.

### `webview`

| Key | Type | Description |
|---|---|---|
| `hosts` | `string[]` | Hosts a [web view](https://nsh.dev/versions/main/docs/web-view-and-video.md) may show and navigate to (`http` and `https`). Without `webview`, the app may not show web pages at all. |
| `input` | `boolean` | A web view's ref may give its page trusted input ([`sendInput`](https://nsh.dev/versions/main/docs/web-view-and-video.md#input-as-the-users-own)). Never granted unless declared, also for an app without `"capabilities"`. |

Top-level navigations inside the web view are checked too, by the platform's navigation delegate, before they load.
The page's own subresources (its scripts, images, XHRs) are the web content's business and are not checked.
`about:blank` and inline HTML (`html`) need only web views to be granted at all: `"webview": { "hosts": [] }`
allows them without allowing any remote page.

`input` is separate from `hosts` because trusted input carries user activation, which `injectJavaScript` never gets:
the page may then open windows, write the clipboard, open the system's file panel, start WebAuthn or permission prompts
and press any button that checks `isTrusted`. Without it the core drops `sendInput` and logs which key to add.

### `statusBar`

`"statusBar": true` lets the app change the status bar (the `statusBar` of pages and dialogs in
[`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md#status-bar), and `nsh.json`'s `"statusBar"` default).

### `clipboard`

`"clipboard": true` lets the app read and write the system clipboard ([`Clipboard`](https://nsh.dev/versions/main/modules/nsh.md#clipboard)). Copying from a selectable text's edit menu is the user's own act and needs no capability.

### `picker`

`"picker": true` lets the app show the system's picker for photos ([`Picker`](https://nsh.dev/versions/main/modules/nsh.md#picker)): the user
picks what reaches the app.

### `speech`

`"speech": true` lets the app recognize what the user says ([`Speech`](https://nsh.dev/versions/main/modules/nsh.md#speech)): the microphone and
the system's speech recognizer, whose transcript reaches the app. The system still asks the user once.

### `notifications`

`"notifications": true` lets the app show system notifications and set its icon's badge
([`Notifications`](https://nsh.dev/versions/main/modules/nsh.md#notifications)). The system still asks the user once, where it asks.

### `openUrl`

Lets the app open URLs outside it ([`openUrl`](https://nsh.dev/versions/main/modules/nsh.md#openurl), a `TextView`'s links with
`links="open"`): `"openUrl": true` for every scheme, `"openUrl": { "schemes": ["https", "mailto"] }` for the schemes
listed. A URL whose scheme is not granted rejects with `ERR_ACCESS_DENIED` (`permission` `"openUrl"`, `resource` the
URL). URLs that would run code or reach the app's own data
(`javascript:`, `data:`, `file:`, ...) are never opened, whatever the capability.

### Storage

Every app may keep its own data on the device with [`Storage`](https://nsh.dev/versions/main/modules/nsh.md#storage), with no capability: the storage holds only that app's data, and the embedding app decides where it is kept.

### `host`

`host` lists the functions of the app embedding NSH that `nsh`'s `host.call(name, args)` may call: exact names
(`"getUserInfo"`) or prefixes ending in `*` (`"bridge.*"` matches `bridge.call` and `bridge.share`). `"host": true`
allows every function. A function not listed is refused, also in an app without `"capabilities"`: the host's
functions are never granted by default, and building an app that imports `host` from `nsh` without `host` warns that every
call will be refused. Names are 1 to 128 characters from `A`–`Z`, `a`–`z`, `0`–`9`, `_`, `.`, `:` and `-`, without `..`;
the call of any other name is refused before the grants are read. End a prefix with a separator (`"bridge.*"`):
`"bridge*"` matches `bridgeAdmin` too. The host's events (`host.on(event, listener)`) reach the app's listeners as the host sends them.

```ts
import { host } from "nsh";

if (host.available()) {
  const user = await host.call("getUserInfo");
  const stop = host.on("loginChanged", (payload) => console.log(payload));
  stop();
}
```

`host.available()` is true on platforms that embed a host; elsewhere `host.call` rejects with `code`
`"ERR_FEATURE_UNAVAILABLE_ON_PLATFORM"`.

### What a refusal looks like

| Request | Result |
|---|---|
| `fetch` | The promise rejects with a `TypeError`, as every failed request, whose `code` is `ERR_ACCESS_DENIED`, `permission` `"network"` and `resource` the URL (the request's, or the redirect's); the request never reaches the network. |
| `Image.getSize`, `Image.prefetch` | The promise rejects with `ERR_ACCESS_DENIED`, `permission` `"network"` and `resource` the URL; the image is never requested. |
| Remote image, video source, web view source or `html` | Nothing is shown, and the element's `onError` reports it with `code` `"ERR_ACCESS_DENIED"`. A web view's navigation to a host not granted is cancelled and reported the same way. |
| Status bar change, canvas image | Nothing changes or is drawn; the refusal is logged. |
| Clipboard | Every function of `Clipboard` rejects with `ERR_ACCESS_DENIED`, `permission` `"clipboard"` and `resource` `""`; the system clipboard is never touched. |
| Picker | `pickImages` shows nothing and rejects with `ERR_ACCESS_DENIED`, `permission` `"picker"` and `resource` `""`. |
| Speech | `Speech.start` throws `ERR_ACCESS_DENIED`, `permission` `"speech"` and `resource` `""`; the microphone stays off. |
| Notifications | Each function of `Notifications` rejects or throws `ERR_ACCESS_DENIED`, `permission` `"notifications"` and `resource` `""`; nothing shows. |
| `openUrl` | The promise rejects with `ERR_ACCESS_DENIED`, `permission` `"openUrl"` and `resource` the URL; nothing opens. |
| Host call | `host.call` rejects with `ERR_ACCESS_DENIED`, `permission` `"host"` and `resource` the function's name (`host.post` throws it); the call never reaches the host. |
| Files (`fs/promises`) | The promise rejects with `ERR_ACCESS_DENIED`, `permission` `"fs"` and `resource` the path; the disk is never touched. |
| Processes (`process`) | `run` rejects, and `spawn` and `exit` throw, with `ERR_ACCESS_DENIED`, `permission` `"process"` and `resource` the command (`"exit"` for `exit`); no child starts. |
| TCP socket (`net.connect`) | The promise rejects with `ERR_ACCESS_DENIED`, `permission` `"network"` and `resource` the `"host:port"`, before any DNS lookup. |
| WebSocket | The `websocket` module's `connect` rejects with `ERR_ACCESS_DENIED`, `permission` `"network"` and `resource` the URL; the global `WebSocket` fires `error` and then `close` (code 1006), as a connection that fails does. |

The errors of the [standard modules](https://nsh.dev/versions/main/modules/standard-modules.md#failures) carry `code` `"ERR_ACCESS_DENIED"`, so an
app tells a refusal apart from a failed operation, and their `permission` and `resource` name the capability and what
was asked for. The modules of [`nsh`](https://nsh.dev/versions/main/modules/nsh.md) refuse the same way: their promises reject with
`ERR_ACCESS_DENIED`, `permission` and `resource` (`fetch` with a `TypeError`, the class of every failed request).

```ts
import { Clipboard } from "nsh";

try {
  await Clipboard.writeText(link);
} catch (error) {
  if (error.code !== "ERR_ACCESS_DENIED") throw error;
  console.warn(`${error.permission} is not granted`); // "clipboard"
}
```

Rust components get the same refusals in Rust's terms: a refused clipboard read answers what an empty clipboard does, a
refused pick no files, a refused `open_url` `false` and a refused `fetch` an `Err` with the message.

Each refusal is logged once, saying which key to add:

```text
fetch GET https://evil.example.org/x is not granted: add `evil.example.org` to capabilities.network in nsh.json
```

Redirects are followed by NSH, not by the platform's HTTP stack, so every hop is checked against the capabilities. (A
streamed request body is not sent twice, so a `307` / `308` redirect of a streamed upload fails.)

### Where capabilities travel

The declaration goes with the app wherever it goes:

- `nsh build` and `nsh package` write it next to the bundle as `capabilities.json`;
- `nsh publish` puts it in the [signed package](https://nsh.dev/versions/main/docs/signed-packages.md) header, covered by the signature;
- `nsh dev` sends it with every build, so development enforces the same rules. Changing `capabilities` reloads the app
  instead of hot-patching it.

## Grants: what a host app allows

A host app that embeds NSH can grant **at most** some capabilities, in the same JSON form:

```rust
// iOS, in Rust (nsh_platform_ios::AppView)
let grant = nsh_engine::Capabilities::from_json(&serde_json::json!({
    "network": { "hosts": ["api.example.com"] }
}))?;
app.set_granted_capabilities(Some(grant));
```

```swift
// iOS
try app.grantCapabilities(#"{ "network": { "hosts": ["api.example.com"] } }"#)
```

```java
// Android
nsh.setGrantedCapabilities("{ \"network\": { \"hosts\": [\"api.example.com\"] } }");
```

A request must be allowed by **both** the app's declaration and the host's grant. With the grant above, an app that
declares `"hosts": ["*"]` can still only reach `api.example.com`, and cannot show web pages or change the status bar.
Without a grant (`nil` / `null`, the default), what each app declares applies.

Grants apply from the next load. A typical setup for third-party mini apps: grant each one only its own API host, run
it from a [signed package](https://nsh.dev/versions/main/docs/signed-packages.md) whose declaration you reviewed, and keep the default limits or lower
them.

> [!WARNING]
> [Native components](https://nsh.dev/versions/main/docs/native-components.md) the host app registers are the host's own code: capabilities do not
> apply to them. Register only components that are safe for every app the view may run.

## Summary

| Layer | Enforced by | Set by |
|---|---|---|
| Limits (heap, stack, time, nodes) | the runtime, per VM | the host app per view (embedded apps) |
| Hardening | the runtime, on load | always on outside development |
| Capabilities | the runtime (fetch, images, video, web views, status bar, files, processes, sockets) | the app (`nsh.json`) and the host app (grant) |
| Code integrity | signature verification | `nsh publish`; the host app's trusted roots |

## See also

- [Signed packages](https://nsh.dev/versions/main/docs/signed-packages.md)
- [Networking](https://nsh.dev/versions/main/docs/networking.md)
- [Embedding in iOS apps](https://nsh.dev/versions/main/docs/ios.md), [Embedding in Android apps](https://nsh.dev/versions/main/docs/android.md)

Source: https://nsh.dev/versions/main/docs/sandbox-and-capabilities

---

# Backward Compatibility

Host apps download NSH apps as [signed packages](https://nsh.dev/versions/main/docs/signed-packages.md) and run them as plugins, and an app that
shipped may never be built again: its team moved on, its source sits in a business process, the host app updated
NSH on its own schedule. So Native Shell keeps a promise to every app: **an app built for a compatible release runs
on every later release, unchanged.** An app that stops working after an NSH update is a bug in NSH.

This page describes the promise, how it is enforced, and how to change NSH within it.

## What an app can rely on

The promise covers everything a built app touches:

| Part | Why it matters |
| --- | --- |
| The exports of every module (`nsh`, `nsh/*`, `nsh/base`, the standard modules) and their members | A bundle imports them by name: a missing name and the app does not start. |
| `nsh:rt`, the functions compiled JSX calls | Each bundle carries the output of the compiler that built it. |
| The globals (timers, `fetch`, `console`, ...) and their members | Apps call them by name. |
| Element props, events and their payloads, style keys and their values | Apps pass them by name; a renamed prop is ignored, so the app runs wrong. |
| Tailwind utilities and variants | Classes are resolved at run time from the strings in the bundle. |
| Behavior: defaults, units, payloads, the order of callbacks | An app relies on what it saw when it was written. |
| The TypeScript declarations (`.nsh/types`) | An old app's source still type-checks when its team fixes a bug. |
| The package format and its signatures | A package signed for an earlier release still verifies. |

The rules that keep it:

1. **What a release shipped stays.** No module, export, member, prop, event, payload key, style key or value,
   Tailwind utility, global or `nsh:rt` function goes away.
2. **A rename keeps the old name** as an alias of the same implementation, marked `@deprecated` with the new name,
   for good. Moving an export to another module keeps it in the old one too.
3. **Types only widen.** A union gains alternatives, a function gains overloads or trailing optional parameters, a
   parameter becomes optional; what apps pass in (props, styles, options) gains optional members only. The values
   an app reads grow the same way: `platform.os` gains a platform, a state or a reason gains a case. A case the app
   saw keeps its value, and the app handles a value it does not know, with a `switch`'s `default`:

   ```tsx
   switch (platform.os) {
     case "ios":
     case "android":
       return <MobileLayout />;
     default:
       // The desktops, the web, and platforms NSH adds later.
       return <WideLayout />;
   }
   ```
4. **Behavior is kept.** New behavior is opt-in, through a new prop, option or value.
5. **`nsh:rt` only grows**, each function keeping its signature and meaning.
6. **Formats are read forever.** Packages, certificates, revocation lists and `app.json` of earlier releases are read
   by later ones; a package names the lowest runtime it needs (`nsh publish --min-runtime`).
7. **Security is the one exception.** A capability that cannot be kept safe is closed, listed with its reason and
   named in the release notes.

The promise starts at the first release recorded as compatible and holds for good, whatever the version number
says. Between releases, an API that only `main` has may still change.

## How it is enforced

What releases froze lives in its own repository,
[longbridge/nsh-compat](https://github.com/longbridge/nsh-compat), apart from NSH's code. A change to NSH runs
against it and cannot edit it: a pull request that renames an API cannot also rewrite the record of that API.

```
nsh                                       nsh-compat
├─ crates/          the code              ├─ releases/v<version>/   one per compatible release, never changed
└─ tests/compat/    apps that test the    │  ├─ runtime.txt         every export, global and nsh:rt function
   ├─ cases/        API being written     │  ├─ types/              the declarations apps build against
   └─ examples/                           │  ├─ tailwind.txt        every Tailwind class and what it sets
                                          │  └─ apps/               the test apps as that release built them
                                          ├─ closed.txt             security closures, each with its reason
                                          └─ src/                   the checks
```

Every pull request to NSH runs the checks of `nsh-compat` against its checkout (the **Compat** workflow, or
`cargo xtask compat` locally):

| Check | What passes |
| --- | --- |
| `checkout_apps_run` | The apps of `tests/compat/`, built by this checkout, do what their scripts say, and every part of the API a script claims to check is really checked. |
| `nothing_released_is_removed` | Everything each recorded release offered (exports, members and their kinds, declarations, Tailwind classes and what they set) is still offered, the same or widened. |
| `released_apps_run` | The apps each recorded release built, as its compiler built them, start on this runtime and do what their scripts say. |

The first check tests the API being written; the other two hold every release that was recorded. A rename of a
released API fails like this:

```
v0.2.0: runtime [nsh] Platform: removed
Keep it: a rename keeps the old name as a @deprecated alias of the new one, a type only widens.
```

`nsh-compat` is reviewed by NSH's maintainers, and its own CI runs it against NSH's `main`.

## The release flow

1. **Develop.** An API lands on `main` with a case in `tests/compat/` whose script checks it. Until a release records
   it, it may be renamed or reshaped; the case changes with it.
2. **Record.** At a release, `cargo xtask compat record <version>` writes `releases/v<version>/` into a checkout of
   `nsh-compat`: the surface the release offers and every app of `tests/compat/` built by its compiler, with their
   scripts. It records only an API whose every part a script checks.
3. **Freeze.** The record is merged through a pull request of `nsh-compat`. From then on every NSH change is held to
   it, together with every earlier record.

## Developing within the promise

### Adding an API

Every new export, global, prop, event or style key comes with a case:

1. Write a module `tests/compat/cases/<domain>/<case>.tsx` whose default export is a component that uses the API and
   shows its result. The domains are `base`, `core`, `events`, `layout`, `paint`, `props`, `modules` and `web`, plus
   `android`, `macos` and `browser` for what one platform or one `nsh.json` setting decides.
2. Add it to the domain's `App.tsx`, which shows one case at a time.
3. Append the steps to the domain's `script.txt`: `tap id:case-<case>`, then the steps that check what the API does,
   and a `covers <item>` step for each part it adds.
4. Run `cargo xtask compat` (`NSH_COMPAT_APP=<domain>` runs one domain).

```txt
# props-media-video
tap id:case-props-media-video
prop id:clip src https://example.com/clip.mp4
prop id:clip paused true
tap id:play
prop id:clip paused false
covers [props] src
covers [props] paused
```

A `covers` step is verified: the app must use the item, and for a prop, event or style key, taking it out of the
built app must make a step of the script fail. Items are named `[<module>] <export>`, `[globals] <name>`,
`[props] <name>`, `[events] <name>`, `[styles] <name>`, a component's own as `[props] <Component>.<name>`, and a
platform's props as `ios.<name>`, `android.<name>`, `desktop.<name>`, `web.<name>`.

### Renaming or moving an API

Add the new name and keep the old one as an alias of the same implementation, declared `@deprecated` with the new
name. Update the case and its script to the new name. An API no release recorded yet is simply renamed.

### Changing a type

Widen it: more alternatives in a union, more overloads, trailing optional parameters, optional new members of what
apps pass in. A union apps read gains members the same way, each new member for a new case. Parameter names are free to change; their count, optionality and types stay.

### Changing behavior

Keep the old behavior and add the new one behind a new prop, option or value. A bug fix that changes what a working
app sees is a behavior change too: put it behind an opt-in, or make sure no app can rely on the old result. Give the
behavior a step in a case, so it stays as it is.

### Changing the compiler

Nothing extra: the apps of each release stay as that release's compiler built them, and the cases are built fresh by
yours. The functions it emits into bundles (`nsh:rt`) only grow.

### Closing an API for security

A pull request of `nsh-compat` adds the entry to its `closed.txt` with the reason (`<entry> -- <reason>`, the entry
as the check reports it), and lands first; the NSH change that removes the API then passes. The release notes say
why.

## Scripts

A `script.txt` is one step per line. Steps that act: `tap <selector>`, `type <selector> <text>`,
`key <selector> <key>`, `scroll <selector> <x> <y>`, `touch start|move|end|cancel`, `event <selector> <onEvent>
[<key>=<value>...]`, `wait <ms>`, `keyboard <height> <duration>`, `pixelratio <ratio>`. Steps that check:
`expect <text>`, `absent <text>`, `frame <selector> <x> <y> <width> <height>`, `origin`, `prop` / `noprop`,
`style` / `nostyle`, `listens`, `state`, `statusbar`, `log <text>`. First lines may set the screen: `viewport <w> <h>`,
`platform <os> [desktop]`, `fontscale <scale>`. A selector is `id:<testID>`, `label:<label>`, `text:<text>` or
`span:<text>`; props and styles are written as apps write them (`style id:card backgroundColor #3366ffff`).
`NSH_COMPAT_DUMP=1` prints what each step adds to and removes from the screen, for writing a script.

## Commands

```sh
cargo xtask compat                      # the checks against this checkout
NSH_COMPAT_APP=props cargo xtask compat -v
cargo xtask compat record 0.2.0         # at a release: record it in nsh-compat, then open a pull request there
```

`cargo xtask compat` keeps a checkout of `nsh-compat` in `target/nsh-compat/` and brings it up to date on each run;
one with changes of its own is used as it is, so a change to the checks can be tried against NSH before its pull
request.

Source: https://nsh.dev/versions/main/docs/compatibility

---

# Design Guides

Use this guide before choosing components or writing layout code for an app built with Native Shell. It records the
product judgment GPUI Kit accumulated through years of desktop work, carried over to NSH: an interface should feel
native, restrained, precise, and understandable without guesswork.

This is a normative guide. **Must** identifies a correctness or ecosystem constraint, **should** is the default that
needs a concrete reason to override, and **may** is an optional technique. The [Elements](https://nsh.dev/versions/main/elements.md) and
[API](https://nsh.dev/versions/main/modules.md) pages remain the authority for individual props and methods.

The rules build on behavior in `nsh/base` (`nsh_base` in Rust), the theme and its tokens, and the interaction each
platform's users already know. NSH renders with each platform's own UI and leaves the look to the app: `nsh/base`'s
components bring behavior, state, focus and accessibility, and every color, size, radius and spacing comes from the
app's own components, so these rules guide the app's design system. <a href="https://ui.shadcn.com/docs" target="_blank" rel="noopener noreferrer">shadcn/ui</a>
contributes useful methods (open code, composition, and dependable defaults) but does not determine how an NSH app
should look. When influences conflict, preserve the platform's behavior and the interaction people already understand.

## Design thesis

Build interfaces that feel native, quiet, and precise. Let content, hierarchy, and interaction carry the experience;
decoration should support them rather than compete with them.

1. **Clarity before personality.** Make the primary task and next action clear before adding brand expression.
2. **Composition before invention.** Start with established components and compose them into product-specific
   workflows. Create a new primitive only when its behavior is genuinely new.
3. **Tokens before values.** Colors, radii, typography, and spacing should form a system. Avoid isolated literals that
   cannot respond to themes. See [Styling](https://nsh.dev/versions/main/docs/styling.md), [Tailwind](https://nsh.dev/versions/main/docs/tailwind.md) and [the theme](https://nsh.dev/versions/main/docs/rust.md#theme).
4. **Platform before web convention.** Preserve keyboard access, window chrome, menus, dense data views, resizable
   regions, and persistent navigation on the desktops, and the system's headers, back gesture, alerts and touch
   targets on phones and tablets, where the task benefits from them.
5. **State must be visible.** Hover, pressed, focus, selection, disabled, loading, validation, and destructive states
   need distinct and consistent treatment.
6. **Geometry explains containment.** Radii, insets, and boundaries should describe one coherent hierarchy, even where
   surfaces overlap.
7. **Feedback reflects reality.** Loading, tooltips, and motion should clarify a real state or transition, not add
   ceremony to an immediate action.

## Learning from Shadcn

Shadcn's most useful contribution is not a particular border color. It is a way of building a system:

- own the top layer of the interface instead of fighting a sealed abstraction;
- compose small, predictable parts into product-specific components;
- provide defaults that already form one visual language;
- keep the code and composition legible to both people and AI;
- separate behavior primitives from the styled layer.

NSH applies those ideas through the split between the primitives of `nsh`, the unstyled base components of
`nsh/base`, and the styled layer, which belongs to the app ([Three layers](https://nsh.dev/versions/main/docs/architecture.md#three-layers)).
Applications build their components on `nsh/base`, in TSX or in the app's Rust crate; reusable behavior belongs in
`nsh/base`, and visual policy stays above it.

Do not copy these web assumptions blindly:

| Web habit | NSH default |
| --- | --- |
| Pointing-hand cursor on every button | Default cursor; pointing hand (`cursor-pointer`) for links |
| Page navigation as the main structure | Persistent windows, panes, sidebars, tabs, and menus on the desktops; a `NavStack` with the system's back on phones |
| Browser focus and scrolling as a fallback | Explicit focus ownership and region-owned scrolling (`Scroll`, `List`) |
| Mobile-first single column | One column on phones, a resizable shell with a defined minimum window size on the desktops |
| Hover-revealed critical actions | Keyboard-, touch- and pointer-reachable actions that do not depend on hover |
| A row of hover-only icon buttons | A visible primary action plus `Menu` or `ContextMenu` for secondary commands |
| Link-styled text for application commands | A `Button` in the app's default, outline, or ghost style; link styling only for URLs, web resources, or email addresses |
| Large touch density everywhere | Touch-sized targets on touch screens; medium density with a pointer, compact only where information work benefits |
| A drawn header and alert card on every platform | The system's header and `AlertDialog` on iOS and Android; the page's `header` slot on the desktops and the web |
| CSS overrides across descendants | The app's components, their parts, and the theme's tokens |

## Start from the task

Before drawing a screen, write down:

- the user's primary task;
- the object being viewed or changed;
- the actions that must remain immediately available;
- the information required to make a decision;
- empty, loading, error, offline, read-only, and permission-denied states;
- the keyboard, touch and screen-reader path through the workflow;
- where the app is shown: on its own, or inside a host app.

Organize the screen around those answers. Do not begin with a dashboard grid or a component catalogue. A good interface
exposes the user's mental model: documents, accounts, projects, messages, settings, or another stable object—not the
internal service architecture.

Design the primary task before distributing controls. Its visual weight, location, and information depth should match
its importance to the product. A core result must not be reduced to a small count, an icon in a corner, or a weak
footer action while secondary content consumes the page. When a result set is the product's main value, consider a
summary region or card that exposes the count, representative results, meaningful state, and a clear next action.

For every proposed action, name its visible object, current state, scope, and result. If the interface does not show
or clearly imply those things, the action is premature. Do not expose a capability merely because the backend has it;
first design how the object enters the user's mental model.

## Visual language

### Hierarchy

Prefer a small number of clear levels:

- **window or page title** identifies the current object or workspace;
- **section title** separates meaningful regions (`role="header"`, so screen readers can jump between them);
- **body text** carries the work;
- **muted text** provides secondary metadata and help;
- **labels** identify controls and values.

Use size, weight, spacing, and separators before adding color or containers. Avoid nesting cards inside cards: most
regions need only a background, a hairline boundary, and intentional spacing.

Evaluate hierarchy across the whole feature, not component by component. Hide accent color and decoration during
review: the primary task, current selection, result summary, and next action should still be obvious from structure.
A screen that contains individually plausible controls can still fail when they do not form one reading order and one
decision path.

Treat emphasis as a limited budget. A local surface needs one clear focal point, not a field of competing highlights.
If everything is colored, badged, bold, boxed, or promoted to an alert, nothing reads as important. Establish priority
with structure and proximity first; spend stronger color and components only where a distinction changes what the
user notices or does.

### Color and themes

Read colors from the theme (`theme()` in Rust, token classes in TSX) and use them by semantic role:

- `background` and `foreground` for the main surface and text;
- `card`, `popover`, `sidebar`, and their foreground tokens for their named surfaces;
- `muted` and `muted-foreground` for supporting information;
- `primary` for the principal action or selection emphasis, `secondary` and `accent` for quieter emphasis and
  hovered or focused rows;
- `destructive` only for destructive actions and errors, and status colors the app adds to its theme (`success`,
  `warning`) only for their meanings;
- `chart-1` to `chart-5` for data series;
- `border`, `input`, and `ring` for structure and interaction.

```rust
use nsh_base::theme;

view()
    .rounded(move || theme().radius)
    .border_1()
    .border_color(move || theme().border)
    .bg(move || theme().background)
    .p_4()
    .gap_1()
    .child(text("Balance").text_color(move || theme().foreground))
    .child(text("Updated just now").text_sm().text_color(move || theme().muted_foreground))
```

```tsx
<View class="gap-1 rounded-(--radius) border border-border bg-background p-4">
  <Text class="text-foreground">Balance</Text>
  <Text class="text-sm text-muted-foreground">Updated just now</Text>
</View>
```

Do not use a semantic status color as decoration. Do not encode meaning by color alone. Verify every custom surface in
light and dark themes and with custom theme values, including the theme of a host app that embeds yours; never assume
that foreground is black or background is white.

Use a badge for a short state, count, or classification that benefits from rapid scanning—not for every label,
metadata value, filter, or section title. Keep most badges neutral; reserve semantic colors for states that truly carry
success, warning, destructive, or informational meaning. A row of multicolored badges is usually a missing hierarchy or
grouping decision.

Application UI should not contain raw hex, `rgb()`/`rgba()`, or `hsl()` colors, or palette classes such as
`bg-zinc-100`. Resolve colors from the theme by semantic role. If the required role does not exist, define it in the
app's theme file ([Theme tokens](https://nsh.dev/versions/main/docs/tailwind.md#theme-tokens): `"up": "#16a34a"` in its `light` and `dark` makes
`text-up`, `bg-up/30`, `token("up")` in TSX and `theme().color("up")` in Rust) rather than embedding a palette value
at the call site. Raw colors belong only inside theme definitions or in audited data/raster content whose color is itself the data.

### Radius, spacing, and density

Use a finite radius scale, as with type and control sizes. Choose from the theme's `radius` (for controls and
surfaces alike, `rounded-(--radius)`), radii the app adds to its theme, and Tailwind's `rounded-sm` … `rounded-2xl` between them) instead of inventing a
radius for each element. Large containers may use a softer tier than the controls they contain; compact controls and
overlays use tighter tiers. For an ordinary rectangle, the radius should remain visibly smaller than half its shorter
side. Use `rounded-full` (`.rounded_full()`) only for intentional circles and pills; a tooltip must not become a
capsule by accident.

Nested surfaces should read as concentric shapes. Use `inner radius ≈ max(0, outer radius − gap)` to choose the
closest suitable radius; the visible band should remain even through the turn. Add a named token to the theme
(`"radius-inset": "0.375rem"`, `rounded-(--radius-inset)`) if a repeated composition needs an intermediate value. A segmented
control is one silhouette: its end segments follow the container's inner corners, its middle segments remain square,
and each boundary has one divider of consistent thickness.

![Light theme chat composer: the inset surface, both buttons, and placeholder spacing change together; red guide circles show their shared corner center.](https://nsh.dev/versions/main/diagrams/radius-hierarchy-light.svg)

A radius must govern the entire visible surface, not just its border. Exposed corners remain transparent to the
surface behind them; child backgrounds, selection fills, and scrolling content must also follow the boundary. Give
inner surfaces their own radius, or clip the container with `overflow-hidden` (`.overflow_hidden()`), then inspect
the composition against a contrasting background in both themes. Preserve outward focus rings when choosing a clip.

Use a compact spacing scale and repeat it. Related label/control pairs should be closer than separate groups; separate
groups should be closer than separate sections. Prefer the sizes of the app's components (small, default medium,
large) over one-off heights. Use compact variants for toolbars and data-dense screens, not to squeeze an unclear layout
into less space.

The shared semantic scale is intentionally small: spacing progresses through roughly 2, 4, 8, 12, 16, 24, and 32
points, while typography stays near 12, 14, 16, 18, and 20 points. Treat these as relationships rather than permission
to scatter their current values through feature code. Tailwind's spacing scale gives them: one step is 4 points
(`p-4` is 16pt), in classes and typed Rust methods alike; `"spacing"` in `nsh.json`'s `"tailwind"` changes the step of
classes, and typed methods keep Tailwind's default scale. An application that needs a different scale owns it in its
own components or theme tokens (`p-(--gap-card)`) and uses it consistently.

### Spatial grammar

Spacing expresses relationship. Choose a gap from the semantic scale by asking what the two things mean to each other:

| Relationship | Typical class | Current scale | Examples |
| --- | --- | --- | --- |
| Optical correction | `gap-0.5` | 2 pt | icon baseline, compact separator |
| Parts of one control | `gap-1` | 4 pt | menu icon/label, title/description |
| Closely related controls | `gap-2` | 8 pt | button icon/label, dialog actions |
| One content group | `gap-3` | 12 pt | notification columns, compact form rows |
| Separate groups in one section | `gap-4` | 16 pt | panel padding, form groups |
| Separate sections | `gap-6` | 24 pt | major blocks in a page or inspector |
| Major region boundary | `gap-8` | 32 pt | empty-state breathing room, page bands |

These values describe the default scale, not literals to repeat. Use the spacing classes and typed methods (`gap-2`,
`.gap_2()`, `p-4`, `.p_4()`) or the theme's tokens. A product-owned scale should preserve the ordering and
relationships and must be passed through the application's own components rather than written at each call site.

Use these rules when resolving horizontal and vertical space:

1. **Inside before outside.** A component's padding belongs to the component; the gap between components belongs to
   their parent.
2. **Vertical rhythm shows grouping.** The gap between a title and its description is smaller than the gap from that
   description to the next section. Equal gaps imply equal relationships.
3. **Horizontal space supports scanning.** Repeated rows keep icons, labels, values, badges, and trailing actions on
   stable columns.
4. **Leading and trailing are semantic.** Think in reading-order edges and write them as start and end (`ps-*`,
   `me-*`, `.ps_4()`), so the layout mirrors right to left.
5. **Do not double padding.** A card placed in an already padded panel should not automatically add another full
   panel inset.
6. **Use optical alignment sparingly.** A one- or two-point correction is valid for icon or glyph geometry, but
   document why it differs from the scale.

Common compositions illustrate the relationships:

- button contents use 4 pt at small sizes and 8 pt at normal sizes;
- dialog headers and footers use an 8 pt internal gap;
- compact list and menu rows use 4 pt vertical and 8–12 pt horizontal padding;
- sheet headers use about 16 pt leading and 12 pt trailing space, leaving room for a close affordance, while footers
  use 16 pt horizontal and 12 pt vertical space;
- notifications use 16 pt horizontal padding and a 12 pt column gap because icon, message, and action are distinct
  groups.

Do not treat these as copy-and-paste recipes for every surface. They reveal the system: controls are tighter
internally, rows optimize scanning, and containers spend more space at their boundary than between their contents.

### Proportion and layer hierarchy

Start with content requirements, then set proportions. Avoid arbitrary halves when one pane has a clearly different
role.

- A navigation sidebar should be wide enough for stable labels but visibly subordinate to the work area. Give it a
  minimum, preferred, and maximum width (`min-w-*`, `w-*`, `max-w-*`) rather than a percentage alone.
- In master–detail layouts, let the collection remain scannable and give the detail pane the surplus. A roughly
  one-third/two-thirds starting point is often useful, but content constraints are authoritative. On a phone the two
  become two pages of a `NavStack`.
- Inspectors and auxiliary sheets should not cover the primary object by default. They should be resizable or
  dismissible when their content grows; a [`Sheet`](https://nsh.dev/versions/main/elements/sheet.md) closes with its backdrop, Escape and back.
- Dialog width comes from the decision: an `AlertDialog` for a short confirmation, a medium form, or a dedicated
  window/page for complex work. Do not enlarge a dialog simply to create whitespace.
- Reserve the strongest elevation for the topmost decision layer. Within a layer, use background and hairlines—not
  successively larger shadows—to show hierarchy.

Define three size constraints for every major region: the minimum at which its task still works, a comfortable
default, and how it consumes surplus. Persist user-controlled splits when they represent workflow preference, and
clamp restored values against the current window.

### Alignment details

Alignment is a structural system, not a final polish pass. Establish a small set of alignment spines for each surface:
shared leading and trailing edges, text baselines, center lines, and fixed functional lanes. Elements at the same level
should attach to the same spine from top to bottom or leading to trailing, even when they are different component
types.

![Alignment spines across a content region](https://nsh.dev/versions/main/diagrams/alignment-spines-light.svg)

Vertical red lines sit beside shared edges or control centers for content, status, time, and trailing actions.
Horizontal lines sit beneath text baselines or pass through a row center to show bottom and vertical-center alignment.
The compact comparison isolates a one-rendered-pixel drift that must be corrected at its structural owner.

- Give sibling regions a shared content inset. A heading, toolbar, list row, empty state, and footer that describe the
  same level should not each invent a slightly different leading edge.
- Repeat column geometry through the whole region. Headers, rows, summaries, loading states, and inline editors should
  reserve the same lanes for identity, metadata, status, numbers, and actions.
- Align related controls across rows and sections. Form labels, fields, descriptions, and validation messages should
  reveal a stable vertical grid when the page is scanned from top to bottom.
- Keep horizontal bands coherent. Items sharing a toolbar, header, status bar, or row should use one baseline or center
  line instead of individually tuned offsets.
- Introduce indentation only for real hierarchy, containment, or disclosure. Decorative indentation makes siblings look
  subordinate and breaks the surface's reading line.
- When a nested level ends, return exactly to the parent spine. Do not let accumulated padding drift across nested
  containers.
- Preserve the spine through optional content. Missing icons, badges, descriptions, or trailing actions must not move
  the remaining labels; use intentional slots or lanes when cross-row comparison matters.
- Align major regions with one another where their hierarchy matches. Sidebar headers, content titles, split panes,
  toolbars, and bottom bars need not share every coordinate, but coincident levels should form visible continuous
  lines.

Not every edge should align. A child can indent, a primary value can lead its supporting metadata, and a destructive
decision can gain separation. Such exceptions must communicate hierarchy or meaning; they must not result from
uncoordinated component padding. Start with the shared spine, then make the exception explicit.

Treat exact alignment and repeated gaps as quality invariants. When two edges or spaces are intended to be equal, a
one-rendered-pixel difference is a defect, not an acceptable optical approximation. Inspect resolved bounds with a
measurement tool at representative window sizes, text sizes, and display scale factors. Compare coordinates and
distances; do not approve alignment only from a casual screenshot.

The rendered-pixel tolerance is a verification rule, not permission to patch the code with raw point offsets. Equal
relationships should resolve from the same spacing class or method, token, grid definition, or shared component inset.
Fix the common owner when they differ. Account for fractional layout and device rounding (2× and 3× phones, fractional
desktop scales) so intended spines land on the same physical pixel instead of drifting at particular scales.

- Align text by baselines, not by bounding-box centers, when mixed sizes share a row.
- Center icons in a fixed slot so labels do not move when icons differ in intrinsic width.
- Align comparable numbers to the end and use tabular figures (`tabular-nums`); align prose and identifiers to the
  start unless the locale requires otherwise.
- Keep trailing row actions and disclosure indicators in fixed-width lanes.
- Align form controls by their interactive frame, not by help text below them.
- Use `justify-between` (`.justify_between()`) only when the two sides truly own opposite edges; it should not
  disguise missing structure in the middle.
- Hairlines belong on the boundary owner. Two adjacent regions must not each draw the same separator.
- A scrollbar belongs to the region that scrolls and sits against that panel, editor, or window's trailing edge.
  Content padding may inset text and rows; it must not pull the scrollbar into the middle of the surface. Pad the
  scroll view's content, not the scroll view.

### Density tiers

Medium is the default. Change density for the whole local context, not one isolated control:

- **comfortable / large:** onboarding, sparse forms, prominent decisions;
- **standard / medium:** most application chrome and workflows, and every touch screen;
- **compact / small:** desktop toolbars, menus, tables, and repeated professional data;
- **extra compact / xsmall:** exceptional high-density utilities, never the automatic choice for an entire application.

Use a bounded scale rather than arbitrary sizing. On touch screens every pressable target is at least 44 × 44 points
([Touch targets](https://nsh.dev/versions/main/docs/accessibility.md#touch-targets)). With a pointer, buttons commonly move through approximately 24, 28,
and 32 pt frames, inputs extend to about 40 pt at large size, and table rows use about 28, 32, and 40 pt. Give the
app's components a size that changes typography, icon, padding, and hit target together; a custom height that changes
only the outer box is usually incomplete.

### Text size, base font, and points

A well-designed scale preserves hierarchy while text grows. Larger text is successful when the relationship between
title and body, control and icon, inner and outer spacing, primary and secondary regions still feels the same at every
size—not merely when every object becomes larger.

NSH's lengths are points, and the user's text size (Dynamic Type on iOS, font size on Android, the desktops' text
scaling, a host app's own setting) scales text: every text and input that allows font scaling grows, while spacing,
radii, borders and images keep their size ([Text size](https://nsh.dev/versions/main/docs/device-and-environment.md#text-size)). The app's base text
size (Tailwind's `text-base`, 16 points) is the body size the type scale steps around.

Design in ratios:

- type steps keep the same hierarchy around the base body size;
- spacing steps keep the same grouping relationships around the type;
- control frames and hit targets grow with their labels: size them by their content and a minimum (`min-h-11`), not a
  fixed height;
- pane minima and comfortable widths account for larger text;
- corner radii and focus treatment remain optically consistent with the control frame.

Because text grows on its own, a fixed frame around it breaks: a larger label inside a fixed-height button, a larger
document inside fixed pane minima, or larger rows inside a fixed row height destroys the original rhythm and can clip
content. Let rows wrap or switch to a column when text gets large (`fontScale()`, `font_scale()`), and cap the scale
of text that is already large, such as a 34pt title (`maxFontSizeMultiplier`).

As a rule, application layout should not write literal point values (`p-[13px]`, `px(13.0)`). Use the spacing scale
(`p-2`, `gap-3`, `w-64`, `text-sm` and their typed methods) or the app's component sizes. Use literal points only when
the value represents a physical or raster boundary: a hairline, platform window inset, bitmap dimension, minimum
hit-test tolerance, or geometry that must match an external surface. These are audited, documented exceptions. Product
spacing, typography, icon size, and ordinary control geometry stay on the scale.

Test at several text sizes, not just the default. Verify hierarchy, wrapping, truncation, minimum window size, pane
resizing, focus-ring clearance, popup placement, and list row measurement.

### Surfaces and elevation

Use elevation to explain stacking, not importance. The base surface is flat; separators and background contrast define
its regions. Popovers, menus, sheets, dialogs, and notifications may use progressively stronger shadows because they
sit above other content. Do not put a shadow on every card.

All surfaces of the same kind should share one treatment. Give the popup families one themed surface (the `popover`
tokens, the border, `radius` and one shadow) so `Popover`, `Menu`, `ContextMenu` and `Tooltip` do not drift apart.
When an application invents another anchored surface, reuse that treatment instead of approximating it with unrelated
border and shadow literals.

### Typography and icons

Use the platform UI font for interface text and monospace only for code, identifiers, shortcuts, and aligned numeric
data. Keep body text readable and avoid excessive uppercase or letter spacing, especially for CJK text.

Use one icon family in a product. Icons supplement labels; they should not replace unfamiliar actions with guesswork.
Icon-only buttons always need an accessible name (`accessibilityLabel`). Their visual explanation follows the tooltip
policy below. Use filled or colored icons to communicate a state, not merely to make a toolbar lively.

## Layout patterns

### Choose a stable shell

Most applications should use one of these shells:

- **single workspace:** a header or toolbar above one primary view;
- **navigation stack:** pages pushed and popped (`NavStack`), with the system's back gesture on phones;
- **sidebar workspace:** persistent navigation beside a changing detail view;
- **master–detail:** resizable collection and detail panes, two pages on a phone;
- **document workspace:** tabs for multiple long-lived objects;
- **utility window:** one focused task with a short, fixed action path.

Keep global navigation stable while content changes. Give the primary work area the remaining space with `flex-1`
(`.flex_1()`) and `min-w-0` / `min-h-0` where overflowing children must shrink. Use `Scroll` and `List` for their
intended behavior instead of rebuilding scrolling or virtualization from nested views.

On the desktops, a title bar of the app's own ([`nsh/desktop`](https://nsh.dev/versions/main/modules/nsh-desktop.md)) is window chrome first.
Preserve its drag region (`.window_drag(true)`) and avoid binding ordinary title clicks to infrequent editing
commands. Rename belongs behind an explicit object command, with a keyboard path where appropriate.

### Responsive windows

A window can be any size: the user, a split view or the host app decides it. Decide what happens as a window narrows:

1. preserve the primary task;
2. allow resizable regions to reach a documented minimum;
3. collapse secondary labels or inspectors;
4. move low-frequency actions into a menu;
5. scroll only the region whose content actually overflows.

Do not hide an action without providing another path to it. Avoid making the entire window scroll when only a list or
document body should scroll. Breakpoints (`md:`, `lg:`) and `windowSize()` (`window()` in Rust) follow the surface NSH
renders into.

NSH's flex layout has the same intrinsic-size pressure found in other layout systems: a `flex-1` child may still refuse
to shrink around long content. Design and implementation must agree on which panes may shrink, truncate, wrap, or
scroll. A clipped region also clips an outward focus ring; never trade away keyboard visibility merely to simplify
overflow.

### Forms and settings

Use a visible label for each field and place help or validation next to the field it describes. Align related fields,
but do not force long labels into a narrow fixed column. Use the appropriate control: `Checkbox` for independent
choices, a [`RadioGroup`](https://nsh.dev/versions/main/elements/radio.md) of `Radio`s for a small visible set, a `Menu` of choices for a longer set,
and [`Switch`](https://nsh.dev/versions/main/elements/switch.md) for a setting that takes effect immediately. Their parts (the switch's track and
thumb, the checkbox's indicator) are the app's to style, with `checked:`, `indeterminate:` and `disabled:` classes
that follow the control:

```rust
use nsh_base::{switch, theme};

fn setting_switch(label: &'static str, on: Signal<bool>) -> impl IntoElement {
    switch()
        .checked(on)
        .on_change(move |next: &bool| on.set(*next))
        .flex_row()
        .items_center()
        .gap_3()
        .track_style(|s| {
            s.w(px(44.0))
                .p(px(2.0))
                .rounded_full()
                .bg(move || theme().muted)
                .transition_colors()
                .checked(|s| s.bg(move || theme().primary))
        })
        .thumb_style(|s| {
            s.size(px(20.0))
                .rounded_full()
                .bg(move || theme().background)
                .shadow_sm()
                .transition_transform()
                .checked(|s| s.translate_x(px(20.0)))
        })
        .child(text(label).text_color(move || theme().foreground))
}
```

```tsx
import { Text } from "nsh";
import { Switch } from "nsh/base";

function SettingSwitch(props: { label: string; on: boolean; onChange: (e: { checked: boolean }) => void }) {
  return (
    <Switch
      checked={props.on}
      onChange={props.onChange}
      class="flex-row items-center gap-3"
      trackClass="w-11 rounded-full bg-muted p-0.5 transition-colors checked:bg-primary"
      thumbClass="size-5 rounded-full bg-background shadow-sm transition-transform checked:translate-x-5"
    >
      <Text class="text-foreground">{props.label}</Text>
    </Switch>
  );
}
```

A "select all" checkbox shows a partial selection with its indeterminate state:

```rust
use nsh_base::{checkbox, theme};

fn select_all(selected: Signal<usize>, total: usize) -> impl IntoElement {
    checkbox()
        .checked(move || selected.get() == total)
        .indeterminate(move || selected.get() > 0 && selected.get() < total)
        .on_change(move |all: &bool| selected.set(if *all { total } else { 0 }))
        .flex_row()
        .items_center()
        .gap_2()
        .indicator_style(|s| {
            s.size(px(20.0))
                .items_center()
                .justify_center()
                .rounded(move || theme().radius)
                .border_2()
                .border_color(move || theme().border)
                .checked(|s| s.bg(move || theme().primary).border_color(move || theme().primary))
                .indeterminate(|s| s.bg(move || theme().primary).border_color(move || theme().primary))
        })
        .indicator(text(move || mark(selected.get(), total)).text_color(move || theme().primary_foreground))
        .child(text("Select all").text_color(move || theme().foreground))
}

fn mark(selected: usize, total: usize) -> &'static str {
    if selected == total { "✓" } else if selected > 0 { "–" } else { "" }
}
```

```tsx
import { Text } from "nsh";
import { Checkbox } from "nsh/base";

function SelectAll(props: { selected: number; total: number; onChange: (e: { checked: boolean }) => void }) {
  return (
    <Checkbox
      checked={props.selected === props.total}
      indeterminate={props.selected > 0 && props.selected < props.total}
      onChange={props.onChange}
      class="flex-row items-center gap-2"
      indicatorClass="size-5 items-center justify-center rounded-(--radius) border-2 border-border checked:border-primary checked:bg-primary indeterminate:border-primary indeterminate:bg-primary"
      indicator={
        <Text class="text-primary-foreground">
          {props.selected === props.total ? "✓" : props.selected > 0 ? "–" : ""}
        </Text>
      }
    >
      <Text class="text-foreground">Select all</Text>
    </Checkbox>
  );
}
```

Disable submission while an operation is in flight, keep the user's input, and show the result near the action. Keep
inputs above the software keyboard (`env(keyboard-inset-height)`). Reserve dialogs for short, focused decisions; use a full
page or sheet for workflows that need exploration or many fields.

A loading treatment must represent actual waiting. Switching between settings panels whose content is already
available should be immediate; a skeleton is appropriate only while content is genuinely loading and its shape is
known.

## Components and composition

Follow the Shadcn principle that components are building material rather than a sealed design system. `nsh/base`
supplies behavior; the app supplies coherent defaults in its own components and owns composition and product
semantics.

- Use component variants by meaning. Primary is reserved for the explicit default commit in a decision area—normally
  the action invoked by Return on the desktops. A lone, frequent, or desirable action is not automatically primary. An
  `Add` command in a management toolbar normally uses a default button; a form's default `Create` commit may use
  primary. Use destructive for destructive commitment and ghost for quiet toolbar actions.
- Prefer explicit parts and slots over styling arbitrary descendants.
- Keep a repeated pattern consistent across the product. Wrap it in an application component when it carries domain
  language or policy.
- Use the standard component for its semantic role. `Menu`, `ContextMenu`, `Popover`, `Sheet`, `Dialog` and
  `AlertDialog` are not interchangeable boxes; each owns different selection, focus, keyboard, dismissal, and layout
  contracts, and takes its own form on each device.
- Preserve the component family's geometry. Menu rows share vertical and horizontal padding, height, icon and
  checkmark slots, separators, radius, and state treatment. Do not imitate one menu with a custom popup whose spacing
  only approximates the system.
- Do not wrap a component merely to rename every prop or freeze all of its capabilities.
- Move reusable behavior without product styling to `nsh/base`, or to a crate the app's products share; keep themed,
  opinionated presentation in the application's components.

```rust
use nsh_base::{button, theme};

/// The footer of a form: a default Cancel and the primary commit.
fn form_actions(cancel: impl Fn() + 'static, create: impl Fn() + 'static) -> impl IntoElement {
    view()
        .flex_row()
        .justify_end()
        .gap_2()
        .child(
            button()
                .on_press(cancel)
                .rounded(move || theme().radius)
                .border_1()
                .border_color(move || theme().border)
                .px_4()
                .py_2()
                .active(|s| s.bg(move || theme().muted))
                .child(text("Cancel").text_color(move || theme().foreground)),
        )
        .child(
            button()
                .on_press(create)
                .rounded(move || theme().radius)
                .bg(move || theme().primary)
                .px_4()
                .py_2()
                .active(|s| s.bg(move || theme().primary.opacity(0.9)))
                .child(text("Create").text_color(move || theme().primary_foreground)),
        )
}
```

```tsx
import { Text, View } from "nsh";
import { Button } from "nsh/base";

// The footer of a form: a default Cancel and the primary commit.
function FormActions(props: { onCancel: () => void; onCreate: () => void }) {
  return (
    <View class="flex-row justify-end gap-2">
      <Button onPress={props.onCancel} class="rounded-(--radius) border border-border px-4 py-2 active:bg-muted">
        <Text class="text-foreground">Cancel</Text>
      </Button>
      <Button onPress={props.onCreate} class="rounded-(--radius) bg-primary px-4 py-2 active:bg-primary/90">
        <Text class="text-primary-foreground">Create</Text>
      </Button>
    </View>
  );
}
```

## Interaction states

### Make the result understandable before the click

A control should predict its result. Use familiar platform controls and placement so people can act without learning
the interface first. Its label names the action and object, its state shows availability, and its feedback confirms
the same outcome.

Do not label a Button `Save` if it opens a configuration flow, or `Delete` if it only removes an item from a group.
Name the scope when context does not make it clear. Respond immediately to activation, prevent duplicate submission
during longer work, and show the result near the object that changed. Add a success message only when the result
itself is not visible.

Every interactive control should be designed for:

| State | NSH | Design requirement |
| --- | --- | --- |
| Rest | | Clear affordance without visual noise |
| Hover | `hover:` | Subtle pointer feedback, never the only cue |
| Pressed | `active:` | Immediate press feedback, styled by the app |
| Open / pressed | the popup's `open` | Persistent feedback while an attached popup is open |
| Focus visible | `focus-visible:` | High-contrast keyboard focus ring |
| Selected / checked | `selected:`, `checked:` | Persistent state distinct from hover |
| Disabled | `disabled:` | Lower emphasis and no misleading hover/pressed response |
| Loading | | Preserve context, prevent duplicate action, explain long waits |
| Error | | State what happened and how to recover |

Bind commands that should work from the keyboard with [`keymap`](https://nsh.dev/versions/main/modules/nsh.md#keymap) on the desktops and
the web. Match familiar platform shortcuts (`"mod+k"` is Command on macOS, Control elsewhere), expose shortcuts in
menus or tooltips, and keep focus in a logical place after opening or dismissing an overlay.

Selection is part of the information model, not optional polish. Tabs, segmented choices, selectable rows, filters,
and navigation destinations must show a persistent selected state (`selected`, which screen readers announce). A
button that owns a menu must remain visibly pressed or open until the popup closes; hover alone cannot explain the
relationship between trigger and surface.

```rust
use nsh_base::{tab, theme};

fn section_tab(label: &'static str, id: Section, current: Signal<Section>) -> impl IntoElement {
    let selected = move || current.get() == id;
    tab()
        .selected(selected)
        .on_press(move || current.set(id))
        .rounded(move || theme().radius)
        .px_3()
        .py_2()
        .selected_style(|s| s.bg(move || theme().muted))
        .child(text(label).text_color(move || {
            if selected() { theme().foreground } else { theme().muted_foreground }
        }))
}
```

```tsx
import { Text } from "nsh";
import { Tab } from "nsh/base";

function SectionTab(props: { label: string; selected: boolean; onPress: () => void }) {
  return (
    <Tab
      selected={props.selected}
      onPress={props.onPress}
      class="group rounded-(--radius) px-3 py-2 selected:bg-muted"
    >
      <Text class="text-muted-foreground group-selected:text-foreground">{props.label}</Text>
    </Tab>
  );
}
```

In a segmented control, the selected fill and unselected surface must share the container's silhouette. Neither may
square off an end corner or make a boundary appear heavier than its peers.

Show a selected navigation item, list row, or tab through the item's own surface: a selected fill, stronger
foreground, or heavier weight. Do not add a leading-edge bar or one-sided border as the selection marker. It is a web
template habit, not a native convention; it breaks the item's rounded silhouette and adds a second, competing edge to a
column that already aligns on its text.

For destructive actions, distinguish between reversible and irreversible work. Prefer undo or a temporary notification
for reversible changes. Use an [`AlertDialog`](https://nsh.dev/versions/main/elements/alert-dialog.md) when the consequence is serious and cannot
be undone; name the specific object and consequence in the confirmation copy.

### Pointer conventions

Use the default cursor for buttons, checkboxes, menu items, tabs, and other controls. Use a pointing hand
(`cursor-pointer`) for links and content that behaves as a link. Use text, resize, grab, and prohibited cursors only
when they describe the active manipulation. A cursor reinforces an affordance; it does not replace the control's
visible state or accessible role.

Keep hover effects modest because touch, keyboard, and accessibility interaction have no hover. Do not reveal the only
copy of a destructive or essential action on hover. Contextual row actions may become quieter at rest if the same
commands remain available through selection, keyboard, or a context menu.

### Prefer command surfaces over hover toolbars

Use command frequency and scope to choose where an action lives:

- keep the primary or frequent action visible as a labeled button or familiar toolbar control;
- put secondary actions for the current region behind a visible [`Menu`](https://nsh.dev/versions/main/elements/menu.md) trigger;
- put commands that act on the object under the pointer or finger in a `ContextMenu`: a right click on the desktops,
  a held finger on touch screens;
- expose the same important command through a keyboard shortcut ([`keymap`](https://nsh.dev/versions/main/modules/nsh.md#keymap)) when it has
  a natural keyboard form, and in the application menu (`Menu.setApplicationMenu` from
  [`nsh/desktop`](https://nsh.dev/versions/main/modules/nsh-desktop.md));
- use a hover-revealed icon only as a shortcut to a command that remains reachable elsewhere.

This is more than a visual preference. `nsh/base`'s menus already own placement at the trigger, cascading submenus on
the desktops and a sheet with submenus in place on phones, dismissal by choosing an item, a press outside, Escape or
back, and the menu and menu item roles for screen readers. A custom strip of hover buttons must rebuild those behaviors
and is invisible to touch, keyboard-only, and many assistive technology workflows.

```rust
use nsh_base::{menu, menu_item, menu_separator, theme};
use nsh_core::{color::black, element::StyleRefinement};

/// The app's popup surface, shared by its menus, popovers and tooltips.
fn popup(s: StyleRefinement) -> StyleRefinement {
    s.min_w(px(192.0))
        .p_1()
        .rounded(move || theme().radius)
        .border_1()
        .border_color(move || theme().border)
        .bg(move || theme().popover)
        .shadow_lg()
}

fn item(label: &'static str, on_select: impl Fn() + 'static) -> impl IntoElement {
    menu_item()
        .on_select(on_select)
        .px_3()
        .py_2()
        .rounded(move || theme().radius)
        .hover(|s| s.bg(move || theme().muted))
        .active(|s| s.bg(move || theme().muted))
        .child(text(label).text_color(move || theme().foreground))
}

fn more_menu(rename: impl Fn() + 'static, duplicate: impl Fn() + 'static, delete: impl Fn() + 'static) -> impl IntoElement {
    menu()
        .offset(px(4.0))
        .popup_style(popup)
        .backdrop_style(|s| s.bg(black().opacity(0.5)))
        .trigger(
            view()
                .label("More actions")
                .size(px(44.0))
                .items_center()
                .justify_center()
                .rounded_full()
                .active(|s| s.bg(move || theme().muted))
                .child(text("⋯").text_color(move || theme().foreground)),
        )
        .child(item("Rename…", rename))
        .child(item("Duplicate", duplicate))
        .child(menu_separator().h(px(1.0)).my_1().bg(move || theme().border))
        .child(item("Delete…", delete))
}
```

```tsx
import { Text, View } from "nsh";
import { Menu, MenuItem, MenuSeparator } from "nsh/base";

/** The app's popup surface, shared by its menus, popovers and tooltips. */
export const popup = "min-w-48 rounded-(--radius) border border-border bg-popover p-1 shadow-lg";
const item = "rounded-(--radius) px-3 py-2 hover:bg-muted active:bg-muted";

function MoreMenu(props: { onRename: () => void; onDuplicate: () => void; onDelete: () => void }) {
  return (
    <Menu
      offset={4}
      popupClass={popup}
      backdropClass="bg-black/50"
      trigger={
        <View accessibilityLabel="More actions" class="size-11 items-center justify-center rounded-full active:bg-muted">
          <Text class="text-foreground">⋯</Text>
        </View>
      }
    >
      <MenuItem onSelect={props.onRename} class={item}><Text class="text-foreground">Rename…</Text></MenuItem>
      <MenuItem onSelect={props.onDuplicate} class={item}><Text class="text-foreground">Duplicate</Text></MenuItem>
      <MenuSeparator class="my-1 h-px bg-border" />
      <MenuItem onSelect={props.onDelete} class={item}><Text class="text-foreground">Delete…</Text></MenuItem>
    </Menu>
  );
}
```

Choose `Menu` when users need a visible indication that more commands exist—for example a toolbar overflow, document
actions, or account menu. Choose `ContextMenu` for selection- or object-scoped commands such as rename, duplicate,
reveal, or remove. The context menu must not be the only way to perform an essential command; provide a menu-bar,
toolbar, keyboard, or detail view path as appropriate.

Do not put every action into a menu to make a screen look minimal. Discovery and speed matter: the main action stays
visible, dangerous items remain clearly labeled and separated, and a menu item should use the same verb, icon,
shortcut, enabled state, and result everywhere it appears.

### Button means application action; Link means external resource

Use a `Button` when activation changes application state, confirms a decision, opens a tool, submits data, or runs a
command. Choose its treatment by local hierarchy:

- primary button for the one emphasized commitment in a decision area;
- default button for ordinary visible actions;
- outline button when an action needs a clear boundary with less emphasis;
- ghost button for familiar, low-emphasis toolbar and inline actions;
- icon button only for a well-known symbol, with an accessible name and a tooltip when meaning or scope is unclear.

Do not assign primary because a button is the only action on screen, because it is placed at the top right, or
because the team wants more clicks. Primary communicates default commitment and keyboard behavior. If activation is
merely an ordinary command such as adding an item, opening a tool, or refreshing a view, use a default, outline, or
ghost button according to its local hierarchy.

Use an underlined link (`role="link"`) only for an external resource target: a URL, web page, online documentation, or
email address. It uses the pointing-hand cursor because its contract is leaving the current application context for
that resource. Do not use link styling to make a functional command look quiet. A link-shaped Delete, Save, Refresh,
Add, Open-menu, or in-app navigation action hides the control's affordance and exposes the wrong accessibility role.

“View” does not make an in-app destination a link. A full report, analysis, details panel, or local record still opens
through a button, row, card, tab, or disclosure control. Use concise context-aware labels such as `Full analysis` when
the containing card already establishes what opens; reserve underlining for a resource that actually opens in a browser
or mail client.

All internal navigation—sidebar rows, tabs, breadcrumbs, list items, opening a local view, or switching
workspaces—must use the navigation stack, a `Button`, or the corresponding component. Visual emphasis is chosen through
the button's variant or the navigation component's selected state, never by lying about semantics.

## Feedback and overlays

Choose the smallest surface that fits the decision:

- tooltip: a short explanation or shortcut ([`Tooltip`](https://nsh.dev/versions/main/elements/tooltip.md), or any element's `tooltip`);
- popover: contextual controls that do not interrupt the task ([`Popover`](https://nsh.dev/versions/main/elements/popover.md));
- menu: a compact list of actions ([`Menu`](https://nsh.dev/versions/main/elements/menu.md));
- notification: asynchronous status that does not require a decision;
- dialog: a focused decision or short form ([`Dialog`](https://nsh.dev/versions/main/elements/dialog.md));
- alert dialog: explicit confirmation of a consequential action ([`AlertDialog`](https://nsh.dev/versions/main/elements/alert-dialog.md));
- sheet: supplementary work that benefits from more persistent space ([`Sheet`](https://nsh.dev/versions/main/elements/sheet.md)).

Each takes the form its device expects, from one structure the app styles (`popupClass`, `backdropClass`):

| | Desktops | Phones and tablets |
| --- | --- | --- |
| `Tooltip` | after the pointer rests on the element | only when the app opens it |
| `Popover` | anchored; a press outside closes it and goes on | anchored; a press outside only closes it |
| `Menu` | a popup at the trigger, cascading submenus | a sheet at the bottom; a submenu takes the place of its items |
| `ContextMenu` | the secondary button, at the pointer | a held finger opens the sheet |
| `Sheet` | an edge panel over a backdrop | the same |
| `AlertDialog` | an alert in the platform's dialog style | the system's alert or action sheet |

A tooltip supplies missing meaning; it does not restate an obvious action. Reserve it for an unfamiliar symbol,
ambiguous scope, or a useful shortcut that is otherwise hidden. Repeated, recognizable commands such as Copy and
Download in a message footer need accessible names and keyboard access, but their hover labels add interruption rather
than clarity. Phones show a tooltip only when the app opens it, so a tooltip must never carry what a touch user needs.

An alert interrupts the visual hierarchy even when it does not open a modal. Use it for important, exceptional
information that needs attention in the current task, not as a decorated container for ordinary descriptions, tips,
or empty space. Prefer inline help, muted text, or a normal section when the content does not require immediate notice
or action.

Avoid stacking overlays. Escape and the Android back button dismiss the topmost dismissible layer; keep the app's state
in sync from `onOpenChange`, and return focus to the trigger or the next logical target.

An overlay action must refer to an object or state the overlay actually shows. For example, expose `Clear history`
only when a distinct recent-history section is visible and contains entries. Search results, recent items, and
favorites are different collections; label and separate them instead of merging them into one unexplained list. Hide
an inapplicable action or disable it with a useful reason—do not park an ambiguous trash icon in a footer.

Footer space is not a catch-all for capabilities that lacked a place in the design. A footer may present shortcuts,
status, or actions that apply to the whole surface, but each item must answer: what is its object, why is it available
now, what scope does it affect, and what visible state changes after activation?

## Motion

Motion explains change; it is not ambient decoration. Use short transitions for appearance, dismissal, expansion, and
spatial continuity. Avoid animating large layout changes when opacity or transform communicates the same relationship.
Honor reduced-motion preferences (`motion-reduce:`, `reduceMotion()`), never require animation to understand state,
and do not add a default animation to every component.

```rust
view()
    .on_press(open)
    .transition_transform()
    .duration(150.0)
    .when(!reduce_motion(), |v| v.active(|s| s.scale(0.97)))
```

```tsx
<View onPress={open} class="transition-transform duration-150 active:scale-[0.97] motion-reduce:active:scale-100" />
```

Motion policy belongs to the application layer. `nsh/base` owns the lifecycle mechanism or geometry needed for a
transition, but it does not decide that every product fades or slides. Give independently animated values stable
identity, and make interruption reverse smoothly from the currently sampled value rather than restarting from an old
endpoint.

Motion follows the continuity of the interaction. While a pointer or scroll position moves among related targets, keep
the preview surface stable and update its content or position in place. Dismiss it only after the interaction ends;
repeated fade-out and re-entry on each update reads as flicker.

## Designing data-heavy interfaces

Dense does not mean cramped. In tables, trees, long lists, and editors:

- keep headers and primary row identity visually stable;
- align comparable values and use tabular numerals where appropriate;
- distinguish focus, hover, active row, and multi-selection;
- keep sorting and filtering visible and reversible;
- preserve selection by domain identity across filtering and reordering;
- virtualize large collections (`List`) without changing keyboard semantics;
- use progressive disclosure for secondary columns and inspectors;
- provide a useful empty state that explains the next action.

Choose a table for comparison across consistent fields, a list for scanning heterogeneous items, and a tree for real
hierarchy. Do not use a complex data layout as a visual style.

## Interface language

Words are part of the interface architecture. Write the vocabulary for a feature as a system—destinations, objects,
commands, states, and outcomes—not as isolated translations of implementation features. Prefer the shortest wording
that remains accurate in its actual context.

### Let context carry context

Do not repeat information that the surrounding surface already establishes. A sidebar destination is usually the
object or domain itself: use `Users`, not `User Management`; `Shortcuts`, not `Shortcut Configuration Management`. A
column whose rows already contain actions can omit a generic `Operation` heading. A dialog titled `Delete “Roadmap”?`
does not need body text that asks the same question again.

This is context economy, not deletion for its own sake. Add text when it changes the decision: identify the affected
scope, an irreversible consequence, an unusual prerequisite, or a way to recover. Every extra word should answer a
question the current layout does not already answer.

Use nouns for destinations and objects (`Users`, `Appearance`, `Orders`), verbs for commands (`Save`, `Duplicate`,
`Export`), and adjectives or short phrases for states (`Offline`, `Up to date`, `Pending review`). Avoid wrappers such
as `Management`, `Module`, `Page`, `Function`, `Operation`, and `System` unless the word distinguishes a real domain
concept.

### Write each language, do not translate its shape

Start from shared intent, hierarchy, and terminology, then compose each locale as natural interface language. Do not
preserve the source language's word order, number of words, politeness filler, or grammatical category. English
`Users` can express a Chinese feature concept that would literally expand to “user management”; fidelity means
preserving purpose, not preserving tokens.

Remove words supplied by the enclosing information architecture. Inside a `Settings` surface, a destination is often
simply `Account`, not `Account Settings` and never the unnatural singular `Account Setting`. The correct English label
is chosen from its role and neighbors, not from the standalone source phrase.

Maintain a small product lexicon for recurring objects, commands, and states. Use the same term in the toolbar, menu,
context menu, dialog, shortcut search, and documentation unless the context genuinely changes its meaning. Review copy
in the rendered surface: neighboring labels often reveal repetition or inconsistent scope that a locale file cannot.

In localized technical writing, preserve an established framework term when a translation would be less precise. Keep
API identifiers in their original form and format them as code. Do not retain ordinary foreign words merely to sound
technical. Explain a retained term on first use when needed, then use the same form throughout the interface,
documentation, and API examples.

In documentation, use the exact English name for a named API, component, source file, or guide in link text, including
localized pages. For example, write `View`, `Button`, `Menu`, and `Text` rather than translating their names or adding a
redundant `NSH` prefix. Keep surrounding explanations in the page's language. Link only the named target; place words
such as “source” outside the link when they describe why it is cited.

In a technical comparison table shared across locales, keep capability names, framework names, API names, and model
names in their established English form. Translate the explanation around the table, not its technical labels. Common
interface words with an established local name may still be localized outside that comparison context.

### Buttons and confirmation dialogs

Button labels are short by default—usually one or two words—and describe the result, not the gesture or the component.
Prefer `Save`, `Move`, or `Delete` to `Click to save`, `Perform move`, or `Confirm deletion`. Use `Cancel` consistently
for the action that leaves without committing. Reserve `OK` for acknowledging purely informational content.

Short is a default, not a character limit. A deliberately longer label is better when its words expose a consequence
or distinguish choices that users could otherwise confuse, for example `Delete from this group` versus `Delete
everywhere`, or `Restart without saving`. Length must buy decision-critical information; it must not restate the
dialog title or body.

Use the most specific concise result as the confirmation label when possible:

| Context | Weak | Prefer |
| --- | --- | --- |
| Delete dialog | `Yes`, `Sure`, `Confirm deletion` | `Delete` |
| Unsaved changes | `Confirm`, `Yes` | `Discard changes` |
| Pure acknowledgement | `Confirm operation` | `OK` or `Done` |
| Complex consent whose result has no clear verb | `Yes` | `Confirm` |

`Confirm` is a useful fallback when the surrounding dialog fully names a complex commitment and no shorter result verb
is accurate. It should not replace a clear command. `Sure` is conversational rather than a stable English command and
is too ambiguous for the standard vocabulary.

A confirmation dialog should form one compact decision:

- title: the decision or condition, such as `Delete “Roadmap”?`;
- body: only new scope, consequence, or recovery information;
- actions: `Cancel` and the result, such as `Delete`;
- destructive styling: applied to the destructive result (an `AlertDialog` action with the `destructive` role), not
  substituted for precise wording.

Avoid generic titles such as `Notice`, `Warning`, `Error`, and `Confirmation` when the actual condition can be named.
Avoid ritual phrases such as “Are you sure you want to…”, “Would you like to…”, “Please note that…”, and
“successfully” when the structure or state already communicates them. Courtesy should come from a calm, respectful
tone, not repeated `please`.

### Capitalization, punctuation, and symbols

Use sentence case for English UI by default: `Reset layout`, not `Reset Layout` or `RESET LAYOUT`. Preserve proper
nouns and established acronyms. Follow a platform convention such as title case for native menu commands only when the
platform integration benefits from it, and apply that convention consistently within the component class.

ALL CAPS can provide restrained typographic emphasis for very short section labels, eyebrows, statuses, established
acronyms, and code-like identifiers. Its compact shape and measured tracking can form a level similar to bold type, but
it does not belong on buttons, long headings, sentences, or dense lists. Do not combine uppercase, strong color, and
bold weight in the same region, and do not transform every string automatically: product names, acronyms, and
localized content must preserve their intended casing.

Labels, buttons, menu items, tabs, headings, placeholders, and short states do not take a final period. Complete
explanatory, warning, and error sentences do. Avoid exclamation marks in routine success and failure messages. In
Chinese, use full-width punctuation in sentences and omit terminal punctuation from short control labels by the same
semantic rule.

Use the single ellipsis character (`…`), not three periods. Append it to every button or menu item that opens a dialog,
sheet, or separate window, and to a command that requires more input or choices before it can complete, such as
`Settings…` or `Export…`. An immediately executed command does not take an ellipsis. Use an indeterminate progress
indicator, not decorative dots, to communicate ongoing work.

Errors should say what happened and, when useful, the next recovery action. Success feedback should name the resulting
state only when that state is not already visible. Prefer `Couldn’t save. Check your connection and try again.` to a
technical code or a long apology; omit a `Saved successfully` toast when the document visibly becomes saved.

## Internationalization and platform fit

Accessibility (A11y) names and labels may remain in English; localization is not required for these strings. Keep the
item's own label when naming a control that acts on it, even when that label is localized. This exception does not
apply to visible UI copy.

Copy must survive expansion, CJK typography, right-to-left scripts, and different shortcut notation. Do not size a
control from one English label. Keep text out of raster assets, avoid concatenating translated fragments, and let
labels wrap or truncate only where the product defines a recovery path such as a tooltip.

Respect platform differences that carry meaning: Command versus Control, native window decorations, system
appearance, scrollbar behavior, menus, notification capabilities, and on phones the system header, back gesture, and
alerts. Keep the product's information architecture stable across platforms, but do not erase familiar platform
behavior for superficial pixel equality.

NSH apps run on phones, tablets, desktops, and the web, and often inside a host app. Design for each:

- **System UI keeps the platform's look.** On iOS and Android a page's header is the system's (`NavPage`'s `title` and
  header options); the desktops and the web show the page's `header` slot, which the app draws. Give every page both
  ([Navigation](https://nsh.dev/versions/main/docs/navigation.md#navpage-and-the-header)). Confirmations use `AlertDialog`; the status bar follows the
  page or dialog on top (`statusBar`).
- **The host's theme.** An embedded app can be given its host's theme; classes and Rust bindings that read tokens
  follow it natively ([Theme tokens](https://nsh.dev/versions/main/docs/tailwind.md#theme-tokens)).
- **Safe areas and the keyboard.** Keep content inside the safe area (`env(safe-area-inset-*)`, `safeAreaInsets()`) and inputs
  above the software keyboard (`env(keyboard-inset-height)`) ([Device and environment](https://nsh.dev/versions/main/docs/device-and-environment.md)).
- **Appearance, text size, and motion.** Every surface works in light and dark (`dark:`, `colorScheme()`), at the
  user's text size, and with reduced motion (`motion-reduce:`, `reduceMotion()`).
- **Right to left.** The layout direction follows the locale, and the `direction` style sets it for a view and its
  subtree; start and end properties mirror ([Right to left](https://nsh.dev/versions/main/docs/layout.md#right-to-left)).
- **Touch and pointer.** Touch targets are at least 44 × 44 points; hover and tooltips exist only with a pointer.

```rust
use nsh_base::nav_page;

nav_page()
    .title("Inbox")
    .header(page_header("Inbox"))
    .child(inbox())
```

```tsx
import { NavPage } from "nsh/base";

<NavPage title="Inbox" header={<PageHeader title="Inbox" />}>
  <Inbox />
</NavPage>
```

## Guidance for AI-generated interfaces

An AI changing an NSH interface should first inspect the nearest feature, the app's components and theme tokens, and
the component documentation and declarations (`.nsh/types`). It should state the primary task, state owner, component
composition, and keyboard and touch paths before generating code. It must not infer an API from React, React Native
or Shadcn examples or invent an NSH prop or method because the name seems plausible; `nsh check` and the build's class
check report what does not exist.

AI output is incomplete until a human can explain why the hierarchy, density, component choice, and exceptional
literal values belong in this product. A visually plausible screenshot is not proof: keyboard and touch behavior,
focus, dynamic content, themes, resizing, text size, and failure states are part of the design.

## Accessibility checklist

Before considering a screen complete, verify that:

- every action is reachable and operable by keyboard, touch, and screen reader;
- focus order follows visual and task order;
- focus remains visible and is restored after overlays;
- controls have accessible names; icon-only controls use tooltips when their meaning, scope, or shortcut needs
  explanation;
- text and meaningful boundaries have sufficient contrast;
- status is not communicated by color alone;
- disabled and read-only states are distinguishable;
- labels, errors, and descriptions remain near their controls;
- content remains usable with longer translations, right to left, and larger text;
- touch targets are at least 44 × 44 points, and pointer targets are comfortably sized even in a dense layout.

## Design review checklist

A review does not inventory components; it judges whether the interface made the right decisions. Ask, in order:

1. **Is the task clear?** Can a new user recognize the purpose, primary action, and next step without learning,
   guessing, or experimenting?
2. **Does every action keep its promise?** Do the label, control, state, scope, feedback, and result describe one
   consistent outcome?
3. **Is hierarchy decisive and restrained?** Does the core feature receive the space it deserves while strong color,
   bold type, badges, alerts, and primary buttons remain scarce?
4. **Could the interface do less, better?** Can an entry point, option, or state be removed, combined, or deferred
   without weakening the complete task?
5. **Is the structure exact?** Do peers share alignment spines, equal gaps stay equal to the rendered pixel, and
   scrollbars sit at the edge of their actual scrolling region?
6. **Does it follow the component system?** Do standard controls retain their geometry, states, keyboard behavior, and
   dismissal model, with appearance supplied by theme and scale tokens?
7. **Does it remain usable in every state and constraint?** Verify keyboard, touch and focus behavior,
   empty/loading/failure/permission states, longer translations, larger text, right to left, both appearances,
   minimum window size, and reduced motion.
8. **Has it been tested on real platforms?** Complete the task with real components, copy, and representative content
   on each platform it ships to (`nsh run --target …`, `nsh test --target …`)—not only an ideal screenshot.

Source: https://nsh.dev/versions/main/docs/design-guides

---

# Coding Guides

This guide describes the application architecture and code patterns that have proved durable in Native Shell apps. It
is written for both engineers and coding agents: developers of NSH apps (TSX modules, Rust components, native apps
that embed NSH) and authors of component libraries built on `nsh/base`. Read the Design Guides first: code structure
should preserve product intent, not replace it.

This is a normative guide. **Must** marks lifecycle, correctness, or ecosystem constraints; **should** is the default
architecture and requires a concrete reason to depart from it. Current source, the reference pages and the
declarations in `.nsh/types` remain authoritative for exact signatures.

## Make the common path inexpensive

**Design principle: choose framework types and ownership so ordinary component use is inexpensive by default.**
Developers should be able to build and reuse UI without adding a cache at every call site. Components that run once
and [signals](https://nsh.dev/versions/main/docs/reactivity.md) read where they are used are examples: a component builds its part of the tree once,
and afterwards only the bindings that read a changed signal run again, so the common path avoids repeated work. The
reactive graph, the renderer, layout and lists are native, and one turn of the app's code becomes one batch of native
operations. Small costs still multiply across elements and updates, above all in TSX, whose own code runs in an
interpreter; measure exceptional hot paths before adding caches ([Performance](https://nsh.dev/versions/main/docs/performance.md)). Neither choice
promises zero cost. The [state ownership rules](#state-ownership) and later rendering sections explain the mechanics.

## Architecture at a glance

![NSH application architecture: the App Shell, Pages and App Components above a Component Library, nsh/base and nsh; dependencies point downward.](https://nsh.dev/versions/main/diagrams/application-layers-light.svg)

Dependencies point downward. Higher layers own domain meaning and orchestration; lower layers own reusable
presentation or behavior. Do not make a reusable component depend on an app page, or make a component library depend
on one app's theme ([Three layers](https://nsh.dev/versions/main/docs/architecture.md#three-layers)).

Use these boundaries:

- **app shell:** the entry (`App.tsx`, or `nsh.json` `"root"`) composes the root and the navigation stacks while
  keeping page logic out;
- **page:** one `NavPage` with its content, its dialogs and the work it starts;
- **app component:** a repeated domain-aware pattern;
- **component library:** styled, general-purpose UI, the app's own or the community's, built on `nsh/base`;
- **`nsh/base`:** reusable behavior without product presentation: navigation, dialogs, popovers, menus, sheets, a
  press target;
- **`nsh`:** the primitives, styles, layout, reactivity and the environment.

### Lay out an app's files

An app's files follow NSH's conventions, so there is nothing to configure: `App.tsx` is the entry and `nsh.json`
sits beside it, and both are found by convention.

```text
App.tsx            # the entry, by convention: mount(App)
nsh.json
Cargo.toml         # the app's crate, with Rust components ("rust": ".")
src/
  lib.rs
pages/
  Inbox.tsx
  Compose.tsx
  Settings.tsx
components/
  Card.tsx
store.ts
```

- `pages/` holds one file per `NavPage`. A page grows into more files only when it needs them.
- `components/` holds the app's reusable components, the ones several pages use.
- `store.ts` holds the app's state: its signals and the functions that change them. Pages read the signals and call
  the functions.
- Tests are `*.test.tsx` files beside what they test (`App.test.tsx`, `pages/Inbox.test.tsx`).
- `Cargo.toml` and `src/lib.rs` are the app's own crate, with its Rust components (`nsh.json` `"rust": "."`); its
  `#[native_module]` in `src/lib.rs` names what TSX imports. An app written only in Rust is the same Cargo project,
  with its root component in `src/lib.rs` ([Project structure](https://nsh.dev/versions/main/docs/project-structure.md)).

The app shell composes pages but contains little page logic. Pages read the store's signals and call its functions;
they never write another page's state. Keep the store's signals private and export what reads and changes them, so the
mutable state stays behind its public functions:

```rust
/// The app's workspace: its state stays behind these functions.
#[derive(Clone, Copy)]
pub struct Workspace {
    name: Signal<SharedString>,
}

impl Workspace {
    /// A workspace named "Untitled".
    pub fn new() -> Self {
        Self { name: signal(SharedString::from("Untitled")) }
    }

    /// Its name (tracked where it is read).
    pub fn name(&self) -> SharedString {
        self.name.get()
    }

    /// Renames it.
    pub fn rename(&self, name: impl Into<SharedString>) {
        self.name.set(name.into());
    }
}
```

```tsx
// store.ts
import { signal } from "nsh";

const name = signal("Untitled");

/** The workspace's name (tracked where it is read). */
export const workspaceName = () => name();

/** Renames the workspace. */
export function renameWorkspace(next: string) {
  name.set(next);
}
```

A page may hold the workspace and pass its id to search; search does not need the workspace's whole collection or its
private signals. A simple acyclic dependency shape is:

```text
App.tsx ──▶ pages/ ──▶ store.ts
              └──────▶ components/ ──▶ nsh/base, nsh
```

Pages may depend on the store and on components, but not on the shell or on another page's private parts. If one page
must change what another shows, do it through the store. These boundaries let different engineers or AI agents work
on separate pages in parallel with fewer file conflicts and less shared-state coupling; the store still requires
coordination.

## Bootstrap and root ownership

Mount the app once, and give the root the whole surface: a TSX entry calls `mount(App)`, a Rust app names its root
component in `nsh.json` (`"root": "App"`). The root fills the surface with `flex: 1` and a background from the theme:

```rust
#[component]
pub fn App() -> impl IntoElement {
    provide_context(Workspace::new());
    view()
        .flex_1()
        .bg(move || theme().background)
        .child(inbox())
}
```

```tsx
import { mount, View } from "nsh";

mount(() => (
  <View class="flex-1 bg-background">
    <App />
  </View>
));
```

The root coordinates what belongs to the whole surface: the navigation stack, the dialogs, popovers, menus, sheets and
tooltips shown over everything in it, and the safe area. Do not mount a second root for each page inside one surface.
One surface is one engine: each `NshAppView`, `NshView` or `AppView` a native app embeds runs its own VM, its own module
state and its own reactive graph, so several surfaces in one host app never share state by accident.

## Understand what runs once and what runs again

NSH is retained state with declarative construction, on Solid's model ([Reactivity](https://nsh.dev/versions/main/docs/reactivity.md)). A signal
survives across updates; a component body describes its part of the tree once, when it is created. Keep that
distinction explicit:

| You write | Runs | Runs again when |
| --- | --- | --- |
| A component body | Once, when it is created | Never |
| A binding: a closure (Rust) or an expression that calls or reads a property (TSX) where a value goes | Once | A signal it read changes; only that prop or child updates |
| `computed(fn)` | When created | A signal it read changes |
| `effect(fn)` | After the elements of the pass exist | A signal it read changes |
| A row of `each` / `<Each>` | When its key first appears | Never; its item and index signals change |
| A cell of `virtual_list` / `<List>` | Once per cell | Never; the cell is given other rows |

- the component that runs is the **owner**: effects, computed values, tasks, timers, key bindings and cleanups created
  while it runs belong to it and are disposed with it;
- **context** (`provide_context` / `use_context`, `context()` and `<Ctx.Provider>`) gives a subtree a value without
  implying that the elements reading it own it;
- a Rust component's **`Scope`** (`cx`) emits its events and reads the insets it is given;
- **refs** (`element_ref()`, `ref`) name a host element for imperative calls (`focus()`, `scroll_to()`, `measure()`);
- layout and measurement are later, native phases; use `onLayout` and `measure()` only when resolved geometry is
  genuinely required.

Never read a context in an event handler or a timer, where there is no component to look it up from: read it in the
body and keep what it gave. Retain typed handles (signals, resources, refs, domain ids), which are `Copy` in Rust and
stop doing anything once their owner is gone.

## Choose the right unit

### Use a plain function for value-like elements

**Default to a plain function for lightweight, reusable pieces of UI.** The caller supplies current props and
handlers, the function returns elements, and nothing of it remains but the bindings it made. Its arguments are its
props; the displayed label, value and callbacks come from the caller's current state. It still runs once, like any
component: what changes afterwards are its bindings.

```rust
fn empty_state(title: impl Into<SharedString>) -> impl IntoElement {
    view()
        .gap_2()
        .items_center()
        .child(text(title.into()).text_color(move || theme().muted_foreground))
}
```

```tsx
function EmptyState(props: { title: string }) {
  return (
    <View class="items-center gap-2">
      <Text class="text-muted-foreground">{props.title}</Text>
    </View>
  );
}
```

### Use a component for retained behavior

Use a `#[component]` (or a TSX component that creates signals) when a piece of UI owns persistent state or an
independent lifecycle: signals, effects, async work, timers, key bindings. Create that state in the component body,
once, never inside a binding.

```rust
#[derive(Debug, Clone, PartialEq, Props)]
pub struct SearchProps {
    /// Shown while the field is empty.
    pub placeholder: Prop<SharedString>,
}

#[component]
pub fn Search(props: SearchProps) -> impl IntoElement {
    let query = signal(String::new());
    input()
        .value(move || query.get())
        .on_change(move |text: &str| query.set(text.to_owned()))
        .placeholder(move || props.placeholder.get().to_string())
}
```

```tsx
function Search(props: { placeholder: string }) {
  const query = signal("");
  return <Input value={query()} onChange={({ value }) => query.set(value)} placeholder={props.placeholder} />;
}
```

A `#[component]` has typed props (`#[derive(Props)]`) and events (`#[derive(Event)]`); TSX imports it with
declarations generated from them. Retained state that TSX uses with `new` (a ledger, a parser, a session) is a
`#[class]`, and functions are a `#[module]` ([Building with Rust](https://nsh.dev/versions/main/docs/rust.md#extending-a-rust-app-with-tsx)). Write the
parts an app uses most, component libraries and demanding logic in Rust, which is native code from start to end; keep
TSX for what changes often or is delivered at run time.

Do not turn every visual fragment into a component. Component boundaries have lifecycle and coordination costs; use
them where retained identity matters.

### Elements, views, and behavior systems are different

Do not force every component into one template. The ecosystem contains:

- semantic elements such as `Button`, `Switch` and `MenuItem`;
- compound behavior roots such as `Dialog`, `Popover`, `Menu`, `ContextMenu`, `Sheet` and `NavStack`;
- stateful systems such as `Input`, `List`, `TextView` and a navigation stack's state;
- infrastructure such as overlays and their placement, virtualization, scrolling, safe areas, the keyboard and
  animation.

An element may be internally complex and still be value-like to its caller. A stateful system may expose render
functions so apps own presentation without reimplementing behavior. Choose the public seam from the behavior, not
from how many views appear in its output.

## State ownership

### Own persistent UI text with `SharedString`

**In Rust, must prefer `SharedString` for UI text retained across updates or callback closures**, including component
labels, titles and placeholders: props take it (`Prop<SharedString>`), and cloning it into a binding does not copy the
text. For a mutable editing buffer or text being assembled with formatting, use `String` and convert when the result is
ready; for temporary read-only access during one call, use `&str`. In TSX, strings are the app's own values; keep text
that is computed from state in a `computed` or a closure instead of rebuilding it in several places.

For immutable response text that the UI will retain, keep the received value intact and put derived or formatted
presentation text in a separate domain value instead of rewriting the response.

Put each state in the narrowest owner that can keep it correct:

- domain state belongs to the store (`store.ts`) or the app's crate;
- transient view state belongs to the component that renders it, as a signal;
- reusable behavioral state belongs to the component designed for it (a `Menu` or `Popover` without `open` keeps its
  own);
- state a subtree shares is a signal provided through [context](https://nsh.dev/versions/main/docs/reactivity.md#context);
- what outlives a run belongs in [storage](https://nsh.dev/versions/main/modules/nsh.md#storage) or on a server.

Prefer controlled values for ordinary selection and toggles: pass the current value into the component, receive a
requested change, update the owner, and the bindings follow. A callback reports intent; it should not create a second
hidden source of truth.

```rust
switch()
    .checked(show_hidden)
    .on_change(move |next: &bool| show_hidden.set(*next))
    .child(text("Show hidden files"))
```

```tsx
<Switch checked={showHidden()} onChange={({ checked }) => showHidden.set(checked)}>
  <Text>Show hidden files</Text>
</Switch>
```

There is nothing to notify: writing a signal updates exactly the bindings that read it. A Rust component emits a
semantic event that its owner should handle with `cx.emit(..)`; an effect follows a signal for as long as its owner
lives. Write several fields that form one invariant in one [`batch`](https://nsh.dev/versions/main/docs/reactivity.md#batch), so effects and computed
values see them at once.

A controlled component of the app's own follows the same contract. A quantity stepper, a domain control written once
in Rust and placed from Rust and TSX:

```rust
use nsh_base::{button, theme};
use nsh_core::prelude::*;

/// The props of [`QuantityStepper`].
#[derive(Debug, Clone, PartialEq, Props)]
pub struct QuantityStepperProps {
    /// The quantity: the app owns the value.
    #[prop(default)]
    pub value: Prop<u32>,
    /// The smallest quantity (0 when left out).
    #[prop(default)]
    pub min: Prop<u32>,
    /// The largest quantity (99 when left out).
    #[prop(default = 99)]
    pub max: Prop<u32>,
    /// What screen readers say for the button that takes one away.
    pub decrement_label: Prop<SharedString>,
    /// What screen readers say for the button that adds one.
    pub increment_label: Prop<SharedString>,
}

/// What a [`QuantityStepper`] reports.
#[derive(Debug, Clone, PartialEq, Event)]
pub enum QuantityStepperEvent {
    /// The user asked for another quantity; the owner sets `value`.
    Change(u32),
}

/// A quantity with a button to take one away and one to add one.
#[component]
pub fn QuantityStepper(props: QuantityStepperProps, cx: Scope<QuantityStepperEvent>) -> impl IntoElement {
    // Read untracked: the user's act, measured against the owner's current value.
    let step = move |delta: i64| {
        let value = props.value.get_untracked();
        let (min, max) = (props.min.get_untracked(), props.max.get_untracked());
        let next = (i64::from(value) + delta).clamp(i64::from(min), i64::from(max)) as u32;
        if next != value {
            cx.emit(QuantityStepperEvent::Change(next));
        }
    };
    view()
        .flex_row()
        .items_center()
        .gap_3()
        .child(step_button(
            "−",
            move || props.decrement_label.get(),
            move || props.value.get() <= props.min.get(),
            move || step(-1),
        ))
        .child(text(move || props.value.get().to_string()).text_color(move || theme().foreground))
        .child(step_button(
            "+",
            move || props.increment_label.get(),
            move || props.value.get() >= props.max.get(),
            move || step(1),
        ))
}

fn step_button(
    symbol: &'static str,
    label: impl Fn() -> SharedString + 'static,
    disabled: impl Fn() -> bool + 'static,
    on_press: impl Fn() + 'static,
) -> impl IntoElement {
    button()
        .disabled(disabled)
        .accessibility_label(move || Some(label()))
        .on_press(on_press)
        .w(px(32.0))
        .h(px(32.0))
        .items_center()
        .justify_center()
        .rounded(move || theme().radius)
        .bg(move || theme().muted)
        .active(|s| s.opacity(0.6))
        .disabled_style(|s| s.opacity(0.4))
        .child(text(symbol).text_color(move || theme().foreground))
}

// The owner:
let quantity = signal(1_u32);
quantity_stepper()
    .value(quantity)
    .min(1)
    .max(10)
    .decrement_label("Fewer")
    .increment_label("More")
    .on_change(move |next: &u32| quantity.set(*next))
```

```tsx
import { signal } from "nsh";
import { QuantityStepper } from "my-app";   // the Rust component: src/lib.rs has #[native_module("my-app")]

function CartRow() {
  const quantity = signal(1);
  return (
    <QuantityStepper
      value={quantity()}
      min={1}
      max={10}
      decrementLabel="Fewer"
      incrementLabel="More"
      onChange={({ value }) => quantity.set(value)}
    />
  );
}
```

The same contract in TSX, a component in `components/`:

```tsx
import { Text, View } from "nsh";
import { Button } from "nsh/base";

export interface QuantityStepperProps {
  /** The quantity: the app owns the value. */
  value: number;
  /** The smallest quantity (0 when left out). */
  min?: number;
  /** The largest quantity (99 when left out). */
  max?: number;
  /** What screen readers say for the button that takes one away. */
  decrementLabel: string;
  /** What screen readers say for the button that adds one. */
  incrementLabel: string;
  /** The user asked for another quantity; the owner sets `value`. */
  onChange?: (e: { value: number }) => void;
}

export function QuantityStepper(props: QuantityStepperProps) {
  const min = () => props.min ?? 0;
  const max = () => props.max ?? 99;
  const step = (delta: number) => {
    const next = Math.min(max(), Math.max(min(), props.value + delta));
    if (next !== props.value) props.onChange?.({ value: next });
  };
  const buttonClass = "size-8 items-center justify-center rounded-(--radius) bg-muted active:opacity-60 disabled:opacity-40";
  return (
    <View class="flex-row items-center gap-3">
      <Button disabled={props.value <= min()} accessibilityLabel={props.decrementLabel} onPress={() => step(-1)} class={buttonClass}>
        <Text class="text-foreground">−</Text>
      </Button>
      <Text class="text-foreground">{props.value}</Text>
      <Button disabled={props.value >= max()} accessibilityLabel={props.incrementLabel} onPress={() => step(1)} class={buttonClass}>
        <Text class="text-foreground">+</Text>
      </Button>
    </View>
  );
}
```

### Keep ownership links and subscriptions bounded

A component owns what it creates, and everything it created goes away with it: when its `<If>` branch hides, its row
is removed or its page is popped. In Rust, tasks, timers and intervals (`spawn`, `set_timeout`, `set_interval`) and key
bindings (`on_key`) end with the owner they were made under; in TSX, register the stop with
[`cleanup`](https://nsh.dev/versions/main/docs/reactivity.md#cleanup) or return it from the effect. Listening is `on(event, listener)`
(`host.on(name, listener)`, `BackHandler.on("press", listener)`), which returns a function that stops it
(`() => void`, from Rust a `Stop`), and what is registered while a component renders goes away with the component, as
`keymap.bind`'s bindings do.

When something keeps running unexpectedly, first inspect effects and computed values created outside a component (in
an event handler or a timer callback they have no owner and live forever), listeners registered without their stop,
and work started from a store that no component owns. A dropped `resource` load is aborted (`info.signal` in TSX);
it does not keep its component alive. These are common places to start, not an exhaustive list.

Do not write a signal merely because a value was read or derived. Avoid unconditional writes from a binding or an
effect that reads the same signal: it runs itself again until NSH stops it with an error. A value computed from other
state is a `computed`, not an effect that writes a second signal.

### Avoid state feedback loops

Text input, selection, filters and controlled popups commonly have two paths: an external owner updates the value, and
user interaction requests a new value. Do not send an owner-supplied value back through the user callback during sync.
Read the owner's current value untracked when handling the user's act (`props.value.get_untracked()` in Rust, as
above; a TSX event handler is already untracked) and compare it with the next one, so each logical change is reported
once. Make callbacks re-entrancy-safe when a callback can synchronously close, replace or update the component that
invoked it.

## Stable identity

A key is part of behavior. It gives a row, a page or a repeated control stable identity, and decides which one keeps
its state, its focus and its measurements when the data changes.

- Use stable domain ids for rows, tabs, pages and repeated controls: `each(projects, |p| p.id, ..)`,
  `<Each of={projects()} key={(p) => p.id}>`, a list's `keyExtractor`.
- Namespace test ids with their owning object when the same control repeats (`delete-${project.id}`).
- Never derive identity from a translated label or a mutable list index when items can be inserted or reordered.
- Do not generate a fresh random key or id while rendering.

```rust
each(projects, |p| p.id, move |project, _index| {
    let id = project.get_untracked().id;
    button()
        .on_press(move || delete(id))
        .child(text("Delete").test_id(&format!("delete-{id}")))
})
```

```tsx
<Each of={projects()} key={(p) => p.id}>
  {(project) => (
    <Button onPress={() => remove(project().id)}>
      <Text testID={`delete-${project().id}`}>Delete</Text>
    </Button>
  )}
</Each>
```

A changed key means a changed UI identity. Treat that reset as deliberate.

The same rule applies to navigation routes, list keys, storage keys and test ids. A route that stays in `setRoutes`
keeps its page and its state; if two independently retained behaviors share a key, they can overwrite each other's
state; if one behavior changes keys every update, it never accumulates state.

## Rendering and composition

Keep a component body declarative: read current state, derive presentation values, and compose elements. Move domain
operations, parsing and non-trivial mutation to named functions of the store or the app's crate.

```rust
#[component]
pub fn ProjectPage() -> impl IntoElement {
    view()
        .flex_1()
        .child(toolbar())
        .child(content())
}
```

```tsx
function ProjectPage() {
  return (
    <View class="flex-1">
      <Toolbar />
      <Content />
    </View>
  );
}
```

Extract a helper when it names a meaningful region and reduces the amount of state a reader must hold at once.
Extract a new component when the region has its own reusable contract or retained lifecycle, not merely because a
builder chain or a JSX block is long.

Use the typed style methods and the components' builders consistently in Rust, and classes in TSX. Prefer
`.when(..)` / `.when_some(..)` (Rust) and `classList` (TSX) for small conditional refinements; use `when` / `<If>`
when branches represent substantially different interfaces, since a ternary in a closure builds its branch again
whenever anything it reads changes.

Compose from the standard semantic component before building a custom surface. Do not reproduce a menu, a popover, a
sheet or a dialog from generic views merely to match one screenshot: `Menu`, `ContextMenu`, `Popover`, `Sheet`,
`Tooltip` and `Dialog` from `nsh/base` preserve placement, focus transfer, keyboard navigation, selection, disabled
state, dismissal on Escape and back, and the accessibility contract. If the standard component cannot express a
recurring valid pattern, improve its explicit API instead of styling arbitrary descendants at each call site.

Render functions supplied by app code should be side-effect-free. A list's row, a `TextView`'s `renderCodeBlock` or a
menu's items may run whenever their owner needs a cell, a part or an opening. They must not perform a business
operation, append data or start an unbounded subscription.

## Behavior and presentation boundary

The durable Base rule is:

> Base owns reusable behavior and the structure required to implement it. The presentation layer owns the product's
> visual language.

"Unstyled" does not mean "one empty view." Overlay placement, keyboard navigation, editing, virtualization, back
navigation, dismissal and safe areas require internal structure and state. Moving that work to every caller would not
create flexibility; it would duplicate fragile behavior.

Conversely, Base must not choose brand colors, typography, density, final icons, component variants, strings or
application composition. Expose presentation through `class` / `style` on the main part, `<part>Class` /
`<part>Style` for every other part, typed state styles (`active`, `hover`, `focus`, `selected`, `checked`, `disabled`),
named slots (`trigger`, `header`, `footer`) and render functions. Do not inspect arbitrary descendants to discover
titles, descriptions or close buttons: make semantic parts explicit, and take every label as a prop or a child.

## Theme and styling

Read semantic values from the theme and apply layout with the typed style methods in Rust and Tailwind classes in TSX
([Tailwind](https://nsh.dev/versions/main/docs/tailwind.md), [theme tokens](https://nsh.dev/versions/main/docs/tailwind.md#theme-tokens)):

```rust
view()
    .bg(move || theme().background)
    .text_color(move || theme().foreground)
    .border_1()
    .border_color(move || theme().border)
    .rounded(move || theme().radius)
```

```tsx
<View class="rounded-(--radius) border border-border bg-background text-foreground" />
```

Rules:

- do not hard-code product colors, corner radii, spacing, or control geometry;
- app code must not introduce raw hex, `rgb` / `rgba` or `hsla` values; read a semantic color from `theme()` or a
  token class (`bg-primary`), or add the missing role to the app's theme file;
- app layout should use the spacing and type scales (`p-2`, `gap-3`, `w-64`, `text-sm`; `.p_2()`, `.gap_3()`,
  `.w_64()`, `.text_sm()`) instead of arbitrary values (`p-[13px]`, `px(13.0)`);
- classes mean exactly what they mean in Tailwind CSS v4, and style values what the
  [style reference](https://nsh.dev/versions/main/modules/style-reference.md) gives them (CSS's, in native forms: numbers are points); an
  `unknown class` warning is a finding to fix;
- use semantic tokens for meaning, not palette position;
- keep state-independent geometry in the ordinary builder chain or class string;
- use `active:`, `hover:` and `focus:` (`.active(..)`, `.hover(..)`, `.focus(..)`) for runtime interaction states;
  they apply natively, with no round trip to app code;
- use a component's semantic state styles (`selected:`, `checked:`, `disabled:`) for checked, selected, pressed, or
  disabled appearance;
- keep popup ownership in explicit state (`open` with `onOpenChange`) so its trigger can render the open or pressed
  appearance until dismissal;
- keep component variants few and meaningful rather than adding a variant for every call site;
- bind primary styling to the decision area's real default commit and its return-key action; do not derive it from
  action count, frequency, or toolbar position;
- keep badge and alert variants semantic and scarce. Ordinary metadata stays neutral; do not map every enum case or
  section to a different color merely because a variant exists.

The effective precedence is the element's own style, then the state styles, later states winning, with `disabled`
over all. Later layers only replace fields they set.

Prefer the theme's semantic tokens for new app-owned presentation. Every name in the app's theme file is a token, as a
variable of Tailwind's `@theme` is (`"up": "#16a34a"` gives `text-up`, `bg-up/30`, `token("up")` in TSX and
`theme().color("up")` in Rust), and the theme has light and dark values, so a token follows the appearance with no
`dark:` class. Name tokens after roles, not components, so they do not become the extension point
for every widget.

Change the theme through the app's theme file (`nsh.json` `"theme"`), or let the embedding app give its own: classes
naming tokens and Rust bindings reading `theme()` are restyled natively whenever it changes, with no JavaScript
running. Code that copies a token's value into a signal of its own stops following it.

An outward focus ring needs physical room. An ancestor with `overflow: hidden` (`overflow-hidden`) clips it. Prefer
layouts that leave room; if a product must clip heavily, draw the focused state inside the control instead of silently
hiding all keyboard focus.

### The user's text size is the app's zoom

Text follows the user's text size (Dynamic Type, Android's font scale, the desktops' settings): `fontScale()` in TSX,
`font_scale()` in Rust, both reactive. The type scale (`text-sm`, `text-base`: 16 points, the body size) sets
the reference, and the user's setting scales it. This deliberately follows
the useful part of Tailwind's model: named type, spacing and size steps instead of unrelated point constants.

Let text containers grow with their text: give them minimum heights and padding rather than fixed heights. A custom
component that combines scaled text with fixed geometry around it must document why that part should not grow.

Treat every arbitrary point value and raw color constructor in app UI as a review finding. Accept it only for a
documented physical or platform boundary, measured runtime geometry, raster or data color, or the theme definition
itself. Convenience and matching a screenshot are not valid exceptions.

Anything cached from resolved layout must include the font scale in its invalidation key, directly or through a
revision that changes with it: row heights a list was told, text measurements, popup geometry, icon sizes derived from
text and custom canvas metrics.

## Events, commands, and focus

Use presses for activation: `onPress`, `onLongPress`, `onPressDown` and `onPressUp` mean the same with a finger, a pen,
a mouse or the keyboard. Use touch handlers and gestures only for what follows the finger (a pan, a drag). Use
keyboard shortcuts (`keymap.bind`, `on_key`) and menu items for commands that should support key bindings, menus, or
dispatch from multiple inputs. Keep the handlers close to the page that owns the command.

Model one logical command once. A `Button`, a `Menu` item, a `ContextMenu` item, an application menu item of
`nsh/desktop` and a keyboard shortcut should call the same function of the store instead of copying five mutations.
Derive their label, icon, shortcut and disabled state from one command policy where practical (`key_label("mod+s")`
writes a shortcut the platform's way), so the entry points cannot disagree. The menu owns navigation and dismissal; the
page still owns whether the command is allowed and what it does.

```rust
on_key("mod+s", move |_| save());
view()
    .child(button().on_press(save).child(text("Save")))
    .child(
        menu()
            .trigger(view().px_3().py_2().child(text("File")))
            .child(menu_item().on_select(save).child(text(format!("Save  {}", key_label("mod+s"))))),
    )
```

```tsx
keymap.bind("mod+s", save);

<View>
  <Button onPress={save}><Text>Save</Text></Button>
  <Menu trigger={<View class="px-3 py-2"><Text>File</Text></View>}>
    <MenuItem onSelect={save}><Text>Save  {keymap.label("mod+s")}</Text></MenuItem>
  </Menu>
</View>
```

Preserve semantic roles in the element choice. Use `Button` for commands even when the desired treatment is quiet;
give it a quiet style instead of replacing it with a link. NSH apps reserve the `link` role for targets opened outside
the app, such as a URL or an email address; use navigation for an in-app destination and `Button` for a command.

Only stop propagation (`stopPropagation()` on a touch event) when a nested interaction must prevent its parent from
handling the same touch. Blanket propagation stops break scrolling, presses and gestures in ways that are difficult
to diagnose.

**The main thread never waits for app code.** When the system needs an answer on the spot (may this page pop, may this
sheet or popover close, may this text change), NSH answers natively from props mounted beforehand, and an event tells
the app afterwards. So a decision is a prop, set as soon as it is known, not a callback that returns true or false:
`popOnBack={!dirty()}` with `onBackPress` to confirm ([popOnBack](https://nsh.dev/versions/main/docs/navigation.md#keeping-the-user-on-a-page-poponback)),
`closeOnEscape` and `closeOnBackdropPress` with `onCancel` to hear the attempt, `maxLength` on an input, `disabled` on
a button.

A menu item's `shortcut` (`nsh/desktop`) binds its key while the menu is set, and the menu shows it in the platform's
style; a `keymap` binding of the same keystroke comes before it. Give each keystroke one owner, and set the application
menu again when its items or shortcuts change.

Make focus ownership explicit:

- `Button`, `Switch` and menu items are keyboard focus stops on the desktops and the web; build controls on them rather
  than on bare views;
- move focus with a ref's `focus()` from an event or an effect that follows a state change, and move the screen
  reader's with `set_accessibility_focus()` (Rust) or `setAccessibilityFocus` from `nsh` (TSX);
- render a visible `focus:` state;
- do not request focus unconditionally while rendering.

Composite widgets should implement the complete navigation model (arrow movement, Home / End or page movement where
appropriate, confirmation, cancellation and Tab behavior) rather than a few isolated shortcuts.

Overlays dismiss from the top: Escape and the Android back button go to the top overlay that listens (`onCancel`).
Handle rapid close and open sequences without acting on an intermediate, already-closing surface.

## Async work and side effects

Start asynchronous work from an event, an effect or a [`resource`](https://nsh.dev/versions/main/docs/reactivity.md#resource), not as an unconditional
side effect of a component body. An effect tracks only what it reads synchronously: read the signals first, then start
the work. When the work completes, update state through signals, accept that the component may be gone, and write
coherent changes together.

Keep recurring work under an owner so its going away cancels it: Rust tasks and timers end with their owner, TSX timers
stop in `cleanup`. A one-shot task that must finish independently can be started from the store, but it gives up that
cancellation. Handle errors and failed requests explicitly.

Represent async operations with explicit states: a resource's `state()` is `unresolved`, `pending`, `ready`,
`refreshing` or `errored`. Preserve usable previous data during refresh: a resource keeps its value while it loads
again. Prevent duplicate destructive submissions and surface recoverable errors in the UI; do not rely on logs as user
feedback.

```rust
let results = resource(
    move || {
        let q = query.get();
        (!q.is_empty()).then_some(q)
    },
    |q, _info| async move {
        let response = fetch(format!("https://api.example.com/search?q={q}")).await?;
        if !response.ok() {
            return Err(format!("HTTP {}", response.status()));
        }
        Ok(response.text())
    },
);
```

```tsx
const results = resource(
  () => query() || undefined,
  async (q, { signal }) => {
    const response = await fetch(`https://api.example.com/search?q=${encodeURIComponent(q)}`, { signal });
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    return (await response.json()) as SearchHit[];
  },
);
```

Move expensive parsing or computation out of TSX handlers: into a `computed`, off the interaction path, or into Rust.
Results can arrive after the query, the page or the selection has changed: a resource drops superseded loads, and work
of your own attaches a revision or an identity and rejects stale results rather than applying them to new state.

## Layout, measurement, and scrolling

A view lays out its children in a column, and children stretch across it by default; `class="flex"` (`.flex_row()`)
is a row, as in CSS. A row of controls wants its children centered (`items-center`), which says so. A row of
full-height columns keeps the default stretch, so a column fills the row's height and its header stays at the top:

```rust
view()
    .flex_row()
    .flex_1()
    .child(sidebar())
    .child(content())
```

```tsx
<View class="flex flex-1">
  <Sidebar />
  <Content />
</View>
```

Most UI should use layout rather than measuring itself ([Layout](https://nsh.dev/versions/main/docs/layout.md)). Measurement (`onLayout`, `measure()`)
is a deep behavior tool for overlays, virtualization, editors, charts and similar components whose correctness depends
on resolved geometry.

- Put measurement and geometry in the layer that owns the behavior.
- Observe layout only when ordinary layout cannot express the relationship.
- Never write unrelated app state on every layout event.
- Treat measured data as revision-scoped; it can become stale after text size, width, theme or content changes.
- Let `nsh/base`'s overlays place popups: their placement, flipping and safe-area margins follow one policy.

For alignment invariants, prefer construction over correction: sibling regions should consume the same spacing token
or shared inset instead of repeating equal literals. Add geometry checks or screenshots on a real platform
(`nsh test --target`) for critical repeated edges, columns and gaps. Exercise more than the default window: a large
text size and display scaling can turn fractional coordinates into a one-pixel drift even when the default screenshot
looks aligned.

Measure the resolved result when reviewing precision, but do not encode a measured correction as an arbitrary value.
Trace the mismatch to duplicated padding, nested insets, border ownership, font metrics or rounding, then fix the
structural owner.

Every scrollable region must have one owner. Avoid accidental nested scrolling on the same axis. Give the scroll view
the element that owns the full page, panel or list, so its indicator resolves against the region's edge, and put the
content's inset inside it (`contentClass` / `contentStyle`) rather than wrapping the scroll view in a padded
container. An indicator floating between content and the page boundary usually reveals the wrong scroll owner or
padding on the wrong layer. Keep clear of the safe area and the keyboard with `env(safe-area-inset-*)` and `env(keyboard-inset-height)` in
padding and margin (read the values with their accessors), which follow rotation and the keyboard natively.

## Lists, tables, and large data

Use [`List`](https://nsh.dev/versions/main/docs/lists.md) (`virtual_list` in Rust) when data can grow beyond a small, bounded collection. Keep row
identity separate from visible position and avoid copying the full data set on every update. Let the list own
recycling, scroll coordination and the visible range while row functions own row presentation.

Separate:

- source data and domain ids;
- filtering and sorting state;
- selection state;
- scroll state;
- row rendering.

This keeps updates local and prevents the view tree from becoming the data model.

Virtualization is a behavioral contract, not just a performance switch. A row function runs once per cell, and cells
are reused for other rows:

- **must keep per-item state in data keyed by id**, not in a signal created inside the row, which travels with the
  cell to the next item;
- **must read the item where it is used**, in bindings: a value copied at the top of the row function belongs to the
  first row the cell showed;
- update immutably in TSX (a new array, unchanged items reused, a changed item a new object), and give an
  `estimatedItemSize` close to the typical row;
- scrolling to an item (`scrollToIndex`) works in data coordinates even when most rows do not exist.

```rust
let liked = signal(HashSet::<u32>::new());

virtual_list(move || posts.with(Vec::len), move |at| {
    let post = computed(move || posts.with(|p| p[at.index()].clone()));
    view()
        .flex_row()
        .p_4()
        .child(text(move || post.with(|p| p.title.clone())).flex_1())
        .child(
            text(move || if liked.with(|s| s.contains(&post.with(|p| p.id))) { "♥" } else { "♡" })
                .on_press(move || toggle(post.with(|p| p.id))),
        )
})
.estimated_item_size(px(64.0))
```

```tsx
const liked = signal<Set<number>>(new Set());

<List each={posts()} estimatedItemSize={64} class="flex-1">
  {(post) => (
    <View class="flex-row p-4">
      <Text class="flex-1">{post().title}</Text>
      <Text onPress={() => toggle(post().id)}>{liked().has(post().id) ? "♥" : "♡"}</Text>
    </View>
  )}
</List>
```

## Public API design

For reusable components:

- props establish valid defaults: `#[prop(default)]` or `#[prop(default = …)]` in Rust, `??` where the prop is read in
  TSX;
- every prop, event and export has a doc comment; in Rust it becomes the TypeScript declaration TSX sees;
- callbacks describe requested changes and include pointer details only when they are meaningful;
- explicit parts, slots and render functions are preferable to inspecting arbitrary descendants;
- adding reusable behavior must not force a product-level visual choice.

Apps are delivered to host apps as signed packages and may never be built again: every later release of NSH runs them
as they are. Apply the same discipline to what an app or a component library exposes to others (its components'
props and events, its crate's exports, the functions a host app's native components and modules receive):

- inputs gain optional members only; types only widen; defaults and behavior stay (new behavior is opt-in);
- a function whose parameters may grow takes its options as one object (`scrollTo({ x, y, animated })`), never a
  further positional parameter; parameters that never will, such as a range's start and end, stay positional;
- a mode is a string union, which can gain values, rather than a boolean that later needs a third state;
- a value has one type: `version: string`, never `string | number`;
- what a function returns is an object, which can gain a field, rather than a tuple or a bare value;
- a function returning a Promise reports every failure by rejecting it, and a failure the caller can handle carries a
  `code`, as NSH's own do: callers branch on codes, while messages are for people and may change;
- a rename keeps the old name as a `@deprecated` alias of the same implementation.

In Rust, private fields are the default for behavioral state that must evolve without breaking callers. Public fields
are appropriate for deliberately record-like configuration and serialized data. Every public struct with public fields
must carry `#[non_exhaustive]` and implement `Default`, so callers can create values without exhaustive struct literals
and a field can be added without breaking them.

Keep public import paths stable while reorganizing internals: a crate's `#[native_module]` specifier and its exports,
and a TSX module's exports, are what other code imports. Prefer platform control terminology and NSH's established
naming over web-framework vocabulary.

## Platform and capability boundaries

Do not assume every platform supports the same facility. Title bars and window controls, accessibility, the
clipboard, haptics, scroll physics, fonts and timing can differ. One bundle runs everywhere
([Platform-specific code](https://nsh.dev/versions/main/docs/platform-specific.md)); put platform-specific code where NSH gives it a place and define
the fallback behavior:

- what an element means on every platform is a top-level prop; a platform's own system feature goes in
  `ios={{…}}`, `android={{…}}`, `desktop={{…}}` or `web={{…}}` (a builder method in Rust), in each of the platforms
  that have it, and only the current platform's object is applied;
- APIs of mobile platforms come from `nsh/mobile`, those of the desktops from `nsh/desktop`;
- styles per platform are `ios:`, `android:` and `web:` classes.

A platform branch must preserve the semantic contract even if presentation differs. For example, a dialog is a sheet
on iOS and a layer over the window on the desktops, but the app still needs a coherent open state. Test the shared
behavior headless and the platform's part with `nsh test --target`. Give every branch on a value NSH reports
(`platform.os`, a state, a reason) a `default`: later releases add platforms and cases, and an app delivered
today runs on them ([Compatibility](https://nsh.dev/versions/main/docs/compatibility.md)).

An app declares what it reaches outside its VM in `nsh.json` `"capabilities"`: the hosts it fetches from, the pages a
web view shows, the clipboard, the status bar ([Sandbox and Capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md)). An app
that will be delivered into other apps lists exactly what it uses, and handles a refused request as it handles a
failed one: a host app may grant less than the app declares. A refused call fails with `code` `"ERR_ACCESS_DENIED"`,
its `permission` naming the capability and its `resource` what was asked for.

## File and naming conventions

- Name pages and components after product concepts: `ProjectList`, `ProjectEditor`, `SettingsPage`.
- Name event handlers after intent: `confirmDelete`, `openProject`, `onQueryChange`.
- Keep one main responsibility per module; split a file when state ownership or lifecycle can no longer be understood
  without reading unrelated behavior.
- Keep a component's module, props, events and focused tests together when they change together.
- Document invariants and surprising lifecycle constraints; do not narrate obvious builder calls.
- Use `rustfmt` and satisfy Clippy in Rust, and `nsh check` in TSX. Avoid broad `allow` attributes that conceal
  unrelated warnings.

### Vocabulary is part of the API

Use the same word for the same concept across components. Before naming a prop or an event, look for the term in
NSH's own API, then in GPUI Kit's `gpui-base`, GPUI and `gpui-component`, then in the platforms' controls. What a
primitive shows and the global APIs take their names from HTML, the DOM and CSS (`src`, `html`, `placeholder`). Rust
names are `snake_case` and translate to `camelCase` in TSX (`on_open_change` is `onOpenChange`); one word stays one
word (`readonly`, `multiline`).

| Concept | Naming pattern | Example |
| --- | --- | --- |
| A component | A noun, `PascalCase` | `Button`, `Dialog`, `QuantityStepper` |
| Its props and events (Rust) | `<Component>Props`, `<Component>Event` | `ButtonProps`, `ButtonEvent::Press` → `onPress` |
| A behavior's state object | `<Control>State`, made by `create<Control>` | `NavStackState`, `createNavStack` |
| Why a value changed | `<Control>ChangeReason`, a string union | `DialogChangeReason`: `"cancel"`, `"backdropPress"` |
| A state | An adjective, positive, no `is` prefix | `open`, `hidden`, `disabled`, `selected`, `checked`, `readonly` |
| What the user may do | The adjective | `scrollable`, `zoomable`, `selectable`, `resizable` |
| A feature with no adjective | `<feature>Enabled` | `pagingEnabled` |
| Whether a part shows | A boolean named after the part, default `true` | `scrollbar`, `caret` (`scrollbar={false}`) |
| Whether a slot shows | `<slot>Visible`, default `true` | `headerVisible` (`header` is a page's slot) |
| A part's styles | `<part>Class`, `<part>Style` | `backdropClass`, `contentStyle` |
| A state's styles | `<state>Style`, `<state>:` classes | `activeStyle`, `disabled:` |
| A slot | What it is | `header`, `footer`, `trigger`, `content`, `empty` |
| Content of the app's | `render<Part>` | `renderCodeBlock` |
| A dismissal flag | `closeOn<Trigger>`, default `true` | `closeOnEscape`, `closeOnBackdropPress` |
| A value's change | `on<Value>Change({ <value>, ... })`, one object | `onChange({ value })`, `onOpenChange({ open, reason })` |
| Any other event | `on<Event>`, present tense, one object | `onPress()`, `onSubmit({ text })` |
| A phase | `<act>Start`, `<act>End` | `onPanStart`, `onLoadStart` |
| The mouse over a view | `Enter` / `Move` / `Leave`, the DOM's | `onMouseEnter`, `onMouseMove`, `onMouseLeave` |
| Starting to listen | `on(event, listener)`, returns `() => void` | `host.on(name, l)`, `BackHandler.on("press", l)` |
| A value of the environment | An accessor, `set<Value>` beside it | `colorScheme()`, `setColorScheme` |
| A read-only boolean | `is<Adjective>`, `has<Noun>` | `isAvailable` |

Props are never `is<Adjective>`: that form is for what only reads a boolean (a constant, a field of a payload). A part
that shows is named after the part, never `<part>Shown`, `<part>Hidden` or `shows<Part>`.

A Rust builder takes and returns `Self` and is named after the prop it sets, with no `set_` (`.disabled(..)`,
`.checked(..)`, `.on_change(..)`); mutation in place is `set_<field>` (`setRoutes`, `setColorScheme`). A boolean reader
is either `has<Noun>`, when the value holds something, or `is<Adjective>`, when it describes a state or a permission.
Reach for the adjective whenever the action has one: `isClosable` over `canClose`, `isZoomable` over `canZoom`. When
the action is a verb phrase with no adjective form, name the thing it needs instead: `hasDefinition`, not
`canGoToDefinition`. Do not add new `can` readers.

### Let the enclosing name carry the context

A name is read inside something: a prop inside its component, a field inside its type. Neither repeats what encloses
it (`contentStyle`, not `contentContainerStyle`; `Dialog`'s `backdropClass`, not `dialogBackdropClass`). Keep one type's
fields at the same level of abbreviation.

### Use precise domain words

- **selected** is membership or the current item; **checked** and **pressed** are the value of a checkbox or a toggle;
  **focused** is the keyboard's target; **hovered** is the pointer's presence. Never use them interchangeably.
- **open / close** is an overlay's state; **show / hide** a transient request; **expand / collapse** structure.
- **disabled** blocks interaction; **readonly** allows selecting and navigating but not editing; **loading** prevents
  duplicate work while an operation runs.
- **press** is activation by any input, and NSH's events say press (`onPress`); **click** is a mouse's.
- **index** is a position; **id** is identity. Do not persist or key reorderable data by index.
- **value** is controlled domain data; **state** is retained behavior.
- **src** is the resource an element shows (an image, a video, a page); any other address is a **url**.
- **role** says what a choice means (`"cancel"`, `"destructive"`); a look is the app's.

Avoid vague names such as `data`, `item2`, `handleAction`, `updateUi`, `process`, `manager` or `config` when a narrower
domain term exists.

### Type and module style

- Rust types are `UpperCamelCase`; modules, functions, methods, fields and locals `snake_case`; constants
  `SCREAMING_SNAKE_CASE`. Name context bindings `cx`.
- TSX components and their tags are `PascalCase`; props, functions and locals `camelCase`. Primitives come from `nsh`,
  base components from `nsh/base`.
- A module named after a component owns its public seam; split its state, parts and tests into files without
  changing what others import.
- Use singular module names for one component concept and established names for families (`menu` for `Menu`,
  `MenuItem` and `Submenu`).
- Suffix identifiers with `Id`, and collections with meaningful plurals. Do not alternate `idx`, `index` and `ix` in
  one subsystem.
- Name predicates positively when possible. A positive state is easier to compose than several negatives, but keep
  established terms such as `disabled` where they match control semantics.

### Callback and event wording

- Every event passes one object, even with one field and for a value's change too, its fields named as the props they
  report: `onChange({ value })`, `onOpenChange({ open, reason })`, `onLinkPress({ url })`. A later field is then an
  addition. A data type of the API is a field, never the payload itself (`onImagePress({ image })`); an event with
  nothing to report passes nothing.
- Name the act, not past tense or a request: `onPress`, `onClose`, `onCancel`, `onBackPress`.
- Name the intent rather than the geometry when the act has a name: `onLoadMore`, not "the end was reached".
- Lifecycle pairs are `onOpen` / `onClose`; phases are `Start` / `End`, never `Begin`; the mouse over a view is
  `onMouseEnter` / `onMouseMove` / `onMouseLeave` (the DOM's names), a file dragged over it `Enter` / `Leave`.
- Document whether a callback runs before or after the component's own state changes, and whether it may re-enter the
  component.

### Documentation and copy style

Public docs should begin with what a component does and who owns its state. Examples must use current APIs and show
stable ids. Document defaults, platform differences, focus behavior, callback ordering, and which props the main
thread reads natively.

Follow the interface language rules of the Design Guides for labels, commands, confirmation dialogs, capitalization,
and ellipses. Keep one canonical term for each domain object, command, and state.

Translation keys describe stable intent (`dialog.deleteProject.title`), not a source-language sentence or a screen
coordinate. Never assemble a sentence from translated fragments or reuse one key for meanings that happen to share the
same English text.

Localize intent, not syntax. Give every locale control over word order, pluralization, punctuation, and the amount of
context it needs. Tests should catch missing keys and inconsistent fixed terms; human review still decides whether
repetition is justified by context. Verify every string inside its component with realistic content, text expansion,
and a large text size.

## Testing strategy

Test at the lowest layer that can prove the behavior ([Testing](https://nsh.dev/versions/main/docs/testing-and-trace.md)):

1. pure tests for state transitions, formatting, parsing and ordering (`cargo test` of a crate's functions, a test
   file of the store's functions);
2. headless app tests for components, events and lifetimes: the real engine, renderer, layout and lists, with display
   frames at 60 Hz, in `nsh test` (`nsh/test`) or `cargo test` (`nsh_testing::Headless`);
3. interaction tests for focus, keyboard, pointer, layout and rendered state, with the steps a user takes (`press`,
   `type`, `scroll`, `drag`, `keyboard.press`), headless and on a real platform (`nsh test --target macos`, `ios`,
   `android`, `web`, ...);
4. example or app smoke tests for complete workflows, and `nsh test --trace` for what an interaction costs.

```rust
#[test]
fn a_tap_counts() {
    let mut app = Headless::start(EngineConfig::new(Root::of::<my_app::App>())).unwrap();
    app.wait_for("Count: 0").unwrap();
    app.press("Tap").unwrap();
    app.wait_for("Count: 1").unwrap();
}
```

```tsx
import { expect, open, test } from "nsh/test";

test("a tap counts", async () => {
  const app = await open("./App.tsx");
  await app.press("role:button[Tap]");
  expect(app.texts()).toContain("Count: 1");
});
```

For an interactive component, cover the semantic contract rather than its implementation details: activation by press
and keyboard, controlled value changes, disabled behavior, focus movement, event count and order, stable identity, and
important empty or failure states. Stub the network (`network` routes) and control time (a manual clock) instead of
waiting on real ones. Add a regression test before fixing a bug whenever the failure can be reproduced
deterministically.

Find views as a user does: by role and name, label or text (`role:button[Save]`, `label:Close`), and by a stable
`testID` where nothing else names them. Selectors are read again at every step, so a step never acts on a stale
snapshot. Use screenshots (`app.screenshot`, on a real platform) for visual facts selectors cannot express; use
coordinates only as a fallback. Report automated and manual evidence separately.

## Performance rules

- Do not write state unconditionally from a binding or an effect that reads it.
- Avoid creating signals, effects, key bindings and expensive data structures inside bindings or row functions.
- Read signals in bindings, so a coherent change updates the narrowest part of the tree.
- Use `List` for long collections and render only the visible range.
- Avoid cloning large strings or collections solely to satisfy a closure; capture `Copy` handles or shared data
  (`SharedString`, `Rc`).
- Keep TSX handlers and computed values light; move heavy work off the interaction path or into Rust.
- Measure with `nsh test --trace` before adding caches. A cache must have a clear invalidation owner.
- Keep animation work bounded: animated values on the UI thread rather than signals written every frame, `scrollValue`
  rather than a scroll listener ([Animation](https://nsh.dev/versions/main/docs/animation.md)), and honor reduced motion (`reduceMotion()`).

## Common failure modes

Avoid these patterns:

- one signal containing the app's unrelated state;
- business logic and network requests embedded in a long component body;
- random or index-based keys for reorderable content;
- per-row state in signals created inside a `List` row;
- reading a prop or signal in a component body and expecting it to update;
- literal colors and radii that break custom themes and dark mode;
- custom pressable views where a semantic component already supplies focus, keyboard, disabled, and accessibility
  behavior;
- duplicated local state that drifts from a controlled value;
- effects that copy one signal into another, and writes that loop through a binding;
- a decision the system needs on the spot left to a callback, instead of a prop set beforehand;
- nested scroll views without explicit ownership;
- a new component variant for a one-off screen;
- confirmation dialogs for reversible, low-risk actions;
- tests that call internal functions but never press, type or scroll.

## Rules for coding agents

Before editing, an agent must read the nearest implementation, its tests, the module's public exports, and the
relevant reference page. It must search the current source and `.nsh/types` for signatures instead of translating a
React, React Native, CSS or GPUI example by analogy: NSH components run once, and bindings follow the signals they
read.

For each change, the agent should be able to name:

1. the behavior owner and presentation owner;
2. the retained identity and state lifecycle;
3. the press, keyboard, focus, and accessibility contract;
4. the layout and scrolling owner;
5. the theme tokens and intentional exceptions;
6. the test that would fail if the behavior regressed.

Generated code must be reviewed and tested by a person. "Compiles" is not a UI quality bar, and a broad refactor that
merely makes generated code look tidy is not a substitute for matching the app's architecture.

## Implementation checklist

Before opening a change for review, confirm that:

- state and side-effect ownership are explicit;
- a plain function versus a component is chosen deliberately, and props and signals are read where they are used;
- repeated elements have stable domain-based keys and test ids;
- theme tokens and the Tailwind scale replace isolated visual literals;
- presses, keyboard shortcuts, focus, disabled state, and overlays work together;
- decisions the system needs on the spot are props, set beforehand;
- loading, empty, error, and cancellation paths are represented;
- long data sets use `List`, with per-item state in data;
- public API additions only widen, and preserve dependency direction and encapsulation;
- tests prove behavior at the appropriate layer, headless and on the platforms the change touches;
- formatting, Clippy, `nsh check`, targeted tests, and relevant examples pass.

See [Getting started](https://nsh.dev/versions/main/docs/getting-started.md) for app setup, and the [Elements](https://nsh.dev/versions/main/elements.md) and
[API](https://nsh.dev/versions/main/modules.md) references for current API details.

Source: https://nsh.dev/versions/main/docs/coding-guides

---

# JSX and components

NSH apps describe their UI with elements and components, in Rust or in TSX. Rust builds elements with functions and typed builder methods (`view().gap_4().child(..)`); TSX writes them as JSX, which NSH's compiler turns into direct calls of the same native renderer, with no React and no virtual DOM. Either way, a component is a function that runs once to build its part of the tree. What keeps the UI up to date afterwards is [reactivity](https://nsh.dev/versions/main/docs/reactivity.md): the bindings that read signals are followed natively, and only they run again.

## Elements

The **host elements** are each backed by a native view. Rust makes them with the prelude's functions; TSX imports them from `nsh` as components, and only `If` and `Each` are globals that need no import:

| Rust | TSX | Native view | Page |
|---|---|---|---|
| `view()` | `<View>` | `UIView` / `ViewGroup`: a box for layout, styling and touches | [View](https://nsh.dev/versions/main/elements/view.md) |
| `text(..)` | `<Text>` | A native text view; nested text elements are spans | [Text](https://nsh.dev/versions/main/elements/text.md) |
| `image(src)` | `<Image>` | An image view (local assets and URLs) | [Image](https://nsh.dev/versions/main/elements/image.md) |
| `scroll()` | `<Scroll>` | `UIScrollView` / `ScrollView` | [Scroll](https://nsh.dev/versions/main/elements/scroll.md) |
| `input()` | `<Input>` | `UITextField` / `UITextView` / `EditText` | [Input](https://nsh.dev/versions/main/elements/input.md) |
| `virtual_list(count, row)` | `<List>` | A virtualized, recycling list | [List](https://nsh.dev/versions/main/elements/list.md) |
| `canvas(..)`, `web_view(url)`, `video(url)` | `<Canvas>`, `<WebView>`, `<Video>` | A drawing, a web page, a video player | [Elements](https://nsh.dev/versions/main/elements.md) |
| `nsh_base::dialog()` | `<Dialog>` from `nsh/base` | A presented layer | [Elements](https://nsh.dev/versions/main/elements.md) |
| `when(..)`, `each(..)` | `<If>`, `<Each>` | Control flow, no view of its own | [Control flow](https://nsh.dev/versions/main/elements/control-flow.md) |

```rust
use nsh_core::prelude::*;   // view, text, image, scroll, input, virtual_list, ..., when, each
```

```tsx
import { Image, mount, Text, View } from "nsh";
```

In Rust, styles are typed methods named as Tailwind's utilities are (`.px_4()`, `.rounded_lg()`, `.bg(..)`), and
listeners are methods too (`.on_press(..)`); platform-only settings have methods of their own. In TSX, props keep
their camelCase names (`onPress`, `allowFontScaling`, `backgroundColor`); every element accepts `style`, `class` /
`classList` ([Tailwind](https://nsh.dev/versions/main/docs/tailwind.md)), `ref`, touch handlers, accessibility props and `testID`, and platform-only
props go in `ios={{…}}` and `android={{…}}`, where only the current platform's object is sent:

```rust
view()
    .rounded(px(12.0))
    .bg(move || theme().background)
    .on_press(move || open.set(true))
    .child(text("Open").font_weight(FontWeight::SEMIBOLD))
```

```tsx
<View android={{ elevation: 4, ripple: { color: "#0001" } }} style={{ borderRadius: 12 }} onPress={() => open.set(true)}>
  <Text style={{ fontWeight: "600" }}>Open</Text>
</View>
```

TSX tags are PascalCase so that TypeScript checks each one against the binding it names: a lowercase tag is checked against one global type per name, so a generic component such as `List` or `Each` could not infer its rows' type from `each` / `of`, and an app's own components would not be typed at all. The imports cost nothing at run time: the compiler recognizes the primitives through their imports (aliases too) and makes the native element in place, so `<View>` is a direct call of the renderer and the import is dropped from the bundle. A lowercase tag is a build error that says what to write:

```text
x lowercase tag <view>: tags are PascalCase components: write <View> and
| `import { View } from "nsh"`
```

> [!IMPORTANT]
> Text is only displayed inside a text element: `text(..)` in Rust, `<Text>` in TSX. A string directly in a `<View>` creates no native view and is not shown.

## Components

The look of an app is the app's own. NSH provides two layers: the primitives (the elements above, styles, Tailwind classes) and the unstyled base components of [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md) (`nsh_base` in Rust), which own behavior such as navigation, dialogs, the keyboard, the status bar and safe areas. The third layer, the component library, is yours: buttons, cards and every other piece of your UI are components you write on those two layers, in your app's crate ([Building with Rust](https://nsh.dev/versions/main/docs/rust.md)) or in TSX, or a library from the community ([Three layers](https://nsh.dev/versions/main/docs/architecture.md#three-layers)).

A Rust component is a `#[component] fn` that takes its props struct (and, when it has events, a `Scope` to emit them) and returns its elements. `#[component]` also makes its constructor, the function's name in snake case: `Badge` is placed with `badge()`, as `view()` places a view, with a setter per prop (`.label(..)`, `.color(..)`: a value, a signal or a closure). A TSX component is a function that takes a props object and returns JSX:

```rust
#[derive(Debug, Clone, PartialEq, Props)]
pub struct BadgeProps {
    /// The text.
    pub label: Prop<SharedString>,
    /// The background (light blue when left out).
    #[prop(default = Hsla::from(rgb(0xddf4ff)))]
    pub color: Prop<Hsla>,
}

/// A small rounded label.
#[component]
pub fn Badge(props: BadgeProps) -> impl IntoElement {
    view()
        .rounded_full()
        .px(px(10.0))
        .py_1()
        .bg(move || props.color.get())
        .child(text(props.label).text_size(px(13.0)).font_weight(FontWeight::SEMIBOLD))
}

// Placed in another component's view:
badge()
    .label(move || format!("{} new", unread.get()))
    .color(rgb(0xfff8c5))
```

```tsx
function Badge(props: { label: string; color?: string }) {
  return (
    <View style={{ borderRadius: 999, paddingHorizontal: 10, paddingVertical: 4, backgroundColor: props.color ?? "#ddf4ff" }}>
      <Text style={{ fontSize: 13, fontWeight: "600" }}>{props.label}</Text>
    </View>
  );
}

<Badge label={`${unread()} new`} color="#fff8c5" />
```

The function runs **once**, when the component is created, and does not track what it reads: there is no re-rendering. Code in its body (creating signals, starting effects, computing constants) runs one time. The elements it returns stay connected to the props and signals they read, so `Badge` above updates its text whenever `unread` changes, without running `Badge` again.

Write a `#[component]` when the UI has props or events of its own, or when a TSX entry imports it: a Rust component is registered under its type (`registry.register::<Badge>()`), with props typed from the struct ([Building with Rust](https://nsh.dev/versions/main/docs/rust.md#extending-a-rust-app-with-tsx)). For a piece of UI only Rust uses, a plain function returning `impl IntoElement` is enough, its arguments the props. In TSX, a component may return an element, a string or number, an array, `null`, or a function returning any of these (which the renderer follows); the `Component<P>` type from `nsh` describes one:

```rust
fn row(title: impl Into<SharedString>, content: impl IntoElement) -> impl IntoElement {
    view()
        .flex_row()
        .gap_2()
        .child(text(title.into()))
        .child(content)
}
```

```tsx
import type { Component, JSX } from "nsh";
import { Text, View } from "nsh";

const Row: Component<{ title: string; children?: JSX.Element }> = (props) => (
  <View style={{ flexDirection: "row", gap: 8 }}>
    <Text>{props.title}</Text>
    {props.children}
  </View>
);
```

### What runs again

A value given to an element is set once; a binding follows what it reads. In Rust a binding is a closure (or a signal, a memo, a prop) given where a value goes. In TSX, the compiler decides for each expression in JSX: an expression changes when it **calls a function or reads a property** (outside nested functions), and everything else is set once:

```rust
text(move || format!("{}", count.get()))     // follows count
text(props.title)                            // follows the prop
text(label.clone())                          // a plain value: set once
view().opacity(move || if busy.get() { 0.5_f32 } else { 1.0 })   // follows busy
```

```tsx
<Text>{count()}</Text>              // follows count
<Text>{props.title}</Text>          // follows the prop
<Text>{user.name}</Text>            // re-read when something it depends on changes
<Text>{label}</Text>                // a plain variable: set once
<View style={{ opacity: busy() ? 0.5 : 1 }} />   // the style object is rebuilt when busy changes
```

A changing prop or child is a small native effect that sets that one prop or replaces that one child. Styles are diffed in Rust, so a style that changes only sends the properties that changed.

Event handlers are set once: a closure in Rust, a function or a name in TSX (`onPress={() => …}`, `onPress={save}`). In TSX, other expressions are followed (`onPress={props.onPress}` follows the prop).

### Props

A Rust component's props are the fields of its `#[derive(Props)]` struct, each a `Prop<T>`: a value, or a binding the parent passed. Read one in a binding (`text(props.title)`, `move || props.title.get()`) to follow it; `props.title.get()` in the body reads it once. Fields with `#[prop(default)]` or `#[prop(default = …)]`, and `Option`s, are optional. The constructor starts every prop at its default, and a parent calls the setters of the ones it needs: `badge().label("New")`.

A TSX prop given a changing expression is passed as a getter: reading `props.title` calls it, which is what lets the JSX that reads it follow it. Static props are plain values. In both, props are read where they are used:

```rust
// Wrong: reads the prop once, when the component runs.
#[component]
fn Title(props: TitleProps) -> impl IntoElement {
    let content = props.text.get();
    text(content)
}

// Right: binds the text to the prop.
#[component]
fn Title(props: TitleProps) -> impl IntoElement {
    text(props.text)
}
```

```tsx
// Wrong: reads the prop once, when the component runs.
function Title(props: { text: string }) {
  const { text } = props;
  return <Text>{text}</Text>;
}

// Right: reads it in JSX, which follows it.
function Title(props: { text: string }) {
  return <Text>{props.text}</Text>;
}
```

A TSX component that takes its props apart in its parameter, `function Title({ text }: …)`, reads them the same once, and the build warns of it with the props to read instead:

```text
warn App.tsx:3:16: Title takes its props apart (`{ text }`): each is read once, when Title runs, and does not follow changes; take `props` and read `props.text` where it is used (`split(props, [...])` to pass the rest on)
```

A prop the component wants only once, such as an id it starts with, is read in the body (`props.id.get_untracked()`, `const { id } = props;`), which says so.

In TSX the same applies to default values: write `props.color ?? "#ddf4ff"` in the JSX rather than destructuring with a default. To compute something from props, use a closure or [`computed`](https://nsh.dev/versions/main/docs/reactivity.md#computed):

```rust
#[component]
fn Price(props: PriceProps) -> impl IntoElement {
    let formatted = move || format!("${:.2}", props.cents.get() as f64 / 100.0);
    text(formatted)
}
```

```tsx
function Price(props: { cents: number }) {
  const formatted = () => `$${(props.cents / 100).toFixed(2)}`;
  return <Text>{formatted()}</Text>;
}
```

### Children

What a parent places in a component arrives as its children: a `children: Prop<Children>` field in Rust, which the parent fills with `.child(..)`; `props.children` in TSX, a getter that builds those elements when read:

```rust
#[derive(Debug, Clone, PartialEq, Props)]
pub struct CardProps {
    /// The title.
    pub title: Prop<SharedString>,
    /// The content.
    pub children: Prop<Children>,
}

#[component]
pub fn Card(props: CardProps) -> impl IntoElement {
    view()
        .p(px(14.0))
        .rounded(px(12.0))
        .bg(move || theme().background)
        .gap_2()
        .child(text(props.title).font_weight(FontWeight::SEMIBOLD))
        .child(props.children)
}

card()
    .title("Account")
    .child(text(move || format!("Signed in as {}", user.get().name)))
```

```tsx
function Card(props: { title: string; children?: JSX.Element }) {
  return (
    <View style={{ padding: 14, borderRadius: 12, backgroundColor: "#ffffff", gap: 8 }}>
      <Text style={{ fontWeight: "600" }}>{props.title}</Text>
      {props.children}
    </View>
  );
}

<Card title="Account">
  <Text>Signed in as {user().name}</Text>
</Card>
```

In TSX, each read of `props.children` builds the children again (new native views): read it once, in the place where the children go. Among several children, one that changes (an `<If>`, an `<Each>`, `{cond() ? a : b}`) arrives as a function, and `{props.children}` updates that one alone: its siblings keep their views, an input its text and focus. Fragments (`<>…</>`) group elements without a view.

Children can also be made by a function the component calls with arguments, a render callback:

```rust
fn repeat<E: IntoElement>(times: usize, row: impl Fn(usize) -> E) -> impl IntoElement {
    view().child((0..times).map(row))
}

repeat(3, |i| text(format!("Row {i}")))
```

```tsx
function Repeat(props: { times: number; children: (i: number) => JSX.Element }) {
  return <View>{Array.from({ length: props.times }, (_, i) => props.children(i))}</View>;
}

<Repeat times={3}>{(i) => <Text>Row {i}</Text>}</Repeat>
```

## Control flow

`when` and `each` in Rust, `<If>` and `<Each>` in TSX, are built-in control flow. They render no view of their own.

```rust
when(move || user.get().is_some(), move || {
    text(move || format!("Hello, {}", user.get().map(|u| u.name).unwrap_or_default()))
})
.otherwise(|| text("Signed out"))

each(todos, |todo| todo.id, |todo, index| {
    text(move || format!("{}. {}", index.get() + 1, todo.get().title))
})
```

```tsx
<If when={user()} else={<Text>Signed out</Text>}>
  {(u) => <Text>Hello, {u().name}</Text>}
</If>

<Each of={todos()} key={(t) => t.id}>
  {(todo, index) => (
    <Text>
      {index() + 1}. {todo().title}
    </Text>
  )}
</Each>
```

- **`when`** / **`<If>`** shows its branch while the condition holds, else the `otherwise` / `else` branch. It renders a branch again only when whether the condition holds changes, not every time the condition is re-evaluated. In TSX, a function child gets an accessor of `when`'s value, typed without `null` and `undefined`: `u()` is the user while the branch shows, and follows it when it changes.
- **`each`** / **`<Each>`** renders a row per item, made by its row function. Rows are kept by key (Rust: the key function; TSX: `key`, by default the item itself, objects by identity and primitives by value): when the list changes, kept rows are moved rather than rebuilt, and new rows are made only for new keys. The row function receives **signals** of the item and its index (`todo.get()` and `index.get()` in Rust, `todo()` and `index()` in TSX), because a kept row's item and position can change. In TSX, `key="index"` (or `key={(item, i) => i}`) keeps rows by position instead: a list of strings that changes in place, such as text streamed in, keeps its rows and only their `item()` changes.

A choice made in a closure (`dynamic(move || if busy.get() { … } else { … })` in Rust, a ternary or `&&` in TSX) builds its branch again every time anything it reads changes. Prefer `when` / `<If>` when a branch is more than a few elements.

For long or infinite lists, use [`List`](https://nsh.dev/versions/main/docs/lists.md) (`virtual_list` in Rust): it creates views only for the rows on screen and recycles them. See [Control flow](https://nsh.dev/versions/main/elements/control-flow.md) for the details.

## Refs

A ref names a host element for imperative calls: `focus()`, `blur()`, `scroll_to()` / `scrollTo()`, `scroll_to_index()` / `scrollToIndex()`, `measure()` ([where a view is](https://nsh.dev/versions/main/docs/touch-and-gestures.md#where-a-view-is-measure)), ... In Rust, `element_ref()` makes one and `.element_ref(&handle)` puts it on an element; in TSX, `ref` gives you the element's ref, whose type is the element's own (`InputRef` here, `ViewRef` for a `View`; see [ref methods](https://nsh.dev/versions/main/elements.md#ref-methods)):

```rust
fn search() -> impl IntoElement {
    let field = element_ref();
    view()
        .child(input().element_ref(&field).placeholder("Search"))
        .child(text("Focus").on_press(move || field.focus()))
}
```

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

function Search() {
  let input: InputRef | undefined;
  return (
    <View>
      <Input ref={input} placeholder="Search" />
      <View onPress={() => input?.focus()}>
        <Text>Focus</Text>
      </View>
    </View>
  );
}
```

A Rust ref is a `Copy` handle; its calls go to the element that carries it, and do nothing once its owner is gone. In TSX, what `ref={…}` names receives the node:

- a variable declared with `let` is assigned it;
- a field (`ref={refs.input}`, `ref={refs[name]}`) is assigned it;
- a [signal](https://nsh.dev/versions/main/docs/reactivity.md) is set to it, so what reads the signal follows it;
- a function is called with it (`<Scroll ref={(node) => (scroller = node)} />`).

A `const` or an import holds a signal or a function, as in `const input = signal<InputRef>()` with `<Input ref={input} />` and `input()?.focus()`; one holding anything else is reported when the element is made, with what to write.

The ref is set when the element is created, before the component returns, so it is available in [effects](https://nsh.dev/versions/main/docs/reactivity.md#effect) and event handlers. Calls are sent to the view in order with the changes made before them. The base components and the Rust components of your own crate accept `ref` too (in Rust `component_ref()`, put on the element with `.component_ref(&r)`: `dialog().component_ref(&r)`).

## Spreading props

In Rust, a parent calls the setters of the props it needs and the rest keep their defaults, and a wrapper passes its own `Prop`s on as they are (`card().title(props.title)`): a `Prop` keeps following what it was given.

In TSX, spread an object of props onto an element or a component with `{...props}`. Getters stay getters, so spread props keep following what they read. To take some props for yourself and pass the rest on, use `split`:

```tsx
import { split, Text, View } from "nsh";
import { Input, type InputProps } from "nsh/base";

function Field(props: InputProps & { label: string }) {
  const [own, rest] = split(props, ["label"]);
  return (
    <View style={{ gap: 4 }}>
      <Text>{own.label}</Text>
      <Input style={{ borderWidth: 1, borderRadius: 8, padding: 8 }} {...rest} />
    </View>
  );
}

<Field label="Email" value={email()} onChange={({ value }) => email.set(value)} keyboardType="email-address" />
```

`split(props, keys)` returns `[picked, rest]`, both still reading through to the original props (destructuring `{ label, ...rest } = props` would read every prop once). Element props that come later in the JSX win over earlier ones.

`<If>` and `<Each>` take no spread props, and spread children (`{...items}`) are not supported: use `<Each>` or an array expression.

## Tags and names

A Rust element is whatever the code calls: a primitive's function, a component's constructor (`badge()`, `nsh_base::button()`), or a function of your own. A TSX tag names a binding in scope, as usual: `<Badge />`, `<Theme.Provider>`, a `<Button>` of your own. A tag that names nothing in scope is a build error, except `<If>` and `<Each>`, which are globals.

```rust
/// The app's button: a press target styled by the app.
fn primary_button(title: &'static str, on_press: impl Fn() + 'static) -> impl IntoElement {
    view()
        .role(AccessibilityRole::Button)
        .rounded_lg()
        .bg(rgb(0x2563eb))
        .px_5()
        .py_3()
        .active(|s| s.opacity(0.6))
        .on_press(on_press)
        .child(text(title).text_base().font_weight(FontWeight::SEMIBOLD).text_color(white()))
}

primary_button("Save", save)
```

```tsx
import { Text, View } from "nsh";

function Button(props: { title: string; onPress: () => void }) {
  return (
    <View onPress={props.onPress} activeStyle={{ opacity: 0.6 }} role="button" class="rounded-lg bg-blue-600 px-5 py-3">
      <Text class="text-base font-semibold text-white">{props.title}</Text>
    </View>
  );
}

<Button title="Save" onPress={save} />
```

`nsh_base`'s `Button` (`button()` in Rust, `<Button>` from `nsh/base`) is the unstyled press target with the disabled and selected states and their accessibility; the app gives it its look: `button().disabled(move || saving.get()).on_press(move || save()).px_4().active(|s| s.opacity(0.6)).child(text("Save"))`.

In TSX, your bindings win over the globals: a component named `Each` in scope makes `<Each>` that component. A primitive is recognized by its import, so `import { View as Box } from "nsh"` makes `<Box>` a view, and a component of your own named `Text` is just your component. The primitives are real components too: `const Tag = inline ? Text : View;` and then `<Tag>…</Tag>` works.

Components are typed by their own declarations: Rust's props structs are checked by the compiler, and TypeScript checks a TSX component's props wherever it is used, with nothing to generate. A Rust component a TSX entry imports gets TypeScript declarations generated from its struct.

## Mounting and the root

A Rust app's root is the component `nsh.json`'s `"root"` names; `nsh run` and `nsh package` mount it. A TSX entry calls `mount(App)` to render the root component (`mount(App, props)` passes it props). The root view fills the surface (the window, or the view an app embeds NSH in). Give the root `flex: 1` so it fills the screen, and a background color: the surface's own background depends on the platform.

```rust
// nsh.json: { "rust": ".", "root": "App" }
#[component]
pub fn App() -> impl IntoElement {
    view()
        .flex_1()
        .bg(move || theme().background)
        .child(home())
}
```

```tsx
mount(() => (
  <View style={{ flex: 1, backgroundColor: "#ffffff" }}>
    <App />
  </View>
));
```

## Related

- [Reactivity](https://nsh.dev/versions/main/docs/reactivity.md): signals, effects, context.
- [Elements](https://nsh.dev/versions/main/elements.md): every host element and its props.
- [Styling](https://nsh.dev/versions/main/docs/styling.md) and [Tailwind](https://nsh.dev/versions/main/docs/tailwind.md): the look of your components.
- [Building with Rust](https://nsh.dev/versions/main/docs/rust.md): Rust apps, components in your app's own crate, and TSX on top.

Source: https://nsh.dev/versions/main/docs/jsx-and-components

---

# Reactivity

NSH updates the UI with **signals**: values that know who reads them. When a signal changes, NSH runs again exactly the computations that read it (a text, a style, an effect) and nothing else. Components do not re-render. The model is Solid's, and the reactive graph itself is native: Rust components and TSX run on the same graph, written in Rust, so in TSX too the scheduling, dependency tracking and cleanup all happen outside the interpreter.

Rust components take everything on this page from the prelude; TSX imports it from `nsh`:

```rust
use nsh_core::prelude::*;   // signal, computed, effect, resource, batch, untracked, cleanup, provide_context, use_context
```

```tsx
import { batch, cleanup, computed, context, effect, resource, signal, untracked } from "nsh";
```

## Signals

`signal(value)` makes a signal. Read it with `get()` in Rust, by calling it in TSX; `set` and `update` write it:

```rust
let count = signal(0);

count.get();                    // 0, and tracks the read
count.set(5);
count.update(|n| *n += 1);      // 6
```

```tsx
const count = signal(0);

count();                     // 0, and tracks the read
count.set(5);
count.update((n) => n + 1);  // 6
```

A read inside a tracking scope (a binding, `computed`, `effect`) subscribes that scope to the signal. A write notifies the subscribers when the value changed: compared with `PartialEq` in Rust, with `===` in TSX.

```rust
fn counter() -> impl IntoElement {
    let count = signal(0);
    view()
        .on_press(move || count.update(|n| *n += 1))
        .child(text(move || format!("Tapped {} times", count.get())))
}
```

```tsx
function Counter() {
  const count = signal(0);
  return (
    <View onPress={() => count.update((n) => n + 1)}>
      <Text>Tapped {count()} times</Text>
    </View>
  );
}
```

Tapping updates the one text node that reads `count`. `counter()` / `Counter` itself runs once. A Rust signal is a `Copy` handle, so closures take it with `move` and use it freely.

A signal can count every write as a change, and TSX can compare values its own way:

```rust
let tick = signal_with(0, SignalEquals::Never);   // every write notifies
```

```tsx
const tick = signal(0, { equals: false });   // every write notifies
const position = signal({ x: 0, y: 0 }, { equals: (a, b) => a.x === b.x && a.y === b.y });
```

In TSX, `signal<T>()` without a value starts as `undefined` and is typed `Signal<T | undefined>`; in Rust, an
`Option` says the same (`signal(None::<User>)`).

### Objects and arrays

In Rust, `update` changes the value in place and notifies the readers; `set` replaces it. In TSX, signals compare with `===`, so a value mutated in place is no change: write a new object or array.

```rust
let todos = signal(Vec::<Todo>::new());

todos.update(|list| list.push(Todo { id: 3, title: "New".into(), done: false }));   // notifies
todos.update(|list| {
    if let Some(todo) = list.iter_mut().find(|t| t.id == id) {
        todo.done = true;
    }
});
```

```tsx
const todos = signal<Todo[]>([]);

todos.update((list) => [...list, { id: 3, title: "New" }]);                 // notifies
todos.update((list) => list.map((t) => (t.id === id ? { ...t, done: true } : t)));

todos().push(item);    // does not notify anyone
todos.set(todos());    // still the same array: no change
```

`each` / `<Each>` keys rows by item, so changing one item rebuilds only that row ([JSX and components](https://nsh.dev/versions/main/docs/jsx-and-components.md#control-flow)).

## computed

`computed(fn)` derives a value from other signals. It runs `fn`, remembers the result, and runs it again when a signal it read changes. Reading it is like reading a signal:

```rust
let price = signal(12);
let quantity = signal(2);
let total = computed(move || price.get() * quantity.get());

text(move || format!("Total: {}", total.get()))
```

```tsx
const price = signal(12);
const quantity = signal(2);
const total = computed(() => price() * quantity());

<Text>Total: {total()}</Text>
```

Use `computed` when a derived value is read in several places or is expensive: it runs once per change however many readers it has, and readers are notified only when its result changes. For a cheap value read once, a plain closure is enough:

```rust
let label = move || format!("{} items", quantity.get());
text(label)
```

```tsx
const label = () => `${quantity()} items`;
<Text>{label()}</Text>
```

In TSX, `fn` receives the previous value (`undefined` the first time), for values that accumulate:

```tsx
const max = computed((prev: number | undefined) => Math.max(prev ?? 0, speed()));
```

## effect

`effect(fn)` runs `fn`, and again whenever a signal it read changes. Effects are for side effects: logging, timers, network requests, imperative calls on [refs](https://nsh.dev/versions/main/docs/jsx-and-components.md#refs).

```rust
#[derive(Debug, Clone, PartialEq, Props)]
pub struct SearchProps {
    /// What to search for.
    pub query: Prop<SharedString>,
}

#[component]
pub fn Search(props: SearchProps) -> impl IntoElement {
    let results = signal(Vec::<SharedString>::new());
    effect(move || {
        let q = props.query.get();          // tracked: runs again when the prop changes
        if q.is_empty() {
            return;
        }
        spawn(async move {
            if let Ok(response) = fetch(format!("https://api.example.com/search?q={q}")).await {
                results.set(response.text().lines().map(|line| SharedString::from(line.to_owned())).collect());
            }
        });
    });
    view().child(each(results, |item| item.clone(), |item, _| text(item)))
}
```

```tsx
function Search(props: { query: string }) {
  const results = signal<string[]>([]);
  effect(() => {
    const q = props.query;          // tracked: runs again when the prop changes
    if (!q) return;
    fetch(`https://api.example.com/search?q=${encodeURIComponent(q)}`)
      .then((r) => r.json())
      .then((data) => results.set(data.items));
  });
  return <Each of={results()}>{(item) => <Text>{item()}</Text>}</Each>;
}
```

An effect tracks the reads made while it runs synchronously. Reads in a task, a `.then` callback or after an `await` are not tracked.

An effect that calls a [ref](https://nsh.dev/versions/main/docs/jsx-and-components.md#refs) acts on the element the ref is on; in TSX, effects run after the elements created in the same pass exist, so refs are set:

```rust
let input = element_ref();
effect(move || {
    if editing.get() {
        input.focus();
    }
});
```

```tsx
let input: InputRef | undefined;
effect(() => {
  if (editing()) input?.focus();
});
```

> [!TIP]
> Do not use effects to keep one signal in sync with another (`effect(() => b.set(a() * 2))`). Use `computed`: it is never out of date and does not cause a second pass. An effect that writes a signal it also reads runs itself again and again until NSH stops it with an error.

## resource

`resource(source, fetcher)` loads a value asynchronously and keeps where the load is, so a component shows data, a spinner or an error without managing them itself:

```rust
let url = signal(SharedString::from("https://api.example.com/quote"));
let quote = resource(move || Some(url.get()), |url, _info| async move {
    let response = fetch(url.to_string()).await?;
    if !response.ok() {
        return Err(format!("HTTP {}", response.status()));
    }
    Ok(response.text())
});

view()
    .child(text(move || match (quote.get(), quote.error()) {
        (_, Some(error)) => format!("Failed: {error}"),
        (Some(quote), None) => quote,
        (None, None) => "Loading…".to_owned(),
    }))
    .child(text("Reload").on_press(move || quote.refetch()))
```

```tsx
import { List, resource, signal, Text } from "nsh";

type Post = { id: number; title: string };

const url = signal("https://jsonplaceholder.typicode.com/posts?_limit=20");
const posts = resource(url, async (u, { signal }) => {
  const response = await fetch(u, { signal });
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return (await response.json()) as Post[];
});

<If when={posts.error()}>
  <Text>Failed: {String(posts.error())}</Text>
</If>
<List
  each={posts() ?? []}
  refreshing={posts.state() === "refreshing"}
  onRefresh={posts.refetch}
>
  {(post) => <Text>{post().title}</Text>}
</List>
```

`source` is tracked: whenever it gives a new value, `fetcher(value, info)` loads again. In Rust it is a closure returning an `Option`, and `None` loads nothing; in TSX it is an accessor (a signal, a function) or a value, and `undefined`, `null` or `false` load nothing: for a user not signed in yet or nothing picked. With no source, Rust passes `|| Some(())`, and TSX's `resource(fetcher)` loads once, calling `fetcher(info)`. The Rust fetcher returns a `Result`; the TSX one a value or a promise, and a throw is a failure.

| Rust | TSX | What it is |
|---|---|---|
| `quote.get()` | `posts()` | The latest value: none before the first load ends, kept while loading again and after a failure. |
| `quote.loading()` | `posts.loading()` | Whether a load runs. |
| `quote.error()` | `posts.error()` | The last load's error, none once a load gives a value. |
| `quote.state()` | `posts.state()` | `Unresolved` / `"unresolved"` (nothing to load), `Pending` (the first load), `Ready`, `Refreshing` (loading again, the value kept), `Errored`. |
| `quote.refetch()` | `posts.refetch()` | Loads again from the same source: a retry, a pull to refresh. |
| `quote.mutate(value)` | `posts.mutate(value)` | Sets the value here with no load, an optimistic update, and clears the error. |

A Rust resource is a `Copy` handle, as signals are; the TSX members are bound, so `onRefresh={posts.refetch}` and `const loading = posts.loading` work as they are.

Only the latest load counts. A new one drops the one running, and so does the component going away; in TSX, `info.signal` aborts the `fetch` it is given. A load that ends after it was superseded changes nothing. `info.refetching` says that `refetch()` started the load. `resource_with_value(value, source, fetcher)` in Rust and `{ initialValue }` in TSX give the resource a value from the start.

## cleanup

`cleanup(fn)` registers `fn` to run before the current effect runs again, or when the component or effect it belongs to goes away:

```rust
effect(move || {
    if !running.get() {
        return;
    }
    let ticker = spawn(async move {
        loop {
            timer(Duration::from_millis(100)).await;
            tick();
        }
    });
    cleanup(move || ticker.cancel());   // before the next run, or on removal
});
```

```tsx
function Clock() {
  const now = signal(Date.now());
  const id = setInterval(() => now.set(Date.now()), 1000);
  cleanup(() => clearInterval(id));       // when Clock is removed
  return <Text>{new Date(now()).toLocaleTimeString()}</Text>;
}

effect(() => {
  if (!running()) return;
  const id = setInterval(tick, 100);
  cleanup(() => clearInterval(id));       // before the next run, or on removal
});
```

In Rust, tasks, timers and intervals (`spawn`, `set_timeout`, `set_interval`) already end with the owner they were made under, so a view's own clock needs no cleanup:

```rust
use std::time::Duration;

use nsh_core::time::unix_ms;

fn clock() -> impl IntoElement {
    let now = signal(unix_ms());
    set_interval(Duration::from_secs(1), move || now.set(unix_ms()));   // ends with the view clock() made
    text(move || format!("{:.0}", now.get() / 1000.0))
}
```

A TSX effect can also return its cleanup, as in React: a function `fn` returns runs at the same moments as one it passes to `cleanup`.

```tsx
effect(() => {
  const id = setInterval(tick, 100);
  return () => clearInterval(id);
});
```

A component goes away when it is no longer rendered: its `when` / `<If>` branch is hidden, its `each` / `<Each>` row is removed, or its page is popped. Everything it created (effects, computed values, tasks, cleanups, nested components) is disposed with it.

## batch

Each write notifies its subscribers right away. To make several writes count as one change, wrap them in `batch`: dependants run once, after the last write.

```rust
let save = move || {
    batch(|| {
        first_name.set(form.first.clone());
        last_name.set(form.last.clone());
        dirty.set(false);
    })
};
```

```tsx
const save = () =>
  batch(() => {
    firstName.set(form.first);
    lastName.set(form.last);
    dirty.set(false);
  });
```

Event handlers are not batched for you: two writes in a press handler run an effect that reads both signals twice. `batch` returns what its function returns.

## untracked

`untracked(fn)` runs `fn` without subscribing to what it reads. Use it in a tracking scope to read a value without depending on it:

```rust
effect(move || {
    let q = query.get();                          // runs again when query changes
    let filters = untracked(|| active_filters.get());   // read, but not a reason to run again
    search(q, filters);
});
```

```tsx
effect(() => {
  const q = query();                     // runs again when query changes
  const filters = untracked(activeFilters); // read, but not a reason to run again
  search(q, filters);
});
```

Rust's `get_untracked()` reads one signal the same way. A component body is already untracked: reading a signal there reads it once.

## context

A context is a value a component provides to everything it renders, however deep. In Rust, `provide_context(value)` provides a value of its type, and `use_context::<T>()` finds the nearest one; in TSX, `context(defaultValue)` makes a context, calling it reads the nearest provided value (or the default), and `<Ctx.Provider value>` provides one:

```rust
#[derive(Clone, Copy)]
struct Dark(bool);

fn label(content: &'static str) -> impl IntoElement {
    let dark = use_context::<Dark>().is_some_and(|d| d.0);
    text(content).text_color(if dark { rgb(0xffffff) } else { rgb(0x1f2328) })
}

fn screen() -> impl IntoElement {
    provide_context(Dark(true));
    view().child(label("Hello"))
}
```

```tsx
const Theme = context<"light" | "dark">("light");

function Label(props: { children: string }) {
  const theme = Theme();
  return <Text style={{ color: theme === "dark" ? "#ffffff" : "#1f2328" }}>{props.children}</Text>;
}

mount(() => (
  <Theme.Provider value="dark">
    <Label>Hello</Label>
  </Theme.Provider>
));
```

A provided value is read once, when it is looked up. To provide something that changes, provide a signal (or a struct of signals) and read it in a binding:

```rust
#[derive(Clone, Copy)]
struct Accent(Signal<Hsla>);

#[component]
fn App() -> impl IntoElement {
    provide_context(Accent(signal(rgb(0x0969da).into())));
    view().child(swatch())
}

fn swatch() -> impl IntoElement {
    let Accent(accent) = use_context::<Accent>().expect("an accent");
    view()
        .w(px(40.0))
        .h(px(40.0))
        .bg(move || accent.get())
        .on_press(move || accent.set(rgb(0x8250df).into()))
}
```

```tsx
const Accent = context(signal("#0969da"));

function App() {
  const accent = signal("#0969da");
  return (
    <Accent.Provider value={accent}>
      <Swatch />
    </Accent.Provider>
  );
}

function Swatch() {
  const accent = Accent();
  return <View onPress={() => accent.set("#8250df")} style={{ width: 40, height: 40, backgroundColor: accent() }} />;
}
```

Read a context in a component body (or in code that runs while components are being created), not in an event handler or a timer, where there is no component to look it up from. Rust components also take the app's theme this way: `theme()` from `nsh_base` ([Theme](https://nsh.dev/versions/main/docs/rust.md#theme)).

## Error boundaries

An error boundary keeps a failure in one part of a view to that part. When something under it throws (Rust: panics) while it renders or runs, such as a component's body, a binding, an effect or an event handler, the failed part is removed and the boundary shows its fallback in its place; the rest of the view stays as it is. In Rust it is `catch_error(view, fallback)`; in TSX, `<ErrorBoundary fallback>` from `nsh`. The fallback gets the error (in TSX the thrown value itself, usually an `Error`) and a reset that renders the view again:

```rust
fn profile_card(user: Signal<Option<User>>) -> impl IntoElement {
    catch_error(
        move || profile(user),
        |error, reset| {
            view()
                .child(text(format!("Something went wrong: {error}")))
                .child(text("Try again").on_press(move || reset.reset()))
        },
    )
}
```

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

function ProfileCard(props: { user: User | undefined }) {
  return (
    <ErrorBoundary
      fallback={(error, reset) => (
        <View>
          <Text>Something went wrong: {error instanceof Error ? error.message : String(error)}</Text>
          <Text onPress={reset}>Try again</Text>
        </View>
      )}
    >
      <Profile user={props.user} />
    </ErrorBoundary>
  );
}
```

A failure goes to the nearest boundary above where it happened, and one in a fallback to the boundary above that. Without a boundary, the failure is reported as an uncaught error (the development error overlay, the log). In TSX, a `fallback` element is shown as it is (`fallback={<Text>Unavailable</Text>}`), and a function is called with the error and `reset`, whatever parameters it declares.

## What runs, and when

| You write | Runs | Runs again when |
|---|---|---|
| Component body | Once, when it is created | Never (hot reload aside) |
| A binding: a closure given to `text`, a style or a prop in Rust; `{expr}` or `prop={expr}` that calls or reads a property in TSX | Once, when the element is created | A signal it read changes; only that prop or child is updated |
| `computed(fn)` | When created | A signal it read changes |
| `effect(fn)` | After the elements of the current pass exist | A signal it read changes |
| `when(cond, ..)` / `<If when>` | When created | Whether the condition holds changes |
| `each(..)` / `<Each of>` row | When its key first appears | Never; its item and index signals change instead |

The environment is reactive the same way: `window()`, `dark()`, `font_scale()`, `safe_area()` and `keyboard_height()` in Rust, `windowSize()`, `colorScheme()` and `fontScale()` from [`nsh`](https://nsh.dev/versions/main/modules/nsh.md#device) and `safeArea()` and `keyboardFrame()` from [`nsh`](https://nsh.dev/versions/main/modules/nsh.md) in TSX, so bindings that read them follow rotation, dark mode or the keyboard.

## Common mistakes

**Reading a signal in the component body and expecting updates.**

```rust
fn bad() -> impl IntoElement {
    let n = count.get();                       // read once
    text(format!("{n}"))                       // never changes
}

fn good() -> impl IntoElement {
    text(move || format!("{}", count.get()))   // a binding: follows count
}
```

```tsx
function Bad() {
  const n = count();           // read once
  return <Text>{n}</Text>;     // never changes
}

function Good() {
  return <Text>{count()}</Text>;
}
```

**Reading props once.** A Rust prop read with `props.title.get()` in the body is read once; read it in a binding (`text(props.title)`, `move || props.title.get()`). In TSX, `const { title } = props` reads `title` once: read `props.title` where you use it, or split props with [`split`](https://nsh.dev/versions/main/docs/jsx-and-components.md#spreading-props).

**Mutating instead of setting, in TSX.** `list().push(x)` changes the array but notifies nobody. Write a new array, as Rust's `update` does for you.

**Deriving state with effects.** `effect(() => total.set(price() * qty()))` works, but leaves `total` stale between the write and the effect, and costs a second pass. Use `computed`.

**Creating effects outside components.** Effects and computed values belong to the component that created them and are disposed with it. Created in an event handler or a timer callback, they have no owner and live forever. Create them in a component body and let them read the signals that change.

**Expecting asynchronous code to be tracked.** Only reads made synchronously while an effect or computed value runs are tracked. Read the signals first, then start the asynchronous work.

## Related

- [JSX and components](https://nsh.dev/versions/main/docs/jsx-and-components.md): components, props, `when` / `<If>` and `each` / `<Each>`, in Rust and TSX.
- [Building with Rust](https://nsh.dev/versions/main/docs/rust.md): Rust apps, tasks and the theme.
- [`nsh` module reference](https://nsh.dev/versions/main/modules/nsh.md): every TSX function's signature.
- [Animation](https://nsh.dev/versions/main/docs/animation.md): animated values that animate on the UI thread without signals.

Source: https://nsh.dev/versions/main/docs/reactivity

---

# Styling

Every element is styled with the same native styles, written two ways. In Rust, styles are typed methods chained on the element (`.p_4()`, `.rounded(px(12.0))`, `.bg(color)`); in TSX, a `style` prop of camelCase properties, or [Tailwind classes](https://nsh.dev/versions/main/docs/tailwind.md). Both include CSS features such as box shadows, gradients, filters, outlines, transitions and grid, and only the properties that changed are sent to the native view.

The three ways write one set of properties and mean the same. Their names are CSS's (a few take the plainer names apps write, such as `paddingHorizontal`, `marginStart` and `numberOfLines`), and CSS values (colors, gradients, filters, shadows, transforms, alignment keywords) and Tailwind utilities mean what they mean on the web, each Rust method and utility setting what Tailwind CSS 4 generates for it, so what you know from the web carries over: `paddingLeft` is `padding-left` and `pl-4`, `boxShadow` is `box-shadow`, `display: "flex"` is a row as the `flex` class is. The rest is made for native apps: lengths are points (`16`, `"50%"`, `"auto"`; classes take `rem` and CSS's other units), the defaults are native layout's (listed below), a value that changes takes numbers instead of a string (`translate: [x, 0]`, a shadow's layers), and what the platforms do beyond CSS has [extensions](#extensions) of its own.

```rust
view()
    .p_4()
    .rounded(px(12.0))
    .bg(white())
    .border_1()
    .border_color(rgb(0xd0d7de))
    .shadow([BoxShadow {
        offset_y: px(4.0),
        blur: px(12.0),
        color: rgba(0x0000001f).into(),
        ..BoxShadow::default()
    }])
    .child(
        text("Card")
            .text_size(px(17.0))
            .font_weight(FontWeight::SEMIBOLD)
            .text_color(rgb(0x1f2328)),
    )
```

```tsx
<View
  style={{
    padding: 16,
    borderRadius: 12,
    backgroundColor: "#ffffff",
    borderWidth: 1,
    borderColor: "#d0d7de",
    boxShadow: "0 4px 12px rgba(0, 0, 0, 0.12)",
  }}
>
  <Text style={{ fontSize: 17, fontWeight: "600", color: "#1f2328" }}>Card</Text>
</View>
```

This page covers how styles combine and the visual properties. Layout properties (flexbox, grid, sizes, positions) are on [Layout](https://nsh.dev/versions/main/docs/layout.md), text properties on [Text](https://nsh.dev/versions/main/docs/text.md), and every property with its type is listed in the [style reference](https://nsh.dev/versions/main/modules/style-reference.md).

## Combining styles

In Rust, shared styles are functions that take an element and return it styled, and conditions are plain Rust: `.when(condition, |v| ..)` for what is known when the element is made, `.style_when(signal, |s| ..)` for styles that switch while the app runs. In TSX, `style` takes an object, or an array of objects merged left to right; falsy entries (`false`, `null`, `undefined`) are skipped, which makes conditional styles short:

```rust
fn button(danger: bool, busy: Signal<bool>) -> View {
    view()
        .px_4()
        .py(px(10.0))
        .rounded(px(10.0))
        .bg(rgb(0x0969da))
        .when(danger, |v| v.bg(rgb(0xcf222e)))
        .style_when(busy, |s| s.opacity(0.4))
}
```

```tsx
const styles = {
  button: { paddingHorizontal: 16, paddingVertical: 10, borderRadius: 10, backgroundColor: "#0969da" },
  disabled: { opacity: 0.4 },
  danger: { backgroundColor: "#cf222e" },
} as const;

<View style={[styles.button, props.danger && styles.danger, busy() && styles.disabled]} />
```

In TSX, define shared styles as constants outside components (with `as const`, so TypeScript keeps literal types such as `"row"`). A plain object is all it takes: styles are parsed in Rust each time they are set, from objects nobody needs to register.

A style that reads signals follows them: in Rust, give the method a closure (`.bg(move || ..)`), and only that property is set again when the signals change; in TSX, a style expression that reads signals is rebuilt, and NSH sends only the properties whose values differ:

```rust
view()
    .p_3()
    .bg(move || if selected.get() { rgb(0xddf4ff) } else { rgb(0xffffff) })
```

```tsx
<View style={{ backgroundColor: selected() ? "#ddf4ff" : "#ffffff", padding: 12 }} />
```

When a TSX element has both, `style` wins over `class`: classes are applied first, then the inline style on top. A key set to `undefined` sets nothing (`backgroundColor: active ? accent : undefined` keeps the class color when inactive); `null` sets the default. In Rust, a later method wins over an earlier one for the same property.

Within one style (an object, or an array merged into one), the order of the keys makes no difference: a more specific property wins over its shorthand, `borderTopWidth` over `borderWidth`, `borderLeftColor` over `borderColor`, `marginTop` over `marginVertical` over `margin` (padding alike), `rowGap` over `gap`, `flexGrow` over `flex`, `gridColumnStart` over `gridColumn`. A specific property set to `null` there shows the shorthand's value.

## Units and values

- **Lengths are points** (density-independent pixels): `px(100.0)` in Rust and `width: 100` in TSX are 100pt, which is 200 or 300 physical pixels on a 2× or 3× screen.
- **Percentages** (`relative(0.5)` in Rust, `"50%"` in TSX) are relative to the parent, for sizes, positions, margins and paddings ([Layout](https://nsh.dev/versions/main/docs/layout.md)).
- **Angles** are `deg(45.0)`, `radians(0.5)` or `turn(0.25)` in Rust, and degrees as numbers or strings with a unit in TSX: `45`, `"45deg"`, `"0.5rad"`; CSS's `rotate` and `transform` also take `"0.25turn"`, and inside a `transform` string every angle has its unit.
- **Durations** are milliseconds: `.duration(150.0)` in Rust, numbers or strings (`"150ms"`, `"0.2s"`) in TSX.

## Defaults

Where nothing sets a property, NSH's defaults apply:

| | Default |
|---|---|
| Layout of a view's children | a column (a flex container with `flexDirection: "column"`); `display: "flex"` makes a row unless `flexDirection` is set, as in CSS |
| `flexShrink` | `0` (children do not shrink unless asked) |
| `alignContent` | `"flex-start"` (in grids, CSS's `"normal"`) |
| `position` | `"relative"` |
| `minWidth` / `minHeight` | `0` |
| `backgroundColor` | transparent |
| Text | black, 14pt, weight 400 |
| Border and outline color | the text color (CSS's `currentColor`) |

New views carry no style at all until you give them one, so unstyled wrappers cost nothing on the native side.

## Colors

In Rust, colors are typed values: `rgb(0x0099ff)`, `rgba(0x0099ffcc)`, `hsla(..)`, `white()`, `black()`, and Tailwind's palette as `nsh_core::element::palette` (`BLUE.shade(500)`). Color methods take an `AdaptiveColor`, a light and a dark value: `AdaptiveColor::rgb(0xffffff, 0x0d1117)` switches with the system appearance natively, with no render. Colors from the app's theme (`theme().primary` from `nsh_base`) are adaptive too ([Rust](https://nsh.dev/versions/main/docs/rust.md#theme)).

In TSX, color properties accept CSS color strings:

| Form | Example |
|---|---|
| Hex | `"#09f"`, `"#09fc"`, `"#0099ff"`, `"#0099ffcc"` |
| `rgb()` / `rgba()` | `"rgb(0, 153, 255)"`, `"rgba(0, 0, 0, 0.5)"`, `"rgb(0 0 0 / 10%)"` |
| `hsl()` / `hsla()` | `"hsl(210 100% 50%)"` |
| `oklch()` / `oklab()` | `"oklch(62.3% 0.214 259.8)"` |
| Named | `"white"`, `"black"`, `"transparent"`, `"rebeccapurple"`, ... |
| `currentColor` | `"currentColor"`: the text color, also inside a gradient, a shadow, a `drop-shadow()` or a `color-mix()` (`"color-mix(in srgb, currentColor 50%, transparent)"`); classes write it `bg-current`, `border-current/50`, `bg-[color-mix(in_srgb,currentColor_50%,transparent)]` |

For dark mode in TSX, read [`colorScheme()`](https://nsh.dev/versions/main/modules/nsh.md#device) from `nsh`, an accessor that follows the system appearance, or use Tailwind's `dark:` variant:

```rust
view()
    .flex_1()
    .bg(AdaptiveColor::rgb(0xffffff, 0x0d1117))
    .child(text("Follows the system appearance").text_color(AdaptiveColor::rgb(0x1f2328, 0xe6edf3)))
```

```tsx
import { Text, View } from "nsh";
import { colorScheme } from "nsh";

const palette = () =>
  colorScheme() === "dark"
    ? { background: "#0d1117", text: "#e6edf3" }
    : { background: "#ffffff", text: "#1f2328" };

<View style={{ flex: 1, backgroundColor: palette().background }}>
  <Text style={{ color: palette().text }}>Follows the system appearance</Text>
</View>
```

For styles other than colors, `.dark(|s| ..)` in Rust applies styles in dark appearance, and `dark()` reads the appearance. The default text color is black in both appearances: set colors explicitly in apps that support dark mode.

## Borders and corners

```rust
view()
    .border_1()
    .border_color(rgb(0xd0d7de))
    .border_dashed()               // .border_solid() | .border_dashed() | .border_dotted()
    .rounded(px(12.0))
    .rounded_tl(px(24.0))          // per corner, overrides .rounded(..)
    .border_b(px(3.0))             // per side
    .border_b_color(rgb(0x0969da))
```

```tsx
<View
  style={{
    borderWidth: 1,
    borderColor: "#d0d7de",
    borderStyle: "dashed",          // "solid" | "dashed" | "dotted"
    borderRadius: 12,
    borderTopLeftRadius: 24,        // per corner, overrides borderRadius
    borderBottomWidth: 3,           // per side
    borderBottomColor: "#0969da",
  }}
/>
```

- **Widths and colors** per side: `borderTopWidth`, `borderRightWidth`, ..., `borderTopColor`, ..., which keep their side in either direction; and `borderStartWidth`, `borderEndWidth`, `borderStartColor`, `borderEndColor`, which follow the [layout direction](https://nsh.dev/versions/main/docs/layout.md#right-to-left) (`.border_t(..)`, `.border_t_color(..)`, `.border_s(..)`, `.border_e_color(..)`, ... in Rust).
- **The color** of a side whose width is set and whose color is not is the text color, as CSS's `currentColor`: `{ borderWidth: 1, color: "#0969da" }` draws a blue border.
- **Radii** per corner: `borderTopLeftRadius`, `borderTopRightRadius`, `borderBottomRightRadius`, `borderBottomLeftRadius`, and `borderTopStartRadius` / `borderTopEndRadius` / `borderBottomStartRadius` / `borderBottomEndRadius` (top start, top end, bottom start, bottom end), which follow the [layout direction](https://nsh.dev/versions/main/docs/layout.md#right-to-left) (`.rounded_tl(..)`, ..., `.rounded_ss(..)`, `.rounded_se(..)`, `.rounded_es(..)`, `.rounded_ee(..)` in Rust, and the presets `.rounded_lg()`, `.rounded_full()`, ...).
- **`borderCurve: "continuous"`** (`.border_curve(BorderCurve::Continuous)`, the class `corner-squircle`) draws superellipse corners, whose curvature eases into the edges, like iOS app icons: on iOS, Android, macOS and Linux, and on the web where the browser has CSS `corner-shape` (Chromium); elsewhere circular corners of the same radius. A pill (`borderRadius` of half the height) stays a pill.
- **`overflow: "hidden"`** (`.overflow_hidden()`) clips children to the rounded shape. What it clips away is clipped in layout too: it does not reach an enclosing scroll view's content size, so a box that lays a child out wider than itself and scales it down with a `transform` (transforms do not affect layout) leaves the scroll view alone.

Radii larger than half the side are clamped, so `borderRadius: 9999` (`.rounded_full()`) makes a circle or a pill.

## Shadows

Views cast CSS's `boxShadow`, and Android adds its material elevation:

```rust
// CSS box-shadow: several layers, with spread and inset.
view().shadow([
    BoxShadow { offset_y: px(1.0), blur: px(2.0), color: rgba(0x00000014).into(), ..BoxShadow::default() },
    BoxShadow { offset_y: px(8.0), blur: px(24.0), color: rgba(0x0000001f).into(), ..BoxShadow::default() },
])
view().shadow([BoxShadow { offset_y: px(2.0), blur: px(4.0), color: rgba(0x00000026).into(), inset: true, ..BoxShadow::default() }])

// A preset in a color of its own.
view().shadow_lg().shadow_color(rgba(0x0969da66))

// Android's material elevation.
view().elevation(px(6.0)).bg(white()).rounded(px(12.0))
```

```tsx
// CSS box-shadow: several, comma separated, with spread and inset
<View style={{ boxShadow: "0 1px 2px rgba(0,0,0,0.08), 0 8px 24px rgba(0,0,0,0.12)" }} />
<View style={{ boxShadow: "inset 0 2px 4px rgba(0,0,0,0.15)" }} />

// Android's material elevation (a prop, not a style)
<View android={{ elevation: 6 }} style={{ backgroundColor: "#ffffff", borderRadius: 12 }} />
```

`boxShadow` follows CSS: `offsetX offsetY blur spread color`, `inset` for inner shadows. It also takes its layers as numbers, the form for values that change, which builds no string: `boxShadow: [{ x: 0, y: 6, blur: 18, spread: 0, color: "#0000004d", inset: false }]` (only `x` and `y` required; a layer without a color is the text color). Rust takes the layers, `.shadow([BoxShadow { .. }])`. Shadows follow the view's rounded shape, and a transition animates them (`transitionProperty: "boxShadow"`, `.transition_shadow()`). Tailwind's presets are `.shadow_sm()`, `.shadow_md()`, `.shadow_lg()`, ... in Rust, and `.shadow_color(..)` recolors their layers. A shadow that follows a transparent view's content (the glyphs of an icon, say) is a `filter: "drop-shadow(...)"` ([Filters](#filters-and-blending)); text has `textShadow` ([Text](https://nsh.dev/versions/main/docs/text.md)).

> [!NOTE]
> On Android, shadows need a background: a view with a transparent background (a text without one, for example) casts no shadow.

## Gradients

`backgroundImage` takes CSS gradients, drawn over the background color; in Rust, `.bg_linear(angle)`, `.bg_radial()` and `.bg_conic(angle)` with the stops `.gradient_from(..)`, `.gradient_via(..)` and `.gradient_to(..)`, as Tailwind's `bg-linear-*` with `from-*`, `via-*` and `to-*`. In TSX, several gradients are separated by commas.

```rust
view().h(px(120.0)).rounded(px(16.0)).bg_linear(deg(135.0)).gradient_from(rgb(0x54aeff)).gradient_to(rgb(0x8250df))
view().bg_radial().gradient_from(rgb(0xfff8c5)).gradient_to(rgb(0xfd8c73))
view().bg_conic(deg(0.0)).gradient_from(rgb(0xff0000)).gradient_via(rgb(0x00ff00)).gradient_to(rgb(0x0000ff))
view()
    .bg_linear_to_r()
    .gradient_from(rgb(0x8250df))
    .gradient_from_position(percentage(0.3))
    .gradient_to(rgb(0x54aeff))
    .gradient_to_position(percentage(0.3))
```

```tsx
<View style={{ height: 120, borderRadius: 16, backgroundImage: "linear-gradient(135deg, #54aeff, #8250df)" }} />
<View style={{ backgroundImage: "radial-gradient(circle at top left, #fff8c5, #fd8c73)" }} />
<View style={{ backgroundImage: "conic-gradient(red, yellow, lime, aqua, blue, magenta, red)" }} />
<View style={{ backgroundImage: "linear-gradient(90deg, #8250df 0 12px, #54aeff 12px)" }} />
```

Color stops are placed by percentages or lengths (`px`, `pt`, `rem`; plain numbers are points) along a linear or radial gradient, and by percentages or angles (`deg`, `turn`, `rad`, `grad`) around a conic one. A stop with two positions (`#8250df 0 12px`) is a band of one color, as are two stops at the same position. Lengths are measured along the gradient line at the view's current size, so a 12px band stays 12px wide as the view resizes.

Colors mix between stops as in CSS: in the space a gradient names (`linear-gradient(in oklab, …)`; also `srgb`, `srgb-linear`, `xyz`, `oklch` with a hue method such as `longer hue`, and `hsl`), and otherwise in sRGB when every color is a hex, `rgb()`, `hsl()` or named color, and in Oklab when one is `oklch()`, `oklab()`, `lab()`, `lch()` or `color()`.

Text elements do not draw gradients on iOS.

## Filters and blending

| Property | Value | Rust |
|---|---|---|
| `filter` | CSS filters of the view and its content: `brightness()`, `contrast()`, `grayscale()`, `hue-rotate()`, `invert()`, `saturate()`, `sepia()`, `opacity()`, `blur()`, `drop-shadow()` (without a color, in the text color, as in CSS); several separated by spaces | `.brightness(n)`, `.contrast(n)`, `.grayscale(n)`, `.hue_rotate(angle)`, `.invert(n)`, `.saturate(n)`, `.sepia(n)`, `.blur(px(..))` |
| `backdropFilter` | Filters of what is behind the view: `"blur(10px)"` (frosted glass) | `.backdrop_blur(px(10.0))`, `.backdrop_saturate(n)`, ... |
| `glassEffect` | `"regular"` or `"clear"` for Apple's Liquid Glass on iOS 26 and macOS 26 and later; `"none"` (the default) uses `backdropFilter` | `.glass_effect(GlassEffect::Regular)` |
| `mixBlendMode` | How the view blends with what is behind it: `"multiply"`, `"screen"`, `"overlay"`, ... | `.mix_blend_mode(BlendMode::Multiply)` |

```rust
image(photo).size(px(120.0)).grayscale(1.0).contrast(1.2)
view()
    .absolute()
    .bottom_0()
    .left_0()
    .right_0()
    .p_3()
    .bg(rgba(0xffffff66))
    .backdrop_blur(px(12.0))
```

```tsx
<Image src={photo} style={{ width: 120, height: 120, filter: "grayscale(1) contrast(1.2)" }} />
<View style={{ position: "absolute", bottom: 0, left: 0, right: 0, padding: 12, backgroundColor: "rgba(255,255,255,0.4)", backdropFilter: "blur(12px)" }} />
```

Platform support differs:

| | iOS | Android |
|---|---|---|
| `filter` on views | `opacity`, `brightness` up to 1 and `drop-shadow` only | All, from Android 12 (API 31); color filters only below |
| `filter` on images | Every color filter and `blur` | As views |
| `backdropFilter` | A system blur material, approximating the radius | From Android 12 (API 31) |
| `mixBlendMode` | Yes | From Android 10 (API 29) |

The web, Windows and Linux apply every filter to views, macOS as iOS does; GPUI draws the color filters and `drop-shadow()`. The backdrop filter is a blur on iOS, macOS and Android, every filter on the web and Windows; Linux and GPUI draw none, and GPUI draws views in the normal blend mode. Of a `filter` with several `drop-shadow()`s, iOS, macOS and Android draw the last. `mixBlendMode` blends the view with everything drawn behind it.

On iOS, `ios={{ backdropMaterial: "regular" }}` selects the system material used by a
`backdropFilter` blur. Values are `"ultraThin"` (the default), `"thin"`, `"regular"`, `"thick"`,
and `"chrome"`. Pair the prop with a positive blur radius to show the material. Rust uses
`.backdrop_material(BackdropMaterial::Regular)` alongside `.backdrop_blur(px(30.0))`.
The radius approximates material strength: NSH applies a fraction of the chosen material,
reaching full strength at 30 points. The light or dark variant follows the view's background color.
These choices map to Apple's [system blur materials](https://developer.apple.com/documentation/uikit/uiblureffect/style/systemmaterial).

```rust
view().backdrop_blur(px(30.0)).backdrop_material(BackdropMaterial::Regular)
```

```tsx
<View ios={{ backdropMaterial: "regular" }} style={{ height: 64, backdropFilter: "blur(30px)" }} />
```

`glassEffect` draws Liquid Glass behind a view's content on iOS 26 and macOS 26 and later. `"regular"` uses the standard material;
`"clear"` takes less color from the background. Pair it with `backdropFilter` for the blur shown on earlier iOS
versions and other platforms. The glass follows the view's size and rounded corners.

```tsx
<View style={{ height: 80, borderRadius: 16, backdropFilter: "blur(12px)", glassEffect: "regular" }} />
```

### Progressive blur

A blur that grows along an edge, as under a header or over a photo's caption, is layers of `backdropFilter`, each stronger than the last and masked in further along with `maskImage`. Five layers doubling their radius hide the steps:

```tsx
const LAYERS = 5;

function ProgressiveBlur(props: { radius: number; style: ViewStyle }) {
  return (
    <View style={{ pointerEvents: "none", ...props.style }}>
      <Each of={Array.from({ length: LAYERS }, (_, i) => i)}>
        {(i) => (
          <View
            style={{
              position: "absolute",
              left: 0,
              right: 0,
              top: 0,
              bottom: 0,
              backdropFilter: `blur(${props.radius / 2 ** (LAYERS - 1 - i())}px)`,
              maskImage: `linear-gradient(to bottom, transparent ${(i() / LAYERS) * 100}%, black ${((i() + 1) / LAYERS) * 100}%)`,
            }}
          />
        )}
      </Each>
    </View>
  );
}
```

A masked `backdropFilter` draws the blur alone, without the system material's tint, at its exact radius, on iOS and macOS too. Each layer blurs what the window shows on every frame, so keep the layers few and the area small. Linux and GPUI draw no `backdropFilter`, so give the region a fading `backgroundImage` where the text over it must stay readable.

## Outlines, opacity and visibility

- `outlineWidth`, `outlineColor`, `outlineStyle`, `outlineOffset` (`.outline(..)`, `.outline_color(..)`, `.outline_dashed()`, `.outline_offset(..)`): a line outside the border that takes no space (negative offsets draw inside). `outlineStyle: "none"` (or `"hidden"`, `.outline_none()`) hides the outline whatever its width, as in CSS.
- `opacity` (`.opacity(n)`): 0 to 1, applied to the view and its children.
- `visibility: "hidden"` (`.invisible()` in Rust): the view is not drawn but keeps its space, and screen readers skip it and its subtree, as in a browser. `display: "none"` (`.hidden()`) removes it from layout.
- `zIndex` (`.z_index(n)`): the order among siblings, also the native stacking order (stable for equal values).
- `cursor` (`.cursor(..)`, `.cursor_pointer()`): the pointer shape over the view, for pointers and desktops.

## Transforms

Transforms are CSS's. In TSX, `translate`, `rotate` and `scale` are properties of their own and `transform` takes CSS's string of functions or a list of steps; they compose in CSS's order, `translate`, then `rotate`, then `scale`, then `transform`, whatever the order of the keys. In Rust, transforms are methods (`.translate_x(..)`, `.rotate(..)`, `.scale(..)`, ...) composed in the same order:

```rust
view().translate_x(px(20.0)).rotate(deg(-8.0)).scale(0.9)
view().perspective(px(600.0)).child(view().rotate_y(deg(35.0)).backface_hidden())
view().origin_top_left().rotate(deg(30.0))
```

```tsx
<View style={{ translate: "20px 0", rotate: "-8deg", scale: 0.9 }} />
<View style={{ transform: "perspective(600px) rotateY(35deg)", backfaceVisibility: "hidden" }} />
<View style={{ transformOrigin: "top left", rotate: "30deg" }} />
```

| Property | Value |
|---|---|
| `translate` | `"10px 20px"`, `"-50% 0"` (percentages of the view's own size), a number (points along x), or `[x, y]` with a number, a string or an animated value per axis |
| `rotate` | `"45deg"`, `"0.25turn"`, about an axis `"x 90deg"`, a number (degrees) or an animated value (degrees) |
| `scale` | `1.5`, `"150%"`, `"1 2"` (x and y), an animated value (both axes) or `[x, y]` |
| `transform` | CSS's functions: `translate()`, `translateX()`, `translateY()`, `scale()`, `scaleX()`, `scaleY()`, `rotate()` / `rotateZ()`, `rotateX()`, `rotateY()`, `skew()`, `skewX()`, `skewY()`, `perspective()`; lengths in `px` (translations also `%`), angles in `deg`, `rad` or `turn`; `"none"`; or a list of steps (`[{ perspective: 800 }, { rotateY: angle }]`) whose amounts may be animated values |

Each is a property of its own, as with classes: a style's `scale` replaces a `scale-95` class and keeps its `rotate-3`. Animated values move `translate`, `rotate` and `scale` natively; for what CSS's string cannot hold with an animated amount, such as a 3D rotation, give `transform` a list of steps: `translateX`, `translateY`, `scale`, `scaleX`, `scaleY`, `rotate` (`rotateZ`), `rotateX`, `rotateY`, `skewX`, `skewY` and `perspective` ([Animation](https://nsh.dev/versions/main/docs/animation.md)). A style's `transform` is one form or the other, so a perspective before animated steps is a step of the list.

Rust's `.perspective(..)` is CSS's `perspective` property, as Tailwind's `perspective-*`: it gives the view's children their depth, while the `perspective()` function of a `transform` applies to the view's own transform. `transformOrigin` takes keywords, percentages and lengths (`"top left"`, `"50% 0"`, `[10, 20]`; `.origin_top_left()`, `.transform_origin(..)` in Rust); the default is the center. Transforms do not affect layout: siblings are placed as if the view were untransformed.

Android has no skew transforms.

## Transitions

A view animates changes of its own style when you name what to animate. The animation runs natively; none of your code runs per frame.

```rust
let open = signal(false);

view()
    .on_press(move || open.update(|o| *o = !*o))
    .w(px(150.0))
    .h(px(72.0))
    .rounded(move || px(if open.get() { 36.0 } else { 12.0 }))
    .bg(move || if open.get() { rgb(0x8250df) } else { rgb(0x54aeff) })
    .translate_x(move || px(if open.get() { 120.0 } else { 0.0 }))
    .transition_all()
    .duration(300.0)
    .ease_in_out()
```

```tsx
<View
  onPress={() => open.set(!open())}
  style={{
    width: 150,
    height: 72,
    borderRadius: open() ? 36 : 12,
    backgroundColor: open() ? "#8250df" : "#54aeff",
    translate: open() ? 120 : 0,
    transitionProperty: "all",
    transitionDuration: 300,
    transitionTimingFunction: "ease-in-out",
  }}
/>
```

| Property | Value | Rust |
|---|---|---|
| `transitionProperty` | What animates: `"all"`, or names separated by commas: colors (`"colors"`, `"backgroundColor"`, `"borderColor"`, ...), `"opacity"`, `"transform"` (every transform property), `"boxShadow"`, `"borderRadius"` / `"borderWidth"` | `.transition()`, `.transition_all()`, `.transition_colors()`, `.transition_opacity()`, `.transition_transform()`, `.transition_shadow()` |
| `transitionDuration` | `300`, `"300ms"`, `"0.3s"` | `.duration(300.0)` |
| `transitionDelay` | As the duration | `.delay(100.0)` |
| `transitionTimingFunction` | `"linear"`, `"ease"`, `"ease-in"`, `"ease-out"`, `"ease-in-out"`, `"cubic-bezier(x1, y1, x2, y2)"` | `.ease_linear()`, `.ease_in()`, `.ease_out()`, `.ease_in_out()`, `.ease_bezier(x1, y1, x2, y2)` |

Sizes and positions are layout, not style, and do not transition; animate layout changes with `LayoutAnimation` or drive values with native animations ([Animation](https://nsh.dev/versions/main/docs/animation.md)).

### Keyframe animations

`animationName` runs one of Tailwind's built-in keyframe animations natively: `"spin"`, `"ping"`, `"pulse"` or `"bounce"`, with `animationDuration`, `animationDelay`, `animationTimingFunction` and `animationIterationCount` (a number or `"infinite"`), in any order. In Rust, `.animate_spin()`, `.animate_ping()`, `.animate_pulse()` and `.animate_bounce()` run them with Tailwind's timing, and `.animation(KeyframeAnimation::new(..))` with your own:

```rust
view()
    .size(px(24.0))
    .rounded(px(4.0))
    .bg(rgb(0x0969da))
    .animation(KeyframeAnimation::new(Keyframes::Spin).duration(1000.0).easing([0.0, 0.0, 1.0, 1.0]))
```

```tsx
<View style={{ width: 24, height: 24, borderRadius: 4, backgroundColor: "#0969da", animationName: "spin", animationDuration: 1000, animationIterationCount: "infinite", animationTimingFunction: "linear" }} />
```

## Press feedback

Press feedback is the app's styles for the pressed state, applied natively without a round trip to your code; the hovered, focused and disabled states take styles the same way (`.hover(..)`, `.focus(..)`, `.disabled_style(..)` in Rust; `hoverStyle`, `focusStyle` and `disabledStyle`, or `hover:`, `focus:`, `disabled:`, in TSX):

| Rust | TSX | Effect while pressed |
|---|---|---|
| `.active(\|s\| s.opacity(0.6))` | `activeStyle={{ opacity: 0.6 }}` | The view fades to this opacity |
| `.active(\|s\| s.bg(rgb(0xeaeef2)))` | `activeStyle={{ backgroundColor: "#eaeef2" }}` | The background becomes this color |
| `.ripple(Ripple { color: Some(rgba(0x00000022).into()), ..Ripple::default() })` | `android={{ ripple: { color: "#0002" } }}` | Android's material ripple |
| `.active(\|s\| s.bg(ZINC.shade(100)).scale(0.95))` | `class="active:bg-zinc-100 active:scale-95"` | Any style |

See [Touch and gestures](https://nsh.dev/versions/main/docs/touch-and-gestures.md).

## Extensions

These keys and classes carry what native platforms do beyond CSS:

| Key | Class | What it does |
|---|---|---|
| `placeholderColor` | `placeholder:text-*` | An `<Input>`'s placeholder color |
| `selectionColor` | `selection:bg-*` | The selection highlight of an `<Input>` or a selectable `<Text>` |
| `tintColor` | `tint-*` | Recolors an `<Image>`'s opaque pixels (template images, icons) |
| `borderCurve` | | `"continuous"`: corners that ease into the edges, as the system's own (Apple's continuous corners) |
| `glassEffect` | | Apple's Liquid Glass behind the view on iOS 26 and macOS 26, the `backdropFilter` elsewhere |
| `writingDirection` | | A text's base direction, `"auto"` (the default: from its content, as the platforms' text views do), `"ltr"` or `"rtl"`; `direction` sets the layout's |
| `textAlignVertical` | | Where text shorter than its `<Text>` box sits: `"top"` (the default), `"center"` or `"bottom"` |
| `textAlign: "auto"` | | The text's natural side, by its direction (the default) |
| `selectedStyle` | `selected:` | The style while `accessibilityState.selected` is `true` (a selected `Button`, a tab) |
| | `ios:`, `android:`, `web:` | Classes for one platform (`ios:pt-2`) |

Values that change also take numbers where CSS takes a string: `transform` as a list of steps, `translate` and `scale` as `[x, y]`, `boxShadow` and `textShadow` as layers.

## Related

- [Tailwind](https://nsh.dev/versions/main/docs/tailwind.md): the same styles as classes, with variants for dark mode, pressed states and breakpoints, and their typed equivalents.
- [Layout](https://nsh.dev/versions/main/docs/layout.md) and [Text](https://nsh.dev/versions/main/docs/text.md).
- [Style reference](https://nsh.dev/versions/main/modules/style-reference.md): every style property and its type.

Source: https://nsh.dev/versions/main/docs/styling

---

# Tailwind

NSH's styles follow Tailwind CSS 4. In Rust, Tailwind's utilities are typed style methods with the same names and values (`.p_4()` is `p-4`, `.rounded_2xl()` is `rounded-2xl`, `ZINC.shade(900)` is `zinc-900`); in TSX, every element accepts the classes themselves in `class`, resolved natively against Tailwind 4's default theme. Each example below shows the typed methods first and the classes second:

```rust
use nsh_core::element::palette::ZINC;

view()
    .flex_row()
    .items_center()
    .gap_3()
    .rounded_2xl()
    .bg(AdaptiveColor::new(white(), ZINC.shade(800)))
    .p_4()
    .shadow_lg()
    .active(|s| s.scale(0.98))
    .child(
        text("Tailwind on native views")
            .text_base()
            .font_weight(FontWeight::SEMIBOLD)
            .text_color(AdaptiveColor::new(ZINC.shade(900), white())),
    )
```

```tsx
<View class="flex-row items-center gap-3 rounded-2xl bg-white p-4 shadow-lg active:scale-[0.98] dark:bg-zinc-800">
  <Text class="text-base font-semibold text-zinc-900 dark:text-white">Tailwind on native views</Text>
</View>
```

Typed methods lower into the same style rules the classes compile to, with no string to parse. For classes, no CSS is generated and nothing runs in JavaScript: the string is passed to the core, which parses each distinct class string once (and caches it), turns it into style rules, and applies them. Variants that depend on state (pressed, dark mode, window width) are re-applied by the core when that state changes, and pressed and focused states are tracked natively, so `active:` feedback (`.active(..)` in Rust) has no round trip to your code.

Classes and the [`style` prop](https://nsh.dev/versions/main/docs/styling.md) produce the same native styles and can be combined; this page covers what is specific to classes and their typed equivalents. The [Tailwind reference](https://nsh.dev/versions/main/modules/tailwind-reference.md) lists every supported utility.

## class and classList

```rust
view()
    .rounded_lg()
    .px_4()
    .py_2()
    .transition_colors()
    .bg(move || if selected.get() { INDIGO.shade(600) } else { ZINC.shade(200) })
    .style_when(busy, |s| s.opacity(0.5))
```

```tsx
<View
  class="rounded-lg px-4 py-2 transition-colors"
  classList={{ "bg-indigo-600": selected(), "bg-zinc-200": !selected(), "opacity-50": busy() }}
/>
```

- **`class`** is a string of classes. It can be dynamic: ``class={`h-6 rounded bg-${color()}-500`}`` works, because classes are resolved at run time.
- **`classList`** maps classes to conditions: a class applies while its value is truthy. It is applied after `class`.
- **In Rust**, a method given a closure or a signal follows it (`.bg(move || ..)`), `.style_when(condition, |s| ..)` applies styles while a condition holds, and `.when(condition, |v| ..)` decides once, when the element is made.

How conflicts resolve:

1. **Later classes win** over earlier ones in the same string: `"p-2 p-4"` is `p-4`. There is no need for `tailwind-merge`: a component can append the `class` its caller passes. Later methods win in Rust too.
2. **Variant classes apply after plain ones**, ordered by Tailwind's variant order (`hover:` before `active:`, `max-*:` widest first, breakpoints ascending, `dark:` last), whatever their position in the string. As in Tailwind, a class's highest variant decides, then its next highest, and a class with one more variant comes later: `dark:hover:bg-a dark:bg-b` is `bg-a` while hovered in dark mode, and `max-md:p-2 max-lg:p-4` is `p-2` below `md`. As in CSS, `odd:bg-a last:bg-b` gives an odd last row `bg-a`, because Tailwind sorts `odd` after `last`.
3. **`style` wins over classes.** A style key is the CSS property of its name, the one the classes set, so it replaces only that property: `style={{ paddingLeft: 8 }}` replaces `pl-4` and keeps `pr-4`.
4. `!` makes a class important: `!p-0`.

Rust components (`nsh/base`'s and those of an app's own crate) accept `class` and `classList` from TSX too; your classes are merged after the component's own styles and win at equal rank.

## Variants

| Variant | Applies when | Rust |
|---|---|---|
| `active:` | The view is pressed | `.active(\|s\| ..)` |
| `hover:` | A pointer is over the view (iPad and Mac pointers) | `.hover(\|s\| ..)` |
| `focus:`, `focus-visible:` | An input has focus | `.focus(\|s\| ..)` |
| `focus-within:` | The view or a descendant has focus (the content of an `Overlay` is a descendant of the view it is in) | `.focus_within(..)` |
| `disabled:`, `enabled:` | The element's `disabled` prop is true / false | `.disabled_style(\|s\| ..)` |
| `selected:` | The element is selected (a `Button`'s `selected`, `accessibilityState.selected`) | `.selected_style(..)` |
| `checked:` | The element is checked (`accessibilityState.checked` is `true`; `"mixed"` is not checked) | `.checked_style(..)` |
| `indeterminate:` | The element is indeterminate (`accessibilityState.checked` is `"mixed"`) | `.indeterminate_style(..)` |
| `aria-expanded:` | The element is expanded (`accessibilityState.expanded` is `true`): a `Popover`'s or `Menu`'s trigger while its popup is open | `.expanded_style(..)` |
| `aria-pressed:` | The element is a toggle button that is on (`accessibilityState.pressed` is `true`; `"mixed"` is not pressed). Not `active:`, a press in progress | `.aria_pressed(..)`, `.pressed_style(..)` |
| `aria-busy:`, `aria-checked:`, `aria-selected:` | `accessibilityState.busy`, `checked` (`true`, not `"mixed"`) or `selected` is `true`, as Tailwind's `aria-*` variants: after the pseudo-classes, in the order of their names | |
| `data-<name>:` | The element has the `data-*` attribute `name`, as Tailwind's boolean `data-*` variants (`&[data-range-start]`): what a component's part shows beyond its states, a calendar's day at the start of a range (`data-range-start:`). After the `aria-*` variants, in the order of their names | `Interactive::project_data(name, ..)` sets one on a component's part |
| `group-active:`, `group-hover:`, `group-focus:`, `group-focus-within:`, `group-disabled:`, `group-selected:`, `group-checked:`, `group-indeterminate:`, `group-aria-expanded:`, `group-aria-pressed:`, `group-aria-busy:`, `group-aria-checked:`, `group-aria-selected:`, `group-data-<name>:` | The nearest ancestor with the `group` class is in that state, or has that `data-*` attribute | `.group()` on the ancestor; `.group_active(..)`, `.group_hover(..)`, `.group_focus_within(..)` inside |
| `group-active/name:` ... | The same, for an ancestor marked `group/name` | `.group_named("name")`; `.group_active_named("name", ..)`, ... |
| `first:`, `last:`, `odd:`, `even:`, `only:` | The element's own position among its siblings. To color a row's label by the row's position, put `last:text-*` on the row: the label inherits it | Plain Rust from the row's index (`at.is_first()`, `at.is_last()`, `at.index() % 2`) |
| `placeholder:` | Styles an input's placeholder (`placeholder:text-zinc-400`) | `.placeholder_color(..)` |
| `selection:` | Colors the selection highlight of an input or a selectable text, and of those inside the element (`selection:bg-violet-200`) | `.selection_color(..)` |
| `dark:` | The system appearance is dark | An `AdaptiveColor`, or `.dark(\|s\| ..)` |
| `sm:`, `md:`, `lg:`, `xl:`, `2xl:` | The window is at least 640, 768, 1024, 1280, 1536 points wide | `.style_when(\|\| window().width >= px(768.0), \|s\| ..)` |
| `max-sm:`, `max-md:`, ... | The window is narrower than the breakpoint | The same, with `<` |
| `min-[600px]:`, `max-[600px]:` | Arbitrary breakpoints | The same |
| `portrait:`, `landscape:` | The window's orientation | `window().width > window().height` |
| `ios:`, `android:`, `web:` | The platform | `.when(os() == Os::Ios, \|v\| ..)` |
| `rtl:`, `ltr:` | The [layout direction](https://nsh.dev/versions/main/docs/layout.md#right-to-left) | `.direction(LayoutDirection::..)` on a view |
| `motion-safe:`, `motion-reduce:` | The user's reduce motion setting | `reduce_motion()` |

Variants combine: `dark:active:bg-zinc-700`, `md:landscape:flex-row`. In Rust, an `AdaptiveColor` in an `.active(..)` style is `dark:active:`.

```rust
view()
    .group()
    .flex_row()
    .items_center()
    .gap_3()
    .rounded_xl()
    .bg(white())
    .p_3()
    .active(|s| s.bg(ZINC.shade(50)))
    .child(text("Settings").flex_1().text_color(ZINC.shade(900)))
    .child(
        text("›")
            .text_color(ZINC.shade(300))
            .transition_transform()
            .group_active(|s| s.translate_x(px(4.0))),
    )
```

```tsx
<View class="group flex-row items-center gap-3 rounded-xl bg-white p-3 active:bg-zinc-50">
  <Text class="flex-1 text-zinc-900">Settings</Text>
  <Text class="text-zinc-300 transition-transform group-active:translate-x-1">›</Text>
</View>
```

`disabled` on any element (`.disabled(..)` in Rust) applies `disabled:` classes (`.disabled_style(..)`) and removes its press handlers from what is mounted, so it shows no press feedback either:

```rust
view()
    .disabled(saving)
    .on_press(save)
    .rounded_lg()
    .bg(EMERALD.shade(500))
    .px_4()
    .py_2()
    .active(|s| s.bg(EMERALD.shade(600)))
    .disabled_style(|s| s.opacity(0.4))
    .child(text("Save").font_weight(FontWeight::MEDIUM).text_color(white()))
```

```tsx
<View disabled={saving()} onPress={save} class="rounded-lg bg-emerald-500 px-4 py-2 active:bg-emerald-600 disabled:opacity-40">
  <Text class="font-medium text-white">Save</Text>
</View>
```

Breakpoints compare against the window (the surface NSH renders into), not the device: in an iPad split view or a resizable window, they follow the window's width, as `window()` does.

## What differs from Tailwind on the web

- **Units are points.** `p-4` (`.p_4()`) is 16 points (1 spacing step = 4pt, 1rem = 16pt). Arbitrary values in `px` are points too: `p-[13px]` (`.p(px(13.0))`) is 13pt.
- **`flex` is a row**, as in CSS: `class="flex"` lays out its children in a row unless a direction class says otherwise (anywhere in the string: `flex-col flex` is a column). A style's `display: "flex"` and Rust's `.flex()` are rows the same way, and a view that sets no display keeps NSH's default column. `block` and `flow-root` use block layout, and so do `inline` and `inline-block`, as a browser lays them out in a flex or grid parent. In Rust, `.flex_row()` and `.flex_col()` set the direction.
- **Text classes on views are inherited.** `text-*`, `font-*`, `leading-*`, `tracking-*` and the other text utilities on a view (`.text_color(..)`, `.font_weight(..)`, ... in Rust) pass to the text and input elements inside it, as CSS inheritance does: `<View class="text-white">` makes its labels white.
- **Every view is a box of its own.** `overflow-x-hidden` and `overflow-y-hidden` clip both axes, as `overflow-hidden` does (scrolling is the [scroll](https://nsh.dev/versions/main/elements/scroll.md) element's); `invisible` hides the view and everything in it; `mix-blend-*` blends a view with everything drawn behind it; `block` boxes keep their own margins and their children's apart; an `absolute` view is placed in its nearest positioned ancestor, as in CSS; `fixed` lays a view out in its root view (other elements are placed as `absolute`).
- **Text keeps its whitespace.** Spaces and line breaks in a string are drawn as written, and `whitespace-*` sets the wrapping; the JSX compiler collapses the whitespace of literal JSX text, as JSX does.
- **Transitions animate property groups**: `transition` animates colors, opacity, shadows and transforms, `transition-all` also corner radii and border widths; filters, backdrop filters, gradients and layout take their new values at once.
- **`focus-visible:` is `focus:`**: it applies whenever the element has focus.
- **State backgrounds show over gradients.** In CSS a gradient covers `background-color`, so `active:bg-*` on a `bg-linear-*` surface would never be seen; in NSH a background color from `active:`, `hover:`, `focus:` or `group-*:` replaces the gradient while that state holds (unless the state sets a gradient of its own, such as `active:from-*`). So do `activeStyle` and the other state styles, and animated background colors.
- **Text and touch settings are style keys**: `line-clamp-*` sets `numberOfLines`, `text-ellipsis` and `text-clip` set `textOverflow`, `truncate` both, `select-*` sets `userSelect` and `pointer-events-*` sets `pointerEvents`, so they work in state variants and lose to the inline `style` as every class does; `caret-*`, `placeholder:text-*` and `selection:bg-*` set the `caretColor`, `placeholderColor` and `selectionColor` styles the same way. In Rust these are `Styled` methods (`.number_of_lines(..)`, `.truncate()`, `.text_overflow(..)`, `.select_text()`, `.pointer_events(..)`, ...). `whitespace-nowrap` keeps a text on one line as a class. `object-*` set the `objectFit` and `objectPosition` styles of images and videos, which a style's keys replace as any other.
- **The supported set**: utilities and variants of Tailwind 4 that have a native meaning. `peer-*` variants, pseudo-elements (`before:`, `after:`) and arbitrary properties (`[mask-type:luminance]`) are reported as unknown classes, and so is every utility NSH has no native meaning for, so a class never means something else than in a browser. Rendering hints (`antialiased`, `will-change-transform`, `appearance-none`, `box-border`, ...) are accepted and change nothing.

Everything else works as documented by Tailwind 4: the color palette, opacity modifiers (`bg-black/40`), arbitrary values (`bg-[#34c759]`, `w-[72px]`, `grid-cols-[1fr_2fr]`; on `p`, `px`, `py`, `pt`, `pr`, `pb`, `pl` and the `m` utilities also the environment variables, `pt-[env(safe-area-inset-top)]`, `pb-[calc(env(keyboard-inset-height)+49px)]`, see [Safe area](https://nsh.dev/versions/main/elements/safe-area.md) and [Keyboard](https://nsh.dev/versions/main/elements/keyboard.md)), fractions (`w-1/2`, `translate-x-1/2`), shadows and rings, gradients (`bg-linear-to-r`, `bg-radial`, `bg-conic` with `from-` / `via-` / `to-`), filters, `backdrop-blur-*`, `mix-blend-*`, transforms, `transition-*` and `duration-*`, `animate-spin` / `ping` / `pulse` / `bounce`, and grid, each with its typed method in Rust. The platform limits of [filters and blending](https://nsh.dev/versions/main/docs/styling.md#filters-and-blending) apply to classes too.

## Theme

Classes resolve against Tailwind 4's default theme. Extend it in `nsh.json` under `"tailwind"`; your entries are added to the defaults (or replace the default of the same name):

```json
{
  "tailwind": {
    "colors": {
      "brand": { "50": "#f5f3ff", "500": "#7c3aed", "600": "#6d28d9", "DEFAULT": "#7c3aed" },
      "ink": "#1f2328"
    },
    "radius": { "card": 14 },
    "fontFamily": { "display": "Pacifico" },
    "breakpoints": { "tablet": 600 }
  }
}
```

With this theme, `bg-brand-500`, `text-brand` (the `DEFAULT` shade), `border-ink`, `rounded-card`, `font-display` and `tablet:flex-row` are valid classes.

| Key | Values | Makes |
|---|---|---|
| `colors` | A CSS color, or an object of shades (`"DEFAULT"` for the bare name) | `bg-*`, `text-*`, `border-*`, `from-*`, `ring-*`, ... |
| `spacing` | Points per spacing step (default 4) | `p-*`, `m-*`, `gap-*`, `w-*`, ... |
| `rem` | Points per `rem` in arbitrary values (default 16) | |
| `breakpoints` | Points | `name:` variants |
| `container` | Points | `max-w-*` sizes |
| `fontSize` | Points, or `[size, lineHeight]` with the line height a multiple of the size | `text-*` |
| `fontWeight` | 1–1000 | `font-*` |
| `fontFamily` | A family name (a system family or an [imported font's](https://nsh.dev/versions/main/docs/fonts.md) name) | `font-*` |
| `tracking` | Ems | `tracking-*` |
| `leading` | Multiples of the font size | `leading-*` |
| `radius` | Points | `rounded-*` |
| `shadow`, `insetShadow`, `dropShadow` | A CSS `box-shadow` | `shadow-*`, `inset-shadow-*`, `drop-shadow-*` |
| `blur` | Points | `blur-*`, `backdrop-blur-*` |
| `perspective` | Points | `perspective-*` |
| `aspect` | A ratio (`1.5`) | `aspect-*` |
| `ease` | `[x1, y1, x2, y2]` | `ease-*` |

Unknown keys and invalid values are build errors (`nsh.json: tailwind: unknown theme key 'colours'`). The theme is compiled into the bundle and applied before the first frame.

The Tailwind theme shapes your classes. Typed methods keep Tailwind's default scales, so a Rust component looks the same in every app, and take the app's look from the design tokens of its theme, `"theme"` in `nsh.json` ([Rust](https://nsh.dev/versions/main/docs/rust.md#theme)).

## Theme tokens

The app's theme (`"theme"` in `nsh.json`) holds its design tokens: shadcn/ui's colors (`background`, `foreground`, `primary`, `muted-foreground`, `border`, `ring`, `chart-1`, `sidebar`, ...), its `radius`, its fonts `font-sans` and `font-mono`, and any token the app adds. Classes name them as Tailwind names the variables of a CSS `@theme`, Rust components read them with `theme()` from `nsh_base`, and TSX reads them with `token()` from `nsh`, so a TSX screen and the Rust components follow the same theme:

```rust
use nsh_base::theme;

view()
    .rounded(move || theme().radius)
    .border_1()
    .border_color(move || theme().border)
    .bg(move || theme().card)
    .p_4()
    .child(text("Balance").text_color(move || theme().card_foreground))
    .child(text("Updated just now").text_color(move || theme().muted_foreground))
    .child(
        view()
            .rounded(move || theme().radius)
            .bg(move || theme().primary)
            .px_4()
            .py_2()
            .active(|s| s.bg(move || theme().primary.opacity(0.9)))
            .child(text("Continue").text_color(move || theme().primary_foreground)),
    )
```

```tsx
<View class="rounded-(--radius) border border-border bg-card p-4">
  <Text class="text-card-foreground">Balance</Text>
  <Text class="text-muted-foreground">Updated just now</Text>
  <View class="rounded-(--radius) bg-primary px-4 py-2 active:bg-primary/90">
    <Text class="text-primary-foreground">Continue</Text>
  </View>
</View>
```

A token's name is its CSS variable's without `--`, as the theme file writes it: `muted-foreground`, `radius`, `chart-1`. In Rust, shadcn's tokens are methods of `theme()` (`primary()`, `muted_foreground()`, `radius()`, `font_mono()`), and every token is `theme().color("up")`, `theme().number("radius-card")` or `theme().font("font-display")`.

| Form | Takes | Example |
|---|---|---|
| A color name in any color utility | A theme color, with an opacity too | `bg-primary`, `text-muted-foreground/70`, `bg-up/30`, `border-t-border`, `ring-ring`, `from-accent`, `placeholder:text-muted-foreground` |
| `(--name)`, Tailwind 4's variable shorthand | A theme color or number | `bg-(--primary)`, `rounded-(--radius)`, `p-(--gap-card)` |
| `(color:--name)`, `(length:--name)`, `(number:--name)`, `(family-name:--name)` | The same, typed where a utility takes several kinds | `text-(color:--up)`, `text-(length:--text-title)`, `font-(family-name:--font-mono)` |
| `font-sans`, `font-mono` | The theme's fonts, when it sets them | `font-mono` |

- **Your own tokens.** Every name in the theme file is a token, as every variable of a CSS `@theme` is: `"up": "#16a34a"` makes `bg-up`, `text-up` and `bg-up/30`; `"radius-card": "14px"` makes `rounded-(--radius-card)`; `"font-display": "Pacifico"` makes `font-(family-name:--font-display)`. Lengths are in points; `(number:--name)` passes the plain number.
- **Fonts.** `font-sans` is the app's font: every text that sets no family of its own is drawn with it, as a page is with Tailwind's `--font-sans`. `font-mono` is the font of `font-mono` and of code in `TextView`. Unset, both are the system's fonts.
- **Both appearances.** A token has the light and the dark value of the theme: `bg-primary`, `theme().primary` and `token("primary")` switch with the appearance by themselves, with no `dark:` class. A color the theme sets in one appearance only is used in both.
- **Your Tailwind colors win.** A name in `"tailwind"` `colors` or Tailwind's palette is that color, so `bg-primary` is a theme token when the Tailwind theme has no color `primary`.
- **The theme can change while the app runs.** When an app embedded in a native app is given that app's theme, and whenever the theme changes, the classes naming tokens, the Rust bindings reading `theme()` and the TSX code reading `token()` are updated, the classes and bindings natively. Tokens the embedding app's theme does not have keep the values of the app's own `"theme"` (then the default theme's). A host that only adds its brand gives theme overrides, the tokens its brand changes in the same file format ([iOS](https://nsh.dev/versions/main/docs/ios.md#theme-overrides), [Android](https://nsh.dev/versions/main/docs/android.md#theme-overrides), `AppView::set_theme_overrides` on the desktops).
- **Checked like other classes.** A name that is no token of the default theme or of the app's `"theme"` is an unknown class when building (`unknown class 'bg-chart-up'`). To use a token only the embedding app provides, give it a value in the app's `"theme"` too: that value shows when the app runs on its own.

Classes naming tokens are resolved once per theme, like any other class: drawing them costs what a palette color does.

### `token()` in TSX

`token(name)` from `nsh` is a token's value in the appearance shown: a color as `#rrggbbaa`, a length as a number of points, a font as its family name. It is reactive, so code that reads it in a component, a memo or an effect runs again when the theme or the appearance changes, which suits values that go where no class does, such as a canvas or a chart:

```tsx
import { Canvas, token } from "nsh";

<Canvas
  style={{ height: 160 }}
  draw={(cx, { width, height }) => {
    cx.beginPath();
    cx.moveTo(0, height);
    cx.lineTo(width, 0);
    cx.strokeStyle = token("chart-1");
    cx.lineWidth = 2;
    cx.stroke();
  }}
/>
```

The names are typed: NSH writes the app's tokens into `.nsh/types/nsh/tokens.d.ts` from its theme, so `token("up")` is a `string` once `"up"` is in the theme, and a name the theme lacks is a type error.

## The class check

`nsh build`, `nsh dev`, `nsh run` and `nsh test` check the static class names in your JSX (string literals in `class` and the keys of `classList`) with the same parser and theme the runtime uses, and warn about classes that do not exist:

```text
 warn nsh::build App.tsx:12:36: unknown class `bg-brand-550`
```

Warnings do not fail the build. Classes built at run time (``bg-${color()}-500``) are checked when the runtime first sees them, which logs each unknown class once (`unknown classes: ...`). Typed methods are checked by the Rust compiler.

## Classes or styles?

Both are resolved natively and cost about the same. Classes are shorter and give you variants (pressed states, dark mode, breakpoints) without code. Inline styles take values computed in JavaScript and accept [native animated values](https://nsh.dev/versions/main/docs/animation.md) (`opacity: fade`, `translate: [x, 0]`). Most TSX apps use classes for the static look and `style` for what is computed or animated. Rust components use typed methods for both, and bind animated values with `.bind_opacity(..)`, `.bind_translate_x(..)` and the other bindings.

## Related

- [Styling](https://nsh.dev/versions/main/docs/styling.md): the style prop, the typed methods and the platform limits of effects.
- [Tailwind reference](https://nsh.dev/versions/main/modules/tailwind-reference.md): every utility and variant.
- [Layout](https://nsh.dev/versions/main/docs/layout.md): flexbox and grid, also available as classes.

Source: https://nsh.dev/versions/main/docs/tailwind

---

# Layout

NSH lays out every element with [Taffy](https://github.com/DioxusLabs/taffy), a Rust implementation of CSS flexbox, grid and block layout, configured so that children stack vertically and do not shrink by default. Layout runs in the core, after each turn of your code, and only the frames that changed are sent to the native views. Text is measured by the platform's text engine on the same thread, so layout never waits for the main thread.

The layout properties below are style properties. In Rust they are typed style methods (`.flex_row()`, `.gap_4()`, `.grid_cols(3)`, `.absolute().inset_0()`); in TSX they are keys of the `style` prop, and each has a [Tailwind](https://nsh.dev/versions/main/docs/tailwind.md) class (`flex-row`, `gap-4`, `grid-cols-3`, `absolute inset-0`, ...). Both lower to the same native styles.

## Flexbox

A view lays out its children with flexbox. A view that sets no `display` stacks its children in a column; `display: "flex"` in a style makes a row unless `flexDirection` is set, exactly as in CSS and as Tailwind's `flex` class. Where nothing sets them, these defaults apply:

| Property | NSH default | Web default |
|---|---|---|
| `flexDirection` | `"column"` (a view that sets no `display`); `"row"` once `display: "flex"` is set | `row` |
| `flexShrink` | `0` | `1` |
| `alignContent` | `"flex-start"` (grids: `"normal"`) | `normal` |
| `alignItems` | `"stretch"` | `stretch` |
| `minWidth` / `minHeight` | `0` | `auto` |
| `position` | `"relative"` | `static` |

```rust
view()
    .flex_row()
    .items_center()
    .gap_3()
    .p_4()
    .child(image(avatar).size(px(40.0)).rounded(px(20.0)))
    .child(
        view()
            .flex_1()
            .gap_0p5()
            .child(text(name).font_weight(FontWeight::SEMIBOLD))
            .child(text(message).text_color(rgb(0x6e7781)).number_of_lines(1)),
    )
    .child(text(time).text_color(rgb(0x6e7781)))
```

```tsx
<View style={{ flexDirection: "row", alignItems: "center", gap: 12, padding: 16 }}>
  <Image src={avatar} style={{ width: 40, height: 40, borderRadius: 20 }} />
  <View style={{ flex: 1, gap: 2 }}>
    <Text style={{ fontWeight: "600" }}>{props.name}</Text>
    <Text style={{ numberOfLines: 1, color: "#6e7781" }}>{props.message}</Text>
  </View>
  <Text style={{ color: "#6e7781" }}>{props.time}</Text>
</View>
```

| Property | Values | Rust |
|---|---|---|
| `flexDirection` | `"column"`, `"row"`, `"column-reverse"`, `"row-reverse"` | `.flex_col()`, `.flex_row()`, `.flex_col_reverse()`, `.flex_row_reverse()` |
| `justifyContent` | Main axis: `"flex-start"`, `"flex-end"`, `"start"`, `"end"`, `"center"`, `"space-between"`, `"space-around"`, `"space-evenly"`, `"stretch"` | `.justify_start()`, `.justify_center()`, `.justify_end()`, `.justify_between()`, `.justify_around()`, `.justify_evenly()` |
| `alignItems` | Cross axis: `"stretch"`, `"flex-start"`, `"flex-end"`, `"start"`, `"end"`, `"self-start"`, `"self-end"`, `"center"`, `"baseline"` | `.items_stretch()`, `.items_start()`, `.items_center()`, `.items_end()`, `.items_baseline()` |
| `alignSelf` | One child's cross-axis alignment; `"auto"` follows the parent's `alignItems` | `.self_start()`, `.self_center()`, `.self_end()`, `.self_stretch()` |
| `alignContent` | Lines of a wrapping container | |
| `flexWrap` | `"nowrap"`, `"wrap"`, `"wrap-reverse"` | `.flex_wrap()` |
| `flex` | A single-number shorthand (below) | `.flex_1()`, `.flex_auto()`, `.flex_none()` |
| `flexGrow`, `flexShrink`, `flexBasis` | As in CSS | `.flex_grow(n)`, `.flex_shrink(n)`, `.flex_shrink_0()`, `.basis(length)` |
| `gap`, `rowGap`, `columnGap` | Space between children | `.gap(length)`, `.gap_y(length)`, `.gap_x(length)`, and the steps `.gap_2()`, `.gap_x_4()`, ... |

`flex-start` and `flex-end` follow the flex direction; `start` and `end` follow the writing direction, as in CSS (right to left, `start` is the right side), and `self-start` / `self-end` the child's own.

`flex` is CSS's shorthand, as Tailwind's `flex-*` classes are: a number `n` means grow by `n`, shrink by 1 and start from a basis of 0, so `flex: 1` siblings (`.flex_1()` in Rust, `flex-1`) share the space equally whatever their content; `"none"` is `0 0 auto` (the view keeps its size), `"auto"` is `1 1 auto`, `"initial"` is `0 1 auto`, and grow, shrink and basis can be written out (`"2 0 50%"`, `"1 1 120px"`). As minimum sizes default to 0, `flex: 0` (`0 1 0`) shrinks a view to nothing unless `minWidth: "auto"` keeps its content's size.

```rust
view()
    .flex_row()
    .gap_2()
    // One share.
    .child(view().flex_1().h(px(36.0)).bg(rgb(0xc8e1ff)))
    // Two shares.
    .child(view().flex_grow(2.0).flex_shrink(1.0).basis(px(0.0)).h(px(36.0)).bg(rgb(0x79b8ff)))
    // Fixed.
    .child(view().size(px(36.0)).bg(rgb(0x0366d6)))
```

```tsx
<View style={{ flexDirection: "row", gap: 8 }}>
  <View style={{ flex: 1, height: 36, backgroundColor: "#c8e1ff" }} />   {/* one share */}
  <View style={{ flex: 2, height: 36, backgroundColor: "#79b8ff" }} />   {/* two shares */}
  <View style={{ width: 36, height: 36, backgroundColor: "#0366d6" }} /> {/* fixed */}
</View>
```

Because minimum sizes default to 0, a `flex: 1` text in a row shrinks and wraps instead of pushing its siblings out. `minWidth: "auto"` / `minHeight: "auto"` (`min-w-auto` / `min-h-auto`, `.min_w(auto())` in Rust) is CSS's automatic minimum: a shrinking item stops at its content's smallest size, the longest word of a text, as on the web.

> [!NOTE]
> `display: "flex"` means a row, in a style, a class (`flex`) and Rust (`.flex()`) alike, unless a direction is set: `{ display: "flex", flexDirection: "column" }`, `flex flex-col`, `.flex().flex_col()`. A view without `display` needs nothing to be a column.

## Sizes

| Property | Values | Rust |
|---|---|---|
| `width`, `height` | Points, a percentage of the parent (`"50%"`), or `"auto"` | `.w(px(120.0))`, `.h(relative(0.5))`, `.w_full()`, `.size(px(44.0))`, the steps `.w_10()`, ... |
| `minWidth`, `maxWidth`, `minHeight`, `maxHeight` | Points or percentages; `minWidth` / `minHeight` also `"auto"`, the content's smallest size | `.min_w(..)`, `.max_w(..)`, `.min_h(..)`, `.max_h(..)` |
| `aspectRatio` | Width divided by height: `1`, `16 / 9` | `.aspect_ratio(16.0 / 9.0)`, `.aspect_square()` |
| `padding`, `paddingHorizontal`, `paddingVertical`, `paddingTop`, ... | Points or percentages | `.p(..)`, `.px(..)`, `.py(..)`, `.pt(..)`, ..., and the steps `.p_4()`, `.px_2()`, ... |
| `margin`, `marginHorizontal`, `marginVertical`, `marginTop`, ... | Points, percentages, or `"auto"` | `.m(..)`, `.mx(..)`, `.my(..)`, `.mt(..)`, ..., `.mx(auto())` |

In Rust a length is typed: `px(16.0)` is 16 points, `relative(0.5)` is 50% of the parent, `auto()` is `auto`. The step methods follow Tailwind's spacing scale of 4 points per step (`.p_4()` is 16 points, `.gap_0p5()` 2 points).

Without a size, a view is as big as its content (plus padding), stretched across its parent's cross axis by the default `alignItems: "stretch"`. Percentages are relative to the parent's size (for padding and margin, as in CSS, to its width).

`aspectRatio` sizes the other dimension from the one that is known:

```rust
view().w_full().aspect_ratio(16.0 / 9.0).bg(black())
```

```tsx
<View style={{ width: "100%", aspectRatio: 16 / 9, backgroundColor: "#000000" }} />
```

Images from the app's assets have a natural size and lay out at it when no size is given ([Images and assets](https://nsh.dev/versions/main/docs/images-and-assets.md)). Remote images have no size until they load: give them one.

## Grid

`display: "grid"` (`.grid()` in Rust) lays out children in CSS grid tracks:

```rust
view()
    .grid()
    .grid_template_columns("repeat(3, 1fr)")
    .gap_2()
    .child(view().col_span(2).h(px(60.0)).bg(rgb(0xd8b9ff)))
    .child(view().h(px(60.0)).bg(rgb(0xb083f0)))
    .child(view().row_span(2).bg(rgb(0x8250df)))
    .child(view().col_start(2).col_end(4).h(px(60.0)).bg(rgb(0x6639ba)))
```

```tsx
<View style={{ display: "grid", gridTemplateColumns: "repeat(3, 1fr)", gap: 8 }}>
  <View style={{ gridColumn: "span 2", height: 60, backgroundColor: "#d8b9ff" }} />
  <View style={{ height: 60, backgroundColor: "#b083f0" }} />
  <View style={{ gridRow: "span 2", backgroundColor: "#8250df" }} />
  <View style={{ gridColumn: "2 / 4", height: 60, backgroundColor: "#6639ba" }} />
</View>
```

| Property | Values | Rust |
|---|---|---|
| `gridTemplateColumns`, `gridTemplateRows` | CSS track lists: `"repeat(3, 1fr)"`, `"200px 1fr"`, `minmax()`, `auto-fill` / `auto-fit`, line names | `.grid_cols(3)`, `.grid_rows(2)`, `.grid_template_columns("200px 1fr")`, `.grid_template_rows(..)` |
| `gridAutoColumns`, `gridAutoRows` | Tracks of implicitly created columns and rows | |
| `gridAutoFlow` | `"row"`, `"column"`, `"dense"`, `"row dense"`, `"column dense"` | `.grid_flow_col()`, `.grid_flow_dense()` |
| `gridColumn`, `gridRow` | `"1 / 3"`, `"span 2"`, a line number or name: `"content-start / content-end"`, `"2 col"` (the second line named `col`), `"span col"` (up to the next line named `col`) | `.col_span(2)`, `.row_span(2)`, `.col_span_full()` |
| `gridColumnStart`, `gridColumnEnd`, `gridRowStart`, `gridRowEnd` | Line numbers or names | `.col_start(1)`, `.col_end(3)`, `.row_start(..)`, `.row_end(..)` (line numbers) |
| `justifyItems`, `justifySelf` | How items sit in their areas along the row: `"start"`, `"end"`, `"center"`, `"stretch"`, ... | |
| `alignItems`, `alignSelf` | How items sit in their areas along the column | `.items_*()`, `.self_*()` |
| `justifyContent`, `alignContent` | How the tracks sit in the grid along the row and the column | `.justify_*()` |

Templates name their lines in brackets, one or several names per line, and items are placed by those names, as in CSS (in Rust, by the lines' numbers):

```rust
view()
    .grid()
    .grid_template_columns("[full-start] 16px [content-start] 1fr [content-end] 16px [full-end]")
    // content-start / content-end: lines 2 to 3.
    .child(view().col_start(2).col_end(3).h(px(60.0)).bg(rgb(0xb083f0)))
    // full-start / full-end: lines 1 to 4.
    .child(view().col_start(1).col_end(4).h(px(60.0)).bg(rgb(0x8250df)))
```

```tsx
<View style={{ display: "grid", gridTemplateColumns: "[full-start] 16px [content-start] 1fr [content-end] 16px [full-end]" }}>
  <View style={{ gridColumn: "content-start / content-end", height: 60, backgroundColor: "#b083f0" }} />
  <View style={{ gridColumn: "full-start / full-end", height: 60, backgroundColor: "#8250df" }} />
</View>
```

In a grid, `justifyContent` and `alignContent` default to CSS's `"normal"`: tracks sized `auto` stretch to fill the container, so a grid with a height and no row template shares that height among its rows. A value set explicitly (`"start"`, `"center"`, `"space-between"`, ...) places the tracks as it does in CSS. The alignment classes set exactly what Tailwind CSS sets: `content-start` (`align-content: flex-start`) and `place-content-start` pack the tracks at the start, and `content-normal` and `justify-normal` stretch them, as in a browser.

`display: "block"` uses CSS block layout (children stacked, each as wide as the container), and `display: "none"` (`.hidden()`) removes the view from layout.

## Absolute positioning

`position: "absolute"` (`.absolute()`) takes a view out of the flow and places it by `top`, `right`, `bottom` and `left`, relative to its parent:

```rust
view()
    .h(px(200.0))
    .child(image(cover).absolute().inset_0())
    .child(
        view()
            .absolute()
            .left_3()
            .right_3()
            .bottom_3()
            .child(text("Caption").text_color(white()).font_weight(FontWeight::BOLD)),
    )
```

```tsx
<View style={{ height: 200 }}>
  <Image src={cover} style={{ position: "absolute", top: 0, right: 0, bottom: 0, left: 0 }} />
  <View style={{ position: "absolute", left: 12, right: 12, bottom: 12 }}>
    <Text style={{ color: "#ffffff", fontWeight: "700" }}>Caption</Text>
  </View>
</View>
```

Offsets accept points and percentages (`.top(..)`, `.right(..)`, `.bottom(..)`, `.left(..)`, `.inset(..)` in Rust). A view with `left` and `right` (or `top` and `bottom`) and no size stretches between them. Later siblings are drawn above earlier ones; `zIndex` (`.z_index(n)`) changes the order.

## Measuring

`onLayout` (`.on_layout(..)`) reports a view's frame, relative to its parent, after each layout in which it changed:

```rust
let width = signal(0.0_f32);

view()
    .on_layout(move |frame: &Bounds<Points>| width.set(frame.size.width.0))
    .child(text(move || format!("{} points wide", width.get())))
```

```tsx
const width = signal(0);

<View onLayout={({ bounds }) => width.set(bounds.size.width)}>
  <Text>{width()} points wide</Text>
</View>
```

The frame is in points: `Bounds<Points>` in Rust, `{ bounds }` in TSX, a `Bounds` (`{ origin: { x, y }, size: { width, height } }`). For the whole window, read `window()` in Rust or `windowSize()` from [`nsh`](https://nsh.dev/versions/main/modules/nsh.md#device) in TSX; both follow rotation and window resizing, and a style that reads them changes with the window:

```rust
view().style_when(|| window().width > px(600.0), |s| s.flex_row())
```

```tsx
import { View } from "nsh";
import { windowSize } from "nsh";

<View style={{ flexDirection: windowSize().width > 600 ? "row" : "column" }} />
```

Tailwind's breakpoints (`sm:`, `md:`, ...) and `portrait:` / `landscape:` give the same result without code.

## Safe areas

The root view covers the whole screen, under the status bar and the home indicator. Pad screens by the safe area insets with CSS's `env()` (`paddingTop: "env(safe-area-inset-top)"`, Tailwind `pt-[env(safe-area-inset-top)]`, `.p_safe_area()` in Rust; see [Safe area](https://nsh.dev/versions/main/elements/safe-area.md)), or read the insets with `safe_area()` in Rust or `safeArea()` / `safeAreaInsets()` in TSX and apply them yourself. Pages of a [navigation stack](https://nsh.dev/versions/main/docs/navigation.md) already sit below their header.

## Right to left

The app's layout direction follows the system language, and a view's `direction` style (`"ltr"`, `"rtl"` or `"inherit"`; `.direction(LayoutDirection::Rtl)` in Rust) sets the direction of its subtree. When the app lays out right to left:

- rows run from the right;
- `left` and `right` keep their sides, as in a browser, in style keys and classes alike: `paddingLeft`, `marginLeft`, `left`, `borderLeftWidth`, `borderTopLeftRadius`, `textAlign: "left"` and `pl-4`, `ml-2`, `left-0`, `border-l`, `rounded-tl-lg`, `text-left` stay on the left;
- the logical properties follow the direction, inline start being the right side: `marginStart`, `marginEnd`, `paddingStart`, `paddingEnd`, `start`, `end`, `borderStartWidth`, `borderEndColor`, `borderTopStartRadius`, ..., `textAlign: "start"` / `"end"` (`ps-4`, `ms-2`, `start-0`, `border-s`, `rounded-ss-lg`, `text-start` as classes; `.ms(..)`, `.me(..)`, `.ps(..)`, `.pe(..)`, `.border_s(..)`, `.rounded_ss(..)`, ... in Rust); `marginHorizontal` and `paddingHorizontal` set both sides;
- text with `textAlign: "auto"` aligns right, and native controls mirror.

```rust
view()
    .flex_row()
    .gap_2()
    .child(view().ms_4().rounded_ss(px(12.0)).size(px(44.0)).bg(rgb(0x54aeff)))

let rtl = signal(false);
view()
    .direction(move || if rtl.get() { LayoutDirection::Rtl } else { LayoutDirection::Ltr })
    .on_press(move |_: &()| rtl.set(!rtl.get()))
    .child(text(move || if rtl.get() { "Right to left" } else { "Left to right" }))
```

```tsx
import { signal, Text, View } from "nsh";

const rtl = signal(false);

<View style={{ direction: rtl() ? "rtl" : "ltr" }}>
  <View style={{ flexDirection: "row", gap: 8 }}>
    <View style={{ marginStart: 16, borderTopStartRadius: 12, width: 44, height: 44, backgroundColor: "#54aeff" }} />
  </View>
  <View onPress={() => rtl.set(!rtl())}>
    <Text>{rtl() ? "Right to left" : "Left to right"}</Text>
  </View>
</View>
```

Changes to the direction, the language's or a view's, apply at once, without a restart. The `direction` style also keeps one view and its children in a direction of their own, for example a phone number left to right. On Android, apps that embed NSH need `android:supportsRtl="true"` in their manifest for native controls to mirror.

## Related

- [Styling](https://nsh.dev/versions/main/docs/styling.md): how styles combine.
- [Scrolling](https://nsh.dev/versions/main/docs/scrolling.md) and [Lists](https://nsh.dev/versions/main/docs/lists.md): content larger than the screen.
- [Style reference](https://nsh.dev/versions/main/modules/style-reference.md): every layout property and its type.

Source: https://nsh.dev/versions/main/docs/layout

---

# Text

All text is shown by text elements: `text(..)` in Rust, `<Text>` in TSX. A text element is one paragraph, typeset by the platform's text engine (CoreText on Apple platforms, `StaticLayout` on Android) on the engine thread when it is laid out, and only drawn on the main thread. Nested text elements are spans of the same paragraph, not separate views.

```rust
text("By continuing you agree to the ")
    .text_size(px(16.0))
    .line_height(px(24.0))
    .text_color(rgb(0x1f2328))
    .child(
        text("Terms of service")
            .text_color(rgb(0x0969da))
            .underline()
            .on_press(open_terms),
    )
    .child(".")
```

```tsx
<Text style={{ fontSize: 16, lineHeight: 24, color: "#1f2328" }}>
  By continuing you agree to the{" "}
  <Text style={{ color: "#0969da", textDecorationLine: "underline" }} onPress={openTerms}>
    Terms of service
  </Text>
  .
</Text>
```

> [!IMPORTANT]
> Strings are displayed by text elements. In TSX, a string placed directly in a `<View>` is not shown: wrap it in `<Text>`.

The element itself is documented on [text](https://nsh.dev/versions/main/elements/text.md); this page is about using it.

## Strings and whitespace

In Rust, a text's content is a string, shown as written: `\n` breaks the line. Content that reads signals is a closure, and the text updates when they change. In TSX, JSX text follows the same rules as in React: each line is trimmed, lines that are only whitespace are dropped, and the remaining lines are joined with a single space. Whitespace within one line is kept, so `{first} {last}` keeps its space. Use `{" "}` for a space at the start or end of a line, and `{"\n"}` for a line break:

```rust
text(move || format!("Hello, {}!\nWelcome back.", name.get()))
```

```tsx
<Text>
  Hello,
  {name()}!{"\n"}
  Welcome back.
</Text>
```

Expressions in text follow what they read: `text(move || format!("{} items", count.get()))` and `<Text>{count()} items</Text>` update when `count` changes.

## Spans and inheritance

A text inside a text is a span. It inherits the text style of its parent and overrides what it sets:

```rust
text("")
    .text_size(px(17.0))
    .text_color(rgb(0x1f2328))
    .child(text("Light ").font_weight(FontWeight::LIGHT))
    .child(text("Bold ").font_weight(FontWeight::BOLD))
    .child(text("Italic ").italic())
    .child(text("Spaced").letter_spacing(px(4.0)))
```

```tsx
<Text style={{ fontSize: 17, color: "#1f2328" }}>
  <Text style={{ fontWeight: "300" }}>Light </Text>
  <Text style={{ fontWeight: "700" }}>Bold </Text>
  <Text style={{ fontStyle: "italic" }}>Italic </Text>
  <Text style={{ letterSpacing: 4 }}>Spaced</Text>
</Text>
```

Text styles also pass down from views, as in CSS: `view().text_color(white()).text_sm()` in Rust and `<View class="text-white text-sm">` in TSX style the text and input elements inside them.

### Links

A span with a press handler (`.on_press(..)` or `.on_long_press(..)`; `onPress` or `onLongPress`) is a link: a press on its characters goes to the span, a press elsewhere to the paragraph. Links in nested spans work too.

```rust
text("Read the ")
    .on_press(move || tapped.set("the sentence"))
    .child(text("terms").text_color(rgb(0x0969da)).on_press(move || tapped.set("terms")))
    .child(" first.")
```

```tsx
<Text onPress={() => log("the sentence")}>
  Read the <Text style={{ color: "#0969da" }} onPress={() => open(termsUrl)}>terms</Text> first.
</Text>
```

### Backgrounds of spans

A span's background color and corner radius paint a box behind its characters on each line it reaches, as tall as
its font; the text lays out the same and copies whole, so inline code is a span
([Text element](https://nsh.dev/versions/main/elements/text.md#span-backgrounds)):

```rust
text("Run ")
    .child(text(" npm test ").font_family("ui-monospace").bg(rgb(0xeff1f3)).rounded(px(4.0)))
    .child(" first.")
```

```tsx
<Text>
  Run <Text style={{ fontFamily: "ui-monospace", backgroundColor: "#eff1f3", borderRadius: 4 }}> npm test </Text> first.
</Text>
```

### Views and images inside text

Any element other than a text inside a text is laid out inline, on the baseline, and wraps with the words. It can take presses of its own:

```rust
text("Made with ")
    .text_size(px(16.0))
    .line_height(px(26.0))
    .child(image(LOGO).size(px(18.0)))
    .child(" nsh. Status ")
    .child(
        view()
            .bg(rgb(0x1a7f37))
            .rounded(px(9.0))
            .px(px(7.0))
            .h(px(18.0))
            .justify_center()
            .child(text("LIVE").text_color(white()).text_size(px(11.0)).font_weight(FontWeight::BOLD)),
    )
```

```tsx
<Text style={{ fontSize: 16, lineHeight: 26 }}>
  Made with <Image src={logo} style={{ width: 18, height: 18 }} /> nsh. Status{" "}
  <View style={{ backgroundColor: "#1a7f37", borderRadius: 9, paddingHorizontal: 7, height: 18, justifyContent: "center" }}>
    <Text style={{ color: "#ffffff", fontSize: 11, fontWeight: "700" }}>LIVE</Text>
  </View>
</Text>
```

Inline elements cut off by `numberOfLines` or an ellipsis are hidden; copying the text leaves them out. Text inside an
inline element takes the color of the text around it, as CSS's `color` reaches an inline block, unless it sets its own
(the `LIVE` badge above does); its font and line height stay its own.

The style key `verticalAlign` places an inline element in its line, as CSS's `vertical-align` places an image:
`"baseline"` (the default) stands its bottom on the baseline, `"text-top"` and `"text-bottom"` put its top or bottom
at the top or bottom of the text's font, and `"middle"` centers it half the font's x height above the baseline. The
line grows to hold the element wherever it reaches past the font, also with a fixed `lineHeight`. An icon at the start of a paragraph that should
line up with the text's bottom, as Android's `ImageSpan` draws it, takes `"text-bottom"`. The classes are
`align-baseline`, `align-text-top`, `align-text-bottom` and `align-middle`; in Rust `.align_text_bottom()` and the
others of the same names.

```tsx
<Text style={{ fontSize: 16 }}>
  <Image src={badge} style={{ width: 16, height: 16, verticalAlign: "text-bottom" }} /> Verified seller
</Text>
```

## Text styles

| Property | Values | Rust |
|---|---|---|
| `color` | A [color](https://nsh.dev/versions/main/docs/styling.md#colors). Default black | `.text_color(..)` |
| `fontSize` | Points. Default 14 | `.text_size(px(..))`, `.text_sm()`, `.text_lg()`, ... |
| `fontWeight` | `"normal"` (400), `"bold"` (700), or `100`–`900` (number or string) | `.font_weight(FontWeight::BOLD)` |
| `fontStyle` | `"normal"`, `"italic"`: color emoji stay upright | `.italic()` |
| `fontFamily` | A system family, a generic family, or an [imported font](https://nsh.dev/versions/main/docs/fonts.md) | `.font_family(..)` |
| `lineHeight` | Points | `.line_height(px(..))` |
| `letterSpacing` | Points | `.letter_spacing(px(..))` |
| `textAlign` | `"auto"`, `"left"`, `"center"`, `"right"`, `"justify"`, `"start"`, `"end"`: `left` and `right` keep their sides right to left, `start` and `end` follow the direction | `.text_left()`, `.text_center()`, `.text_right()`, `.text_justify()` |
| `textAlignVertical` | `"auto"`, `"top"`, `"center"`, `"bottom"`: where text shorter than its box sits | |
| `textTransform` | `"none"`, `"uppercase"`, `"lowercase"`, `"capitalize"` | `.normal_case()`, `.uppercase()`, `.lowercase()`, `.capitalize()` |
| `textDecorationLine` | `"none"`, `"underline"`, `"line-through"`, `"underline line-through"` | `.no_underline()`, `.underline()`, `.line_through()` |
| `textDecorationColor`, `textDecorationStyle` | Color; `"solid"`, `"double"`, `"dotted"`, `"dashed"`, `"wavy"` | `.text_decoration_color(..)`, `.text_decoration_wavy()`, ... |
| `textDecorationThickness`, `textUnderlineOffset` | Points, or `"auto"` (thickness also `"from-font"`) | `.text_decoration_thickness(px(..))`, `.underline_offset(px(..))` |
| `textShadow` | CSS's `text-shadow`, a shadow behind the glyphs: `"2px 2px 4px rgb(0 0 0 / 0.6)"` (offsets, blur, color), or its layers as numbers, `[{ x: 2, y: 2, blur: 4, color: "#00000099" }]`; several layers draw as the widest | `.text_shadow([TextShadow { .. }])`, `.text_shadow_sm()`, ..., `.text_shadow_color(..)` |
| `fontVariant` | OpenType features: `["tabular-nums"]`, `"small-caps"`, `"oldstyle-nums"`, `"lining-nums"`, `"proportional-nums"` | `.tabular_nums()`, `.small_caps()`, `.oldstyle_nums()`, `.lining_nums()`, `.proportional_nums()` |
| `writingDirection` | `"auto"`, `"ltr"`, `"rtl"`: the base direction of the paragraph | `.writing_direction(WritingDirection::Rtl)` |

A text element is also a view: it takes backgrounds, borders, corners, padding and the other [view styles](https://nsh.dev/versions/main/docs/styling.md).

```rust
text(move || format!("{:.2}", price.get())).text_size(px(18.0)).tabular_nums()
text("Typo").underline().text_decoration_wavy().text_decoration_color(rgb(0xcf222e))
text("Shadow")
    .text_size(px(26.0))
    .font_weight(FontWeight::EXTRA_BOLD)
    .text_color(white())
    .text_shadow([TextShadow {
        offset_x: px(2.0),
        offset_y: px(2.0),
        radius: px(4.0),
        color: rgba(0x00000099).into(),
    }])
```

```tsx
<Text style={{ fontSize: 18, fontVariant: ["tabular-nums"] }}>{price().toFixed(2)}</Text>
<Text style={{ textDecorationLine: "underline", textDecorationStyle: "wavy", textDecorationColor: "#cf222e" }}>Typo</Text>
<Text style={{ fontSize: 26, fontWeight: "800", color: "#ffffff", textShadow: "2px 2px 4px rgba(0,0,0,0.6)" }}>
  Shadow
</Text>
```

`tabular-nums` gives every digit the same width, which keeps counters and prices from jittering as they change.

## Truncation

```rust
text(long_description).number_of_lines(2)
text(file_path).number_of_lines(1).text_overflow(EllipsizeMode::Middle)
```

```tsx
<Text style={{ numberOfLines: 2 }}>{longDescription}</Text>
<Text style={{ numberOfLines: 1, textOverflow: "ellipsis-middle" }}>{filePath}</Text>
```

| Style key / prop | Rust | Description |
|---|---|---|
| `numberOfLines` (style) | `.number_of_lines(n)` | The most lines shown; `0` (default) shows them all |
| `textOverflow` (style) | `.text_overflow(EllipsizeMode::Middle)` | How text that does not fit is cut: an ellipsis at the end (`"ellipsis"`, default), at the start (`"ellipsis-start"`) or in the middle (`"ellipsis-middle"`), or `"clip"` |
| `adjustsFontSizeToFit` | `.shrink_to_fit(min_scale)` | Shrink the font until the text fits its lines and box |
| `minimumFontScale` | | How far `adjustsFontSizeToFit` may shrink (0–1) |

```rust
text(move || total.get())
    .number_of_lines(1)
    .shrink_to_fit(0.5)
    .text_size(px(48.0))
    .w(px(200.0))
```

```tsx
<Text adjustsFontSizeToFit minimumFontScale={0.5} style={{ numberOfLines: 1, fontSize: 48, width: 200 }}>
  {total()}
</Text>
```

The Tailwind classes `line-clamp-*`, `text-ellipsis` and `text-clip` set the same keys, and `truncate` (`.truncate()`) is one line cut with an ellipsis; as style keys they also take state styles and variants.

## System text size

Text follows the user's text size setting (Dynamic Type on iOS, font size on Android) by default.

| Prop | Rust | Description |
|---|---|---|
| `allowFontScaling` | `.allow_font_scaling(false)` | `false` keeps the size fixed. Default `true` |
| `maxFontSizeMultiplier` | `.max_font_size_multiplier(1.5)` | The largest scale applied, e.g. `1.5`. `0` is no limit |

`font_scale()` in Rust and `fontScale()` from [`nsh`](https://nsh.dev/versions/main/modules/nsh.md#device) in TSX are the current scale, and change when the user changes the setting. Inputs take `allowFontScaling` and `maxFontSizeMultiplier` too.

```rust
text("Tab label").max_font_size_multiplier(1.3).text_size(px(13.0))
```

```tsx
<Text maxFontSizeMultiplier={1.3} style={{ fontSize: 13 }}>Tab label</Text>
```

Prefer limiting the scale over turning it off: large text is an accessibility setting people rely on.

## Selection

The style key `userSelect: "text"` (`.select_text()`, the class `select-text`) lets the user select and copy the text, as in the system's own text views: a long press selects the word under the finger, the handles move the selection's ends, and the edit menu offers Copy and Select All (iOS adds Look Up, Translate and Share; Android Share). A selection stays inside one text block. The style key `selectionColor` (`.selection_color(..)`, `selection:text-*`) colors the highlight and the handles. `userSelect` set on a view reaches the texts inside it that set none.

In desktop browsers text is selectable by default, as on a web page, except inside interactive elements (views with press or touch handlers, such as buttons and pressable rows); `userSelect: "none"` (`.select_none()`, the class `select-none`) keeps a text unselectable there. Phone and tablet browsers follow the native rule.

```rust
text(order_number).select_text().selection_color(rgb(0x7c3aed))
```

```tsx
<Text style={{ userSelect: "text", selectionColor: "#7c3aed" }}>{orderNumber}</Text>
```

To copy from code (a Copy button), use `set_clipboard(..)` in Rust or [`Clipboard`](https://nsh.dev/versions/main/modules/nsh.md#clipboard) in TSX.

In the terminal host, drag across a selectable view or Text to select whole graphemes; a double click selects a word and a triple click its paragraph, and dragging on from either extends the selection by words or paragraphs.
Selected Cells use reversed colors. Copy with Ctrl+C, Ctrl+Shift+C, Ctrl+Insert, Alt+W or Cmd+C; the host sends the
text through OSC 52 to the terminal clipboard. Shift+click extends the selection, Ctrl+A / Cmd+A selects the area,
and Esc or any other key clears it. With nothing selected, Ctrl+C quits the terminal host.

## onTextLayout

`onTextLayout` (the `TextLayout` event in Rust) reports the laid-out lines after each layout, in the text's content box:

```rust
text(move || body.get()).on(EventKind::TextLayout, move |e: &EventPayload| {
    if let EventPayload::TextLayout(laid_out) = e {
        lines.set(laid_out.len());
    }
})
```

```tsx
<Text
  onTextLayout={(e) => {
    lines.set(e.lines.length);
    console.log(e.lines.map((l) => `${l.text} (${l.bounds.size.width.toFixed(0)}pt)`));
  }}
>
  {body()}
</Text>
```

Each line has `text`, `x`, `y`, `width`, `height`, `ascender`, `descender`, `capHeight` and `xHeight` (`cap_height` and `x_height` in Rust). Use it to show a "Read more" button only when text was cut, or to align other content with a baseline.

## Accessibility

A text element is read by screen readers as its content. Give a role to text that acts as a heading (`.role(AccessibilityRole::Header)`, `role="header"`) and to links (`AccessibilityRole::Link`, `role="link"`). See [Accessibility](https://nsh.dev/versions/main/docs/accessibility.md).

## Related

- [Fonts](https://nsh.dev/versions/main/docs/fonts.md): custom fonts and weights.
- [text element](https://nsh.dev/versions/main/elements/text.md): every prop.
- [Forms and keyboard](https://nsh.dev/versions/main/docs/forms-and-keyboard.md): text input.

Source: https://nsh.dev/versions/main/docs/text

---

# Images and assets

The image element (`image(..)` in Rust, `<Image>` in TSX) shows a bitmap or an SVG drawing: a file shipped with the app, or an image downloaded from a URL. Images are read and decoded off the main thread, downsampled to the size the view shows them at, and cached; the main thread only displays the decoded result.

```rust
const LOGO: ImageAsset = asset!("logo@2x.png");

image(LOGO)
image("https://picsum.photos/seed/nsh/600/400").w_full().h(px(200.0)).rounded(px(12.0))
```

```tsx
import { Image } from "nsh";
import logo from "./assets/logo@2x.png";

<Image src={logo} />
<Image src="https://picsum.photos/seed/nsh/600/400" style={{ width: "100%", height: 200, borderRadius: 12 }} />
```

The element's props are listed on [image](https://nsh.dev/versions/main/elements/image.md).

## Images in the app

A Rust crate keeps its files in its `assets/` directory: `asset!("logo@2x.png")` (the path relative to `assets/`) is an `ImageAsset`, `{ url, size, scales }`, read when the crate compiles, and `registry.assets(assets!())` in the crate's `#[native_module]` function ships every file of the directory with the app. In TSX, import an image file like a module: the import gives an `ImageAsset`, `{ url, size, scales? }`, and the bundler ships the file with the app:

```rust
const LOGO: ImageAsset = asset!("logo@2x.png");

// LOGO.url: "asset:/@my-app/logo@2x.png", LOGO.size: 64 × 64 points

#[native_module("app/native")]
fn native(registry: &mut Registry) {
    registry.assets(assets!());
}
```

```tsx
import logo from "./assets/logo@2x.png";

logo; // { url: "asset:/assets/logo@2x.png", size: { width: 64, height: 64 } }
```

Supported files: `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.heic`, and `.svg` ([SVG images](#svg-images)).

**Sizes are in points.** An `@2x` or `@3x` suffix in the file name says the file has 2 or 3 pixels per point, so `logo@2x.png` at 128×128 pixels is a 64×64 point asset. Without a suffix, one pixel is one point. A file named with a suffix is the one that shows; a file named without one shows its [pixel-density variants](#pixel-densities) when it has them.

**Natural size.** An image from an asset lays out at its natural size when its style leaves the width or height open, so `image(LOGO)` and `<Image src={logo} />` need no style. Set one dimension and the aspect ratio, or both, to size it differently.

In Rust, a missing or broken file fails the build, and a changed one builds the crate again. In TSX, assets are resolved relative to the importing module, and their `url` is relative to the app's root (the entry's directory). `nsh build` copies them to `out/assets/`, `nsh package` puts them in the app, and during development the dev server serves them.

> [!TIP]
> In TSX, `src` also accepts `asset:/path` strings, and imported files are the ones guaranteed to ship. A path that is never imported works with the dev server, which serves the whole app directory, and is missing from packaged apps. Import every image you use. A Rust crate ships its whole `assets/` directory through `assets!()`.

### Pixel densities

Name the file without a suffix and put its denser versions next to it, and the app loads the one that fits the screen:

```text
assets/
├── logo.png       64×64 pixels
├── logo@2x.png    128×128
└── logo@3x.png    192×192
```

```rust
const LOGO: ImageAsset = asset!("logo.png");

// LOGO.size: 64 × 64 points, LOGO.scales: [1.0, 2.0, 3.0]
```

```tsx
import logo from "./assets/logo.png";

logo; // { url: "asset:/assets/logo.png", size: { width: 64, height: 64 }, scales: [1, 2, 3] }
```

- `asset!` and the bundler look for `@1.5x`, `@2x`, `@3x` and `@4x` siblings of an image named without a suffix. `scales` lists them, with 1 for the named file; an image without siblings has no scales (in TSX it imports as `{ url, size }`). The bundler ships the siblings it finds, and `assets!()` ships the whole directory.
- The image loads the smallest scale at least the screen's pixel ratio, otherwise the largest, as React Native picks: `logo.png` on a 1× screen, `logo@2x.png` on a 2× one, `logo@3x.png` on a 3× phone (and at 2.625). On the web only that file is downloaded.
- When the pixel ratio changes (a window moved to another screen, browser zoom), the images whose choice changes load again, with their [load events](#load-events). Their size stays the named file's size, in points.
- A variant whose pixels are not the named file's size times its scale gets a build warning in TSX and fails the build in Rust.
- A file named with a density suffix (`./logo@3x.png`, `asset!("logo@3x.png")`) is that file alone.
- An [SVG image](#svg-images) is drawn for the screen at any ratio, so it ships no variants.

One file is fine too: export it at the highest density you need (`@3x` for the sharpest result on every phone) and name it with its suffix; images are downsampled to the screen when decoded. Variants let each screen download, decode and keep the file that fits it.

## SVG images

Import an `.svg` file like any image. Its size in points is its `width` and `height` (or one of them, with the other from the `viewBox`'s aspect ratio), else its `viewBox`: a CSS pixel of the SVG is a point, and `@2x` suffixes leave SVG files as they are.

```tsx
import logo from "./assets/logo.svg"; // <svg width="120" height="40" …>
import star from "./assets/star.svg"; // <svg viewBox="0 0 24 24" …>

logo; // { url: "asset:/assets/logo.svg", size: { width: 120, height: 40 } }

<Image src={logo} />
<Image src={star} style={{ width: 36, height: 36, tintColor: "#0969da" }} />
```

An SVG is sharp at the size it is shown. The browser draws it as vectors; iOS, macOS and Android draw it at the size the view shows it, in pixels, when the image loads (as they downsample bitmaps; a view that grows afterwards scales that drawing, until the image loads again); Windows, Linux and GPUI draw it once at four pixels per point (up to 2048 pixels a side) and scale it to each view. Everything else works as for bitmaps: `objectFit`, `tintColor` (through the SVG's opaque shapes, so one-color icons follow the theme), filters, `blurRadius`, placeholders, the load events, `Image.getSize` and `Image.prefetch`. `onLoad` and `Image.getSize` report an SVG's size in whole points; the image lays out at its exact size. Remote SVG files load the same way, through the same downloads and [capability](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md) checks; NSH recognizes an SVG by its content (also gzip-compressed, `.svgz`), whatever its URL ends with.

**What native platforms draw.** iOS, macOS, Android, Windows, Linux and GPUI draw SVGs with one renderer (resvg), so a drawing looks the same on each: shapes and paths, fills and strokes, gradients and patterns, clip paths and masks, opacity, filters and transforms. Text (`<text>`), animation (SMIL and CSS), embedded images (`<image>`) and HTML (`<foreignObject>`) show in the browser; native platforms draw the rest of the SVG, still, and `nsh build` names the files that use them. Export text as outlines (paths) for the same result everywhere.

**A self-contained picture.** On native platforms an SVG draws only what it holds: files, URLs, `data:` images and other documents it references are left out. Native platforms draw SVGs, remote ones included, within bounds that keep memory in check: a document of up to 16 MiB (a compressed one once inflated), a drawing of up to 8192 pixels a side and 4096 × 4096 pixels in all (64 MiB; a larger one is drawn smaller), and layers (groups with opacity, masks, clip paths and filters, which the renderer draws apart) of up to 256 MiB at once. An SVG over the document or layer bound fails to load, with `onError`.

**Reported sizes on the web.** The browser measures SVGs itself, imported or remote: `onLoad` and `Image.getSize` report an SVG's `width` and `height` when it has them, and otherwise the size the browser gives it, which browsers typically derive from a default of 300 × 150 and the `viewBox`'s aspect ratio. Imported SVGs lay out at the bundler's size on every platform. Give SVGs a `width` and `height` for the same reported size everywhere.

## Remote images

Give the element a URL: a string in Rust (a closure for one that changes), a URL string in TSX:

```rust
image(move || user.with(|u| u.avatar_url.clone()))
    .size(px(48.0))
    .rounded(px(24.0))
    .bg(rgb(0xeaeef2))
```

```tsx
<Image src={user().avatarUrl} style={{ width: 48, height: 48, borderRadius: 24, backgroundColor: "#eaeef2" }} />
```

- **Give remote images a size.** Their size is unknown until they load, so without a width and height (or one of them and an aspect ratio) they collapse to no height.
- **A background color** shows while the image loads, or use a placeholder (below).
- Downloads are shared: several views showing the same URL download it once, also when they decode it at different sizes. A download nobody waits for any more is cancelled.
- Decoded images are cached in memory (the cache is purged under memory pressure), keyed by URL, decode size and blur radius.
- When the app declares [capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md), the image's host must be allowed under `network`; a refused image fails with its error event.

### Kept on disk

Downloaded images are also kept on disk, as the server sent them, so an app that is opened again (a conversation full
of avatars and photos, a feed) shows the images it showed before without downloading them, also offline. The app
needs no setting: every image with an `http://` or `https://` URL goes through the cache on iOS, Android, macOS,
Windows, Linux and GPUI, and in the browser the browser's own HTTP cache does the same.

The cache follows the server's HTTP caching headers:

- An image is kept unless the response says `Cache-Control: no-store`.
- It is used without a request while it is fresh: for `max-age`, else until `Expires`, else for a tenth of the time
  since `Last-Modified` (at most a week).
- After that it is checked with the server (`If-None-Match` with its `ETag`, `If-Modified-Since` with its
  `Last-Modified`): an unchanged image (`304`) is used again without downloading it, a changed one replaces it.
- When the request fails (no network) or the server has an error (`5xx`), the kept copy is shown, unless the response
  said `must-revalidate` or `no-cache`.

Each app has its own cache of 256 MiB; past that, the images used least recently are dropped first. Several views,
surfaces and processes of one app share it safely. Embedding apps choose where it is and how large, or turn it off:

```rust
// macOS, Windows, Linux and GPUI: the AppView's options (or AppView::set_cache).
let mut cache = CacheOptions::at(CacheLocation::Dir(caches.join("nsh")));  // each app in <dir>/<app id>
cache.images = CachePolicy::MaxSize(ByteSize::mib(64));                     // CachePolicy::Off: none
let view = AppView::new(mtm, AppOptions { cache, ..AppOptions::default() });
```

```swift
// iOS: NshAppView, before loading.
app.cacheOptions = NshCacheOptions(location: .directory(caches.appendingPathComponent("nsh")),
                                   images: .maxSize(megabytes: 64))   // .off: none
```

```java
// Android: NshView, before loading.
nsh.setCacheOptions(NshCacheOptions.builder()
        .location(new File(getCacheDir(), "nsh"))
        .imagesMaxMegabytes(64)          // imagesOff(): none
        .build());
```

`CacheLocation::Off` (`.off`, `noDiskCache()`) keeps nothing on disk.

By default the cache is in the system's cache directory: `Library/Caches/nsh` on iOS, `nsh` in the cache directory
on Android, `~/Library/Caches` on macOS, `%LOCALAPPDATA%` on Windows and `$XDG_CACHE_HOME` (`~/.cache`) on Linux,
each app in `<app id>/images` there. The system may clear these directories when it needs the space.

## Resize modes

The `objectFit` style, CSS's `object-fit` (`.object_fit(..)` in Rust), decides how an image fills a box of a different shape:

| Value | Result |
|---|---|
| `"cover"` (`ResizeMode::Cover`, default) | Fills the box, keeping the aspect ratio, cropping what overflows |
| `"contain"` (`ResizeMode::Contain`) | Fits inside the box, keeping the aspect ratio, leaving empty bands |
| `"fill"` (`ResizeMode::Stretch`) | Fills the box exactly, distorting the image |
| `"none"` (`ResizeMode::Center`) | Natural size, placed at `objectPosition` (centered by default) |
| `"scale-down"` (`ResizeMode::ScaleDown`) | Natural size, shrunk to fit where larger |

```rust
image(photo).object_fit(ResizeMode::Contain).size(px(140.0)).bg(rgb(0xeaeef2))
```

```tsx
<Image src={photo} style={{ width: 140, height: 140, objectFit: "contain", backgroundColor: "#eaeef2" }} />
```

The Tailwind classes `object-cover`, `object-contain`, `object-fill`, `object-none` and `object-scale-down` set the same style.

### Image position

Where the sized image sits in its box is the `objectPosition` style (`.object_position(..)` and `.object_top()`, ... in Rust), CSS's `object-position`: the center by default. A covering image is cropped around it, a contained one moves within its bands. It takes keywords (`"top"`, `"left bottom"`), percentages and lengths (`"25% 75%"`, `"10px 0"`) and edges with offsets (`"right 10px bottom 20%"`). A tall photo in a chat bubble shows its top this way:

```rust
image(photo).object_fit(ResizeMode::Cover).object_top().w(px(220.0)).h(px(160.0)).rounded(px(16.0))
```

```tsx
<Image src={photo} style={{ width: 220, height: 160, borderRadius: 16, objectPosition: "top" }} />
```

The Tailwind classes are Tailwind's: `object-top`, `object-bottom`, `object-left`, `object-right`, `object-center`, `object-top-left`, `object-top-right`, `object-bottom-left`, `object-bottom-right` and arbitrary values (`object-[25%_75%]`).

## Styling images

Images are views: they take corner radii (also per corner), borders, shadows, opacity and transforms. Corners clip the image.

```rust
image(avatar).size(px(90.0)).rounded(px(45.0)).border(px(3.0)).border_color(rgb(0x8250df))
```

```tsx
<Image src={avatar} style={{ width: 90, height: 90, borderRadius: 45, borderWidth: 3, borderColor: "#8250df" }} />
```

- **Tint** (`.tint_color(..)` in Rust, the `tintColor` style in TSX) recolors the image's opaque pixels: use it for one-color icons that follow the theme.
- **Filters** (`.grayscale(..)`, `.sepia(..)`, `.blur(..)`; `filter` in TSX) apply to images on both platforms ([Filters](https://nsh.dev/versions/main/docs/styling.md#filters-and-blending)).

```rust
image(ICON).size(px(24.0)).tint_color(AdaptiveColor::rgb(0x0969da, 0x58a6ff))
```

```tsx
<Image src={icon} style={{ width: 24, height: 24, tintColor: active() ? "#0969da" : "#6e7781" }} />
```

## Placeholders, fading and blur

| Prop | Rust | Description |
|---|---|---|
| `placeholder` | `.placeholder(..)` | An image shown until `src` has loaded, a URL or an asset; best a local asset |
| `fadeDuration` | `.fade_duration(ms)` | Milliseconds the loaded image fades in over. Default 0 on iOS, 300 on Android |
| `blurRadius` | `.blur_radius(px(..))` | Blurs the image by this radius in points, applied once when decoding |

```rust
image(move || format!("https://picsum.photos/seed/{}/300/300", id.get()))
    .placeholder(PLACEHOLDER)
    .fade_duration(250.0)
    .size(px(100.0))
    .rounded(px(12.0))
image(cover).blur_radius(px(16.0)).absolute().inset_0()
```

```tsx
<Image
  src={`https://picsum.photos/seed/${id()}/300/300`}
  placeholder={placeholder}
  fadeDuration={250}
  style={{ width: 100, height: 100, borderRadius: 12 }}
/>
<Image src={cover} blurRadius={16} style={{ position: "absolute", top: 0, right: 0, bottom: 0, left: 0 }} />
```

## Animated images

Animated GIF, WebP and APNG files play automatically, as assets or from URLs. They take the same styles, `objectFit` included; a tinted animated image shows its first frame on iOS.

## Load events

| Event | Rust | Payload | When |
|---|---|---|---|
| `onLoadStart` | `.on_load_start(..)` | | Loading starts |
| `onProgress` | `.on_progress(..)` | `{ loaded, total }` in bytes (`total` 0 when unknown) | During a download, at most every 100 ms |
| `onLoad` | `.on_load(..)` | `{ size }` | The image is ready; the source's size in pixels (an SVG's in points, [on the web as the browser measures it](#svg-images)) |
| `onError` | `.on_error(..)` | `{ message }` (a `&str` in Rust) | Loading or decoding failed |
| `onLoadEnd` | `.on_load_end(..)` | | After `onLoad` or `onError` |

```rust
let status = signal(SharedString::from("loading…"));

image(url)
    .on_load(move |size: &Size<DevicePixels>| status.set(format!("{}×{}", size.width.0, size.height.0).into()))
    .on_error(move |message: &str| status.set(message.to_owned().into()))
    .w(px(90.0))
    .h(px(60.0))
```

```tsx
const status = signal("loading…");

<Image
  src={url}
  onLoad={({ size }) => status.set(`${size.width}×${size.height}`)}
  onError={(e) => status.set(e.message)}
  style={{ width: 90, height: 60 }}
/>
```

The load event reports the source image's size, not the size it was decoded at.

An image with [pixel-density variants](#pixel-densities) loads one of its files, and the load event reports that file's pixels: 192×192 for `logo@3x.png` on a 3× screen, where `Image.getSize(logo)` resolves with the imported file's 64×64. When the pixel ratio changes and the image loads another variant, that load reports its events too: `onLoadStart`, then `onLoad` with the new file's size (or `onError`), then `onLoadEnd`.

## An image's size and prefetching

Images that are not on screen can be measured and loaded ahead: `image_size(..)` and `prefetch_image(..)` in Rust, `Image.getSize` and `Image.prefetch` (on the same `Image` that renders the element) in TSX:

```rust
spawn(async move {
    // Ok(ImageSize { width, height }), in pixels.
    let size = image_size("https://example.com/photo.jpg").await;
    // Ok(()) once the bytes are in memory.
    let loaded = prefetch_image("https://example.com/next.jpg").await;
});
```

```tsx
import { Image } from "nsh";

const size = await Image.getSize("https://example.com/photo.jpg");   // { width, height } in pixels
await Image.prefetch("https://example.com/next.jpg");                // once the bytes are in memory
```

| Rust | TSX | Returns |
|---|---|---|
| `image_size(src)` | `Image.getSize(src)` | The image's size in pixels (an SVG's in points, [on the web as the browser measures it](#svg-images)); an error when it cannot be loaded |
| `prefetch_image(src)` | `Image.prefetch(src)` | Nothing, once the image's bytes are loaded; an error when it cannot be loaded |

In TSX, `src` is a URL string or an imported image. For an imported image with [variants](#pixel-densities), both load the variant the views load on this screen, and `getSize` gives the imported file's size. Both keep the downloaded bytes for the views that show the image next, so an image prefetched before it is shown appears without a download.

A common use is sizing a remote image by its aspect ratio:

```rust
fn remote_image(url: &'static str) -> impl IntoElement {
    let ratio = signal(1.0_f32);
    spawn(async move {
        if let Ok(size) = image_size(url).await {
            ratio.set(size.width.0 as f32 / size.height.0 as f32);
        }
    });
    image(url).w_full().aspect_ratio(ratio)
}
```

```tsx
function RemoteImage(props: { url: string }) {
  const ratio = signal(1);
  Image.getSize(props.url).then((s) => ratio.set(s.width / s.height));
  return <Image src={props.url} style={{ width: "100%", aspectRatio: ratio() }} />;
}
```

## Other assets

| File | Rust (`asset!`) | TSX import | Page |
|---|---|---|---|
| `.ttf`, `.otf`, `.woff`, `.woff2` | A `FontAsset` with its family name | The font's family name | [Fonts](https://nsh.dev/versions/main/docs/fonts.md) |
| `.json` and other files | A `FileAsset` with its URI | `.json`: the parsed value, bundled into the script | [Project structure](https://nsh.dev/versions/main/docs/project-structure.md#modules) |

Fonts are registered before the first frame in both.

### Reading a file at run time

`fetch` reads a file the app ships by its `asset:/` URL, in TSX and in Rust alike, on every platform. An imported image carries its URL (`url`), a Rust crate's files have theirs from `asset!` (`FileAsset::uri`) and `assets!()`:

```rust
const GREETING: FileAsset = asset!("locales/en.txt");

#[component]
fn Greeting() -> impl IntoElement {
    let greeting = signal(String::new());
    spawn(async move {
        match fetch(GREETING.uri).await {
            Ok(response) => greeting.set(response.text()),
            Err(error) => greeting.set(error),
        }
    });
    text(move || greeting.get())
}
```

```tsx
import flag from "./images/flag.png";

const bytes = await (await fetch(flag.url)).bytes();
```

The engine reads the file from the app's files off its thread (from the dev server during `nsh run`), with no capability needed: they are the app's own. A web app downloads what the page did not preload from where it serves its assets. The response is `200` with the file's bytes, its `Content-Length` and the `Content-Type` its extension gives (`image/png`, `application/json`, ...), and its `url` is the `asset:/` URL however the file arrived; a file the app does not ship rejects as a network error that names it. The URL names the file by its path inside the app's files, and the request reads it with `GET` (or `HEAD`): a URL whose path leaves them (`..`, an absolute path) and a request with another method reject the same way, before anything is read or downloaded.

### A module's own URL

In TSX, `import.meta.url` is the URL of the module it is written in, so `new URL("./data.json", import.meta.url)` names a file beside it. A local or packaged desktop app's modules have `file:` URLs in the app's directory, which `fs/promises` reads under a `${pluginDir}` grant; a web app's are the page's; a packaged mobile app's are `asset:/` URLs like those of imported images. Import an image to ship it: a URL made this way names the file, it does not package it.

Bitmap images are also drawn on a canvas with `draw_image` / `drawImage` ([Canvas](https://nsh.dev/versions/main/docs/canvas.md)), and gradients replace many decorative images ([Styling](https://nsh.dev/versions/main/docs/styling.md#gradients)).

## Related

- [image element](https://nsh.dev/versions/main/elements/image.md): every prop, with `getSize` and `prefetch`.
- [Lists](https://nsh.dev/versions/main/docs/lists.md): long lists of images recycle their views.

Source: https://nsh.dev/versions/main/docs/images-and-assets

---

# Fonts

Text uses the system font (San Francisco on iOS, Roboto on Android) unless a font family says otherwise (`.font_family(..)` in Rust, `fontFamily` in TSX). A family can be a generic family, a font installed on the device, or a font file you ship with the app.

## System and generic families

| `fontFamily` | Font |
|---|---|
| (none), `"system-ui"`, `"sans-serif"`, `"ui-sans-serif"`, `"-apple-system"` | The system font |
| `"serif"`, `"ui-serif"` | The system serif (New York on iOS, Noto Serif on Android) |
| `"monospace"`, `"ui-monospace"` | The system monospace font (SF Mono on iOS) |
| `"ui-rounded"` | The rounded system font (SF Pro Rounded), iOS only |

The system font honors every weight from 100 to 900. Tailwind's `font-sans`, `font-serif` and `font-mono` map to the first three rows, and `font-sans` and `font-mono` to the theme's fonts when it sets them ([A default font for the app](#a-default-font-for-the-app)).

A family installed on the device can be named directly (`"Georgia"`, `"Avenir Next"` on iOS). Installed fonts differ between platforms and versions, so ship the fonts your design depends on. On iOS, a family that does not exist falls back to the system font with a warning in the log (`font family 'X' is not available`); name a list to choose what comes instead ([Fallback lists](#fallback-lists)).

## Shipping a font

A Rust crate ships the files of its `assets/` directory: `registry.assets(assets!())` in its `#[native_module]` function ships them all, and `asset!("fonts/Pacifico-Regular.ttf")` is a `FontAsset` whose `family` is the font's family name, read from the file when the crate compiles. In TSX, import a `.ttf`, `.otf`, `.woff` or `.woff2` file: the import evaluates to the font's family name. Either way the font is registered before the first frame, so it is ready when text first renders. WOFF and WOFF2 files are compressed TrueType or OpenType fonts (a WOFF2 file is often half its TrueType's size, which the app's package and the web's downloads save): NSH reads them as the fonts they hold, on every platform:

```rust
use nsh_core::{element::FontAsset, prelude::*};

const PACIFICO: FontAsset = asset!("fonts/Pacifico-Regular.ttf");

#[native_module("app/native")]
fn native(registry: &mut Registry) {
    registry.assets(assets!());
}

text("Custom fonts").font_family(PACIFICO.family).text_size(px(30.0))
```

```tsx
import { Text } from "nsh";
import Pacifico from "./fonts/Pacifico-Regular.ttf";

<Text style={{ fontFamily: Pacifico, fontSize: 30 }}>Custom fonts</Text>
```

`PACIFICO.family` and the TSX import `Pacifico` are the string `"Pacifico"`: the family name stored in the font file (its typographic family name, or else its family name), not the file name. Using the asset's value instead of writing the name by hand keeps the two in sync; a missing or broken file fails the Rust build, and an imported file is sure to be bundled.

The files ship with the app like any other [asset](https://nsh.dev/versions/main/docs/images-and-assets.md). Fonts are registered for the app's process only; they are not installed on the device.

> [!WARNING]
> In TSX, an import whose value is never used is removed by TypeScript's import elision, and with it the font. If you only refer to a family by its name (for example in the Tailwind theme), import the file for its side effect: `import "./fonts/Inter-Bold.ttf";`. A Rust crate ships every file of `assets/` through `assets!()`.

## Fallback lists

`fontFamily` takes a list, as CSS does: families separated by commas, most preferred first, a name with spaces quoted or not (`"Brand, 'Noto Sans SC', sans-serif"`), a quoted name keeping its commas (`'ACME, Inc'`). Text is set in the first family the platform has, and a character that family lacks (another script, a symbol) comes from the next family in the list that has it, then from the system's fallback fonts. A list lets a brand font that covers Latin only show Chinese in a matching font, or name a font the app downloads with a system font to show until it arrives:

```rust
text("Brand 品牌").font_family("Brand, 'Noto Sans SC', sans-serif")
```

```tsx
<Text style={{ fontFamily: "Brand, 'Noto Sans SC', sans-serif" }}>Brand 品牌</Text>
```

Each platform keeps the list's order with its own font machinery: a cascade list on iOS and macOS, a font fallback on Windows (one per paragraph: its first style's list), a Pango family list on Linux, the browser's on the web, GPUI's fallbacks. On Android, text is set in the first family it has; when that one is a font the app registers, the registered fonts after it in the list are its fallbacks (Android 10 and later).

## Weights and italics

A family usually comes as several files, one per weight and style. Ship each one (put them in `assets/` in Rust, import each in TSX); they register under the same family name, and the weight and style choose the face:

```rust
// assets/fonts: Inter-Regular.ttf, Inter-Medium.ttf, Inter-Bold.ttf, Inter-Italic.ttf
const INTER: FontAsset = asset!("fonts/Inter-Regular.ttf");

text("Regular, ")
    .font_family(INTER.family)
    .text_size(px(16.0))
    .child(text("medium").font_weight(FontWeight::MEDIUM))
    .child(", ")
    .child(text("bold").font_weight(FontWeight::BOLD))
    .child(" and ")
    .child(text("italic").italic())
    .child(".")
```

```tsx
import { Text } from "nsh";
import Inter from "./fonts/Inter-Regular.ttf";
import "./fonts/Inter-Medium.ttf";
import "./fonts/Inter-Bold.ttf";
import "./fonts/Inter-Italic.ttf";

const body = { fontFamily: Inter, fontSize: 16 } as const;

<Text style={body}>
  Regular, <Text style={{ fontWeight: "500" }}>medium</Text>, <Text style={{ fontWeight: "bold" }}>bold</Text> and{" "}
  <Text style={{ fontStyle: "italic" }}>italic</Text>.
</Text>
```

When no registered face has the exact weight asked for, the nearest one is used. The platforms differ when a face is missing:

| | iOS | Android |
|---|---|---|
| Weight without a face | The nearest registered face | The nearest face, with Android's synthetic bold where it applies |
| Italic without an italic face | The upright face (no slanting) | A slanted version of the upright face |

Ship the faces you use to get the same result on both.

## Fonts in typed styles and Tailwind classes

In Rust, `.font_family(..)` takes the asset's family wherever a style goes, and the weight methods (`.font_weight(FontWeight::SEMIBOLD)`) select faces. For classes, name your families in the Tailwind theme in `nsh.json` to use them as `font-*` classes:

```json
{
  "tailwind": {
    "fontFamily": { "display": "Pacifico", "body": "Inter" }
  }
}
```

```rust
use nsh_core::element::palette::VIOLET;

text("Custom fonts").font_family(PACIFICO.family).text_3xl().text_color(VIOLET.shade(600))
text("Bold Inter").font_family(INTER.family).font_weight(FontWeight::BOLD)
```

```tsx
import { Text } from "nsh";
import "./fonts/Pacifico-Regular.ttf";
import "./fonts/Inter-Regular.ttf";
import "./fonts/Inter-Bold.ttf";

<Text class="font-display text-3xl text-violet-600">Custom fonts</Text>
<Text class="font-body font-bold">Bold Inter</Text>
```

An arbitrary family works without a theme entry: `font-[Pacifico]`. Weight classes (`font-light`, `font-semibold`, `font-bold`, ...) select faces as `fontWeight` does. Text styles on a view pass down to the texts inside it, so `.font_family(INTER.family)` on a view, or `<View class="font-body">`, sets the family for a whole screen.

## A default font for the app

The theme's `font-sans` is the app's font: every text that sets no family of its own is drawn with it, in Rust components and TSX alike, as a web page is with Tailwind's `--font-sans`. `font-mono` is the monospaced font, of the `font-mono` class and of code in `TextView`. Set them in the app's theme (`"theme"` in `nsh.json`, [Rust](https://nsh.dev/versions/main/docs/rust.md#theme)) and ship the font files as above:

```json
{
  "cssVars": {
    "theme": {
      "font-sans": "Inter, sans-serif",
      "font-mono": "JetBrains Mono, monospace"
    }
  }
}
```

The first family of the list that is not a generic one is the font; a generic first family (`system-ui`, `sans-serif`) is the system font. The font can also be set on a container: the texts inside inherit it.

```rust
#[component]
pub fn Root() -> impl IntoElement {
    view().flex_1().font_family(INTER.family).child(app())
}
```

```tsx
mount(() => (
  <View class="flex-1 font-body">
    <App />
  </View>
));
```

## Font features

`fontVariant` turns on OpenType features of the font: `"tabular-nums"`, `"proportional-nums"`, `"lining-nums"`, `"oldstyle-nums"` and `"small-caps"` (`.tabular_nums()`, `.small_caps()`, ... in Rust; [Text](https://nsh.dev/versions/main/docs/text.md#text-styles)). The font has to contain them; system fonts do.

## Related

- [Text](https://nsh.dev/versions/main/docs/text.md): text styles, sizes and the system text size setting.
- [Tailwind](https://nsh.dev/versions/main/docs/tailwind.md#theme): the theme keys.
- [Images and assets](https://nsh.dev/versions/main/docs/images-and-assets.md): how the app's files are shipped.

Source: https://nsh.dev/versions/main/docs/fonts

---

# Touch and gestures

NSH has three levels of touch handling. **Presses** (`.on_press` in Rust, `onPress` in TSX, and their siblings) cover buttons, rows and links, with press feedback drawn natively. **Native gestures** (pan, pinch and rotation) move [animated values](https://nsh.dev/versions/main/docs/animation.md#animated-values) on the UI thread, so a dragged card follows the finger even while your code is busy. **Raw touches and the responder system** (`.on_touch` and `.claim_touches` with the `.on_responder_*` handlers in Rust; `onTouchStart`, `onResponderMove` and `PanResponder` in TSX) give your code every finger position for anything the other two cannot express, such as drawing.

Pick the highest level that does the job: the higher the level, the less work crosses from the UI thread to your code.

## Presses

Every element accepts the press handlers; there is no separate "touchable" component. Put `.on_press` / `onPress` on a view, a text, an image or anything else.

```rust
use nsh_core::prelude::*;

#[component]
fn App() -> impl IntoElement {
    let count = signal(0_u32);
    view().flex_1().items_center().justify_center().child(
        view()
            .on_press(move || count.update(|n| *n += 1))
            .on_long_press(move || count.set(0))
            .active(|s| s.opacity(0.6))
            .role(AccessibilityRole::Button)
            .px(px(20.0))
            .py(px(12.0))
            .rounded(px(10.0))
            .bg(rgb(0x0969da))
            .child(
                text(move || format!("Pressed {} times", count.get()))
                    .text_color(white())
                    .font_weight(FontWeight::SEMIBOLD),
            ),
    )
}
```

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

function App() {
  const count = signal(0);
  return (
    <View style={{ flex: 1, alignItems: "center", justifyContent: "center" }}>
      <View
        onPress={() => count.update((n) => n + 1)}
        onLongPress={() => count.set(0)}
        activeStyle={{ opacity: 0.6 }}
        role="button"
        style={{ paddingHorizontal: 20, paddingVertical: 12, borderRadius: 10, backgroundColor: "#0969da" }}
      >
        <Text style={{ color: "#ffffff", fontWeight: "600" }}>Pressed {count()} times</Text>
      </View>
    </View>
  );
}

mount(App);
```

| Rust | TSX | Default | Description |
|---|---|---|---|
| `.on_press(..)` | `onPress` | | The finger lifted inside the view (after a press, not a long press). |
| `.on_long_press(..)` | `onLongPress` | | The finger stayed down for the long press delay. The press handler does not follow. |
| `.on_press_down(..)` | `onPressDown` | | The press started. |
| `.on_press_up(..)` | `onPressUp` | | The press ended: lifted, slid off, or taken over by a scroll view. |
| `.long_press_delay(ms)` | `delayLongPress` | `500` | Milliseconds before a press becomes a long press. |
| `.disabled(..)` | `disabled` | `false` | Takes no presses and shows no feedback; applies the disabled style; screen readers say it is disabled. |

How presses behave:

- **Only the innermost pressable view responds.** A pressable row containing a pressable button gets no press when the button is pressed.
- **Inside a scroll view, the press waits about 130 ms** before it starts (and shows feedback), so a drag that begins on a button scrolls instead of pressing it.
- **Sliding off cancels.** Moving the finger out of the view ends the press with the press-up handler and no press.
- **Disabling removes the press listeners** from what is mounted, so the view shows no feedback at all, and the disabled style applies (`.disabled_style(..)`, `class="disabled:opacity-40"`).
- **Nested text spans with a press handler are links.** The paragraph is one native view; the press goes to the span under the finger. See [Text](https://nsh.dev/versions/main/docs/text.md).

## Press feedback

Press feedback is the app's: styles the view takes while it is pressed, hovered, focused or disabled. They are applied natively the moment the state changes, with no round trip to your code. Each state has a Rust method, a TSX style prop and a [Tailwind variant](https://nsh.dev/versions/main/docs/tailwind.md):

| Rust | TSX prop | Class | Description |
|---|---|---|---|
| `.active(\|s\| ..)` | `activeStyle` | `active:` | While pressed. |
| `.hover(\|s\| ..)` | `hoverStyle` | `hover:` | While a pointer is over it (desktops, iPad pointers, browsers). |
| `.focus(\|s\| ..)` | `focusStyle` | `focus:` | While it has focus. |
| `.focus_within(\|s\| ..)` | `focusWithinStyle` | `focus-within:` | While it or a view inside it has focus: a field's frame around the input that edits. |
| `.disabled_style(\|s\| ..)` | `disabledStyle` | `disabled:` | While disabled. |
| `.ripple(Ripple { .. })` | `android={{ ripple }}` | | Android's material ripple (`color`, `borderless`, `radius`, `foreground`), in addition to the styles. |

The state styles go over the view's own styles. Later states win (hover, focus, active), the disabled style wins over all, and the others do not apply while the view is disabled.

```rust
use nsh_core::{Ripple, prelude::*};

view().on_press(open).active(|s| s.opacity(0.5))

view().on_press(open).active(|s| s.bg(rgb(0xddf4ff))).p(px(16.0))

view()
    .on_press(open)
    .active(|s| s.opacity(0.6))
    .ripple(Ripple {
        color: Some(rgba(0x0969da4d).into()),
        ..Ripple::default()
    })
```

```tsx
<View onPress={open} activeStyle={{ opacity: 0.5 }}>…</View>

<View onPress={open} activeStyle={{ backgroundColor: "#ddf4ff" }} style={{ padding: 16 }}>…</View>

<View
  onPress={open}
  activeStyle={{ opacity: 0.6 }}
  android={{ ripple: { color: "rgba(9,105,218,0.3)" } }}
>
  …
</View>
```

A borderless ripple spreads outside the view, which suits icon buttons: `Ripple { borderless: true, radius: Some(px(24.0)), .. }`, `android={{ ripple: { borderless: true, radius: 24 } }}`. See [Platform-specific code](https://nsh.dev/versions/main/docs/platform-specific.md).

With a transition (`.transition()`, the `transition` class) the change of state animates. `.group()` (the `group` class) makes a view a group, and `.group_active(..)` (`group-active:`) styles its children while it is pressed:

```rust
view()
    .on_press(save)
    .group()
    .rounded_xl()
    .bg(rgb(0x059669))
    .p_4()
    .transition()
    .active(|s| s.scale(0.95).bg(rgb(0x065f46)))
    .child(
        text("Save")
            .font_weight(FontWeight::SEMIBOLD)
            .text_color(white())
            .group_active(|s| s.opacity(0.85)),
    )
```

```tsx
<View
  onPress={save}
  class="group rounded-xl bg-emerald-600 p-4 transition active:scale-95 active:bg-emerald-800"
>
  <Text class="font-semibold text-white group-active:opacity-85">Save</Text>
</View>
```

## Hit areas: hitSlop

The hit slop (`.hit_slop(..)`, `hitSlop`) extends the area that takes touches beyond the view's bounds, without changing its layout. Use it for small targets such as close buttons and toggles.

```rust
view().hit_slop(EdgeInsets::all(px(12.0))).on_press(close).size(px(20.0))

view()
    .hit_slop(EdgeInsets { top: px(10.0), bottom: px(10.0), left: px(4.0), right: px(4.0) })
    .on_press(next)
```

```tsx
<View hitSlop={12} onPress={close} style={{ width: 20, height: 20 }}>…</View>
<View hitSlop={{ top: 10, bottom: 10, left: 4, right: 4 }} onPress={next}>…</View>
```

| Rust | TSX | Description |
|---|---|---|
| `.hit_slop(EdgeInsets)` | `hitSlop: number \| { top?, right?, bottom?, left? }` | Points added around the bounds. `EdgeInsets::all(..)` and a TSX number apply to all four sides. |

Keep the extended area inside the parent's bounds (give the small view some margin or padding around it): hit testing reaches a child through its parent, so a touch outside the parent never gets to the child's slop.

## Children outside their parent

A child placed outside its parent's bounds (absolutely positioned with `overflow` left visible, such as a dropdown under its field) takes touches where it is drawn, like any other view: NSH hit-tests the descendants that reach outside a view natively. A parent that clips its overflow clips them, and then they neither show nor take touches there. The area is computed from the layout, so a child moved out of its parent by a transform only takes touches inside the parent's bounds.

Mind the drawing order: a dropdown is drawn over the siblings of its field only if the field comes after them or has a higher `z-index`, and touches go to what is drawn on top.

## pointerEvents

The style key `pointerEvents` (`.pointer_events(..)` in Rust) decides which views of a subtree can be the target of a touch. It is evaluated natively during hit testing, so it costs nothing per touch.

| Rust | TSX | The view | Its children |
|---|---|---|---|
| `PointerEvents::Auto` (default) | `"auto"` | Takes touches | Take touches |
| `PointerEvents::None` | `"none"` | Never the target | Never the target unless one sets `"auto"`: touches pass through to what is behind |
| `PointerEvents::BoxNone` | `"box-none"` | Never the target | Take touches |
| `PointerEvents::BoxOnly` | `"box-only"` | Takes touches | Never the target |

The typical uses: an overlay that must not block what is under it (none), a full-screen container whose empty space should let touches through to the content behind while its buttons still work (box-none), and a row that should take a press even when the finger lands on a child (box-only).

```rust
view().flex_1().child(map()).child(
    // A floating toolbar: the empty area passes touches to the map.
    view()
        .pointer_events(PointerEvents::BoxNone)
        .absolute()
        .inset_0()
        .justify_end()
        .p(px(16.0))
        .child(
            view()
                .on_press(locate)
                .self_end()
                .p(px(12.0))
                .rounded(px(24.0))
                .bg(white())
                .child(text("Locate")),
        ),
)
```

```tsx
<View style={{ flex: 1 }}>
  <Map />
  {/* A floating toolbar: the empty area passes touches to the map. */}
  <View style={{ pointerEvents: "box-none", position: "absolute", top: 0, left: 0, right: 0, bottom: 0, justifyContent: "flex-end", padding: 16 }}>
    <View onPress={locate} style={{ alignSelf: "flex-end", padding: 12, borderRadius: 24, backgroundColor: "#ffffff" }}>
      <Text>Locate</Text>
    </View>
  </View>
</View>
```

`"none"` is inherited as CSS's `pointer-events`: a view inside it that sets `"auto"` takes touches again. `"box-none"` and `"box-only"` apply to the view that sets them. The Tailwind classes `pointer-events-none` and `pointer-events-auto` set `"none"` and `"auto"`, and as a style key `pointerEvents` also takes state styles (`activeStyle`, ...) and variants.

## Native gestures: pan, pinch and rotation

For drags, pinches and rotations that move something on screen, bind [animated values](https://nsh.dev/versions/main/docs/animation.md#animated-values) to the gesture. The platform's gesture recognizer writes the values on the UI thread and the views bound to them move in the same frame; your code is told when the gesture starts and ends.

```rust
use nsh_core::prelude::*;

#[component]
fn App() -> impl IntoElement {
    let x = animated_value(0.0);
    let y = animated_value(0.0);
    view().flex_1().items_center().justify_center().child(
        view()
            .pan_values(Some(&x), Some(&y))
            .on_pan_end(move |e: &PanEvent| {
                // Spring back, starting at the speed the finger let go with.
                let spring = |velocity| Spring { velocity: Some(velocity), ..Spring::default() };
                x.spring(0.0, spring(e.velocity_x));
                y.spring(0.0, spring(e.velocity_y));
            })
            .size(px(120.0))
            .rounded(px(24.0))
            .bg(rgb(0x8250df))
            .bind_translate_x(&x)
            .bind_translate_y(&y),
    )
}
```

```tsx
import { mount, View } from "nsh";
import { createAnimatedValue } from "nsh";

function App() {
  const x = createAnimatedValue(0);
  const y = createAnimatedValue(0);
  return (
    <View style={{ flex: 1, alignItems: "center", justifyContent: "center" }}>
      <View
        pan={{ x, y }}
        onPanEnd={(e) => {
          // Spring back, starting at the speed the finger let go with.
          x.spring(0, { velocity: e.velocity.x });
          y.spring(0, { velocity: e.velocity.y });
        }}
        style={{ width: 120, height: 120, borderRadius: 24, backgroundColor: "#8250df", translate: [x, y] }}
      />
    </View>
  );
}

mount(App);
```

| Rust | TSX | Description |
|---|---|---|
| `.pan_values(Some(&x), Some(&y))` | `pan={{ x?, y? }}` | One-finger drags move these values, in points. |
| `.pinch_value(&scale)` | `pinch={{ scale? }}` | Two-finger pinches drive `scale` (a factor). |
| `.rotation_value(&angle)` | `rotation={{ angle? }}` | Two-finger rotations drive `angle`, in degrees. |
| `.on_pan_start` / `.on_pan_end` | `onPanStart` / `onPanEnd` | The drag started / ended, with a `PanEvent`. |
| `.on_pinch_start` / `.on_pinch_end` | `onPinchStart` / `onPinchEnd` | The pinch started / ended: its scale and velocity (`GestureEvent`). |
| `.on_rotation_start` / `.on_rotation_end` | `onRotationStart` / `onRotationEnd` | The rotation started / ended: its angle (Rust: `GestureEvent<Radians>`) and velocity. |

A pan event has the translation (`translation`, a `Point`: points since the start), the velocity (`velocity_x` / `velocity_y`; TSX: `velocity`, a `Point`: points per **second**) and the bound values at that moment (`value_x` / `value_y`; TSX: `value`, `{ x?, y? }` with the axes `pan` binds).

What the native side does for you:

- **A drag continues from where the value is.** At the start the values are read, and the translation is added to them; grabbing a value that is still animating (a spring on its way home) stops the animation where it is.
- **One axis only lets the other scroll.** With only a horizontal value bound the drag begins only when the finger moves more horizontally than vertically, so a horizontal swipe row inside a vertical scroll view still scrolls vertically. This decision is made natively when the system asks whether the gesture may begin.
- **Pan, pinch and rotation run together** on the same view: one card can be dragged, pinched and rotated at once.
- **Release velocity for physics.** The pan end's velocity feeds a spring's or a decay's velocity directly; the values let you pick a snap point.

```rust
// A card that snaps to the left or right edge.
view()
    .pan_values(Some(&x), None)
    .on_pan_end(move |e: &PanEvent| {
        let projected = e.value_x.unwrap_or(0.0) + e.velocity_x * 0.2;
        let to = if projected > 0.0 { 140.0 } else { -140.0 };
        x.spring(to, Spring { velocity: Some(e.velocity_x), ..Spring::default() });
    })
    .bind_translate_x(&x)
```

```tsx
// A card that snaps to the left or right edge.
<View
  pan={{ x }}
  onPanEnd={(e) => {
    const projected = (e.value?.x ?? 0) + e.velocity.x * 0.2;
    x.spring(projected > 0 ? 140 : -140, { velocity: e.velocity.x });
  }}
  style={{ translate: [x, 0] }}
/>
```

> [!TIP]
> Bind animated values to the gesture rather than following it through the responder whenever the drag only moves things. With bound values, busy app code cannot make the drag stutter; with the responder, every move is an event to your code and an update of what the view shows.

## Raw touches

The touch handlers report every finger as it goes down, moves and lifts. They are useful for logging, custom hit testing and reacting to multi-touch; they do not claim the touch (presses and scroll views keep working).

In Rust, `.on_touch(..)` hears every phase as a `TouchEvent`: its `phase` (`TouchPhase::Start`, `Move`, `End`, `Cancel`), its `timestamp` and its `points`, every finger that is down, each with its `id`, its `location` in the view it went down on, its `page` position in the surface, and `changed` for the fingers the event is about. In TSX, each phase has its own handler:

| TSX | Description |
|---|---|
| `onTouchStart` | A finger went down on the view or inside it. |
| `onTouchMove` | A finger moved. Moves are merged per engine turn. |
| `onTouchEnd` | A finger lifted. |
| `onTouchCancel` | The system took the touch (a scroll view started scrolling, a call came in). |
| `onTouchStartCapture`, `onTouchMoveCapture`, `onTouchEndCapture`, `onTouchCancelCapture` | The same, called from the outside in, before the bubbling handlers. |

Each TSX handler gets a `GestureResponderEvent`:

| Field | Description |
|---|---|
| `identifier` | Identifies the finger while it is down. |
| `locationX`, `locationY` | Position in the view the finger went down on (`target`). |
| `pageX`, `pageY` | Position in the surface. |
| `target` | The id of the view the finger went down on. |
| `timestamp` | Milliseconds. |
| `touches` | Every finger that is down. |
| `changedTouches` | The fingers this event is about. |
| `nativeEvent` | The event itself, so `e.nativeEvent.locationX` works too. |
| `stopPropagation()` | Views further out do not see this touch event. |

```rust
use nsh_core::{TouchPhase, element::{TouchEvent}, prelude::*};

view().on_touch(|e: &TouchEvent| {
    let Some(p) = e.points.iter().find(|p| p.changed) else { return };
    match e.phase {
        TouchPhase::Start => log::info!("down {:?} {}", p.location, e.points.len()),
        TouchPhase::Move => log::info!("move {:?}", p.page),
        TouchPhase::End | TouchPhase::Cancel => log::info!("up"),
    }
})
```

```tsx
<View
  onTouchStart={(e) => console.log("down", e.locationX, e.locationY, e.touches.length)}
  onTouchMove={(e) => console.log("move", e.pageX, e.pageY)}
  onTouchEnd={() => console.log("up")}
/>
```

### Where a view is: measure

A touch's location is relative to the view the finger went down on, which may be a child of the view you care about (a slider's knob). Measuring a view tells you where it is, so you can use the page position instead. In Rust, put an `element_ref()` on the view and await its `measure()`; in TSX, call `measure()` on its ref:

```rust
let track = element_ref();
let origin = stored(px(0.0));
view()
    .element_ref(&track)
    .claim_touches(TouchClaim::on_start())
    .on_responder_grant(move |e: &ResponderEvent| {
        let x = e.page.x;
        spawn(async move {
            let page = track.measure().await.map_or(px(0.0), |m| m.page.x);
            origin.replace(page);
            seek(x - page);
        });
    })
    .on_responder_move(move |e: &ResponderEvent| seek(e.page.x - origin.get()))
```

```tsx
let track!: ViewRef;
let origin = 0;
<View
  ref={track}
  onStartShouldSetResponder={() => true}
  onResponderGrant={async (e) => {
    const x = e.pageX;
    origin = (await track.measure())?.pagePosition.x ?? 0;
    seek(x - origin);
  }}
  onResponderMove={(e) => seek(e.pageX - origin)}
/>;
```

It resolves once the changes made so far are laid out: in Rust to a `Measurement` (`frame`, the frame in the parent as the layout handler reports it, and `page`, the top left corner), in TSX to `{ bounds, pagePosition }`. The corner is in the surface, or in the dialog the view is in, the same coordinates as touches' page positions. The offsets of the scroll views and lists around it are taken into account; transforms (animations included) are not. It resolves to `None` / `null` for a view that is not on screen.

## The responder system

When your code has to own a touch sequence (finger drawing, a custom slider, a gesture the native recognizers do not offer), use the gesture responder system. One view at a time is the **responder** and receives the moves; views negotiate who that is.

Becoming the responder:

| Rust | TSX | Description |
|---|---|---|
| `.claim_touches(TouchClaim::on_start())` | `onStartShouldSetResponder` returning `true` | Asked when a finger goes down, from the target outwards. |
| `.claim_touches(TouchClaim::on_move())` | `onMoveShouldSetResponder` returning `true` | Asked on every move while there is no responder (or to take it over). |
| `TouchClaim::on_start().capture()` | `onStartShouldSetResponderCapture` | As above, asked from the outside in, before the bubbling ones. A parent uses it to take a touch from its children. |
| `TouchClaim::on_move().capture()` | `onMoveShouldSetResponderCapture` | The move version. |

A claim decides from the view alone, with no code of yours running, unless it asks: `TouchClaim::on_move().ask(|r: &ClaimRequest| ..)` claims when the listener calls `r.claim()`, deciding with the gesture so far (`r.event.gesture`). The TSX handlers get the gesture as their second argument, `gestureState`, with the same fields as [PanResponder's](#panresponder) (`dx`, `dy`, `vx`, `vy`, `moveX`, `moveY`, `x0`, `y0`, `numberActiveTouches`). A swipe that claims only horizontal moves: `onMoveShouldSetResponder={(e, g) => Math.abs(g.dx) > 10 && Math.abs(g.dx) > Math.abs(g.dy)}`. That decision still comes a move late, so a scroll view around may start scrolling first; for drags inside scroll views use [pan activation](#pans-inside-scroll-views-panactivation).

While responding:

| Rust | TSX | Description |
|---|---|---|
| `.on_responder_grant(..)` | `onResponderGrant` | This view is now the responder. Rust keeps native scroll views from taking the touches by default (`TouchClaim::block_native(false)` lets them); in TSX, return `true` for that. |
| `.on_responder_reject(..)` | `onResponderReject` | Another view is the responder and would not let go. |
| `.on_responder_start(..)` | `onResponderStart` | Another finger went down. |
| `.on_responder_move(..)` | `onResponderMove` | A finger moved. |
| `.on_responder_end(..)` | `onResponderEnd` | A finger lifted. |
| `.on_responder_release(..)` | `onResponderRelease` | The last finger lifted: the gesture is over. |
| `.keep_touches(true)` | `onResponderTerminationRequest` returning `false` | Another view wants the touches: keep them (by default they are handed over). |
| `.on_responder_terminate(..)` | `onResponderTerminate` | Another view, or a native gesture, took the touches. |

A Rust component's responder stays pressed from its grant until its touches end, wherever the finger or pointer goes, as CSS's `:active` holds until the button is released: its `.active(..)` styles and the `group-active:` classes inside it keep their look for the whole drag (a resize handle dragged off its band).

The Rust handlers get a `ResponderEvent`: the finger's `location` in the view it went down on, its `page` position, the `timestamp` and the `gesture` since the grant.

```rust
use nsh_core::prelude::*;

fn sketch() -> impl IntoElement {
    let strokes = signal(Vec::<Vec<Point<Points>>>::new());
    canvas(move || {
        strokes.with(|all| {
            all.iter().fold(Painter::new().line_width(3.0), |p, s| {
                let mut p = p.begin_path();
                for (i, pt) in s.iter().enumerate() {
                    p = if i == 0 { p.move_to(pt.x, pt.y) } else { p.line_to(pt.x, pt.y) };
                }
                p.stroke()
            })
        })
    })
    .flex_1()
    // The responder: the scroll view around does not take the touches.
    .claim_touches(TouchClaim::on_start())
    .keep_touches(true)
    .on_responder_grant(move |e: &ResponderEvent| strokes.update(|all| all.push(vec![e.location])))
    .on_responder_move(move |e: &ResponderEvent| {
        strokes.update(|all| {
            if let Some(last) = all.last_mut() {
                last.push(e.location);
            }
        })
    })
}
```

```tsx
import { Canvas, type GestureResponderEvent, mount, signal } from "nsh";

function Sketch() {
  const strokes = signal<[number, number][][]>([]);
  const point = (e: GestureResponderEvent): [number, number] => [e.locationX, e.locationY];
  return (
    <Canvas
      style={{ flex: 1 }}
      onStartShouldSetResponder={() => true}
      onResponderGrant={(e) => {
        strokes.set([...strokes(), [point(e)]]);
        return true; // the scroll view around must not take the touches
      }}
      onResponderTerminationRequest={() => false}
      onResponderMove={(e) => {
        const all = strokes();
        strokes.set([...all.slice(0, -1), [...all[all.length - 1], point(e)]]);
      }}
      draw={(cx) => {
        cx.lineWidth = 3;
        for (const s of strokes()) {
          cx.beginPath();
          s.forEach(([x, y], i) => (i === 0 ? cx.moveTo(x, y) : cx.lineTo(x, y)));
          cx.stroke();
        }
      }}
    />
  );
}

mount(Sketch);
```

How it runs: a view with any touch or responder handler listens to touches natively; the platform reports the touches on it (and inside it) with the path of listening views, and the negotiation runs in NSH's Rust core, asking the claims and calling your handlers in order: the captures from the outermost view inwards, then the others from the target outwards. Two consequences:

- **Native scroll views and responders compete.** While a responder blocks them, the scroll views around it stop taking the touches until it ends. If a native scroll view starts dragging first, it wins: the responder gets the terminate handler and the touch handlers a cancel.
- **Each move is an event to your code.** Responder-driven drags are as smooth as your code is fast; for drags that only move views, prefer [bound values](#native-gestures-pan-pinch-and-rotation).

## PanResponder

In Rust, the responder events already carry the gesture: `ResponderEvent::gesture` is a `PanGesture` with the distance from the start, the velocity and the number of fingers. In TSX, `PanResponder` from `nsh` wraps the responder system and adds the same gesture state; spread its `panHandlers` on a view.

```rust
use nsh_core::prelude::*;

fn ball() -> impl IntoElement {
    let pos = signal((0.0_f32, 0.0_f32));
    let start = stored((0.0_f32, 0.0_f32));
    view()
        .size(px(60.0))
        .rounded(px(30.0))
        .bg(rgb(0x0969da))
        .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();
            let d = e.gesture.delta;
            pos.set((x + d.x.0, y + d.y.0));
        })
        .on_responder_release(move |e: &ResponderEvent| {
            log::info!("released at {} {} pt/s", e.gesture.vx, e.gesture.vy)
        })
}
```

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

function Ball() {
  const pos = signal({ x: 0, y: 0 });
  let start = { x: 0, y: 0 };
  const responder = 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, g.vy, "pt/s"),
  });
  return (
    <View
      {...responder.panHandlers}
      style={{ width: 60, height: 60, borderRadius: 30, backgroundColor: "#0969da", translate: [pos().x, pos().y] }}
    />
  );
}

mount(Ball);
```

The gesture state:

| Rust (`PanGesture`) | TSX (`gestureState`) | Description |
|---|---|---|
| | `stateID` | Identifies the gesture. |
| `position` | `moveX`, `moveY` | The latest position of the touches' centroid, in surface points. |
| `origin` | `x0`, `y0` | Where the centroid was when the responder was granted. |
| `delta` | `dx`, `dy` | Distance moved since the grant. |
| `vx`, `vy` | `vx`, `vy` | Velocity, in points per second. |
| `active_touches` | `numberActiveTouches` | Fingers down. |

`PanGesture::begin` and `PanGesture::update` follow a gesture from raw touches (`.on_touch`) in Rust. The TSX callbacks get `(event, gestureState)`: `onStartShouldSetPanResponder(Capture)`, `onMoveShouldSetPanResponder(Capture)`, `onPanResponderGrant`, `onPanResponderReject`, `onPanResponderStart`, `onPanResponderMove`, `onPanResponderEnd`, `onPanResponderRelease`, `onPanResponderTerminate`, `onPanResponderTerminationRequest` and `onShouldBlockNativeResponder`. The last one defaults to `true`: a granted PanResponder keeps native scroll views from taking its touches.

## Pans inside scroll views: panActivation

A chart scrubbed sideways inside a vertical scroll view has to take horizontal drags and leave vertical ones to the scroll view. Claiming the touch on start blocks scrolling from the first pixel, and deciding on the moves in your code is too late: by the time it answers, the scroll view may have taken the touch. Pan activation (`TouchClaim::on_pan(..)`, `panActivation`) lets the platform decide on the main thread, as the finger moves:

```rust
view()
    .claim_touches(TouchClaim::on_pan(PanActivation::horizontal(px(10.0), px(10.0))))
    .on_responder_grant(|e: &ResponderEvent| scrub(Some(e.location.x)))
    .on_responder_move(|e: &ResponderEvent| scrub(Some(e.location.x)))
    .on_responder_release(|_: &ResponderEvent| scrub(None))
    .child(chart())
```

```tsx
<View
  panActivation={{ activeOffsetX: 10, failOffsetY: 10 }}
  onResponderGrant={(e) => scrub(e.locationX)}
  onResponderMove={(e) => scrub(e.locationX)}
  onResponderRelease={() => scrub(null)}
>
  <Chart />
</View>
```

| Rust (`PanActivation`) | TSX | Description |
|---|---|---|
| `active_offset_x`, `active_offset_y` | `activeOffsetX`, `activeOffsetY` | The pan activates once the finger has moved further than this from where it went down, along that axis (either direction, points). |
| `fail_offset_x`, `fail_offset_y` | `failOffsetX`, `failOffsetY` | The pan fails once the finger has moved further than this first: the scroll views keep the touches. |

`PanActivation::horizontal(active, fail)` and `PanActivation::vertical(active, fail)` set the usual pairs. Without active offsets the pan activates after 10 points in any direction. Until it activates, the scroll views around wait for it (iOS) and the view's other claims are not asked. When it activates, the scroll views can no longer take these touches and the view becomes the responder (the grant, then the moves); when it fails, the scroll view scrolls as usual. In TSX, `PanResponder`'s `panHandlers` work with it too: spread them next to the prop, and `onPanResponderGrant` runs at the activation.

> [!NOTE]
> Every velocity is in points per second: the responder gesture's `vx` / `vy`, a pan's velocity and a spring's or a decay's, so `vx` goes to a spring or a decay as it is.

## Why some answers are props

The main thread never waits for your code. When the system needs an answer on the spot (may this pan gesture begin, does this point hit the view, should this tap dismiss the keyboard), NSH answers natively from what was mounted beforehand: the bound pan values (their axes), the pinch value, the hit slop, the pointer events, the keyboard taps setting of scroll views, the pan activation. Your handlers hear about what happened afterwards. That is why these are declarative settings rather than callbacks, and why the responder negotiation, which does run your code, only decides between responders and never blocks a native gesture.

## Related

- [`View`](https://nsh.dev/versions/main/elements/view.md): every touch prop on the basic element.
- [Animation](https://nsh.dev/versions/main/docs/animation.md): animated values, springs and decay for gesture-driven motion.
- [Scrolling](https://nsh.dev/versions/main/docs/scrolling.md): the keyboard taps setting, scroll views and nested gestures.
- [`PanResponder`](https://nsh.dev/versions/main/modules/nsh.md#panresponder): the `PanResponder` reference.
- [Accessibility](https://nsh.dev/versions/main/docs/accessibility.md): pressable views are accessibility elements; give them a role and a label.

## Terminal pointer input

The terminal host captures the mouse: hover applies the app's `hoverStyle` and `hover:` classes and reports
`onMouseEnter` / `onMouseMove` / `onMouseLeave`, primary-button drags drive native pans and responders, dragging
scroll content or a scroll bar's thumb moves its viewport, and the wheel scrolls the innermost scroll view under
the pointer (Shift scrolls sideways). Double and triple clicks carry their count in `Press` events, and a right
click reaches `onContextMenu`. Positions follow the Cell grid. Start the host with `--no-mouse` to leave the
mouse to the terminal emulator and its own text selection. Embedding applications choose when to forward mouse
events to their NSH surface.

Source: https://nsh.dev/versions/main/docs/touch-and-gestures

---

# Scrolling

The scroll view (`scroll()` in Rust, `<Scroll>` in TSX) is the platform's own scroll view (UIScrollView on iOS, a ScrollView on Android): flings, bounces, the scroll indicator and pull to refresh are native, and so is snapping. Your code hears about scrolling through events and can bind the offset to an [animated value](https://nsh.dev/versions/main/docs/animation.md#animated-values) for effects that follow the finger frame by frame.

Use a scroll view for content of a known, moderate size: a settings page, a form, an article, a row of chips. For long or unbounded data use a [list](https://nsh.dev/versions/main/docs/lists.md), which recycles rows and accepts the same scrolling props.

## A scroll view

A scroll view is the viewport; its children are the content. The viewport needs a size from its parent (usually `flex: 1`, `.flex_1()`), and the content is laid out at the viewport's width (vertical) or height (horizontal) and as long as it needs to be.

```rust
#[component]
pub fn App() -> impl IntoElement {
    scroll().flex_1().bg(rgb(0xf6f8fa)).child(
        view().p_4().gap_3().children((1..=50).map(|n| {
            view().p_4().rounded(px(10.0)).bg(white()).child(text(format!("Row {n}")))
        })),
    )
}
```

```tsx
import { mount, Scroll, Text, View } from "nsh";

function App() {
  return (
    <Scroll style={{ flex: 1, backgroundColor: "#f6f8fa" }}>
      <View style={{ padding: 16, gap: 12 }}>
        <Each of={Array.from({ length: 50 }, (_, i) => i + 1)}>
          {(n) => (
            <View style={{ padding: 16, borderRadius: 10, backgroundColor: "#ffffff" }}>
              <Text>Row {n()}</Text>
            </View>
          )}
        </Each>
      </View>
    </Scroll>
  );
}

mount(App);
```

The child view above is the scroll view's content container; in TSX, `contentStyle` (or `contentClass`) makes one for you, wrapping the children in a view with that style, which scrolls with them. `flexGrow: 1` (`.flex_grow(1.0)`) makes the content at least as tall as the viewport, so a short content can be centered and a long one still scrolls:

```rust
scroll().flex_1().child(
    view().flex_grow(1.0).justify_center().p_4().child(
        when(move || messages.with(|m| !m.is_empty()), move || {
            each(messages, |m| m.id, |m, _| text(move || m.with(|m| m.text.clone())))
        })
        .otherwise(|| text("No messages yet")),
    ),
)
```

```tsx
<Scroll style={{ flex: 1 }} contentStyle={{ flexGrow: 1, justifyContent: "center", padding: 16 }}>
  <If when={messages().length > 0} else={<Text>No messages yet</Text>}>
    <Each of={messages()}>{(m) => <Text>{m().text}</Text>}</Each>
  </If>
</Scroll>
```

A horizontal scroll view takes `horizontal` (`.horizontal()`) and a row as its child:

```rust
scroll().horizontal().scrollbar(false).child(
    view().flex_row().gap_2().px_4().children(["Today", "This week", "This month", "This year"].map(|label| {
        text(label).px(px(14.0)).py_2().rounded(px(16.0)).overflow_hidden().bg(white())
    })),
)
```

```tsx
<Scroll horizontal scrollbar={false}>
  <View style={{ flexDirection: "row", gap: 8, paddingHorizontal: 16 }}>
    <Each of={["Today", "This week", "This month", "This year"]}>
      {(label) => <Text style={{ paddingHorizontal: 14, paddingVertical: 8, borderRadius: 16, overflow: "hidden", backgroundColor: "#ffffff" }}>{label()}</Text>}
    </Each>
  </View>
</Scroll>
```

Right to left (see [Device and environment](https://nsh.dev/versions/main/docs/device-and-environment.md#right-to-left)), a horizontal scroll view starts at its right end and keeps its distance from it.

Fingers drag scroll views. On the desktop (macOS, Windows, Linux) and in the browser, the mouse scrolls as in desktop apps: with its wheel (Shift + wheel scrolls horizontally), the touchpad, the keyboard and the scroll indicator, which shows while the mouse moves over the view and drags as a scroll bar; mouse drags go to the app's pans, responders and text selection. Touchscreens on desktops drag scroll views as fingers do. Horizontal views keep their indicator there even with `scrollbar={false}`, since it is how a mouse without a horizontal wheel moves them.

### Behavior props

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `horizontal` | `.horizontal()` | `boolean` | `false` | Scrolls sideways. |
| `scrollable` | `.scrollable(..)` | `boolean` | `true` | The user can scroll it. Scrolling from code still works. |
| `bounces` | `.bounces(..)` | `boolean` | `true` | Overscroll past the edges. |
| `scrollbar` | `.scrollbar(..)` | `boolean` | `true` | The scroll indicator shows. On the desktop and in desktop browsers a horizontal view keeps it: it is the mouse's scroll bar. |
| `contentInset` | `.content_inset(EdgeInsets { .. })` | `Partial<Edges>` | | Room around the content, scrollable into. |
| `contentOffset` | `.content_offset(point(..))` | `{ x?, y? }` | | Where it starts. |
| `decelerationRate` | `.deceleration(rate)` | `"normal" \| "fast" \| number` | the platform's | How fast a fling slows down: `"normal"`, `"fast"`, or the velocity kept per millisecond (`0.998` is normal, `0.99` fast; `0` is the platform's default). |

## Paging and snapping

Snapping is decided natively when the finger lifts, from the release offset, the projected glide and the velocity; the scroll view then glides to the chosen stop, with none of your code involved.

| Prop | Rust | Type | Description |
|---|---|---|---|
| `pagingEnabled` | `.paging(true)` | `boolean` | Stops at multiples of the viewport's size. |
| `snapToInterval` | `.snap_interval(px(..))` | `number` | Stops at multiples of this length (0: off). |
| `snapToOffsets` | `.snap_offsets(vec![..])` | `number[]` | Stops at these offsets. |
| `snapToAlignment` | `.snap_alignment(SnapAlignment::Center)` | `"start" \| "center" \| "end"` | With `snapToInterval`: which point of an item aligns with the viewport. |
| `disableIntervalMomentum` | `.disable_interval_momentum(true)` | `boolean` | A fling moves one stop at most. |

A pager: pages as wide as the scroll view, and an indicator updated when the glide ends.

```rust
const COLORS: [u32; 4] = [0x0969da, 0x8250df, 0xbf3989, 0x1a7f37];

pub fn pager() -> impl IntoElement {
    let width = signal(0.0_f32);
    let page = signal(0_usize);
    let settle = move |e: &Point<Points>| {
        let width = width.get_untracked();
        if width > 0.0 {
            page.set((e.x.0 / width).round() as usize);
        }
    };
    let pages = COLORS.iter().enumerate().map(|(i, &color)| {
        view()
            .w(move || px(width.get()))
            .h(px(160.0))
            .bg(rgb(color))
            .items_center()
            .justify_center()
            .child(text(format!("Page {}", i + 1)).text_color(white()).text_2xl().font_weight(FontWeight::BOLD))
    });
    let dots = (0..COLORS.len()).map(|i| {
        view()
            .size_2()
            .rounded(px(4.0))
            .bg(move || if page.get() == i { rgb(0x0969da) } else { rgb(0xd0d7de) })
    });
    view()
        .gap_2()
        .p_4()
        .child(
            scroll()
                .horizontal()
                .paging(true)
                .scrollbar(false)
                .h(px(160.0))
                .rounded(px(12.0))
                .on_layout(move |frame: &Bounds<Points>| width.set(frame.size.width.0))
                .on_scroll_end(settle)
                .child(view().flex_row().children(pages)),
        )
        .child(view().flex_row().justify_center().gap(px(6.0)).children(dots))
}
```

```tsx
import { mount, type Point, Scroll, signal, Text, View } from "nsh";

const colors = ["#0969da", "#8250df", "#bf3989", "#1a7f37"];

function Pager() {
  const width = signal(0);
  const page = signal(0);
  const settle = ({ offset }: { offset: Point }) => page.set(Math.round(offset.x / width()));
  return (
    <View style={{ gap: 8, padding: 16 }}>
      <Scroll
        horizontal
        pagingEnabled
        scrollbar={false}
        style={{ height: 160, borderRadius: 12 }}
        onLayout={({ bounds }) => width.set(bounds.size.width)}
        onScrollEnd={settle}
      >
        <View style={{ flexDirection: "row" }}>
          <Each of={colors}>
            {(color, i) => (
              <View style={{ width: width(), height: 160, backgroundColor: color(), alignItems: "center", justifyContent: "center" }}>
                <Text style={{ color: "#ffffff", fontSize: 24, fontWeight: "700" }}>Page {i() + 1}</Text>
              </View>
            )}
          </Each>
        </View>
      </Scroll>
      <View style={{ flexDirection: "row", justifyContent: "center", gap: 6 }}>
        <Each of={colors}>
          {(_, i) => <View style={{ width: 8, height: 8, borderRadius: 4, backgroundColor: page() === i() ? "#0969da" : "#d0d7de" }} />}
        </Each>
      </View>
    </View>
  );
}

mount(Pager);
```

A carousel of cards that snap to the center, one card per fling:

```rust
scroll()
    .horizontal()
    .snap_interval(px(232.0))          // card width (220) + gap (12)
    .snap_alignment(SnapAlignment::Center)
    .deceleration(0.99)
    .disable_interval_momentum(true)
    .scrollbar(false)
    .child(view().flex_row().gap_3().px_4().children(cards))
```

```tsx
<Scroll
  horizontal
  snapToInterval={232}          // card width (220) + gap (12)
  snapToAlignment="center"
  decelerationRate="fast"
  disableIntervalMomentum
  scrollbar={false}
>
  <View style={{ flexDirection: "row", gap: 12, paddingHorizontal: 16 }}>…</View>
</Scroll>
```

Lists take the same snapping props, which makes them the better choice for a long carousel.

## Scroll events

| Prop | Rust | Payload | When |
|---|---|---|---|
| `onScroll` | `.on_scroll(..)` | `ScrollEvent` | The offset changed. At most once per frame; `scrollEventThrottle` spaces them further. |
| `scrollEventThrottle` | `.event_throttle(ms)` | `number` | Minimum milliseconds between `onScroll` events. |
| `onScrollDragStart` | `.on_scroll_drag_start(..)` | `{ offset }` | The user started dragging. |
| `onScrollDragEnd` | `.on_scroll_drag_end(..)` | `{ offset }` | The user lifted the finger. |
| `onMomentumStart` | `.on_momentum_start(..)` | `{ offset }` | The glide after a fling started. |
| `onMomentumEnd` | `.on_momentum_end(..)` | `{ offset }` | The glide ended (also when a new drag catches it). |
| `onScrollEnd` | `.on_scroll_end(..)` | `{ offset }` | A user scroll came to rest: after the glide, or at the end of a drag without one. |

`ScrollEvent` carries the offset (`offset`, a `Point`; the same in Rust), the content's size, zoomed (`contentSize`, a `Size`; `content_size`), the viewport (`size`) and `zoomScale` (`zoom_scale`). The other events carry the offset: `{ offset }` with a `Point` in TSX, a `Point<Points>` in Rust.

```rust
let at_bottom = signal(false);

scroll()
    .flex_1()
    .event_throttle(100.0)
    .on_scroll(move |e: &ScrollEvent| {
        at_bottom.set(e.offset.y + e.size.height >= e.content_size.height - px(20.0))
    })
    .child(content)
```

```tsx
const atBottom = signal(false);

<Scroll
  style={{ flex: 1 }}
  scrollEventThrottle={100}
  onScroll={(e) => atBottom.set(e.offset.y + e.size.height >= e.contentSize.height - 20)}
>
  …
</Scroll>
```

> [!TIP]
> `onScroll` runs your code on every frame of a scroll (subject to the throttle). For something that only has to *look* scroll-linked, such as a header that fades or a parallax image, use [`scrollValue`](#scroll-linked-effects-scrollvalue) instead: it runs entirely natively.

## Scroll-linked effects: scrollValue

`scrollValue` (`.scroll_value(&value)`) takes an [animated value](https://nsh.dev/versions/main/docs/animation.md#animated-values) and writes the scroll offset (along the main axis) into it natively, in the same frame the content moves. Bind that value, or nodes derived from it with `interpolate`, `diffClamp` (`diff_clamp`) or arithmetic, to styles.

```rust
#[component]
pub fn App() -> impl IntoElement {
    let offset = animated_value(0.0);
    view()
        .flex_1()
        .child(
            view()
                .h(px(56.0))
                .justify_center()
                .px_4()
                // Transparent at the top, white after 80 points.
                .bind_background(&offset.interpolate_colors(&[0.0, 80.0], &[rgba(0xffffff00), rgba(0xffffffff)]))
                .child(
                    text("Inbox")
                        .text_size(px(22.0))
                        .font_weight(FontWeight::BOLD)
                        .origin_left()
                        .bind_scale(&offset.interpolate(&[0.0, 80.0], &[1.0, 0.8])),
                ),
        )
        .child(scroll().flex_1().scroll_value(&offset).child(view().p_4().gap_2()))
}
```

```tsx
import { mount, Scroll, Text, View } from "nsh";
import { createAnimatedValue } from "nsh";

function App() {
  const offset = createAnimatedValue(0);
  return (
    <View style={{ flex: 1 }}>
      <View
        style={{
          height: 56,
          justifyContent: "center",
          paddingHorizontal: 16,
          // Transparent at the top, white after 80 points.
          backgroundColor: offset.interpolate({ inputRange: [0, 80], outputRange: ["rgba(255,255,255,0)", "#ffffff"] }),
        }}
      >
        <Text
          style={{
            fontSize: 22,
            fontWeight: "700",
            transformOrigin: "left center",
            scale: offset.interpolate({ inputRange: [0, 80], outputRange: [1, 0.8] }),
          }}
        >
          Inbox
        </Text>
      </View>
      <Scroll style={{ flex: 1 }} scrollValue={offset}>
        <View style={{ padding: 16, gap: 8 }}>…</View>
      </Scroll>
    </View>
  );
}

mount(App);
```

A header that slides away while the content scrolls up and comes back as soon as it scrolls down is `diffClamp` of the offset:

```rust
let offset = animated_value(0.0);
let header = offset.diff_clamp(0.0, 56.0);

view()
    .flex_1()
    .child(scroll().flex_1().scroll_value(&offset).child(view().pt(px(56.0))))
    .child(view().absolute().top_0().left_0().right_0().h(px(56.0)).bind_translate_y(&header.mul(-1.0)))
```

```tsx
const offset = createAnimatedValue(0);
const header = offset.diffClamp(0, 56);

<View style={{ flex: 1 }}>
  <Scroll style={{ flex: 1 }} scrollValue={offset}>
    <View style={{ paddingTop: 56 }}>…</View>
  </Scroll>
  <View style={{ position: "absolute", top: 0, left: 0, right: 0, height: 56, translate: [0, header.mul(-1)] }}>…</View>
</View>
```

Interpolations clamp outside their input range by default, so pulling past the top (a negative offset) keeps the effect at its end; pass `extrapolate: "extend"` (`interpolate_with(.., Interpolation::extrapolate(Extrapolate::Extend))` in Rust) for a stretchy header that grows as you pull.

## Pull to refresh

`refreshing` and `onRefresh` (`.refreshing(..)` and `.on_refresh(..)`) add the platform's pull-to-refresh control. The control shows while `refreshing` is true; set it in `onRefresh` and clear it when the work is done.

```rust
let refreshing = signal(false);
let reload = move || {
    refreshing.set(true);
    spawn(async move {
        if let Ok(response) = fetch("https://api.example.com/items").await {
            items.set(parse_items(&response.text()));
        }
        refreshing.set(false);
    });
};

scroll().flex_1().refreshing(refreshing).on_refresh(reload).child(content)
```

```tsx
const refreshing = signal(false);
const reload = async () => {
  refreshing.set(true);
  try {
    items.set(await (await fetch("https://api.example.com/items")).json());
  } finally {
    refreshing.set(false);
  }
};

<Scroll style={{ flex: 1 }} refreshing={refreshing()} onRefresh={reload}>…</Scroll>
```

On iOS the control is UIRefreshControl; in the Mac idiom of Mac Catalyst, NSH shows its own spinner with the same behavior. Lists take the same props. On the desktop and in the browser the pull is a touchscreen's (or a macOS trackpad's, which pulls past the top) gesture, since the mouse scrolls without dragging; offer another way to refresh there, such as a button or a keyboard shortcut.

### An indicator of your own

The look of the pull is the app's to choose. `refreshIndicator={{ height }}` says the app draws its own indicator, `height` points tall: the platform's spinner is hidden, a pull refreshes once it reaches `height`, and refreshing keeps `height` above the content for the indicator. `pullValue` feeds an animated value with how far the content is pulled past the top: 0 at rest, growing with the pull, and `height` while it refreshes. Draw the indicator over the top of the scroll view and interpolate its styles from the value: they follow the finger on the UI thread, with no JS per frame.

```rust
let pull = animated_value(0.0);

view()
    .flex_1()
    .child(
        scroll()
            .flex_1()
            .refreshing(refreshing)
            .on_refresh(reload)
            .pull_value(&pull)
            .refresh_indicator(Some(px(72.0)))
            .child(content),
    )
    .child(
        view()
            .pointer_events(PointerEvents::None)
            .absolute()
            .top_0()
            .left_0()
            .right_0()
            .h(px(72.0))
            .items_center()
            .justify_center()
            .bind_opacity(&pull.interpolate(&[0.0, 36.0], &[0.0, 1.0]))
            .bind_rotate(&pull.interpolate(&[36.0, 72.0], &[0.0, 180.0]))
            .child(arrow()),
    )
```

```tsx
const pull = createAnimatedValue(0);

<View style={{ flex: 1 }}>
  <Scroll
    style={{ flex: 1 }}
    refreshing={refreshing()}
    onRefresh={reload}
    pullValue={pull}
    refreshIndicator={{ height: 72 }}
  >
    …
  </Scroll>
  <View
    style={{
      pointerEvents: "none",
      position: "absolute",
      top: 0,
      left: 0,
      right: 0,
      height: 72,
      alignItems: "center",
      justifyContent: "center",
      opacity: pull.interpolate({ inputRange: [0, 36], outputRange: [0, 1] }),
      transform: [{ rotate: pull.interpolate({ inputRange: [36, 72], outputRange: ["0deg", "180deg"] }) }],
    }}
  >
    <Arrow />
  </View>
</View>;
```

Keep `height` within half the viewport: past the top the content resists the finger more the further it goes, and a height too far is never reached. On iOS, an indicator of the app's own replaces UIRefreshControl with the pull NSH detects itself, as in the Mac idiom.

## Zooming

A scroll view (lists keep a scale of 1) zooms when its maximum zoom scale is above its minimum: pinching scales the content, and while zoomed in it scrolls both ways.

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `minimumZoomScale` | `.zoom_range(min, max)` | `number` | `1` | The smallest zoom. |
| `maximumZoomScale` | `.zoom_range(min, max)` | `number` | `1` | The largest zoom; above the minimum, pinching zooms. |
| `zoomScale` | `.zoom(scale)` | `number` | | Zooms to this scale when the prop changes; the user's zoom is kept otherwise. |
| `bouncesZoom` | `.bounces_zoom(..)` | `boolean` | `true` | Pinching may go past the limits and springs back. |
| `zoomable` | `.zoomable(..)` | `boolean` | `true` | The user can pinch to zoom. |
| `centerContent` | `.center_content(..)` | `boolean` | `false` | Content smaller than the viewport (zoomed out) is centered. |

The scroll event reports the zoom scale and the zoomed content size. From code, `zoom_to(scale, center, animated)` / `zoomTo({ scale, x, y, animated })` zooms so that the content point (in unzoomed points) lands in the middle of the viewport; double tap to zoom is a press handler calling it:

```rust
pub fn photo() -> impl IntoElement {
    let photo = element_ref();
    let scale = signal(1.0_f32);
    scroll()
        .flex_1()
        .bg(black())
        .zoom_range(1.0, 4.0)
        .center_content(true)
        .on_scroll(move |e: &ScrollEvent| scale.set(e.zoom_scale))
        .element_ref(&photo)
        .child(
            image("https://picsum.photos/id/1015/1200/800")
                .w(px(390.0))
                .h(px(260.0))
                .on_press(move || photo.zoom_to(if scale.get_untracked() > 1.5 { 1.0 } else { 3.0 }, None, true)),
        )
}
```

```tsx
import { Image, mount, Scroll, type ScrollRef, signal } from "nsh";

function Photo() {
  let scroll!: ScrollRef;
  const scale = signal(1);
  return (
    <Scroll
      ref={scroll}
      style={{ flex: 1, backgroundColor: "#000000" }}
      minimumZoomScale={1}
      maximumZoomScale={4}
      centerContent
      onScroll={(e) => scale.set(e.zoomScale)}
    >
      <Image
        src="https://picsum.photos/id/1015/1200/800"
        style={{ width: 390, height: 260 }}
        onPress={() => scroll.zoomTo({ scale: scale() > 1.5 ? 1 : 3 })}
      />
    </Scroll>
  );
}

mount(Photo);
```

Text and canvases inside a zoomed scroll view are drawn again at the new resolution when the zoom ends, so they stay sharp on iOS. On Android, NSH zooms with a scroll view of its own, which scales around the pinch's focal point, pans with any number of fingers, flings and rubber-bands at the edges and zoom limits. Android starts a pinch once the fingers are about 27 mm apart, as the system's gesture detector does.

## Scrolling from code

Give the scroll view a ref (`element_ref()` and `.element_ref(&scroller)` in Rust, a [`ref`](https://nsh.dev/versions/main/docs/jsx-and-components.md) in TSX) and call its methods. Commands run after the rest of the changes in the same update, so scrolling to content you just added works.

| Rust | TSX | Description |
|---|---|---|
| `scroll_to(point, animated)` | `scrollTo({ x?, y?, animated? })` | Scrolls to an offset. Animated by default in TSX. |
| `zoom_to(scale, center, animated)` | `zoomTo({ scale, x?, y?, animated? })` | Zoomable scroll views: zooms to `scale` (clamped to the limits), around the content point or the middle. |

```rust
let scroller = element_ref();

scroll().flex_1().element_ref(&scroller).child(content)
view().on_press(move || scroller.scroll_to(point(px(0.0), px(0.0)), true))
```

```tsx
let scroll!: ScrollRef;

<Scroll ref={scroll} style={{ flex: 1 }}>…</Scroll>
<View onPress={() => scroll.scrollTo({ y: 0 })}>…</View>
```

Lists add `scrollToIndex`, `scrollToOffset` and `scrollToEnd`; see [Lists](https://nsh.dev/versions/main/docs/lists.md#scrolling-from-code).

## Scroll views and the keyboard

NSH keeps a focused input visible on its own: when the keyboard shows, the scroll view around the input gets a bottom inset as tall as the keyboard and scrolls the input into view. This happens natively, with no code in your app. Use `env(keyboard-inset-height)` as a bottom padding ([Content outside scroll views](https://nsh.dev/versions/main/docs/forms-and-keyboard.md#content-outside-scroll-views)) for content outside scroll views, such as a message bar pinned to the bottom.

Two props decide how scrolling and taps interact with the keyboard:

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `keyboardDismissMode` | `.keyboard_dismiss_mode(KeyboardDismissMode::OnDrag)` | `"none" \| "on-drag" \| "interactive"` | `"none"` | Whether dragging the content hides the keyboard. `"interactive"` lets the keyboard follow the finger down on iOS; on Android it behaves like `"on-drag"`. |
| `keyboardShouldPersistTaps` | `.keyboard_taps(KeyboardTaps::Handled)` | `"never" \| "always" \| "handled"` | `"never"` | What a tap does while the keyboard is up. |

`keyboardShouldPersistTaps`:

- `"never"`: a tap outside the focused input only hides the keyboard, and buttons get the next tap. The user taps once to dismiss, again to press.
- `"handled"`: a tap on something that handles it (a button) goes through and the keyboard stays; a tap on empty space hides it. Usually the right choice for forms.
- `"always"`: the keyboard stays up through every tap.

Both are decided natively when the tap or drag happens, without waiting for your code. To hide the keyboard from code, call `dismiss_keyboard()` in Rust or `Keyboard.dismiss()` from [`nsh`](https://nsh.dev/versions/main/modules/nsh.md#keyboard-and-keyboardframe) in TSX.

## Nested scroll views

A horizontal scroll view inside a vertical one works as expected: each takes the drags along its own axis. Two scroll views on the same axis nest too (the inner one scrolls first). Responders that need the finger, such as a drawing canvas inside a scroll view, keep it from the scroll views around them: `.keep_touches(true)` in Rust, `true` returned from `onResponderGrant` in TSX; see [Touch and gestures](https://nsh.dev/versions/main/docs/touch-and-gestures.md#the-responder-system).

## Related

- [Scroll](https://nsh.dev/versions/main/elements/scroll.md): the element reference, every prop and event.
- [Lists](https://nsh.dev/versions/main/docs/lists.md): virtualized lists with the same scrolling props.
- [Animation](https://nsh.dev/versions/main/docs/animation.md): animated values, `interpolate` and `diffClamp` for scroll-linked effects.
- [Forms and the keyboard](https://nsh.dev/versions/main/docs/forms-and-keyboard.md): inputs, focus and the keyboard.

Source: https://nsh.dev/versions/main/docs/scrolling

---

# Lists

A list (`virtual_list(..)` in Rust, `List` from `nsh` in TSX) renders long data on a native scroll view while only creating the rows near the screen. Which rows exist, where they go, the columns, sticky headers and which items are visible are all computed natively; your code only fills cells with content when the native side asks for one. A list of a million items costs about as much as a list of thirty.

```rust
use std::rc::Rc;

use nsh_core::prelude::*;

#[component]
pub fn App() -> impl IntoElement {
    let titles: Rc<Vec<String>> = Rc::new((1..=10_000).map(|i| format!("Item {i}")).collect());
    virtual_list(titles.len(), move |at| {
        let titles = titles.clone();
        view()
            .p_4()
            .border_b_1()
            .border_b_color(rgb(0xeaeef2))
            .child(text(move || titles[at.index()].clone()).text_size(px(16.0)))
    })
    .estimated_item_size(px(52.0))
    .flex_1()
    .bg(white())
}
```

```tsx
import { List, mount, Text, View } from "nsh";

const items = Array.from({ length: 10_000 }, (_, i) => ({ id: i, title: `Item ${i + 1}` }));

function App() {
  return (
    <List each={items} estimatedItemSize={52} style={{ flex: 1, backgroundColor: "#ffffff" }}>
      {(item) => (
        <View style={{ paddingHorizontal: 16, paddingVertical: 16, borderBottomWidth: 1, borderBottomColor: "#eaeef2" }}>
          <Text style={{ fontSize: 16 }}>{item().title}</Text>
        </View>
      )}
    </List>
  );
}

mount(App);
```

In Rust, `virtual_list(count, row)` takes the number of rows (a value, a signal or a closure) and a function that builds a row from its position (`at.index()`); the rows read your data by that index. In TSX, `each` takes the items and the row function gets the item. Like a [scroll view](https://nsh.dev/versions/main/docs/scrolling.md), the list is the viewport and needs a size from its parent (`.flex_1()`, `flex: 1` or a height).

## How recycling works

The row function is not called once per item. It is called **once per cell**, and cells are reused: when a row scrolls far off screen, its cell is given another row, and its position (`at.index()` in Rust, `item()` and `index()` in TSX) changes. Everything in the row that reads it updates in place, like any other [signal](https://nsh.dev/versions/main/docs/reactivity.md).

Two rules follow from that:

**Read the position where you use it.** A value copied out at the top of the row function belongs to whichever row the cell showed first.

```rust
// Wrong: `title` stays the first row's title when the cell is reused.
virtual_list(count, move |at| {
    let title = titles[at.index()].clone();
    text(title)
})

// Right: the text follows the cell's current row.
virtual_list(count, move |at| {
    let titles = titles.clone();
    text(move || titles[at.index()].clone())
})
```

```tsx
// Wrong: `title` stays the first item's title when the cell is reused.
{(item) => {
  const title = item().title;
  return <Text>{title}</Text>;
}}

// Right: the text follows the cell's current item.
{(item) => <Text>{item().title}</Text>}
```

**Keep per-item state in your data, not in the row.** A signal created inside the row belongs to the cell and travels with it to the next item. Store "is this row expanded / selected / liked" in the items or in a set keyed by id:

```rust
let liked = signal(HashSet::<u32>::new());
let toggle = move |id: u32| {
    liked.update(|s| {
        if !s.remove(&id) {
            s.insert(id);
        }
    })
};

virtual_list(move || posts.with(Vec::len), move |at| {
    let post = computed(move || posts.with(|p| p[at.index()].clone()));
    view()
        .flex_row()
        .p_4()
        .child(text(move || post.with(|p| p.title.clone())).flex_1())
        .child(
            text(move || if liked.with(|s| s.contains(&post.with(|p| p.id))) { "♥" } else { "♡" })
                .on_press(move || toggle(post.with(|p| p.id))),
        )
})
.estimated_item_size(px(64.0))
.flex_1()
```

```tsx
const liked = signal<Set<number>>(new Set());
const toggle = (id: number) =>
  liked.update((s) => {
    const next = new Set(s);
    next.has(id) ? next.delete(id) : next.add(id);
    return next;
  });

<List each={posts()} estimatedItemSize={64} style={{ flex: 1 }}>
  {(post) => (
    <View style={{ flexDirection: "row", padding: 16 }}>
      <Text style={{ flex: 1 }}>{post().title}</Text>
      <Text onPress={() => toggle(post().id)}>{liked().has(post().id) ? "♥" : "♡"}</Text>
    </View>
  )}
</List>
```

Rows can have different heights. Until a row has been measured, the list assumes the estimated item size (default 50 points); pass a value close to your typical row so the scroll indicator and jumps to far items are accurate from the start.

## Changing the data

In Rust, give the count as a signal or a closure (`move || posts.with(Vec::len)`): the list grows and shrinks in place. Rows added or removed at the end need nothing more; when rows come and go elsewhere, give their identities with `.keys(move || posts.with(|p| p.iter().map(|p| p.id).collect::<Vec<_>>()))`, and the list keeps the common start and end and treats what is between as removed and inserted.

In TSX, pass a new array to change the items: `posts.set([...posts(), ...more])`. The list compares the old and the new array **by item identity** (`===`), keeps the common start and end, and treats what is between as removed and inserted.

In both, measurements stay with their rows, and when rows are inserted above the rows on screen, the visible rows stay where they are instead of jumping.

- In TSX, update immutably: a new array, with the unchanged item objects reused. Mutating the array in place (`push`) is not seen.
- A changed item should be a new object (`{ ...post, title }`), so its row shows the change.
- Prepending (new messages, a refreshed feed) keeps the user's place.

`keyExtractor` names items in viewability tokens (below); by default the key is `item.key`, then `item.id`, then the index. It does not affect how changes are matched in TSX, which is always by identity.

## Props

A list takes every scrolling prop of the scroll view that makes sense for a list (`pagingEnabled`, `snapToInterval`, `snapToOffsets`, `snapToAlignment`, `decelerationRate`, `disableIntervalMomentum`, `bounces`, `scrollable`, `contentInset`, `contentOffset`, `keyboardShouldPersistTaps`, `keyboardDismissMode`, `scrollEventThrottle`, `onScroll`, `onScrollDragStart`, `onScrollDragEnd`, `onMomentumStart`, `onMomentumEnd`, `onScrollEnd`, `scrollValue`, `pullValue`; in Rust the same methods as a scroll view's), described in [Scrolling](https://nsh.dev/versions/main/docs/scrolling.md). Lists keep a scale of 1. Its own props:

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `each` | `virtual_list(count, ..)` | `readonly T[]` | | The items; in Rust, the number of rows. |
| `children` | `virtual_list(.., row)` | `(item: () => T, index: () => number) => JSX.Element` | | Renders a cell; called once per cell, see [recycling](#how-recycling-works). |
| `estimatedItemSize` | `.estimated_item_size(px(..))` | `number` | `50` | The size of rows not measured yet, in points. |
| `horizontal` | `.horizontal()` | `boolean` | `false` | Scrolls sideways. |
| `viewport` | `.viewport(ListViewport::..)` | `"own" \| "parent"` | `"own"` | `"own"`: the list scrolls in a scroll view of its own. `"parent"`: it lies at its full length in the scroll view around it, which scrolls it with the rest of the page (see [lists in a page](#lists-in-a-page-viewportparent)). Chosen when the list is made. |
| `numColumns` | `.columns(n)` | `number` | `1` | Items per row (vertical lists). |
| `inverted` | `.inverted()` | `boolean` | `false` | Item 0 at the bottom (chat); starts at the end and keeps its distance from the end. |
| `maintainVisibleContentPosition` | `.follow_end(px(..))` | `{ autoscrollToBottomThreshold?: number }` | | A list that is not inverted stays at the end while it is within that many points of it, as content grows (see below). |
| `stickyHeaderIndices` | `.sticky_header_indices(..)` | `number[]` | | Items that stick to the top while scrolled past (one column, not inverted). |
| `stickyHeaderOffset` | `.sticky_header_offset(px(..))`, `.bind_sticky_header_offset(&node)` | `number \| AnimatedNode` | `0` | How far below the top the sticky items stick, as CSS `position: sticky`'s `top`; the content scrolls on under the space above them. An animated value moves them every frame. |
| `contentStyle` | `.content_padding(..)`, `.content_padding_x(..)`, ..., `.row_gap(..)`, `.column_gap(..)` | `{ padding*, gap, rowGap, columnGap }` | | Padding and gaps of the content, numbers only. |
| `contentClass` | | `string` | | The same as classes (`p-*`, `gap-*`); `contentStyle` wins over them. |
| `header` | `.header(..)` | component or element | | Before the items. |
| `footer` | `.footer(..)` | component or element | | After the items. |
| `empty` | `.empty(..)` | component or element | | Shown instead of the items while there are none. |
| `separator` | `.separator(\|\| ..)` | component or element | | Between items (one column). |
| `initialScrollIndex` | `.initial_scroll_index(i)` | `number` | | Scrolls to this item before the first frame. |
| `onLoadMore` | `.on_load_more(..)` | `() => void` | | The end is near (see below). |
| `loadMoreThreshold` | `.load_more_threshold(..)` | `number` | `1` | How close to the end, in viewports, `onLoadMore` fires. |
| `onLoadMoreAtStart` | `.on_load_more_at_start(..)` | `() => void` | | The start is near, after a scroll (see below). |
| `loadMoreAtStartThreshold` | `.load_more_at_start_threshold(..)` | `number` | `1` | How close to the start, in viewports, `onLoadMoreAtStart` fires. |
| `onViewableItemsChange` | `.on_viewable_items_change(..)` | `(info) => void` | | Items became or stopped being viewable. |
| `viewabilityConfig` | `.viewability(..)`, `.minimum_view_time(..)` | `ViewabilityConfig` | | When items count as viewable. |
| `keyExtractor` | `.keys(..)` | `(item, index) => string` | | The key in viewability tokens; in Rust, the rows' identities. |
| `refreshing` / `onRefresh` | `.refreshing(..)` / `.on_refresh(..)` | `boolean` / `() => void` | | Pull to refresh. |
| `refreshIndicator` | `.refresh_indicator(..)` | `{ height: number }` | | The app's own pull-to-refresh indicator, in place of the platform's spinner (see [Scrolling](https://nsh.dev/versions/main/docs/scrolling.md#an-indicator-of-your-own)). |
| `scrollbar` | `.scrollbar(..)` | `boolean \| ScrollbarTheme` | `true` | The scroll indicator shows: the platform's, or the app's [built-in bar](https://nsh.dev/versions/main/elements/scrollbar.md#built-in-bars) once it set a theme; an object is a theme of the view's own. On the desktop and in desktop browsers a horizontal view keeps it: it is the mouse's scroll bar. |
| `ref` | `.element_ref(&list)` | `ListRef` | | `scrollToIndex`, `scrollToOffset`, `scrollToEnd`, `scrollTo`. |

The header, footer and empty slots take an element (in TSX also a component: `header={Header}`). They are cells of their own, never recycled, and they are reactive like any other element.

## Columns and grids

`numColumns` (`.columns(n)`) lays items out in rows of that many columns; content padding goes around the content, with gaps between rows and columns. Rows of a grid may have different heights: each row is as tall as its tallest item. `numColumns` may change while the list shows (more columns as a window widens): the first visible item stays at the top, and so it does when `estimatedItemSize` changes.

```rust
let count = photos.len();
virtual_list(count, move |at| {
    let photos = photos.clone();
    image(move || photos[at.index()].thumb.clone()).aspect_square().rounded(px(8.0))
})
.columns(3)
.estimated_item_size(px(120.0))
.content_padding(px(12.0))
.row_gap(px(8.0))
.column_gap(px(8.0))
.flex_1()
```

```tsx
<List
  each={photos}
  numColumns={3}
  estimatedItemSize={120}
  style={{ flex: 1 }}
  contentStyle={{ padding: 12, gap: 8 }}
>
  {(photo) => <Image src={photo().thumb} style={{ aspectRatio: 1, borderRadius: 8 }} />}
</List>
```

## Sticky headers

`stickyHeaderIndices` lists items that stick to the top of the viewport while the content scrolls past them, until the next sticky item pushes them out. Sections are one list of header and row items; the headers' indices stick. The pinning is done natively on every scroll frame.

```rust
#[derive(Clone, PartialEq)]
enum Row {
    Header(String),
    Name(String),
}

let mut rows = Vec::new();
let mut headers = Vec::new();
for (letter, names) in groups {
    headers.push(rows.len());
    rows.push(Row::Header(letter));
    rows.extend(names.into_iter().map(Row::Name));
}
let count = rows.len();
let rows = Rc::new(rows);

virtual_list(count, move |at| {
    let rows = rows.clone();
    let row = computed(move || rows[at.index()].clone());
    let is_header = computed(move || matches!(row.get(), Row::Header(_)));
    let label = move || match row.get() {
        Row::Header(s) | Row::Name(s) => s,
    };
    when(is_header, move || {
        text(label).p(px(6.0)).bg(rgb(0xeaeef2)).font_weight(FontWeight::BOLD)
    })
    .otherwise(move || text(label).p_3())
})
.sticky_header_indices(headers)
.estimated_item_size(px(44.0))
.flex_1()
```

```tsx
type Row = { header: string } | { name: string };

const rows: Row[] = [];
const headers: number[] = [];
for (const [letter, names] of groups) {
  headers.push(rows.length);
  rows.push({ header: letter });
  for (const name of names) rows.push({ name });
}

<List each={rows} stickyHeaderIndices={headers} estimatedItemSize={44} style={{ flex: 1 }}>
  {(row) => (
    <If
      when={"header" in row()}
      else={<Text style={{ padding: 12 }}>{(row() as { name: string }).name}</Text>}
    >
      <Text style={{ padding: 6, backgroundColor: "#eaeef2", fontWeight: "700" }}>{(row() as { header: string }).header}</Text>
    </If>
  )}
</List>
```

Because a cell may show a header now and a name later, the row decides what to render with [`when` / `<If>`](https://nsh.dev/versions/main/elements/control-flow.md), which switches when the row changes. Sticky headers need one column and a list that is not inverted.

`stickyHeaderOffset` (`.sticky_header_offset(..)` in Rust) makes the headers stick that many points below the top instead, as CSS `position: sticky`'s `top` does: under a translucent bar 56 points tall, `stickyHeaderOffset={56}` (`.sticky_header_offset(px(56.0))`) keeps each header below the bar while the rows scroll on under it, and the next header pushes it out from there. A negative offset leaves part of a header out of view.

The offset can be an [animated value](https://nsh.dev/versions/main/docs/animation.md#animated-values) (`.bind_sticky_header_offset(&node)` in Rust): the headers follow it every frame on the UI thread, so they stay below a bar that moves. With a bar that hides as the content scrolls down and comes back as it scrolls up ([`diffClamp`](https://nsh.dev/versions/main/docs/animation.md#arithmetic-and-diffclamp)), the headers stick to its bottom edge wherever it is:

```rust
let offset = animated_value(0.0);
let hidden = offset.diff_clamp(0.0, 56.0);
let shown = hidden.mul(-1.0).add(56.0);

view().flex_1().overflow_hidden().child(
    virtual_list(rows.len(), row)
        .scroll_value(&offset)
        .sticky_header_indices(headers)
        .bind_sticky_header_offset(&shown),
).child(view().absolute().top_0().left_0().right_0().h(px(56.0)).bind_translate_y(&hidden.mul(-1.0)))
```

```tsx
const scroll = createAnimatedValue(0);
const hidden = scroll.diffClamp(0, 56);
const shown = hidden.mul(-1).add(56);

<View style={{ flex: 1, overflow: "hidden" }}>
  <List each={rows} scrollValue={scroll} stickyHeaderIndices={headers} stickyHeaderOffset={shown}>…</List>
  <View style={{ position: "absolute", top: 0, left: 0, right: 0, height: 56, translate: [0, hidden.mul(-1)] }}>…</View>
</View>
```

## Chat: inverted lists

`inverted` lays the list out from the end: item 0 is at the bottom, the list starts scrolled to the end, and it keeps its distance from the end as items change. Keep the newest message first; prepend to add one, append to load older ones with `onLoadMore` (the "end" of an inverted list is the top). A chat opened at an old message loads the newer ones with [`onLoadMoreAtStart`](#loading-at-the-start-onloadmoreatstart); with it, the list keeps its distance from the bottom while it is there and keeps the messages on screen in place when scrolled up.

```rust
#[derive(Clone, PartialEq)]
struct Message {
    id: u32,
    text: String,
    mine: bool,
}

pub fn chat() -> impl IntoElement {
    let next = stored(0_u32);
    let message = move |text: String, mine: bool| Message {
        id: next.with(|n| {
            *n += 1;
            *n
        }),
        text,
        mine,
    };
    // Newest first.
    let messages = signal(
        (0..30)
            .map(|i| message(format!("Message {}", 30 - i), i % 3 == 0))
            .collect::<Vec<_>>(),
    );
    let draft = signal(String::new());
    let send = move || {
        let text = draft.get_untracked();
        if text.trim().is_empty() {
            return;
        }
        let sent = message(text, true);
        messages.update(|m| m.insert(0, sent));
        draft.set(String::new());
    };
    let load_older = move || {
        let older: Vec<_> = (0..20).map(|i| message(format!("Older {i}"), false)).collect();
        messages.update(|m| m.extend(older));
    };
    let list = virtual_list(
        move || messages.with(Vec::len),
        move |at| {
            let mine = computed(move || messages.with(|m| m[at.index()].mine));
            view()
                .style_when(mine, |s| s.self_end().bg(rgb(0x0969da)))
                .style_when(move || !mine.get(), |s| s.self_start().bg(rgb(0xeaeef2)))
                .max_w(relative(0.75))
                .px_3()
                .py_2()
                .rounded(px(14.0))
                .child(
                    text(move || messages.with(|m| m[at.index()].text.clone()))
                        .text_color(move || if mine.get() { rgb(0xffffff) } else { rgb(0x1f2328) }),
                )
        },
    )
    .keys(move || messages.with(|m| m.iter().map(|m| m.id).collect::<Vec<_>>()))
    .inverted()
    .estimated_item_size(px(44.0))
    .content_padding(px(12.0))
    .row_gap(px(6.0))
    .keyboard_dismiss_mode(KeyboardDismissMode::Interactive)
    .on_load_more(load_older)
    .load_more_threshold(0.5)
    .flex_1();
    view()
        .flex_1()
        .pb_keyboard()
        .child(list)
        .child(
            view().flex_row().gap_2().p_2().child(
                input()
                    .value(move || draft.get())
                    .on_change(move |text: &str| draft.set(text.to_owned()))
                    .on_submit(move |_: &str| send())
                    .multiline(true)
                    .submit_behavior(SubmitBehavior::Submit)
                    .return_key_type(ReturnKeyType::Send)
                    .placeholder("Message")
                    .flex_1()
                    .max_h(px(120.0))
                    .border_1()
                    .border_color(rgb(0xd0d7de))
                    .rounded(px(18.0))
                    .px_3()
                    .py_2(),
            ),
        )
}
```

```tsx
import { List, mount, signal, Text, View } from "nsh";
import { Input } from "nsh/base";

type Message = { id: number; text: string; mine: boolean };

function Chat() {
  let next = 0;
  const message = (text: string, mine: boolean): Message => ({ id: next++, text, mine });
  const messages = signal(Array.from({ length: 30 }, (_, i) => message(`Message ${30 - i}`, i % 3 === 0)));
  const draft = signal("");
  const send = () => {
    if (!draft().trim()) return;
    messages.update((m) => [message(draft(), true), ...m]); // newest first
    draft.set("");
  };
  const loadOlder = () => messages.update((m) => [...m, ...Array.from({ length: 20 }, (_, i) => message(`Older ${i}`, false))]);
  return (
    <View style={{ flex: 1, paddingBottom: "env(keyboard-inset-height)" }}>
      <List
        each={messages()}
        inverted
        estimatedItemSize={44}
        style={{ flex: 1 }}
        contentStyle={{ padding: 12, gap: 6 }}
        keyboardDismissMode="interactive"
        onLoadMore={loadOlder}
        loadMoreThreshold={0.5}
      >
        {(m) => (
          <View
            style={{
              alignSelf: m().mine ? "flex-end" : "flex-start",
              maxWidth: "75%",
              paddingHorizontal: 12,
              paddingVertical: 8,
              borderRadius: 14,
              backgroundColor: m().mine ? "#0969da" : "#eaeef2",
            }}
          >
            <Text style={{ color: m().mine ? "#ffffff" : "#1f2328" }}>{m().text}</Text>
          </View>
        )}
      </List>
      <View style={{ flexDirection: "row", gap: 8, padding: 8 }}>
        <Input
          value={draft()}
          onChange={({ value }) => draft.set(value)}
          onSubmit={send}
          multiline
          submitBehavior="submit"
          returnKeyType="send"
          placeholder="Message"
          style={{ flex: 1, maxHeight: 120, borderWidth: 1, borderColor: "#d0d7de", borderRadius: 18, paddingHorizontal: 12, paddingVertical: 8 }}
        />
      </View>
    </View>
  );
}

mount(Chat);
```

`scroll_to_end(..)` / `scrollToEnd()` on an inverted list scrolls to its start: the newest message.

### Following the end of a list that is not inverted

A list in reading order (oldest first) can follow its end too: with `.follow_end(px(40.0))` in Rust or `maintainVisibleContentPosition={{ autoscrollToBottomThreshold: 40 }}` in TSX, while the user is at the end (or within 40 points of it), the list stays at the end as the content grows: a reply streaming into the last item, a new message appended, the keyboard shrinking the list. Scrolled further up, the visible content stays where it is and the new content grows below it. Items inserted above the visible ones never move them, with or without the option.

```rust
virtual_list(move || messages.with(Vec::len), move |at| bubble(messages, at))
    .keys(move || messages.with(|m| m.iter().map(|m| m.id).collect::<Vec<_>>()))
    .follow_end(px(40.0))
    .flex_1()
```

```tsx
<List each={messages()} keyExtractor={(m) => m.id} maintainVisibleContentPosition={{ autoscrollToBottomThreshold: 40 }} style={{ flex: 1 }}>
  {(m) => <Bubble message={m()} />}
</List>
```

## Horizontal lists

`horizontal` turns the list sideways; cells are laid out at the list's height. Combined with snapping it makes a carousel of any length:

```rust
let count = cards.len();
virtual_list(count, move |at| {
    let cards = cards.clone();
    view()
        .w(px(220.0))
        .h(px(140.0))
        .rounded(px(14.0))
        .bg(move || cards[at.index()].color)
})
.horizontal()
.estimated_item_size(px(232.0))
.snap_interval(px(232.0))
.deceleration(0.99)
.scrollbar(false)
.content_padding_x(px(16.0))
.column_gap(px(12.0))
.h(px(140.0))
```

```tsx
<List
  each={cards}
  horizontal
  estimatedItemSize={232}
  snapToInterval={232}
  decelerationRate="fast"
  scrollbar={false}
  style={{ height: 140 }}
  contentStyle={{ paddingHorizontal: 16, gap: 12 }}
>
  {(card) => <View style={{ width: 220, height: 140, borderRadius: 14, backgroundColor: card().color }} />}
</List>
```

Right to left, horizontal lists start at the right and run leftwards.

## Lists in a page: viewport="parent"

A page often scrolls as one: a header, a few cards, then a long list, and maybe another list below it. Give the list `viewport="parent"` (`.viewport(ListViewport::Parent)` in Rust) and put it in a `Scroll` with the rest of the page: the list lies in the page at its full length, and the page's scroll view scrolls it with everything else. It still creates only the rows near the page's viewport and recycles their cells, so one page can hold several long lists.

```rust
scroll()
    .flex_1()
    .child(header())
    .child(
        virtual_list(count, row)
            .viewport(ListViewport::Parent)
            .estimated_item_size(px(56.0))
            .row_gap(px(6.0)),
    )
    .child(footer())
```

```tsx
<Scroll style={{ flex: 1 }}>
  <Header />
  <List viewport="parent" each={items} estimatedItemSize={56} contentStyle={{ gap: 6 }}>
    {(item) => <Row item={item()} />}
  </List>
  <Footer />
</Scroll>
```

- The list is as long as its rows: its height (its width, sideways) comes from its content, as a view's does, and its padding, border and margins work as on a view.
- Its rows follow the nearest scroll view around it along its axis, or the screen it is on.
- The page keeps what you read in place, as a browser does: rows that change size wholly above the top of the viewport move the page by as much; while the list's start is in view, rows that grow push what is below them down.
- `scrollToIndex`, `scrollToEnd` and `initialScrollIndex` scroll the page to the list's rows, within the page's content; `onLoadMore` fires as the list's end comes near the viewport, and `onViewableItemsChange` reports the rows in the page's viewport.
- `stickyHeaderIndices` and `stickyHeaderOffset` stick rows to the top of the page: a section header stays at the top while its rows scroll under it, until the next one pushes it out, and the last one leaves with the end of its list.
- How the page scrolls is its scroll view's: set `onScroll` and the other scroll events, `scrollValue`, `refreshing` / `onRefresh`, paging and snapping, `contentInset`, `scrollbar`, `scrollable` and `keyboardDismissMode` on the `Scroll`. Inverted lists and `maintainVisibleContentPosition` are features of a list with a viewport of its own (`viewport="own"`, the default).
- The viewport is chosen when the list is made: to switch, render a new list.

## Loading more: onLoadMore

`onLoadMore` (`.on_load_more(..)`) fires when the viewport comes within `loadMoreThreshold` viewports of the end (1 by default: one screen ahead). Append the next page; the list fires again when the new end comes near.

```rust
let posts = signal(Vec::<Post>::new());
let page = stored(0_u32);
let loading = stored(false);

let load_more = move || {
    if loading.replace(true) {
        return;
    }
    let next = page.with(|p| {
        *p += 1;
        *p
    });
    spawn(async move {
        if let Ok(response) = fetch(format!("https://api.example.com/posts?page={next}")).await {
            let more = parse_posts(&response.text());
            posts.update(|p| p.extend(more));
        }
        loading.replace(false);
    });
};
load_more();

virtual_list(move || posts.with(Vec::len), move |at| post_row(posts, at))
    .estimated_item_size(px(72.0))
    .on_load_more(load_more)
    .load_more_threshold(0.5)
    .footer(text("Loading…").p_4().text_center().text_color(rgb(0x8c959f)))
    .flex_1()
```

```tsx
const posts = signal<Post[]>([]);
let loading = false;
let page = 0;

const loadMore = async () => {
  if (loading) return;
  loading = true;
  try {
    const next: Post[] = await (await fetch(`https://api.example.com/posts?page=${++page}`)).json();
    posts.set([...posts(), ...next]);
  } finally {
    loading = false;
  }
};
loadMore();

<List
  each={posts()}
  estimatedItemSize={72}
  style={{ flex: 1 }}
  onLoadMore={loadMore}
  loadMoreThreshold={0.5}
  footer={<Text style={{ padding: 16, textAlign: "center", color: "#8c959f" }}>Loading…</Text>}
>
  {(post) => <PostRow post={post()} />}
</List>
```

Guard against overlapping loads as above: the end may be reported again while a page is on its way.

## Loading at the start: onLoadMoreAtStart

A list can also open in the middle of its data: a chat opened at an old message (a search result, a reply's quote) shows a page around it, with newer messages still to load. `onLoadMoreAtStart` (`.on_load_more_at_start(..)`) fires when the viewport comes within `loadMoreAtStartThreshold` viewports of the start (1 by default), the side of item 0: the top of a list, the bottom of an inverted one. Prepend the page: the rows on screen keep their place while it arrives before them (an inverted list too, once scrolled away from its bottom), and the list fires again on the next approach, or at once when the page left it still near the start.

It fires once the user scrolls there or a scroll command takes the list there (`initialScrollIndex` included), so a list that opens at its newest item asks for nothing, and one opened with `initialScrollIndex` near its start asks for the page before it right away.

```rust
let messages = signal(page_around(target)); // newest first, ending at an old message
let loading = stored(false);

let load_newer = move |_: &()| {
    if loading.replace(true) {
        return;
    }
    let newest = messages.with(|m| m[0].id);
    spawn(async move {
        if let Ok(response) = fetch(format!("https://api.example.com/messages?after={newest}")).await {
            let newer = parse_messages(&response.text());
            messages.update(|m| {
                m.splice(0..0, newer);
            });
        }
        loading.replace(false);
    });
};

virtual_list(move || messages.with(Vec::len), move |at| message_row(messages, at))
    .inverted(true)
    .on_load_more(load_older)
    .on_load_more_at_start(load_newer)
    .load_more_at_start_threshold(0.5)
    .flex_1()
```

```tsx
const messages = signal<Message[]>(pageAround(target)); // newest first, ending at an old message
let loading = false;

const loadNewer = async () => {
  if (loading) return;
  loading = true;
  try {
    const newest = messages()[0].id;
    const newer: Message[] = await (await fetch(`https://api.example.com/messages?after=${newest}`)).json();
    messages.set([...newer, ...messages()]);
  } finally {
    loading = false;
  }
};

<List
  each={messages()}
  inverted
  style={{ flex: 1 }}
  onLoadMore={loadOlder}
  onLoadMoreAtStart={loadNewer}
  loadMoreAtStartThreshold={0.5}
>
  {(message) => <Bubble message={message()} />}
</List>
```

Once the newest message is in, stop loading: new messages then arrive at the start as in any chat.

## Viewability

`onViewableItemsChange` (`.on_viewable_items_change(..)`) reports which items are on screen, for analytics, autoplaying the visible video, or marking messages read. In TSX it gets `{ viewableItems, changed }`, arrays of tokens `{ item, key, index, isViewable }`; in Rust, `ViewableItems` with the first and last viewable row (`viewable`) and the rows whose state changed (`changed()`). Viewability is computed natively; your code only hears about changes.

| `viewabilityConfig` | Rust | Description |
|---|---|---|
| `itemVisibleThreshold` | `Viewability { item_visible_threshold, .. }` | How much of an item must be visible, from 0 to 1. |
| `viewAreaCoverageThreshold` | `Viewability { view_area_coverage_threshold, .. }` | How much of the viewport an item must cover, from 0 to 1. |
| `minimumViewTime` | `.minimum_view_time(Duration)` | Milliseconds an item must stay viewable before it is reported. |

Without a threshold, any visible pixel counts.

```rust
let playing = signal(None::<usize>);

virtual_list(count, move |at| video_card(videos.clone(), at))
    .estimated_item_size(px(300.0))
    .viewability(Viewability {
        item_visible_threshold: Some(Percentage(0.6)),
        ..Viewability::default()
    })
    .minimum_view_time(Duration::from_millis(250))
    .on_viewable_items_change(move |rows: &ViewableItems| {
        playing.set(rows.viewable.map(|(first, _)| first))
    })
    .flex_1()
```

```tsx
<List
  each={videos}
  estimatedItemSize={300}
  style={{ flex: 1 }}
  keyExtractor={(v) => v.slug}
  viewabilityConfig={{ itemVisibleThreshold: 0.6, minimumViewTime: 250 }}
  onViewableItemsChange={({ viewableItems }) => playing.set(viewableItems[0]?.key ?? null)}
>
  {(v) => <VideoCard video={v()} />}
</List>
```

## Scrolling from code

Give the list a ref (`element_ref()` and `.element_ref(&list)` in Rust, `ref` in TSX):

| Rust | TSX | Description |
|---|---|---|
| `scroll_to_index(index, view_position, view_offset, animated)` | `scrollToIndex({ index, animated?, viewPosition?, viewOffset? })` | Scrolls item `index` into view. The view position places it: 0 at the start of the viewport (default), 0.5 in the middle, 1 at the end; the view offset shifts it further. |
| `scroll_to_offset(offset, animated)` | `scrollToOffset({ offset, animated? })` | Scrolls to a content offset along the list's axis. |
| `scroll_to_end(animated)` | `scrollToEnd({ animated? })` | Scrolls to the end of the content (the start of an inverted list). |
| `scroll_to(point, animated)` | `scrollTo({ x?, y?, animated? })` | Scrolls to an offset, as on a scroll view. |

```rust
let list = element_ref();

virtual_list(count, row).estimated_item_size(px(48.0)).flex_1().element_ref(&list)

list.scroll_to_index(120, percentage(0.5), px(0.0), true);
```

```tsx
import { List, type ListRef } from "nsh";

let list!: ListRef;

<List ref={list} each={items} estimatedItemSize={48} style={{ flex: 1 }}>…</List>

list.scrollToIndex({ index: 120, viewPosition: 0.5 });
```

Scrolling to an index (and to the end) is resolved natively with the sizes known at that moment: measured rows where they have been measured, the estimated size elsewhere. The list then follows its target while the rows around it are measured, so it lands exactly, until the user scrolls or the items change. To open a list at an item, use `initialScrollIndex` (`.initial_scroll_index(..)`) rather than scrolling after the first frame.

## A settings-style list

The look of a list is the app's own: the list places and recycles the rows, and the rows, dividers and surfaces are your views. A grouped, settings-style list is a list with padding, a separator and rounded first and last rows. Make it a component of your own and use it wherever the app lists settings:

```rust
use std::rc::Rc;

use nsh_core::{element::palette::NEUTRAL, prelude::*};

pub struct Setting {
    pub id: &'static str,
    pub label: &'static str,
}

pub fn settings_list(settings: Rc<Vec<Setting>>, on_select: impl Fn(&Setting) + 'static) -> impl IntoElement {
    let surface = AdaptiveColor::new(white(), NEUTRAL.shade(900));
    let on_select = Rc::new(on_select);
    let count = settings.len();
    view().flex_1().bg(AdaptiveColor::new(NEUTRAL.shade(100), NEUTRAL.shade(950))).child(
        virtual_list(count, move |at| {
            let (pressed, shown, on_select) = (settings.clone(), settings.clone(), on_select.clone());
            view()
                .on_press(move || on_select(&pressed[at.index()]))
                .role(AccessibilityRole::Button)
                .h_12()
                .justify_center()
                .bg(surface)
                .px_4()
                .active(|s| s.bg(NEUTRAL.shade(200)))
                .rounded_t(move || px(if at.is_first() { 12.0 } else { 0.0 }))
                .rounded_b(move || px(if at.is_last() { 12.0 } else { 0.0 }))
                .child(text(move || shown[at.index()].label))
        })
        .estimated_item_size(px(48.0))
        .content_padding(px(16.0))
        .separator(move || {
            view()
                .bg(surface)
                .child(view().ml_4().h(px(1.0)).bg(AdaptiveColor::new(NEUTRAL.shade(200), NEUTRAL.shade(800))))
        })
        .flex_1(),
    )
}
```

```tsx
import { List, Text, View } from "nsh";

type Setting = { id: string; label: string };

function SettingsList(props: { each: Setting[]; onSelect: (s: Setting) => void }) {
  return (
    <View class="flex-1 bg-neutral-100 dark:bg-neutral-950">
      <List
        each={props.each}
        estimatedItemSize={48}
        style={{ flex: 1 }}
        contentStyle={{ padding: 16 }}
        separator={() => (
          <View class="bg-white dark:bg-neutral-900">
            <View class="ml-4 h-px bg-neutral-200 dark:bg-neutral-800" />
          </View>
        )}
      >
        {(s, i) => (
          <View
            onPress={() => props.onSelect(s())}
            role="button"
            class="h-12 justify-center bg-white px-4 active:bg-neutral-200 dark:bg-neutral-900"
            classList={{ "rounded-t-xl": i() === 0, "rounded-b-xl": i() === props.each.length - 1 }}
          >
            <Text>{s().label}</Text>
          </View>
        )}
      </List>
    </View>
  );
}
```

## Performance notes

- Each cell is laid out on its own, so scrolling only lays out the cells that changed. Keep rows shallow and avoid reading signals in rows that change on every frame.
- The native side asks for cells in batches, up to several rounds per frame, merged into one update; a fast fling binds many cells in one frame without a call into your code per cell. Rust rows are bound in the core itself, within the commit that needs them.
- Use [`nsh test --trace` with a `scroll` step](https://nsh.dev/versions/main/docs/testing-and-trace.md#scrolling) to measure the per-frame cost of your rows.

## Related

- [`List` element](https://nsh.dev/versions/main/elements/list.md): the reference.
- [Scrolling](https://nsh.dev/versions/main/docs/scrolling.md): the scrolling props lists share with scroll views.
- [Reactivity](https://nsh.dev/versions/main/docs/reactivity.md): why rows read their position in bindings.
- [Performance](https://nsh.dev/versions/main/docs/performance.md): measuring lists.

Source: https://nsh.dev/versions/main/docs/lists

---

# Navigation

`nsh_base` (TSX: `nsh/base`) provides a native navigation stack and native dialogs. A navigation stack (`nav_stack()` in Rust, `NavStack` in TSX) is a UINavigationController on iOS, with its header, swipe back and large titles, and a stack with a toolbar and predictive back on Android; on the desktops and the web, each page shows the header your app draws. You keep the routes in your state; the stack renders each route as a page and keeps it mounted, with its state, while it is in the stack.

In Rust, import the builders by name next to the prelude (`use nsh_base::{dialog, nav_page, nav_stack};`; system alerts are `nsh_base::alert_dialog()`). The routes are a signal and the stack's children are its pages, one per route, kept by key (`each`): a page goes in to push it and out to pop it. In TSX, `createNavStack` holds the routes and `NavStack` renders them.

```rust
use nsh_base::{nav_page, nav_stack};
use nsh_core::prelude::*;

#[derive(Debug, Clone, PartialEq)]
enum Route {
    Inbox,
    Message(u32),
}

/// The page's header on the desktops and the web; iOS and Android show the system's, from `title`.
fn header(routes: Signal<Vec<Route>>, title: &'static str) -> impl IntoElement {
    view()
        .h(px(48.0))
        .flex_row()
        .items_center()
        .gap_3()
        .border_b_1()
        .border_color(rgb(0xe5e7eb))
        .px_4()
        .child(when(
            move || routes.with(|r| r.len() > 1),
            move || {
                text("Back")
                    .role(AccessibilityRole::Button)
                    .on_press(move || routes.update(|r| { r.pop(); }))
                    .text_color(rgb(0x2563eb))
                    .active(|s| s.opacity(0.6))
            },
        ))
        .child(text(title).text_size(px(17.0)).font_weight(FontWeight::SEMIBOLD))
}

fn inbox(routes: Signal<Vec<Route>>) -> Screen {
    nav_page()
        .title("Inbox")
        .header(header(routes, "Inbox"))
        .child(scroll().flex_1().children((1..=5).map(move |id| {
            view()
                .on_press(move || routes.update(|r| r.push(Route::Message(id))))
                .p_4()
                .active(|s| s.bg(rgb(0xf3f4f6)))
                .child(text(format!("Message {id}")))
        })))
}

fn message(routes: Signal<Vec<Route>>, id: u32) -> Screen {
    nav_page()
        .title(format!("Message {id}"))
        .header(header(routes, "Message"))
        .child(view().flex_1().p(px(16.0)).child(text(format!("The body of message {id}."))))
}

#[component]
pub fn App() -> impl IntoElement {
    let routes = signal(vec![Route::Inbox]);
    nav_stack().flex_1().child(each(
        move || routes.get(),
        |route: &Route| format!("{route:?}"),
        move |route, index| {
            let page = match route.get_untracked() {
                Route::Inbox => inbox(routes),
                Route::Message(id) => message(routes, id),
            };
            // The user went back natively: drop the route (and those above it).
            page.on_dismiss(move || routes.update(|r| r.truncate(index.get_untracked())))
        },
    ))
}
```

```tsx
import { mount, Scroll, Text, View } from "nsh";
import { createNavStack, NavPage, NavStack } from "nsh/base";

type Route = { name: "inbox" } | { name: "message"; id: number };

const nav = createNavStack<Route>([{ name: "inbox" }]);

// The page's header on the desktops and the web; iOS and Android show the system's, from `title`.
function Header(props: { title: string }) {
  return (
    <View class="h-12 flex-row items-center gap-3 border-b border-gray-200 px-4">
      <If when={nav.routes().length > 1}>
        <Text role="button" onPress={() => nav.pop()} class="text-blue-600 active:opacity-60">
          Back
        </Text>
      </If>
      <Text style={{ fontSize: 17, fontWeight: "600" }}>{props.title}</Text>
    </View>
  );
}

function Inbox() {
  return (
    <NavPage title="Inbox" header={<Header title="Inbox" />}>
      <Scroll style={{ flex: 1 }}>
        <Each of={[1, 2, 3, 4, 5]}>
          {(id) => (
            <View onPress={() => nav.push({ name: "message", id: id() })} class="p-4 active:bg-gray-100">
              <Text>Message {id()}</Text>
            </View>
          )}
        </Each>
      </Scroll>
    </NavPage>
  );
}

function Message(props: { id: number }) {
  return (
    <NavPage title={`Message ${props.id}`} header={<Header title={`Message ${props.id}`} />}>
      <View style={{ flex: 1, padding: 16 }}>
        <Text>The body of message {props.id}.</Text>
      </View>
    </NavPage>
  );
}

function App() {
  return (
    <NavStack state={nav} style={{ flex: 1 }}>
      {(route) => {
        switch (route.name) {
          case "inbox":
            return <Inbox />;
          case "message":
            return <Message id={route.id} />;
        }
      }}
    </NavStack>
  );
}

mount(App);
```

## The stack's state

In Rust, the routes are your own signal (`signal(vec![..])`, or `global::<Routes>()` for one the whole app reaches), and you push, pop and replace by updating it: `routes.update(|r| r.push(route))`, `r.pop()`, `r.truncate(1)`, `routes.set(..)`. Each page's key (here the route's `Debug` text) tells the stack which page is which, so pages whose route stays keep their state; give routes that may repeat a unique key. Handle each page's `on_dismiss`: the user went back natively, and the route (with those above it) leaves your signal.

In TSX, `createNavStack(routes)` creates the stack's state from an array of routes, bottom to top. A route is any value you like (a string, an object, a discriminated union as above), and each push is a page of its own, the same route pushed twice included. Create the state once, at module level or in your root component, and import it wherever pages navigate.

| Member | Description |
|---|---|
| `routes()` | The routes, bottom to top (reactive). |
| `push(route)` | Pushes a page. |
| `pop(count?)` | Pops `count` pages (default 1); at least one stays. |
| `popToRoot()` | Pops back to the first page. |
| `replace(route)` | Replaces the top page. |
| `setRoutes(routes)` | Replaces the pages, e.g. after signing in; a route that stays (the same value) keeps its page and its state. |
| `remove(route)` | Removes the topmost page of `route`, wherever it is. |

To start several pages deep, pass more routes: `createNavStack<Route>([{ name: "inbox" }, { name: "message", id: 3 }])`.

When the user leaves a page natively (the back button in the header, a swipe back on iOS, Android's back button or gesture, the desktops' back keys and mouse button, the browser's back button), the TSX stack removes that route from its state for you, so `routes()` always matches what is on screen; a Rust page reports it with `on_dismiss`, as above.

A route carries what the page needs. The gallery apps push routes that hold what makes the page, which keeps the route type small when there are many pages:

```rust
use std::rc::Rc;

use nsh_core::prelude::*;

/// A pushed page: its key (unique in the stack) and what makes it.
#[derive(Clone)]
pub struct Route {
    pub key: SharedString,
    pub page: Rc<dyn Fn() -> Screen>,
}

impl PartialEq for Route {
    fn eq(&self, other: &Self) -> bool {
        self.key == other.key
    }
}

/// The pushed pages, bottom to top: one signal for the whole app.
#[derive(Default, Clone)]
pub struct Routes(pub Vec<Route>);

pub fn routes() -> Signal<Routes> {
    global::<Routes>()
}

// Elsewhere: routes().update(|r| r.0.push(Route { key: "settings".into(), page: Rc::new(settings) }));
```

```ts
import { type JSX } from "nsh";
import { createNavStack } from "nsh/base";

export type Route = { name: "home" } | { name: "page"; page: () => JSX.Element };
export const nav = createNavStack<Route>([{ name: "home" }]);

// Elsewhere: nav.push({ name: "page", page: Settings });
```

## NavStack

In Rust, `nav_stack()` is a view whose children are its pages, bottom to top; style it as any view (`.flex_1()`). In TSX:

| Prop | Type | Description |
|---|---|---|
| `state` | `NavStackState<R>` | The routes to show. |
| `children` | `(route: R, index: Accessor<number>) => JSX.Element` | Renders a route; return a `<NavPage>` for its header. |
| `style`, `class` | | The stack's own style (usually `flex: 1`). |

The render function runs once per route, when it is pushed; `route` is the plain value, `index()` its current position. What it returns becomes the page's content. Return a `<NavPage>` to set the header; anything else is wrapped in a page with default options.

Pages stay mounted while their route is in the stack: going back shows the previous page exactly as it was left, with its scroll position, inputs and signals. A page's [`cleanup`](https://nsh.dev/versions/main/docs/reactivity.md) handlers run when its route leaves the stack.

## NavPage and the header

A page (`nav_page()` in Rust, `NavPage` in TSX) wraps a page's content and carries its header. iOS and Android show their system header, set up by the title and the header options. The desktops and the web show the page's header slot (`.header(..)`, TSX `header`), your own views, at the top of the page: as wide as the page, as tall as it lays out, with the content below it. Give a page both, as the example above does, and it looks at home everywhere. All options are reactive: change a signal and the header follows.

In Rust, each prop below is a method of `nav_page()` in snake case: `.title(..)`, `.header(..)`, `.header_visible(..)`, `.header_transparent(..)`, `.header_style_with(..)`, `.header_style(..)`, `.header_back_visible(..)`, `.header_left(..)`, `.header_right(..)`, `.header_title(..)`, `.header_large_title(..)`, `.header_back_title(..)`, `.animation(ScreenAnimation::Fade)`, `.status_bar(..)`, `.pop_on_swipe(..)`, `.pop_on_back(..)`, `.on_back_press(..)`, `.on_dismiss(..)`; its children are its content.

| Prop | Type | Default | Description |
|---|---|---|---|
| `header` | `JSX.Element` | | The desktops and the web: the page's header, drawn by the app (a title, a back button, toolbar buttons). |
| `title` | `string` | | iOS and Android: the system header's title. |
| `headerVisible` | `boolean` | `true` | iOS and Android: the system header shows. |
| `headerTransparent` | `boolean` | `false` | iOS and Android: the content extends under the header. |
| `headerStyle` | `{ backgroundColor?, color?, tintColor? }` | | iOS and Android: the header's background, the title's color (`color`) and the buttons' (`tintColor`). |
| `headerClass` | `string` | | The same as classes: `bg-*`, `text-*` for the title, `tint-*` for the buttons; `headerStyle` wins over them. |
| `headerBackVisible` | `boolean` | `true` | iOS and Android: the back button shows. |
| `headerLeft` | `JSX.Element` | | iOS and Android: views at the start of the header (they replace the back button). |
| `headerRight` | `JSX.Element` | | iOS and Android: views at the end of the header. |
| `ios={{ headerRightSystemItem }}` | `"add" \| "done" \| "close" \| "edit" \| "compose" \| "search" \| "share" \| "trash" \| "save" \| "cancel"` | | iOS: UIKit's own bar button at the end of the header, with the system's look, symbol or label, in place of `headerRight`'s views; a press on it is a press on the first pressable view of `headerRight`, so keep one there. Android shows `headerRight` as it is. |
| `ios={{ headerLeftSystemItem }}` | same as `headerRightSystemItem` | | iOS: the same, at the start of the header, pressing `headerLeft`. |
| `ios={{ headerRightSymbol }}` | `string` | | iOS: UIKit's own bar button showing the SF Symbol of that name (`"slider.horizontal.3"`) in place of `headerRight`'s views; a press on it is a press on the first pressable view of `headerRight`, and VoiceOver reads that view's label. `headerRightSystemItem` wins over it; a name SF Symbols does not have shows `headerRight` as it is. Android shows `headerRight` as it is. |
| `ios={{ headerLeftSymbol }}` | `string` | | iOS: the same, at the start of the header, pressing `headerLeft`. |
| `headerTitle` | `JSX.Element` | | iOS and Android: views replacing the title. |
| `headerLargeTitle` | `boolean` | `false` | iOS: a large title that shrinks into the bar as the content scrolls. |
| `headerBackTitle` | `string` | | The label of the back button that leads back to this page (iOS; Android's up arrow says it to screen readers). |
| `animation` | `"default" \| "slide" \| "fade" \| "none"` | `"default"` | How the page enters and leaves. |
| `statusBar` | `{ foreground?, hidden?, animated? }` | | iOS and Android: the status bar while the page is on top ([Status bar](https://nsh.dev/versions/main/modules/nsh-base.md#status-bar)). |
| `popOnSwipe` | `boolean` | `true` | The interactive back gesture (iOS swipe back, Android predictive back) pops. The back buttons pop either way. |
| `popOnBack` | `boolean` | `true` | Every way back pops the page: the back buttons, Android's back, the desktops' back keys, the browser's back button and the swipe. |
| `onBackPress` | `() => void` | | The user pressed back on the page, whether or not `popOnBack` let it pop. |
| `onDismiss` | `() => void` | | The user popped the page; its route is already removed. |
| `style`, `class` | | | The page's content view. |

Header items are ordinary views, so they can be pressable and reactive:

```rust
fn compose(routes: Signal<Vec<Route>>) -> Screen {
    let draft = signal(String::new());
    let cancel = move || {
        text("Cancel")
            .on_press(move || routes.update(|r| { r.pop(); }))
            .text_size(px(17.0))
            .text_color(rgb(0x0969da))
    };
    let send_button = move || {
        text("Send")
            .on_press(move || send(draft.get()))
            .text_size(px(17.0))
            .font_weight(FontWeight::SEMIBOLD)
            .text_color(move || if draft.with(String::is_empty) { rgb(0x8c959f) } else { rgb(0x0969da) })
    };
    nav_page()
        .title("New message")
        .header_left(cancel())
        .header_right(send_button())
        .header(
            view()
                .h(px(48.0))
                .flex_row()
                .items_center()
                .justify_between()
                .px_4()
                .child(cancel())
                .child(text("New message").text_size(px(17.0)).font_weight(FontWeight::SEMIBOLD))
                .child(send_button()),
        )
        .child(
            input()
                .multiline(true)
                .value(move || draft.get())
                .on_change(move |t: &str| draft.set(t.to_owned()))
                .flex_1()
                .p(px(16.0))
                .text_size(px(17.0)),
        )
}
```

```tsx
function Compose() {
  const text = signal("");
  const cancel = () => (
    <Text onPress={() => nav.pop()} style={{ fontSize: 17, color: "#0969da" }}>
      Cancel
    </Text>
  );
  const sendButton = () => (
    <Text
      onPress={() => send(text())}
      style={{ fontSize: 17, fontWeight: "600", color: text() ? "#0969da" : "#8c959f" }}
    >
      Send
    </Text>
  );
  return (
    <NavPage
      title="New message"
      headerLeft={cancel()}
      headerRight={sendButton()}
      header={
        <View class="h-12 flex-row items-center justify-between px-4">
          {cancel()}
          <Text style={{ fontSize: 17, fontWeight: "600" }}>New message</Text>
          {sendButton()}
        </View>
      }
    >
      <Input multiline value={text()} onChange={({ value }) => text.set(value)} style={{ flex: 1, padding: 16, fontSize: 17 }} />
    </NavPage>
  );
}
```

A colored system header (in Rust, `header_style_with` takes typed styles: `bg`, `text_color` and `tint_color`, the color of the header's buttons; theme colors follow the appearance):

```rust
nav_page()
    .title("Profile")
    .header_style_with(|s| s.bg(rgb(0x1a7f37)).text_color(rgb(0xffffff)).tint_color(rgb(0xffffff)))
```

```tsx
<NavPage title="Profile" headerStyle={{ backgroundColor: "#1a7f37", color: "#ffffff", tintColor: "#ffffff" }}>
  …
</NavPage>
```

A page that shows no header still has the system bars around it; pad its content by the [safe area](https://nsh.dev/versions/main/elements/safe-area.md) insets:

```rust
use nsh_base::nav_page;

nav_page()
    .header_visible(false)
    .child(view().flex_1().p_safe_area() /* … */)
```

```tsx
<NavPage headerVisible={false}>
  <View class="flex-1 pt-[calc(env(safe-area-inset-top)+16px)] pb-[calc(env(safe-area-inset-bottom)+16px)] px-4">…</View>
</NavPage>
```

### Safe areas under the header

Inside a page, the `env(safe-area-inset-*)` variables and the page's insets (`Scope::insets` in Rust, `safeAreaInsets()` in TSX) are those below the system header, within the page. With a transparent header, the content starts at the top of the page and the top inset is the header's height, so padding by `env(safe-area-inset-top)` keeps text clear of it while a background image fills the whole page. With a large title, put a scroll view directly in the page so the title can collapse as it scrolls. On the desktops and the web, the content starts below the page's header slot.

## Keeping the user on a page: popOnBack

To ask before discarding unsaved changes, set `pop_on_back` (TSX `popOnBack`) to false while there is something to lose, handle the back press (`.on_back_press(..)`, TSX `onBackPress`), and pop once the user agrees:

```rust
use nsh_base::{alert_dialog, nav_page};
use nsh_core::prelude::*;

fn edit_note(routes: Signal<Vec<Route>>) -> Screen {
    let draft = signal(String::new());
    let confirm = move || {
        spawn(async move {
            let choice = alert_dialog()
                .title("Discard your changes?")
                .cancel("keep", "Keep editing")
                .destructive("discard", "Discard")
                .show()
                .await;
            if choice.is_ok_and(|r| r.action.as_deref() == Some("discard")) {
                routes.update(|r| { r.pop(); });
            }
        });
    };
    nav_page()
        .title("Edit")
        .pop_on_back(move || draft.with(String::is_empty))
        .on_back_press(move || {
            if !draft.with(String::is_empty) {
                confirm();
            }
        })
        .child(
            input()
                .value(move || draft.get())
                .on_change(move |t: &str| draft.set(t.to_owned()))
                .placeholder("A note")
                .m(px(16.0))
                .text_size(px(17.0)),
        )
}
```

```tsx
import { signal } from "nsh";
import { AlertDialog, NavPage, Input } from "nsh/base";

function EditNote() {
  const text = signal("");
  const dirty = () => text().length > 0;
  const confirm = async () => {
    const { action } = await AlertDialog.show({
      title: "Discard your changes?",
      actions: [
        { label: "Keep editing", role: "cancel", id: "keep" },
        { label: "Discard", role: "destructive", id: "discard" },
      ],
    });
    if (action === "discard") nav.pop();
  };
  return (
    <NavPage title="Edit" popOnBack={!dirty()} onBackPress={() => dirty() && confirm()}>
      <Input value={text()} onChange={({ value }) => text.set(value)} placeholder="A note" style={{ margin: 16, fontSize: 17 }} />
    </NavPage>
  );
}
```

With `pop_on_back(false)` (`popOnBack={false}`), the page stays on every way back (the back buttons, Android's back button and gesture, the desktops' back keys, the browser's back button, the swipe), and the back press event tells you the user tried. Popping from code (removing the route, `nav.pop()`) pops as always.

> [!IMPORTANT]
> `pop_on_back` / `popOnBack` is a prop, not a callback that returns true or false, because the main thread never waits for app code. When the user starts a swipe or presses back, the system asks right away whether the page may go, and NSH answers natively from the props it already has. Set it as soon as there is something to lose (as above, from the text), before the user tries to leave.

`pop_on_swipe(false)` (`popOnSwipe={false}`) is the lighter option: it turns off only the interactive gesture (iOS swipe back, Android's predictive back animation), and the back buttons still pop.

## Dialogs

A dialog (`dialog()` of `nsh_base` in Rust, `Dialog` in TSX) presents content over everything else, in its own native window layer: a presented view controller on iOS, a dialog window on Android, a layer over the whole window on the desktops and the web. Its look is yours. In Rust, the dialog is presented while it is in the view (inside a `when`) and its children fill it: draw the backdrop and the popup as views. In TSX, `class` and `style` style the popup that holds its children, `backdropClass` or `backdropStyle` add a backdrop behind it, and `open` controls it:

```rust
use nsh_base::dialog;
use nsh_core::prelude::*;

pub fn files() -> impl IntoElement {
    let open = signal(false);
    view()
        .flex_1()
        .child(view().on_press(move || open.set(true)).p(px(16.0)).child(text("Delete the file")))
        .child(when(
            move || open.get(),
            move || {
                dialog()
                    .animation(ModalAnimation::Fade)
                    // Escape, Android's back button, a swipe down on a sheet.
                    .on_cancel(move || open.set(false))
                    .child(
                        // The backdrop and the popup are the app's views.
                        view()
                            .flex_1()
                            .bg(rgba(0x00000066))
                            .items_center()
                            .justify_center()
                            .on_press(move || open.set(false))
                            .child(
                                view()
                                    .w(px(320.0))
                                    .gap_3()
                                    .rounded_2xl()
                                    .bg(white())
                                    .p_5()
                                    .on_press(|| {})
                                    .child(text("Delete the file?").text_size(px(20.0)).font_weight(FontWeight::BOLD))
                                    .child(
                                        view()
                                            .on_press(move || open.set(false))
                                            .child(text("Delete").text_color(rgb(0xcf222e))),
                                    ),
                            ),
                    )
            },
        ))
}
```

```tsx
import { signal, Text, View } from "nsh";
import { Dialog } from "nsh/base";

function Files() {
  const open = signal(false);
  return (
    <View style={{ flex: 1 }}>
      <View onPress={() => open.set(true)} style={{ padding: 16 }}>
        <Text>Delete the file</Text>
      </View>
      <Dialog
        open={open()}
        animation="fade"
        onOpenChange={(e) => open.set(e.open)}
        backdropClass="bg-black/40"
        class="m-auto w-80 gap-3 rounded-2xl bg-white p-5"
      >
        <Text style={{ fontSize: 20, fontWeight: "700" }}>Delete the file?</Text>
        <View onPress={() => open.set(false)}>
          <Text style={{ color: "#cf222e" }}>Delete</Text>
        </View>
      </Dialog>
    </View>
  );
}
```

Escape, Android's back button, a press on the backdrop (TSX's backdrop, a native sheet's in Rust) and a swipe down on a sheet close it natively (`close_on_escape`, `close_on_backdrop_press` and `close_on_swipe`, TSX `closeOnEscape`, `closeOnBackdropPress` and `closeOnSwipe`, each true by default). In Rust, `on_cancel` reports every attempt and `on_close` the close, so leave the dialog out of the view there; a backdrop your app draws closes it with its own press handler, as above. In TSX, `onOpenChange({ open: false, reason })` tells you, so set `open` to `false` there. To confirm first, set a flag to false and handle the cancel event (`on_cancel`, `onCancel`), which reports every attempt, then close the dialog yourself. On iOS, `.presentation(ModalPresentation::PageSheet)` or `FormSheet` (`presentation="pageSheet"` or `"formSheet"`) presents a sheet that keeps what is behind visible.

See [Dialog](https://nsh.dev/versions/main/elements/dialog.md) for every prop. Inside a dialog, the `env(safe-area-inset-*)` variables and the insets are the dialog's own. For system dialogs (an alert with actions, an action sheet) use [`AlertDialog`](https://nsh.dev/versions/main/modules/nsh-base.md#alertdialog) from `nsh_base` (TSX: `nsh/base`).

## The Android back button

On Android, the back button (or gesture) is handled in this order:

1. The top dialog: it reports the cancel (`on_cancel`, `onCancel`), and closes while `close_on_escape` / `closeOnEscape` is true (the default).
2. Your back listeners (`on_back_press` in Rust, `BackHandler` from `nsh/mobile` in TSX), most recently added first.
3. The top stack: its top page reports the back press, and pops while `pop_on_back` / `popOnBack` is true.
4. Nothing handled it: the app exits.

A listener returns `true` when it handled the press, which keeps the stack from popping. While a listener is registered,
Android's back gesture does not preview the pop (the app answers only once the gesture ends), so add listeners only
while they may take the press:

```rust
use nsh_core::prelude::*;

pub fn editor() -> impl IntoElement {
    let selecting = signal(false);
    // Listening only while selecting: otherwise the stack pops, with the gesture's preview.
    effect(move || {
        if selecting.get() {
            on_back_press(move || {
                selecting.set(false);
                true
            });
        }
    });
    // …
    view()
}
```

```tsx
import { effect, signal } from "nsh";
import { BackHandler } from "nsh/mobile";

function Editor() {
  const selecting = signal(false);
  // Listening only while selecting: otherwise the stack pops, with the gesture's preview.
  effect(() => {
    if (selecting()) {
      BackHandler.on("press", () => {
        selecting.set(false);
        return true;
      });
    }
  });
  // …
}
```

A listener made in an effect lasts until the effect runs again or its component goes; in TSX, the function
`BackHandler.on` returns also stops it. In TSX, `BackHandler.exitApp()` leaves the app; `nsh/mobile` can be imported on iOS too, where `BackHandler`'s calls return at once, so the same code runs on both platforms. See [Platform-specific code](https://nsh.dev/versions/main/docs/platform-specific.md).

## Tabs and other layouts

A tab bar is your own UI, drawn from primitives: a row of pressable views and a signal holding the selected tab; render the selected tab's content with [`when` / `<If>`](https://nsh.dev/versions/main/elements/control-flow.md) (or a function child in TSX). To keep each tab's state while switching, give each tab its own stack and routes and keep all of them mounted, hiding the inactive ones with `display: none`.

## Related

- [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md): the `nav_stack`, `nav_page`, `dialog`, `createNavStack`, `NavStack`, `NavPage` and `Dialog` reference; [Safe area](https://nsh.dev/versions/main/elements/safe-area.md) for the insets.
- [The status bar](https://nsh.dev/versions/main/modules/nsh-base.md#status-bar) of pages and dialogs.
- [`AlertDialog`](https://nsh.dev/versions/main/modules/nsh-base.md#alertdialog).
- [`BackHandler`](https://nsh.dev/versions/main/modules/nsh-mobile.md#backhandler): `BackHandler`.

Source: https://nsh.dev/versions/main/docs/navigation

---

# Forms and the keyboard

Text entry is the input element, `input()` in Rust and `<Input>` in TSX: a UITextField or UITextView on iOS, an EditText on Android. Typing, the caret, selection, autocorrection and autofill are the platform's own; your app gets the text through events and can control it. NSH also keeps focused inputs above the software keyboard on its own, and gives you the keyboard's height as a reactive value for the cases it cannot handle by itself.

An input takes styles like any view (typed style methods in Rust, styles and Tailwind classes in TSX), so the fields of a form have your app's own look. A labeled field is a short component of your own:

```rust
use nsh_core::prelude::*;

fn field(label: &'static str, value: Signal<String>, masked: bool) -> impl IntoElement {
    let focused = signal(false);
    view()
        .gap_1()
        .child(text(label).text_sm().text_color(rgb(0x737373)))
        .child(
            input()
                .value(move || value.get())
                .on_change(move |text: &str| value.set(text.to_owned()))
                .masked(masked)
                .on_focus(move || focused.set(true))
                .on_blur(move || focused.set(false))
                .rounded_lg()
                .border_1()
                .px_3()
                .py_2()
                .text_base()
                .border_color(move || if focused.get() { rgb(0x0969da) } else { rgb(0xd0d7de) }),
        )
}
```

```tsx
import { signal, Text, View } from "nsh";
import { Input } from "nsh/base";

function Field(props: { label: string; value: string; onChange: (e: { value: string }) => void; masked?: boolean }) {
  const focused = signal(false);
  return (
    <View class="gap-1">
      <Text class="text-sm text-neutral-500">{props.label}</Text>
      <Input
        value={props.value}
        onChange={props.onChange}
        masked={props.masked}
        onFocus={() => focused.set(true)}
        onBlur={() => focused.set(false)}
        class="rounded-lg border px-3 py-2 text-base"
        style={{ borderColor: focused() ? "#0969da" : "#d0d7de" }}
      />
    </View>
  );
}
```

## Controlled and uncontrolled inputs

An input is **controlled** when you pass its value (`.value(..)`, TSX `value`): it shows what your signal holds, and you update the signal from the change event (`.on_change(..)`, TSX `onChange`).

```rust
use nsh_core::prelude::*;

#[component]
pub fn App() -> impl IntoElement {
    let name = signal(String::new());
    view()
        .flex_1()
        .p(px(16.0))
        .pt(px(60.0))
        .gap(px(8.0))
        .child(
            input()
                .value(move || name.get())
                .on_change(move |text: &str| name.set(text.to_owned()))
                .placeholder("Your name")
                .text_size(px(17.0))
                .border_1()
                .border_color(rgb(0xd0d7de))
                .rounded(px(10.0))
                .p(px(12.0)),
        )
        .child(text(move || {
            let name = name.get();
            format!("Hello, {}", if name.is_empty() { "stranger" } else { &name })
        }))
}
```

```tsx
import { mount, signal, Text, View } from "nsh";
import { Input } from "nsh/base";

function App() {
  const name = signal("");
  return (
    <View style={{ flex: 1, padding: 16, paddingTop: 60, gap: 8 }}>
      <Input
        value={name()}
        onChange={({ value }) => name.set(value)}
        placeholder="Your name"
        style={{ fontSize: 17, borderWidth: 1, borderColor: "#d0d7de", borderRadius: 10, padding: 12 }}
      />
      <Text>Hello, {name() || "stranger"}</Text>
    </View>
  );
}

mount(App);
```

Because you control the value, you can transform what the user types: `.on_change(move |t: &str| tag.set(t.to_uppercase()))` uppercases, `onChange={({ value }) => code.set(value.replace(/[^0-9]/g, ""))}` keeps digits only.

### Input methods

Chinese, Japanese and Korean input methods compose text before committing it: pinyin turns into 腾 once a character is chosen. `onCompositionChange` (Rust `.on_composition_change(..)`) reports the composition as it goes, `{ composing: true, text: "teng" }` while the user types and `{ composing: false, text: "" }` when it ends; the committed text reaches `onChange` before the end. On iOS, Android, macOS and the web, `onChange` also reports the text being composed, as those systems keep it in the input; on Windows, Linux and GPUI it reports the committed text. A controlled input keeps the composition going whatever the app does with the value: a `value` set while the user composes is shown once the composition ends, so an input that uppercases or filters its text takes pinyin as typed.

A search box that searches the committed text only:

```rust
let query = signal(String::new());
let composing = signal(false);
input()
    .value(move || query.get())
    .on_change(move |text: &str| {
        query.set(text.to_owned());
        if !composing.get() {
            search(text);
        }
    })
    .on_composition_change(move |e: &Composition| {
        composing.set(e.composing);
        if !e.composing {
            search(&query.get());
        }
    })
```

```tsx
const query = signal("");
let composing = false;
<Input
  value={query()}
  onChange={({ value }) => {
    query.set(value);
    if (!composing) search(value);
  }}
  onCompositionChange={(e) => {
    composing = e.composing;
    if (!e.composing) search(query());
  }}
/>
```

An input is **uncontrolled** without a value: it keeps its own text, starting at its default value (`.default_value(..)`, TSX `defaultValue`), and you read it from the change or submit event when you need it. Use this for fields you only read on submit, such as a password.

> [!NOTE]
> A controlled input never loses keystrokes. Every native edit carries an edit count, and a `value` coming back from JS is applied only if it answers the latest edit. If JS is slow and the user has typed more in the meantime, the stale value is dropped instead of overwriting the newer text.

## Props

In Rust, each prop is a method of `input()` named in snake case (`.placeholder(..)`, `.masked(true)`, `.max_length(6)`, `.return_key_type(ReturnKeyType::Next)`, `.selected_range((0, 4))`), with these names of their own: `.keyboard_type(KeyboardType::Email)` and the other `KeyboardType` variants, `.auto_fill(AutoFill::Email)` for `autoComplete`, `.keyboard_appearance(..)` and `.input_accessory(..)` for the `ios={{ … }}` props. Each event is an `on_` method: `.on_change(|text: &str| ..)`, `.on_submit(|text: &str| ..)`, `.on_focus(..)`, `.on_blur(..)`, `.on_selection_change(|s: &Selection| ..)`, `.on_key_press(|key: &str| ..)`, `.on_content_size_change(|size: &Size<Points>| ..)`.

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` | `string` | | The text, controlled by JS. |
| `defaultValue` | `string` | | The initial text of an uncontrolled input. |
| `placeholder` | `string` | | Shown while the input is empty. |
| `masked` | `boolean` | `false` | Hides the text (passwords). |
| `keyboardType` | `KeyboardType` | `"default"` | The keyboard layout. |
| `returnKeyType` | `ReturnKeyType` | `"default"` | The return key's label. |
| `autoCapitalize` | `"none" \| "sentences" \| "words" \| "characters"` | `"sentences"` | Automatic capitalization. |
| `autoCorrect` | `boolean` | `true` | The system's corrections. |
| `autoComplete` | `AutoComplete` | | What the input holds, for autofill. |
| `multiline` | `boolean` | `false` | Several lines; return inserts a line break unless `submitBehavior` says otherwise. |
| `maxLength` | `number` | | The most characters the user can enter. |
| `readonly` | `boolean` | `false` | The user can select and copy the text but not change it. |
| `autoFocus` | `boolean` | `false` | Focused when it appears. |
| `submitBehavior` | `"submit" \| "blurAndSubmit" \| "newline"` | single line `"blurAndSubmit"`, multiline `"newline"` | What return does: submit and keep the focus, submit and unfocus, or insert a line break (multiline only). |
| `pasteBehavior` | `"insert" \| "report"` | `"insert"` | What a paste does: insert its text, or nothing ([pasting](#pasting-images-and-files)). |
| `caret` | `boolean` | `true` | The caret is drawn; `false` hides it. |
| `ios={{ keyboardAppearance }}` | `"default" \| "light" \| "dark"` | `"default"` | The keyboard's look (iOS). |
| `selectedRange` | `{ start: number; end?: number }` | | The controlled selection, in UTF-16 units. |
| `allowFontScaling` | `boolean` | `true` | Follow the system text size. |
| `maxFontSizeMultiplier` | `number` | | The upper bound of the system scale (0: none). |
| `ios={{ inputAccessoryViewID }}` | `string` | | iOS: the bar shown over the keyboard (see below). |
| `ios={{ textContentType }}` | `TextContentType` | | iOS's names for `autoComplete` values. |

Events:

| Event | Payload | When |
|---|---|---|
| `onChange` | `{ value }` | The text changed: `value` is the text now. |
| `onSubmit` | `{ text }` | The return key was pressed in an input that submits (single line, or `submitBehavior` `"submit"` / `"blurAndSubmit"`). |
| `onFocus` / `onBlur` | | The input gained / lost focus. |
| `onSelectionChange` | `{ start, end }` | The caret or selection moved (UTF-16 units). |
| `onPaste` | `{ text, html, files, uris }` | The user pasted: text, its HTML (Linux, web), images as `File`s, local files' URLs ([pasting](#pasting-images-and-files)). |
| `onCaretMove` | `{ bounds, pageBounds }` | The caret moved: where it is in the input and in the window ([the caret](#the-caret)). |
| `onKeyPress` | `{ key }` | Before the text changes: `key` is the typed text, `"Backspace"` or `"Enter"`. |
| `onContentSizeChange` | `{ size }` | The text's size (`size`) changed (at the input's width when multiline), as it is typed; an empty input reports one empty line, whatever its placeholder. |
| `onCompositionChange` | `{ composing, text }` | An input method's composition started, changed or ended (see [Input methods](#input-methods)). |

An input is styled like text: `fontSize`, `color`, `fontFamily`, `textAlign`, `letterSpacing` and the rest of [text styles](https://nsh.dev/versions/main/docs/text.md), plus borders, padding and backgrounds. The focus style (`.focus(|s| ..)` in Rust, the `focus:` Tailwind variant or `focusStyle` in TSX) applies while the input has focus. The placeholder's color is `.placeholder_color(..)` (the
`placeholderColor` style key, `placeholder:text-*`), the caret's is `.caret_color(..)` (`caretColor`, `caret-*`), and the selection highlight's is `.selection_color(..)`
(`selectionColor`, `selection:text-*`); UIKit tints the caret and the selection with one color, the caret's when set:

```rust
input()
    .placeholder("Search")
    .rounded_lg()
    .border_1()
    .border_color(rgb(0xd4d4d8))
    .px_3()
    .py_2()
    .text_base()
    .focus(|s| s.border_color(rgb(0x3b82f6)))
    .placeholder_color(rgb(0xa1a1aa))
    .selection_color(rgb(0x2563eb))
```

```tsx
<Input
  class="rounded-lg border border-zinc-300 px-3 py-2 text-base focus:border-blue-500 placeholder:text-zinc-400 selection:text-blue-600"
  placeholder="Search"
/>
```

## Keyboards and autofill

The keyboard type (`.keyboard_type(..)`, TSX `keyboardType`) picks the layout:

| Rust | TSX | Keyboard |
|---|---|---|
| `KeyboardType::Default` | `"default"` | Text. |
| `KeyboardType::Email` | `"email-address"` | Text with `@` and `.` at hand. |
| `KeyboardType::Url` | `"url"` | Text with `/` and `.com`. |
| `KeyboardType::Number` | `"number-pad"` | Digits only: no sign, no decimal separator (codes, PINs). |
| `KeyboardType::Decimal` | `"decimal-pad"` | Digits and a decimal separator. |
| `KeyboardType::Numeric` | `"numeric"` | As React Native: iOS's decimal pad; on Android digits with a sign and a decimal separator. |
| `KeyboardType::NumbersAndPunctuation` | `"numbers-and-punctuation"` | Digits, a minus sign and punctuation (iOS's numbers and punctuation keyboard; on Android digits with a sign and a decimal separator). Use it for negative numbers on iOS. |
| `KeyboardType::Phone` | `"phone-pad"` | A phone dial pad. |

On iOS, `.keyboard_appearance(KeyboardAppearance::Dark)` (TSX `ios={{ keyboardAppearance: "dark" }}`; or light, default) gives the keyboard a light or dark look regardless of the system's appearance, for a dark app in light mode. Android's keyboards always follow the system's theme.

Autofill (`.auto_fill(AutoFill::Email)`, TSX `autoComplete`) tells the system what the field holds, so it can offer saved names, addresses, passwords and one-time codes from messages. Rust's `AutoFill` has a variant per kind (`Name`, `GivenName`, `FamilyName`, `Email`, `Tel`, `Username`, `Password`, `NewPassword`, `OneTimeCode`, `StreetAddress`, `PostalCode`, `Country`, `CreditCardNumber`, `Url`, `Birthdate`, ..., and `Off`). TSX takes these values: `"name"`, `"given-name"`, `"family-name"`, `"email"`, `"tel"`, `"username"`, `"current-password"`, `"new-password"`, `"one-time-code"`, `"street-address"`, `"postal-code"`, `"country"`, `"cc-number"`, `"cc-exp"`, `"cc-csc"`, `"url"`, `"birthdate-full"` and others, or `"off"`; iOS's own names (`"emailAddress"`, `"oneTimeCode"`, ...) are accepted too, in `autoComplete` or `ios={{ textContentType }}`.

```rust
use nsh_core::element::AutoFill;

input()
    .keyboard_type(KeyboardType::Email)
    .auto_capitalize(AutoCapitalize::None)
    .auto_correct(false)
    .auto_fill(AutoFill::Email)
    .placeholder("E-mail")
input().masked(true).auto_fill(AutoFill::NewPassword).placeholder("Password")
input()
    .keyboard_type(KeyboardType::Number)
    .auto_fill(AutoFill::OneTimeCode)
    .max_length(6)
    .placeholder("Code")
```

```tsx
<Input keyboardType="email-address" autoCapitalize="none" autoCorrect={false} autoComplete="email" placeholder="E-mail" />
<Input masked autoComplete="new-password" placeholder="Password" />
<Input keyboardType="number-pad" autoComplete="one-time-code" maxLength={6} placeholder="Code" />
```

## The return key and moving between fields

The return key type (`.return_key_type(ReturnKeyType::Next)`, TSX `returnKeyType`) labels the return key: default, done, go, next, search or send. The submit behavior (`.submit_behavior(..)`, TSX `submitBehavior`) says what pressing it does:

| Rust | TSX | Return | Default for |
|---|---|---|---|
| `SubmitBehavior::BlurAndSubmit` | `"blurAndSubmit"` | fires the submit event, then the input loses focus | single-line inputs |
| `SubmitBehavior::Submit` | `"submit"` | fires the submit event; the input keeps focus | |
| `SubmitBehavior::Newline` | `"newline"` | inserts a line break (multiline inputs only) | multiline inputs |

A multiline input with `"submit"` or `"blurAndSubmit"` sends on return, as chat composers do, and still wraps its lines; on a hardware keyboard (desktops, a Mac, a tablet's keyboard) Shift+Return or Option / Alt+Return inserts a line break. A return that commits an input method's composition (Chinese or Japanese input, say) only commits it and never submits.

To move to the next field, keep refs to the inputs (`element_ref()` and `.element_ref(&r)` in Rust, `ref` in TSX) and call `focus()`:

```rust
use nsh_core::prelude::*;

pub fn sign_in() -> impl IntoElement {
    let email = signal(String::new());
    let password = element_ref();
    let submit = move || log::info!("sign in {}", email.get());
    view()
        .flex_1()
        .p(px(16.0))
        .pt(px(60.0))
        .gap(px(12.0))
        .child(
            input()
                .value(move || email.get())
                .on_change(move |t: &str| email.set(t.to_owned()))
                .keyboard_type(KeyboardType::Email)
                .auto_capitalize(AutoCapitalize::None)
                .return_key_type(ReturnKeyType::Next)
                .submit_behavior(SubmitBehavior::Submit)
                .on_submit(move |_: &str| password.focus())
                .placeholder("E-mail"),
        )
        .child(
            input()
                .element_ref(&password)
                .masked(true)
                .return_key_type(ReturnKeyType::Go)
                .on_submit(move |_: &str| submit())
                .placeholder("Password"),
        )
}
```

```tsx
import { type InputRef, mount, signal, View } from "nsh";
import { Input } from "nsh/base";

function SignIn() {
  const email = signal("");
  let password!: InputRef;
  const submit = () => console.log("sign in", email());
  return (
    <View style={{ flex: 1, padding: 16, paddingTop: 60, gap: 12 }}>
      <Input
        value={email()}
        onChange={({ value }) => email.set(value)}
        keyboardType="email-address"
        autoCapitalize="none"
        returnKeyType="next"
        submitBehavior="submit"
        onSubmit={() => password.focus()}
        placeholder="E-mail"
      />
      <Input ref={password} masked returnKeyType="go" onSubmit={submit} placeholder="Password" />
    </View>
  );
}

mount(SignIn);
```

Submitting without blurring (`SubmitBehavior::Submit`, `submitBehavior="submit"`) on the first field keeps the keyboard up while focus moves, so it does not drop and rise again. A chat input that sends on return and stays focused submits the same way (see the composer [below](#content-outside-scroll-views)).

Both the maximum length and the submit behavior are enforced natively: the platform asks "may this character be added?" and "should return end editing?" as the user types, and NSH answers from the props without waiting for JS.

## Focus from code

An input's ref has:

| Rust | TSX | Description |
|---|---|---|
| `focus()` | `focus()` | Focuses the input and shows the keyboard. |
| `blur()` | `blur()` | Unfocuses it. |
| `set_selection(start, end)` | `setSelection(start, end?)` | Selects `start..end` (UTF-16 units); a caret when they are equal (TSX: without `end`). |

On macOS and the web, `focus()` and `blur()` on the ref of a view that takes presses move the keyboard focus as Tab does ([keyboard focus](https://nsh.dev/versions/main/elements.md#keyboard-focus)).

`dismiss_keyboard()` in Rust and `Keyboard.dismiss()` from `nsh` in TSX unfocus whichever input has focus:

```rust
view().on_press(|| dismiss_keyboard())
```

```tsx
import { View, Keyboard } from "nsh";

<View onPress={() => Keyboard.dismiss()}>…</View>
```

## Selection

The selection event (`.on_selection_change(..)`, TSX `onSelectionChange`) reports the caret and selection; the ref's `set_selection` or the selected range (`.selected_range(..)`, TSX `selectedRange`) set them. Positions are UTF-16 code units, as JavaScript string indices are, so in TSX `text.slice(start, end)` is the selected text; in Rust, slice the text's UTF-16 units.

```rust
/// `start..end` of `text` in UTF-16 units, as inputs count.
fn utf16_slice(text: &str, start: u32, end: u32) -> String {
    let units: Vec<u16> = text.encode_utf16().collect();
    let end = (end as usize).min(units.len());
    String::from_utf16_lossy(&units[(start as usize).min(end)..end])
}

let content = signal("Select part of this text".to_owned());
let range = signal(Selection::default());
let field = element_ref();

view()
    .child(
        input()
            .element_ref(&field)
            .value(move || content.get())
            .on_change(move |t: &str| content.set(t.to_owned()))
            .on_selection_change(move |r: &Selection| range.set(*r)),
    )
    .child(text(move || {
        let r = range.get();
        format!("Selected: \"{}\"", content.with(|t| utf16_slice(t, r.start, r.end)))
    }))
    .child(
        view()
            .on_press(move || {
                let len = content.with(|t| t.encode_utf16().count()) as u32;
                field.set_selection(0, len);
            })
            .child(text("Select all")),
    )
```

```tsx
const text = signal("Select part of this text");
const range = signal({ start: 0, end: 0 });
const selection = signal<{ start: number; end?: number } | undefined>(undefined);

<Input
  value={text()}
  onChange={({ value }) => text.set(value)}
  selectedRange={selection()}
  onSelectionChange={(r) => range.set(r)}
/>
<Text>Selected: "{text().slice(range().start, range().end)}"</Text>
<View onPress={() => selection.set({ start: 0, end: text().length })}><Text>Select all</Text></View>
```

## The caret

The caret event (`.on_caret_move(..)`, TSX `onCaretMove`) says where the caret is, so that what belongs at the
caret can open there: suggestions for an `@` mention, a slash command's menu, an emoji picker. `bounds` is a `Bounds`
in the input (`origin` and `size`, the input's padding and scrolling applied), as wide as the platform draws the
caret and as tall as its line; `pageBounds` is the same box in the window (or the dialog the input is in), which an
overlay takes as its `anchor`. The event comes while the input has the focus, whenever the caret moves: with the
selection, and when the input's text scrolls or wraps onto other lines. In Rust an overlay is placed against a box
with `.anchor_bounds(..)`.

```rust
let draft = signal(String::new());
let end = signal(0u32);
let caret = signal(None::<Bounds<Points>>);

view()
    .child(
        input()
            .multiline(true)
            .value(move || draft.get())
            .on_change(move |t: &str| draft.set(t.to_owned()))
            .on_selection_change(move |s: &Selection| end.set(s.end))
            .on_caret_move(move |e: &CaretEvent| {
                // Suggestions while the word before the caret starts with "@".
                let typed = draft.with(|t| utf16_slice(t, 0, end.get()));
                let word = typed.rsplit(char::is_whitespace).next().unwrap_or("");
                caret.set(word.starts_with('@').then_some(e.page_bounds));
            })
            .p_2(),
    )
    .child(when(
        move || caret.get().is_some(),
        move || {
            overlay()
                .anchor_bounds(move || caret.get().unwrap_or_default())
                .placement(Placement::Bottom)
                .align(Align::Start)
                .offset(px(4.0))
                .child(text("@ada"))
                .child(text("@grace"))
        },
    ))
```

```tsx
import { type Bounds, Overlay, Text, View, signal } from "nsh";
import { Input } from "nsh/base";

const draft = signal("");
const end = signal(0);
const caret = signal<Bounds | null>(null);

<View>
  <Input
    multiline
    value={draft()}
    onChange={({ value }) => draft.set(value)}
    onSelectionChange={(e) => end.set(e.end)}
    onCaretMove={(e) => {
      // Suggestions while the word before the caret starts with "@".
      const word = draft().slice(0, end()).split(/\s/).pop() ?? "";
      caret.set(word.startsWith("@") ? e.pageBounds : null);
    }}
    class="p-2"
  />
  <If when={caret()}>
    <Overlay anchor={caret()} placement="bottom" align="start" offset={4}>
      <Text>@ada</Text>
      <Text>@grace</Text>
    </Overlay>
  </If>
</View>;
```

`pageBounds` is where the caret was when the event came: a page that scrolls under the input moves the input but
sends no event, so close the suggestions when it scrolls, or anchor them to the input itself.

## Pasting images and files

The paste event (`.on_paste(..)`, TSX `onPaste`) tells what the user pasted, from the keyboard's shortcut, a menu's
Paste or a keyboard's image: `text`, `html`, `files` and `uris`. `html` is the same content with its formatting, as a
browser, an office suite or a rich text editor copied it (on Linux and the web). `files` are what the clipboard held as data, such as a
screenshot or an image copied from a page or another app: `File`s whose bytes the app can upload or show, named
`image.png` (or the type it is). `uris` are the `file:` URLs of files copied in a file manager, as a file drop's.
The platform reads the clipboard as the user pastes, and only then.

The input inserts the pasted text by itself, as it always does: the event comes before the `onChange` of that text.
Images and files are never inserted, since an input holds text. With `pasteBehavior` `"report"` the input inserts
nothing, and the app decides what a paste does: send a long text as an attachment, or insert a cleaned-up version.
The input decides at once, from the prop, because the system asks it on the spot.

```rust
let attachments = signal(Vec::<PastedFile>::new());

input()
    .multiline(true)
    .placeholder("Message")
    .on_paste(move |e: &PasteEvent| {
        // A screenshot pasted into the message goes along as an image.
        attachments.update(|a| a.extend(e.files.iter().cloned()));
    })
    .p_2()
```

```tsx
import { signal } from "nsh";
import { Input } from "nsh/base";

const attachments = signal<File[]>([]);

<Input
  multiline
  placeholder="Message"
  onPaste={(e) => {
    // A screenshot pasted into the message goes along as an image.
    attachments.update((a) => [...a, ...e.files]);
  }}
  class="p-2"
/>;
```

Upload a pasted file as any `File`, with `fetch` and `FormData` (`form.append("image", file)`); its bytes stay
native until they are sent. On Android, keyboards that insert images (GIFs, stickers) report them the same way. On
Linux the clipboard is read asynchronously, so the event may come after the `onChange` of the text it inserts.
Masked inputs on macOS keep AppKit's own paste and report nothing.

## Multiline inputs that grow

A multiline input (`.multiline(true)`, TSX `multiline`) scrolls its text inside its own height. To grow it with its content, feed the content size event's height (`.on_content_size_change(..)`, TSX `onContentSizeChange`) back into its style, with a limit:

```rust
let height = signal(px(0.0));

input()
    .multiline(true)
    .placeholder("Write a comment")
    .on_content_size_change(move |e: &Size<Points>| height.set(e.height.min(px(120.0))))
    .text_size(px(16.0))
    .p(px(10.0))
    .border_1()
    .border_color(rgb(0xd0d7de))
    .rounded(px(10.0))
    .h(move || height.get().max(px(20.0)) + px(20.0))
```

```tsx
const height = signal(0);

<Input
  multiline
  placeholder="Write a comment"
  onContentSizeChange={({ size }) => height.set(Math.min(size.height, 120))}
  style={{ fontSize: 16, padding: 10, borderWidth: 1, borderColor: "#d0d7de", borderRadius: 10, height: Math.max(height(), 20) + 20 }}
/>
```

The reported height is the text's (at the input's width), so add the vertical padding yourself, as above.

## Keeping inputs above the keyboard

### Inside scroll views: automatic

When the keyboard appears over a focused input that is inside a scroll view or a list, NSH gives the scroll view a bottom inset as tall as the keyboard and scrolls the input into view. This is native and needs no code. A long form is simply a scroll view of inputs:

```rust
scroll()
    .flex_1()
    .keyboard_dismiss_mode(KeyboardDismissMode::OnDrag)
    .keyboard_taps(KeyboardTaps::Handled)
    .child(view().p(px(16.0)).gap(px(12.0)) /* inputs */)
```

```tsx
<Scroll style={{ flex: 1 }} keyboardDismissMode="on-drag" keyboardShouldPersistTaps="handled">
  <View style={{ padding: 16, gap: 12 }}>
    {/* inputs */}
  </View>
</Scroll>
```

The dismiss mode (`.keyboard_dismiss_mode(..)`, TSX `keyboardDismissMode`: none, on drag, interactive) lets dragging the form hide the keyboard; handled taps (`.keyboard_taps(KeyboardTaps::Handled)`, TSX `keyboardShouldPersistTaps="handled"`) let a tap on a button go through while the keyboard is up instead of only dismissing it. See [Scrolling](https://nsh.dev/versions/main/docs/scrolling.md#scroll-views-and-the-keyboard).

### Content outside scroll views

On iOS, when the keyboard would cover a focused input that is in no scroll view, NSH moves the content of its screen (or dialog) up until the input is just above the keyboard, along the keyboard's curve, and back down when the keyboard hides or the input loses focus, as SwiftUI does (on Android, a window in `adjustPan` mode is panned by the system). It only does so for what the app's own layout leaves covered: an app that makes room itself, as below, is not moved again.

That moves the whole page. A message bar pinned to the bottom of a screen should ride on the keyboard while the content above it shrinks instead: pad the screen's bottom by CSS's `env(keyboard-inset-height)` (`paddingBottom: "env(keyboard-inset-height)"`, Tailwind `pb-[env(keyboard-inset-height)]`, Rust `.pb_keyboard()`): it makes room at the bottom as tall as the keyboard, animated natively with the keyboard.

```rust
use nsh_core::prelude::*;

pub fn chat_screen() -> impl IntoElement {
    let draft = signal(String::new());
    let send = move || {
        let text = draft.get();
        if !text.trim().is_empty() {
            log::info!("send {text}");
        }
        draft.set(String::new());
    };
    view()
        .flex_1()
        .pb_keyboard()
        .child(scroll().flex_1().keyboard_dismiss_mode(KeyboardDismissMode::Interactive) /* messages */)
        .child(
            view()
                .flex_row()
                .p(px(8.0))
                // Above the home indicator, unless the keyboard covers it.
                .pb(move || {
                    px(8.0) + if keyboard_height() > px(0.0) { px(0.0) } else { safe_area().bottom }
                })
                .child(
                    input()
                        .value(move || draft.get())
                        .on_change(move |t: &str| draft.set(t.to_owned()))
                        .multiline(true)
                        .submit_behavior(SubmitBehavior::Submit)
                        .return_key_type(ReturnKeyType::Send)
                        .on_submit(move |_: &str| send())
                        .placeholder("Message")
                        .flex_1()
                        .max_h(px(120.0)),
                ),
        )
}
```

```tsx
import { Scroll, signal, View, keyboardFrame, safeAreaInsets } from "nsh";
import { Input } from "nsh/base";

function ChatScreen() {
  const insets = safeAreaInsets();
  const draft = signal("");
  const send = () => {
    if (draft().trim()) console.log("send", draft());
    draft.set("");
  };
  return (
    <View style={{ flex: 1, paddingBottom: "env(keyboard-inset-height)" }}>
      <Scroll style={{ flex: 1 }} keyboardDismissMode="interactive">
        {/* messages */}
      </Scroll>
      <View
        style={{
          flexDirection: "row",
          padding: 8,
          // Above the home indicator, unless the keyboard covers it.
          paddingBottom: 8 + (keyboardFrame().height > 0 ? 0 : insets().bottom),
        }}
      >
        <Input
          value={draft()}
          onChange={({ value }) => draft.set(value)}
          multiline
          submitBehavior="submit"
          returnKeyType="send"
          onSubmit={send}
          placeholder="Message"
          style={{ flex: 1, maxHeight: 120 }}
        />
      </View>
    </View>
  );
}
```

Padding (`.pb_keyboard()`) shrinks the content above while the background reaches the bottom of the screen; a bottom margin (`marginBottom: "env(keyboard-inset-height)"`, `.mb_keyboard()`) ends the whole view at the top of the keyboard. `calc(env(keyboard-inset-height) + <length>)` (Rust `.pb_keyboard_plus(..)`, `.mb_keyboard_plus(..)`) adds a length, such as minus the height of a tab bar below the view.

The full height suits a view that reaches the bottom of the surface, as a screen's content does. On an Android host whose window resizes for the keyboard, the window itself shrinks and the variable is 0. See [Keyboard](https://nsh.dev/versions/main/elements/keyboard.md).

### The keyboard accessor

`keyboard_height()` and `keyboard_duration()` in Rust, and `keyboardFrame()` from `nsh` in TSX (a `{ height, duration }`), are reactive: how far the keyboard reaches into the surface (0 when hidden; the bottom safe area under it included) and its animation's duration in milliseconds. Read them for anything custom: hide a floating button while typing, or size a panel. What changes with them in the update the keyboard's move starts moves with the keyboard, on its curve and timed from when it started to move (`LayoutCurve::Keyboard`), as `env(keyboard-inset-height)` does; an animation the app configures for that update (`LayoutAnimation.configureNext`) wins.

```rust
view().child(when(
    || keyboard_height() == px(0.0),
    || view().absolute().right(px(16.0)).bottom(px(16.0)), /* … */
))
```

```tsx
import { View, keyboardFrame } from "nsh";

<If when={keyboardFrame().height === 0}>
  <View style={{ position: "absolute", right: 16, bottom: 16 }}>…</View>
</If>
```

## A bar over the keyboard (iOS): InputAccessoryView

`input_accessory_view(id)` in Rust and `InputAccessoryView` from `nsh/mobile` in TSX show a bar attached to the top of the keyboard while an input that names it has focus: iOS's `inputAccessoryView`. It moves with the keyboard natively, including during interactive dismissal. It takes no room where it is placed in the tree; inputs refer to it by its id (`.input_accessory(id)`, TSX `ios={{ inputAccessoryViewID }}` and `nativeID`):

```rust
use nsh_core::prelude::*;

pub fn note() -> impl IntoElement {
    let content = signal(String::new());
    let field = element_ref();
    view()
        .p(px(16.0))
        .child(
            input()
                .element_ref(&field)
                .value(move || content.get())
                .on_change(move |t: &str| content.set(t.to_owned()))
                .input_accessory("note-bar")
                .placeholder("A note"),
        )
        .child(
            input_accessory_view("note-bar").bg(rgb(0xf6f8fa)).child(
                view()
                    .flex_row()
                    .items_center()
                    .p(px(8.0))
                    .child(
                        text(move || format!("{} characters", content.with(|t| t.chars().count())))
                            .flex_1()
                            .text_color(rgb(0x57606a)),
                    )
                    .child(
                        text("Done")
                            .on_press(move || field.blur())
                            .text_color(rgb(0x0969da))
                            .font_weight(FontWeight::SEMIBOLD),
                    ),
            ),
        )
}
```

```tsx
import { type InputRef, signal, Text, View } from "nsh";
import { Input } from "nsh/base";
import { InputAccessoryView } from "nsh/mobile";

function Note() {
  const text = signal("");
  let input!: InputRef;
  return (
    <View style={{ padding: 16 }}>
      <Input
        ref={input}
        value={text()}
        onChange={({ value }) => text.set(value)}
        ios={{ inputAccessoryViewID: "note-bar" }}
        placeholder="A note"
      />
      <InputAccessoryView nativeID="note-bar" style={{ backgroundColor: "#f6f8fa" }}>
        <View style={{ flexDirection: "row", alignItems: "center", padding: 8 }}>
          <Text style={{ flex: 1, color: "#57606a" }}>{text().length} characters</Text>
          <Text onPress={() => input.blur()} style={{ color: "#0969da", fontWeight: "600" }}>Done</Text>
        </View>
      </InputAccessoryView>
    </View>
  );
}
```

The bar is as wide as the window and as tall as its content. Input accessories are iOS's: on Android the bar is an empty hidden view, so place those controls elsewhere there, for example above the input (`os() == Os::Android` in Rust, `platform.os === "android"` in TSX).

## Related

- [`Input`](https://nsh.dev/versions/main/elements/input.md): the element reference.
- [Keyboard](https://nsh.dev/versions/main/elements/keyboard.md) and [`Keyboard`](https://nsh.dev/versions/main/modules/nsh.md#keyboard-and-keyboardframe).
- [`InputAccessoryView`](https://nsh.dev/versions/main/modules/nsh-mobile.md#inputaccessoryview): `InputAccessoryView`.
- [Scrolling](https://nsh.dev/versions/main/docs/scrolling.md#scroll-views-and-the-keyboard): keyboard dismissal and taps in scroll views.

Source: https://nsh.dev/versions/main/docs/forms-and-keyboard

---

# Animation

Every animation in NSH runs on the UI thread. You describe it once, from Rust or TSX, and the platform plays it frame by frame (Core Animation and a display link on iOS, the UI-thread animator on Android) without calling back into your code. A busy engine thread cannot make an animation stutter, and an animation costs none of your code while it runs.

There are six tools, from the readiest to the most flexible:

| Tool | Use it for |
|---|---|
| [Motion](#motion) | A view that enters, leaves, draws the eye or loops: ready-made motions (`fadeInUp`, `shake`, `pulse`, ...) or keyframes of your own, on its opacity and transform. |
| [Transitions](#transitions) | A style change that should animate instead of jump: a color, an opacity, a transform. |
| [Keyframe animations](#keyframe-animations) | A spinner, a pulsing placeholder, a bouncing hint. |
| [Keyframes](#keyframes) | Any animated value through keyframes, as CSS plays them: offsets, an easing per segment, iterations and a direction. |
| [Animated values](#animated-values) | Anything driven by a value over time: springs, gestures, scroll position, sequences. |
| [Layout animations](#layoutanimation) | Size and position changes after an update: items inserted, removed, reordered, a panel expanding. |

## Motion

A motion moves a view's opacity and transform through keyframes, natively. Create one in the component that owns the view (`motion()` in Rust, `createMotion()` from `nsh` in TSX), bind it to the view, and play a ready-made motion or one of your own on it. `enter` starts the view where a motion begins and plays it at once, so the view comes in from its first frame.

```rust
#[component]
pub fn App() -> impl IntoElement {
    let card = motion().entering(MotionPreset::FadeInUp);
    view().flex_1().items_center().justify_center().child(
        view()
            .size(px(120.0))
            .rounded(px(16.0))
            .bg(rgb(0x0969da))
            .bind_motion(&card)
            .on_press(move || {
                card.play(MotionPreset::Shake);
            }),
    )
}
```

```tsx
import { mount, View } from "nsh";
import { createMotion } from "nsh";

function App() {
  const card = createMotion({ enter: "fadeInUp" });
  return (
    <View style={{ flex: 1, alignItems: "center", justifyContent: "center" }}>
      <View
        onPress={() => card.play("shake")}
        style={{ width: 120, height: 120, borderRadius: 16, backgroundColor: "#0969da", ...card.style }}
      />
    </View>
  );
}

mount(App);
```

A motion has an animated value per channel: `opacity` (0..1), `translateX` and `translateY` (points), `rotate`, `rotateX` and `rotateY` (degrees), `scale`, `scaleX` and `scaleY`. They start at rest (opacity and scales 1, the rest 0) and apply in that order: translations, then rotations, then scales, about the view's transform origin. A motion has no look of its own: it moves what you styled.

A motion moves opacity and transform only. Spreading `m.style` sets the view's `opacity` and `transform`; to keep an opacity of your own, bind only the steps (`transform: m.transform`). Colors move with an animated value and [`interpolate`](#interpolation).

| TSX | Rust | Description |
|---|---|---|
| `createMotion(options?)` | `motion()` | A motion with every channel at rest. |
| `createMotion({ initial: { opacity: 0 } })` | `m.value(MotionChannel::Opacity).set(0.0)` | Where channels start; the others start at rest. |
| `createMotion({ enter, delay, duration, ... })` | `motion().entering(spec)` | Starts where `enter` starts and plays it at once; the other options change its timing. `enter` sets the channels it moves, over `initial`. |
| `style={m.style}`, `m.transform` | `.bind_motion(&m)` | Binds the channels: `m.style` is `{ opacity, transform }`, its `transform` a list of seven steps (`scale` is folded into `scaleX` and `scaleY`). They apply after the view's `translate`, `rotate` and `scale`; a perspective before them gives a 3D flip its depth: `transform: [{ perspective: 800 }, ...m.transform]`. In Rust the motion's transform applies after the view's own. |
| `m.opacity`, `m.translateX`, ... | `m.value(MotionChannel::Opacity)`, ... | One channel's animated value, to interpolate or drive by hand. |
| `m.play(motion, options?)` | `m.play(spec)` | Plays a preset or a motion of your own; a new one interrupts the one playing. Resolves with `{ finished }`, `true` when it finished (`AnimationEnd` in Rust). |
| `m.animation(motion, options?)` | `m.animation(spec)` | The same motion as a [composite animation](#composite-animations), not started, to sequence, stagger or loop with others. |
| `play(motion, { ignoreReduceMotion: true })` | `m.play_ignoring_reduce_motion(spec)` | Plays it even when the user asks for less motion. |
| `m.stop()` | `m.stop()` | Stops it where it is. |
| `m.reset()` | `m.reset()` | Stops it and puts every channel back at rest. |

### Presets

The ready-made motions are data: `motions` from `nsh` (`motions.fadeInUp` is what `play("fadeInUp")` plays) and `MotionPreset` in Rust (`MotionPreset::FadeInUp.spec()`). Distances are in points, sized for controls and cards; for larger views, scale a motion's values or write your own keyframes. `swing` and the other rotations turn about the view's transform origin: give a swinging sign `transformOrigin: "top"` (`.origin_top()`).

**Enter**: they start hidden or away and end at rest.

| TSX | Rust | Duration | Description |
|---|---|---|---|
| `fadeIn` | `MotionPreset::FadeIn` | 300 ms | Fades in. |
| `fadeInUp` | `MotionPreset::FadeInUp` | 450 ms | Fades in, rising into place. |
| `fadeInDown` | `MotionPreset::FadeInDown` | 450 ms | Fades in, dropping into place. |
| `fadeInLeft` | `MotionPreset::FadeInLeft` | 450 ms | Fades in, coming from the left. |
| `fadeInRight` | `MotionPreset::FadeInRight` | 450 ms | Fades in, coming from the right. |
| `zoomIn` | `MotionPreset::ZoomIn` | 350 ms | Fades in, growing from 90 %. |
| `popIn` | `MotionPreset::PopIn` | 450 ms | Pops in: grows from half its size past its own and settles. |
| `bounceIn` | `MotionPreset::BounceIn` | 650 ms | Bounces in, overshooting twice. |
| `slideInUp` | `MotionPreset::SlideInUp` | 400 ms | Slides up from below, unfaded (sheets, toasts). |
| `slideInDown` | `MotionPreset::SlideInDown` | 400 ms | Slides down from above, unfaded. |
| `flipInX` | `MotionPreset::FlipInX` | 600 ms | Flips in about its horizontal axis. |
| `flipInY` | `MotionPreset::FlipInY` | 600 ms | Flips in about its vertical axis. |

**Exit**: they start at rest and end hidden or away.

| TSX | Rust | Duration | Description |
|---|---|---|---|
| `fadeOut` | `MotionPreset::FadeOut` | 250 ms | Fades out. |
| `fadeOutUp` | `MotionPreset::FadeOutUp` | 300 ms | Fades out, rising away. |
| `fadeOutDown` | `MotionPreset::FadeOutDown` | 300 ms | Fades out, dropping away. |
| `fadeOutLeft` | `MotionPreset::FadeOutLeft` | 300 ms | Fades out to the left. |
| `fadeOutRight` | `MotionPreset::FadeOutRight` | 300 ms | Fades out to the right. |
| `zoomOut` | `MotionPreset::ZoomOut` | 250 ms | Fades out, shrinking to 90 %. |
| `popOut` | `MotionPreset::PopOut` | 300 ms | Pops out: swells a little, then shrinks away. |
| `slideOutDown` | `MotionPreset::SlideOutDown` | 300 ms | Slides down out of view, unfaded. |
| `slideOutUp` | `MotionPreset::SlideOutUp` | 300 ms | Slides up out of view, unfaded. |

**Attention**: they start and end at rest.

| TSX | Rust | Duration | Description |
|---|---|---|---|
| `shake` | `MotionPreset::Shake` | 500 ms | Shakes sideways: a wrong password, an invalid field. |
| `headShake` | `MotionPreset::HeadShake` | 800 ms | Shakes its head: a gentler no. |
| `wiggle` | `MotionPreset::Wiggle` | 600 ms | Wiggles about its center: something to notice. |
| `swing` | `MotionPreset::Swing` | 900 ms | Swings from its top edge, like a sign. |
| `pulse` | `MotionPreset::Pulse` | 500 ms | Grows a little and back: a soft emphasis. |
| `heartbeat` | `MotionPreset::Heartbeat` | 900 ms | Beats twice, like a heart: a like, a favorite. |
| `rubberBand` | `MotionPreset::RubberBand` | 800 ms | Squashes and stretches like rubber. |
| `jello` | `MotionPreset::Jello` | 800 ms | Wobbles like jelly. |
| `tada` | `MotionPreset::Tada` | 900 ms | Shrinks, then grows with a wiggle: a reward. |
| `jump` | `MotionPreset::Jump` | 700 ms | Jumps and lands with a squash. |
| `flash` | `MotionPreset::Flash` | 800 ms | Blinks out and in twice. |

**Loop**: they repeat until stopped.

| TSX | Rust | Duration | Description |
|---|---|---|---|
| `spin` | `MotionPreset::Spin` | 1000 ms | Turns once, forever. |
| `float` | `MotionPreset::Float` | 1500 ms | Floats up and down, forever. |
| `breathe` | `MotionPreset::Breathe` | 1800 ms | Breathes: grows and fades a little, forever. |
| `sway` | `MotionPreset::Sway` | 1600 ms | Sways about its center, forever. |
| `bob` | `MotionPreset::Bob` | 1000 ms | Bobs like a bouncing ball, forever. |
| `glow` | `MotionPreset::Glow` | 2000 ms | Glows in and out, forever. |

`play` takes a preset's timing options over it (`m.play("shake", { duration: 300 })`), and a preset spreads into a motion of your own (`m.play({ ...motions.fadeInUp, duration: 600 })`). In Rust, change a preset's spec: `MotionPreset::FadeInUp.spec().timing(|t| t.delay(100.0))`.

### Motions of your own

A motion of your own is keyframes per channel and one timing (the options of [keyframes](#keyframes)). In TSX, write each channel's keyframes (`{ opacity: [0, 1] }`), or a list of frames as the Web Animations API writes them (`[{ opacity: 0, translateY: 24 }, { opacity: 1, translateY: 0 }]`), each frame with its `offset` and `easing`. In a list of frames, a frame without an offset sits where its position in the list puts it, and a channel follows the frames that name it. Angles can be strings (`"45deg"`, `"0.5turn"`). In Rust, build a `MotionSpec`.

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

let flip = MotionSpec::new(KeyframeTiming::new(600.0).infinite())
    .values(MotionChannel::RotateY, [0.0, 180.0, 360.0]);
card.play(flip);
```

```tsx
// Channels' keyframes.
card.play({
  duration: 400,
  keyframes: { opacity: [0, 1], translateY: [{ value: 24, easing: "easeOut" }, 0] },
});

// A list of frames.
card.play({
  duration: 400,
  keyframes: [
    { opacity: 0, translateY: 24, easing: "easeOut" },
    { opacity: 1, translateY: 0 },
  ],
});

card.play({ duration: 600, iterations: "infinite", keyframes: { rotateY: ["0deg", "180deg", "360deg"] } });
```

### Entrances and staggered lists

Give each row a motion that enters, with a delay that grows with its index: rows that appear together come in one after another. Cap the delay so that a row added far down the list does not wait.

```rust
each(items, |item: &Item| item.id, |item, index| {
    let delay = index.get_untracked().min(10) as f32 * 60.0;
    let row = motion().entering(MotionPreset::FadeInUp.spec().timing(|t| t.delay(delay)));
    view()
        .rounded_xl()
        .bg(ZINC.shade(100))
        .p_4()
        .bind_motion(&row)
        .child(text(move || item.get().title))
})
```

```tsx
function Row(props: { title: string; index: number }) {
  const row = createMotion({ enter: "fadeInUp", delay: Math.min(props.index, 10) * 60 });
  return (
    <View class="rounded-xl bg-zinc-100 p-4" style={row.style}>
      <Text>{props.title}</Text>
    </View>
  );
}

<Each of={items()} key={(item) => item.id}>
  {(item, index) => <Row title={item().title} index={index()} />}
</Each>
```

Motions also compose: `m.animation(..)` is a motion as a [composite animation](#composite-animations), not started, so `Animated.stagger` runs a group of them natively, counted from the first item, the last, the center or any index. Give them a hidden `initial` (or start them where the motion starts) so nothing shows before its turn.

```rust
let cards: Vec<Motion> = (0..5)
    .map(|_| {
        let m = motion();
        m.value(MotionChannel::Opacity).set(0.0);
        m
    })
    .collect();
Animation::stagger_from(60.0, StaggerFrom::Center, cards.iter().map(|m| m.animation(MotionPreset::FadeInUp))).start();
```

```tsx
const cards = [0, 1, 2, 3, 4].map(() => createMotion({ initial: { opacity: 0 } }));
Animated.stagger(60, cards.map((m) => m.animation("fadeInUp")), { from: "center" }).start();
```

### Exits

Play the exit, wait for it, then remove the view. A [layout animation](#layoutanimation) lets the views around it close the gap.

```rust
let remove = move || {
    spawn(async move {
        row.play(MotionPreset::FadeOutLeft).await;
        animate_layout(LayoutAnimation::EASE_IN_EASE_OUT);
        items.update(|items| items.retain(|i| i.id != id));
    });
};
```

```tsx
const remove = async () => {
  await row.play("fadeOutLeft");
  LayoutAnimation.easeInEaseOut();
  items.set(items().filter((i) => i.id !== id));
};
```

Motions follow the user's [reduced motion](#reduced-motion) setting on their own: when the user asks for less motion, a motion lands where it ends at once, without moving.

## Transitions

Name what to animate and for how long (`.transition_all().duration(400.0)` in Rust, `transitionProperty` and `transitionDuration` in TSX), and later changes to those properties animate natively from what is on screen to the new value.

```rust
#[component]
pub fn App() -> impl IntoElement {
    let on = signal(false);
    view().flex_1().items_center().justify_center().child(
        view()
            .on_press(move || on.update(|on| *on = !*on))
            .size(px(100.0))
            .rounded(move || px(if on.get() { 50.0 } else { 16.0 }))
            .bg(move || if on.get() { rgb(0x8250df) } else { rgb(0x0969da) })
            .rotate(move || deg(if on.get() { 45.0 } else { 0.0 }))
            .scale(move || if on.get() { 1.2_f32 } else { 1.0 })
            .transition_all()
            .duration(400.0)
            .ease_in_out(),
    )
}
```

```tsx
import { mount, signal, View } from "nsh";

function App() {
  const on = signal(false);
  return (
    <View style={{ flex: 1, alignItems: "center", justifyContent: "center" }}>
      <View
        onPress={() => on.set(!on())}
        style={{
          width: 100,
          height: 100,
          borderRadius: on() ? 50 : 16,
          backgroundColor: on() ? "#8250df" : "#0969da",
          rotate: on() ? "45deg" : "0deg",
          scale: on() ? 1.2 : 1,
          transitionProperty: "all",
          transitionDuration: 400,
          transitionTimingFunction: "ease-in-out",
        }}
      />
    </View>
  );
}

mount(App);
```

| Style | Rust | Type | Description |
|---|---|---|---|
| `transitionProperty` | `.transition()`, `.transition_all()`, `.transition_colors()`, `.transition_opacity()`, `.transition_transform()`, `.transition_shadow()` | `string` | What animates, comma-separated: `"all"`, `"colors"`, `"opacity"`, `"transform"`, `"box-shadow"`, `"border-radius"`, ... |
| `transitionDuration` | `.duration(ms)` | `number \| "150ms" \| "0.2s"` | Milliseconds as a number, or a CSS time. |
| `transitionDelay` | `.delay(ms)` | `number \| "150ms" \| "0.2s"` | Before it starts. |
| `transitionTimingFunction` | `.ease_linear()`, `.ease_in()`, `.ease_out()`, `.ease_in_out()`, `.ease_bezier(..)` | `"linear" \| "ease" \| "ease-in" \| "ease-out" \| "ease-in-out" \| "cubic-bezier(…)"` | The curve. |

Properties that transition, by group: **colors** (background, border, outline, shadow and text colors, gradient stops), **opacity**, **transform**, **shadows** (`box-shadow`) and **shape** (border radius and width). CSS names and their camel-case forms both work (`background-color`, `backgroundColor`, `transform`, `scale`, ...). Layout changes animate with [layout animations](#layoutanimation).

With Tailwind, the same thing is `transition` (colors, opacity, shadows and transforms), `transition-all`, `transition-colors`, `transition-opacity`, `transition-transform`, `transition-shadow`, with `duration-*`, `delay-*` and `ease-*`. Combined with the pressed state (`.active(..)`, `active:`) it gives pressed states that animate:

```rust
view()
    .on_press(save)
    .rounded_xl()
    .bg(BLUE.shade(600))
    .px_5()
    .py_3()
    .transition()
    .duration(150.0)
    .active(|s| s.scale(0.95).bg(BLUE.shade(800)))
    .child(text("Save").font_weight(FontWeight::SEMIBOLD).text_color(white()))
```

```tsx
<View onPress={save} class="rounded-xl bg-blue-600 px-5 py-3 transition duration-150 active:scale-95 active:bg-blue-800">
  <Text class="font-semibold text-white">Save</Text>
</View>
```

A transition starts from the value currently on screen, so changing the target again mid-way turns smoothly.

## Keyframe animations

Four built-in keyframe animations run natively, forever by default: `spin` (one turn clockwise), `ping` (scales up to 2× and fades out), `pulse` (fades to half opacity and back) and `bounce` (jumps up by a quarter of its height and lands).

```rust
view()
    .size_8()
    .rounded_full()
    .border(px(4.0))
    .border_color(ZINC.shade(300))
    .border_t_color(BLUE.shade(600))
    .animate_spin()
view().h_4().w_40().rounded(px(4.0)).bg(ZINC.shade(200)).animate_pulse()
```

```tsx
<View class="size-8 rounded-full border-4 border-zinc-300 border-t-blue-600 animate-spin" />
<View class="h-4 w-40 rounded bg-zinc-200 animate-pulse" />
```

| Style | Rust | Type | Description |
|---|---|---|---|
| `animationName` | `.animate_spin()`, `.animate_ping()`, `.animate_pulse()`, `.animate_bounce()`, `.animate_none()`, or `.animation(KeyframeAnimation::new(Keyframes::Spin))` | `"none" \| "spin" \| "ping" \| "pulse" \| "bounce"` | The animation. |
| `animationDuration` | `KeyframeAnimation::duration(ms)` | `number \| "1s" \| …` | One iteration. |
| `animationDelay` | `KeyframeAnimation::delay(ms)` | `number \| "200ms" \| …` | Before it starts. |
| `animationTimingFunction` | `KeyframeAnimation::easing([x1, y1, x2, y2])` | as `transitionTimingFunction` | The curve. |
| `animationIterationCount` | `KeyframeAnimation::iterations(n)` | `number \| "infinite"` | Default `"infinite"`. |

Tailwind: `animate-spin`, `animate-ping`, `animate-pulse`, `animate-bounce`, `animate-none`.

## Animated values

An animated value is a number that lives on the UI thread. Create one (`animated_value(..)` in Rust, `createAnimatedValue` from `nsh` in TSX), bind it to styles, and animate it; the bound views follow it every frame without an update.

```rust
#[component]
pub fn App() -> impl IntoElement {
    let x = animated_value(0.0);
    let opacity = animated_value(1.0);
    let play = move || {
        spawn(async move {
            x.timing(240.0, 600.0, Easing::Curve(Curve::Cubic, EaseMode::Out)).await;
            opacity.timing(0.3, 200.0, Easing::EaseInOut).await;
            x.spring(0.0, Spring::default());
            opacity.timing_with(1.0, Timing::default());
        });
    };
    view()
        .flex_1()
        .justify_center()
        .p_6()
        .gap_6()
        .child(
            view()
                .size(px(60.0))
                .rounded(px(12.0))
                .bg(rgb(0x0969da))
                .bind_opacity(&opacity)
                .bind_translate_x(&x),
        )
        .child(view().on_press(play).child(text("Play").text_color(rgb(0x0969da))))
}
```

```tsx
import { mount, Text, View } from "nsh";
import { createAnimatedValue, Easing } from "nsh";

function App() {
  const x = createAnimatedValue(0);
  const opacity = createAnimatedValue(1);
  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24, gap: 24 }}>
      <View style={{ width: 60, height: 60, borderRadius: 12, backgroundColor: "#0969da", opacity, translate: [x, 0] }} />
      <View
        onPress={async () => {
          await x.timing(240, { duration: 600, easing: Easing.out(Easing.cubic) });
          await opacity.timing(0.3, { duration: 200 });
          x.spring(0);
          opacity.timing(1);
        }}
      >
        <Text style={{ color: "#0969da" }}>Play</Text>
      </View>
    </View>
  );
}

mount(App);
```

**What can be bound:** `opacity` (`.bind_opacity(..)`); `backgroundColor`, `borderColor` (every side) and a text's `color` (the whole text), through an interpolation to colors (`.bind_background(..)`, `.bind_border_color(..)`, `.bind_color(..)`); `translate` (`[x, y]`, a value per axis), `rotate` (degrees) and `scale` (`[x, y]` per axis, or one value for both); and the steps of a `transform` list: `translateX`, `translateY`, `scale`, `scaleX`, `scaleY`, `rotate`, `rotateX`, `rotateY` and `rotateZ` (`.bind_translate_x(..)`, `.bind_translate_y(..)`, `.bind_scale(..)`, `.bind_rotate(..)` in degrees, `.bind_transform(kind, ..)` in Rust). Shadows change with [transitions](#transitions). A focus ring or a price that flashes green is a color interpolation bound to the border or text color:

```rust
let flash = animated_value(0.0);
let color = flash.interpolate_colors(&[0.0, 1.0], &[rgb(0x1f2328), rgb(0x1a7f37)]);

text(move || price.get().to_string()).bind_color(&color)
// On a new price: flash.set(1.0); flash.timing(0.0, 600.0, Easing::EaseInOut);
```

```tsx
const flash = createAnimatedValue(0);
const color = flash.interpolate({ inputRange: [0, 1], outputRange: ["#1f2328", "#1a7f37"] });

<Text style={{ color }}>{price()}</Text>
// On a new price: flash.set(1); flash.timing(0, { duration: 600 });
```

Animated values also drive [canvas drawings](https://nsh.dev/versions/main/docs/canvas.md#driving-drawings-with-animated-values), receive scroll offsets ([`scrollValue`](https://nsh.dev/versions/main/docs/scrolling.md#scroll-linked-effects-scrollvalue)) and gestures ([`pan`, `pinch`, `rotation`](https://nsh.dev/versions/main/docs/touch-and-gestures.md#native-gestures-pan-pinch-and-rotation)).

The value is kept alive by the views bound to it and by the component that made it, so a binding stays connected however your variables come and go. Create animated values in the component that owns them (not at module level when every instance needs its own).

### AnimatedValue methods

| TSX | Rust | Description |
|---|---|---|
| `set(value)` | `set(value)` | Jumps to `value`, stopping any animation. |
| `stop()` | `stop()` | Stops the running animation where it is; in TSX, resolves with `{ value }`, the value there. |
| `getValue()` | `value()` | The current value, read on the UI thread where it moves (it settles within a frame): a promise in TSX, an awaitable answer in Rust. |
| `setOffset(offset)` | `set_offset(offset)` | Adds `offset` to what the value shows: bindings see value + offset, while `set`, animations and drags move the value. |
| `flattenOffset()` | `flatten_offset()` | Adds the offset to the value and makes the offset 0. |
| `extractOffset()` | `extract_offset()` | Moves the value into the offset and makes the value 0: a drag then starts from 0, on top of where the last one left it. |
| `timing(to, { duration?, easing?, delay? })` | `timing(to, ms, easing)`, `timing_with(to, Timing { .. })` | Animates to `to` over `duration` ms (default 300, easing `"easeInOut"`). |
| `spring(to, { stiffness?, damping?, mass?, velocity? })` | `spring(to, Spring { .. })` | Springs to `to` (defaults: stiffness 170, damping 26, mass 1). |
| `decay({ velocity?, deceleration?, clamp?, bounce? })` | `decay(velocity, deceleration)`, `decay_within(velocity, deceleration, (min, max), bounce)` | Coasts from `velocity` (units per second) and slows down (deceleration 0.998 per ms by default). With a clamp of `[min, max]` it stops at a bound, or bounces back from it keeping `bounce` (0..1) of its speed. |

Each animation gives an answer you can await, whether it finished: `true` when it played to the end, `false` when something stopped it (`stop()`, `set()`, or a new animation on the same value). It is a `Promise<{ finished: boolean }>` in TSX and an `AnimationEnd` in Rust, which a task awaits for the `bool`. Starting a new animation on a moving value interrupts the old one smoothly: a spring or decay without a velocity continues with the value's current velocity.

```rust
// Spring settings: lower damping overshoots more, higher stiffness is faster.
x.spring(200.0, Spring { stiffness: 180.0, damping: 8.0, ..Spring::default() });   // wobbly
x.spring(200.0, Spring { stiffness: 400.0, damping: 30.0, ..Spring::default() });  // stiff, no overshoot

// A fling that coasts to a stop, from a pan's release velocity.
view().pan_values(Some(&x), None).on_pan_end(move |e: &PanEvent| {
    x.decay(Some(e.velocity_x), 0.998);
})

// A fling that stays on its track and bounces softly off its ends.
x.decay_within(Some(e.velocity_x), 0.998, (0.0, 300.0), 0.3);

// Where a value is now (it moves on the UI thread, so the answer is async).
let at = x.value().await;
```

```tsx
// Spring settings: lower damping overshoots more, higher stiffness is faster.
x.spring(200, { stiffness: 180, damping: 8 });   // wobbly
x.spring(200, { stiffness: 400, damping: 30 });  // stiff, no overshoot

// A fling that coasts to a stop, from a pan's release velocity.
<View pan={{ x }} onPanEnd={(e) => x.decay({ velocity: e.velocity.x })} />

// A fling that stays on its track and bounces softly off its ends.
x.decay({ velocity: e.velocity.x, clamp: [0, 300], bounce: 0.3 });

// Where a value is now (it moves on the UI thread, so the answer is async).
const where = await x.getValue();
```

### Keyframes

`keyframes` plays a value through keyframes as CSS keyframes play: `value.keyframes(frames, options)` in TSX, `value.keyframes(frames, KeyframeTiming)` in Rust (`Animated.keyframes(value, { keyframes, ... })` and `Animation::keyframes(..)` as a step of a [composite](#composite-animations)). A keyframe is a number (or an angle string such as `"90deg"`), spread evenly with the others, or `{ offset, value, easing }` (`Keyframe::new(value)`, `Keyframe::at(offset, value)`, `.ease(easing)` in Rust).

```rust
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).easing(Easing::EaseOut).iterations(Some(3)),
);

// A clock hand that ticks once a second.
let hand = animated_value(0.0);
hand.keyframes(
    [Keyframe::new(0.0), Keyframe::new(360.0)],
    KeyframeTiming::new(60_000.0).easing(Easing::Steps(60, StepPosition::JumpEnd)).infinite(),
);
```

```tsx
const y = createAnimatedValue(0);
y.keyframes([0, { offset: 0.3, value: -20, easing: "easeIn" }, 0], { duration: 600, easing: "easeOut", iterations: 3 });

// A clock hand that ticks once a second.
const hand = createAnimatedValue(0);
hand.keyframes([0, 360], { duration: 60_000, easing: Easing.steps(60), iterations: "infinite" });
```

| Option | Rust (`KeyframeTiming`) | Default | Description |
|---|---|---|---|
| `duration` | `KeyframeTiming::new(ms)` | 300 | One iteration, in milliseconds. |
| `delay` | `.delay(ms)` | 0 | Before the first iteration. |
| `easing` | `.easing(easing)` | CSS `ease` | The curve of each segment without an easing of its own. |
| `iterations` | `.iterations(Some(n))`, `.infinite()` | 1 | How many iterations, or `"infinite"`. |
| `direction` | `.direction(PlaybackDirection::Alternate)` | `"normal"` | `"normal"`, `"reverse"`, `"alternate"` or `"alternate-reverse"`. |

They play as in CSS and the Web Animations API:

- An easing shapes each segment, not the whole: a keyframe's `easing` shapes the segment that starts at it, and the timing's `easing` every other segment.
- Keyframes without an offset spread evenly between their neighbors; the first defaults to 0 and the last to 1.
- Each iteration starts with a jump to its first keyframe. Without a keyframe at offset 0, the value goes from where it is.
- During a `delay`, the value already holds the first keyframe (CSS `animation-fill-mode: backwards`), so a delayed entrance shows its first frame rather than the view at rest. This holds for motions too.
- `reverse` and the backward iterations of `alternate` run the segments backwards, each with its curve reversed.
- The value stays where the last iteration leaves it. The answer says whether they finished: `true` when they did, `false` when something stopped them.

### Interpolation

`interpolate` maps a value through piecewise linear segments to numbers, colors or angles, and returns a new node you can bind. One value can drive many properties. In Rust, `interpolate(&input, &output)` maps to numbers, `interpolate_colors(&input, &colors)` to colors, and `interpolate_with(&input, output, Interpolation { .. })` takes the extrapolation and easing; in TSX, `value.interpolate({ inputRange, outputRange })` takes them all.

```rust
let t = animated_value(0.0);

view()
    .bind_background(&t.interpolate_colors(&[0.0, 1.0, 2.0], &[rgb(0x54aeff), rgb(0x8250df), rgb(0xcf222e)]))
    .bind_opacity(&t.interpolate(&[0.0, 1.0], &[0.4, 1.0]))
    .bind_rotate(&t.interpolate(&[0.0, 1.0], &[0.0, 180.0]))
    .bind_scale(&t.interpolate_with(
        &[0.0, 1.0],
        AnimationOutput::Numbers(vec![0.6, 1.2]),
        Interpolation {
            easing: Easing::Curve(Curve::Back(1.70158), EaseMode::Out),
            ..Interpolation::default()
        },
    ))
```

```tsx
const t = createAnimatedValue(0);

<View
  style={{
    backgroundColor: t.interpolate({ inputRange: [0, 1, 2], outputRange: ["#54aeff", "#8250df", "#cf222e"] }),
    opacity: t.interpolate({ inputRange: [0, 1], outputRange: [0.4, 1] }),
    rotate: t.interpolate({ inputRange: [0, 1], outputRange: ["0deg", "180deg"] }),
    scale: t.interpolate({ inputRange: [0, 1], outputRange: [0.6, 1.2], easing: Easing.out(Easing.back()) }),
  }}
/>
```

| Option | Rust | Description |
|---|---|---|
| `inputRange` | the input slice | Increasing input stops. |
| `outputRange` | the output slice, or `AnimationOutput` | One output per stop: numbers, colors (`"#rrggbb"`, `"rgba(…)"`, named) or angles (`"45deg"`, `"1rad"`). |
| `extrapolate` | `Interpolation::extrapolate(Extrapolate::Extend)` | Outside the input range: `"clamp"` (default), `"extend"` (continue the end segments) or `"identity"` (pass the input through). |
| `extrapolateLeft`, `extrapolateRight` | `extrapolate_left`, `extrapolate_right` | The same, for one side. |
| `easing` | `easing` | Shapes each segment. |

> [!IMPORTANT]
> Interpolations **clamp** by default: outside the input range, the output stays at the nearest end. Pulling a scroll view past its top therefore keeps a scroll-linked header at its end state. Pass `extrapolate: "extend"` (`Extrapolate::Extend`) when you want the line to continue.

### Arithmetic and diffClamp

Nodes combine with arithmetic, also natively: `a.add(b)`, `a.sub(b)`, `a.mul(b)`, `a.div(b)`, `a.mod(b)` (`a.modulo(b)` in Rust; never negative for a positive `b`, e.g. angles in 0..360), where `b` is a node or a number. In TSX, `Animated.add`, `subtract`, `multiply`, `divide` and `modulo` are the same as functions.

`diffClamp(min, max)` (`diff_clamp`) follows the node's *changes* while staying within `min..max`. Applied to a scroll offset, it makes a header that hides as the content scrolls up and comes back as soon as it scrolls down:

```rust
let offset = animated_value(0.0);
let header = offset.diff_clamp(0.0, 56.0);

scroll().flex_1().scroll_value(&offset)
view().absolute().top_0().left_0().right_0().h(px(56.0)).bind_translate_y(&header.mul(-1.0))
```

```tsx
const scroll = createAnimatedValue(0);
const header = scroll.diffClamp(0, 56);

<Scroll style={{ flex: 1 }} scrollValue={scroll}>…</Scroll>
<View style={{ position: "absolute", top: 0, left: 0, right: 0, height: 56, translate: [0, header.mul(-1)] }}>…</View>
```

With `{ snap: true }` (`diff_clamp_with(min, max, DiffClamp::snapping())`), a header left partly shown when the scrolling stops finishes the move: it settles fully shown or fully hidden, whichever is nearer, in 200 ms on the UI thread. It hides only once the page has scrolled at least its height, so a page scrolled less than that shows the whole header. Scrolling again during the move takes over from where the header is.

```rust
let header = offset.diff_clamp_with(0.0, 56.0, DiffClamp::snapping());
```

```tsx
const header = scroll.diffClamp(0, 56, { snap: true });
```

## Composite animations

Animations are built out of steps (`Animation` in Rust, `Animated` from `nsh` in TSX) and the whole tree runs natively: each step starts on the UI thread the moment the previous one ends, with no gap and none of your code in between.

```rust
let ys: Vec<AnimatedValue> = (0..5).map(|_| animated_value(0.0)).collect();
let fade = animated_value(1.0);

let hop = Animation::stagger(
    80.0,
    ys.iter().map(|y| {
        Animation::sequence([
            Animation::timing(y, -30.0, Timing::new(200.0, Easing::Curve(Curve::Quad, EaseMode::Out))),
            Animation::spring(y, 0.0, Spring { stiffness: 300.0, damping: 12.0, ..Spring::default() }),
        ])
    }),
);

let breathe = Animation::sequence([
    Animation::timing(&fade, 0.3, Timing::new(400.0, Easing::EaseInOut)),
    Animation::timing(&fade, 1.0, Timing::new(400.0, Easing::EaseInOut)),
])
.looped(None);

let landed = hop.start();
spawn(async move {
    status.set(if landed.await { "landed" } else { "stopped" });
});
```

```tsx
import { Animated, createAnimatedValue, Easing } from "nsh";

const ys = [0, 1, 2, 3, 4].map(() => createAnimatedValue(0));
const fade = createAnimatedValue(1);

const hop = Animated.stagger(
  80,
  ys.map((y) =>
    Animated.sequence([
      Animated.timing(y, { toValue: -30, duration: 200, easing: Easing.out(Easing.quad) }),
      Animated.spring(y, { toValue: 0, stiffness: 300, damping: 12 }),
    ]),
  ),
);

const breathe = Animated.loop(
  Animated.sequence([
    Animated.timing(fade, { toValue: 0.3, duration: 400 }),
    Animated.timing(fade, { toValue: 1, duration: 400 }),
  ]),
);

hop.start(({ finished }) => console.log(finished ? "landed" : "stopped"));
```

| TSX | Rust | Description |
|---|---|---|
| `Animated.timing(value, { toValue, duration?, easing?, delay? })` | `Animation::timing(&value, to, Timing { .. })` | A timing step. |
| `Animated.spring(value, { toValue, stiffness?, damping?, mass?, velocity? })` | `Animation::spring(&value, to, Spring { .. })` | A spring step. |
| `Animated.decay(value, { velocity?, deceleration?, clamp?, bounce? })` | `Animation::decay(&value, velocity, deceleration)`, `Animation::decay_within(..)` | A decay step. |
| `Animated.sequence(list)` | `Animation::sequence(list)` | One after another. |
| `Animated.parallel(list, { stopTogether? })` | `Animation::parallel(list)`, `.stop_together(..)` | All at once. |
| `Animated.stagger(ms, list, { from? })` | `Animation::stagger(ms, list)`, `Animation::stagger_from(ms, StaggerFrom::Center, list)` | All at once, each starting `ms` after the previous one, counted from `from`: `"first"` (the default), `"last"`, `"center"` (a ripple out from the middle) or an index (`StaggerFrom::First`, `Last`, `Center`, `Index(i)`). |
| `Animated.keyframes(value, { keyframes, ...timing })` | `Animation::keyframes(&value, frames, KeyframeTiming)` | A step of [keyframes](#keyframes). |
| `Animated.delay(ms)` | `Animation::delay(ms)` | Waits. |
| `Animated.loop(animation, { iterations?, resetBeforeIteration? })` | `.looped(iterations)`, `.reset_before_iteration(..)` | Repeats (forever by default; `None` in Rust). |

A composite animation has `start()` (in TSX also with a callback and a promise, both given `{ finished }`; in Rust an awaitable `bool`; calling it again runs it again), `stop()` (stops where it is) and `reset()` (stops and puts its values back where they were when it started). The callback runs once for the whole tree.

A running animation does not keep its values alive: when the component that owns them goes (its views and variables), an endless loop stops with them, and its answer is that it did not finish (`false`).

## Easing

Easing curves are data, evaluated natively: `Easing` from `nsh` in TSX, the `Easing` enum in Rust.

| TSX | Rust | Description |
|---|---|---|
| `Easing.linear`, `Easing.ease` | `Easing::Linear`, `Easing::Bezier(0.25, 0.1, 0.25, 1.0)` | Constant speed; CSS's `ease`. |
| `Easing.quad`, `Easing.cubic`, `Easing.poly(n)` | `Curve::Quad`, `Curve::Cubic`, `Curve::Poly(n)` | `t²`, `t³`, `tⁿ`. |
| `Easing.sin`, `Easing.circle`, `Easing.exp` | `Curve::Sin`, `Curve::Circle`, `Curve::Exp` | Sinusoidal, circular, exponential. |
| `Easing.back(s?)` | `Curve::Back(s)` | Pulls back before going (overshoot `s`, 1.70158 by default). |
| `Easing.elastic(bounciness?)` | `Curve::Elastic(bounciness)` | Springy overshoot. |
| `Easing.bounce` | `Curve::Bounce` | Bounces at the end. |
| `Easing.bezier(x1, y1, x2, y2)` | `Easing::Bezier(x1, y1, x2, y2)` | A cubic Bézier, as in CSS. |
| `Easing.steps(count, position?)` | `Easing::Steps(count, StepPosition::JumpEnd)` | Jumps between `count` levels instead of moving, as CSS `steps()`: a frame-by-frame sprite, a ticking hand. `position` is `"jump-end"` (the default, also `"end"`), `"jump-start"` (`"start"`), `"jump-none"` or `"jump-both"`. |
| `Easing.in(e)`, `Easing.out(e)`, `Easing.inOut(e)` | `Easing::Curve(curve, EaseMode::In)`, `EaseMode::Out`, `EaseMode::InOut` | The curves are "in" curves; `out` and `inOut` turn them around. |

In TSX, anywhere an easing is accepted you can also pass a name (`"linear"`, `"ease"`, `"easeIn"`, `"easeOut"`, `"easeInOut"`) or a Bézier array `[x1, y1, x2, y2]`; in Rust, `Easing::EaseIn`, `Easing::EaseOut` and `Easing::EaseInOut` are the CSS curves.

```rust
x.timing(1.0, 300.0, Easing::Curve(Curve::Back(1.70158), EaseMode::Out));
x.timing(1.0, 300.0, Easing::EaseOut);
x.timing(1.0, 300.0, Easing::Bezier(0.2, 0.8, 0.2, 1.0));
```

```tsx
x.timing(1, { easing: Easing.out(Easing.back()) });
x.timing(1, { easing: "easeOut" });
x.timing(1, { easing: [0.2, 0.8, 0.2, 1] });
```

`Easing.sample(easing, count)` (`sample_easing` in Rust) returns the curve at `count` evenly spaced points from 0 to 1, and `Animated.sampleSpring(config, fps?)` / `Animated.sampleDecay(config, fps?)` (`sample_spring`, `sample_decay`) the values a spring or decay moves through, one per frame (60 per second by default) from `config.from` (0) until it ends. They are computed by the same native code the animations run, so a chart of a curve shows exactly what the animation does:

```rust
use nsh_core::element::{sample_easing, sample_spring};

let curve = sample_easing(Easing::Curve(Curve::Back(1.70158), EaseMode::Out), 50); // 50 progress values
let spring = sample_spring(0.0, 1.0, Spring { stiffness: 180.0, damping: 8.0, ..Spring::default() }, 60.0);
```

```ts
const curve = Easing.sample(Easing.out(Easing.back()), 50); // 50 progress values
const spring = Animated.sampleSpring({ toValue: 1, stiffness: 180, damping: 8 });
```

## LayoutAnimation

A layout animation animates the frame changes of the **next** update natively: views that move or resize glide to their new frames, new views fade (or scale) in, removed views fade out. Call it right before the state change: `animate_layout(..)` in Rust, `LayoutAnimation.configureNext(config)` in TSX.

```rust
use nsh_core::element::LayoutAnimation;

let items = signal(vec![1, 2, 3]);
let next = stored(4);

let add = move || {
    animate_layout(LayoutAnimation::SPRING);
    let n = next.with(|n| {
        *n += 1;
        *n - 1
    });
    items.update(|i| i.insert(0, n));
};
let remove = move || {
    animate_layout(LayoutAnimation::EASE_IN_EASE_OUT);
    items.update(|i| {
        i.remove(0);
    });
};
```

```tsx
import { signal } from "nsh";
import { LayoutAnimation } from "nsh";

const items = signal([1, 2, 3]);
let next = 4;

const add = () => {
  LayoutAnimation.configureNext(LayoutAnimation.Presets.spring);
  items.set([next++, ...items()]);
};
const remove = () => {
  LayoutAnimation.easeInEaseOut();
  items.set(items().slice(1));
};
```

| TSX | Rust | Description |
|---|---|---|
| `configureNext(config, onEnd?)` | `animate_layout(config)` | Animates the next commit's changes; in TSX, `onEnd` runs when done. |
| `create(duration, type?, property?)` | `LayoutAnimation::all(LayoutTransition::new(curve, ms))` | A config with one curve for all three phases. |
| `Presets.easeInEaseOut`, `Presets.linear`, `Presets.spring` | `LayoutAnimation::EASE_IN_EASE_OUT`, `LINEAR`, `SPRING` | Ready-made configs. |
| `easeInEaseOut(onEnd?)`, `linear(onEnd?)`, `spring(onEnd?)` | `animate_layout` with a preset | `configureNext` with a preset. |
| `Types`, `Properties` | `LayoutCurve`, `LayoutProperty` | The names, for building configs. |

A config is `{ duration, create?, update?, delete? }` (`LayoutAnimation { create, update, delete }` in Rust): `create` for inserted views, `update` for moved or resized ones, `delete` for removed ones. Each phase is `{ type?, property?, duration?, delay?, springDamping? }` (`LayoutTransition { curve, property, duration_ms, delay_ms }`), where `type` is `"easeInEaseOut"`, `"spring"`, `"linear"`, `"easeIn"`, `"easeOut"` or `"keyboard"` (the software keyboard's own curve, timed from when the keyboard started to move, so that what makes room for it moves with it; `LayoutCurve::Keyboard`), `property` is what appearing and disappearing views animate (`"opacity"`, `"scaleXY"`, `"scale"`), and `springDamping` (0..1, 0.7 by default; `LayoutCurve::Spring { damping }`) sets the spring's overshoot.

```rust
use nsh_core::element::{LayoutAnimation, LayoutCurve, LayoutProperty, LayoutTransition};

animate_layout(LayoutAnimation {
    create: Some(LayoutTransition::new(LayoutCurve::EaseOut, 300.0)),
    update: Some(LayoutTransition::new(LayoutCurve::Spring { damping: 0.8 }, 300.0)),
    delete: Some(LayoutTransition {
        property: LayoutProperty::Scale,
        ..LayoutTransition::new(LayoutCurve::EaseIn, 300.0)
    }),
});
```

```tsx
LayoutAnimation.configureNext({
  duration: 300,
  create: { type: "easeOut", property: "opacity" },
  update: { type: "spring", springDamping: 0.8 },
  delete: { type: "easeIn", property: "scaleXY" },
});
```

A layout animation covers every frame the update changes, anywhere on the screen: a list that refreshes or live data that lands in the same update moves with it. In a Rust component, animate only what one element's change moves with `ElementRef::animate_layout(transition)`: the element's own frame and its content's, and those of the views its size pushes along (its siblings and theirs, up to the screen). The update's other frames change at once. This is how `nsh/base`'s `Collapsible` and `AccordionPanel` reveal their content.

```rust
use nsh_core::element::{LayoutCurve, LayoutTransition};

let region = element_ref();
let open = signal(false);
let toggle = move || {
    region.animate_layout(LayoutTransition::new(LayoutCurve::Spring { damping: 1.0 }, 265.0));
    open.update(|o| *o = !*o);
};
view()
    .element_ref(&region)
    .overflow_hidden()
    .style_with(move |s| if open.get() { s } else { s.h(px(0.0)) })
```

## What runs where

| | Runs on | Your code per frame |
|---|---|---|
| Transitions, keyframe animations | UI thread | none |
| Motions, keyframes, `timing` / `spring` / `decay`, composites | UI thread | none; your code hears when they end |
| `interpolate`, arithmetic, `diffClamp` | UI thread | none |
| `scrollValue`, `pan` / `pinch` / `rotation` | UI thread | none; your code hears start and end |
| Layout animations | UI thread | none |
| `requestAnimationFrame` loops (`request_animation_frame` in Rust), `onScroll` handlers, `PanResponder` | your code, then an update | every frame |

Reach for `requestAnimationFrame` (a global in TSX, following the display) only for what cannot be described ahead of time, such as a physics simulation in your code. Anything that can be an animated value should be one.

## Reduced motion

On the terminal target (`--target tui`), the host advances animated values and composites on its frames and
delivers their completion callbacks. Opacity, colors and two-dimensional transforms project to the Cell grid;
text keeps upright terminal glyphs, and canvas paths use braille dots. The terminal reports reduced motion:
motions, navigation, modal, layout and style transitions settle immediately, while explicit animated-value
drivers and `Animated` composites play as written.

When the user asks for less motion (iOS "Reduce Motion", Android "Remove animations"), `reduce_motion()` in Rust and `reduceMotion()` from `nsh` in TSX are `true`, and the `motion-reduce:` / `motion-safe:` Tailwind variants apply.

[Motions](#motion) follow the setting on their own: `play` and `enter` land where the motion ends at once, without moving, and the answer is that it finished (`true`), as for a motion that played. An exit still ends hidden, an entrance still ends at rest. Pass `ignoreReduceMotion: true` (`play_ignoring_reduce_motion` in Rust) for a motion that carries meaning the user needs, such as a progress spinner.

Transitions, keyframe animations, animated values, keyframes and composites play as written; use these to choose a calmer alternative:

```rust
let open = move || {
    if reduce_motion() {
        panel.set(0.0);
    } else {
        panel.spring(0.0, Spring::default());
    }
};

view().style_when(|| !reduce_motion(), |s| s.animate_bounce())
```

```tsx
import { View } from "nsh";
import { reduceMotion } from "nsh";

const open = () => (reduceMotion() ? panel.set(0) : panel.spring(0));

<View class="motion-safe:animate-bounce" />
```

See [Accessibility](https://nsh.dev/versions/main/docs/accessibility.md#reduced-motion).

## Related

- [`nsh`'s animation API](https://nsh.dev/versions/main/modules/nsh.md#animation): the TSX reference.
- [Touch and gestures](https://nsh.dev/versions/main/docs/touch-and-gestures.md): driving animated values with the finger.
- [Scrolling](https://nsh.dev/versions/main/docs/scrolling.md#scroll-linked-effects-scrollvalue): `scrollValue`.
- [Canvas](https://nsh.dev/versions/main/docs/canvas.md#driving-drawings-with-animated-values): animated values in drawings.
- [Style reference](https://nsh.dev/versions/main/modules/style-reference.md): the `transition*` and `animation*` keys.

Source: https://nsh.dev/versions/main/docs/animation

---

# Canvas

A canvas is a view you draw into with the operations of the HTML Canvas 2D API: charts, progress rings, gauges, signatures, custom icons, anything that is easier to draw than to build out of views. In Rust, `canvas(..)` shows what a `Painter` recorded; in TSX, `Canvas` from `nsh` takes a `draw` function that records the drawing in one go. The platform replays it natively (Core Graphics on iOS, `android.graphics.Canvas` on Android) at the screen's resolution, so drawings stay sharp at any pixel density.

```rust
use std::f32::consts::TAU;

use nsh_core::prelude::*;

#[component]
pub fn App() -> impl IntoElement {
    let area = signal((0.0_f32, 0.0_f32));
    view().flex_1().p_6().pt(px(60.0)).child(
        canvas(move || {
            let (w, h) = area.get();
            Painter::new()
                .fill_color(rgb(0x0969da))
                .begin_path()
                .arc(w / 2.0, h / 2.0, 60.0, 0.0, TAU)
                .fill()
                .stroke_color(rgb(0x1f2328))
                .line_width(4.0)
                .stroke_rect(bounds(point(px(20.0), px(20.0)), size(px(w - 40.0), px(h - 40.0))))
        })
        .h(px(200.0))
        .rounded(px(12.0))
        .bg(white())
        .on_layout(move |frame: &Bounds<Points>| area.set((frame.size.width.0, frame.size.height.0))),
    )
}
```

```tsx
import { Canvas, mount, View } from "nsh";

function App() {
  return (
    <View style={{ flex: 1, padding: 24, paddingTop: 60 }}>
      <Canvas
        style={{ height: 200, borderRadius: 12, backgroundColor: "#ffffff" }}
        draw={(cx, { width, height }) => {
          cx.fillStyle = "#0969da";
          cx.beginPath();
          cx.arc(width / 2, height / 2, 60, 0, Math.PI * 2);
          cx.fill();
          cx.strokeStyle = "#1f2328";
          cx.lineWidth = 4;
          cx.strokeRect(20, 20, width - 40, height - 40);
        }}
      />
    </View>
  );
}

mount(App);
```

A canvas takes everything a [view](https://nsh.dev/versions/main/elements/view.md) takes (styles, classes, touch handlers, accessibility, refs) plus its drawing. It needs a size from its style or layout; its content is the drawing. Coordinates are in points, with the origin at the top left.

## When the drawing is made

In Rust, `canvas(move || ..)` records in a binding: the closure runs once, and again when a [signal](https://nsh.dev/versions/main/docs/reactivity.md) it read changes. A drawing that depends on the canvas's size keeps the size from `.on_layout(..)` in a signal and reads it, as above. In TSX, `draw(cx, { width, height })` runs:

- once the canvas's size is known (after its first layout);
- again when the canvas is resized;
- again when a signal it read changes.

Each run replaces the whole drawing. Reading signals while drawing is how a canvas follows your data:

```rust
let values = signal(vec![12.0_f32, 30.0, 22.0, 48.0, 36.0, 60.0]);
let width = signal(0.0_f32);
let height = 160.0;

canvas(move || {
    let w = width.get();
    values.with(|v| {
        let x = |i: usize| i as f32 / (v.len() - 1) as f32 * w;
        let y = |n: f32| height - n / 100.0 * height;
        let mut p = Painter::new().begin_path().move_to(x(0), y(v[0]));
        for (i, &n) in v.iter().enumerate().skip(1) {
            p = p.line_to(x(i), y(n));
        }
        p.stroke_color(rgb(0x3b82f6)).line_width(2.5).line_join(LineJoin::Round).stroke()
    })
})
.h(px(height))
.on_layout(move |frame: &Bounds<Points>| width.set(frame.size.width.0))
```

```tsx
const values = signal([12, 30, 22, 48, 36, 60]);

<Canvas
  style={{ height: 160 }}
  draw={(cx, { width, height }) => {
    const v = values();
    const x = (i: number) => (i / (v.length - 1)) * width;
    const y = (n: number) => height - (n / 100) * height;
    cx.beginPath();
    v.forEach((n, i) => (i === 0 ? cx.moveTo(x(i), y(n)) : cx.lineTo(x(i), y(n))));
    cx.strokeStyle = "#3b82f6";
    cx.lineWidth = 2.5;
    cx.lineJoin = "round";
    cx.stroke();
  }}
/>
```

Drawing calls only record: the drawing is made by the platform after the recording is done, so pixels are not read back. The recording is sent to the platform as one operation.

## The 2D operations

The operations are a subset of the HTML Canvas 2D API: `CanvasRenderingContext2D` in TSX, and the methods of `Painter` in Rust, under Rust names (`begin_path`, `fill_rect`, `line_width`, `set_transform`, `draw_image`, ...; colors through `fill_color` / `stroke_color`, gradients through `fill_style` / `stroke_style`). What is supported:

**State**

| Member | Rust | Description |
|---|---|---|
| `save()`, `restore()` | `.save()`, `.restore()` | Push and pop the drawing state (styles, transform, clip). |
| `fillStyle`, `strokeStyle` | `.fill_color(..)`, `.fill_style(..)`, `.stroke_color(..)`, `.stroke_style(..)` | A CSS color, a gradient, or an animated value interpolating colors. |
| `lineWidth`, `lineCap`, `lineJoin`, `miterLimit` | `.line_width(..)`, `.line_cap(..)`, `.line_join(..)`, `.miter_limit(..)` | Stroke shape. |
| `setLineDash(segments)`, `getLineDash()`, `lineDashOffset` | `.line_dash(..)`, `.line_dash_offset(..)` | Dashes. |
| `globalAlpha` | `.global_alpha(..)` | Opacity of what is drawn next, 0..1. |
| `globalCompositeOperation` | `.composite(Composite::DestinationOut)` | How it combines: `"source-over"`, `"destination-out"`, `"multiply"`, `"screen"`, ... |
| `shadowColor`, `shadowBlur`, `shadowOffsetX`, `shadowOffsetY` | `.shadow(color, blur, offset)` | Shadows. |
| `font` | `.font(..)` | CSS `font` shorthand: `"600 14px Inter"` (sizes in px, pt or rem); `small-caps` and the number forms `tabular-nums`, `oldstyle-nums`, ... may come before the size. |
| `fontVariantNumeric` | `.font_variant_numeric(..)` | `"tabular-nums"` makes every figure the same width, so changing numbers (counters, prices, axis labels) do not jitter; also `"proportional-nums"`, `"oldstyle-nums"`, `"lining-nums"`, `"normal"`. An NSH addition (CSS's `font-variant-numeric`); setting `font` keeps it. Browsers ignore it. |
| `textAlign`, `textBaseline` | `.text_align(..)`, `.text_baseline(..)` | Text placement. |

**Transforms**: `translate(x, y)`, `scale(x, y)`, `rotate(angle)` (radians, clockwise), `transform(a, b, c, d, e, f)`, `setTransform(a, b, c, d, e, f)`, `resetTransform()`.

**Paths**: `beginPath()`, `moveTo`, `lineTo`, `quadraticCurveTo`, `bezierCurveTo`, `arc`, `arcTo`, `ellipse`, `rect`, `roundRect(x, y, w, h, radii)`, `closePath()`; then `fill(rule?)`, `stroke()` and `clip(rule?)`, each also taking a path (`fill_path`, `stroke_path`, `clip_path` in Rust). Fill rules are `"nonzero"` and `"evenodd"`.

**Rectangles**: `fillRect`, `strokeRect`, `clearRect`.

**Text**: `fillText(text, x, y, maxWidth?)`, `strokeText(...)`, `measureText(text)` (measured synchronously by the platform's text engine with the current `font`; only `width`). In Rust, `measure_text(font, text)` gives the width.

**Hit testing**: `isPointInPath(path?, x, y, rule?)` and `isPointInStroke(path?, x, y)` (`path_contains`, `stroke_contains`, `is_point_in_path` and `is_point_in_stroke` on a `Painter`) answer synchronously, computed from the recorded geometry (the current transform, path, `lineWidth` and `lineCap`). Keep the drawing and the paths you drew to find the shape under a tap:

```rust
let slices: Rc<Vec<Path>> = Rc::new(vec![svg_path("M50 50 L100 50 A50 50 0 0 1 50 100 Z") /* , ... */]);
let draw = {
    let slices = slices.clone();
    move || slices.iter().fold(Painter::new(), |p, s| p.fill_path(s, FillRule::NonZero))
};

canvas(draw.clone())
    .size(px(100.0))
    .claim_touches(TouchClaim::on_start())
    .on_responder_release(move |e: &ResponderEvent| {
        let drawing = draw();
        if let Some(hit) = slices.iter().position(|s| drawing.path_contains(s, e.location, FillRule::NonZero)) {
            selected.set(Some(hit));
        }
    })
```

```tsx
let cx: CanvasRenderingContext2D | undefined;
const slices = [new Path2D("M50 50 L100 50 A50 50 0 0 1 50 100 Z"), /* ... */];

<Canvas
  style={{ width: 100, height: 100 }}
  onStartShouldSetResponder={() => true}
  onResponderRelease={(e) => {
    const hit = slices.findIndex((p) => cx?.isPointInPath(p, e.locationX, e.locationY));
    if (hit >= 0) select(hit);
  }}
  draw={(c) => {
    cx = c;
    slices.forEach((p) => c.fill(p));
  }}
/>
```

Strokes are tested with round joins and without dashes; coordinates given as animated values count as 0.

**Gradients**: `createLinearGradient`, `createRadialGradient`, `createConicGradient`, each with `addColorStop(offset, color)` (`CanvasGradient::linear`, `radial`, `conic` and `add_color_stop` in Rust).

**Images**: `drawImage(image, dx, dy)`, `drawImage(image, dx, dy, dw, dh)`, `drawImage(image, sx, sy, sw, sh, dx, dy, dw, dh)` (`draw_image(url, dest)` and `draw_image_part(..)` in Rust).

`cx.canvas.width` and `cx.canvas.height` give the canvas's size in points in TSX.

**The supported set**: drawing operations. Pixels are written by the platform, so `getImageData` / `putImageData` and other pixel access are outside it, as are `filter` and SVG images in `drawImage`. An invalid color or font drops that one operation, as in HTML Canvas.

## Paths and SVG path data

A path built once can be filled, stroked or clipped many times: `svg_path(d)` in Rust, `Path2D` in TSX. Both take SVG path data, parsed natively, which makes icons easy:

```rust
use nsh_core::canvas::{FillRule, svg_path};

const HEART: &str = "M12 21s-7-4.35-9.5-8.5C.5 8.5 3 4 7 4c2 0 3.5 1 5 3 1.5-2 3-3 5-3 4 0 6.5 4.5 4.5 8.5C19 16.65 12 21 12 21z";

fn heart(size: f32, color: Rgba) -> impl IntoElement {
    let path = svg_path(HEART);
    canvas(
        Painter::new()
            .scale(size / 24.0, size / 24.0) // the path is drawn on a 24-point grid
            .fill_color(color)
            .fill_path(&path, FillRule::NonZero),
    )
    .size(px(size))
}
```

```tsx
import { Canvas, Path2D } from "nsh";

const heart = new Path2D("M12 21s-7-4.35-9.5-8.5C.5 8.5 3 4 7 4c2 0 3.5 1 5 3 1.5-2 3-3 5-3 4 0 6.5 4.5 4.5 8.5C19 16.65 12 21 12 21z");

function Heart(props: { size: number; color: string }) {
  return (
    <Canvas
      style={{ width: props.size, height: props.size }}
      draw={(cx) => {
        cx.scale(props.size / 24, props.size / 24); // the path is drawn on a 24-point grid
        cx.fillStyle = props.color;
        cx.fill(heart);
      }}
    />
  );
}
```

A `Path2D` has the same path methods as the context (`moveTo`, `arc`, `roundRect`, ...) and `addPath(other)`. `new Path2D(other)` copies a path.

## Gradients

```rust
canvas(move || {
    let (w, h) = (width.get(), 120.0);
    let linear = CanvasGradient::linear(point(px(0.0), px(0.0)), point(px(w), px(0.0)))
        .add_color_stop(percentage(0.0), rgb(0x22d3ee))
        .add_color_stop(percentage(1.0), rgb(0x6366f1));
    let center = point(px(w / 2.0), px(h * 0.75));
    let radial = CanvasGradient::radial(center, px(4.0), center, px(40.0))
        .add_color_stop(percentage(0.0), rgb(0xfde68a))
        .add_color_stop(percentage(1.0), rgb(0xf97316));
    Painter::new()
        .fill_style(linear)
        .fill_rect(0.0, 0.0, w, h / 2.0)
        .fill_style(radial)
        .begin_path()
        .arc(w / 2.0, h * 0.75, 28.0, 0.0, TAU)
        .fill()
})
.h(px(120.0))
.on_layout(move |frame: &Bounds<Points>| width.set(frame.size.width.0))
```

```tsx
<Canvas
  style={{ height: 120 }}
  draw={(cx, { width, height }) => {
    const linear = cx.createLinearGradient(0, 0, width, 0);
    linear.addColorStop(0, "#22d3ee");
    linear.addColorStop(1, "#6366f1");
    cx.fillStyle = linear;
    cx.fillRect(0, 0, width, height / 2);

    const radial = cx.createRadialGradient(width / 2, height * 0.75, 4, width / 2, height * 0.75, 40);
    radial.addColorStop(0, "#fde68a");
    radial.addColorStop(1, "#f97316");
    cx.fillStyle = radial;
    cx.beginPath();
    cx.arc(width / 2, height * 0.75, 28, 0, Math.PI * 2);
    cx.fill();
  }}
/>
```

A conic gradient (`createConicGradient(startAngle, x, y)`, `CanvasGradient::conic(start_angle, center)`) sweeps colors around a point; its start angle is in radians, clockwise from the x axis. A conic gradient on a stroked arc makes a gradient progress ring.

## Text

```rust
Painter::new()
    .font("600 20px system-ui")
    .fill_color(rgb(0x1f2328))
    .text_align(CanvasTextAlign::Center)
    .text_baseline(CanvasTextBaseline::Middle)
    .fill_text("72%", width / 2.0, height / 2.0)
    .font("11px system-ui")
    .fill_text("100", 32.0 - 6.0 - measure_text("11px system-ui", "100").0, 16.0)
```

```tsx
cx.font = "600 20px system-ui";
cx.fillStyle = "#1f2328";
cx.textAlign = "center";
cx.textBaseline = "middle";
cx.fillText("72%", width / 2, height / 2);

cx.font = "11px system-ui";
const label = "100";
cx.fillText(label, 32 - 6 - cx.measureText(label).width, 16);
```

Font families are the same as in styles: system families and the names of fonts your app ships (see [Fonts](https://nsh.dev/versions/main/docs/fonts.md)).

## Images

Drawing an image takes a URL in Rust (an asset's is `LOGO.url`), and a URL or an imported asset (`import logo from "./logo.png"`) in TSX. The image is loaded natively, and the canvas draws again once it has loaded, so you do not need to track loading yourself. Remote URLs are subject to the app's [network capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md).

Canvases on iOS, macOS, Android, Windows, Linux and GPUI draw bitmap images (PNG, JPEG, GIF, WebP, ...); on them, an SVG source is an image that fails to load, and the log names it. Show SVG images with [`<Image>`](https://nsh.dev/versions/main/docs/images-and-assets.md#svg-images), or draw their shapes as `Path2D` paths. On the web, a canvas draws what the browser draws, SVG included.

```rust
const LOGO: ImageAsset = asset!("logo.png");

canvas(
    Painter::new()
        .save()
        .begin_path()
        .arc(60.0, 60.0, 56.0, 0.0, TAU)
        .clip() // a round avatar
        .draw_image(LOGO.url, bounds(point(px(4.0), px(4.0)), size(px(112.0), px(112.0))))
        .restore(),
)
.size(px(120.0))
```

```tsx
import { Canvas } from "nsh";
import logo from "./logo.png";

<Canvas
  style={{ width: 120, height: 120 }}
  draw={(cx) => {
    cx.save();
    cx.beginPath();
    cx.arc(60, 60, 56, 0, Math.PI * 2);
    cx.clip(); // a round avatar
    cx.drawImage(logo, 4, 4, 112, 112);
    cx.restore();
  }}
/>
```

The nine-argument form (`draw_image_part`) takes the source rectangle in the image's pixels.

## Driving drawings with animated values

Any number argument of a drawing call, and the fill and stroke paints, can be an [animated value](https://nsh.dev/versions/main/docs/animation.md#animated-values) or a node derived from it. Such arguments are read while the platform draws, and when the value animates, the platform redraws on its own, every frame, without recording the drawing again or running any of your code.

```rust
use std::f32::consts::{FRAC_PI_2, TAU};

use nsh_core::{
    canvas::{CanvasTextAlign, CanvasTextBaseline, LineCap},
    prelude::*,
};

pub fn ring() -> impl IntoElement {
    let progress = animated_value(0.3);
    let label = signal(30_u32);
    let go = move |to: f32| {
        label.set((to * 100.0).round() as u32);
        progress.timing(to, 900.0, Easing::Curve(Curve::Cubic, EaseMode::InOut));
    };
    let (center_x, cy, r) = (70.0, 70.0, 60.0);
    view()
        .flex_1()
        .items_center()
        .justify_center()
        .gap_4()
        .child(
            canvas(move || {
                // The end angle reads the animated value on every frame.
                let end = progress.mul(TAU).sub(FRAC_PI_2);
                Painter::new()
                    .line_width(12.0)
                    .line_cap(LineCap::Round)
                    .stroke_color(rgb(0xe5e7eb))
                    .begin_path()
                    .arc(center_x, cy, r, 0.0, TAU)
                    .stroke()
                    .stroke_color(rgb(0x6366f1))
                    .begin_path()
                    .arc(center_x, cy, r, -FRAC_PI_2, &end)
                    .stroke()
                    .fill_color(rgb(0x1f2328))
                    .font("600 22px system-ui")
                    .text_align(CanvasTextAlign::Center)
                    .text_baseline(CanvasTextBaseline::Middle)
                    .fill_text(&format!("{}%", label.get()), center_x, cy)
            })
            .size(px(140.0)),
        )
        .child(
            text("Animate")
                .text_color(rgb(0x0969da))
                .on_press(move || go(if label.get_untracked() < 50 { 0.85 } else { 0.2 })),
        )
}
```

```tsx
import { Canvas, mount, signal, Text, View } from "nsh";
import { createAnimatedValue, Easing } from "nsh";

function Ring() {
  const progress = createAnimatedValue(0.3);
  const label = signal(30);
  const go = (to: number) => {
    label.set(Math.round(to * 100));
    progress.timing(to, { duration: 900, easing: Easing.inOut(Easing.cubic) });
  };
  return (
    <View style={{ flex: 1, alignItems: "center", justifyContent: "center", gap: 16 }}>
      <Canvas
        style={{ width: 140, height: 140 }}
        draw={(cx, { width, height }) => {
          const centerX = width / 2, cy = height / 2, r = width / 2 - 10;
          cx.lineWidth = 12;
          cx.lineCap = "round";
          cx.strokeStyle = "#e5e7eb";
          cx.beginPath();
          cx.arc(centerX, cy, r, 0, Math.PI * 2);
          cx.stroke();
          cx.strokeStyle = "#6366f1";
          cx.beginPath();
          // The end angle reads the animated value on every frame.
          cx.arc(centerX, cy, r, -Math.PI / 2, progress.mul(Math.PI * 2).sub(Math.PI / 2));
          cx.stroke();
          cx.fillStyle = "#1f2328";
          cx.font = "600 22px system-ui";
          cx.textAlign = "center";
          cx.textBaseline = "middle";
          cx.fillText(`${label()}%`, centerX, cy);
        }}
      />
      <View onPress={() => go(Math.random())}>
        <Text style={{ color: "#0969da" }}>Animate</Text>
      </View>
    </View>
  );
}

mount(Ring);
```

The arc's end angle is `progress.mul(2π).sub(π/2)`: a node, so the ring sweeps natively for 900 ms while the drawing was recorded once (and once more for the label, which reads a signal). A clock's second hand works the same way: `rotate(seconds.mul(π / 30))` with `seconds` animated linearly.

Colors animate the same way: `.fill_style(&t.interpolate_colors(&[0.0, 1.0], &[rgb(0x54aeff), rgb(0xcf222e)]))` in Rust, `cx.fillStyle = t.interpolate({ inputRange: [0, 1], outputRange: ["#54aeff", "#cf222e"] })` in TSX.

## Touch on a canvas

A canvas is a view, so it takes presses and the [responder system](https://nsh.dev/versions/main/docs/touch-and-gestures.md#the-responder-system). Finger drawing records points in a signal and draws them:

```rust
let strokes = signal(Vec::<Vec<(f32, f32)>>::new());

canvas(move || {
    strokes.with(|strokes| {
        let mut p = Painter::new().line_width(3.0).line_cap(LineCap::Round).line_join(LineJoin::Round);
        for stroke in strokes {
            p = p.begin_path();
            for (i, &(x, y)) in stroke.iter().enumerate() {
                p = if i == 0 { p.move_to(x, y) } else { p.line_to(x, y) };
            }
            p = p.stroke();
        }
        p
    })
})
.h(px(240.0))
.claim_touches(TouchClaim::on_start())
.keep_touches(true) // a scroll view around must not take the touches
.on_responder_grant(move |e: &ResponderEvent| {
    strokes.update(|s| s.push(vec![(e.location.x.0, e.location.y.0)]))
})
.on_responder_move(move |e: &ResponderEvent| {
    strokes.update(|s| {
        if let Some(stroke) = s.last_mut() {
            stroke.push((e.location.x.0, e.location.y.0));
        }
    })
})
```

```tsx
const strokes = signal<[number, number][][]>([]);

<Canvas
  style={{ height: 240 }}
  onStartShouldSetResponder={() => true}
  onResponderGrant={(e) => {
    strokes.set([...strokes(), [[e.locationX, e.locationY]]]);
    return true; // a scroll view around must not take the touches
  }}
  onResponderMove={(e) => {
    const all = strokes();
    strokes.set([...all.slice(0, -1), [...all[all.length - 1], [e.locationX, e.locationY]]]);
  }}
  draw={(cx) => {
    cx.lineWidth = 3;
    cx.lineCap = "round";
    cx.lineJoin = "round";
    for (const s of strokes()) {
      cx.beginPath();
      s.forEach(([x, y], i) => (i === 0 ? cx.moveTo(x, y) : cx.lineTo(x, y)));
      cx.stroke();
    }
  }}
/>
```

## Performance

- A drawing is recorded in Rust (in TSX, as JS calls the context) and travels to the platform as one operation; there is no per-call bridge crossing.
- Each drawing re-records everything. Keep the work proportional to what is shown, and keep data that changes every frame in animated values rather than signals.
- Split a drawing that has a static part and a frequently changing part into two canvases stacked on top of each other, so only one redraws.
- Inside a zooming scroll view, canvases are drawn again at the zoomed resolution when the zoom ends.

## Related

- [`Canvas` element](https://nsh.dev/versions/main/elements/canvas.md): the reference.
- [Animation](https://nsh.dev/versions/main/docs/animation.md): animated values, `interpolate` and `Easing`.
- [Images and assets](https://nsh.dev/versions/main/docs/images-and-assets.md): the app's images.

Source: https://nsh.dev/versions/main/docs/canvas

---

# Web view and video

The web view and the video player embed the platform's own web engine and media player as ordinary views: `web_view` and `video` in Rust (`nsh_core::prelude`), `WebView` and `Video` from `nsh` in TSX. Because NSH renders with native views, they sit in your layout like any other element: they scroll with their parent, take rounded corners and clipping, and other views can overlap them without layering problems.

| Component | iOS | Android | macOS | Linux | Windows |
|---|---|---|---|---|---|
| `WebView` | WKWebView | `android.webkit.WebView` | WKWebView | WebKitGTK 6.0's `WebKitWebView` | WebView2, in a child window |
| `Video` | AVPlayerLayer; AVPlayerViewController with `controls` | MediaPlayer on a TextureView; MediaController with `controls` | AVPlayerLayer; AVKit's AVPlayerView with `controls` | GTK's media stream (GStreamer) in a `GtkPicture`; `GtkVideo` with `controls` | Media Foundation's media engine, frames drawn with Direct2D; NSH's own control bar with `controls` |

The frameworks behind them (WebKit, AVFoundation) are loaded the first time an app uses one, so apps that never show a web page or a video do not pay for them at launch.

On [macOS](https://nsh.dev/versions/main/docs/macos.md) the web view has no scroll view of its own: with `scrollable={false}` the mouse wheel and the
trackpad scroll the app's scroll views around it instead of the page, which still scrolls with its keyboard and its
own scripts.

On [Linux](https://nsh.dev/versions/main/docs/linux.md) a web view is a WebKitGTK page drawn inside its view: NSH content over it (a dialog, a sheet)
covers it, and its parents clip it. The `webview` capability also applies to the navigations of frames there (an
`iframe` of a host that is not granted stays empty), and `scrollable: false` stops the page itself from scrolling
(elements inside it still scroll). Apps need WebKitGTK 6.0 installed; a runtime built without it shows a neutral
placeholder. Videos play the formats the installed GStreamer plugins decode; `rate` is not supported (they
play at 1×), and `onEnd` only comes for videos that do not loop.

On [Windows](https://nsh.dev/versions/main/docs/windows.md) a web view is a WebView2 control in a child window that follows its view: it is clipped to
its parents and rounded corners, but NSH content drawn over it (a dialog, a sheet) stays under it. It needs the
WebView2 Runtime (part of Windows 11; installed with Edge on Windows 10), else it shows a placeholder;
`baseUrl` for HTML, `scrollable` and `allowsBackForwardNavigationGestures` are not supported. Videos are
ordinary content (clipped, transformed and covered like any view) and play the formats the installed Media Foundation
codecs decode; `rate` works, there is no poster, and the control bar always shows while `controls` is on.

## WebView

```rust
use nsh_core::prelude::*;

#[component]
pub fn App() -> impl IntoElement {
    web_view("https://en.m.wikipedia.org/wiki/Swift_(programming_language)").flex_1()
}
```

```tsx
import { mount, WebView } from "nsh";

function App() {
  return <WebView src="https://en.m.wikipedia.org/wiki/Swift_(programming_language)" style={{ flex: 1 }} />;
}

mount(App);
```

### Sources

A web view shows one of `src` and `html`:

| Props | Shows |
|---|---|
| `src="https://…"` | A web page. |
| `html="<!doctype html>…"` | HTML from a string, shown instead of `src`. |
| `html` with `baseUrl="https://example.com/"` | HTML whose relative URLs resolve against `baseUrl`. |

In Rust, `web_view(url)` shows a page and `web_view_html(html, base_url)` shows HTML (`base_url` an `Option<&str>`); the URL and the HTML can be a signal or a closure, which loads the page again when what it reads changes. Changing `src` or `html` loads the new page.

### Props

In Rust each prop is a builder method in snake case (`injected_java_script`, `java_script_enabled`, `scrollable`, `user_agent`; `injected_java_script_before_content` for `injectedJavaScriptBeforeContentLoaded`, `back_forward_gestures` for iOS's `allowsBackForwardNavigationGestures`) and each event an `on_…` method (`on_navigation_state_change`) whose listener gets a `WebNavigation` (`url`, `title`, `loading`, `can_go_back`, `can_go_forward`) or, for `on_error` and `on_message`, a `&str`.

| Prop | Type | Default | Description |
|---|---|---|---|
| `src` | `string` | | The URL of the page to show. |
| `html` | `string` | | Inline HTML, shown instead of `src`. |
| `baseUrl` | `string` | | What `html`'s relative URLs resolve against. |
| `injectedJavaScript` | `string` | | Runs after each page loads. |
| `injectedJavaScriptBeforeContentLoaded` | `string` | | Runs before each page's own scripts. |
| `javaScriptEnabled` | `boolean` | `true` | Pages run scripts. |
| `scrollable` | `boolean` | `true` | The user can scroll the page. |
| `userAgent` | `string` | | The browser's user agent string. |
| `ios={{ allowsBackForwardNavigationGestures }}` | `boolean` | | iOS: swipe back and forward through the page history. |
| `desktop={{ allowsBackForwardNavigationGestures }}` | `boolean` | | macOS: swipe with two fingers on the trackpad to go back and forward; Windows: swipe on a touchscreen; Linux: swipe on the touchpad. |

Events:

| Event | Payload | When |
|---|---|---|
| `onLoadStart` | `WebViewNavigation` | A page started loading. |
| `onLoad` | `WebViewNavigation` | A page finished loading. |
| `onError` | `{ message }` | Loading failed. |
| `onNavigationStateChange` | `WebViewNavigation` | The URL, title, loading state or history changed. |
| `onMessage` | `{ data: string }` | The page posted a message (below). |

`WebViewNavigation` is `{ url, title, loading, canGoBack, canGoForward }`.

### A browser with back and forward

The web view's ref (an `element_ref()` put on it with `.element_ref(&web)` in Rust, `ref` in TSX) has `reload`, `go_back` / `goBack`, `go_forward` / `goForward`, `stop_loading` / `stopLoading`, `inject_java_script` / `injectJavaScript(script)`, `post_message` / `postMessage(data)` and `send_input` / `sendInput(input)` ([below](#input-as-the-users-own)):

```rust
use nsh_core::prelude::*;

pub fn browser() -> impl IntoElement {
    let web = element_ref();
    let nav = signal(None::<WebNavigation>);
    let button = move |label: &'static str, enabled: fn(&WebNavigation) -> bool, action: fn(&ElementRef)| {
        let enabled = move || nav.with(|n| n.as_ref().is_some_and(enabled));
        text(label)
            .p(px(12.0))
            .text_color(move || if enabled() { rgb(0x0969da) } else { rgb(0x8c959f) })
            .disabled(move || !enabled())
            .on_press(move || action(&web))
    };
    view()
        .flex_1()
        .pt(px(50.0))
        .child(
            text(move || {
                nav.with(|n| match n {
                    Some(n) if n.loading => "Loading…".to_owned(),
                    Some(n) => n.title.clone(),
                    None => String::new(),
                })
            })
            .number_of_lines(1)
            .px(px(12.0))
            .text_color(rgb(0x57606a)),
        )
        .child(
            web_view("https://developer.mozilla.org/")
                .element_ref(&web)
                .flex_1()
                .on_navigation_state_change(move |n: &WebNavigation| nav.set(Some(n.clone())))
                .back_forward_gestures(true),
        )
        .child(
            view()
                .flex_row()
                .justify_around()
                .child(button("Back", |n| n.can_go_back, |web| web.go_back()))
                .child(button("Forward", |n| n.can_go_forward, |web| web.go_forward()))
                .child(button("Reload", |_| true, |web| web.reload())),
        )
}
```

```tsx
import { mount, signal, Text, View, WebView, type WebViewNavigation, type WebViewRef } from "nsh";

function Browser() {
  let web!: WebViewRef;
  const nav = signal<WebViewNavigation | null>(null);
  const button = (label: string, enabled: boolean, action: () => void) => (
    <Text onPress={enabled ? action : undefined} style={{ padding: 12, color: enabled ? "#0969da" : "#8c959f" }}>
      {label}
    </Text>
  );
  return (
    <View style={{ flex: 1, paddingTop: 50 }}>
      <Text style={{ numberOfLines: 1, paddingHorizontal: 12, color: "#57606a" }}>
        {nav()?.loading ? "Loading…" : nav()?.title ?? ""}
      </Text>
      <WebView
        ref={web}
        src="https://developer.mozilla.org/"
        style={{ flex: 1 }}
        onNavigationStateChange={(n) => nav.set(n)}
        ios={{ allowsBackForwardNavigationGestures: true }}
      />
      <View style={{ flexDirection: "row", justifyContent: "space-around" }}>
        {button("Back", !!nav()?.canGoBack, () => web.goBack())}
        {button("Forward", !!nav()?.canGoForward, () => web.goForward())}
        {button("Reload", true, () => web.reload())}
      </View>
    </View>
  );
}

mount(Browser);
```

### Messaging between the page and the app

Pages talk to the app with `window.nsh.postMessage(string)`, which arrives as `on_message` (`onMessage`). The app talks to the page with the ref's `post_message` (`postMessage(string)`), which arrives in the page as a `message` event on `window`. Messages are strings; send JSON for structured data.

```rust
use nsh_core::prelude::*;

const PAGE: &str = r#"<!doctype html>
<html><head><meta name="viewport" content="width=device-width"></head>
<body style="font-family: -apple-system, sans-serif; margin: 16px">
  <button onclick="window.nsh.postMessage(JSON.stringify({ type: 'hello', at: Date.now() }))">
    Post to the app
  </button>
  <p id="got">Nothing from the app yet.</p>
  <script>
    window.addEventListener("message", (e) => {
      document.getElementById("got").textContent = "The app says: " + e.data;
    });
  </script>
</body></html>"#;

#[component]
pub fn App() -> impl IntoElement {
    let web = element_ref();
    let last = signal(String::new());
    view()
        .flex_1()
        .pt(px(50.0))
        .gap(px(12.0))
        .child(
            web_view_html(PAGE, None)
                .element_ref(&web)
                .h(px(240.0))
                .on_message(move |data: &str| {
                    let message: serde_json::Value = serde_json::from_str(data).unwrap_or_default();
                    last.set(message["type"].as_str().unwrap_or_default().to_owned());
                }),
        )
        .child(
            text("Post to the page")
                .p(px(16.0))
                .text_color(rgb(0x0969da))
                .on_press(move || web.post_message("hi from nsh")),
        )
        .child(text(move || format!("Last message: {}", last.get())).px(px(16.0)))
}
```

```tsx
import { mount, signal, Text, View, WebView, type WebViewRef } from "nsh";

const page = `<!doctype html>
<html><head><meta name="viewport" content="width=device-width"></head>
<body style="font-family: -apple-system, sans-serif; margin: 16px">
  <button onclick="window.nsh.postMessage(JSON.stringify({ type: 'hello', at: Date.now() }))">
    Post to the app
  </button>
  <p id="got">Nothing from the app yet.</p>
  <script>
    window.addEventListener("message", (e) => {
      document.getElementById("got").textContent = "The app says: " + e.data;
    });
  </script>
</body></html>`;

function App() {
  let web!: WebViewRef;
  const last = signal("");
  return (
    <View style={{ flex: 1, paddingTop: 50, gap: 12 }}>
      <WebView
        ref={web}
        html={page}
        style={{ height: 240 }}
        onMessage={(e) => last.set(JSON.parse(e.data).type)}
      />
      <Text onPress={() => web.postMessage("hi from nsh")} style={{ padding: 16, color: "#0969da" }}>
        Post to the page
      </Text>
      <Text style={{ paddingHorizontal: 16 }}>Last message: {last()}</Text>
    </View>
  );
}

mount(App);
```

The ref's `inject_java_script` (`injectJavaScript(script)`) runs code in the current page at any time; `injected_java_script` and `injected_java_script_before_content` (`injectedJavaScript`, `injectedJavaScriptBeforeContentLoaded`) run on every page load, before or after the page's own scripts, which is the place to install hooks:

```rust
web_view("https://example.com")
    .injected_java_script_before_content("window.isNativeApp = true;")
    .injected_java_script("window.nsh.postMessage(document.title);")
    .on_message(|title: &str| log::info!("title {title}"))
```

```tsx
<WebView
  src="https://example.com"
  injectedJavaScriptBeforeContentLoaded={`window.isNativeApp = true;`}
  injectedJavaScript={`window.nsh.postMessage(document.title);`}
  onMessage={(e) => console.log("title", e.data)}
/>
```

### Input as the user's own

`injectJavaScript` can only make synthetic events, which a page sees as untrusted (`event.isTrusted` is `false`) and some widgets ignore. The ref's `send_input` (`sendInput(input)`) gives the page input as the user's own hands would, so its events are trusted:

- `{ type: "click", x, y }` clicks a point of the viewport, in CSS pixels (what `getBoundingClientRect()` reports).
- `{ type: "text", text }` types the text into what has the page's focus, a key at a time: each character on the US layout's key for it, a line break as Enter, and what no US key types (`é`, CJK, emoji) on no key (`code` is `"Unidentified"`).
- `{ type: "key", key }` presses `Enter`, `Tab`, `Escape` or `Backspace`.

```rust
use nsh_core::{WebInput, WebKey, prelude::*};
use std::time::Duration;

fn search(web: &ElementRef) {
    web.send_input(WebInput::Click { x: px(120.0), y: px(40.0) });
    let web = *web;
    set_timeout(Duration::from_millis(50), move || {
        web.send_input(WebInput::Text("espresso".into()));
        web.send_input(WebInput::Key(WebKey::Enter));
    });
}
```

```tsx
web.sendInput({ type: "click", x: 120, y: 40 });
setTimeout(() => {
  web.sendInput({ type: "text", text: "espresso" });
  web.sendInput({ type: "key", key: "Enter" });
}, 50);
```

In Rust these are `WebInput::Click { x, y }`, `WebInput::Text(text)` and `WebInput::Key(WebKey::Enter)`.

Trusted input carries user activation (it may open windows, write the clipboard, open the system's file panel or press a page's confirm button), so it is a capability of its own: the app needs `"webview": { "input": true }` in `nsh.json`'s `capabilities` ([`webview`](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md#webview)), also when it declares none, and the core drops the call otherwise.

Like a click, `sendInput` takes the keyboard focus for the web view, away from the app's own `Input`. The page handles input on its own schedule: a click's events can still be on their way when the next call starts, so let a click settle (a frame or so) before typing after it. macOS delivers the input; the other platforms ignore it for now.

Before offering anything that depends on it, ask whether it works here: `web_input_available()` (`WebView.inputAvailable()`) resolves `true` only where the platform delivers the input and the app holds `webview.input`, so it is `false` on platforms that ignore the call and in apps without the grant.

```rust
use nsh_core::prelude::*;

let input = signal(false);
spawn(async move { input.set(web_input_available().await) });
```

```tsx
import { signal, WebView } from "nsh";

const input = signal(false);
WebView.inputAvailable().then((available) => input.set(available));
```

### Which sites a web view may show

If your `nsh.json` declares `"capabilities"`, a web view may only show and navigate to the hosts listed under `webview`:

```json
{
  "capabilities": {
    "webview": { "hosts": ["example.com", "*.example.com"] }
  }
}
```

The check covers the web view's `src` and every top-level navigation the page makes (links, redirects, `location` changes); it is decided natively when the platform asks whether a navigation may proceed. A page's own subresources (scripts, images, frames) are the web content's business and are not checked. `*.example.com` matches subdomains only; list `example.com` as well for the bare domain. An app without a `"capabilities"` key may show any page. See [Sandbox and capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md).

## Video

```rust
use nsh_core::prelude::*;

pub fn player() -> impl IntoElement {
    let player = element_ref();
    let paused = signal(true);
    let time = signal(String::new());
    let link = |label: &'static str| text(label).text_color(rgb(0x0969da));
    view()
        .flex_1()
        .justify_center()
        .p(px(16.0))
        .gap(px(12.0))
        .child(
            video("https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4")
                .element_ref(&player)
                .paused(paused)
                .repeat(true)
                .object_fit(ResizeMode::Contain)
                .h(px(220.0))
                .rounded(px(12.0))
                .overflow_hidden()
                .bg(rgb(0x000000))
                .on_progress(move |e: &VideoProgress| {
                    time.set(format!("{:.1} / {:.1} s", e.current_time, e.duration))
                })
                .on_end(move || paused.set(true)),
        )
        .child(
            view()
                .flex_row()
                .gap(px(16.0))
                .items_center()
                .child(
                    text(move || if paused.get() { "Play" } else { "Pause" })
                        .text_color(rgb(0x0969da))
                        .font_weight(FontWeight::SEMIBOLD)
                        .on_press(move || paused.update(|p| *p = !*p)),
                )
                .child(link("Restart").on_press(move || player.seek(0.0)))
                .child(text(move || time.get()).text_color(rgb(0x57606a))),
        )
}
```

```tsx
import { mount, signal, Text, Video, type VideoRef, View } from "nsh";

function Player() {
  let video!: VideoRef;
  const paused = signal(true);
  const time = signal("");
  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 16, gap: 12 }}>
      <Video
        ref={video}
        src="https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4"
        paused={paused()}
        repeat
        style={{ height: 220, borderRadius: 12, overflow: "hidden", backgroundColor: "#000000" }}
        onProgress={(e) => time.set(`${e.currentTime.toFixed(1)} / ${e.duration.toFixed(1)} s`)}
        onEnd={() => paused.set(true)}
      />
      <View style={{ flexDirection: "row", gap: 16, alignItems: "center" }}>
        <Text onPress={() => paused.set(!paused())} style={{ color: "#0969da", fontWeight: "600" }}>
          {paused() ? "Play" : "Pause"}
        </Text>
        <Text onPress={() => video.seek(0)} style={{ color: "#0969da" }}>
          Restart
        </Text>
        <Text style={{ color: "#57606a" }}>{time()}</Text>
      </View>
    </View>
  );
}

mount(Player);
```

Playback is controlled by props: set `paused`, `muted`, `volume` and `rate` from signals and the player follows. The ref has `seek(seconds)`.

In Rust, `video(url)` makes the player (the URL a value, a signal or a closure) and each prop is a builder method in snake case (`paused`, `repeat(true)`, `object_fit(ResizeMode::Contain)` (the `objectFit` style), `progress_interval` for `progressUpdateInterval`); `on_load` gets a `VideoInfo` (`duration`, `size`), `on_progress` a `VideoProgress` (`current_time`, `duration`) and `on_buffer` a `bool`.

| Prop | Type | Default | Description |
|---|---|---|---|
| `src` | `string` | | The video's URL. |
| `paused` | `boolean` | `false` | Playback is paused. |
| `muted` | `boolean` | `false` | No sound. |
| `volume` | `number` | `1` | 0..1. |
| `rate` | `number` | `1` | The playback speed. |
| `repeat` | `boolean` | `false` | Plays again from the start at the end. |
| `objectFit` (style), `object-*` classes | `"cover" \| "contain" \| "fill" \| "none" \| "scale-down"` | `"contain"` | How the picture fits the view, as CSS's `object-fit` (`class="object-cover"`). |
| `controls` | `boolean` | `false` | The platform's playback controls. |
| `progressUpdateInterval` | `number` | `250` | Milliseconds between `onProgress` events. |

| Event | Payload | When |
|---|---|---|
| `onLoadStart` | | Loading started. |
| `onLoad` | `{ duration, size }` | The video is ready: its length in seconds and its size. |
| `onProgress` | `{ currentTime, duration }` | While playing, every `progressUpdateInterval` ms. |
| `onBuffer` | `{ isBuffering }` | Playback stalled waiting for data, or resumed. |
| `onEnd` | | Playback reached the end. |
| `onError` | `{ message }` | Loading or playback failed. |

With `controls`, the platform draws its own play button, scrubber and full-screen button. Without, draw your own with views over or below the video; since the video is a native view in your layout, overlays work naturally:

```rust
view()
    .h(px(220.0))
    .child(video(url).paused(paused).flex_1())
    .child(
        view()
            .absolute()
            .inset_0()
            .items_center()
            .justify_center()
            .on_press(move || paused.update(|p| *p = !*p))
            .child(when(move || paused.get(), || {
                text("▶").text_size(px(48.0)).text_color(rgb(0xffffff))
            })),
    )
```

```tsx
<View style={{ height: 220 }}>
  <Video src={url} paused={paused()} style={{ flex: 1 }} />
  <View
    onPress={() => paused.set(!paused())}
    style={{ position: "absolute", top: 0, left: 0, right: 0, bottom: 0, alignItems: "center", justifyContent: "center" }}
  >
    <If when={paused()}>
      <Text style={{ fontSize: 48, color: "#ffffff" }}>▶</Text>
    </If>
  </View>
</View>
```

Video sources are network requests: with declared capabilities, the video's host must be allowed under `network` in `nsh.json`, as for `fetch` and remote images. A refused source shows nothing, and the refusal is logged once with the key to add.

## Related

- [`WebView`](https://nsh.dev/versions/main/elements/web-view.md) and [`Video`](https://nsh.dev/versions/main/elements/video.md): the element references.
- [Sandbox and capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md): `webview` and `network` grants.
- [Native components](https://nsh.dev/versions/main/docs/native-components.md): embedding other native views your host app provides.

Source: https://nsh.dev/versions/main/docs/web-view-and-video

---

# Networking

NSH apps make HTTP requests with `fetch`: in Rust the function of `nsh_core::prelude`, awaited in a task, and in TSX the standard global. Both run on the platform's network stack (NSURLSession on iOS, HttpURLConnection on Android, the browser's [on the web](https://nsh.dev/versions/main/docs/web.md#apps-with-rust-components)), so requests use the system's TLS, proxies and HTTP/2, and both pass the same [capability checks](#capabilities-which-hosts-an-app-may-reach). Rust's `fetch` takes a URL or an `HttpRequest` and gives the whole response (`HttpResponse`: `status()`, `ok()`, `header(name)`, `text()`, `body`). TSX's streams both ways: a response body arrives as a stream as the stack delivers it, and a request body can be a stream sent as you produce it. TSX has the Fetch API's companions too: `Headers`, `Request`, `Response`, `AbortController`, `FormData`, `Blob`, `File`, `URL`, `URLSearchParams`, `TextEncoder` / `TextDecoder` and Web Streams.

## Getting JSON

```rust
use nsh_core::prelude::*;

#[derive(Clone, PartialEq)]
struct Post {
    id: u64,
    title: String,
}

fn parse(body: &str) -> Result<Vec<Post>, String> {
    let posts: Vec<serde_json::Value> = serde_json::from_str(body).map_err(|e| e.to_string())?;
    Ok(posts
        .iter()
        .map(|p| Post {
            id: p["id"].as_u64().unwrap_or_default(),
            title: p["title"].as_str().unwrap_or_default().to_owned(),
        })
        .collect())
}

#[component]
fn App() -> impl IntoElement {
    let posts = resource(
        || Some(()),
        |(), _| async move {
            let response = fetch("https://jsonplaceholder.typicode.com/posts?_limit=5").await?;
            if !response.ok() {
                return Err(format!("HTTP {}", response.status()));
            }
            parse(&response.text())
        },
    );
    scroll().flex_1().child(
        view()
            .p_4()
            .pt(px(60.0))
            .gap_2()
            .child(
                text(move || {
                    if posts.loading() { "loading…".to_owned() } else { posts.error().unwrap_or_default() }
                })
                .text_color(rgb(0x57606a)),
            )
            .child(each(
                move || posts.get().unwrap_or_default(),
                |post| post.id,
                |post, _| text(move || post.with(|p| p.title.clone())).number_of_lines(1),
            )),
    )
}
```

```tsx
import { mount, resource, Scroll, Text, View } from "nsh";

type Post = { id: number; title: string };

function App() {
  const posts = resource(async ({ signal }) => {
    const response = await fetch("https://jsonplaceholder.typicode.com/posts?_limit=5", { signal });
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    return (await response.json()) as Post[];
  });

  return (
    <Scroll style={{ flex: 1 }}>
      <View style={{ padding: 16, paddingTop: 60, gap: 8 }}>
        <Text style={{ color: "#57606a" }}>{posts.loading() ? "loading…" : String(posts.error() ?? "")}</Text>
        <Each of={posts() ?? []}>{(post) => <Text style={{ numberOfLines: 1 }}>{post().title}</Text>}</Each>
      </View>
    </Scroll>
  );
}

mount(App);
```

[`resource`](https://nsh.dev/versions/main/docs/reactivity.md#resource) keeps the value, the error and whether a load runs, loads again from a source that changes (or on `refetch()`), and cancels a load that no longer counts (the component goes away, or a newer load starts): in Rust by dropping the load's task, which cancels its request, in TSX through the `signal` it passes on. Rust's `fetch` takes absolute URLs; JSON is parsed with a crate such as `serde_json`.

In TSX, a `Response` reads its body once, as `json()`, `text()`, `arrayBuffer()`, `bytes()`, `blob()` or `formData()`, or as the `body` stream. `response.ok` is true for 2xx statuses; like in browsers, an HTTP error status does not reject the promise.

## Sending data

```rust
use nsh_core::prelude::*;

// JSON
let body = serde_json::json!({ "title": "Groceries", "items": ["milk", "eggs"] });
let created = fetch(
    HttpRequest::post("https://api.example.com/notes", body.to_string())
        .header("Content-Type", "application/json")
        .header("Authorization", format!("Bearer {token}")),
)
.await?;

// A form, URL-encoded
fetch(
    HttpRequest::post("https://api.example.com/login", "user=ada&password=…")
        .header("Content-Type", "application/x-www-form-urlencoded"),
)
.await?;

// Other methods
fetch(HttpRequest::new("DELETE", "https://api.example.com/notes/1")).await?;
```

```tsx
// JSON
const created = await fetch("https://api.example.com/notes", {
  method: "POST",
  headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
  body: JSON.stringify({ title: "Groceries", items: ["milk", "eggs"] }),
});

// A form, URL-encoded
await fetch("https://api.example.com/login", {
  method: "POST",
  body: new URLSearchParams({ user: "ada", password: "…" }),
});

// Query strings
const url = new URL("https://api.example.com/search");
url.searchParams.set("q", "native shell");
url.searchParams.set("page", "2");
const results = await (await fetch(url)).json();
```

`HttpRequest::new(method, url)`, `get` and `post` make a request, `.header(..)` and `.body(..)` complete it. In TSX, `body` accepts a string, `URLSearchParams`, `FormData`, a `Blob` or `File`, an `ArrayBuffer` or typed array, or a `ReadableStream`.

### Uploading files with FormData

In TSX, a `FormData` body is sent as `multipart/form-data` with its boundary. NSH always sets that content type for a `FormData` body, even if a library sets a default `Content-Type` first, because without the boundary the server cannot parse it.

```ts
const form = new FormData();
form.append("title", "Sunset");
form.append("photo", new Blob([bytes], { type: "image/jpeg" }), "sunset.jpg");

const response = await fetch("https://api.example.com/photos", { method: "POST", body: form });
```

### Uploading a photo the user picks

[`Picker`](https://nsh.dev/versions/main/modules/nsh.md#picker) gives the photos the user picks as files whose bytes stay native, scaled down
and in a format servers take; Rust sends their bytes, TSX appends the `File` to a `FormData`:

```rust
use nsh_core::geometry::DevicePixels;
use nsh_core::picker::PickRequest;
use nsh_core::prelude::*;

let mut request = PickRequest::new(false, 1);
request.max_dimension = Some(DevicePixels(2048));
let picked = pick_images(request);
spawn(async move {
    if let Some(photo) = picked.await.into_iter().next() {
        let upload = HttpRequest::post("https://api.example.com/photos", photo.data.to_vec())
            .header("Content-Type", photo.mime.as_str());
        let _ = fetch(upload).await;
    }
});
```

```tsx
import { Picker } from "nsh";

const [photo] = await Picker.pickImages({ maxDimension: 2048 });
if (photo) {
  const form = new FormData();
  form.append("photo", photo.file);
  await fetch("https://api.example.com/photos", { method: "POST", body: form });
}
```

## Streaming

TSX's `fetch` streams responses and request bodies; Rust's gives the whole body with the response.

### Reading a response as it arrives

`response.body` is a `ReadableStream<Uint8Array>` filled as the network delivers bytes. Read it chunk by chunk to show progress or to process server-sent lines as they come:

```ts
const response = await fetch("https://api.example.com/large.csv");
const total = Number(response.headers.get("Content-Length") ?? 0);
let received = 0;

for await (const chunk of response.body!) {
  received += chunk.length;
  progress.set(total ? received / total : 0);
}
```

Text streams decode with `TextDecoderStream`, and a `TransformStream` splits them into lines:

```ts
const response = await fetch("https://api.example.com/events", { headers: { Accept: "text/event-stream" } });
let rest = "";
const lines = response
  .body!.pipeThrough(new TextDecoderStream())
  .pipeThrough(
    new TransformStream<string, string>({
      transform(chunk, controller) {
        const parts = (rest + chunk).split("\n");
        rest = parts.pop() ?? "";
        for (const line of parts) controller.enqueue(line);
      },
    }),
  );

for await (const line of lines) {
  if (line.startsWith("data: ")) messages.update((m) => [...m, line.slice(6)]);
}
```

Back pressure works end to end: while more than 1 MiB of a response waits unread, the request is paused at the network level until your code catches up.

### Streaming a request body

A `ReadableStream` body is sent chunk by chunk as the network stack asks for it (chunked transfer). Pass `duplex: "half"`, as the Fetch standard requires:

```ts
const encoder = new TextEncoder();
const body = new ReadableStream<Uint8Array>({
  async start(controller) {
    for (const line of logLines) controller.enqueue(encoder.encode(line + "\n"));
    controller.close();
  },
});

await fetch("https://api.example.com/logs", { method: "POST", body, duplex: "half" });
```

A streamed body cannot be sent twice, so a 307 or 308 redirect of a streamed request fails.

## Cancelling and timeouts

In Rust, a request runs in a task and is cancelled with it: when the task's component goes away, or with `cancel()` on the task `spawn` returns. In TSX, pass an `AbortSignal` to cancel a request; the promise rejects with the signal's reason (an `AbortError` `DOMException` by default), and a body being read stops.

```rust
let task = spawn(async move {
    if let Ok(response) = fetch(format!("https://api.example.com/search?q={query}")).await {
        results.set(response.text());
    }
});

// Typing again: cancel the previous search.
task.cancel();
```

```tsx
const controller = new AbortController();
const request = fetch("https://api.example.com/search?q=" + encodeURIComponent(query), { signal: controller.signal });

// Typing again: cancel the previous search.
controller.abort();
```

In TSX, `AbortSignal.timeout(ms)` makes a signal that aborts after a delay, and `AbortSignal.any([...])` combines signals:

```ts
const response = await fetch(url, { signal: AbortSignal.timeout(10_000) });
```

A component that loads data should cancel when it goes away: a Rust task does on its own, and TSX aborts in [`cleanup`](https://nsh.dev/versions/main/docs/reactivity.md):

```rust
use nsh_core::prelude::*;

fn weather(city: String) -> impl IntoElement {
    let data = signal(String::new());
    // The task, and its request, end when the component goes away.
    spawn(async move {
        if let Ok(response) = fetch(format!("https://api.example.com/weather?city={city}")).await {
            data.set(response.text());
        }
    });
    text(move || data.get())
}
```

```tsx
import { cleanup, signal, Text } from "nsh";

function Weather(props: { city: string }) {
  const data = signal<unknown>(null);
  const controller = new AbortController();
  cleanup(() => controller.abort());
  fetch(`https://api.example.com/weather?city=${encodeURIComponent(props.city)}`, { signal: controller.signal })
    .then((r) => r.json())
    .then((d) => data.set(d))
    .catch(() => {});
  return <Text>{JSON.stringify(data())}</Text>;
}
```

## Errors

A request that does not produce an HTTP response fails: Rust's `fetch` gives an `Err` with the message, TSX's rejects with a `TypeError` whose message starts with `Network request failed:`. That happens with no connection, a DNS or TLS failure, an unsupported URL scheme, or a request your app's capabilities do not allow. Check `ok()` / `status()` (TSX: `response.ok`, `response.status`) for HTTP errors.

```rust
match fetch(url).await {
    Ok(response) if response.ok() => items.set(response.text()),
    Ok(response) => error.set(format!("Server answered {}", response.status())),
    Err(message) => error.set(message), // no response, or not granted
}
```

```tsx
try {
  const response = await fetch(url);
  if (!response.ok) throw new Error(`Server answered ${response.status}`);
  return await response.json();
} catch (e) {
  if (e instanceof DOMException && e.name === "AbortError") return; // cancelled
  showError(String(e));
}
```

## From Rust components

Rust components, `#[module]` functions and `#[class]` members call `fetch` from a task: `spawn` in a component, `resource` for a value the UI shows, or an `async fn` exported to TSX, which TSX awaits as a Promise. A request is a URL or an `HttpRequest` (`HttpRequest::get(url)`, `HttpRequest::post(url, body)`, `.header(name, value)`), and its response arrives whole. The task owns the request: dropping it, or the component that spawned it going away, cancels the request. It uses the same network stack and capability checks as TSX, on every platform and in the browser.

## Capabilities: which hosts an app may reach

An app may declare in `nsh.json` which hosts it talks to. Once `"capabilities"` is present, everything not listed is denied:

```json
{
  "capabilities": {
    "network": {
      "hosts": ["api.example.com", "*.cdn.example.com"],
      "http": [
        { "host": "quotes.example.com", "methods": ["GET"], "pathPrefix": "/v1/" }
      ]
    }
  }
}
```

| Key | Description |
|---|---|
| `network.hosts` | Hosts reachable with any method: `"*"` (any host), `"*.example.com"` (its subdomains, not `example.com` itself) or a host name. |
| `network.http` | Finer grants: a `host`, optionally limited to `methods`, `schemes`, a `port`, exact `paths` and `pathPrefixes`. |

The checks are enforced in NSH's runtime, outside your app's code, before a request reaches the network:

- A refused `fetch` fails (in TSX with a `TypeError`, as every failed request) with a message naming the key to add, such as ``Network request failed: fetch GET https://evil.io/ is not granted: add `evil.io` to capabilities.network in nsh.json``. In TSX the error's `code` is `"ERR_ACCESS_DENIED"`, its `permission` `"network"` and its `resource` the URL refused (the request's, or a redirect's), so the app tells a refusal apart from a lost connection:

  ```ts
  try {
    await fetch(url);
  } catch (error) {
    if (error.code === "ERR_ACCESS_DENIED") console.warn(`not granted: ${error.resource}`);
    else throw error;
  }
  ```
- **Every redirect is checked again.** NSH follows redirects itself (up to 20) instead of letting the platform do it, so a granted host cannot redirect your app to one that is not.
- The same `network` grants cover remote images (also in canvases and `Image.getSize` / `prefetch`) and video sources. `asset:` URIs of your own bundle are always allowed.
- The host is taken after the last `@`, so `https://ok.com@evil.io` counts as `evil.io`.

An app without `"capabilities"` may reach every host: a standalone app is its developer's own. Apps embedded in a host app or distributed as [signed packages](https://nsh.dev/versions/main/docs/signed-packages.md) should declare them; the host app can grant less than an app declares, and a request must be allowed by both. Development with `nsh dev` / `nsh run` enforces the same capabilities. See [Sandbox and capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md).

## Differences from browsers

TSX's `fetch` follows the Fetch standard with the differences that make sense for an app rather than a web page:

- **No CORS.** An app talks to any host its capabilities allow; there are no preflight requests and no opaque responses.
- **No forbidden headers.** An app may set `Cookie`, `User-Agent`, `Origin` and others.
- **`redirect: "manual"`** gives the 3xx response itself (with its `Location` header) rather than an opaque redirect. `redirect: "error"` rejects on a redirect.
- **`data:` and `blob:` URLs** are answered locally. `URL.createObjectURL(blob)` makes a `blob:` URL that `fetch` can read until you revoke it.
- **`asset:/` URLs** are the files the app ships, read from the app's own files with no capability needed ([Reading a file at run time](https://nsh.dev/versions/main/docs/images-and-assets.md#reading-a-file-at-run-time)).
- Browser-only options (`mode`, `credentials`, `cache`, `referrer`, `integrity`, `keepalive`, `priority`) are accepted for compatibility with libraries.

Libraries built on `fetch` (and on `AbortController`, `FormData` and streams) generally work unchanged. There is no `XMLHttpRequest`; native hosts provide the global `WebSocket` and the [`websocket` module](https://nsh.dev/versions/main/modules/standard-modules.md), checked against the same grants as `fetch`.

## Related

- [Global APIs](https://nsh.dev/versions/main/modules/globals.md): every global, with its members.
- [Sandbox and capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md): capabilities, limits and how the embedding app grants them.
- [Images and assets](https://nsh.dev/versions/main/docs/images-and-assets.md): remote images.
- [Lists](https://nsh.dev/versions/main/docs/lists.md#loading-more-onloadmore): paging through an API.

Source: https://nsh.dev/versions/main/docs/networking

---

# Device and environment

The environment an app runs in changes while it runs: the window resizes (rotation, split view, a Mac window), the user switches to dark mode or a larger text size, the keyboard comes and goes. NSH exposes each of these as a **reactive accessor**: call it like a signal, and whatever read it (a style, a text, a computed value) updates when it changes. There are no listeners to add or remove.

In Rust the accessors are functions of `nsh_core::prelude`; in TSX they come from the modules listed.

| Rust | TSX | Value |
|---|---|---|
| `window()` | `windowSize()` (`nsh`) | The surface's width and height, in points. |
| `dark()` | `colorScheme()` (`nsh`) | Dark or light: the system's, or the app's own (`set_color_scheme`, `setColorScheme`). |
| `font_scale()` | `fontScale()` (`nsh`) | The user's preferred text size relative to the default (1 is the default). |
| `safe_area()` | `safeArea()` (`nsh`) | Insets of the surface not covered by system UI: top, right, bottom, left. |
| `cx.insets()` | `safeAreaInsets()` (`nsh`) | The insets where the calling component renders (a page, a dialog). |
| `keyboard_height()`, `keyboard_duration()` | `keyboardFrame()` (`nsh`) | The software keyboard's height and animation duration. |
| `locale()` | `locale()` (`nsh`) | The user's locale as a BCP 47 tag (`"en-US"`, `"zh-Hans-CN"`): what `Intl` formats for by default. |
| `lifecycle()` | `lifecycle()` (`nsh`) | Whether the app is in use: `active`, `inactive` (visible without the focus) or `background` ([In the background](#in-the-background)). |
| `reduce_motion()`, `screen_reader()` | `reduceMotion()`, `screenReaderEnabled()` (`nsh`) | See [Accessibility](https://nsh.dev/versions/main/docs/accessibility.md). |

```rust
use nsh_core::prelude::*;

#[component]
pub fn App() -> impl IntoElement {
    view()
        .flex_1()
        .pt(move || safe_area().top + px(16.0))
        .px(px(16.0))
        // A light and a dark value: the color follows the appearance natively.
        .bg(AdaptiveColor::rgb(0xffffff, 0x0d1117))
        .child(
            text(move || {
                let size = window();
                format!(
                    "{} × {} pt, text at {:.2}×",
                    size.width.0.round(),
                    size.height.0.round(),
                    font_scale()
                )
            })
            .text_color(AdaptiveColor::rgb(0x1f2328, 0xe6edf3)),
        )
}
```

```tsx
import { mount, Text, View, safeArea } from "nsh";
import { colorScheme, fontScale, windowSize } from "nsh";

function App() {
  return (
    <View style={{ flex: 1, paddingTop: safeArea().top + 16, paddingHorizontal: 16, backgroundColor: colorScheme() === "dark" ? "#0d1117" : "#ffffff" }}>
      <Text style={{ color: colorScheme() === "dark" ? "#e6edf3" : "#1f2328" }}>
        {Math.round(windowSize().width)} × {Math.round(windowSize().height)} pt, text at {fontScale().toFixed(2)}×
      </Text>
    </View>
  );
}

mount(App);
```

## Window size and responsive layout

`window()` (TSX: `windowSize()`) is the size of the surface NSH renders into: the screen on a phone, the window on an iPad in split view or on a Mac, the host view when NSH is embedded. Use it to change the layout, not only sizes:

```rust
use nsh_core::prelude::*;

fn gallery() -> impl IntoElement {
    let columns = || {
        let width = window().width.0;
        if width >= 700.0 { 4.0 } else if width >= 500.0 { 3.0 } else { 2.0 }
    };
    let side = move || px((window().width.0 - 32.0 - (columns() - 1.0) * 8.0) / columns());
    view().flex_row().flex_wrap().gap_2().child(each(
        photos,
        |p| p.id,
        move |p, _| image(move || p.with(|p| p.url.clone())).w(side).aspect_ratio(1.0),
    ))
}
```

```tsx
import { Image, View } from "nsh";
import { windowSize } from "nsh";

function Gallery() {
  const columns = () => (windowSize().width >= 700 ? 4 : windowSize().width >= 500 ? 3 : 2);
  return (
    <View style={{ flexDirection: "row", flexWrap: "wrap", gap: 8 }}>
      <Each of={photos}>
        {(p) => <Image src={p().url} style={{ width: (windowSize().width - 32 - (columns() - 1) * 8) / columns(), aspectRatio: 1 }} />}
      </Each>
    </View>
  );
}
```

Often flexbox, percentages and `aspect_ratio` (`aspectRatio`) do the job without reading the size at all; see [Layout](https://nsh.dev/versions/main/docs/layout.md). Rust's `style_when(|| window().width.0 >= 640.0, |s| s.flex_row())` switches styles with the width; in TSX with Tailwind, the breakpoint variants (`sm:`, `md:`, `lg:`, `xl:`, `2xl:`, `max-*:`, `min-[…]:`) and `portrait:` / `landscape:` follow the window too: `class="grid grid-cols-2 md:grid-cols-4"`.

## Dark mode

The appearance follows the system unless the app sets its own. In Rust, the simplest way to support dark mode is a color with a light and a dark value, `AdaptiveColor::rgb(light, dark)`: it switches natively when the appearance does, with nothing to run. In TSX it is the `dark:` Tailwind variant, which applies when `colorScheme()` is `"dark"`:

```rust
view()
    .flex_1()
    .p_4()
    .bg(AdaptiveColor::rgb(0xffffff, 0x18181b))
    .child(
        text("Follows the system appearance")
            .text_color(AdaptiveColor::rgb(0x18181b, 0xf4f4f5)),
    )
```

```tsx
<View class="flex-1 bg-white dark:bg-zinc-900 p-4">
  <Text class="text-zinc-900 dark:text-zinc-100">Follows the system appearance</Text>
</View>
```

For anything else, read `dark()` (TSX: `colorScheme()`) in a closure or a computed value; in TSX, for more than a few colors, derive a palette once:

```rust
use nsh_core::prelude::*;

// `dark()` is reactive: the closure runs again when the appearance changes.
view()
    .flex_1()
    .bg(move || if dark() { rgb(0x0d1117) } else { rgb(0xf6f8fa) })
    .child(text("Hello"))
```

```tsx
import { computed, Text, View } from "nsh";
import { colorScheme } from "nsh";

const palette = computed(() =>
  colorScheme() === "dark"
    ? { background: "#0d1117", surface: "#161b22", text: "#e6edf3", muted: "#8b949e" }
    : { background: "#f6f8fa", surface: "#ffffff", text: "#1f2328", muted: "#57606a" },
);

<View style={{ flex: 1, backgroundColor: palette().background }}>
  <Text style={{ color: palette().text }}>Hello</Text>
</View>
```

Rust components also take their colors from the theme, which has light and dark values (`nsh.json` `"theme"`, see [Building with Rust](https://nsh.dev/versions/main/docs/rust.md)), so they switch with the system as well. To match the status bar to your background, give your pages and dialogs a [`statusBar`](https://nsh.dev/versions/main/modules/nsh-base.md#status-bar), or the app one in `nsh.json`.

### An app with its own appearance

An app that is always dark (or always light) says so in `nsh.json`, and `dark()` and `colorScheme()`, adaptive colors, `dark:` classes, the theme, the status bar's default style and alerts follow it from the first frame (packaged apps also launch in it):

```json
{ "appearance": "dark" }
```

`set_color_scheme(Appearance::Dark)` (TSX: `setColorScheme` from `nsh`) changes it at run time, for an in-app appearance setting; `Appearance::System` (`"system"`) follows the system again:

```rust
use nsh_core::prelude::*;

view()
    .on_press(move || {
        set_color_scheme(if dark() { Appearance::Light } else { Appearance::Dark })
    })
    .role(AccessibilityRole::Button)
    .rounded_lg()
    .px_4()
    .py_2()
    .bg(AdaptiveColor::rgb(0xe5e5e5, 0x262626))
    .child(
        text(|| if dark() { "Light" } else { "Dark" })
            .text_color(AdaptiveColor::rgb(0x171717, 0xfafafa)),
    )
```

```tsx
import { Text, View } from "nsh";
import { colorScheme, setColorScheme } from "nsh";

<View onPress={() => setColorScheme(colorScheme() === "dark" ? "light" : "dark")} role="button" class="rounded-lg px-4 py-2 bg-neutral-200 dark:bg-neutral-800">
  <Text class="text-neutral-900 dark:text-neutral-50">{colorScheme() === "dark" ? "Light" : "Dark"}</Text>
</View>
```

> [!TIP]
> Test both appearances while developing: `xcrun simctl ui booted appearance dark` switches an iOS simulator, and Android has a dark theme toggle in Quick Settings. The change reaches your app at once, without a reload.

## Text size

`font_scale()` (TSX: `fontScale()`) is the user's text size setting (Dynamic Type on iOS, font size on Android) relative to the default. Text and inputs follow it by themselves: `fontSize: 16` renders larger when the user asked for larger text. Per element you can opt out or cap it:

| Rust (on `text` and `input`) | TSX (on `<Text>` and `<Input>`) | Default | Description |
|---|---|---|---|
| `.allow_font_scaling(..)` | `allowFontScaling` | `true` | Follow the system text size. |
| `.max_font_size_multiplier(..)` | `maxFontSizeMultiplier` | `0` (none) | The largest scale applied to this text. |

```rust
text("Today")
    .text_size(px(34.0))
    .font_weight(FontWeight::BOLD)
    .max_font_size_multiplier(1.4)
```

```tsx
<Text style={{ fontSize: 34, fontWeight: "700" }} maxFontSizeMultiplier={1.4}>Today</Text>
```

Read `font_scale()` to adapt layout that does not follow text automatically, such as switching a row to a column when the text gets large: `.style_when(|| font_scale() > 1.3, |s| s.flex_col())` in Rust, `flexDirection: fontScale() > 1.3 ? "column" : "row"` in TSX.

The text size scales text: every text and input that allows font scaling, and the platform's alerts and toasts. Lengths keep their size: spacing, widths and heights, corner radii, borders and images, in points or in classes (`p-4`, `rounded-lg`, `w-[2rem]`). Boxes sized by their content grow with their text.

## Language and region

`locale()` is the user's locale, as a BCP 47 tag (`locale().as_str()` in Rust). In TSX, `Intl` formats numbers and dates for it by default, so `new Intl.NumberFormat().format(1234.5)` gives `1,234.5` in `en-US` and `1.234,5` in `de-DE`. Read `locale()` to pick the strings of your own translations: the texts that read it update when it changes.

```rust
use nsh_core::prelude::*;

fn greeting() -> &'static str {
    match locale().as_str().split('-').next() {
        Some("de") => "Willkommen",
        Some("zh") => "欢迎",
        _ => "Welcome",
    }
}

text(greeting)
```

```tsx
import { Text } from "nsh";
import { locale } from "nsh";

const greetings: Record<string, string> = { en: "Welcome", de: "Willkommen", zh: "欢迎" };

<Text>{greetings[locale().split("-")[0]] ?? greetings.en}</Text>
```

## In an embedding app

An app shown inside a native app follows that app's own settings when it sets them: the embedding APIs' locale and text size (`AppView::set_locale` and `set_font_scale` in Rust on [GPUI](https://nsh.dev/versions/main/docs/gpui.md), [macOS](https://nsh.dev/versions/main/docs/macos.md), [Linux](https://nsh.dev/versions/main/docs/linux.md) and [Windows](https://nsh.dev/versions/main/docs/windows.md), `locale` and `fontScale` in Swift on [iOS](https://nsh.dev/versions/main/docs/ios.md), `setLocale` and `setFontScale` in Java on [Android](https://nsh.dev/versions/main/docs/android.md)) stand in for the system's language and text size. `locale()`, `Intl`, `fontScale()` and text follow them at once, as they follow a system change, and the system's come back when the embedding app clears them. Use them when the native app lets its users choose a language or a text size of its own.

## In the background

`lifecycle()` (the same in TSX) says whether the user is using the app. It is `active` in the foreground, `inactive` while the app is still visible but another app or window has the focus (or the system shows something over it: the app switcher, an incoming call), and `background` while it is not visible: in the background on a phone, minimized on a desktop, a hidden tab on the web. Like every accessor it updates what read it, so an effect pauses a live feed, polling or a video in the background and resumes them when the user comes back:

```rust
effect(move || {
    if lifecycle() == Lifecycle::Background {
        feed.pause();
    } else {
        feed.resume();
    }
});
```

```tsx
effect(() => {
  if (lifecycle() === "background") feed.pause();
  else feed.resume();
});
```

Use `background` to pause work, and save what the user changes as they change it: the system may suspend an app seconds after it moves to the background, before an effect that reads the change has run. An app shown inside a native app follows that app's state, and where an app has several windows (an iPad, a desktop) a view follows the window it is in. In tests, `app.setLifecycle("background")` of `nsh/test` moves the app there ([Testing](https://nsh.dev/versions/main/docs/testing-and-trace.md#steps)).

## Safe areas

Notches, the home indicator, the status bar, Android's navigation bar and the Mac Catalyst title bar cover parts of the surface. NSH apps draw edge to edge on every platform, and get the covered parts as insets.

- `safe_area()` (TSX: `safeArea()`) gives the surface's insets.
- A component's `cx.insets()` (TSX: `safeAreaInsets()`) gives the insets **where the component renders**: inside a navigation [page](https://nsh.dev/versions/main/docs/navigation.md#safe-areas-under-the-header) they are measured below its header, inside a [dialog](https://nsh.dev/versions/main/elements/dialog.md) they are the dialog's. Prefer it in components that may be shown in several places.
- CSS's `env(safe-area-inset-top)`, `-right`, `-bottom` and `-left` pad or space any view by the insets where it renders, in `padding*` and `margin*` (`calc(env(safe-area-inset-bottom) + 8px)` adds a length; Tailwind `pt-[env(safe-area-inset-top)]`; Rust `.p_safe_area()`, `.pt_safe_area()`, `.pb_safe_area_plus(px(8.0))`, ...). The padding updates natively when the insets change ([Safe area](https://nsh.dev/versions/main/elements/safe-area.md)).

```rust
use nsh_core::prelude::*;

fn screen() -> impl IntoElement {
    view()
        .pt_safe_area()
        .px_safe_area()
        .flex_1()
        .bg(white())
        .child(content())
        .child(bottom_bar())
}

// A component, for its `Scope`: the insets where it renders.
#[component]
fn BottomBar(cx: Scope<NoEvent>) -> impl IntoElement {
    // `cx.insets()`: the insets where the component renders.
    view()
        .flex_row()
        .pt(px(8.0))
        .pb(move || cx.insets().bottom + px(8.0))
}
```

```tsx
import { View, safeAreaInsets } from "nsh";

function Screen() {
  return (
    <View class="flex-1 bg-white pt-[env(safe-area-inset-top)] pr-[env(safe-area-inset-right)] pl-[env(safe-area-inset-left)]">
      <Content />
      <BottomBar />
    </View>
  );
}

function BottomBar() {
  const insets = safeAreaInsets();
  return <View style={{ paddingBottom: insets().bottom + 8, paddingTop: 8, flexDirection: "row" }}>…</View>;
}
```

On Android, a view embedded below a toolbar gets only the parts of the system bars that overlap it, like UIKit's safe area: no top inset if it does not reach the status bar.

## The platform

`os()`, `os_version()`, `idiom()`, `is_desktop()` and `is_catalyst()` in Rust, and the `platform` constant from `nsh` in TSX, describe where the app runs. They stay the same while the app runs.

| Rust | TSX | Description |
|---|---|---|
| `os()` | `platform.os` | `Os::Ios`, `Os::Android`, `Os::MacOs`, `Os::Windows`, `Os::Linux` or `Os::Web` (`os().name()` is TSX's string). Mac Catalyst is iOS. |
| `os_version()` | `platform.version` | Major and minor; on Android the API level and 0. |
| `idiom()` | `platform.idiom` | `Idiom::Phone`, `Pad`, `Mac`, `Tv`, `Desktop` or `Terminal`; `Terminal` in a terminal, else `Desktop` exactly where `is_desktop()` holds. |
| `is_desktop()` | `platform.desktop` | macOS, Windows or Linux, a desktop browser or a terminal ([Desktop and mobile](https://nsh.dev/versions/main/docs/platform-specific.md#desktop-and-mobile)). |
| `is_catalyst()` | `platform.catalyst` | Mac Catalyst, in either of its idioms. |

TSX's `platform` in full:

| Member | Description |
|---|---|
| `platform.os` | `"ios"`, `"android"`, `"macos"`, `"windows"`, `"linux"` or `"web"`. Mac Catalyst reports `"ios"`. |
| `platform.version` | A string: iOS and desktops: the OS version (`"17.5"`); Android: the API level (`"35"`); the web: `"0.0"`. |
| `platform.idiom` | `"phone"`, `"pad"`, `"mac"`, `"tv"`, `"desktop"` or `"terminal"`. `"terminal"` in a terminal, else `"desktop"` exactly where `platform.desktop` is `true`. `"mac"` is UIKit's Mac idiom under Mac Catalyst, a mobile idiom. |
| `platform.desktop` | Desktop behavior applies: macOS, Windows, Linux, desktop browsers and terminals. `desktop={{…}}` props and `platform.select({ desktop })` follow it. |
| `platform.catalyst` | The app runs under Mac Catalyst (`os` `"ios"`), in the Mac or the iPad idiom. |
| `platform.select(spec)` | The value for this platform; see [Platform-specific code](https://nsh.dev/versions/main/docs/platform-specific.md#platformselect). |

```rust
use nsh_core::{element::Os, prelude::*};

let haptics_supported = os() == Os::Ios || (os() == Os::Android && os_version().0 >= 30);
```

```tsx
import { platform } from "nsh";

const hapticsSupported = platform.os === "ios" || (platform.os === "android" && Number(platform.version) >= 30);
```

`nsh test` runs headless as iOS.

On [Linux](https://nsh.dev/versions/main/docs/linux.md), `platform.os` is `"linux"`, the idiom `"desktop"` and `platform.version` the kernel's major
and minor version (`"6.12"`): distributions number their releases in ways that cannot be compared. There, the safe
area and the keyboard height are 0, `colorScheme()` follows the desktop's setting (the XDG settings portal) live,
`fontScale()` the desktop's text scaling and `pixelRatio()` the display's scale, fractional ones included.

On [macOS](https://nsh.dev/versions/main/docs/macos.md) (the AppKit backend), `platform.os` is `"macos"`, the idiom `"desktop"` and
`platform.version` the macOS version. The safe area and the keyboard height are 0, `colorScheme()` follows the
system's appearance live, `fontScale()` is 1 and `pixelRatio()` the display's backing scale.

On [Windows](https://nsh.dev/versions/main/docs/windows.md), `platform.os` is `"windows"`, the idiom `"desktop"` and `platform.version` `"10.0"`, on
Windows 11 too (Windows kept the version number). The safe area and the keyboard height are 0, `colorScheme()` follows
Settings > Personalization > Colors live, `fontScale()` the Text size setting (1 to 2.25), `reduceMotion()` the
animation effects setting, `pixelRatio()` the monitor's scale, and `Intl` formats in the user's regional format.

In a browser ([the web runtime](https://nsh.dev/versions/main/docs/web.md)), `platform.os` is `"web"` and `platform.version` `"0.0"`. The idiom is
`"desktop"` with a mouse and a window at least 600 points wide, `"pad"` on a tablet and `"phone"` on a phone,
decided when the app starts. The locale, `reduceMotion()`, `fontScale()` (the browser's text size), `pixelRatio()`,
the safe area and the keyboard height come from the browser and follow it live.

In a terminal ([the terminal backend](https://nsh.dev/versions/main/docs/tui.md)), `platform.idiom` is `"terminal"`, `platform.desktop` is `true` and
`platform.os` is the machine's own system. `colorScheme()` follows the terminal's background, `reduceMotion()` is
`true`, and the safe area and the keyboard height are 0.

## Pixel density

`pixel_ratio()` and `round_to_nearest_pixel(points)` in Rust, and `pixelRatio()` from `nsh` in TSX, convert between points and device pixels.

| Rust | TSX | Description |
|---|---|---|
| `pixel_ratio()` | `pixelRatio()` | Device pixels per point (2 or 3 on most phones), reactive. |
| `round_to_nearest_pixel(points)` | `Math.round(x * pixelRatio()) / pixelRatio()` | Points rounded to the nearest device pixel. |

A hairline, one device pixel tall:

```rust
view()
    .h(move || px(1.0 / pixel_ratio()))
    .bg(rgb(0xd0d7de))
```

```tsx
import { View } from "nsh";
import { pixelRatio } from "nsh";

<View style={{ height: 1 / pixelRatio(), backgroundColor: "#d0d7de" }} />
```

`pixel_ratio()` and `pixelRatio()` are reactive, so a hairline follows a window moved to a screen with another density.

## Right to left

When the device language is written right to left (Arabic, Hebrew, Persian, ...), NSH lays the app out right to left: rows run from the right, the logical style properties take their right-to-left sides, text aligns to the right, and native widgets mirror. The layout direction follows the user's language by itself. A view's `direction` style (`"ltr"`, `"rtl"` or `"inherit"`; `.direction(LayoutDirection::..)` in Rust) sets the direction of its subtree; on the root view it sets the app's.

Changes apply at once, without restarting the app; the demo on this page toggles the `direction` style.

Write layouts that work both ways with the logical properties: in Rust `ms` / `me` and `ps` / `pe` (Tailwind's names), in TSX `marginStart` / `marginEnd`, `paddingStart` / `paddingEnd`, `start` / `end`, `borderTopStartRadius`, `textAlign: "start"` and so on, which mean left and right in left-to-right layouts and the reverse right to left. `left` and `right` (`marginLeft`, `paddingRight`, `left`, `textAlign: "left"`, ...) keep their sides in both, as in CSS. The `direction` style (`"inherit"`, `"ltr"`, `"rtl"`) overrides the direction for a subtree, for example to keep a phone number or a media player's controls left to right. The `rtl:` and `ltr:` Tailwind variants apply per direction.

Horizontal scroll views and lists start at the right end in right-to-left layouts. On Android, the host app must declare `android:supportsRtl="true"` in its manifest for native widgets to mirror.

## Related

- [`nsh`'s device API](https://nsh.dev/versions/main/modules/nsh.md#device): the reference.
- [Platform-specific code](https://nsh.dev/versions/main/docs/platform-specific.md): `platform.select`, platform props and modules.
- [Accessibility](https://nsh.dev/versions/main/docs/accessibility.md): screen readers and reduced motion.
- [Safe area](https://nsh.dev/versions/main/elements/safe-area.md), [Keyboard](https://nsh.dev/versions/main/elements/keyboard.md) and [the status bar](https://nsh.dev/versions/main/modules/nsh-base.md#status-bar).
- [Tailwind](https://nsh.dev/versions/main/docs/tailwind.md): `dark:`, breakpoint and orientation variants.

Source: https://nsh.dev/versions/main/docs/device-and-environment

---

# Accessibility

NSH renders with native views, so the platforms' assistive technologies (VoiceOver on iOS and Mac Catalyst, TalkBack on Android, Switch Control, Voice Control, ...) see your app's real view hierarchy. What you add are the descriptions those technologies cannot infer: what an element is, what it says, what state it is in and what it can do. Every element accepts the methods (Rust) and props (TSX) below.

## What you get without doing anything

- **Text is read.** A text element is an accessibility element whose label is its text. A view without a label is read as the texts inside it.
- **Pressable views are elements.** A view with a press or long press handler (`.on_press`, `onPress`) is an accessibility element by default, and activating it (double tap with VoiceOver or TalkBack) presses it.
- **Inputs are text fields**, with their placeholder, value and keyboard.
- **Text follows the user's size setting.** See [Text size](#text-size).

## Labels, hints and roles

```rust
view()
    .on_press(play)
    .role(AccessibilityRole::Button)
    .label("Play")
    .hint("Starts the song")
    .size(px(44.0))
    .items_center()
    .justify_center()
    .child(text("▶"))
```

```tsx
<View
  onPress={play}
  role="button"
  accessibilityLabel="Play"
  accessibilityHint="Starts the song"
  style={{ width: 44, height: 44, alignItems: "center", justifyContent: "center" }}
>
  <Text>▶</Text>
</View>
```

| Rust | TSX | Type | Description |
|---|---|---|---|
| `.accessible(..)` | `accessible` | `boolean` | The view is one element for assistive technologies; its children are not exposed separately. |
| `.label(..)` | `accessibilityLabel` | `string` | What screen readers read, instead of the texts inside. |
| `.hint(..)` | `accessibilityHint` | `string` | What activating the element does, read after a pause. |
| `.role(..)` | `role` | `AccessibilityRole` | What the element is. |
| `.accessibility_state(..)` | `accessibilityState` | `AccessibilityState` | Its state: disabled, selected, checked, busy, expanded, pressed, current, has popup. `selected` also applies the selected style, `checked` the checked style when true and the indeterminate style when `"mixed"`, `pressed` the pressed style when true. |
| `.accessibility_level(..)` | `accessibilityLevel` | `number` | The level of a heading (1 the top), the depth of a tree item (1 at the top). |
| `.accessibility_value(..)` | `accessibilityValue` | `{ min?, max?, now?, text? }` | The value of a range or textual element. |
| | `accessibilityActions` | `{ name, label? }[]` | Actions offered to assistive technologies. |
| `.on_accessibility_action(..)` | `onAccessibilityAction` | `(e: { actionName }) => void` | An action was performed (Rust: its name). |
| `.accessibility_elements_hidden(..)` | `accessibilityElementsHidden` | `boolean` | Hides the view and its subtree from assistive technologies. |
| | `importantForAccessibility` | `"auto" \| "yes" \| "no" \| "no-hide-descendants"` | Whether the view (and its subtree) is exposed. |
| | `android={{ accessibilityLiveRegion }}` | `"none" \| "polite" \| "assertive"` | Android: how changes of the view are announced to TalkBack. |
| `.test_id(..)` | `testID` | `string` | An identifier for UI tests (the accessibility identifier on iOS, the resource id on Android); not read aloud. |

Give every icon-only control a label: a screen reader cannot read a glyph or an image. Keep labels short and do not include the role ("Play", not "Play button"): the role is announced on its own.

### Roles

The role (`.role(AccessibilityRole::Header)`, `role="header"`) tells the user what kind of element this is and how to operate it. In Rust it is an `AccessibilityRole` variant (`Button`, `Header`, `Switch`, ...); the TSX values are `"none"`, `"button"`, `"link"`, `"search"`, `"image"`, `"imagebutton"`, `"keyboardkey"`, `"text"`, `"adjustable"`, `"header"`, `"summary"`, `"alert"`, `"checkbox"`, `"combobox"`, `"menu"`, `"menubar"`, `"menuitem"`, `"progressbar"`, `"radio"`, `"radiogroup"`, `"scrollbar"`, `"spinbutton"`, `"switch"`, `"tab"`, `"tablist"`, `"timer"`, `"toolbar"`, `"list"`, `"grid"`, `"table"`, `"rowgroup"`, `"row"`, `"columnheader"` and `"cell"` (the roles of [`Table`](https://nsh.dev/versions/main/elements/table.md)'s parts), `"listbox"` and `"option"` (a list of options to choose from, such as [`Select`](https://nsh.dev/versions/main/elements/select.md)'s list, and its options, the chosen one marked by `accessibilityState.selected`), `"group"` (related elements that belong together), `"region"` (a section worth reaching on its own, such as an accordion's panel), `"navigation"` (links that move around the app, such as a pagination), `"tree"` and `"treeitem"` (items that expand and collapse, each at its `accessibilityLevel`), `"menuitemcheckbox"` and `"menuitemradio"` (menu items that are checked, alone or as one choice of a group).

The most useful ones:

- `"button"` for anything pressable that is not a link; `"link"` for navigation to content.
- `"header"` for section titles: screen reader users jump between headers to skim a screen. `accessibilityLevel` gives its level (1 the top) where the platform reads one.
- `"button"` with `accessibilityState.pressed` for a toggle button, one that stays on or off (bold in a toolbar).
- `"navigation"` around links that move between pages, the link of the shown page with `accessibilityState.current: "page"`.
- `"switch"`, `"checkbox"`, `"radio"` with `accessibilityState.checked`.
- `"adjustable"` for sliders and steppers, with `accessibilityValue` and the `increment` / `decrement` actions
  (each thumb of a [`Slider`](https://nsh.dev/versions/main/elements/slider.md) is one).
- `"spinbutton"` for a field that holds a number the user can also step, with the same value and actions (the
  field of a [`NumberInput`](https://nsh.dev/versions/main/elements/number-input.md)).
- `"image"` for meaningful images, with a label; decorative images should be hidden instead.

```rust
text("Settings")
    .role(AccessibilityRole::Header)
    .text_size(px(22.0))
    .font_weight(FontWeight::BOLD)
```

```tsx
<Text role="header" style={{ fontSize: 22, fontWeight: "700" }}>Settings</Text>
```

### States and values

For an on / off control in an app, use [`Switch`](https://nsh.dev/versions/main/elements/switch.md) from `nsh/base`, which sets the role and state itself. The example shows what a role and state on a view do.

```rust
use nsh_core::{Checked, prelude::*};

// A toggle drawn with views.
view()
    .on_press(move || on.update(|v| *v = !*v))
    .role(AccessibilityRole::Switch)
    .label("Wi-Fi")
    .accessibility_state(move || AccessibilityState {
        checked: Some(if on.get() { Checked::True } else { Checked::False }),
        ..AccessibilityState::default()
    })
    .hit_slop(EdgeInsets::all(px(8.0)))
    .w(px(51.0))
    .h(px(31.0))
    .rounded_full()
    .p(px(2.0))
    .bg(move || if on.get() { rgb(0x22c55e) } else { rgb(0xd4d4d8) })
    .child(
        view()
            .size(px(27.0))
            .rounded_full()
            .bg(white())
            .style_with(move |s| s.translate_x(px(if on.get() { 20.0 } else { 0.0 }))),
    )
```

```tsx
// A toggle drawn with views.
<View
  onPress={() => on.set(!on())}
  role="switch"
  accessibilityLabel="Wi-Fi"
  accessibilityState={{ checked: on() }}
  hitSlop={8}
  class="h-[31px] w-[51px] rounded-full p-0.5 transition-colors"
  classList={{ "bg-green-500": on(), "bg-zinc-300": !on() }}
>
  <View class="size-[27px] rounded-full bg-white transition-transform" classList={{ "translate-x-5": on() }} />
</View>
```

The state is `AccessibilityState { disabled, selected, checked: Option<Checked>, busy, expanded, pressed: Option<Checked>, current: Option<AccessibilityCurrent>, has_popup }` in Rust and `{ disabled?, selected?, checked?: boolean | "mixed", busy?, expanded?, pressed?: boolean | "mixed", current?: boolean | "page" | "step" | "location" | "date" | "time", hasPopup? }` in TSX. `pressed` makes a button a toggle button (ARIA's `aria-pressed`); `current` marks the current item of a set (ARIA's `aria-current`): a pagination's page, a wizard's step; `hasPopup` marks the trigger of a popup, a menu or a list (ARIA's `aria-haspopup`), whose `expanded` says whether it is open, where an `expanded` element without it is a disclosure that shows its content in place (`Popover`, `Menu`, `HoverCard`, `Select`, `Combobox` and `DatePicker` set it on their triggers). `disabled` is also implied by disabling the view (`.disabled(..)`, `disabled`). `accessibilityValue` with `min`, `max` and `now` is read as a percentage; with `text` it is read as given ("3 of 10", "Medium").

## Actions

A pressable view supports activation already. For anything else, declare actions with `accessibilityActions` and handle them with `onAccessibilityAction`; a Rust component hears the performed action's name with `.on_accessibility_action(|name: &str| ..)`:

```tsx
function Quantity() {
  const n = signal(1);
  return (
    <View
      accessible
      role="adjustable"
      accessibilityLabel="Quantity"
      accessibilityValue={{ text: String(n()) }}
      accessibilityActions={[{ name: "increment" }, { name: "decrement" }]}
      onAccessibilityAction={(e) => {
        if (e.actionName === "increment") n.update((v) => v + 1);
        if (e.actionName === "decrement") n.update((v) => Math.max(0, v - 1));
      }}
      style={{ flexDirection: "row", alignItems: "center", gap: 12 }}
    >
      <View onPress={() => n.update((v) => Math.max(0, v - 1))}><Text>−</Text></View>
      <Text>{n()}</Text>
      <View onPress={() => n.update((v) => v + 1)}><Text>+</Text></View>
    </View>
  );
}
```

Some action names are standard and map to the platforms' own gestures:

| Name | iOS (VoiceOver) | Android (TalkBack) |
|---|---|---|
| `activate` | Double tap | Double tap (click) |
| `increment`, `decrement` | Swipe up / down, then VoiceOver reads the new value | Scroll forward / backward |
| `longpress` | | Double tap and hold |
| `expand`, `collapse` | | Expand / collapse |
| `magicTap` | Two-finger double tap | |
| `escape` | Two-finger Z scrub | |

An element with `increment` or `decrement` is adjustable whatever its role: a chart keeps its `"image"` role and steps through its points with VoiceOver's swipes and TalkBack's scrolls, its `accessibilityValue` read after each step.

Any other name becomes a custom action, listed in VoiceOver's actions rotor and TalkBack's actions menu with its `label` (or its name). Custom actions are the accessible form of swipe-to-delete and similar gestures:

```tsx
<View
  accessibilityActions={[{ name: "archive", label: "Archive" }, { name: "delete", label: "Delete" }]}
  onAccessibilityAction={(e) => (e.actionName === "archive" ? archive(mail.id) : remove(mail.id))}
>
  …
</View>
```

## Grouping and hiding

Making a view accessible (`.accessible(true)`, `accessible`) makes a view one element: a card with a title, a subtitle and a price is read in one go, instead of the user swiping through three texts.

```rust
view()
    .accessible(true)
    .on_press(open)
    .role(AccessibilityRole::Button)
    .p(px(16.0))
    .child(text("Blue jacket"))
    .child(text("Size M"))
    .child(text("$120"))
```

```tsx
<View accessible onPress={open} role="button" style={{ padding: 16 }}>
  <Text>Blue jacket</Text>
  <Text>Size M</Text>
  <Text>$120</Text>
</View>
```

Hide what adds nothing: decorative images, dividers, an icon next to a text that already says the same.

```tsx
<Image src={decoration} accessibilityElementsHidden importantForAccessibility="no-hide-descendants" />
```

`accessibilityElementsHidden` (iOS's name) and `importantForAccessibility="no-hide-descendants"` (Android's) both hide the subtree on both platforms; setting both is harmless.

## The screen reader and the user's settings

In Rust, the prelude reports the user's settings and talks to the screen reader: `screen_reader()` and `reduce_motion()` are reactive, `announce_for_accessibility(message)` has the screen reader read a message, and an element's `element_ref()` moves the screen reader's focus to it with `set_accessibility_focus()`. In TSX, `nsh`'s accessibility API reports the user's settings and lets you talk to the screen reader.

| Member | Description |
|---|---|
| `screenReaderEnabled()` | Whether VoiceOver or TalkBack runs (reactive). |
| `reduceMotion()` | Whether the user asked for less motion (reactive). |
| `announce(message)` | The screen reader reads `message`. |
| `setAccessibilityFocus(ref)` | Moves the screen reader's focus to a view. |

The settings are accessors: read them in a binding or an effect, and what reads them updates when the user changes the setting, with no cleanup.

```rust
use nsh_core::prelude::*;

fn upload() -> impl IntoElement {
    let done = signal(false);
    let result = element_ref();
    let finish = move || {
        done.set(true);
        announce_for_accessibility("Upload complete");
        result.set_accessibility_focus();
    };
    view()
        .gap(px(12.0))
        // Autoplaying carousels are hard to use with a screen reader: show a list instead.
        .child(when(move || !screen_reader(), photo_carousel).otherwise(photo_list))
        .child(
            text(move || if done.get() { "Uploaded 3 photos" } else { "Uploading…" })
                .element_ref(&result),
        )
}
```

```tsx
import { signal, Text, View, type ViewRef } from "nsh";
import { announce, screenReaderEnabled, setAccessibilityFocus } from "nsh";

function Upload() {
  const done = signal(false);
  let result!: ViewRef;
  const finish = () => {
    done.set(true);
    announce("Upload complete");
    setAccessibilityFocus(result);
  };
  return (
    <View style={{ gap: 12 }}>
      {/* Autoplaying carousels are hard to use with a screen reader: show a list instead. */}
      <If when={!screenReaderEnabled()} else={<PhotoList />}>
        <PhotoCarousel />
      </If>
      <Text ref={result}>{done() ? "Uploaded 3 photos" : "Uploading…"}</Text>
    </View>
  );
}
```

Announce changes the user would otherwise miss: a background save finishing, an error appearing away from the focus, a timer ending. On Android, `android={{ accessibilityLiveRegion: "polite" }}` on a view makes TalkBack announce its changes by itself.

## Text size

Text and inputs follow the system text size (Dynamic Type on iOS, font size on Android) unless you turn it off (`.allow_font_scaling(false)`, `allowFontScaling={false}`). Rather than turning it off, design for it:

- Let text wrap: avoid fixed heights on views that contain text.
- Cap very large headings with `.max_font_size_multiplier(..)` / `maxFontSizeMultiplier` instead of disabling scaling.
- Switch layouts when the text is large: read `font_scale()` (Rust) or `fontScale()` from `nsh` (TSX) (for example, stack a label and its value vertically above 1.3).

See [Device and environment](https://nsh.dev/versions/main/docs/device-and-environment.md#text-size).

## Reduced motion

`reduce_motion()` (Rust) and `reduceMotion()` (TSX) are `true` when the user turned on iOS's Reduce Motion or Android's remove animations setting. Your animations run as you write them, so use it, or the `motion-reduce:` and `motion-safe:` Tailwind variants, to replace large movement with a fade or an instant change:

```rust
use nsh_core::{element::LayoutAnimation, prelude::*};

let toggle = move || {
    if !reduce_motion() {
        animate_layout(LayoutAnimation::SPRING);
    }
    expanded.update(|e| *e = !*e);
};

view()
    .on_press(toggle)
    .when(!reduce_motion(), |v| v.active(|s| s.scale(0.95)))
```

```tsx
import { View } from "nsh";
import { reduceMotion } from "nsh";
import { LayoutAnimation } from "nsh";

const toggle = () => {
  if (!reduceMotion()) LayoutAnimation.configureNext(LayoutAnimation.Presets.spring);
  expanded.set(!expanded());
};

<View onPress={open} class="transition active:scale-95 motion-reduce:transition-none" />
<View class="motion-safe:animate-bounce" />
```

## Touch targets

Make pressable elements at least 44 × 44 points. When a control must look smaller, extend its touch area with the hit slop (`.hit_slop(..)`, `hitSlop`) instead of its size; see [Touch and gestures](https://nsh.dev/versions/main/docs/touch-and-gestures.md#hit-areas-hitslop).

## Checking your app

- Turn on VoiceOver (iOS Settings, Accessibility, or triple-click the side button if set up) or TalkBack, and use the app without looking: every control should say what it is and what it does.
- On iOS simulators, Xcode's Accessibility Inspector shows each element's label, traits and value.
- Try the largest text size and dark mode.
- A test id (`.test_id(..)`, `testID`) gives UI tests a stable handle that does not change with the label's language.

## Related

- [`nsh`'s accessibility API](https://nsh.dev/versions/main/modules/nsh.md#accessibility): the reference.
- [`View`](https://nsh.dev/versions/main/elements/view.md): every accessibility prop.
- [Animation](https://nsh.dev/versions/main/docs/animation.md#reduced-motion) and [Device and environment](https://nsh.dev/versions/main/docs/device-and-environment.md).

Source: https://nsh.dev/versions/main/docs/accessibility

---

# Dev Server and Debugging

During development, NSH builds your app on every save. A Rust app (`nsh.json` names its `"root"`) is built into its
own runner, which `nsh run` starts; a change to its crate builds it again and restarts the app. A TSX app is pushed to
every connected host, which updates in place. Two commands do this:

- `nsh run` builds the app **and** launches it: a Mac Catalyst or AppKit window, a GTK window on Linux, a Win32 window
  on Windows, an iOS simulator, an Android device or emulator, or a browser page. For TSX it also starts the dev
  server, which the development host connects to.
- `nsh dev --server-only` starts the dev server for TSX, for hosts you start yourself: your own app with the
  development SDK, a device on the network, or several hosts at once.

```sh
# A Rust app, from its directory
nsh run                             # AppKit window (macOS); GTK window (Linux); Win32 window (Windows)
nsh run --target ios                # iOS simulator
nsh run --target android            # Android device or emulator

# A TSX app
nsh run App.tsx                     # AppKit window (macOS); GTK window (Linux); Win32 window (Windows)
nsh run App.tsx --target macos      # AppKit window (macOS)
nsh run App.tsx --target ios        # iOS simulator
nsh run App.tsx --target android    # Android device or emulator
nsh dev App.tsx --server-only       # server only
```

`nsh dev` also opens the native host by default; mobile hosts use `--target ios` or `--target android`.

## `nsh run`

| Flag | Description |
|---|---|
| `--target <catalyst \| ios \| android \| macos \| linux \| windows \| gpui \| web>` | Where to run. Default `macos` on macOS (AppKit), `linux` on Linux, `windows` on Windows. A Rust app runs on all of them but `gpui`, which embeds its root in a GPUI app ([GPUI](https://nsh.dev/versions/main/docs/gpui.md)). |
| `--device <name or UDID>` | The iOS simulator to use. Default: a booted one, else the newest iPhone (booted for you). |
| `--port <port>` | Dev server port. Default 8790; the next free port is used if it is taken. |
| `--release` | Serve release builds of TSX (minified, no debug info, no hot updates). |
| `--trace` | Log the time of every commit on the host (TSX apps). |

What each target does:

- **`catalyst`** (macOS) runs the development host as a Mac app. Stopping `nsh run` (Ctrl-C, or `kill`) closes it, and
  closing the window ends `nsh run`.
- **`macos`** (macOS) runs the AppKit development host, a desktop app in a 1200×800 window, the same way; Cmd+R
  reloads the latest build. Requires macOS 14 or later ([macOS](https://nsh.dev/versions/main/docs/macos.md)).
- **`linux`** (Linux) runs the GTK development host in a 390×844 window, the same way: stopping `nsh run` closes
  it, closing the window ends `nsh run`. Requires GTK 4.14 or later ([Linux](https://nsh.dev/versions/main/docs/linux.md)).
- **`windows`** (Windows) runs the Win32 development host in a 1200×800 window, the same way; the host never outlives
  `nsh run`, even when the console is closed. Requires Windows 10 1809 or later ([Windows](https://nsh.dev/versions/main/docs/windows.md)).
- **`ios`** installs the development host in the simulator, launches it pointed at the dev server and keeps watching.
  The simulator shares the Mac's network, so the host reaches the server on `127.0.0.1`. Stopping `nsh run` (Ctrl-C)
  closes the host, which would otherwise join the next session. Requires Xcode.
- **`android`** installs the development host APK (again only when the runtime changed), runs
  `adb reverse tcp:<port> tcp:<port>` so the device's own `127.0.0.1` reaches the server, and starts it. Works with an
  emulator or a USB device. Requires the Android SDK (`ANDROID_HOME`). When `nsh run` ends (Ctrl-C too), it stops the
  host and removes that port forwarding, so the host does not join the next session.

When `nsh run` ends, however it ends, it stops the host it started: it quits the Catalyst app or closes the macOS, Linux or Windows host, terminates the
development host in the simulator, or force-stops it on the device.

For a Rust app each target runs the app's own runner, built with its crate: the desktops a debug build in place, with
its output in the terminal; iOS and Android a package of it, installed. For TSX the hosts are generic: they run any
NSH app the server sends, so there is nothing to build per app (an app with a crate of its own gets hosts built with
it).

## `nsh dev`

```sh
nsh dev App.tsx
```

```text
✓ built App.tsx (3.2 KB js, 9.8 KB bytecode, 21ms)
→ dev server ws://127.0.0.1:8790/ws
  devices on this network: ws://192.168.1.20:8790/ws
```

| Flag | Description |
|---|---|
| `--port <port>` | Dev server port. Default 8790 (the next free one if taken). |
| `--release` | Serve release builds. |

Connect hosts to the printed URL:

- **Your own iOS app**, linked with `NativeShellDev.xcframework`:
  `try app.connectDevServer(URL(string: "ws://192.168.1.20:8790/ws")!)`. See [Embedding in iOS apps](https://nsh.dev/versions/main/docs/ios.md#development).
- **Your own Android app**, with `nsh-dev.aar`: `nsh.connectDevServer("ws://192.168.1.20:8790/ws")`, or
  `adb reverse tcp:8790 tcp:8790` and `ws://127.0.0.1:8790/ws`. See [Embedding in Android apps](https://nsh.dev/versions/main/docs/android.md#development).

Any number of hosts can be connected at once; every build goes to all of them. A host that connects later receives the
current build right away. A host that cannot run the app, because it lacks a UI set the app imports (a development
host built for another app), gets no build: it shows why, and the terminal prints a `warn` line with the command that
installs the app's host.

> [!NOTE]
> A device on the LAN needs to reach your computer on the dev server's port: same network, no firewall in between.
> Assets (images, fonts) are served over plain HTTP from the same port.

## Rust edits

Rust is compiled: a change to an app's crate, or to a crate it depends on by path, builds the app again, and `nsh run`
restarts it with the new code. The app's state starts afresh; keep what must survive a restart in
[storage](https://nsh.dev/versions/main/modules/nsh.md#storage). A build error is printed in the terminal, and the next save that compiles runs
again. In an app with Rust and TSX, TSX edits stay hot updates (below) and Rust edits restart the app.

## Hot module replacement

TSX development builds keep one module per source file. When you save, NSH rebuilds, compares the modules with the last
good build and sends a **patch** with only the modules that changed. The host applies it in place in well under a
millisecond; from saving a file to seeing the change takes roughly 120 ms.

What happens to your app:

- **Only the components you edited render again.** Every top-level component (a capitalized function that returns JSX)
  is wrapped in a stable proxy. When its code changes (or the rest of its module's code, which it may use), its
  instances render again with the new code; components whose code did not change keep their instances, and with them
  their signals and state. Edit a button's style and the
  screen stays where it was, with the same input text and scroll position.
- **Modules that changed run again**, and so do the modules importing a changed module that cannot take the update
  by itself, up to the entry. Module-level code therefore runs again, except for what keeps its state:
- **Top-level signals and navigation stacks keep their state**: a `const` made by `signal(…)` or `createNavStack(…)` at the
  top of a module keeps its value (a stack its pages) across edits, as long as its own initializer is the same;
  change the initializer (`signal(0)` to `signal(10)`) to start afresh.
- **Top-level `context()` objects keep their identity**, taking the new default value, so providers and consumers in
  different modules keep matching.
- **Editing the entry keeps the app mounted.** `mount(App)` (or `mount(() => <App />)`) run again with the same
  component keeps what it mounted: only the components you edited render again. Edit `App` itself and it renders
  again, with what it renders (their own state starts afresh), but a navigator made at the top of the module keeps its
  routes, so a pushed screen stays pushed. A `mount` call that changed (another component, props) mounts the app
  again.
- **A component that throws** reports the error and renders nothing until you fix it; the rest of the app keeps
  running. The next good save recovers.

The host **reloads the whole app** instead of patching when:

- the change imports an NSH module the running app did not import yet (for example the first `import … from "nsh"`);
- the app's `capabilities` in `nsh.json` changed;
- the host is not running the build the patch is based on (it just connected, or a previous load failed);
- a patch cannot be applied.

> [!TIP]
> State a component keeps in its own signals resets when that component, or one that renders it, is edited. Keep
> state that must survive edits in top-level signals (or a store module), and make navigators at the top of a module.

`--release` serves release builds, without hot updates: every save reloads the app. Use it to check the minified build.
Anything loaded from a dev server, `--release` or not, skips the runtime's hardening (`eval` stays available); see
[Sandbox and capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md#hardening).

## Logs

A Rust app logs with the `log` crate (`log::info!`, `log::warn!`, `log::error!`): `nsh run` shows the lines in its
terminal, with the app's output, on the desktops and in the iOS simulator.

In TSX, `console.log`, `console.info`, `console.debug`, `console.warn` and `console.error` go to the native log with
target `js`. While a host is connected, its log lines are forwarded to the terminal running `nsh run` / `nsh dev`: your
`console.log` lines as they are (prefixed with the device's name when several devices are connected), warnings and
errors after the device's name:

```text
• iPhone 16 Pro connected, build 1
loading more after 1000
warn iPhone 16 Pro: deprecated option
error iPhone 16 Pro: uncaught exception: TypeError: cannot read property 'id' of undefined
          at Row (demos/Photos.tsx:18:22)
```

`console.log` formats values like a browser console: strings as they are, errors with their stack, functions by name,
objects and arrays as JSON. When the host is not connected, logs go to the platform's log (Xcode's console / the
unified log on iOS, `adb logcat` on Android).

A promise that is rejected and still has no handler once the work that rejected it is done (its microtasks ran) is
logged as an error too, the way a browser reports it: an `async` function that throws while nobody awaits it, a
`Promise.reject(…)` nobody catches, a call into Rust that fails with nothing waiting for it. The line goes wherever
`console.error` goes (the terminal, the platform's log, the browser console on the web), with its stack pointing at
your sources:

```text
error iPhone 16 Pro: unhandled rejection: Error: HTTP 404
          at loadProfile (App.tsx:12:11)
```

A handler attached later in the same turn (`const p = load(); …; p.catch(…)`) counts as handling it. Await the
promise or give it a `.catch` where the failure matters.

The rest of the terminal is one line per step (`✓` done, `→` where to connect, `•` what a device did); the output of
the tools NSH runs (cargo, the hosts themselves) is only printed when one fails. `nsh run -v` (or `NSH_VERBOSE=1`)
prints everything: every log line with its level and source, cargo's output and the hosts' own.

`--trace` adds the cost of every commit:

```text
perf commit: 10 ops, 151µs (list js 2µs), 8 mount items, 27 nodes
```

See [Testing](https://nsh.dev/versions/main/docs/testing-and-trace.md) for what these numbers mean.

## The error overlay

These errors show a red overlay over the app on the host, with the message and stack:

- a build failure (a syntax error, an unknown element, a missing import), with a code frame pointing at the line;
- an error while the bundle is evaluated;
- an uncaught exception in an event handler, timer or effect.

Tap the overlay to dismiss it. It also disappears on the next successful reload. Build failures are printed in the
terminal too:

```text
error building App.tsx failed
App.tsx

  x <Buton> names nothing in scope
   ,-[3:11]
 2 | function App() {
 3 |   return <Buton />;
   :           ^^^^^
 4 | }
```

The bundler removes TypeScript types without checking them; run [`nsh check`](https://nsh.dev/versions/main/docs/cli.md#nsh-check) (TypeScript's
native compiler with the `tsconfig.json` `nsh init` writes; no Node needed) or rely on your editor for type errors.

In release builds (an embedding app with the release SDK, a packaged app), errors are logged and passed to the host
app's error handler (`NshAppView.onError`, `NshView.setErrorListener`) but not shown over the app.

## Source maps and stack traces

Bundling produces a source map that composes every step (TypeScript → JSX → the bundle), and it is sent along with each
build. Before a stack trace is printed or shown, the runtime rewrites the bundle's positions to your sources, so stacks
point at `App.tsx:2:28`, not at the bundle:

```text
error Mac Catalyst: uncaught exception: Error: tap boom
          at <anonymous> (App.tsx:2:58)
```

`nsh build` writes the map as `bundle.js.map`; an embedding app that loads a bundle from a folder reads it from next to
the bundle, and [signed packages](https://nsh.dev/versions/main/docs/signed-packages.md) carry it too, unless it is kept next to the package and applied
with `nsh symbolicate` ([Errors from published packages](https://nsh.dev/versions/main/docs/signed-packages.md#errors-from-published-packages)).

## Debugging tips

- **Nothing updates after an edit**: check the terminal for a build error; the overlay shows it on the host too.
- **The app keeps old state you expected to reset**: hot replacement keeps unchanged components' state, top-level
  signals and navigators on purpose. Restart with Ctrl-C and `nsh run`, or change the state's initializer.
- **A request fails only in a packaged or embedded build**: check the app's [capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md);
  refusals are logged with the key to add.
- **Something is slow**: reproduce it headless with [`nsh test --trace`](https://nsh.dev/versions/main/docs/testing-and-trace.md), which prints every
  native view operation, or run a TSX app with `--trace`.
- **Type errors in the editor**: `nsh run` and `nsh dev` keep `.nsh/types` up to date; see
  [Project structure](https://nsh.dev/versions/main/docs/project-structure.md).

## See also

- [CLI](https://nsh.dev/versions/main/docs/cli.md)
- [Testing](https://nsh.dev/versions/main/docs/testing-and-trace.md)
- [Embedding in iOS apps](https://nsh.dev/versions/main/docs/ios.md), [Embedding in Android apps](https://nsh.dev/versions/main/docs/android.md)

Source: https://nsh.dev/versions/main/docs/dev-server-and-debugging

---

# Testing

NSH runs apps **headless**: the real engine (the same reactive graph, renderer, components, layout and list
virtualization as on a device, and QuickJS for TSX), with display frames at 60 Hz, but no simulator, no device and no
window. It runs anywhere Cargo or the CLI runs, including Linux CI machines, and does two jobs:

- it runs tests: each opens the app, takes the steps a user would (press, type, scroll), and checks what is on screen.
  A Rust app's tests are Rust, run by `cargo test` with the `nsh-testing` crate; tests written in TypeScript run with
  `nsh test`, for TSX apps and Rust apps alike;
- with `--trace`, it prints every operation the runtime sends to the native views, with timings: what the first
  frame, a tap or a frame of scrolling costs.

## Writing tests

The same test, in Rust and in TypeScript: it opens the app with an empty todo list in its storage, types, presses and
checks what the screen shows.

```rust
// tests/app/main.rs
use nsh_engine::{EngineConfig, Root};
use nsh_testing::{Headless, MemoryStorage};

#[test]
fn adds_a_todo() {
    let mut config = EngineConfig::new(Root::of::<my_app::App>());
    config.storage = Some(MemoryStorage::new([("todos".to_owned(), "[]".to_owned())]));
    let mut app = Headless::start(config).unwrap();
    app.type_text("id:new-todo", "Buy milk").unwrap();
    app.press("text:Add").unwrap();
    app.wait_for("text:Buy milk").unwrap();
    assert!(app.screen().texts().contains(&"1 item left"));
}
```

```tsx
// App.test.tsx
import { expect, open, test } from "nsh/test";

test("adds a todo", async () => {
  const app = await open("./App.tsx", { storage: { todos: "[]" } });
  await app.type("id:new-todo", "Buy milk");
  await app.press("text:Add");
  await app.waitFor("text:Buy milk");
  expect(app.texts()).toContain("1 item left");
});
```

## Tests in Rust with cargo test

A Rust app's tests are integration tests of its crate, with `nsh-engine` and `nsh-testing` (its default features,
without QuickJS) as dev-dependencies:

```toml
[dev-dependencies]
nsh-engine = "0.1"
nsh-testing = "0.1"
```

```sh
cargo test                    # every test of the crate
cargo test adds_a_todo        # the tests whose name contains "adds_a_todo"
```

`EngineConfig::new(root)` is a phone-sized engine (390×844 points) with nothing else set; its fields set what `open`'s
options set below: `storage` (`MemoryStorage::new(entries)`), `network` (`StubNetwork`, below), `viewport`,
`environment` (the appearance, the locale, reduced motion), `clock` (`Clock::manual(time)`, below).
`nsh_testing::Headless::start(config)` starts the app and keeps a model of the views it shows. Its steps are those of
`nsh test` below, with the same selectors, in Rust: `press`, `long_press`, `clear`, `type_text`, `submit`,
`scroll(selector, px(3000.0))`, `back`, `wait`, `wait_for`, `wait_for_gone`, `wait_until`, `run_for`, `fast_forward`,
`set_system_time`, `set_viewport`, `set_clipboard` and `on_dialog`; `app.shows(text)` and `app.screen()` (`texts()`,
`count(selector)`, `enabled(selector)`, `dialogs()`, `clipboard()`, `commands()`) read what is on screen. A step
returns an error with the texts on screen when it cannot be taken.

`nsh_testing::tsx(entry, sets)` (feature `bundle`) opens an app's TSX entry the same way, built against NSH's and the
crate's UI sets ([Building with Rust](https://nsh.dev/versions/main/docs/rust.md#testing)). `examples/gallery-rs` tests its Rust root this way, one
module per demo; `examples/rust-exports` tests its TSX entry from Rust.

`nsh test` runs these tests too: given the directory of an app with Rust crates (`nsh.json` `"rust"`), it runs
`cargo test` for each crate in it before the test files, and shows and counts the Rust tests with the TypeScript ones
(`✓ src/lib.rs › tests::adds`), in its summary and its `--junit` report. So `nsh test` is the one command for a Rust app,
a TSX app with a crate and a TSX app alike, and `nsh check` likewise runs `cargo check --all-targets` on the crates
before it type checks the TypeScript.

## Tests with nsh test

A test file is a `*.test.tsx` or `*.test.ts` file next to your code. It imports `nsh/test`, as `App.test.tsx` above
does:

```sh
nsh test                      # every test file of the app in the current directory
nsh test App.test.tsx         # one file
nsh test --filter "adds"      # the tests whose name contains "adds"
```

```text
✓ App.test.tsx › adds a todo (84ms)
✗ App.test.tsx › keeps todos after a restart (312ms)
    expected ["Todos","0 items left"] to contain "1 item left"
    at <anonymous> (App.test.tsx:21:22)
    on screen: "Todos", "0 items left"
error 2 tests: 1 passed, 1 failed (0.9s)
```

A failing test shows what was thrown, where in the test file, and the texts on screen of the app it opened. Any failure
makes `nsh test` exit with a non-zero code. `nsh init` creates an `App.test.tsx` with the app, and `nsh check` type
checks test files with the rest (`.nsh/types` declares `nsh/test`).

Each test file runs on an engine of its own, and its tests run one after the other, in order. `open` starts the app on
another engine, a fresh one each time, so tests never share state; the apps a test opened are closed when it ends. A
test fails when it throws, when the promise it returns rejects, and after its timeout: 30 seconds, or the milliseconds
`test`'s third argument gives (`test("syncs", body, 60_000)`). An app with Rust crates of its own
(`nsh.json` `"rust"`) runs its tests in a headless runner NSH builds with them, the same way; in a Rust app
(`nsh.json` `"root"`, [Building with Rust](https://nsh.dev/versions/main/docs/rust.md)), `open(".")` starts its root component.

### Grouping tests and setting them up

`describe`, the hooks and the variants of `test` work as Jest's:

```tsx
import { beforeEach, describe, expect, open, test } from "nsh/test";
import type { App } from "nsh/test";

describe("the cart", () => {
  let app: App;
  beforeEach(async () => {
    app = await open("./App.tsx", { storage: { cart: "[]" } });
    await app.press("Cart");
  });

  test("starts empty", () => {
    expect(app.texts()).toContain("No items");
  });

  test.todo("applies a coupon");
});
```

| Function | Description |
|---|---|
| `describe(name, body)` | Groups the tests and blocks `body` declares (at once, as the file loads): their names start with `name` (`the cart › starts empty`), and the hooks it declares run around them only. Blocks nest. |
| `beforeEach(fn, timeout?)`, `afterEach(fn, timeout?)` | Run `fn` before / after each test of the block they are declared in (the file, a `describe`): `beforeEach` of the outer blocks first, `afterEach` of the inner ones first. A `beforeEach` that fails fails the test; `afterEach` runs either way. |
| `beforeAll(fn, timeout?)`, `afterAll(fn, timeout?)` | Run `fn` once before the first and after the last test of their block, when one of its tests runs. A `beforeAll` that fails fails the block's tests; an `afterAll` that fails is reported as a failed `<block> › afterAll`. An app a `beforeAll` opens stays open for the block's tests, and is closed after its `afterAll`. |
| `test.skip(name, body, timeout?)`, `describe.skip(name, body)` | Declares a test, or a block whose tests, do not run: they are reported as skipped. |
| `test.only(name, body, timeout?)`, `describe.only(name, body)` | While a test file has one, only those tests and blocks run; the file's others are reported as skipped. |
| `test.todo(name)` | A test still to write, reported as one. |

A hook may be `async`; its `timeout` is 30 seconds unless given. Tests and hooks are declared as the file loads: a
test declared inside a test or a hook throws.

### Opening the app

`open(entry, options?)` builds the app at `entry` (relative to the test file; each entry is built once per run),
starts it on a 390×844 viewport and resolves once it rendered and is quiet. With `--target`, the app runs with the
options as the test gives them: one the target's platform cannot honor makes `open` reject with
`ERR_NSH_TEST_UNSUPPORTED`, naming it (see [On a real platform](#on-a-real-platform)).

| Option | Default | Description |
|---|---|---|
| `storage` | empty | What `Storage` holds at the start: `{ todos: "[]" }`. |
| `network` | none | What the app's requests get, by route: see [Stubbing the network](#stubbing-the-network). `"live"`: the real network, for its requests, sockets and WebSockets. |
| `width`, `height` | 390, 844 | The viewport in points: headless, the desktops' window, the web's page. On iOS and Android the app fills the device's screen. |
| `safeArea` | 0 | The safe area insets in points: `{ top: 47, bottom: 34 }`. |
| `clipboard` | empty | The text on the clipboard at the start. |
| `colorScheme` | `"light"` | The system's appearance: `"light"` or `"dark"` (`colorScheme()`, `dark:` classes). |
| `locale` | `"en-US"` | The device's locale, a BCP 47 tag (`locale()`, `Intl`'s default). |
| `reducedMotion` | `false` | The user asked for less motion (`reduceMotion()`). |
| `platform` | `"ios"` | The platform the app runs as headless: `"ios"`, `"android"`, or a desktop's, `"macos"`, `"windows"`, `"linux"`, or `"web"` in the desktop idiom (`platform.os`, `ios={{…}}` / `android={{…}}` / `desktop={{…}}` props, keyboard shortcuts). With `--target`, the app runs as the target's platform: a desktop's `platform` on any desktop and the web, always as a desktop (in the browser in the desktop idiom at any width, `platform.os` staying `"web"`), `"ios"` and `"android"` on their own. |
| `clock` | the system's | A manual clock, whose time moves only as the test moves it: `{}`, or `{ time }` to start at a `Date` (or milliseconds since the Unix epoch). See [Controlling time](#controlling-time). |
| `host` | none | The embedding app's part, which the test plays: `{ params, handlers }`. See [Playing the host app](#playing-the-host-app). |

### Playing the host app

An app embedded in a native app talks to it through [`host`](https://nsh.dev/versions/main/modules/nsh.md#host). In a test, the test plays
the host app: `host.params` gives the launch parameters the app reads at start, and `host.handlers` answers the app's
`host.call` and hears its `host.post`, by name. A handler is a value, which answers every call, or a function of the
call's data that returns the answer (or a promise of it). What the function throws rejects the call, as a host app's
error does. A call of a name `handlers` does not list fails, as it does in a host app that handles none.

```tsx
const app = await open("./App.tsx", {
  host: {
    params: { conversation: "c-42" },
    handlers: {
      "user.profile": async ({ id }) => ({ id, name: "Ada" }),
      "feature.flags": { search: true },
      analytics: null,
    },
  },
});
await app.press("Profile");
expect(app.host.calls()).toEqual([{ name: "user.profile", data: { id: 7 } }]);
expect(app.host.posts()).toEqual([{ name: "analytics", data: { screen: "profile" } }]);
// The app's `host.on("conversation.open", …)` hears it.
await app.host.send("conversation.open", { id: "c-43" });
expect(app.shows("Conversation c-43")).toBe(true);
```

`app.host.send(name, data)` sends an event, then waits until the app is quiet. `app.host.calls()` and
`app.host.posts()` list what the handlers got, in order: `name` and `data`.

The URLs the app opens ([`openUrl`](https://nsh.dev/versions/main/modules/nsh.md#openurl), a `TextView`'s links with `links="open"`) are
recorded and reported to the app as opened, and nothing opens on this machine. `app.openedUrls()` lists them:

```tsx
await app.press("Contact us");
expect(app.openedUrls()).toEqual(["mailto:help@example.com"]);
```

### Stubbing the network

`network` lists routes by `"<METHOD> <URL>"` (a bare URL is a `GET`; `*` matches any text). A request no route
matches fails, so tests never reach the network unasked. A route is a response, or a function of the request that
returns one (or a promise of one); in Rust, `StubNetwork::new(routes)` takes the same routes, each a `StubResponse` or
a `StubRoute::Handler`:

```rust
use std::sync::Arc;
use nsh_engine::{EngineConfig, Root};
use nsh_testing::{Headless, StubNetwork, StubResponse};

#[test]
fn adds_a_todo_on_the_server() {
    let mut todos = StubResponse::default();
    todos.status = 200;
    todos.headers = vec![("content-type".to_owned(), "application/json".to_owned())];
    todos.body = br#"[{ "id": 1, "title": "Walk" }]"#.to_vec();
    let mut created = StubResponse::default();
    created.status = 201;
    let mut offline = StubResponse::default();
    offline.error = Some("offline".to_owned());
    let network = Arc::new(StubNetwork::new([
        ("GET https://api.example.com/todos".to_owned(), todos),
        ("POST https://api.example.com/todos".to_owned(), created),
        ("GET https://api.example.com/sync".to_owned(), offline),
    ]));
    let mut config = EngineConfig::new(Root::of::<my_app::App>());
    config.network = Some(network.clone());
    let mut app = Headless::start(config).unwrap();
    app.press("Add").unwrap();
    let methods: Vec<String> = network.requests().iter().map(|r| r.method.clone()).collect();
    assert_eq!(methods, ["GET", "POST"]);
}
```

```tsx
const app = await open("./App.tsx", {
  network: {
    "GET https://api.example.com/todos": { body: [{ id: 1, title: "Walk" }] },
    "POST https://api.example.com/todos": (request) => ({ status: 201, body: JSON.parse(request.body!) }),
    "GET https://api.example.com/todos/*": { status: 404 },
    "GET https://api.example.com/sync": { error: "offline" },
    "GET https://api.example.com/slow": { body: "done", delay: 2000 },
  },
});
await app.press("Add");
expect(app.requests().map((r) => r.method)).toEqual(["GET", "POST"]);
```

| Response member | Default | Description |
|---|---|---|
| `status` | 200 | The status code. |
| `headers` | none | Header names and values. |
| `body` | empty | A string, or a value sent as JSON (with `content-type: application/json` unless `headers` name one). |
| `error` | none | The request fails with this message instead, as when the device is offline. |
| `delay` | 0 | How long the response takes, in milliseconds; a step does not wait for it, `waitFor` does. On a manual clock, it comes once the clock passes it. |

A route's function gets the request (`method`, `url`, `headers`, `body` as text) and runs in the test file, so it can
count requests or answer from what the test set up. A function that throws fails the request and the step that made
it. `app.requests()` lists the requests the app made, in order, the same way.

Connections stay in the test too: the app's sockets (`net`) and WebSockets (the global `WebSocket` and the `websocket`
module) open none unless `network` is `"live"`. After the capability checks the app's own runs pass, `net.connect`
and the `websocket` module's `connect` reject with `code` `ERR_NSH_TEST_NETWORK`, and a global `WebSocket` fires `error`, then
`close` (1006, not clean), as for a connection the network refused. With `"live"`, they connect to the real network
along with the app's requests. In Rust, `EngineConfig::refuse_connections` does the same for a `Headless` app: a
function of what the app connects to (a WebSocket's URL, a socket's `host:port`) that returns the error its call
fails with.

### Controlling time

On the system's clock, an app's timers and native animations take as long as on a device, and so do the tests that
wait for them. With a manual clock (`EngineConfig::clock` in Rust, `open`'s `clock` in TypeScript), the app runs on a
clock whose time moves only as the test moves it, and at once, as with Jest's fake timers or Playwright's
`page.clock`. `app.clock` is that clock, and `null` when the app runs on the system's:

```rust
use std::time::{Duration, SystemTime};
use nsh_engine::{Clock, EngineConfig, Root};
use nsh_testing::Headless;

#[test]
fn autosaves() {
    let mut config = EngineConfig::new(Root::of::<my_app::App>());
    // 2026-01-01T09:00:00Z
    config.clock = Clock::manual(SystemTime::UNIX_EPOCH + Duration::from_secs(1_767_258_000));
    let mut app = Headless::start(config).unwrap();
    app.type_text("label:Note", "Milk").unwrap();
    app.run_for(Duration::from_secs(10)).unwrap(); // the autosave, ten seconds later
    assert!(app.shows("Saved at 09:00:10"));
}
```

```tsx
const app = await open("./App.tsx", { clock: { time: new Date("2026-01-01T09:00:00Z") } });
await app.type("label:Note", "Milk");
await app.clock!.runFor(10_000);           // the autosave, ten seconds later
expect(app.texts()).toContain("Saved at 09:00:10");
```

A `StubNetwork` whose responses have a `delay` follows a manual clock with `.with_clock(clock.clone())`. The steps below
are `nsh test`'s; `Headless` has each of them (`run_for`, `fast_forward`, `set_system_time`).

| Step | Description |
|---|---|
| `await app.clock.runFor(ms)` | Moves the clock by `ms` milliseconds, one display frame at a time. Timers, `requestAnimationFrame`, native animations and delayed responses run as they come due, in order, each at its time. Resolves once the app is quiet. |
| `await app.clock.fastForward(ms)` | Moves the clock by `ms` milliseconds at once, as a device waking from sleep does: the timers due meanwhile run once each. |
| `app.clock.setSystemTime(time)` | Sets the wall time (`Date.now()`, `new Date()`) to a `Date` or milliseconds, moving no timer. |

`Date`, `performance.now()` and `Intl`'s default date follow the clock. Steps finish what is running without waiting
for it: while the app asks for frames or a native animation runs, frames come one after another, each a frame's time
(1/60 s) later on the clock. A 300 ms transition takes a few milliseconds, and a timer due during it runs. An
animation that loops forever (a spinner) runs along with the clock: it turns as the test moves the clock. `app.wait(ms)`
and a long press move the clock by their time. A timer that comes due later runs only when the test moves the clock
there. `waitFor` and `waitUntil` move the clock while they wait, a display frame at a time, looking after each frame,
so what a timer shows comes as they wait for it, in a moment: `waitFor("Saved", { timeout: 15_000 })` moves the clock
by up to fifteen seconds. Their timeout counts on both clocks: a wait moves the app's clock by it at most, and rejects
once as much real time passed too, so what comes from outside the app (a route's function, the network) has as long
as on the system's clock. The gallery's tests run this way (`examples/gallery/tests`): its twelve tests that wait for animations
take 6 s instead of 28 s.

### Steps

Steps name views with **selectors**, written as Playwright's:

| Selector | Matches |
|---|---|
| `id:<testID>` | The view with that `testID`. |
| `label:<label>` | The view with that `accessibilityLabel`. |
| `text:<text>` | A text that reads it (spaces around it aside), a span of a text that takes presses (a nested `<Text onPress>`, a `TextView`'s link), or an input holding it or, while empty, with that placeholder. |
| `role:<role>`, `role:<role>[<name>]` | A view with that `role` (`role:button`), and that name: its label, else the texts in it (`role:button[Save]`). |
| `view:<id>` | The view with that id in `--trace` output. |
| anything else | A `testID`, else a label, else a text, as written. |

A part that starts with a lowercase word and a colon names a prefix (`id`, `label`, `role`, `text`, `view`), so
`tapped: solo` is a step error that lists them. A text, label or test id that starts this way takes its prefix, which
reads the rest as written: `text:tapped: solo`, `label:note: draft`, `id:row:2`. Selectors keep their meaning as new
prefixes arrive.

`label:`, `text:` and a role's name also take a regex: `text:/^Buy/i`, written in the syntax of Rust's `regex` crate
(JavaScript's classes, groups, anchors and quantifiers, matched in linear time; flags `i`, `m` and `s`). ` >> ` looks
inside what the part before matched (`id:cart >> role:button[Remove]`), and `nth=<n>` keeps one of the matches, from 0
(`text:Delete >> nth=1`). A selector finds the views a user would look at first: in the top modal, then on screen,
and of a navigation stack only the top screen. It matches what the user sees: views with an area, outside `visibility: hidden`, inside the window and
the views that clip them (`overflow: hidden`), or anywhere in the content of a scroll view the user can scroll, which
scrolling brings in (`opacity` and transforms aside, as in Playwright). A step that acts on a view (`press`, `type`, `clear`, `submit`, `scroll`, `longPress`) needs exactly
one: a selector matching several fails the step, and the error says how to narrow it.

| Step | Description |
|---|---|
| `await app.press(selector)` | Presses the view, or the nearest view around it that hears presses (the button around a text): `onPressDown`, `onPressUp`, `onPress`, inside a finger going down and lifting, which the views around it that listen to touches hear (an overlay's `onPressOutside`). A span of a text is pressed on its characters (`await app.press("Privacy policy")`), headless and on iOS, Android and the desktops. A second press of the same view within 500 ms is its second click (`clicks: 2`, a double press), as the platforms count them. Rejects when it is disabled. |
| `await app.longPress(selector)` | Holds a finger on it (or the nearest view around it that hears presses or touches) for its `delayLongPress` (500 ms): `onPressDown`, `onLongPress`, `onPressUp`; no `onPress` follows. The touches' handlers hear the finger (a `ContextMenu` or `Tooltip` opens). |
| `await app.clear(selector)` | Empties the input, as selecting all and deleting does. |
| `await app.type(selector, text)` | Types into the input (or the first input inside the view; `text:` also matches an input's text or placeholder) at the end of what it holds, key by key: it takes the focus, then each character is an `onKeyPress` and an `onChange`, within `maxLength`. A `\n` in a single-line input is the return key. |
| `await app.submit(selector)` | The return key in the input, as its `submitBehavior` says: `onSubmit` (and the focus leaves a single-line input), or a line break in a multiline one. |
| `await app.scroll(selector, distance)` | Drags the scroll view or list (the view, the one around it, or the first inside it) by `distance` points along its axis, 10 points per frame, within its content, as the user may (`scrollable`). Negative scrolls back. |
| `await app.hover(selector)` | Moves the mouse over the middle of the view: the views under it that it left hear `onMouseLeave`, those it came over `onMouseEnter` and take their `hover:` styles, and those listening hear `onMouseMove` with where it is and no button down. The desktops and the web at any width, a browser in the phone idiom included (headless: a desktop or `"web"` `platform`); an iOS or Android phone has no mouse: there it rejects. |
| `await app.rightClick(selector)` | The mouse's secondary button over the middle of the view: it, or the nearest view around it listening, hears `onContextMenu`. The desktops and the web (headless: a desktop `platform`); a phone has no mouse: there it rejects. |
| `await app.paste(selector, { text?, html?, files?, uris? })` | Pastes into the input as the user does with that on the clipboard: it takes the focus and hears `onPaste` (`html` the same content with its formatting, `files` are paths whose bytes it gets as `File`s, `uris` `file:` URLs), then its text goes in as `pasteBehavior` says. Headless, on macOS, on iOS and on the web; the machine's clipboard stays as it was. |
| `app.menu()` | The actions of the context menu the app shows (`Menu.popup`): `label` (a submenu's after its own, `"Share > Mail"`), `disabled`, and `checked` for a checkable item; `null` when none is open. |
| `await app.chooseMenuItem(label)` | Chooses the open context menu's action, as a click on it does: the app hears `onMenu` (its `onSelect` runs), then the menu closes. Rejects when the item is disabled or missing. |
| `await app.closeMenu()` | Closes the open context menu with nothing chosen, as Escape does. |
| `await app.keyboard.press(keys)` | Presses a key with its modifiers, as `keymap` names it (`"mod+k"`, `"shift+/"`, `"escape"`; `mod` is the platform's command key), on a hardware keyboard, on every platform (phones and tablets have one too): the app's shortcut of it hears it (`keymap.bind`, `onKeyCommand`), else on macOS and the web Tab and Shift+Tab move the keyboard focus between the inputs and the views that take presses (`onFocus`, `onBlur`, `focus:` styles) and Return or Space presses the view it is on, else the focused input takes a character, Backspace or the return key, else Escape goes back. |
| `await app.keyboard.down(keys)` / `up(keys)` | Holds modifier keys (`"mod"`, `"shift"`, `"alt"`, `"ctrl"`, `"meta"`, joined by `+`) down until `up`: the presses, drags and hovers meanwhile carry them, as a Mod-click or a Shift-drag does. Headless and on Linux for now. |
| `await app.dragAndHold(selector, by)` / `app.drop()` | Drags as `drag` does and keeps the finger down until `drop()`, which lifts it where it is: the steps between look at the screen mid-drag (a drag preview, a drop line). Headless and on Linux for now. |
| `await app.dropFiles(selector, uris)` | Drops local files (`file:` URLs, as a file manager drags them) on the middle of the view: it, or the nearest view around it listening, hears `onFileDrop`. Desktops, headless and on Linux for now. |
| `await app.drag(selector, { x, y })` | A finger lands on the middle of the view, rests for 100 ms, moves by `x`, `y` points, 10 per frame, and lifts, as the platform's input takes it: a pan follows it (`pan={{ x, y }}`, `onPanStart`, `onPanEnd` with the release velocity), the views listening to touches hear it (`onTouchStart`, `PanResponder`), a scroll view scrolls with it and, pulled far enough past its top, refreshes (`onRefresh`), and a press under it is cancelled once it moves away. On the desktops and the web it is the mouse. |
| `await app.wait(ms)` | Lets the app run for `ms` milliseconds: timers, animations, requests. On a manual clock, moves it by `ms` (`app.clock.runFor`). |
| `await app.waitFor(selector, options?)` | Resolves once a view matches, or with `{ state: "gone" }` once none does; rejects after `timeout` ms (5000). On a manual clock, moves it a display frame at a time while it waits, by `timeout` at most. |
| `await app.waitUntil(condition, options?)` | Resolves once `condition()` returns true, looking again after each change of the app: for what no selector says (`() => app.storage().note === "Milk"`). On a manual clock, moves it a display frame between two looks, by `timeout` at most. |
| `app.shows(selector)` | Whether a view matches now. |
| `app.count(selector)` | How many views match now. |
| `app.enabled(selector)` | Whether the view takes input: neither it nor a view around it is disabled, and an input is not `readonly`. |
| `app.texts()` | The texts on screen now, in order. |
| `app.value(selector)` | The text of an input, `null` when none matches. |
| `app.spanStyle(selector)` | The first matched character’s resolved style, headless and on every `--target`: `color`, optional `backgroundColor`, `fontSize`, `fontWeight`, `italic`, `underline`, and `lineThrough`. Colors are `#rrggbbaa`; sizes are in points. |
| `app.storage()` | What the app's storage holds now. |
| `await app.back()` | Goes back as the user does (a header's back button, swiping a sheet down): the innermost stack of the newest modal, else of the screen, pops its top screen (`onDismiss`), or asks it (`onBackRequest`) when it has `preventBack`; without one, the newest modal asks to close (`onRequestClose`). Rejects when there is nothing to go back from. |
| `app.onDialog(handler)` | Answers the dialogs the app shows from now on (`Alert.alert`, action sheets): `handler` gets the dialog (`title`, `message`, `buttons`, `cancelable`, `sheet`) and returns the text of the button to press, or `null` to close it without one. |
| `app.dialogs()` | The dialogs the app showed, in order. |
| `app.onPick(handler)` | Answers the picks the app asks for from now on (`Picker.pickImages`): `handler` gets what the pick asks (`multiple`, `limit`, `maxDimension`, `quality`, `format`) and returns the files the user picks (`{ name, type?, data: Uint8Array }`, given to the app as they are), or `null` to cancel. Without a handler, picks are cancelled. Headless runs. |
| `app.picks()` | The picks the app asked for, in order. |
| `app.hear(text)` | The user says `text` into the running speech session (`Speech.start`): its `result` reports `text` as the whole transcript so far. Headless runs. |
| `app.endSpeech(error?)` | Ends the running speech session: with `error` (`"no-speech"`, `"network"`, ...) it fails, else a last final result and `end` come, `no-speech` when nothing was heard. Headless runs. |
| `app.speechRequests()` | The speech sessions the app started, in order: `lang` (`null` for the user's) and `interim`. |
| `app.clipboard()` | The text on the clipboard now, `null` when it holds none. |
| `app.requests()` | The requests the app made, in order: `method`, `url`, `headers`, `body`. |
| `await app.host.send(name, data?)` | Sends an event of the host app's to the app (`host.on`), then waits until it is quiet. See [Playing the host app](#playing-the-host-app). |
| `app.host.calls()`, `app.host.posts()` | The app's calls and posts that `open`'s `host.handlers` got, in order: `name`, `data`. |
| `app.openedUrls()` | The URLs the app opened (`openUrl`), in order: recorded, never opened. |
| `await app.setViewport(width, height)` | Resizes the viewport, as rotating the device or resizing a window does (`windowSize()`). |
| `await app.setColorScheme(scheme)` | Switches the system's appearance to `"light"` or `"dark"`, as the user does. |
| `await app.setLifecycle(state)` | Moves the app to `"background"`, `"inactive"` or `"active"`, as the system does when the user leaves it, switches to another app or window and comes back (`lifecycle()`). Headless runs only. |
| `await app.screenshot(path?)` | A picture of the app as a `Uint8Array`: PNG of its window on graphical targets, UTF-8 Cell JSON on `tui`, also saved at `path` on this machine when given (relative to the current directory). Only a real platform draws the app: see [On a real platform](#on-a-real-platform). |

A step resolves once the app rendered nothing for 100 ms and no native animation runs that ends by itself (2 s at
most, for apps that render all the time; on a manual clock, also 2 s of the app's time), so what it changed is on
screen when the next line runs; use `waitFor` for what comes later (a response, a timer). On a manual clock a step
does not wait for those 100 ms: it resolves as soon as the app has run everything the step and the clock's time made
due (timers due now, promises, a stubbed response answered at once) and wants no frame, unless a request is still in
flight, so tests on a manual clock run without pauses between their steps. What another thread answers (an
`nsh/host` call, a file read, a Rust task's work on a thread) arrives after the step resolves: `waitFor` what it
shows. An animation that loops
forever, such as a loading spinner, keeps running in the background while steps and `waitFor` go on, as an infinite
CSS animation does in a browser's tests. A step rejects, failing the test, when nothing matches its selector (the error lists the texts on
screen), when the app threw an exception meanwhile, and when the app asked for what only a real platform answers.

The failures a test may expect carry a `code`, which stays as it is; their messages are for people and may change, so
a test matches the code:

| `code` | The step or query |
|---|---|
| `ERR_NSH_TEST_NOT_FOUND` | Nothing on screen matches the selector, or the open menu has no such item. |
| `ERR_NSH_TEST_DISABLED` | The view the selector names is disabled (a scroll view the user cannot scroll, a disabled menu item). |
| `ETIMEDOUT` | `waitFor` or `waitUntil` ran out of time, or the app rendered nothing after `open`. |
| `ERR_NSH_TEST_NO_BACK` | `back()` found nothing to go back from. |
| `ERR_NSH_TEST_UNSUPPORTED` | `open` with `--target` was given an option the target's platform cannot honor: `width` or `height` on iOS and Android, a phone's `platform` on a desktop or the web, a desktop's or the other phone's on iOS or Android, `host.handlers`. The message names it. |

```tsx
await expect(app.press("Pay")).rejects.toMatchObject({ code: "ERR_NSH_TEST_DISABLED" });
```

`app.spanStyle("id:guide")` reads a nested `<Text testID="guide">`; `text:word` reads the first character
of that match. Scope queries with `id:note >> text:word` and select repeated matches with `>> nth=0`.
The query reports an error for a missing, ambiguous or empty span. Updating a span’s `testID` reuses its text
layout and preserves the `onTextLayout` callback count.

### What headless runs play of the platform

A headless run has the real runtime and no platform. It plays the platform's part NSH's protocol defines, and nothing
that only a real platform can do:

- **Native animations run** frame by frame, to their end: `start(callback)` callbacks run, and so does what waits for
  them. Loops without an end run until the app stops them.
- **Going back** pops screens and closes modals as a platform does (`app.back()`).
- **Dialogs are answered**: by the test's `onDialog`, else by their cancel button, else they are closed when they can
  be; a dialog that only its other buttons answer fails the step that showed it until the test says which to press.
- **The clipboard holds text**: what the app copies, read back when it pastes (`clipboard` to start with some).
- **The page's host answers `host`** when the app's `nsh.json` names one in `web.host` ([The page's
  host](#the-pages-host)).
- **The app runs under its capabilities**: what its `nsh.json` declares in `capabilities` is enforced as on a device,
  so what it does not declare is refused.
- **URLs are recorded**: what the app opens is reported opened, and `app.openedUrls()` lists it.
- **Picks are answered**: with the test's files (`onPick`), else cancelled, so `Picker.pickImages` resolves `[]`.
- **Speech is the test's**: `Speech.available()` resolves `true`, a session starts at once and hears what `hear` says.
- **Modals show at once**: `onShow` comes when one is presented.
- **Images are not loaded**: no `onLoad` or `onError` comes, and `Image.getSize` and `Image.prefetch` reject.
- **What only a real platform answers fails the step**: an image or files on the clipboard.

### The page's host

An app published to the web gets its host from its page: `nsh.json` `web.host`, a module exporting
`createHost(player)` ([Web](https://nsh.dev/versions/main/docs/web.md#the-hosts-functions)). Headless runs load that module for each app a test opens,
before the app starts, in a JavaScript context of its own (timers and `console`, nothing of the browser's, no
imports): its `call` answers the app's [`host.call`](https://nsh.dev/versions/main/modules/nsh.md#host), its `player.hostEvent` reaches
`host.on`, and `host.available()` is `true`. A `call` that throws, rejects or returns what is not JSON rejects the
app's call with its message, as on the page, and events sent before the app starts reach its top-level listeners
once it does. `--web-host <module>` names another module. The app's `capabilities.host` must list what it calls, as on
the page. A call's timeout and the host's own timers run on the app's time, so a manual clock moves them
(`app.clock.runFor`). In a browser (`--target web`) the development page runs `nsh.json`'s `web.host` for each app as a
published page does; on the other platforms (`--target`) the apps have no host: `host.available()` is `false`.

```tsx
// nsh.json: { "capabilities": { "host": ["echo"] }, "web": { "host": "./host.js" } }
import { open, test } from "nsh/test";

test("calls reach the page's host", async () => {
  const app = await open("./App.tsx");
  await app.press("label:call");
  await app.waitFor('text:{"n":1}');
});
```

`examples/host-echo` has an app, its host and their tests.

### Expectations

`expect(value)` checks values as Jest does, as JS made them: `toBe` is `Object.is`, `toEqual` compares member by
member, and a `Date`, a `Map` or a `Uint8Array` is compared as what it is. Each check throws when it does not hold.
`.not` turns them around: `expect(app.texts()).not.toContain("Error")`. Given a function, `toThrow` checks what calling
it throws; given a promise, or a function that returns one, `rejects` and `resolves` check what it settles to, as in
Jest: `await expect(save()).rejects.toMatchObject({ code: "ERR_ACCESS_DENIED" })`.

| Check | Holds when |
|---|---|
| `toBe(expected)` | The value is `expected`, as `Object.is` says: the same primitive (`NaN` is `NaN`, `0` is not `-0`) or the same object. |
| `toEqual(expected)` | The value equals `expected` member by member, as Jest's `toEqual`: objects by their own enumerable properties (a property that is `undefined` counts as missing), arrays item by item, dates by their time, regular expressions by source and flags, maps and sets by their entries in any order, `ArrayBuffer`s and typed arrays by their bytes, errors by name and message; `NaN` equals `NaN`. An instance of a class equals a plain object with its properties. |
| `toMatchObject(subset)` | The value has every property of `subset`, each equal as `toEqual` says, and objects in it match in turn; other properties are not looked at, and arrays match item by item, all of them. |
| `toContain(item)` | An array, a `Set`, a typed array or another iterable holds `item` (`===`), or a string contains it. |
| `toContainEqual(item)` | An array, a `Set` or another iterable holds an item equal to `item`, as `toEqual` says. |
| `toBeTruthy()`, `toBeFalsy()` | The value is truthy / falsy, as JS sees it. |
| `toMatch(pattern)` | A string contains `pattern` (a string), or matches it (a `RegExp`, run by the JS engine: look-behind, backreferences and named groups work as in JavaScript). |
| `toHaveLength(n)` | The value's `length` is `n`: a string's UTF-16 units, an array's or a typed array's items. |
| `toBeNull()` | The value is `null`. |
| `toBeUndefined()`, `toBeDefined()` | The value is `undefined` / anything else. |
| `toBeNaN()` | The value is `NaN`. |
| `toBeGreaterThan(n)`, `toBeGreaterThanOrEqual(n)`, `toBeLessThan(n)`, `toBeLessThanOrEqual(n)` | A number compares so with `n`. |
| `toThrow(expected?)` | `expect(fn)`: calling `fn` throws. Given `expected`, the error matches it: its message contains a string or matches a `RegExp`; an error class (`TypeError`, a class of the app's) is the error's `name`, and `Error` matches every error; an error has the same message. |
| `rejects.toThrow(expected?)` | `expect(promise)`: the promise rejects, with an error matching `expected` as `toThrow` says. |
| `rejects.toMatchObject(subset)` | `expect(promise)`: the promise rejects with a value matching `subset` as `toMatchObject` says: an error's own properties (`code`, `permission`, ...) with its `name` and `message`. |
| `resolves.toBe(expected)`, `resolves.toEqual(expected)`, `resolves.toMatchObject(subset)` | `expect(promise)`: the promise resolves to a value that holds the check. |

A failing check says what it got and what it expected, written as JS would write them:
`expected Date(2024-01-02T00:00:00.000Z) to equal Date(2024-01-01T00:00:00.000Z)`.

`rejects` and `resolves` have a `.not` of their own too: `await expect(load()).resolves.not.toBe(null)`.

### On a real platform

`nsh test --target macos` (or `linux`, `windows`, `gpui`, `tui`, `web`, `ios`, `android`) runs the same tests on the platform's development host instead of headless:
each `open` starts the app in a window of its own, with a fresh data directory, and the steps act with the platform's
own input at the views their selectors name, as Playwright does in a browser:

- a press is a click at the view's middle, a long press a held click, `type` clicks the input and types its keys,
  `scroll` is a trackpad gesture over the scroll view, `back` is what a user does (Escape on macOS and Linux, the mouse's
  back button on Windows and in GPUI, the browser's back button on the web, a sheet swiped down, VoiceOver's escape
  gesture while a menu, popover or `Sheet` is open, else the header's back button on iOS, the back button on Android);
- a view off screen is scrolled into view first, a gesture at a time; on a touch screen the finger lands where the
  page itself takes it, beside the views that follow a drag (a slider, a drawing area), as a user scrolls;
- selectors, waits and queries see the same model of the app as headless runs, built from what the host draws, so
  they find the same views;
- dialogs are the platform's own: `app.dialogs()` reads them, and answering one (`onDialog`, or its cancel button
  when the test says nothing) presses its button;
- `app.screenshot(path)` takes a picture of the window.

```sh
nsh test --target macos                       # the app's tests in macOS windows
nsh test --target linux                       # in GTK windows (xvfb-run -a … on a machine without a display)
nsh test --target windows                     # in Win32 windows
nsh test --target ios                         # in an iOS simulator
nsh test --target android                     # on the Android device or emulator adb lists first
nsh test --target gpui                        # in GPUI windows (macOS, Windows, Linux)
nsh test --target web                         # in a headless Chrome, Edge or Chromium
nsh test --target tui                         # in an in-memory terminal
nsh test tests/form.test.tsx --target macos   # one file
```

The window opens at the viewport's size (390 × 844 unless `open` says), within the screen; on iOS and Android the app
fills the device's screen, at the device's size. The app runs as the target's platform (`platform.os`). A manual `clock` works as
it does headless: `app.clock.runFor`, `fastForward` and `setSystemTime` move the app's time at once (timers,
`requestAnimationFrame` a frame apart, `Date`), `app.wait(ms)`, `waitFor` and `waitUntil` move it too, and each frame
the platform shows moves it a frame (1/60 s), so the app's time passes while it animates. The platform's own animations, and a route's
`delay`, take real time. The app's requests come to the test as they do headless: `network` routes answer them,
a request no route matches fails, and `"live"` lets them through to the host's network; `app.requests()` lists them
all. Sockets and WebSockets connect on the host's network with `"live"`, and are refused as headless otherwise. `storage` is in the app's storage when it starts, and `app.storage()` reads it from the app. `locale`,
`reducedMotion` and `safeArea`, when `open` gives them (a default value included), hold whatever the platform reports,
and a `colorScheme` it gives switches the system's appearance (`"light"` too); what it leaves out is the platform's, and the app's clipboard calls are served from the
test's own clipboard (`clipboard` is its text at first, `app.clipboard()` reads it), so the machine's clipboard stays
as it was; a text input's own copy and paste use the system's. `host.params` reaches the app, `app.host.send` sends
events, and the URLs the app opens are recorded for `app.openedUrls()` instead of being opened. `host.handlers` runs
headless, where the test answers the app's calls. `open` checks its options against the target: `width` and
`height` on iOS and Android, a `platform` of another kind of device (a phone's on a desktop or the web, a desktop's or
the other phone's on iOS or Android) and `host.handlers` reject with `ERR_NSH_TEST_UNSUPPORTED`, so a test runs as it
is written or says what it needs. A desktop's `platform` (`"macos"` for a desktop's mouse and keys) runs on every
desktop target and the web, as that target's platform and always as a desktop: in the browser the page starts in the
desktop idiom whatever its width, where without a `platform` (or with `"web"`) it measures its idiom as a browser does
(a desktop from 600 points wide). An app with Rust crates of its own runs in a development host built with its crates, which NSH
builds for the platform; a Rust app's host runs its root, so `open(".")` starts it there as it does headless.

`nsh test --target tui` runs the tests against the terminal renderer in an in-memory terminal, suitable for CI.
Each `open` uses its own surface and data directory. Set its point dimensions with `open(entry, { width, height })`;
they round up to whole Cells at the app's `nsh.json` `tui.pointsPerCell` scale (8 × 16 points by default).
`app.screenshot("cells.json")` returns and saves UTF-8 JSON: `format: "nsh-tui-cells"`, `version: 1`, `width`,
`height`, and `rows[y][x]` containing each Cell's `symbol`, `fg`, `bg`, `underline` and `modifiers`. Colors use `reset`, lowercase
ratatui color names, `#rrggbb` or `indexed:N`; modifiers are arrays of active style names such as `bold`, `italic`
and `underlined`. Decode the returned bytes with `new TextDecoder().decode(bytes)` and parse the JSON for Cell
snapshot assertions.

On the web, the apps run in the development host's page in a headless Chrome, Edge or Chromium: the one installed
on this machine, or the executable `--browser <PATH>` names (a browser is needed: `nsh test` says where it looked
when it finds none). One browser serves the run, and each `open` gets a page with storage of its own. The input is
the browser's trusted input, as a user's: mouse clicks, wheel scrolling and keys.

On iOS, the apps run in the development host in an iOS simulator: the booted one, else the newest iPhone, which
`nsh test` boots. The steps are a finger's touches and the software keyboard's typing, as UIKit gets them from the
device. `setColorScheme` switches the simulator's appearance, which `nsh test` sets back after the app, and the screen
has the simulated device's size.

On Android, the apps run in the development host on the first device or emulator `adb devices` lists, with storage
of their own. The steps are a finger's touches and a keyboard's keys, as the app's views get them from the device;
`back` is the system's back. `setColorScheme` switches the device's dark theme, which `nsh test` sets back after the
app.

### Steps from standard input

Given the app's entry instead of tests, `nsh test` opens the app on the real network, lets it run for 1.2 s, then takes
the steps standard input gives, with `app` the app:

```sh
echo 'await app.press("text:+1"); expect(app.texts()).toContain("1");' | nsh test App.tsx
```

The 1.2 s let the engine's idle garbage collection run before the first step, so an app that lets go of what it still
uses shows it: its handlers stop working.

The examples have tests to start from: `examples/gallery-rs` for a Rust app (`cargo test`, one module per demo, and
`App.test.tsx`), `examples/rust-exports` for an app with a Rust crate, `examples/counter` and `examples/gallery/tests`
(storage, inputs, a long list, stubbed requests, dark mode, a manual clock) for TSX apps.

## Tracing with --trace

`--trace` prints every mount batch of the apps the tests open, under the step it came in, and the time of every
commit. In Rust, a test prints the same: `observe` hands it each batch with its step, and `EngineConfig::trace` logs
the `perf` lines through the `log` crate (target `nsh::perf`; install a logger such as `env_logger` in the test):

```rust
let mut config = EngineConfig::new(Root::of::<my_app::App>());
config.trace = true;
let mut app = Headless::start(config).unwrap();
app.observe(|step, batch| nsh_testing::print_batch(&mut std::io::stdout(), step, batch));
app.press("Add").unwrap();
```

`nsh test` takes `--trace` on a test file, or on the app's entry with the steps on standard input:

```sh
nsh test App.test.tsx --trace
nsh test App.tsx --trace                                   # the first frame, then 1.2 s idle
echo 'await app.press("Add")' | nsh test App.tsx --trace    # and a press
echo 'await app.press("Add")' | nsh test App.tsx --trace --target ios   # the same in an iOS simulator
```

With `--target`, the trace is the platform's: the batches the host applied, under the steps that brought them, and
the host's own timings of each commit and event, on the device's hardware.

Use it to:

- check that an app (or a demo) builds, evaluates and renders without errors;
- see exactly which native views a change creates, moves or updates, and how many;
- measure the cost of the first frame, of a tap and of each scrolling frame;
- catch regressions in CI.

### Reading the output

Here is the counter example with one press (`echo 'await app.press("+1")' | nsh test examples/counter/App.tsx
--trace`), shortened:

```text
✓ bundled App.tsx (3255 B in 6.2 ms)
perf commit: 56 ops, 271µs (list js 5µs), 49 mount items, 21 nodes
perf first frame: eval 187µs, total 820µs
── open(App.tsx): 49 items
   LayoutDirection { rtl: false }
   Create { id: 2, kind: View }
   Create { id: 4, kind: Text }
   Insert { parent: 2, child: 4, before: None }
   ...
   Frame { id: 2, x: 0, y: 0, w: 390, h: 844 }
   Frame { id: 4, x: 24, y: 64, w: 342, h: 34 }
   ...
   Text { id: 4, text: "nsh counter", content: 342x34 @ 0,0 }
   Text { id: 14, text: "0", content: 36x77 @ 0,0 }
perf event Press on view 26
perf event js: 413µs
perf commit: 10 ops, 672µs (list js 7µs), 7 mount items, 24 nodes
── press(+1): 7 items
   Create { id: 42, kind: Text }
   Insert { parent: 32, child: 42, before: None }
   Frame { id: 32, x: 24, y: 366, w: 342, h: 43 }
   Frame { id: 42, x: 0, y: 23, w: 342, h: 20 }
   Text { id: 14, text: "1", content: 36x77 @ 0,0 }
   Text { id: 42, text: "• 1", content: 342x20 @ 0,0 }
   Text { id: 34, text: "Recent values: 1", content: 342x17 @ 0,0 }
✓ App.tsx › steps (1.4s)
```

#### Batches and mount items

Each `── step: N items` block is one **mount batch**, under the step it came in: everything the platform applies to native views for one frame,
in one hop to the main thread. The lines in it are **mount items**:

| Item | Meaning |
|---|---|
| `Create { id, kind }` | Create a native view (`View`, `Text`, `Image`, `Scroll`, ...). |
| `Insert { parent, child, before }` | Put a view into its parent, before a sibling (`None`: at the end). |
| `Remove` / `Delete` | Detach a view from its parent / free it. |
| `ViewStyle { id, style }` | The view's decoration: background, borders, radius, shadow, opacity, transform, ... |
| `ViewProps { id, props }` | Touch and accessibility settings, `testID`. |
| `Events { id, events }` | Which events the view reports (`EventMask(1)` is press). |
| `Frame { id, x, y, w, h }` | Its position and size in its parent, in points. |
| `Text { id, text, content }` | Laid-out text for a text view. |
| `Image { id, source, ... }` | An image to load. |

Only what changed is sent: a tap that changes one number sends one `Text` item; views get no default style and no empty
event mask; unchanged frames are not sent. A frame of scrolling that reveals no new row produces **no batch at all**.

#### The `perf` lines

| Line | Meaning |
|---|---|
| `✓ bundled App.tsx (3255 B in 14.3 ms)` | Bundling time and bundle size (development settings). |
| `commit: 56 ops, 395µs (list js 6µs), 49 mount items, 21 nodes` | One commit: the operations JS queued, the time the core spent (rendering components, laying out, diffing), JS time spent binding list rows, the mount items produced, and the nodes alive. |
| `turn: 2640µs (timers and tasks 1964µs)` | A turn that committed: its whole time, and what its JS timers and Rust component tasks took before the commit (a Rust component renders in the commit). |
| `first frame: eval 271µs, total 1235µs` | Time to evaluate the bundle, and from start to the first batch. |
| `event Press on view 20` / `event js: 196µs` | An event dispatched, and the time its handler (and what it caused) took in JS. |

> [!NOTE]
> Text is measured with an approximate text engine headless, so text sizes differ a little from a device, which uses
> CoreText or Android's text layout. Layout logic, view counts and operation counts are the same.

Single-run timings depend a lot on the CPU's clock state (a machine that just woke from idle is slow). Compare runs on
the same machine, look at the minimum of several runs, and trust the op and item counts more than the microseconds.

### Scrolling

```rust
app.scroll("id:photos", px(3000.0)).unwrap();
```

```sh
echo 'await app.scroll("id:photos", 3000)' | nsh test examples/gallery/Bench.tsx --trace
```

`scroll` moves the list 10 points per frame, at 60 frames a second, and each frame's batch is printed:

```text
perf commit: 55 ops, 1667µs (list js 771µs), 46 mount items, 414 nodes
── scroll(id:photos, 3000): 46 items
   Create { id: 792, kind: View }
   Insert { parent: 94, child: 792, before: None }
   ...
```

For a [list](https://nsh.dev/versions/main/docs/lists.md), this shows the virtualization at work: which frames bind new rows, how many operations a row
costs, and that frames revealing no new row produce nothing. Use it with a release build (`cargo test --release`, or `./target/release/nsh` in a checkout) for meaningful
timings.

### In CI

Headless tests need no device or display, so they run on Linux runners: `cargo test` for a Rust app's tests, and
`nsh test`, which needs nothing but the CLI. Any failing test makes either exit with a non-zero code: a test that
fails, an app that does not build or renders nothing, an exception the app throws during a step.

```yaml
# .github/workflows/test.yml
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: cargo test                            # a Rust app's tests
      - run: nsh test --junit test-results.xml     # its TypeScript tests, or a TSX app's
```

(Install the `nsh` CLI on the runner the way you install it locally; see [Installation](https://nsh.dev/versions/main/docs/installation.md).)

`--junit <FILE>` also writes the results as a JUnit XML report, which CI services (GitHub Actions test reporters,
GitLab, Jenkins, Azure Pipelines) show per test: a `testsuite` per test file, a `testcase` per test, with what failed,
where, and the texts on screen.

To guard performance, record the item counts of a few interactions (the `── … : N items` lines and the `ops` /
`mount items` numbers of `--trace`) and fail when they grow. Counts are deterministic; timings on shared CI machines
are not.

> [!NOTE]
> Tests run under the `capabilities` the app's `nsh.json` declares, as on a device: what the app does not declare is
> refused in the test too.

## `testID` for UI tests

Headless tests check what the runtime renders, and their `id:` selectors find views by test id. To drive the real
native UI with the platform's test tools (XCUITest, Espresso / UI Automator, Appium, Maestro), give views a test id:
`.test_id(…)` in Rust, `testID` in TSX:

```rust
view()
    .test_id("add-to-cart")
    .p_3()
    .on_press(add)
    .child(text(move || format!("{} items", count.get())).test_id("cart-count"))
```

```tsx
<View testID="add-to-cart" onPress={add} style={{ padding: 12 }}>
  <Text testID="cart-count">{`${count()} items`}</Text>
</View>
```

| Platform | Where `testID` goes |
|---|---|
| iOS | The view's `accessibilityIdentifier` (`app.otherElements["add-to-cart"]` in XCUITest). |
| Android | The accessibility node's view id resource name (`By.res("add-to-cart")` in UI Automator). |

The test id is a method of every element in Rust, components' elements included (`button().test_id("save")`, which
names the component's root), and `testID` a prop of every element and of every Rust component (`Button`, `Dialog`, ...). It does not change what screen readers
say; use `accessibilityLabel` for that (see [Accessibility](https://nsh.dev/versions/main/docs/accessibility.md)). In `--trace` output it appears in
the view's `ViewProps` item as `test_id: Some("add-to-cart")`.

## See also

- [Performance](https://nsh.dev/versions/main/docs/performance.md): what to look for in these numbers
- [Dev server and debugging](https://nsh.dev/versions/main/docs/dev-server-and-debugging.md)
- [Architecture](https://nsh.dev/versions/main/docs/architecture.md): ops, commits and mount batches

Source: https://nsh.dev/versions/main/docs/testing-and-trace

---

# Performance

Performance is NSH's first priority, and most of it is decided by the framework rather than by your app: the runtime
is native, each update crosses threads once, animations and list virtualization run without JS, and an app written in
Rust runs no JS at all. This page explains the rules NSH follows, what they mean for the code you write, in Rust and in
TSX, and how to measure.

## The rules

### 1. JS does as little as possible

**An app written in Rust is native code from start to end**: its components, state and handlers are compiled with
NSH's engine, and no interpreter runs ([Building with Rust](https://nsh.dev/versions/main/docs/rust.md)). That is the fastest way to write an app, and
the one to choose for demanding business logic.

In a TSX app, QuickJS is an interpreter: small, quick to start, and much slower than native code for heavy work. So in
NSH, **only your app's code is JS**. The reactive graph (signals, computed values, effects), the renderer your compiled JSX calls,
the layout engine, list virtualization, animation and every module you import are
Rust. Parsing, diffing, layout and string processing happen natively.

The effect is measurable. The same counter app on NSH's earlier JS runtime and on the native runtime (release builds):

| | Former JS runtime | Native runtime |
|---|---|---|
| Bundle size | 14 KB JS / 19.6 KB bytecode | 886 B JS / 1.7 KB bytecode |
| Evaluating the bundle | ~390 µs | ~95 µs |
| JS time of one tap (median) | ~14 µs | ~5 µs |
| Commit of one tap | ~22 µs | ~15 µs |
| Scrolling a 1000-row list, JS per rebinding frame | ~150 µs | ~77 µs |

The same holds for components: a button written as a Rust component against an equivalent TSX button, 200 of them:

| | Rust button: JS / core | TSX button: JS / core |
|---|---|---|
| First frame (ops) | 1.32 ms / 0.77 ms (1015) | 2.32 ms / 0.70 ms (2415) |
| Updating all 200 titles (ops) | 0.42 ms / 0.42 ms (200) | 0.77 ms / 0.36 ms (600) |

(Measured on Apple silicon; the second table on the former runtime. Both from NSH's performance baselines.)

**For your code:** keep event handlers and computed values light. Heavy computation (parsing large payloads, sorting
thousands of items on every keystroke) costs more in QuickJS than you may be used to in V8 or JavaScriptCore with a JIT.
Do it once, cache it in a `computed`, or move it off the interaction path.

### 2. Cross threads in batches

Your app's code, Rust or JS, runs on an engine thread, never on the main thread. One turn, for example one event
handler with everything it changes, becomes **one commit**: the runtime renders components, lays out, diffs and produces one batch
of native view operations, which reaches the main thread in **one hop**. There is no bridge message per view and no
serialization per prop.

**For your code:** you do not need to coalesce writes for performance; ten `set` calls in one handler still produce one
commit, in Rust and in TSX. Use `batch` when you want effects and computed values to see all the writes at once instead of running after
each one.

### 3. Fine-grained updates

Components run **once**, in Rust and in TSX alike. Afterwards, only the bindings that read a signal run again when it
changes: a text, a style property, a branch of `when` (`<If>`), the rows of `each` (`<Each>`). Nothing re-renders a whole
subtree to find out what changed.

```rust
use nsh_core::prelude::*;

#[derive(Clone, PartialEq)]
struct Quote {
    price: f64,
    change: f64,
}

fn price(quote: Signal<Quote>) -> impl IntoElement {
    // Runs once. When the quote changes, only the text and the color update.
    text(move || format!("{:.2}", quote.with(|q| q.price))).text_color(move || {
        if quote.with(|q| q.change < 0.0) { rgb(0xcf222e) } else { rgb(0x1a7f37) }
    })
}
```

```tsx
import type { Accessor } from "nsh";
import { Text } from "nsh";

type Quote = { price: number; change: number };

function Price(props: { quote: Accessor<Quote> }) {
  // Runs once. When quote() changes, only the text and the color update.
  return (
    <Text style={{ color: props.quote().change < 0 ? "#cf222e" : "#1a7f37" }}>
      {props.quote().price.toFixed(2)}
    </Text>
  );
}
```

**For your code:**

- Read signals where they are used (inside bindings, `move ||` closures in Rust and JSX expressions in TSX, and in
  `computed` and `effect`), not at the top of a component, so the narrowest binding updates.
- Use `each` / `<Each>` (rows kept by key) or a [virtual list](https://nsh.dev/versions/main/docs/lists.md) for collections; rows made again from the whole
  collection (`dynamic` in Rust, a plain `.map()` in JSX) are all created again on each change.
- Derive values with `computed` when several bindings use them, so they are computed once per change.

Appending a fourth item to a three-item list, as `nsh test --trace` shows it:

```rust
// 22 mount items: 3 views removed, 4 created
dynamic(move || items.get().into_iter().map(|n| text(format!("row {n}"))).collect::<Vec<_>>())
// 4 mount items: 1 view created
each(move || items.get(), |n: &u32| *n, |n, _| text(move || format!("row {}", n.get())))
```

```tsx
{items().map((n) => <Text>{`row ${n}`}</Text>)}                   // 22 mount items: 3 views removed, 4 created
<Each of={items()}>{(n) => <Text>{`row ${n()}`}</Text>}</Each>      // 4 mount items: 1 view created
```

See [Reactivity](https://nsh.dev/versions/main/docs/reactivity.md).

### 4. Do not send what is not needed

The core sends only what changed: new views get no default style and no empty event mask, unchanged styles and frames
are not sent, a change of text color does not lay the text out again. A tap that changes one number sends one text
item. You can see this in `nsh test --trace` output (below).

### 5. Animate natively

An animation driven from the engine thread (a signal written on every frame) costs a commit per frame, and a JS call
in TSX, and stutters when the engine thread is busy. Animated values ([Animation](https://nsh.dev/versions/main/docs/animation.md): `animated_value` in
Rust, [`nsh`'s animation API](https://nsh.dev/versions/main/modules/nsh.md#animation) in TSX) run animations natively instead:

```rust
use nsh_core::prelude::*;

let scroll_y = animated_value(0.0);

view()
    .bind_opacity(&scroll_y.interpolate(&[0.0, 120.0], &[1.0, 0.35]))
    .bind_translate_y(&scroll_y.interpolate(&[0.0, 120.0], &[0.0, -6.0]));
virtual_list(move || photos.with(Vec::len), move |at| photo_row(photos, at))
    .scroll_value(&scroll_y)
    .estimated_item_size(px(64.0))
    .flex_1();
```

```tsx
import { List, View } from "nsh";
import { createAnimatedValue } from "nsh";

const scrollY = createAnimatedValue(0);

<View
  style={{
    opacity: scrollY.interpolate({ inputRange: [0, 120], outputRange: [1, 0.35] }),
    translate: [0, scrollY.interpolate({ inputRange: [0, 120], outputRange: [0, -6] })],
  }}
/>;
<List each={photos()} scrollValue={scrollY} estimatedItemSize={64} style={{ flex: 1 }}>
  {(photo) => <Row photo={photo()} />}
</List>;
```

- `timing`, `spring` and `decay` run on the platform's UI thread, frame by frame, with no work on the engine thread
  per frame.
- `scroll_value` (`scrollValue`) writes a scroll offset into an animated value in the same frame; a pan
  (`pan={{ x, y }}`) lets drags move a view directly. Your code hears about the end (the animation completes, the pan's
  end gets the velocity).
- `Animated.sequence` / `parallel` / `stagger` / `loop` run as one native tree: each step starts the moment the
  previous one ends, with no gap waiting for JS.
- `LayoutAnimation.configureNext` animates the next commit's frames, insertions and removals natively.

### 6. Virtualize long lists

[`List`](https://nsh.dev/versions/main/docs/lists.md) keeps only the rows near the viewport, recycles their cells, and computes positions, columns,
sticky headers and viewability natively. Scrolling frames that reveal no new row run none of your code and produce no batch; a
frame that binds one new row of the gallery's photo list is 4 operations and 4 mount items.

**For your code:**

- Give `estimated_item_size` (`estimatedItemSize`) close to the real row height.
- Keep per-item state in your data (keyed by id), not in signals created inside the row: cells are reused for other
  items, and the row's position (`at.index()`; `item()` / `index()` in TSX) changes when they are.
- Keep rows cheap: a row binds once per recycle, so its code runs while the user scrolls.
- Use `scroll_value` (`scrollValue`) instead of `on_scroll` (`onScroll`) for effects that follow the scroll position.
  A scroll listener gets at most one event per engine turn, but each is still a call into your code (into JS, in TSX).

## Measuring

### Headless: `--trace`

In a Rust test, `EngineConfig::trace` logs the same `perf` lines and `Headless::observe` sees every batch
([Testing](https://nsh.dev/versions/main/docs/testing-and-trace.md#tracing-with-trace)). `nsh test --trace` prints them for TSX:

```sh
echo 'await app.press("Add")' | nsh test App.tsx --trace                 # first frame + a press
echo 'await app.scroll("id:feed", 3000)' | nsh test App.tsx --trace       # scrolling, 10 pt per frame
```

```text
perf commit: 56 ops, 395µs (list js 6µs), 49 mount items, 21 nodes
perf first frame: eval 271µs, total 1235µs
perf event js: 88µs
perf commit: 10 ops, 151µs (list js 2µs), 8 mount items, 27 nodes
```

What to look at:

- **ops** (operations your JS queued) and **mount items** (native view operations): these are deterministic. If a tap
  that should change one label produces 40 items, something re-creates views it should update.
- **event js**: the JS cost of a handler and what it triggered.
- **commit**: the core's cost of rendering components, layout and diffing.
- **list js**: JS spent binding list rows during that commit.

Full guide: [Testing](https://nsh.dev/versions/main/docs/testing-and-trace.md).

### On a device: `--trace`

```sh
nsh run App.tsx --trace
nsh run App.tsx --target android --trace --release
```

logs the same commit lines from a TSX app's real host, with the platform's own text engine. `NshAppView(trace: true)` and
`new NshView(context, true)` do the same in an embedding app.

### On screen: `--fps`

```sh
nsh run App.tsx --target macos --fps --release
```

(`AppOptions { fps: true, .. }` in a Rust app's `run_app`) shows the frame rate and what frames and commits cost over the running app, with CPU, GPU and memory
([macOS: performance monitor](https://nsh.dev/versions/main/docs/macos.md#performance-monitor)). On Linux and Windows, `--target linux --fps` and
`--target windows --fps` log the same readings once a second, with the time of each phase of a frame;
`nsh test --target linux --fps -v` (or `windows`) takes them while a test drives the app.

On the terminal target, `nsh run examples/gallery --target tui --fps` shows one line in a corner.
`C-h p` toggles it outside text fields. It shows active FPS, `idle` when the app rests, frame time and p95,
apply / draw / flush times, bytes written and changed Cells per frame. The same readings appear in the
`C-h e` log panel. Measuring is enabled only while the line is shown.

> [!TIP]
> Single measurements are dominated by the CPU's clock state: a thread that just slept runs slower for a while.
> Compare the minimum of several runs, on the same machine, and prefer release builds for timing.

## Reference numbers

Measured numbers, NSH's baselines and the gallery page by page on Linux, are in the [performance report](https://nsh.dev/versions/main/docs/performance-report.md).

## Checklist

- Language: write the app, or the parts it uses most, in Rust ([Building with Rust](https://nsh.dev/versions/main/docs/rust.md)); keep TSX for what
  changes often or is delivered at run time.
- Interactions: a tap changes a handful of mount items, not dozens.
- Lists: a virtual list (`virtual_list`, `List`) for anything long, with an estimated item size; per-item state in data.
- Animations: animated values, not signals written every frame.
- Scroll effects: `scroll_value` (`scrollValue`), not a scroll listener.
- Handlers: no heavy work per keystroke or per scroll event; cache in `computed`.

## See also

- [Performance report](https://nsh.dev/versions/main/docs/performance-report.md)
- [Architecture](https://nsh.dev/versions/main/docs/architecture.md)
- [Testing](https://nsh.dev/versions/main/docs/testing-and-trace.md)
- [Lists](https://nsh.dev/versions/main/docs/lists.md), [Animation](https://nsh.dev/versions/main/docs/animation.md), [Reactivity](https://nsh.dev/versions/main/docs/reactivity.md)

Source: https://nsh.dev/versions/main/docs/performance

---

# Performance report

What NSH apps cost, measured. How NSH keeps them fast and how to measure your own app is in [Performance](https://nsh.dev/versions/main/docs/performance.md).

## Baselines

From NSH's own baselines (Apple silicon unless noted):

| Scenario | Numbers |
|---|---|
| Counter app, headless (debug) | First frame ~0.5–0.65 ms (58 ops / 49 mount items); one tap ~0.15 ms |
| Counter app, Mac Catalyst (release) | First frame ~1.05–1.15 ms (about 0.7 ms of it lays out 10 texts with CoreText for the first time); one tap ~0.12 ms |
| Gallery photo list, headless (debug) | First frame 653 ops / 224 nodes, ~2.7 ms |
| Scrolling the photo list, Catalyst (release) | Rebinding one row while scrolling slowly ~0.4 ms; a whole screen of ~32 rows on a fast fling 0.9–1.6 ms |
| Scrolling the photo list, Android emulator (arm64, release) | Rebinding one row ~0.3–0.4 ms (JS ~60 µs) |
| Engine startup (release) | ~75–155 µs; the global APIs (`fetch`, `URL`, ...) cost nothing until first used, then ~90 µs |
| Hot reload | ~120 ms from saving a file to the new version running; applying the update 0.2–0.5 ms |

## Linux (GTK 4)

Measured on a Linux desktop (x86_64, 24 threads, NVIDIA GPU), release builds, the gallery in a 1896 × 1030 window on a
120 Hz display, every reading taken automatically by `examples/gallery/tools/perf.py` (`nsh test --target linux --fps`,
one line a second; CPU is the whole process, in percent of one core). *Frame p95* is the main thread's time per drawn
frame at the 95th percentile: under 8.3 ms, a frame fits a 120 Hz refresh.

### Animated demos

<div class="data-table">

| Demo | FPS | Frame p95 | CPU |
|---|---|---|---|
| Stocks: 22 live sparklines, an intraday chart, order book, tape | 117–120 | 5–6 ms | 25–29% (1200 × 800), 28–32% (1896 × 1030) |
| Stocks, the window filling a 4K 144 Hz display at 1.6× | 143–145 | 4.1–4.4 ms | 26–29% |
| Canvas: a gauge, a clock, a dot matrix | 120 | 2.6–4.4 ms | 5–10% |
| Animations: three native loops, springs, sequences | 120 | 2.0 ms | 12–13% |

</div>

### Every page

Every page of the gallery, as it opens and while the test scrolls it, in a 1200 × 800 window on a 144 Hz display (the
same machine). NSH draws a frame only when something on screen changes, so *FPS* here is the rate while something
moves: one frame per median gap between drawn frames (`perf.py`'s `moving`); at the display's 144, every frame of an
animation or a scroll comes one refresh after the last. *Over one refresh* is the share of frames that took longer
than a refresh (6.9 ms). Images' GIF and WebP play at their own frame rates (about 50 FPS here), as does video. Physics, Overlays and Menus are short: in 1200 × 800 a scroll reaches their end within a few frames, so they are measured in a 900 × 500 window, where they have room to scroll.

<div class="data-table">

| Page | Frames come from | FPS | Frame p95 | Over one refresh | CPU |
|---|---|---|---|---|---|
| Stocks | Live data, native loops | 144 | 4.1 ms | 0% | 26% |
| Stocks, scrolling | Live data, scroll | 144 | 4.1 ms | 0% | 25% |
| Photos, scrolling | Scroll | 144 | 2.8 ms | 2% | 9% |
| Lists, scrolling | Scroll | 143 | 1.7 ms | 0% | 7% |
| Scrolling, scrolling | Scroll | 144 | 1.6 ms | 1% | 4% |
| Navigation, scrolling | Scroll | 143 | 1.7 ms | 0% | 2% |
| Form, scrolling | Scroll | 144 | 1.3 ms | 0% | 4% |
| Resizable, scrolling | Scroll | 143 | 0.6 ms | 0% | 1% |
| Dock, scrolling | Scroll | 142 | 0.5 ms | 1% | 1% |
| Gestures | Springs, a pulsing ring | 144 | 1.6 ms | 0% | 1–5% |
| Physics, scrolling | Scroll (a 900 × 500 window) | 144 | 1.6 ms | 1% | 1% |
| Animations | Native loops | 144 | 2.6 ms | 0–1% | 5% |
| Canvas, scrolling | Scroll, native loops | 144 | 4.2 ms | 0% | 1–4% |
| Styles, scrolling | Scroll | 144 | 2.3 ms | 2% | 3% |
| Tailwind | `animate-*` utilities | 144 | 1.7 ms | 0% | 3–8% |
| Text, scrolling | Scroll | 144 | 1.9 ms | 0% | 4% |
| Text View, scrolling | Scroll | 141 | 1.8 ms | 2% | 7% |
| Images, scrolling | Scroll, GIF and WebP frames | 143 | 2.9 ms | 2% | 8% |
| Components, scrolling | Scroll | 144 | 1.4 ms | 0% | 3% |
| Overlays, scrolling | Scroll (a 900 × 500 window) | 144 | 1.7 ms | 0% | 2% |
| Menus, scrolling | Scroll (a 900 × 500 window) | 144 | 1.9 ms | 0% | 2% |
| Controls | Transitions | 144 | 0.9 ms | 0% | 1–4% |
| Web and video | Video frames, the page | 135–142 | 1.0 ms | 0% | 7–8% |

</div>

### Memory

At rest, 3 s after start (release runners, a 480 × 640 window). *Private* is the memory the process alone owns (USS);
*resident* adds the shared libraries' pages (GTK, the GPU driver), which every GTK app on the machine shares:

<div class="data-table">

| App | Renderer | Private (USS) | Resident (RSS) |
|---|---|---|---|
| Rust app (`nsh init --template rust`) | GL (`ngl`) | ~49 MB | ~142 MB |
| Rust app | Cairo (`GSK_RENDERER=cairo`) | ~28 MB | ~95 MB |
| TSX counter (`examples/counter`) | GL | ~79 MB | ~166 MB |
| GTK 4 window with one label, for reference | Vulkan / Cairo | ~62 / ~40 MB | ~132 / ~109 MB |

</div>

Revisiting a page adds no memory; the first visit to a page grows the process by what it caches on purpose (decoded
images, bounded at 128 MB) and the libraries it loads on first use (WebKitGTK for web views).

### App size

A hello world app made by `nsh init` with each template, and two apps people use, as `nsh package --target linux`
builds them for x86_64. The runner is the app's one executable; the archive is the `.tar.gz` it ships as. The hello
worlds are built with link-time optimization and stripped (`CARGO_PROFILE_RELEASE_LTO=fat`,
`CARGO_PROFILE_RELEASE_CODEGEN_UNITS=1`, `CARGO_PROFILE_RELEASE_STRIP=true`):

<div class="data-table">

| App | Written in | Runner | Archive |
|---|---|---|---|
| Hello world (`--template rust`) | Rust | 16.5 MB | 7.5 MB |
| Hello world (`--template ts`) | TSX, on QuickJS | 25.7 MB | 11.6 MB |
| Hello world (`--template mixed`) | TSX and a Rust crate | 25.8 MB | 11.7 MB |
| [sysmon](https://github.com/huacnlee/sysmon) 0.1.3 | Rust | 20.9 MB stripped | 9.7 MB |
| [Omasend](https://github.com/huacnlee/omasend) 0.2.0 | Rust | 22.3 MB | 9.8 MB |

</div>

The TSX runners hold the QuickJS runtime, the native modules and the renderer; an app's own code is its bundle beside
the runner, under 1 KB for a hello world.

What makes these numbers:

- **The renderer**: under NVIDIA's driver NSH draws with GSK's GL renderer, whose frames cost a fraction of the Vulkan
  renderer's there (the Animations demo: ~1 ms of drawing per frame instead of ~9.5 ms). `GSK_RENDERER` still chooses.
- **Canvas rasters**: each canvas is rasterized once into 256 px tiles kept on the GPU. An animated value redraws only
  the area the operations reading it cover, over the kept pixels of the drawing's static part; a canvas out of sight
  waits until it scrolls into view.
- **Paths set aside once**: `fillRect` and `fillText` after a long path leave it in place until it is used again (a
  400-point line then 240 bars: 0.63 ms).

## macOS (AppKit)

Measured on a MacBook Pro (Apple M3, 24 GB) on its built-in 120 Hz ProMotion display, release builds, the gallery in
a 1200 × 800 window, every reading taken automatically by `examples/gallery/tools/perf.py` (`nsh test --target macos
--fps`, one line a second; CPU is the whole process, in percent of one core, GPU its share of the GPU). The phases are
the main thread's per frame: *tick* (the display link's native animations) and *canvas* (replaying drawings).

### Animated demos

<div class="data-table">

| Demo | FPS | Frame p95 | CPU | GPU |
|---|---|---|---|---|
| Stocks: 22 live sparklines, an intraday chart, order book, tape | 120 | 2.7–3.7 ms | 33–36% | 18–22% |
| Canvas: a gauge, a clock, a dot matrix | 119–120 | 0.6–0.7 ms | 4–7% | 0% |
| Animations: three native loops, springs, sequences | 119–120 | 0.3–1.6 ms | 5–8% | 0% |

</div>

On Stocks a frame's main-thread time is ~1.6 ms of ticks, of which ~0.45 ms replays the canvases' animated parts;
Core Animation draws the rest of each canvas on its own threads.

### Every page

Every page of the gallery, as it opens and while the test scrolls it, in the same 1200 × 800 window. As on Linux, *FPS*
is the rate while something moves (one frame per median gap between drawn frames); at the display's 120, every frame
of an animation or a scroll comes one refresh after the last. *Over one refresh* is the share of frames that took
longer than a refresh (8.3 ms). A page at rest draws no frame and uses 2–5% CPU. Images' GIF and WebP play in Core
Animation and video in AVFoundation, at their own frame rates.

<div class="data-table">

| Page | Frames come from | FPS | Frame p95 | Over one refresh | CPU |
|---|---|---|---|---|---|
| Stocks | Live data, native loops | 120 | 3.2 ms | 0% | 35% |
| Stocks, scrolling | Live data, scroll | 120 | 3.5 ms | 0% | 36% |
| AI Chat, scrolling | Scroll | 120 | 2.4 ms | 1% | 5% |
| Photos, scrolling | Scroll | 120 | 1.4 ms | 0% | 10% |
| Lists, scrolling | Scroll | 120 | 1.6 ms | 0% | 8% |
| Scrolling, scrolling | Scroll | 120 | 2.7 ms | 0% | 6% |
| Navigation, scrolling | Scroll | 120 | 0.2 ms | 0% | 4% |
| Form, scrolling | Scroll | 120 | 0.6 ms | 0% | 5% |
| Resizable, scrolling | Scroll | 120 | 0.3 ms | 0% | 4% |
| Dock, scrolling | Scroll | 120 | 0.3 ms | 1% | 5% |
| Gestures | Springs, a pulsing ring | 120 | 0.4 ms | 0% | 4% |
| Physics, scrolling | Scroll | 120 | 0.3 ms | 0% | 4% |
| Animations | Native loops | 120 | 0.3 ms | 0% | 5% |
| Canvas, scrolling | Scroll, native loops | 120 | 1.2 ms | 0% | 7% |
| Styles, scrolling | Scroll, a swaying transform | 120 | 1.0 ms | 0% | 6% |
| Tailwind | `animate-*` utilities | 120 | 0.5 ms | 0% | 4% |
| Text, scrolling | Scroll | 120 | 0.3 ms | 0% | 5% |
| Text View, scrolling | Scroll | 120 | 0.7 ms | 0% | 5% |
| Images, scrolling | Scroll | 120 | 0.4 ms | 0% | 5% |
| Components, scrolling | Scroll | 120 | 0.3 ms | 0% | 5% |
| Overlays, scrolling | Scroll | 120 | 0.3 ms | 0% | 4% |
| Menus, scrolling | Scroll | 120 | 0.3 ms | 0% | 5% |
| Controls | Transitions | 120 | 0.3 ms | 0% | 4% |
| Web and video, scrolling | Scroll | 120 | 0.2 ms | 0% | 6% |
| System | `requestAnimationFrame`, timers | 120 | 0.2 ms | 0% | 3% |
| Standard APIs, scrolling | Scroll | 120 | 0.3 ms | 0% | 5% |
| Storage, scrolling | Scroll | 120 | 0.3 ms | 0% | 5% |

</div>

### Memory

At rest, 3 s after start (release runners). *Footprint* is the memory macOS charges the process (what Activity
Monitor shows); *resident* adds the pages of the system's shared libraries:

<div class="data-table">

| App | Window | Footprint | Resident (RSS) |
|---|---|---|---|
| Rust app (`nsh init --template rust`) | 1200 × 800 | ~19 MB | ~86 MB |
| TSX counter (`examples/counter`) | 1200 × 800 | ~20 MB | ~89 MB |
| AppKit window with one label, for reference | 480 × 640 | ~17 MB | ~80 MB |

</div>

Through the gallery's tour the process holds 84–230 MB up to the Canvas page and ~350–360 MB from the Text View page
on, with what it caches on purpose (decoded images, bounded at 128 MB; the Text View page's documents) and the
frameworks it loads on first use (WebKit for web views); the Canvas page's rasters, up to ~310 MB with all three
canvases on screen, go when the page closes.

### App size

The hello world apps made by `nsh init` with each template, as `nsh package --target macos` builds them for Apple
silicon (arm64), with link-time optimization and stripped as on Linux, and the two apps above as they ship for Apple
silicon. The executable is the runner inside the `.app`; the zip is the `.app` compressed (`ditto -c -k`):

<div class="data-table">

| App | Written in | Executable | Zipped `.app` |
|---|---|---|---|
| Hello world (`--template rust`) | Rust | 12.4 MB | 6.0 MB |
| Hello world (`--template ts`) | TSX, on QuickJS | 19.8 MB | 9.5 MB |
| Hello world (`--template mixed`) | TSX and a Rust crate | 19.8 MB | 9.5 MB |
| [sysmon](https://github.com/huacnlee/sysmon) 0.1.3 | Rust | 21.6 MB | 8.4 MB (its release's `.tar.gz`) |
| [Omasend](https://github.com/huacnlee/omasend) 0.2.0 | Rust | 18.4 MB | 9.7 MB (its release's `.tar.gz`) |

</div>

What makes these numbers:

- **Frames only for changes**: the display link ticks while a native animation runs and stops with it; an animation
  stops with its page (its view's deletion ends its keyframes, a loop stops in its component's `cleanup`).
- **Canvases drawn where they cost least**: a canvas that paints often (an animation, live data) draws on Core
  Animation's threads (`drawsAsynchronously`), which keeps the main thread free; one redrawn now and then draws at
  once, without the graphics memory asynchronous drawing holds. An animated value redraws only the area the
  operations reading it cover.
- **Static canvas parts kept**: once a drawing stays unchanged, a long part before its first animated operation is
  kept as a layer; each frame draws that layer and replays only the animated rest, at once on the main thread (the
  Canvas page's gauge, clock and dot matrix: no GPU work and half the memory).
- **Content drawn when it changes**: texts and canvases draw into layers of their own, again when their content or
  size changes, not when they move or scroll.

## Windows (Win32, Direct2D)

Measured on a Windows 11 desktop (Intel Core i7-13700KF, 32 GB, NVIDIA GeForce RTX 3060 Ti) on a 4K 144 Hz display at
150%, release builds, the gallery in a 1200 × 800 window (1800 × 1200 pixels), every reading taken automatically by
`examples/gallery/tools/perf.py` (`nsh test --target windows --fps`, one line a second; CPU is the whole process, in
percent of one core). The phases are the main thread's per frame: *paint* (Direct2D drawing the window) and, within
it, *canvas* (recording and replaying drawings).

### Animated demos

<div class="data-table">

| Demo | FPS | Frame p95 | Paint / canvas per frame | CPU |
|---|---|---|---|---|
| Stocks: 22 live sparklines, an intraday chart, order book, tape | 144 | 3.7–4.3 ms | 1.4 / 0.13 ms | 36–43% |
| Canvas: a gauge, a clock, a dot matrix | 144 | 1.0–2.0 ms | 0.8–1.4 / 0.05 ms | 21–35% |
| Animations: three native loops, springs, sequences | 144 | 1.0–3.6 ms | 0.9–1.9 ms | 20–41% |

</div>

Stocks commits 16–17 times a second, each in up to 2.1 ms of JS and 1.7 ms of the core on the engine thread (p95).

> [!NOTE]
> Pages whose animations move views across large areas take more CPU here than on Linux and macOS (Animations 20–41%
> against 5–13%, Gestures 36% against 1–5%). A Windows frame draws again, with Direct2D on the main thread, every view
> over the areas that changed: a ring that grows redraws the card under it on every frame. On macOS Core Animation
> moves, scales and fades the layers it keeps on the GPU without drawing them again, and on Linux GSK keeps the
> render nodes of what did not change. The numbers also count 144 frames a second at 1800 × 1200 pixels.

### Every page

Every page of the gallery, as it opens and while the test scrolls it, in the same 1200 × 800 window. As on Linux and
macOS, *FPS* is the rate while something moves (one frame per median gap between drawn frames); at the display's 144,
every frame of an animation or a scroll comes one refresh after the last. *Over one refresh* is the share of frames
that took longer than a refresh (6.9 ms). A page at rest draws no frame and uses 0–2% CPU. Images' GIF and WebP play
at their own frame rates (about 40 FPS here). Physics, Overlays, Menus and Storage are measured in a 900 × 500 window,
where they have room to scroll.

<div class="data-table">

| Page | Frames come from | FPS | Frame p95 | Over one refresh | CPU |
|---|---|---|---|---|---|
| Stocks | Live data, native loops | 144 | 3.9 ms | 0% | 36% |
| Stocks, scrolling | Live data, scroll | 144 | 4.3 ms | 0% | 43% |
| Photos, scrolling | Scroll | 143 | 2.1 ms | 0% | 9% |
| Lists, scrolling | Scroll | 144 | 2.0 ms | 1% | 19% |
| Scrolling, scrolling | Scroll | 143 | 2.1 ms | 0% | 7% |
| Navigation, scrolling | Scroll | 144 | 0.8 ms | 0% | 9% |
| Form, scrolling | Scroll | 144 | 0.8 ms | 0% | 12% |
| Resizable, scrolling | Scroll | 143 | 0.4 ms | 0% | 4% |
| Dock, scrolling | Scroll | 144 | 0.5 ms | 1% | 5% |
| Gestures | Springs, a pulsing ring | 144 | 1.8 ms | 0% | 36% |
| Physics, scrolling | Scroll (a 900 × 500 window) | 144 | 0.8 ms | 0% | 4% |
| Animations | Native loops | 144 | 1.0 ms | 0% | 28% |
| Canvas, scrolling | Scroll, native loops | 144 | 2.0 ms | 0% | 35% |
| Styles, scrolling | Scroll, a swaying transform | 144 | 2.1 ms | 0% | 39% |
| Tailwind | `animate-*` utilities | 144 | 0.6 ms | 0% | 19% |
| Text, scrolling | Scroll | 144 | 1.6 ms | 0% | 8% |
| Text View, scrolling | Scroll | 144 | 1.1 ms | 0% | 10% |
| Images, scrolling | Scroll, GIF and WebP frames | 143 | 4.8 ms | 2% | 23% |
| Components, scrolling | Scroll | 144 | 1.0 ms | 1% | 11% |
| Overlays, scrolling | Scroll (a 900 × 500 window) | 144 | 0.6 ms | 0% | 1% |
| Menus, scrolling | Scroll (a 900 × 500 window) | 144 | 0.6 ms | 0% | 2% |
| Controls | Transitions | 117–144 | 1.5 ms | 0% | 22% |
| Web and video, scrolling | Scroll | 144 | 1.6 ms | 0% | 15% |
| System | `requestAnimationFrame`, timers | 144 | < 0.1 ms | 0% | 1% |
| Storage, scrolling | Scroll (a 900 × 500 window) | 144 | 0.5 ms | 0% | 1% |

</div>

### Memory

At rest, 3 s after start (release runners, a 1200 × 800 window). *Private working set* is the memory the process
alone uses (Task Manager's Memory column); *private bytes* what it has committed; *working set* adds the pages of the
system's libraries it shares with other processes (Direct3D, Direct2D, DirectWrite, the GPU driver):

<div class="data-table">

| App | Private working set | Private bytes | Working set |
|---|---|---|---|
| Rust app (`nsh init --template rust`) | ~14 MB | ~60 MB | ~53–71 MB |
| TSX counter (`examples/counter`) | ~15 MB | ~61 MB | ~56–71 MB |

</div>

Through the gallery's tour the working set is ~108–115 MB on Stocks, ~230 MB from the Canvas page, ~320–340 MB from the
Text View page and ~390–405 MB once Web and video has opened WebView2 (whose pages run in WebView2's own processes),
with what it caches on purpose (decoded images, bounded at 128 MB; the Text View page's documents).

### App size

The hello world apps made by `nsh init` with each template, as `nsh package --target windows` builds them for x86_64
(the Rust runners with link-time optimization and stripped, as on Linux). The executable is the app's `<Name>.exe`;
the zip is the `.zip` written beside its directory:

<div class="data-table">

| App | Written in | Executable | Zip |
|---|---|---|---|
| Hello world (`--template rust`) | Rust | 15.0 MB | 6.7 MB |
| Hello world (`--template ts`) | TSX, on QuickJS | 28.6 MB | 12.4 MB |
| Hello world (`--template mixed`) | TSX and a Rust crate | 26.3 MB | 11.5 MB |

</div>

What makes these numbers:

- **Frames only for changes, drawn only where they changed**: the compositor-paced ticker runs while a native
  animation, a transition or a frame callback runs. A frame draws the areas of the views that changed (where they
  were and where they are), over the pixels the window keeps, and presents only those to the compositor (Stocks:
  ~34 views a frame).
- **Canvases record their animated part**: a drawing is recorded as Direct2D command lists, vector and sharp at any
  scale. When an animated value changes, only the operations from the first one that reads an animated value on are
  recorded again; what comes before is kept (Stocks: ~26 ms of recording a second for 22 pulsing sparklines and the
  chart).
- **Only what shows is drawn**: the children of a scroll view or a clipping view that lie out of sight are left out of
  the frame, and views with no content of their own draw no more than their background and border.

## iOS (UIKit)

Measured in the iOS simulator (an iPhone 18 Pro Max, on the MacBook Pro above), release builds, with the same tour
(`perf.py --target ios`: `nsh test --target ios --fps`, a finger's touches as UIKit gets them). The simulator presents
at 60 Hz; on an iPhone with a ProMotion screen NSH's display links run at the screen's 120 Hz (apps that `nsh package`
builds and the development host ask for it with `CADisableMinimumFrameDurationOnPhone`). The phases are *tick* (native
animations), *drain* (applying the engine's batches) and *scroll* (what follows a scroll view: lists, sticky cells,
bound values).

<div class="data-table">

| Page | Frames come from | FPS | Frame p95 | CPU |
|---|---|---|---|---|
| Home, scrolling | Scroll | 60 | 0.1 ms | 6% |
| Stocks | Live data, native loops | 60 | 0.3 ms | 22% |
| Stocks, scrolling | Live data, scroll | 60 | 0.3 ms | 25% |
| Photos, scrolling | Scroll | 60 | 1.2 ms | 6% |
| Lists, scrolling | Scroll | 60 | 1.1 ms | 8% |
| Scrolling, scrolling | Scroll | 60 | 0.1 ms | 7% |
| Navigation, scrolling | Scroll | 60 | 0.2 ms | 7% |
| Form, scrolling | Scroll | 60 | 0.3 ms | 7% |
| Gestures | Springs, a pulsing ring | 60 | 0.3 ms | 3% |
| Animations | Native loops | 60 | 0.7 ms | 6% |
| Canvas | Native loops | 60 | 0.4 ms | 16% |
| Styles | A swaying transform | 60 | 0.4 ms | 4% |
| Tailwind, scrolling | Scroll | 60 | 0.2 ms | 7% |
| Text, scrolling | Scroll | 60 | 0.1 ms | 7% |
| Text View, scrolling | Scroll | 60 | 0.1 ms | 6% |
| Images, scrolling | Scroll | 60 | 0.1 ms | 5% |
| Components, scrolling | Scroll | 60 | 0.2 ms | 6% |
| Overlays, scrolling | Scroll | 60 | 0.1 ms | 6% |
| Menus, scrolling | Scroll | 60 | 0.2 ms | 7% |
| Controls, scrolling | Scroll, transitions | 60 | 0.2 ms | 5% |
| Web and video, scrolling | Scroll | 60 | 0.1 ms | 8% |
| System | `requestAnimationFrame`, timers | 60 | 0.3 ms | 4% |
| Standard APIs, scrolling | Scroll | 60 | 0.1 ms | 7% |
| Storage, scrolling | Scroll | 60 | 0.1 ms | 8% |

</div>

*FPS* is the rate while something moves, as above: at the simulator's 60, every frame comes one refresh after the
last. Every page with nothing moving draws no frame and uses 1–2% CPU at rest. The process holds 40 MB on the
gallery's home page and ~180 MB after the whole tour (images cached on purpose, the Text View page's documents).

On an iPhone 17 Pro (ProMotion, 120 Hz), with the development host and one demo on the screen, the animated pages
draw every refresh:

<div class="data-table">

| Page | Frames come from | FPS | Frame p95 | Over one refresh | CPU | Memory |
|---|---|---|---|---|---|---|
| Stocks | Live data, native loops | 120 | 0.2–0.3 ms | 0% | 46–70% | 41–43 MB |
| Canvas | Native loops | 120 | 0.1 ms | 0% | 25–36% | 37–38 MB |
| Animations | Native loops | 120 | 0.2 ms | 0% | 3–11% | 37 MB |

</div>

Stocks commits 20 times a second (a tick every 50 ms), each in 1.5 ms of JS and 1.4 ms of the core on the engine
thread (p95 2.2 and 2.0 ms), which is busy 4–6% of the time.

## Measuring an app

To measure an app the same way, run its tests or steps with `--fps` and `-v` on `--target linux`, `macos`, `windows` or `ios`:

```sh
cargo build --release -p nsh-cli
python3 examples/gallery/tools/perf.py --target macos --only Stocks,Canvas   # the gallery, page by page
echo 'await app.wait(5000)' | nsh -v test App.tsx --target linux --fps        # any app
```

Source: https://nsh.dev/versions/main/docs/performance-report

---

# Architecture

This page is for app developers who want to know what happens between `count.set(1)` and a label changing on screen,
in an app written in Rust or in TSX.
You do not need it to write apps, but it explains why NSH behaves the way it does: why components run once, why
animations stay smooth while JS is busy, why the main thread never waits for your code.

## The big picture

![How an nsh app runs: the nsh CLI builds App.tsx into bytecode; on the engine thread, QuickJS runs a handler, the reactive graph in nsh-js queues ops, and nsh-core commits one MountBatch; it crosses to the main thread in one hop, which applies it to UIKit or Android views; touches go back as events. Native animations run on the main thread without JavaScript.](https://nsh.dev/versions/main/diagrams/architecture-light.svg)

## Building: only your code becomes JS

`nsh build`, `nsh dev` and the other commands bundle your app with a toolchain written in Rust (no Node.js):

1. **Oxc** removes the TypeScript types.
2. **NSH's JSX compiler** turns JSX into direct calls to the native renderer, in the same pass. Static props and
   children are set once; expressions that can change (they call a function or read a property) become bindings the
   renderer follows. Components become plain function calls with a props object whose changing props are getters.
3. **rolldown** bundles your modules into one ES module. Imports of NSH's modules (`nsh`, `nsh/mobile`,
   `nsh/base`, ...) stay imports: those modules are native, served by the runtime. **The bundle contains only your
   app's code**; the counter example is under 1 KB of JS.
4. The bundle is compiled to **bytecode** (`bundle.nshc`), which loads faster than source, and a **source map**
   is composed across all steps so stack traces point at your `.tsx` lines.

Images and fonts you import are collected as assets, and type declarations for your editor are written to
`.nsh/types`.

An app written in Rust has no bundle: Cargo builds each target's runner with your crate linked in, and the root
component `nsh.json` names runs on the engine natively. Everything below holds for it as well, with your components'
code running in Rust where a TSX app's runs in QuickJS.

## Running: two threads per app

Each running app (an `NshAppView` on iOS, an `NshView` on Android, the window of a packaged app) is one **engine** with
its own **engine thread**, and, for TSX, its own QuickJS VM. There are no global singletons, so several apps can run side by side
in one host app.

### The engine thread

Everything about your app's logic happens here:

- **Your code** runs here: components, event handlers, timers, effects. Rust components run natively; TSX runs in
  **QuickJS**.
- **The reactive graph** (signals, computed values, effects, owners, context) is native. Its nodes are QuickJS objects
  of native classes, so the garbage collector sees the references through them, but tracking dependencies and
  scheduling updates is Rust (it follows the algorithm of Solid 1.9).
- **The renderer** your compiled JSX calls is native. It creates nodes and turns every change into an **op** pushed
  straight into a native queue: no JSON, no messages per prop.
- **The core** keeps a shadow tree of all nodes. When a JS turn ends, it takes all queued ops at once and **commits**:
  renders the Rust components (`nsh/base`'s and the app's own), resolves `env()` insets in padding and margin, rebuilds changed texts, lays out with **Taffy** (flexbox and grid, with a
  column default and no shrinking), diffs frames and styles, and produces one **MountBatch**: the list of operations the native
  views need.

### The main thread

The platform's main (UI) thread applies each MountBatch in one hop: create views, insert them, set styles and frames,
hand over laid-out text. Besides that it only does what must happen on it:

- **drawing text** that was already laid out on the engine thread;
- **native animations**: animated values from `nsh` are driven frame by frame (a `CADisplayLink` on iOS, a UI-thread
  animator on Android) and written to the views directly;
- **gestures and scrolling**: touches become events sent to the engine thread; `scrollValue` and `pan` feed animated
  values in the same frame.

**The main thread never waits for JS.** When the system needs an answer on the spot (may this text change, may the
back button pop this screen, may this sheet close), the answer was mounted beforehand as a prop, and JS hears about it
afterwards through an event. A busy engine thread can delay updates, but it cannot freeze scrolling, animations or
the system's gestures.

## From a tap to the screen

```text
 main thread               engine thread                                              main thread
 ───────────               ─────────────────────────────────────────────────────      ───────────
 tap on a view ─ event ─▶  handler runs: count.set(count() + 1)
                           reactive graph: the bindings that read count() run again
                           renderer: one op per changed binding → native queue
                           JS turn ends → core commit: render, text, layout, diff
                           → MountBatch (e.g. 1 Text item)                 ─ hop ─▶   apply: draw the new text
```

In the counter example, a tap costs about 0.12 ms in a release build on a Mac, JS and commit together, and produces a
handful of mount items (see [Testing](https://nsh.dev/versions/main/docs/testing-and-trace.md)).

In a Rust app the handler is a Rust closure (`count.set(count.get() + 1)`), and the same graph, commit and batch
follow, with no interpreter on the way.

Three properties follow from this design:

- **One turn is one commit.** However many signals a handler sets, the views change once, together.
- **Components run once.** Only bindings re-run; there is no re-render of a component and no virtual DOM diff. The
  diffing that remains is the core's, over frames and styles, in Rust.
- **Only changes travel.** Unchanged styles and frames are not sent; new views get no default values.

## Text: laid out once, off the main thread

Text is often the most expensive part of a UI. NSH lays it out on the engine thread with the platform's own text
engine, so it looks exactly like native text:

1. **prepare**: a `<Text>` and its nested spans become one attributed string (CoreText on Apple platforms,
   `PrecomputedText` / `StaticLayout` on Android);
2. **measure** at the widths layout asks for; measurements are cached by content and width, so a color-only change does
   not measure again;
3. **layout** at the final size.

The main thread receives the immutable result and only draws it. A text nested in a `<Text>` is a span, not a view;
strings outside `<Text>` render nothing.

## Lists

`List` is virtualized natively. The core decides which rows are near the viewport, computes positions, columns and
sticky headers, and recycles cells. When a cell needs a different item, the runtime binds it (your row function's
`item()` and `index()` accessors change); frames that reveal no new row call no JS at all. See [Lists](https://nsh.dev/versions/main/docs/lists.md).

## Everything else the runtime does

- **Networking**: `fetch` and the other global APIs are native classes. Requests go to the platform's HTTP stack
  (`NSURLSession`, `HttpURLConnection`), streaming in both directions.
- **Images** download and decode off the main thread, at the size of the view, with a memory cache.
- **Limits and capabilities** are enforced by the runtime, in Rust: see [Sandbox and capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md).
- **Hot module replacement** is native too: patches are applied by the runtime in well under a millisecond (see
  [Dev server and debugging](https://nsh.dev/versions/main/docs/dev-server-and-debugging.md)).

## Three layers

NSH's UI is built in three layers, as GPUI Kit's is:

| Layer | NSH | GPUI Kit | What it is |
|---|---|---|---|
| Primitives | `nsh-core` and the runtime (`nsh`, `nsh/mobile`, `nsh/desktop`) | `gpui` | The host elements, styles, layout, rendering, reactivity, the environment |
| Base components | `nsh-base` (`nsh/base`) | `gpui-base` | Unstyled components that own behavior, state, focus, the keyboard and accessibility, and take their look from the app |
| Component library | your app's, or the community's | `gpui-component` | Styled components: buttons, cards, rows with a look |

The first two layers are Native Shell. The third is yours: an app builds its own component library on `nsh/base` and
the primitives, in TSX or as Rust components in [its own crate](https://nsh.dev/versions/main/docs/rust.md), uses one the community publishes, or
styles its UI directly in the app.

## The crates

NSH is a Rust workspace. You never build it to write apps (the distribution ships the CLI and prebuilt runtimes), but
the names show up in logs and docs:

| Crate | What it is |
|---|---|
| `nsh-core` | The platform-independent core: shadow tree, styles, Taffy layout, text merging, list virtualization, mount items; CSS values and Tailwind; the native animation graph (values, interpolation, timing / spring / decay); the Rust components' framework and theme; the runtime's Rust modules (`nsh/mobile`'s `BackHandler`, ...). |
| `nsh-base` | `nsh/base`, the unstyled base components (NSH's `gpui-base`): navigation, dialogs, controls and the status bar; Rust apps use it as `nsh_base`. |
| `nsh-js` | The QuickJS host and NSH's runtime: the reactive graph, the renderer, every native module, the global APIs, hot module replacement, limits; and the TypeScript declarations of all of it. |
| `nsh-engine` | The engine thread: drives `nsh-js` and `nsh-core` and hands one batch per frame to the platform. |
| `nsh-package` | Signed packages: keys, certificates, revocation, the trust store. |
| `nsh-bundler` | The bundler: rolldown, Oxc, NSH's JSX compiler, source maps, Tailwind class checks. |
| `nsh-dev` | The dev server and its client. |
| `nsh-platform-ios` | The UIKit backend (iOS, simulator, Mac Catalyst): view mounting, the CoreText text engine, input; the embedding SDK. |
| `nsh-platform-android` | The Android backend: `libnsh.so` and the Java runtime (`NshView`, the views, images, networking). |
| `nsh-cli` | The `nsh` command. |

The dependency direction is `nsh-core` ← `nsh-js` ← `nsh-engine` ← platforms; `nsh-base` builds on `nsh-core`. The core depends on no platform and no JS
engine, which is what lets `nsh test` run the real runtime headless on any machine.

## See also

- [Performance](https://nsh.dev/versions/main/docs/performance.md)
- [Reactivity](https://nsh.dev/versions/main/docs/reactivity.md)

Source: https://nsh.dev/versions/main/docs/architecture

---

# Elements

Native Shell builds every screen from a small set of elements: primitives such as `View`, `Text` and `Image`, and base
components such as `Button`, `Dialog` and `NavStack`. Each primitive is a native view (a UIView subclass on iOS and Mac
Catalyst, an Android `View`, an AppKit, GTK or Win32 view on the desktops), created and laid out by the NSH runtime.
Everything an app shows is made of them: an app's buttons, cards, rows and screens are its own components, drawn with
these elements and styled by the app, so the app's look is entirely its own.

Every example on these pages comes in Rust and TSX: pick a tab, and every example on the page follows.

```rust
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())),
        )
}
```

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

In Rust, the primitives are functions of `nsh_core::prelude` (`view()`, `text(..)`, `image(..)`) and the base
components come from the `nsh_base` crate. Styles are typed methods (`.flex_1()`, `.gap_3()`, `.px(px(20.0))`,
`.bg(..)`), state styles take a closure (`.active(|s| s.opacity(0.6))`), listeners are closures of their event
(`.on_press(move || ..)`, `.on_change(move |text: &str| ..)`) and `.child(..)` adds children. A piece of UI is a plain function returning
`impl IntoElement`; it runs once, and signals it reads in closures (`text(move || ..)`, `.bg(move || ..)`) update what
they bind. See [Building with Rust](https://nsh.dev/versions/main/docs/rust.md).

In TSX, every tag is PascalCase and names a binding in scope: the primitives come from `nsh`, the base components from
`nsh/base`. Only `<If>` and `<Each>` are globals that need no import. A lowercase tag such as `<view>` is a build error,
because TypeScript would check it against one global type per name, and generic components such as `List` and `Each`
could not infer their item types. The compiler recognizes the elements through their imports and makes the native
views in place, so importing them costs nothing at run time. See [JSX and components](https://nsh.dev/versions/main/docs/jsx-and-components.md).

```tsx
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

Imported from `nsh` in TSX, from `nsh_core::prelude` in Rust.

| Element | Rust | Native view (iOS / Android) | Page |
|---|---|---|---|
| `<View>` | `view()` | UIView / ViewGroup; with `selectable`, the texts inside it select together | [View](https://nsh.dev/versions/main/elements/view.md), [Text selection](https://nsh.dev/versions/main/elements/text-selection.md) |
| `<Text>` | `text(content)` | CoreText view / StaticLayout view | [Text](https://nsh.dev/versions/main/elements/text.md) |
| `<Image>` | `image(src)` | a view with an image layer / an image view | [Image](https://nsh.dev/versions/main/elements/image.md) |
| `<Scroll>` | `scroll()` | UIScrollView / ScrollView | [Scroll](https://nsh.dev/versions/main/elements/scroll.md) |
| `<List>` | `virtual_list(count, \|at\| row)` | UIScrollView / ScrollView with recycled cells | [List](https://nsh.dev/versions/main/elements/list.md) |
| `<Canvas>` | `canvas(painter)` | a view replaying a 2D drawing | [Canvas](https://nsh.dev/versions/main/elements/canvas.md) |
| `<Shader>` | `shader(program)` | a view whose box a WGSL program draws on the GPU, under its children | [Shader](https://nsh.dev/versions/main/elements/shader.md) |
| `<WebView>` | `web_view(url)`, `web_view_html(html, base)` | WKWebView / android.webkit.WebView | [WebView](https://nsh.dev/versions/main/elements/web-view.md) |
| `<Video>` | `video(url)` | AVPlayerLayer / MediaPlayer on a TextureView | [Video](https://nsh.dev/versions/main/elements/video.md) |
| `<Overlay>` | `overlay()` | a view on top of the window (or the dialog it is in), placed against an anchor | [Overlay](https://nsh.dev/versions/main/elements/overlay.md) |
| `<If>`, `<Each>` | `when(..)`, `each(..)`, `dynamic(..)` | control flow: the elements they choose | [Control flow](https://nsh.dev/versions/main/elements/control-flow.md) |
| `<InputAccessoryView>` (`nsh/mobile`) | `input_accessory_view(id)` | a bar over the keyboard on iOS | [`InputAccessoryView`](https://nsh.dev/versions/main/modules/nsh-mobile.md#inputaccessoryview) |

Padding and margin keep content clear of system UI with CSS's `env()`: `env(safe-area-inset-top)` and the other edges ([Safe area](https://nsh.dev/versions/main/elements/safe-area.md)) and `env(keyboard-inset-height)` ([Keyboard](https://nsh.dev/versions/main/elements/keyboard.md)).

## Base

Imported from `nsh/base` in TSX, from the `nsh_base` crate in Rust. They own behavior, state, focus and accessibility
and take their look from the app.

| Component | Rust | What it does | Page |
|---|---|---|---|
| `AlertDialog` | `nsh_base::alert_dialog()` | The system's alert and action sheet | [AlertDialog](https://nsh.dev/versions/main/elements/alert-dialog.md) |
| `<Accordion>` and its parts | `nsh_base::accordion()`, `accordion_item()`, ... | Stacked sections that expand and collapse under their headings, one at a time or several | [Accordion](https://nsh.dev/versions/main/elements/accordion.md) |
| `<Avatar>`, `<AvatarGroup>` | `nsh_base::avatar()`, `avatar_group()` | A person's picture, or a fallback while it loads or when it fails, and a row of them that shows the first few | [Avatar](https://nsh.dev/versions/main/elements/avatar.md) |
| `<Button>` | `nsh_base::button()` | A pressable control with its states and its role | [Button](https://nsh.dev/versions/main/elements/button.md) |
| `<Carousel>` and its parts | `nsh_base::carousel()`, `carousel_content()`, ... | Slides shown one place at a time, swiped natively, with previous / next, a pagination, the keys and a seamless loop | [Carousel](https://nsh.dev/versions/main/elements/carousel.md) |
| `<Checkbox>` | `nsh_base::checkbox()` | A checked, unchecked or indeterminate control with an indicator | [Checkbox](https://nsh.dev/versions/main/elements/checkbox.md) |
| `<Collapsible>` | `nsh_base::collapsible()` | A region whose content expands and collapses | [Collapsible](https://nsh.dev/versions/main/elements/collapsible.md) |
| `<Command>` | `nsh_base::command()` | A command palette: a search field over commands filtered natively, a virtualized list, the keys of a Cmd+K palette | [Command](https://nsh.dev/versions/main/elements/command.md) |
| `<DataTable>` | `nsh_base::data_table()` | A table of rows and columns of any number, selectable, sortable, with resizable and movable columns | [DataTable](https://nsh.dev/versions/main/elements/data-table.md) |
| `<Dialog>` | `nsh_base::dialog()` | Presents its children over everything else | [Dialog](https://nsh.dev/versions/main/elements/dialog.md) |
| `<DiffView>` | `nsh_base::diff_view()` | The changes between two texts or of a patch, split or unified | [DiffView](https://nsh.dev/versions/main/elements/diff-view.md) |
| `<DockArea>` | `nsh_base::dock_area()` | A workspace of splits, tab groups and edge docks the user arranges | [Dock](https://nsh.dev/versions/main/elements/dock.md) |
| `<Editor>` | `nsh_base::editor()` | A code editor with highlighting, several carets, folding and search | [Editor](https://nsh.dev/versions/main/elements/editor.md) |
| `<HoverCard>` | `nsh_base::hover_card()` | A preview of what its trigger points at, while the pointer rests on it | [HoverCard](https://nsh.dev/versions/main/elements/hover-card.md) |
| `<Input>` | `nsh_base::input()` | The native text input (UITextField or UITextView / EditText) | [Input](https://nsh.dev/versions/main/elements/input.md) |
| `<Link>` | `nsh_base::link()` | A press target that opens a page, a site or a route of the app | [Link](https://nsh.dev/versions/main/elements/link.md) |
| `<Menu>`, `<ContextMenu>`, `<MenuItem>`, `<MenuSeparator>`, `<Submenu>` | `nsh_base::menu()`, ... | Menus: popups with cascading submenus on desktops, sheets on phones | [Menu](https://nsh.dev/versions/main/elements/menu.md) |
| `<NavStack>`, `<NavPage>` | `nsh_base::nav_stack()`, `nsh_base::nav_page()` | Native navigation: a stack of pages with the platform's header and back gestures | [NavStack](https://nsh.dev/versions/main/elements/nav-stack.md) |
| `<NumberInput>` | `nsh_base::number_input()` | A number typed in a field or stepped with buttons and keys | [NumberInput](https://nsh.dev/versions/main/elements/number-input.md) |
| `<OtpInput>` | `nsh_base::otp_input()` | A one-time code of a fixed number of digits, typed, pasted or autofilled into cells | [OtpInput](https://nsh.dev/versions/main/elements/otp-input.md) |
| `<Pagination>` | `nsh_base::pagination()` | The pages of a set: Previous, the pages around the current one, ellipses and Next | [Pagination](https://nsh.dev/versions/main/elements/pagination.md) |
| `<Tree>` | `nsh_base::tree()` | Items that hold items, expanded and collapsed, one selected: virtualized, one stop of the keyboard focus | [Tree](https://nsh.dev/versions/main/elements/tree.md) |
| `<Plot>`, `<Line>`, `<Area>`, `<Bar>`, `<Grid>`, `<Pie>`, `<Arc>` (`nsh/base/plot`) | `nsh_base::plot::{plot, line, area, bar, grid, pie, arc}` | A chart's frame and its marks, drawn natively from the app's rows | [Plot](https://nsh.dev/versions/main/elements/plot.md) |
| `<Popover>` | `nsh_base::popover()` | Content anchored to a trigger, on top of everything | [Popover](https://nsh.dev/versions/main/elements/popover.md) |
| `<Progress>` | `nsh_base::progress()` | A progress bar: how far a task is, or that it is under way | [Progress](https://nsh.dev/versions/main/elements/progress.md) |
| `<Radio>`, `<RadioGroup>` | `nsh_base::radio()`, `radio_group()` | One option of a set the user picks one of, and the set | [Radio](https://nsh.dev/versions/main/elements/radio.md) |
| `<ResizablePanelGroup>`, `<ResizablePanel>` | `nsh_base::h_resizable()`, `resizable_panel()` | Panels side by side or stacked, with handles that resize them | [Resizable](https://nsh.dev/versions/main/elements/resizable.md) |
| `<Scrollbar>` | `nsh_base::scrollbar()` | A scroll bar of the app's own look for a scroll view or a list | [Scrollbar](https://nsh.dev/versions/main/elements/scrollbar.md) |
| `<Select>` | `nsh_base::select()` | One value chosen from a list of items, with the keyboard, search and sections | [Select](https://nsh.dev/versions/main/elements/select.md) |
| `<Sheet>` | `nsh_base::sheet()` | A panel at an edge of the screen over a backdrop | [Sheet](https://nsh.dev/versions/main/elements/sheet.md) |
| `<Slider>` | `nsh_base::slider()` | A value, or a range of two, picked along a track | [Slider](https://nsh.dev/versions/main/elements/slider.md) |
| `<Switch>` | `nsh_base::switch()` | An on / off control with a track and a thumb | [Switch](https://nsh.dev/versions/main/elements/switch.md) |
| `<Table>` and its parts | `nsh_base::table()`, `table_row()`, ... | A table of the app's own rows and cells, with a table's roles | [Table](https://nsh.dev/versions/main/elements/table.md) |
| `<Tab>`, `<Tabs>` | `nsh_base::tab()`, `tabs()` | One tab of a tab list, and the list | [Tabs](https://nsh.dev/versions/main/elements/tabs.md) |
| `<TextView>` | `nsh_base::text_view()` | Shows a Markdown or HTML document with texts and views | [TextView](https://nsh.dev/versions/main/elements/text-view.md) |
| `<Toast>`, `<ToastStack>` | `nsh_base::toast()`, `toast_stack()` | A toast's semantic root; toasts laid out as layers from an edge | [Toast](https://nsh.dev/versions/main/elements/toast.md) |
| `<Toggle>`, `<ToggleGroup>` | `nsh_base::toggle()`, `toggle_group()` | A button that is on or off, and a toolbar of them | [Toggle](https://nsh.dev/versions/main/elements/toggle.md) |
| `<Toolbar>`, `<ToolbarGroup>`, `<ToolbarSeparator>` | `nsh_base::toolbar()`, `toolbar_group()`, `toolbar_separator()` | A bar of buttons, toggles and links, one stop of the keyboard focus | [Toolbar](https://nsh.dev/versions/main/elements/toolbar.md) |
| `<Tooltip>` | `nsh_base::tooltip()` | A hint next to its trigger, on hover or a held finger | [Tooltip](https://nsh.dev/versions/main/elements/tooltip.md) |

> [!NOTE]
> A string is only drawn inside a `Text`. A string child of a `View` creates no native view and takes no part in
> layout.

## Common props

Every primitive accepts the props below (the `CommonProps` type in TSX; the `Styled`, `Interactive` and `Accessible`
traits in Rust). Element pages list only their own props. The Rust column names the builder method.

### Styling

| Prop | Rust | Type | Description |
|---|---|---|---|
| `style` | typed `Styled` methods; `.inline_style(style)` | `StyleProp<ViewStyle>` (`TextStyle` for `<Text>` and `<Input>`, `ImageStyle` for `<Image>`) | Inline style, or an array of styles merged left to right (falsy entries skipped; arrays may nest, so `style={[base, props.style]}` takes a `props.style` that is itself an array). Wins over `class`. See the [style reference](https://nsh.dev/versions/main/modules/style-reference.md). |
| `class` | typed `Styled` methods (`.flex_row().gap_2().p_4()`) | `string` | Tailwind classes, resolved natively (`"flex-row gap-2 p-4 dark:bg-zinc-900"`). Later classes win over earlier ones. See [Tailwind](https://nsh.dev/versions/main/docs/tailwind.md). |
| `classList` | `.style_when(when, \|s\| ..)` | `Record<string, boolean \| null \| undefined>` | Classes applied while their value is truthy (`{ "opacity-50": busy() }`). |
| `disabled` | `.disabled(..)` | `boolean` | Ignores presses (no press feedback either), applies `disabled:` styles, disables controls such as inputs, and screen readers say it is disabled (`accessibilityState.disabled`). |

### Presses and feedback

Press handling runs natively: the platform recognizes the press and applies the app's press styles, and the app's code
only hears about it afterwards. Only the innermost pressable view responds; inside scroll views a press-in waits about
130 ms so a scroll can start first.

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `onPress` | `.on_press(..)` | `(e: PressEvent) => void` | | A tap ended inside the view. |
| `onLongPress` | `.on_long_press(..)` | `(e: PressEvent) => void` | | The finger stayed down for `delayLongPress`. |
| `onPressDown` | `.on_press_down(..)` | `(e: PressEvent) => void` | | A finger went down on the view. |
| `onPressUp` | `.on_press_up(..)` | `(e: PressEvent) => void` | | The finger lifted or left. |
| `delayLongPress` | `.long_press_delay(ms)` | `number` | `500` | Milliseconds before a press becomes a long press. |
| `hitSlop` | `.hit_slop(EdgeInsets::all(px(8.0)))` | `number \| Partial<Edges>` | | Extends the touch area beyond the bounds, in points. |

`PressEvent` is `{ position, pagePosition, modifiers, clickCount }`: where the pointer was in the view and in its root
view (`Point`s), the modifier keys held when the press began and the consecutive clicks (2 for a double click). Where
the platform reports no pointer, it is the view's origin with no keys and one click.

The style key `pointerEvents` (`.pointer_events(PointerEvents::BoxNone)` in Rust, the classes `pointer-events-*`)
decides which touches the view and the views in it receive: `"none"` neither (a view inside that sets `"auto"` takes
them again), `"box-none"` only the views in it, `"box-only"` only the view itself
([touch and gestures](https://nsh.dev/versions/main/docs/touch-and-gestures.md#pointerevents)).

The press feedback is the app's: `activeStyle` (or `active:` classes, `.active(..)` in Rust) applies while the view is
pressed, natively, with no round trip to the app's code (below).

### State styles

Styles that apply while the view is in a state, over its own styles, natively. Each is the object form of a Tailwind
variant. Later states win (selected, checked and indeterminate, then hover, focus, active); `disabledStyle` wins over all, and the others do not
apply while the view is disabled. Each takes the element's own style: a `TextStyle` on a `<Text>`, an `InputStyle` on
an `<Input>`, an `ImageStyle` on an `<Image>`, a `ViewStyle` elsewhere.

| Prop | Rust | Class variant | Applies |
|---|---|---|---|
| `activeStyle` | `.active(\|s\| ..)` | `active:` | While pressed. |
| `hoverStyle` | `.hover(\|s\| ..)` | `hover:` | While a pointer is over the view. |
| `focusStyle` | `.focus(\|s\| ..)` | `focus:` | While the view has focus. |
| `focusWithinStyle` | `.focus_within(\|s\| ..)` | `focus-within:` | While the view or a view inside it has focus (the content of an `Overlay` counts as inside the view it is in). |
| `disabledStyle` | `.disabled_style(\|s\| ..)` | `disabled:` | While `disabled`. |
| `checkedStyle` | `.checked(\|s\| ..)`, `.checked_style(style)` | `checked:` | While `accessibilityState.checked` is `true` (a checkbox, a switch, a radio; `"mixed"` is not checked). |
| `indeterminateStyle` | `.indeterminate(\|s\| ..)`, `.indeterminate_style(style)` | `indeterminate:` | While `accessibilityState.checked` is `"mixed"` (a checkbox that is neither checked nor unchecked). |
| `selectedStyle` | `.selected(\|s\| ..)` | `selected:` | While `accessibilityState.selected` is `true` (a selected `Button`, a tab). |
| `expandedStyle` | `.expanded(\|s\| ..)`, `.expanded_style(style)` | `aria-expanded:` | While `accessibilityState.expanded` is `true` (a `Popover`'s or `Menu`'s trigger while its popup is open). |
| `pressedStyle` | `.aria_pressed(\|s\| ..)`, `.pressed_style(style)` | `aria-pressed:` | While `accessibilityState.pressed` is `true` (a toggle button that is on; `"mixed"` is not pressed). Not `activeStyle`, a press in progress. |

```rust
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()))
```

```tsx
<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

The app hears the mouse come over a view, move over it and leave it: on macOS, Windows, Linux, the GPUI backend and in
desktop browsers, with an iPad's pointer or a Mac's mouse on iOS, and with a mouse or a stylus on Android. Hover styles
(`hover:`, `.hover(..)`) style hovered views in the same places.

| Prop | Rust | Type | Description |
|---|---|---|---|
| `onMouseEnter` | `.on_mouse_enter(..)` | `(e: MouseEvent) => void` | The mouse came over the view or a view inside it (the DOM's `mouseenter`). |
| `onMouseMove` | `.on_mouse_move(..)` | `(e: MouseEvent) => void` | The mouse moved over the view (or a view inside it), with or without a button down, or a modifier key was pressed or released while it rests there with none down (the DOM's `mousemove`). |
| `onMouseLeave` | `.on_mouse_leave(..)` | `(e: MouseEvent) => void` | The mouse left the view and the views inside it, or the window; `e` is where it was last (the DOM's `mouseleave`). |

Like CSS `:hover` and the DOM's `mouseenter`, a view counts as hovered while the mouse is over it or over anything
inside it, so the views around the one under the mouse hear `onMouseEnter` too (from the outside in; `onMouseLeave`
from the inside out). The events come after the fact and never on touches. A view removed from under the mouse hears
`onMouseLeave`, on Linux and Windows at the next mouse move.

`MouseEvent` says where the mouse is, as GPUI's `MouseMoveEvent` does: `position` in the view (a `Point` in points, its
transforms undone), `pagePosition` in the root view it is in, as touches give it, the `modifiers` held (`control`,
`alt`, `shift`, `platform`: Command on Apple platforms, the Windows key elsewhere), and `pressedButton`, the button held
down (`"left"`, `"right"`, `"middle"`, `"back"` or `"forward"`, GPUI's `MouseButton`) or `null`; in Rust `position`,
`page_position`, `modifiers` and `pressed_button`. On the desktops and the web a drag is also a touch (`onTouchMove`,
the responder), and its moves reach `onMouseMove` with `pressedButton` set: feedback that only follows the hover skips
those; on iOS and Android the hover reports the pointer with no button down. Moves come at most once a frame, the
latest one, and always before the `onMouseLeave` that follows them, so a handler can redraw on each move:

```rust
// 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))
    }))
```

```tsx
// 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` gives any element a hint, shown above it on the desktops (macOS, Windows, Linux, the GPUI backend and
desktop browsers) once the pointer has rested on it for half a second, until the pointer leaves or presses it, and on
every device while the keyboard focus is on it, until the focus leaves or Escape is pressed. The hint never takes the pointer or presses, so the element works exactly as it does without it.

| Prop | Rust | Type | Description |
|---|---|---|---|
| `tooltip` | `.tooltip(..)` | `JSX.Element` | The hint, an element the app styles: a [`Tooltip`](https://nsh.dev/versions/main/elements/tooltip.md) of `nsh/base` is the tooltip itself, with its placement, delay and events; any other element is shown as it is. |

```rust
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("💾"))
```

```tsx
<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>
```

The `Tooltip` sets its own look, placement, delay and events, as GPUI's `.tooltip(..)` takes one. An app with many
tooltips keeps one small component of its own that wraps a text in its `Tooltip`.

### Context menus

`onContextMenu` tells a view that the secondary button was pressed over it: a right click, Control-click on macOS, a
two-finger click on a touchpad, the secondary click of an iPad's pointer; in browsers also the keyboard's menu key.
Open the app's own menu there; in TSX, [`Menu.popup`](https://nsh.dev/versions/main/modules/nsh-desktop.md) shows the system's:

```rust
// 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()))
```

```tsx
import { Menu } from "nsh/desktop";

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

| Prop | Rust | Type | Description |
|---|---|---|---|
| `onContextMenu` | `.on_context_menu(..)` | `(e: ContextMenuEvent) => void` | The secondary button was pressed over the view or a view inside it. |

`ContextMenuEvent` has `position` in the view, `pagePosition` in its root view (where `Menu.popup` places a menu:
`Menu.popup(items, e.pagePosition)`) and the `modifiers`; in Rust `position`, `page_position` and `modifiers`. The nearest view that listens, from the one under the pointer outwards, hears it. A text input, or
selectable text with an edit menu (Windows, the GPUI backend, browsers), nearer than that view shows its own menu
instead. The platform decides this as the button goes down, from what is mounted, so the handler is told after the fact
and nothing has to be cancelled. A `disabled` view leaves the click to the nearest enabled listener around it. On
touchscreens, a long press opens menus: handle `onLongPress` with the same function.

### Keyboard focus

On macOS and the web, Tab moves the keyboard focus between its stops in tree order: the inputs, the views that take
presses, and every `focusable` view. Focus styles (`focus:`, `.focus(..)`) style the focused view, and Return or Space
presses it when it takes presses. A click presses a view without focusing it, so focus styles show for keyboard focus
only.

Focus and presses are separate. A view that takes keys while it has the focus (a chart, a slider, a list that moves
its selection with the arrow keys) sets `focusable` and binds its keys while focused (`onFocus` / `onBlur` with
[`keymap`](https://nsh.dev/versions/main/modules/nsh.md#keymap)); a press on it still reaches a pressable around it, such as a card that
opens a page.

A ref's `focus()` moves the keyboard focus to a stop as Tab does (its focus styles show and `onFocus` fires), say to
give it back to the trigger of a popup that closed, and `blur()` takes it off.

A view around the focus styles itself with `focus-within:` (`focusWithinStyle`, `.focus_within(..)`) while the focus
is on it or on any view inside it: a field's frame around the input that edits, a toolbar while one of its buttons has
the focus. The content of an `Overlay` is inside the view the overlay is in, wherever it shows, so a popup counts as
part of the view that holds its trigger. In Rust, a component hears the focus come into an element and leave it with
its ref's `on_focus_in(..)` and `on_focus_out(..)`: moving between views inside it is neither.

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `focusable` | `.focusable(..)` | `boolean` | `true` for views that take presses | Whether the view is a stop of Tab. `true` makes any view one, whether it takes presses or leaves them to the views around it; `false` leaves a pressable to the pointer (a backdrop that closes a popover, rows the arrow keys move between). |
| `onFocus` | `.on_focus(..)` | `() => void` | | Tab (or `focus()`) gave the view the keyboard focus. |
| `onBlur` | `.on_blur(..)` | `() => void` | | The keyboard focus left the view. |

```rust
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)),
)
```

```tsx
<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 and identity

| Prop | Rust | Type | Description |
|---|---|---|---|
| `onLayout` | `.on_layout(\|frame: &Bounds<Points>\| ..)` | `(e: { bounds: Bounds }) => void` | `bounds` is the view's frame relative to its parent, `{ origin, size }`, after each layout that changes it. |
| `ref` | `.element_ref(&handle)` | `ViewRef \| (node: ViewRef) => void` | The element's ref (see [ref methods](#ref-methods)): `ViewRef`, or the element's own type over it. `ref={el}` assigns a variable, `ref={fn}` calls a function. |
| `nativeID` | `.native_id(id)` | `string` | Names the view for others, e.g. the `InputAccessoryView` an input refers to. |
| `testID` | `.test_id(id)` | `string` | An identifier for UI tests (on Android, the view's resource id). |
| `key` | `.key(key)` | `string` | The element's identity among its siblings. |

### Gestures driving animated values

These props bind a gesture to [native animated values](https://nsh.dev/versions/main/modules/nsh.md#animation) that move on the UI thread, with no
work in the app's code per frame. See [touch and gestures](https://nsh.dev/versions/main/docs/touch-and-gestures.md).

| Prop | Rust | Type | Description |
|---|---|---|---|
| `pan` | `.pan_values(Some(&x), Some(&y))` | `{ x?: AnimatedValue; y?: AnimatedValue }` | Drags drive these values (points). |
| `onPanStart` | `.on_pan_start(..)` | `(e: PanEvent) => void` | A drag started. |
| `onPanEnd` | `.on_pan_end(..)` | `(e: PanEvent) => void` | A drag ended, with the release velocity (e.g. to start a `decay`). |
| `pinch` | `.pinch_value(&scale)` | `{ scale?: AnimatedValue }` | Two-finger pinches drive `scale`. |
| `onPinchStart` / `onPinchEnd` | `.on_pinch_start(..)` / `.on_pinch_end(..)` | `(e: { scale: number; velocity: number }) => void` | A pinch started / ended. |
| `rotation` | `.rotation_value(&angle)` | `{ angle?: AnimatedValue }` | Two-finger rotations drive `angle` (degrees). |
| `onRotationStart` / `onRotationEnd` | `.on_rotation_start(..)` / `.on_rotation_end(..)` | `(e: { rotation: number; velocity: number }) => void` | A rotation started / ended. |

`PanEvent` is `{ cancelled, translation, velocity, value? }` (in Rust `cancelled`, `translation`, `velocity_x`,
`velocity_y`, `value_x`, `value_y`): whether the system cancelled the drag, the translation since the start and the
velocity in points per second (`Point`s), and the bound values at that moment, `{ x?, y? }` for the axes `pan` binds
(a drag can grab a value mid-animation).

### Raw touches and the responder system

For gestures the props above do not cover, every element takes the touch and responder props:
`onTouchStart`, `onTouchMove`, `onTouchEnd`, `onTouchCancel` (and their `…Capture` forms),
`onStartShouldSetResponder`, `onMoveShouldSetResponder` (and `…Capture`), `onResponderGrant`, `onResponderReject`,
`onResponderStart`, `onResponderMove`, `onResponderEnd`, `onResponderRelease`, `onResponderTerminate` and
`onResponderTerminationRequest`. Each handler gets a `GestureResponderEvent`
(`{ identifier, locationX, locationY, pageX, pageY, target, timestamp, touches, changedTouches, nativeEvent,
stopPropagation() }`); the `…ShouldSetResponder` handlers also get a `gestureState` (`dx`, `dy`, `vx`, `vy`, ...).
Returning `true` from `onResponderGrant` keeps native scroll views from taking the touches. `panActivation`
(`{ activeOffsetX, activeOffsetY, failOffsetX, failOffsetY }`) makes the view the responder only once the platform
activates its pan, so drags inside scroll views leave the other axis to them
([Touch and gestures](https://nsh.dev/versions/main/docs/touch-and-gestures.md#pans-inside-scroll-views-panactivation)).
`PanResponder` in [`PanResponder`](https://nsh.dev/versions/main/modules/nsh.md#panresponder) builds on them. In Rust, `.on_touch(..)` hears every touch
(`TouchEvent`), `.claim_touches(..)` decides when the view takes them, and `.on_responder_grant(..)`,
`.on_responder_move(..)`, `.on_responder_release(..)` and the others follow the responder.

### Accessibility

| Prop | Rust | Type | Description |
|---|---|---|---|
| `accessible` | `.accessible(..)` | `boolean` | The view is one element for assistive technologies; its children are not exposed separately. |
| `accessibilityLabel` | `.label(..)` | `string` | What screen readers read. Views without a label read their texts. |
| `accessibilityHint` | `.hint(..)` | `string` | What activating the element does. |
| `role` | `.role(AccessibilityRole::Button)` | `AccessibilityRole` | What the element is (`"button"`, `"header"`, `"link"`, `"switch"`, …). |
| `accessibilityState` | `.accessibility_state(..)` | `{ disabled?, selected?, checked?, busy?, expanded?, pressed?, current? }` | The state assistive technologies report (`checked` and `pressed` may be `"mixed"`; `current` is `true` or `"page"`, `"step"`, `"location"`, `"date"`, `"time"`). |
| `accessibilityLevel` | `.accessibility_level(..)` | `number` | The level of a heading (1 the top), the depth of a tree item (1 at the top). |
| `accessibilityValue` | `.accessibility_value(..)` | `{ min?, max?, now?, text? }` | The value of a range or textual element. |
| `accessibilityElementsHidden` | | `boolean` | Hides the view and its subtree from assistive technologies. |
| `importantForAccessibility` | | `"auto" \| "yes" \| "no" \| "no-hide-descendants"` | Whether the view is exposed. |
| `accessibilityActions` | | `{ name: string; label?: string }[]` | Custom actions offered to assistive technologies. |
| `onAccessibilityAction` | `.on_accessibility_action(..)` | `(e: { actionName: string }) => void` | The user invoked one of `accessibilityActions`. |

See [accessibility](https://nsh.dev/versions/main/docs/accessibility.md).

### Platform-only props

Props that exist on one platform go in an object named after it in TSX, so the shared props stay the same everywhere.
Only the current platform's object is sent; the others are ignored. Rust builders take them as methods that apply on
their platform.

| Prop | Description |
|---|---|
| `ios={{…}}` | iOS and Mac Catalyst. `<Input>`, `Dialog` and `WebView` add their own keys. |
| `android={{…}}` | Android. Every element takes `ripple`, `elevation` and `accessibilityLiveRegion` (below). |
| `desktop={{…}}` | Desktop platforms and desktop browsers; ignored on mobile. Every element takes `windowDrag` (below). |
| `web={{…}}` | Browsers; ignored elsewhere. |

| `android` key | Rust | Type | Description |
|---|---|---|---|
| `ripple` | `.ripple(Ripple { .. })` | `{ color?, borderless?, radius?, foreground? }` | The material ripple while pressed. |
| `elevation` | `.elevation(px(2.0))` | `number` | The material shadow (points), from the view's shape. |
| `accessibilityLiveRegion` | | `"none" \| "polite" \| "assertive"` | How changes of the view are announced to TalkBack. |

| `desktop` key | Rust | Type | Description |
|---|---|---|---|
| `windowDrag` | `.window_drag(..)` | `boolean` | Pressing the view drags the window, as its title bar would; `false` keeps a part of a draggable view clickable. See [a title bar of your own](https://nsh.dev/versions/main/modules/nsh-desktop.md#a-title-bar-of-your-own). |

```rust
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"))
```

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

See [platform-specific code](https://nsh.dev/versions/main/docs/platform-specific.md).

## Ref methods

In TSX, `ref` receives the element's ref, whose type is the element's own: `ViewRef` (`focus`, `blur`, `measure`) for
`View`, `Text`, `Image`, `Canvas`, `Overlay` and `Shader`, and a type over `ViewRef` with the element's methods for the
others: `InputRef` (`Input`), `ScrollRef` (`Scroll`), `ListRef` (`List`), `WebViewRef` (`WebView`), `VideoRef`
(`Video`) and `NativeComponentRef` (native components). In Rust, `element_ref()` makes an `ElementRef` handle that
`.element_ref(&handle)` attaches. Their methods send commands to the native view, in order with the changes made
before them in the same turn. Each element page says which apply to it. Type a ref variable with its element's own
type (`let field!: InputRef` for an `<Input>`): a variable typed `ViewRef` does not fit an element whose ref has methods
of its own.

| Method | Rust | Ref | Description |
|---|---|---|---|
| `focus()` / `blur()` | `focus()` / `blur()` | `ViewRef` | Focuses an `<Input>` (shows the keyboard), or gives a view that takes presses the keyboard focus / unfocuses. |
| `measure()` | `measure()` | `ViewRef` | [Where the view is](https://nsh.dev/versions/main/docs/touch-and-gestures.md#where-a-view-is-measure). |
| `setSelection(start, end?)` | `set_selection(start, end)` | `InputRef` | Selects `start..end` in UTF-16 units; a caret without `end`. |
| `scrollTo({ x?, y?, animated? })` | `scroll_to(point, animated)` | `ScrollRef`, `ListRef` | Scrolls to an offset. |
| `zoomTo({ scale, x?, y?, animated? })` | `zoom_to(scale, center, animated)` | `ScrollRef` (a zoomable `<Scroll>`) | Zooms to `scale` around a content point. |
| `scrollToOffset({ offset, animated? })` | `scroll_to_offset(offset, animated)` | `ListRef` | Scrolls to an offset along the list's axis. |
| `scrollToIndex({ index, animated?, viewPosition?, viewOffset? })` | `scroll_to_index(index, position, offset, animated)` | `ListRef` | Scrolls an item into view. |
| `scrollToEnd({ animated? })` | `scroll_to_end(animated)` | `ScrollRef`, `ListRef` | Scrolls to the end of the content. |
| `reload()`, `goBack()`, `goForward()`, `stopLoading()`, `injectJavaScript(script)`, `postMessage(data)` | `reload()`, `go_back()`, `go_forward()`, `stop_loading()`, `inject_java_script(..)`, `post_message(..)` | `WebViewRef` | Controls the page. |
| `seek(seconds)` | `seek(seconds)` | `VideoRef` | Jumps to a time. |
| `command(name, args?)` | `command(name, args)` | `NativeComponentRef` | Calls a command of a registered native component ([`nativeComponent`](https://nsh.dev/versions/main/modules/nsh.md#nativecomponent-and-nativemodule)). |

```rust
let field = element_ref();

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

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

## Why handlers never block the UI

The main thread never waits for the app's code. When the system needs an answer on the spot (may this text change, may
the back button pop, may this sheet close), NSH answers it natively from props set beforehand (`maxLength`,
`popOnBack`, `closeOnSwipe`, …), and the event reaches the app afterwards. This is why such behavior
is a prop, not a return value of a handler.

Source: https://nsh.dev/versions/main/elements

---

# View

`View` is the building block of every screen: a native container (a UIView on iOS and Mac Catalyst, a ViewGroup on
Android) that lays out its children with flexbox or grid, draws a background, borders, shadows and gradients, and handles
presses. Buttons, cards, rows and screens are all views. Rust makes one with `view()`, TSX with `<View>` from `nsh`.

```rust
use nsh_core::prelude::*;

fn app() -> impl IntoElement {
    let liked = signal(false);
    view()
        .flex_1()
        .p_6()
        .gap_4()
        .bg(rgb(0xf6f8fa))
        .child(
            view()
                .flex_row()
                .items_center()
                .gap_3()
                .p_4()
                .rounded(px(16.0))
                .bg(white())
                .shadow_md()
                .child(view().size(px(40.0)).rounded_full().bg(rgb(0x8250df)))
                .child(text("A card").flex_1().text_base())
                .child(
                    view()
                        .hit_slop(EdgeInsets::all(px(8.0)))
                        .active(|s| s.opacity(0.5))
                        .on_press(move || liked.update(|l| *l = !*l))
                        .child(text(move || if liked.get() { "♥" } else { "♡" }).text_size(px(22.0))),
                ),
        )
}
```

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

function App() {
  const liked = signal(false);
  return (
    <View style={{ flex: 1, padding: 24, gap: 16, backgroundColor: "#f6f8fa" }}>
      <View
        style={{
          backgroundColor: "#ffffff",
          borderRadius: 16,
          padding: 16,
          boxShadow: "0 4px 12px rgba(0, 0, 0, 0.08)",
          flexDirection: "row",
          alignItems: "center",
          gap: 12,
        }}
      >
        <View style={{ width: 40, height: 40, borderRadius: 20, backgroundColor: "#8250df" }} />
        <Text style={{ flex: 1, fontSize: 16 }}>A card</Text>
        <View onPress={() => liked.set(!liked())} activeStyle={{ opacity: 0.5 }} hitSlop={8}>
          <Text style={{ fontSize: 22 }}>{liked() ? "♥" : "♡"}</Text>
        </View>
      </View>
    </View>
  );
}

mount(App);
```

## Layout

A view lays out its children with flexbox, with these defaults: `flexDirection: "column"`, `flexShrink: 0`,
`alignContent: "flex-start"`, `position: "relative"`. `display: "grid"` (`.grid()` in Rust) switches to CSS grid and
`display: "block"` to block layout. Sizes are in points. See [layout](https://nsh.dev/versions/main/docs/layout.md) and the
[style reference](https://nsh.dev/versions/main/modules/style-reference.md).

`display: "flex"` follows CSS: in a style, as the `flex` class and Rust's `.flex()`, it is a row unless a direction is
set (`flexDirection: "column"`, `flex-col`, `.flex_col()`). A view that sets no display stacks its children in a column.

## Props

`View` has one prop of its own, `selectable` (`.selectable(true)` in Rust): the texts inside the view select together, as one selection ([Text selection](https://nsh.dev/versions/main/elements/text-selection.md)). The rest are the [common props](https://nsh.dev/versions/main/elements.md#common-props): its styles (`style`, `class`,
`classList`; the `Styled` methods in Rust), `disabled`, the press props (`onPress`, `onLongPress`, `onPressDown`,
`onPressUp`, `delayLongPress`, `hitSlop`), the state styles (`activeStyle`, `hoverStyle`,
`focusStyle`, `disabledStyle`, `checkedStyle`), `onMouseEnter` / `onMouseMove` / `onMouseLeave`, `onContextMenu`,
`onFileDragEnter` / `onFileDragLeave` / `onFileDrop`, `focusable`, `onLayout`, `ref`, `nativeID`, `testID`, the
gesture props (`pan`, `pinch`, `rotation` and their events), the touch and responder props, the accessibility props
and `ios` / `android` / `desktop`.

## Selectable views

With `selectable`, a selection runs across the [`Text`](https://nsh.dev/versions/main/elements/text.md) elements and [`TextView`](https://nsh.dev/versions/main/elements/text-view.md)s inside
the view, in reading order; texts with `selectable={false}` stay out, and a selectable view inside another is part of
the outer one. See [Text selection](https://nsh.dev/versions/main/elements/text-selection.md) for the gestures on each platform.

```tsx
<View selectable class="gap-3 p-4">
  <Text>One selection runs from here…</Text>
  <Text>…to here.</Text>
</View>
```

## Press feedback

A pressable view is any view with a press handler. Its feedback is the app's: a style while pressed, applied natively
while the finger is down, with no round trip to the app's code. `hoverStyle`, `focusStyle` and `disabledStyle` do the
same for the other states:

```rust
// Fade the whole view.
view().on_press(open).active(|s| s.opacity(0.6))

// Show a background; group_active styles the children.
view()
    .group()
    .on_press(open)
    .active(|s| s.bg(rgb(0xe5e7eb)))
    .child(text("Open").group_active(|s| s.opacity(0.7)))

// Change any style while pressed.
view().on_press(open).bg(rgb(0x2563eb)).active(|s| s.bg(rgb(0x1e40af)).scale(0.95))
```

```tsx
// Fade the whole view.
<View onPress={open} activeStyle={{ opacity: 0.6 }}>…</View>

// Show a background; group-active: styles the children.
<View onPress={open} class="group" activeStyle={{ backgroundColor: "#e5e7eb" }}>
  <Text class="group-active:opacity-70">Open</Text>
</View>

// Change any style while pressed with active: classes.
<View onPress={open} class="bg-blue-600 active:bg-blue-800 active:scale-95">…</View>
```

On Android, `android={{ ripple: { color: "#0000001f" } }}` (`.ripple(Ripple { .. })` in Rust) adds the material
ripple (`borderless`, `radius` and `foreground` adjust it).

`disabled` removes the press listeners from the native view (no press, no feedback) and applies the disabled styles:

```rust
view()
    .on_press(submit)
    .disabled(move || !valid.get())
    .bg(rgb(0x16a34a))
    .disabled_style(|s| s.opacity(0.4))
```

```tsx
<View onPress={submit} disabled={!valid()} class="bg-green-600 disabled:opacity-40">…</View>
```

## Events

| Event | Rust | Payload | When |
|---|---|---|---|
| `onPress` | `.on_press` | `PressEvent` (none in Rust) | A tap ended inside the view. |
| `onLongPress` | `.on_long_press` | `PressEvent` (none in Rust) | The finger stayed down for `delayLongPress` (500 ms). |
| `onPressDown` / `onPressUp` | `.on_press_down` / `.on_press_up` | `PressEvent` (none in Rust) | A finger went down / lifted or left. |
| `onMouseEnter` / `onMouseLeave` | `.on_mouse_enter` / `.on_mouse_leave` | `MouseEvent` | The mouse came over the view (or a view inside it) / left it or the window ([hover](https://nsh.dev/versions/main/elements.md#hover)); `onMouseLeave`'s is where it was last. |
| `onMouseMove` | `.on_mouse_move` | `MouseEvent` | The mouse moved over the view (or a view inside it), with or without a button down, or a modifier key was pressed or released while it rests there with none down: `position`, `pagePosition` (`Point`s), `modifiers` and `pressedButton` (`"left"`, `"right"`, `"middle"`, `"back"`, `"forward"` or `null`); at most once a frame. |
| `onContextMenu` | `.on_context_menu` | `ContextMenuEvent` | The secondary button was pressed over the view ([context menus](https://nsh.dev/versions/main/elements.md#context-menus)). |
| `onFileDragEnter` / `onFileDragLeave` | `.on_file_drag_enter` / `.on_file_drag_leave` | none | A local-file drag entered / left the active desktop destination. |
| `onFileDrop` | `.on_file_drop` | `{ uris: string[] }` (`FileDropEvent`) | Local files or directories were dropped on the desktop destination. |
| `onLayout` | `.on_layout` | `{ bounds }` (`Bounds<Points>`) | The frame relative to the parent changed. |
| `onPanStart` / `onPanEnd` | `.on_pan_start` / `.on_pan_end` | `PanEvent` | A drag bound with `pan` started / ended; `cancelled` is true when the system cancels it. |
| `onPinchStart` / `onPinchEnd` | `.on_pinch_start` / `.on_pinch_end` | `{ scale, velocity }` | A pinch bound with `pinch` started / ended. |
| `onRotationStart` / `onRotationEnd` | `.on_rotation_start` / `.on_rotation_end` | `{ rotation, velocity }` | A rotation bound with `rotation` started / ended. |
| `onAccessibilityAction` | `.on_accessibility_action` | `{ actionName }` | A custom accessibility action ran. |

Touch and responder events: see [common props](https://nsh.dev/versions/main/elements.md#raw-touches-and-the-responder-system).

## Desktop file drops

On AppKit, GTK, Win32 and GPUI, a view with `onFileDrop` receives local files and directories dragged from another
application. `onFileDragEnter` and `onFileDragLeave` track the active destination; `onFileDrop` receives
`{ uris: string[] }` in the native file-list order. Each entry is an absolute `file:` URL with escaped spaces and
non-ASCII characters. Parse the URL to obtain a filesystem path rather than removing the prefix by hand.

```rust
let hovering = signal(false);
let files = signal(Vec::<String>::new());

view()
    .min_h(px(160.0))
    .p_6()
    .on_file_drag_enter(move || hovering.set(true))
    .on_file_drag_leave(move || hovering.set(false))
    .on_file_drop(move |event: &FileDropEvent| {
        files.set(event.uris.clone());
        hovering.set(false);
    })
    .child(text(move || if hovering.get() { "Release files here" } else { "Drop files here" }))
    .child(text(move || files.get().join("\n")))
```

```tsx
const hovering = signal(false);
const files = signal<string[]>([]);

<View
  onFileDragEnter={() => hovering.set(true)}
  onFileDragLeave={() => hovering.set(false)}
  onFileDrop={(event) => {
    files.set(event.uris);
    hovering.set(false);
  }}
  style={{ minHeight: 160, padding: 24 }}
>
  <Text>{hovering() ? "Release files here" : "Drop files here"}</Text>
  <Text>{files().join("\n")}</Text>
</View>
```

The closest enabled ancestor listening to `onFileDrop` receives the drop. A modal root bounds that search. `disabled`
removes file-drag/drop listeners; leaving, cancellation, completion and destination removal clear the active state.
Acceptance uses the Copy operation and mounted native state. The app decides whether to read, open or transfer the
received files.

## Ref methods

A plain view's ref is a `ViewRef`: `focus()`, `blur()` and `measure()`. `ref` (`.element_ref(&handle)` in Rust) gives you its node, e.g. to pass to
`setAccessibilityFocus` ([`nsh`'s accessibility API](https://nsh.dev/versions/main/modules/nsh.md#accessibility)), or to measure it
(`handle.measure()` in Rust).

## Views inside text

A view placed inside a text is an inline attachment: it sits on the baseline and wraps with the words, and it takes
presses of its own. See [text](https://nsh.dev/versions/main/elements/text.md#inline-views-and-images).

## Platform notes

- `boxShadow` draws on every platform; `android={{ elevation }}` gives Android's material shadow instead. On Android a shadow needs a
  background color (a view with a transparent background casts none).
- `filter` on views: iOS supports `opacity()`, `brightness()` up to 1 and `drop-shadow()` (images take every color
  filter and `blur()`); Android supports them all from API 31, and the color filters below it.
- `backdropFilter: "blur(…)"` is a system material on iOS (an approximation) and needs API 31 on Android.
- Android draws `translate`, `scale` and `rotate` transforms; skews (`skew()`, `skewX()`, `skewY()`) apply on the other platforms.
- `borderCurve: "continuous"` (`.border_curve(BorderCurve::Continuous)`) draws corners that ease into the edges (as
  iOS app icons), on both platforms.
- The `cursor` style applies where there is a pointer (Mac Catalyst, iPad with a pointer, desktops).

Source: https://nsh.dev/versions/main/elements/view

---

# Text

`Text` draws a paragraph. It is the element that shows strings: a string child of a `View` draws nothing. The
paragraph is typeset natively (CoreText on iOS and Mac Catalyst, `StaticLayout` on Android) and measured on the engine
thread, so the main thread only draws it. Rust makes one with `text(content)`, TSX with `<Text>` from `nsh`.

```rust
use nsh_core::prelude::*;

text("Read the ")
    .text_base()
    .line_height(px(24.0))
    .text_color(rgb(0x1f2328))
    .child(text("terms").font_weight(FontWeight::BOLD))
    .child(" before you continue.")
```

```tsx
<Text style={{ fontSize: 16, lineHeight: 24, color: "#1f2328" }}>
  Read the <Text style={{ fontWeight: "700" }}>terms</Text> before you continue.
</Text>
```

`text(..)` takes a string, a `SharedString`, a signal or a closure (`text(move || format!("{} items", count.get()))`):
a closure or a signal updates the text in place when what it reads changes.

## Spans

A text inside a text is a span of the same paragraph, not a separate view. Spans inherit the text styles of the
paragraph (`color`, `fontSize`, `fontWeight`, …) and override what they set. The whole block is one native view. In
Rust, `text(..)` shows its content and then its children: `.child(text(..))` adds a span, `.child("…")` a plain run.

```rust
text("")
    .text_size(px(17.0))
    .child(text("Light ").font_weight(FontWeight::LIGHT))
    .child(text("Bold ").font_weight(FontWeight::BOLD))
    .child(text("Italic").italic().text_color(rgb(0x8250df)))
```

```tsx
<Text style={{ fontSize: 17 }}>
  <Text style={{ fontWeight: "300" }}>Light </Text>
  <Text style={{ fontWeight: "bold" }}>Bold </Text>
  <Text style={{ fontStyle: "italic", color: "#8250df" }}>Italic</Text>
</Text>
```

### Span backgrounds

A span with a background fills the box of its characters, behind them: as tall as its font (the ascent above the
baseline and the descent below it, whatever the line height), and on every line it wraps to, each line's part a box of
its own with the span's corner radius. Spans inside it share its background unless they set their own. It is drawing
only: the text lays out as without it, and a selectable text copies the span's characters with the rest. Inline code
is a span:

```rust
text("Run ")
    .text_size(px(15.0))
    .line_height(px(22.0))
    .select_text()
    .child(
        text(" cargo test ")
            .font_family("ui-monospace")
            .text_size(px(13.0))
            .bg(rgb(0xeff1f3))
            .rounded(px(4.0)),
    )
    .child(" before you commit.")
```

```tsx
<Text style={{ userSelect: "text", fontSize: 15, lineHeight: 22 }}>
  {"Run "}
  <Text style={{ fontFamily: "ui-monospace", fontSize: 13, backgroundColor: "#eff1f3", borderRadius: 4 }}>
    {" cargo test "}
  </Text>
  {" before you commit."}
</Text>
```

The Tailwind classes work the same way: `<Text class="bg-gray-100 rounded">`. Padding and borders are box styles and
leave spans as they are; spaces inside the span give the box room on its sides.

### Links

A span with a press handler is a link: a press on its characters goes to the span, a press elsewhere to the paragraph.
In a terminal each link is also a stop of the keyboard focus: Tab reaches the links of a paragraph in turn, and Return
presses the focused one.

```rust
text("By continuing you agree to the ")
    .text_size(px(15.0))
    .on_press(move || log("the sentence"))
    .child(
        text("Terms of service")
            .text_color(rgb(0x0969da))
            .underline()
            .on_press(move || open("terms")),
    )
    .child(".")
```

```tsx
<Text style={{ fontSize: 15 }} onPress={() => log("the sentence")}>
  {"By continuing you agree to the "}
  <Text style={{ color: "#0969da", textDecorationLine: "underline" }} onPress={() => open("terms")}>
    Terms of service
  </Text>
  .
</Text>
```

### Inline views and images

Any other element inside a text (a view, an image, even inside spans) is an inline attachment: it is laid out at its
own size, sits on the baseline (or where its `verticalAlign` style puts it: `"text-top"`, `"text-bottom"`,
`"middle"`, as in CSS; the line grows to hold it) and wraps with the words. It takes presses of its own.

```rust
text("Made with ")
    .text_base()
    .line_height(px(26.0))
    .child(image(LOGO).size(px(18.0)).rounded(px(4.0)))
    .child(" NSH. Status ")
    .child(
        view()
            .bg(rgb(0x1a7f37))
            .rounded(px(9.0))
            .px(px(7.0))
            .h(px(18.0))
            .justify_center()
            .child(text("LIVE").text_color(white()).text_size(px(11.0)).font_weight(FontWeight::BOLD)),
    )
```

```tsx
<Text style={{ fontSize: 16, lineHeight: 26 }}>
  {"Made with "}
  <Image src={logo} style={{ width: 18, height: 18, borderRadius: 4 }} />
  {" NSH. Status "}
  <View style={{ backgroundColor: "#1a7f37", borderRadius: 9, paddingHorizontal: 7, height: 18, justifyContent: "center" }}>
    <Text style={{ color: "#ffffff", fontSize: 11, fontWeight: "700" }}>LIVE</Text>
  </View>
</Text>
```

Attachments cut off by `numberOfLines` or an ellipsis are hidden. Copying a selectable text leaves them out.

### Whitespace

JSX text follows React's rules: lines are trimmed except at the text's ends, whitespace-only lines are dropped and the
remaining lines are joined with one space. Spaces on one line are kept (`{a} {b}` keeps its space). Write
`{" "}` or a string expression when a span needs a leading or trailing space. Rust strings are drawn as written.

## Props

Besides the [common props](https://nsh.dev/versions/main/elements.md#common-props) (with `style` typed as `TextStyle`):

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `numberOfLines` (style) | `.number_of_lines(n)`, `.truncate()` | `number` | `0` | The most lines shown; `0` shows them all. |
| `textOverflow` (style) | `.text_overflow(EllipsizeMode::Middle)` | `"ellipsis" \| "clip" \| "ellipsis-start" \| "ellipsis-middle"` | `"ellipsis"` | How text that does not fit `numberOfLines` is cut: an ellipsis at its end, at its start or in its middle, or clipped. |
| `allowFontScaling` | `.allow_font_scaling(..)` | `boolean` | `true` | Follow the system text size setting. |
| `maxFontSizeMultiplier` | `.max_font_size_multiplier(..)` | `number` | `0` | The upper bound of the system scale; `0` is none. |
| `adjustsFontSizeToFit` | `.shrink_to_fit(min_scale)` | `boolean` | `false` | Shrink the font until the text fits its lines (`numberOfLines`) and its box. |
| `minimumFontScale` | `.shrink_to_fit(min_scale)` | `number` | | How far `adjustsFontSizeToFit` shrinks at most (0..1; at least 0.1). |
| `userSelect` (style) | `.select_text()`, `.select_none()` | `"auto" \| "none" \| "text"` | `"auto"` | `"text"`: the user can select ranges of the text: a long press selects a word, handles extend it, the edit menu copies it. `"auto"` takes the setting of the views around the text; with none set, text is not selectable, except in desktop browsers, where it is unless it is inside an interactive element; `"none"` keeps it unselectable there too. |
| `selectionColor` (style) | `.selection_color(..)` | `ColorValue` | the platform's accent | The selection's highlight and handles. |
| `onTextLayout` | | `(e: { lines: TextLayoutLine[] }) => void` | | The laid-out lines after each layout. |

The Tailwind classes `select-text`, `select-none` and `select-auto` set `userSelect`, `line-clamp-*` sets `numberOfLines`, `text-ellipsis` and `text-clip` set `textOverflow`, and `truncate` is one line cut with an ellipsis. The selection's highlight and handles take the style key
`selectionColor` (`selection:text-*`), the platform's accent by default.

## Text styles

`TextStyle` adds to the view styles: `color`, `fontSize`, `fontWeight` (`"normal"`, `"bold"` or 100–900), `fontStyle`,
`fontFamily`, `lineHeight`, `letterSpacing`, `textAlign`, `textAlignVertical`, `textTransform`, `textDecorationLine`,
`textDecorationColor`, `textDecorationStyle`, `textDecorationThickness`, `textUnderlineOffset`, `textShadow` (CSS's
`text-shadow`), `fontVariant`, `writingDirection`, `numberOfLines` and `textOverflow`. In Rust they are `Styled` methods:
`.text_color(..)`, `.text_size(..)` (or `.text_sm()`, `.text_lg()`, …), `.font_weight(FontWeight::SEMIBOLD)`,
`.italic()`, `.font_family(..)`, `.line_height(..)`, `.letter_spacing(..)`, `.text_center()`, `.uppercase()`,
`.underline()`, `.line_through()`, `.tabular_nums()`, `.number_of_lines(..)` and the rest. See the
[style reference](https://nsh.dev/versions/main/modules/style-reference.md#textstyle) and [text](https://nsh.dev/versions/main/docs/text.md).

The font family is a system family or a font file of the app:

```rust
// assets/fonts/Inter-Regular.ttf, shipped by the registry (`registry.assets(assets!())`).
const INTER: FontAsset = asset!("fonts/Inter-Regular.ttf");

text("Inter").font_family(INTER.family).text_size(px(17.0))
```

```tsx
import { Text } from "nsh";
import Inter from "./fonts/Inter-Regular.ttf";

<Text style={{ fontFamily: Inter, fontSize: 17 }}>Inter</Text>;
```

The font is registered before the first frame. See [fonts](https://nsh.dev/versions/main/docs/fonts.md).

## Events

| Event | Rust | Payload | When |
|---|---|---|---|
| `onTextLayout` | | `{ lines: TextLayoutLine[] }` | After each layout of the paragraph. |
| `onPress`, `onLongPress`, … | `.on_press`, `.on_long_press`, … | `PressEvent` (none in Rust) | As on [view](https://nsh.dev/versions/main/elements/view.md#events); on a span, presses on its characters. |
| `onLayout` | `.on_layout` | `{ bounds }` | The block's frame changed. |

`TextLayoutLine` is `{ text, x, y, width, height, ascender, descender, capHeight, xHeight }`, in the text's content box:

```tsx
const lines = signal(0);
<Text onTextLayout={(e) => lines.set(e.lines.length)}>{article}</Text>;
```

Rust measures a string before it lays out with `measure_text(..)`.

## Ref methods

None of its own.

## Platform notes

- Selection stays inside one text block (one text and its spans). iOS shows its edit menu (Copy, Select All, Look Up,
  Translate, Share), Android a floating toolbar (Copy, Select all, Share).
- Text decorations other than a solid single line (`double`, `dotted`, `dashed`, `wavy`) are drawn by NSH on iOS.
- iOS texts draw solid backgrounds and outer shadows.
- `fontScale()` from [`nsh`](https://nsh.dev/versions/main/modules/nsh.md#device) (`font_scale()` in Rust) reports the current system text
  scale.

Source: https://nsh.dev/versions/main/elements/text

---

# Image

`Image` shows a picture from the app's assets or from a URL. Images are downloaded and decoded off the main thread,
downsampled to the size the view shows them at, and cached in memory. Animated GIF, WebP and APNG images play. Rust
makes one with `image(src)`, TSX with `<Image>` from `nsh`.

```rust
use nsh_core::prelude::*;

// assets/logo.png in the app's crate.
const LOGO: ImageAsset = asset!("logo.png");

view()
    .flex_row()
    .gap_3()
    .child(image(LOGO))
    .child(
        image("https://example.com/avatar.jpg")
            .placeholder(LOGO)
            .object_fit(ResizeMode::Cover)
            .size(px(64.0))
            .rounded_full(),
    )
```

```tsx
import { Image, View } from "nsh";
import logo from "./assets/logo.png";

<View style={{ flexDirection: "row", gap: 12 }}>
  <Image src={logo} />
  <Image
    src="https://example.com/avatar.jpg"
    placeholder={logo}
    style={{ width: 64, height: 64, borderRadius: 32 }}
  />
</View>;
```

An asset knows its size: without a width or height the image takes it, and with one of them the other follows the
asset's aspect ratio. A URL's size is known once it loads, so give remote images a width and a height (or an aspect
ratio with one of them).

## Sources

The source (`src` and `placeholder`; `image(..)` and `.placeholder(..)` in Rust) takes:

| Value | Example | Description |
|---|---|---|
| An asset | Rust `asset!("logo.png")`, TSX `import logo from "./logo.png"` | An `ImageAsset` `{ url, size, scales? }`, sized in points: a `@2x` file counts half its pixels. With `logo@2x.png` / `logo@3x.png` next to `logo.png`, the variant for the screen's pixel ratio is loaded ([pixel densities](https://nsh.dev/versions/main/docs/images-and-assets.md#pixel-densities)). `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp` and `.heic` can be imported, and `.svg`, sized by its `width` and `height` or `viewBox` ([SVG images](https://nsh.dev/versions/main/docs/images-and-assets.md#svg-images)). |
| A URL | `"https://example.com/a.jpg"` | Downloaded and cached. Downloads of the same URL are shared between views. |
| An asset path | `"asset:/images/a.png"` | A file of the app's assets. |
| A `data:` URI | `"data:image/png;base64,iVBOR…"` | Bytes in the URI, base64 or percent-encoded (`data:image/svg+xml,%3Csvg…`). |
| A `blob:` URL | `URL.createObjectURL(blob)` | The bytes of a `Blob` or `File` (TSX). The image keeps them: revoking the URL leaves an image that shows it whole. |

An image from bytes the app already has shows without a request. A chat shows a picked photo from its blob while it
uploads, then switches `src` to the photo's URL:

```rust
// Bytes in a `data:` URI (an image the app made or received inline).
image(format!("data:image/png;base64,{encoded}")).size(px(64.0))
```

```tsx
import { Image, signal } from "nsh";

const preview = URL.createObjectURL(photo); // the picked `File`
const src = signal(preview);
upload(photo).then((url) => {
  src.set(url);
  URL.revokeObjectURL(preview);
});

<Image src={src()} style={{ width: 240, height: 180 }} />;
```

Equal bytes are one image: the same picture as a `data:` URI and as a blob is decoded once and shares the cache.

During development assets are served by the dev server; `nsh build` and `nsh package` copy them into the app (a Rust
crate ships its `assets/` directory with `registry.assets(assets!())`). See
[images and assets](https://nsh.dev/versions/main/docs/images-and-assets.md).

> [!NOTE]
> When the app declares [capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md), remote images load from the hosts it
> lists; an image from any other host is not requested and fails with `onError`, whose `code` is `"ERR_ACCESS_DENIED"`. `asset:` URIs, `data:` URIs and `blob:` URLs always load.

## Props

Besides the [common props](https://nsh.dev/versions/main/elements.md#common-props) (with `style` typed as `ImageStyle`):

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `src` | `image(src)` | `string \| ImageAsset` | | The image. |
| `placeholder` | `.placeholder(src)` | `string \| ImageAsset` | | Shown until `src` has loaded; best a local asset. |
| `blurRadius` | `.blur_radius(px(..))` | `number` | | Blurs the image by this radius in points (applied once while decoding, off the main thread). |
| `fadeDuration` | `.fade_duration(ms)` | `number` | iOS `0`, Android `300` | How long a loaded image fades in, in milliseconds. |
| `tintColor` (style) | `.tint_color(..)` | `ColorValue` | | Recolors a template image (an icon drawn in one color). |
| `objectFit` (style) | `.object_fit(ResizeMode::Contain)` | `"cover" \| "contain" \| "fill" \| "none" \| "scale-down"` | `"cover"` | How the image fits its box, as CSS's `object-fit` (`object-*` classes): `"cover"` fills it and crops, `"contain"` fits inside it, `"fill"` stretches, `"none"` shows it at its natural size, `"scale-down"` the same, shrunk to fit where it is larger. |
| `objectPosition` (style) | `.object_position(..)`, `.object_top()`, ... | `string` | `"center"` | Where the image sits in its box once `objectFit` has sized it, as CSS's `object-position` (`"top"`, `"25% 75%"`, `"right 10px bottom 20%"`); a covering image is cropped around it. |
| `onLoadStart` | `.on_load_start(..)` | `() => void` | | Loading began. |
| `onProgress` | `.on_progress(..)` | `(e: { loaded: number; total: number }) => void` | | Download progress in bytes (`total` is 0 when unknown), at most every 100 ms. |
| `onLoad` | `.on_load(..)` | `(e: { size: PixelSize }) => void` | | Loaded; the source image's size in pixels (not the decoded, downsampled one; an SVG's size in points, [on the web as the browser measures it](https://nsh.dev/versions/main/docs/images-and-assets.md#svg-images)); for an image with variants, the loaded variant's. |
| `onError` | `.on_error(..)` | `(e: { message: string; code?: string }) => void` | | Loading failed; `code` is `"ERR_ACCESS_DENIED"` for a URL the app's capabilities do not grant. |
| `onLoadEnd` | `.on_load_end(..)` | `() => void` | | After `onLoad` or `onError`. |

`ImageStyle` adds `tintColor` to the view styles, which recolors a template image (an icon drawn in one color), and `objectPosition`, which places the image in its box ([Image position](https://nsh.dev/versions/main/docs/images-and-assets.md#image-position)).

```rust
image(ICON).size(px(24.0)).tint_color(rgb(0x0969da))
```

```tsx
<Image src={icon} style={{ width: 24, height: 24, tintColor: "#0969da" }} />
```

## Events

| Event | Rust | Payload | When |
|---|---|---|---|
| `onLoadStart` | `.on_load_start` | none | Loading began. |
| `onProgress` | `.on_progress` | `{ loaded, total }` (`ImageProgress`) | Bytes arrived (at most every 100 ms). |
| `onLoad` | `.on_load` | `{ size }` (`Size<DevicePixels>`) | The image is shown; its source size in pixels (an SVG's in points, [on the web as the browser measures it](https://nsh.dev/versions/main/docs/images-and-assets.md#svg-images)). |
| `onError` | `.on_error` | `{ message, code? }` (`&str`, the message) | Loading or decoding failed, or the host is outside the app's capabilities (`code` `"ERR_ACCESS_DENIED"`). |
| `onLoadEnd` | `.on_load_end` | none | After `onLoad` or `onError`. |

```rust
let state = signal(SharedString::from("loading"));

image(url)
    .w_full()
    .aspect_ratio(16.0 / 9.0)
    .on_load(move |size: &Size<DevicePixels>| state.set(format!("{}×{}", size.width.0, size.height.0).into()))
    .on_error(move |message: &str| state.set(message.to_string().into()))
```

```tsx
const state = signal("loading");
<Image
  src={url}
  style={{ width: "100%", aspectRatio: 16 / 9 }}
  onLoad={({ size }) => state.set(`${size.width}×${size.height} px`)}
  onError={(e) => state.set(e.message)}
/>;
```

An image with [pixel-density variants](https://nsh.dev/versions/main/docs/images-and-assets.md#pixel-densities) loads one of its files, and
`onLoad` reports that file's pixels: 192×192 for `logo@3x.png` on a 3× screen, for a 64×64 point `logo.png`. When the
pixel ratio changes and the image loads another variant, it reports that load too: `onLoadStart`, then `onLoad` with the
new file's size (or `onError`), then `onLoadEnd`.

To know an image's size or load it before showing it, TSX calls `Image.getSize(src)` and `Image.prefetch(src)` (the
same `Image` that renders the element carries them; see the [Image API](https://nsh.dev/versions/main/modules/nsh-image.md)), and Rust
`image_size(src)` and `prefetch_image(src)`, awaited in a task. Given an imported image with variants, `Image.getSize`
and `Image.prefetch` load the variant this screen shows, and `getSize` resolves with the imported file's size (64×64
for `logo.png`).

## Ref methods

None of its own.

## Platform notes

- The cache key includes the decode size and the blur radius: the same URL shown at two sizes is decoded twice but
  downloaded once.
- iOS plays animated images as a keyframe animation (up to 600 frames); a tinted animated image shows its first frame.
- Android plays animated images from API 28 (`AnimatedImageDrawable`), uncached and unblurred.
- On Android borders are drawn above the image, as on iOS.

Source: https://nsh.dev/versions/main/elements/image

---

# Scroll

`Scroll` is a native scroll view (UIScrollView on iOS and Mac Catalyst, a ScrollView on Android). It lays out all its
children as its content and scrolls them natively: scrolling, flinging, bouncing and snapping run on the platform, at
the display's rate. Rust makes one with `scroll()`, TSX with `<Scroll>` from `nsh`.

```rust
use nsh_core::prelude::*;

scroll().flex_1().child(
    view().p_4().gap_2().child(each(
        rows,
        |row: &Row| row.id,
        |row, _index| text(move || row.get().title),
    )),
)
```

```tsx
<Scroll style={{ flex: 1 }}>
  <View style={{ padding: 16, gap: 8 }}>
    <Each of={rows}>{(row) => <Text>{row().title}</Text>}</Each>
  </View>
</Scroll>
```

A scroll view creates every child, which suits pages of moderate size. For long or unbounded data use a
[list](https://nsh.dev/versions/main/elements/list.md): it creates the rows near the viewport and recycles them.

A scroll view needs a bounded size along its axis: give it `flex: 1` (`.flex_1()`) or a height inside a container that
has one. Its content is laid out at the scroll view's width (height when horizontal) and as tall (wide) as it needs.

## Props

Besides the [common props](https://nsh.dev/versions/main/elements.md#common-props) (with `style` typed as `ViewStyle`). In Rust, the scrolling props
are methods of the `Scrollable` trait, which lists share.

### Scrolling

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `horizontal` | `.horizontal()` | `boolean` | `false` | Scrolls sideways. |
| `scrollable` | `.scrollable(..)` | `boolean` | `true` | The user can scroll it. |
| `scrollbar` | `.scrollbar(..)` | `boolean \| ScrollbarTheme` | `true` | The scroll indicator shows: the platform's, or the app's [built-in bar](https://nsh.dev/versions/main/elements/scrollbar.md#built-in-bars) once it set a theme; an object is a theme of the view's own. On the desktop and in desktop browsers a horizontal view keeps it: it is the mouse's scroll bar. |
| `bounces` | `.bounces(..)` | `boolean` | `true` | Overscroll past the edges. |
| `pagingEnabled` | `.paging(..)` | `boolean` | `false` | Stops at multiples of the viewport. |
| `snapToInterval` | `.snap_interval(px(..))` | `number` | `0` | Stops at multiples of this length (0: off). |
| `snapToOffsets` | `.snap_offsets(..)` | `number[]` | | Stops at these offsets. |
| `snapToAlignment` | `.snap_alignment(SnapAlignment::Center)` | `"start" \| "center" \| "end"` | `"start"` | Which point of an item aligns with the viewport with `snapToInterval`. |
| `disableIntervalMomentum` | `.disable_interval_momentum(..)` | `boolean` | `false` | A fling moves one snap point at most. |
| `decelerationRate` | `.deceleration(rate)` | `"normal" \| "fast" \| number` | platform | How fast a fling slows down: the velocity kept per millisecond (`normal` 0.998, `fast` 0.99). |
| `contentInset` | `.content_inset(EdgeInsets { .. })` | `Partial<Edges>` | | Room around the content. |
| `contentOffset` | `.content_offset(point(..))` | `{ x?, y? }` | | Where it starts. |
| `contentStyle` | the content view's own styles | `ViewStyle` | | The style of a view around the children that scrolls with them; `flexGrow: 1` makes it at least as tall as the viewport (a centered empty state). |
| `contentClass` | the content view's own styles | `string` | | The same as classes, e.g. `"grow justify-center p-4"`. |
| `keyboardDismissMode` | `.keyboard_dismiss_mode(KeyboardDismissMode::OnDrag)` | `"none" \| "on-drag" \| "interactive"` | `"none"` | Whether dragging dismisses the keyboard. |
| `keyboardShouldPersistTaps` | `.keyboard_taps(KeyboardTaps::Handled)` | `"never" \| "always" \| "handled" \| boolean` | `"never"` | Whether a tap dismisses the keyboard: `never` (the tap only dismisses it), `always` (it stays up), `handled` (it stays up when something handles the tap). |
| `scrollValue` | `.scroll_value(&value)` | `AnimatedValue` | | An animated value fed with the scroll offset (main axis), for scroll-linked animations. |
| `scrollEventThrottle` | `.event_throttle(ms)` | `number` | | Minimum milliseconds between `onScroll` events (at most one per frame anyway). |

### Pull to refresh

| Prop | Rust | Type | Description |
|---|---|---|---|
| `refreshing` | `.refreshing(..)` | `boolean` | The refresh spinner shows. |
| `onRefresh` | `.on_refresh(..)` | `() => void` | The user pulled to refresh: start loading and set `refreshing` until it ends. |
| `refreshIndicator` | `.refresh_indicator(Some(height))` | `{ height: number }` | The app draws its own indicator, `height` points tall: the platform's spinner is hidden, a pull refreshes once it reaches `height`, and refreshing keeps `height` above the content. A height of 0 or less is none. |
| `pullValue` | `.pull_value(&value)` | `AnimatedValue` | An animated value fed with how far the view is pulled past its top (0 at rest, growing with the pull; the room kept above the content while it refreshes: `height` with `refreshIndicator`), for the app's indicator. |

```rust
let refreshing = signal(false);

scroll()
    .flex_1()
    .refreshing(refreshing)
    .on_refresh(move || {
        refreshing.set(true);
        spawn(async move {
            load().await;
            refreshing.set(false);
        });
    })
    .child(content())
```

```tsx
const refreshing = signal(false);
async function reload() {
  refreshing.set(true);
  await load();
  refreshing.set(false);
}

<Scroll style={{ flex: 1 }} refreshing={refreshing()} onRefresh={reload}>
  …
</Scroll>;
```

### Zooming

Setting `maximumZoomScale` above `minimumZoomScale` (`.zoom_range(min, max)` in Rust) makes the content zoomable with a
pinch; zoomed in, it scrolls both ways. Lists keep their scale.

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `minimumZoomScale` | `.zoom_range(min, max)` | `number` | `1` | The smallest zoom. |
| `maximumZoomScale` | `.zoom_range(min, max)` | `number` | `1` | The largest zoom. |
| `zoomScale` | `.zoom(..)` | `number` | | Zooms to this scale when it changes; otherwise the user's zoom is kept. |
| `bouncesZoom` | `.bounces_zoom(..)` | `boolean` | `true` | Pinching may go past the limits and springs back. |
| `zoomable` | `.zoomable(..)` | `boolean` | `true` | The user can pinch to zoom. |
| `centerContent` | `.center_content(..)` | `boolean` | `false` | Content smaller than the viewport (zoomed out) is centered. |

```rust
let photo = element_ref();

scroll()
    .element_ref(&photo)
    .zoom_range(1.0, 4.0)
    .center_content(true)
    .flex_1()
    .bg(black())
    .child(
        image(PICTURE)
            .w(px(390.0))
            .h(px(520.0))
            .on_press(move || photo.zoom_to(1.0, None, true)),
    )
```

```tsx
let photo!: ScrollRef;
<Scroll ref={photo} maximumZoomScale={4} centerContent style={{ flex: 1, backgroundColor: "#000" }}>
  <Image src={picture} style={{ width: 390, height: 520 }} onPress={() => photo.zoomTo({ scale: 1, animated: true })} />
</Scroll>;
```

## Events

| Event | Rust | Payload | When |
|---|---|---|---|
| `onScroll` | `.on_scroll` | `ScrollEvent` | The offset changed (at most once per frame, and no more often than `scrollEventThrottle`). |
| `onScrollDragStart` / `onScrollDragEnd` | `.on_scroll_drag_start` / `.on_scroll_drag_end` | `{ offset }` (`Point<Points>`) | The user started / stopped dragging. |
| `onMomentumStart` / `onMomentumEnd` | `.on_momentum_start` / `.on_momentum_end` | `{ offset }` | A glide after the drag started / stopped. A glide caught by a new drag still ends with `onMomentumEnd`. |
| `onScrollEnd` | `.on_scroll_end` | `{ offset }` | Scrolling came to rest. |
| `onRefresh` | `.on_refresh` | none | Pulled to refresh. |

`ScrollEvent` is `{ offset: Point; contentSize: Size; size: Size; zoomScale }` (in Rust `offset`, `content_size`,
`size`, `zoom_scale`): the offset, the (zoomed) content size, the viewport size and the zoom scale (1 unless the view
zooms).

> [!TIP]
> To move something with the scroll position (a shrinking header, a parallax image), bind `scrollValue` to a native
> value and interpolate it in a style. It runs on the UI thread at the display's rate, while `onScroll` is an event per
> frame in the app's code. See [animation](https://nsh.dev/versions/main/docs/animation.md).

## Ref methods

| Method | Rust | Description |
|---|---|---|
| `scrollTo({ x?, y?, animated? })` | `scroll_to(point(x, y), animated)` | Scrolls to an offset. |
| `zoomTo({ scale, x?, y?, animated? })` | `zoom_to(scale, Some(point(x, y)), animated)` | Zooms to `scale` (clamped to the limits) with the content point (`x`, `y`, unzoomed points) in the middle of the viewport, or around the middle. E.g. a double tap zooming in on the tapped point. |

```rust
let scroller = element_ref();
scroll().element_ref(&scroller).child(content());

scroller.scroll_to(point(px(0.0), px(0.0)), true);
```

```tsx
let scroller!: ScrollRef;
<Scroll ref={scroller}>…</Scroll>;
scroller.scrollTo({ y: 0, animated: true });
```

## Keyboard

Inputs inside a scroll view are kept clear of the keyboard natively: the scroll view gets a bottom inset and scrolls to
the focused input on its own. For content outside scroll views use [`env(keyboard-inset-height)`](https://nsh.dev/versions/main/elements/keyboard.md)
in a bottom padding or margin. See [forms and the keyboard](https://nsh.dev/versions/main/docs/forms-and-keyboard.md).

## Right to left

Horizontal scroll views start at the right end in right-to-left layouts and keep their distance from it as the content
changes; their children are mirrored.

## Platform notes

- Android: pull to refresh is drawn by NSH (overscroll stays native), `contentInset` is applied as padding, and
  `decelerationRate` shapes snapping glides.
- Android zooms with NSH's own scroll view, which scales the content around its top left and scrolls both ways.
  Pinches start after Android's minimum span between the fingers (about 27 mm).
- On Mac Catalyst (Mac idiom), NSH detects the pull and shows its spinner.
- iOS redraws texts and canvases at the zoomed resolution when a zoom ends.

Source: https://nsh.dev/versions/main/elements/scroll

---

# List

`List` shows long or unbounded data. The rows near the viewport exist: as the user scrolls, rows that leave are
recycled for the rows that come in. Which rows exist, their positions, columns, sticky headers and viewability are all
computed natively, so scrolling a list of thousands of items costs as much as a list of twenty. Rust makes one with
`virtual_list(count, |at| row)`, TSX with `<List>` from `nsh`.

```rust
use nsh_core::prelude::*;

#[derive(Clone, PartialEq)]
struct Contact {
    id: usize,
    name: String,
}

fn app() -> impl IntoElement {
    let contacts = signal(
        (0..1000).map(|i| Contact { id: i, name: format!("Contact {}", i + 1) }).collect::<Vec<_>>(),
    );
    virtual_list(move || contacts.with(|c| c.len()), move |at| {
        view().h(px(56.0)).px_4().justify_center().child(
            text(move || contacts.with(|c| format!("{}. {}", at.index() + 1, c[at.index()].name)))
                .text_base(),
        )
    })
    .estimated_item_size(px(56.0))
    .flex_1()
}
```

```tsx
import { List, mount, Text, View } from "nsh";

const contacts = Array.from({ length: 1000 }, (_, i) => ({ id: i, name: `Contact ${i + 1}` }));

function App() {
  return (
    <List each={contacts} estimatedItemSize={56} style={{ flex: 1 }}>
      {(contact, index) => (
        <View style={{ height: 56, paddingHorizontal: 16, justifyContent: "center" }}>
          <Text style={{ fontSize: 16 }}>
            {index() + 1}. {contact().name}
          </Text>
        </View>
      )}
    </List>
  );
}

mount(App);
```

In TSX, `List` is generic: `List<T>` checks that `each` and the row function agree on the item type, which TypeScript
infers from `each` (see the [List API](https://nsh.dev/versions/main/modules/nsh-list.md)). In Rust, `virtual_list` takes the number of rows (a
value, a signal or a closure: the list grows and shrinks in place) and the function that builds the row at a
`Position`; the rows read the component's data by `at.index()`.

For a short list whose rows should all exist (a settings page, a form), an [`Each`](https://nsh.dev/versions/main/elements/control-flow.md) inside a
[scroll view](https://nsh.dev/versions/main/elements/scroll.md) is simpler. For a list styled as a grouped table, see
[a settings-style list](https://nsh.dev/versions/main/docs/lists.md#a-settings-style-list). The [lists guide](https://nsh.dev/versions/main/docs/lists.md) covers patterns:
infinite loading, chat, sections.

## Rows are recycled

The row function runs once per cell, not once per item. When a cell is reused for another item, its position changes
(TSX: the `item()` and `index()` accessors; Rust: `at.index()`) and everything that reads it updates:

```rust
virtual_list(move || messages.with(|m| m.len()), move |at| {
    text(move || messages.with(|m| m[at.index()].body.clone()))
})
```

```tsx
<List each={messages()}>
  {(message) => <Text>{message().body}</Text>}
</List>
```

So keep per-item state in your data (keyed by id), not in signals created inside the row function: such a signal stays
with the cell and shows up on another item.

Cells waiting for their next item are hidden once their row is gone or shown by another cell, so screen readers,
touches and UI tests meet each row once.

## Props

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `each` | `virtual_list(count, ..)` | `readonly T[]` | | The items. |
| `children` | `virtual_list(.., \|at\| row)` | `(item: () => T, index: () => number) => JSX.Element` | | Renders one row. |
| `estimatedItemSize` | `.estimated_item_size(px(..))` | `number` | `50` | The size of items not measured yet, in points. Close estimates keep the scroll bar steady. |
| `horizontal` | `.horizontal()` | `boolean` | `false` | Scrolls sideways. |
| `viewport` | `.viewport(ListViewport::..)` | `"own" \| "parent"` | `"own"` | `"own"`: the list scrolls in a scroll view of its own. `"parent"`: it lies at its full length in its parent's layout and renders the rows near the viewport of the scroll view around it, which scrolls it with the rest of the page (see [lists in a page](https://nsh.dev/versions/main/docs/lists.md#lists-in-a-page-viewportparent)). Chosen when the list is made. |
| `numColumns` | `.columns(n)` | `number` | `1` | Items per row (vertical lists). |
| `inverted` | `.inverted()` | `boolean` | `false` | Laid out from the end, item 0 last (chat style): starts scrolled to the end and keeps its distance from the end as content changes. |
| `maintainVisibleContentPosition` | `.follow_end(px(threshold))` | `{ autoscrollToBottomThreshold?: number }` | | For lists that are not inverted: at the end of the content, or within that many points of it, the list stays at the end as the content grows or the viewport shrinks; scrolled further up, the visible content stays. |
| `stickyHeaderIndices` | `.sticky_header_indices([..])` | `number[]` | | Items that stick to the start while scrolled past (one column, not inverted). |
| `contentStyle` | `.content_padding(..)`, `.content_padding_x(..)`, `.row_gap(..)`, `.column_gap(..)`, … | `ListContentStyle` | | Padding and gaps of the content, in points: `padding`, `paddingHorizontal`, `paddingVertical`, `paddingTop`, `paddingRight`, `paddingBottom`, `paddingLeft`, `gap`, `rowGap`, `columnGap`. |
| `contentClass` | | `string` | | Padding and gaps of the content as classes (`p-*`, `gap-*`); `contentStyle` wins over them. |
| `header` | `.header(el)` | `ListSlot` | | Before the items: a component (`Header`) or an element (`<Header />`). |
| `footer` | `.footer(el)` | `ListSlot` | | After the items. |
| `empty` | `.empty(el)` | `ListSlot` | | Shown instead of the items while `each` is empty. |
| `separator` | `.separator(\|\| el)` | `ListSlot` | | Between items (one column). |
| `initialScrollIndex` | `.initial_scroll_index(i)` | `number` | | Scrolls to this item before the first frame. |
| `keyExtractor` | `.keys(\|\| ids)` | `(item: T, index: number) => string` | `item.key`, `item.id` or the index | The key of an item in viewability tokens. In Rust, the rows' identities, so rows keep their cells and sizes when rows come and go before them. |
| `onLoadMore` | `.on_load_more(..)` | `() => void` | | The end is near: load more. |
| `loadMoreThreshold` | `.load_more_threshold(viewports)` | `number` | `1` | How close to the end (in viewports) `onLoadMore` fires. |
| `onLoadMoreAtStart` | `.on_load_more_at_start(..)` | `() => void` | | The start is near, after the user or a scroll command moved the list: load what comes before the first item. |
| `loadMoreAtStartThreshold` | `.load_more_at_start_threshold(viewports)` | `number` | `1` | How close to the start (in viewports) `onLoadMoreAtStart` fires. |
| `onViewableItemsChange` | `.on_viewable_items_change(..)` | `(info: { viewableItems: ViewToken<T>[]; changed: ViewToken<T>[] }) => void` | | Items became viewable or stopped being viewable. |
| `viewabilityConfig` | `.viewability(..)`, `.minimum_view_time(..)` | `ViewabilityConfig` | | When items count as viewable (below). |
| `refreshing` | `.refreshing(..)` | `boolean` | | The pull-to-refresh spinner shows. |
| `onRefresh` | `.on_refresh(..)` | `() => void` | | The user pulled to refresh. |
| `refreshIndicator` | `.refresh_indicator(Some(height))` | `{ height: number }` | | The app draws its own indicator, `height` points tall: the platform's spinner is hidden, a pull refreshes once it reaches `height`, and refreshing keeps `height` above the content. A height of 0 or less is none. |
| `pullValue` | `.pull_value(&value)` | `AnimatedValue` | | An animated value fed with how far the list is pulled past its top (0 at rest, growing with the pull; the room kept above the content while it refreshes: `height` with `refreshIndicator`), for the app's indicator. |
| `scrollbar` | `.scrollbar(..)` | `boolean \| ScrollbarTheme` | `true` | The scroll indicator shows: the platform's, or the app's [built-in bar](https://nsh.dev/versions/main/elements/scrollbar.md#built-in-bars) once it set a theme; an object is a theme of the view's own. On the desktop and in desktop browsers a horizontal view keeps it: it is the mouse's scroll bar. |
| `scrollValue` | `.scroll_value(&value)` | `AnimatedValue` | | An animated value fed with the scroll offset, for scroll-linked animations. |
| `keyboardDismissMode` | `.keyboard_dismiss_mode(..)` | `"none" \| "on-drag" \| "interactive"` | `"none"` | Whether dragging dismisses the keyboard. |
| `style` | `Styled` methods | `StyleProp<ViewStyle>` | | The list's own style (it needs a bounded size: `flex: 1` or a height). |
| `testID` | `.test_id(id)` | `string` | | The id UI tests find the list's scroll view by (`nsh test`'s `id:`, XCUITest, UI Automator). |
| `ref` | `.element_ref(&handle)` | `ListRef \| (node: ListRef) => void` | | The list's ref (see [ref methods](#ref-methods)). |

Lists also take the scrolling props of [`Scroll`](https://nsh.dev/versions/main/elements/scroll.md#scrolling) (the `Scrollable` methods in Rust):
`pagingEnabled`, `snapToInterval`, `snapToOffsets`, `snapToAlignment`, `disableIntervalMomentum`, `decelerationRate`,
`bounces`, `contentInset`, `contentOffset`, `keyboardShouldPersistTaps`, `scrollEventThrottle` and `scrollable`.
Lists keep their scale.

The props every element takes ([common props](https://nsh.dev/versions/main/elements.md#common-props)) go to the list's scroll view as they are:
`testID`, `accessibilityLabel` and the other accessibility props, the styles, `onLayout`, touch and responder props.
UI tests find a list by its `testID` as they find any view.

`ViewabilityConfig` (Rust: `Viewability { item_visible_threshold, view_area_coverage_threshold }` and `.minimum_view_time(..)`):

| Field | Type | Description |
|---|---|---|
| `itemVisibleThreshold` | `number` | How much of an item must be visible, from 0 to 1. |
| `viewAreaCoverageThreshold` | `number` | How much of the viewport an item must cover, from 0 to 1. Without either threshold, any visible pixel counts. |
| `minimumViewTime` | `number` | Milliseconds items must stay viewable before they are reported. |

`ViewToken<T>` is `{ item, key, index, isViewable }`. Rust's listener gets `ViewableItems`: `indices()` is the range of
viewable rows, `changed()` the rows that came or went.

## Events

| Event | Rust | Payload | When |
|---|---|---|---|
| `onScroll` | `.on_scroll` | `ScrollEvent` | The offset changed. |
| `onScrollDragStart` / `onScrollDragEnd` | `.on_scroll_drag_start` / `.on_scroll_drag_end` | `{ offset }` | Dragging started / stopped. |
| `onMomentumStart` / `onMomentumEnd` | `.on_momentum_start` / `.on_momentum_end` | `{ offset }` | A glide started / stopped. |
| `onScrollEnd` | `.on_scroll_end` | `{ offset }` | Scrolling came to rest. |
| `onLoadMore` | `.on_load_more` | none | Within `loadMoreThreshold` viewports of the end. |
| `onLoadMoreAtStart` | `.on_load_more_at_start` | none | Within `loadMoreAtStartThreshold` viewports of the start, once per approach after a scroll. |
| `onViewableItemsChange` | `.on_viewable_items_change` | `{ viewableItems, changed }` (`ViewableItems`) | Viewability changed. |
| `onRefresh` | `.on_refresh` | none | Pulled to refresh. |

## Ref methods

| Method | Rust | Description |
|---|---|---|
| `scrollToIndex({ index, animated?, viewPosition?, viewOffset? })` | `scroll_to_index(index, percentage(0.5), px(0.0), animated)` | Scrolls item `index` into view. `viewPosition` places it: 0 at the start of the viewport (default), 0.5 in the middle, 1 at the end; `viewOffset` shifts it further. Resolved natively with the current (measured or estimated) item sizes. |
| `scrollToOffset({ offset, animated? })` | `scroll_to_offset(px(..), animated)` | Scrolls to an offset along the list's axis. |
| `scrollToEnd({ animated? })` | `scroll_to_end(animated)` | Scrolls to the end of the content (the start of an inverted list). |
| `scrollTo({ x?, y?, animated? })` | `scroll_to(point(..), animated)` | Scrolls to an offset. |

## Examples

A grid with a header and viewability:

```rust
let visible = signal(SharedString::default());
let list = element_ref();

virtual_list(move || photos.with(|p| p.len()), move |at| {
    image(move || photos.with(|p| p[at.index()].url.clone())).h(px(120.0)).rounded(px(8.0))
})
.element_ref(&list)
.columns(3)
.estimated_item_size(px(120.0))
.content_padding(px(12.0))
.row_gap(px(8.0))
.column_gap(px(8.0))
.viewability(Viewability { item_visible_threshold: Some(Percentage(0.5)), ..Viewability::default() })
.on_viewable_items_change(move |items: &ViewableItems| {
    visible.set(format!("{} visible", items.indices().count()).into())
})
.header(
    text("Jump to 60")
        .on_press(move || list.scroll_to_index(60, percentage(0.5), px(0.0), true)),
)
.flex_1()
```

```tsx
const visible = signal("");
let list!: ListRef;

<List
  ref={list}
  each={photos}
  numColumns={3}
  estimatedItemSize={120}
  contentStyle={{ padding: 12, gap: 8 }}
  viewabilityConfig={{ itemVisibleThreshold: 0.5 }}
  onViewableItemsChange={({ viewableItems }) => visible.set(`${viewableItems.length} visible`)}
  header={<Text onPress={() => list.scrollToIndex({ index: 60, viewPosition: 0.5 })}>Jump to 60</Text>}
  style={{ flex: 1 }}
>
  {(photo) => <Image src={photo().url} style={{ height: 120, borderRadius: 8 }} />}
</List>;
```

A chat:

```rust
virtual_list(move || messages.with(|m| m.len()), move |at| bubble(messages, at))
    .keys(move || messages.with(|m| m.iter().map(|m| m.id).collect::<Vec<_>>()))
    .inverted()
    .estimated_item_size(px(64.0))
    .keyboard_dismiss_mode(KeyboardDismissMode::Interactive)
    .flex_1()
```

```tsx
<List each={messages()} inverted estimatedItemSize={64} keyboardDismissMode="interactive" style={{ flex: 1 }}>
  {(m) => <Bubble message={m()} />}
</List>
```

Item 0 is the newest message, drawn at the bottom; new messages prepended to the items appear without moving what the
user is reading.

## Platform notes

- Inserting items above the visible rows keeps the visible rows in place on both platforms.
- Horizontal lists in right-to-left layouts are mirrored natively.
- Sticky headers are pinned natively on every scroll frame.

Source: https://nsh.dev/versions/main/elements/list

---

# Canvas

A canvas is a view you draw yourself with a 2D drawing API, the HTML Canvas 2D API's: charts, gauges, rings,
signatures, custom shapes. The drawing code records operations; the platform replays them natively (Core Graphics on
iOS and Mac Catalyst, `android.graphics.Canvas` on Android) at the screen's resolution. Rust makes one with
`canvas(painter)`, a `Painter` recording the drawing; TSX with `<Canvas>` from `nsh` and its `draw` function.

```rust
use std::f32::consts::{FRAC_PI_2, TAU};

use nsh_core::{canvas::LineCap, prelude::*};

/// A progress ring, 120 points square.
fn ring(progress: f32) -> impl IntoElement {
    let (center, radius) = (60.0, 50.0);
    canvas(
        Painter::new()
            .line_width(12.0)
            .line_cap(LineCap::Round)
            .stroke_color(rgb(0xe5e7eb))
            .begin_path()
            .arc(center, center, radius, 0.0, TAU)
            .stroke()
            .stroke_color(rgb(0x6366f1))
            .begin_path()
            .arc(center, center, radius, -FRAC_PI_2, -FRAC_PI_2 + progress * TAU)
            .stroke(),
    )
    .size(px(120.0))
}
```

```tsx
import { Canvas, mount } from "nsh";

function Ring(props: { progress: number }) {
  return (
    <Canvas
      style={{ width: 120, height: 120 }}
      draw={(cx, { width, height }) => {
        const centerX = width / 2, cy = height / 2, r = width / 2 - 10;
        cx.lineWidth = 12;
        cx.lineCap = "round";
        cx.strokeStyle = "#e5e7eb";
        cx.beginPath();
        cx.arc(centerX, cy, r, 0, Math.PI * 2);
        cx.stroke();
        cx.strokeStyle = "#6366f1";
        cx.beginPath();
        cx.arc(centerX, cy, r, -Math.PI / 2, -Math.PI / 2 + props.progress * Math.PI * 2);
        cx.stroke();
      }}
    />
  );
}

mount(() => <Ring progress={0.7} />);
```

In TSX, `Canvas` creates the native canvas view, measures it, and runs your `draw` function with a context and the
canvas's size (see the [Canvas API](https://nsh.dev/versions/main/modules/nsh-canvas.md)). In Rust, `canvas(..)` takes a `Painter`, or a closure
returning one: the closure draws again when what it reads changes, and the size comes from `on_layout` when the
drawing depends on it.

## Props

A canvas takes the props of a [view](https://nsh.dev/versions/main/elements/view.md) (styles, press and gesture props, `onLayout`, accessibility, `ref`, …)
plus:

| Prop | Rust | Type | Description |
|---|---|---|---|
| `draw` | `canvas(painter)` | `(cx: CanvasRenderingContext2D, size: { width: number; height: number }) => void` | Draws the canvas. Runs once the size is known, again when the canvas resizes, and again when signals it reads change. |

Give the canvas a size through its styles (width / height, `flex`, an aspect ratio): its size is the one its styles
give it.

## When it redraws

The drawing is tracked like an effect: reading a signal inside it subscribes the drawing to that signal.

```rust
let values = signal(vec![12.0_f32, 40.0, 28.0, 64.0]);
let width = signal(0.0_f32);
let height = 160.0;

canvas(move || {
    let data = values.get(); // a change of values redraws
    let step = width.get() / data.len() as f32;
    data.iter().enumerate().fold(Painter::new().fill_color(rgb(0x0969da)), |p, (i, v)| {
        p.fill_rect(i as f32 * step + 4.0, height - v, step - 8.0, *v)
    })
})
.h(px(height))
.on_layout(move |frame: &Bounds<Points>| width.set(frame.size.width.0))
```

```tsx
const values = signal([12, 40, 28, 64]);

<Canvas
  style={{ height: 160 }}
  draw={(cx, { width, height }) => {
    const data = values(); // a change of values() redraws
    const step = width / data.length;
    cx.fillStyle = "#0969da";
    data.forEach((v, i) => cx.fillRect(i * step + 4, height - v, step - 8, v));
  }}
/>;
```

Numbers and colors may also be [native animated values](https://nsh.dev/versions/main/modules/nsh.md#animation) (`CanvasNumber`, `CanvasPaint`;
in Rust a `&AnimatedValue` wherever a number goes): the platform then redraws on its own while they animate, with no
work in the app's code per frame.

```rust
use std::f32::consts::TAU;

let angle = animated_value(0.0);
angle.timing(TAU, 1000.0, Easing::Linear);

canvas(
    Painter::new()
        .translate(40.0, 40.0)
        .rotate(&angle) // animates natively
        .fill_color(rgb(0xcf222e))
        .fill_rect(-20.0, -4.0, 40.0, 8.0),
)
.size(px(80.0))
```

```tsx
import { Canvas } from "nsh";
import { Animated, createAnimatedValue } from "nsh";

const angle = createAnimatedValue(0);
Animated.timing(angle, { toValue: Math.PI * 2, duration: 1000 }).start();

<Canvas
  style={{ width: 80, height: 80 }}
  draw={(cx) => {
    cx.translate(40, 40);
    cx.rotate(angle); // animates natively
    cx.fillStyle = "#cf222e";
    cx.fillRect(-20, -4, 40, 8);
  }}
/>;
```

## The context

`CanvasRenderingContext2D` is a subset of the browser's, and `Painter` has the same operations as methods in snake case
(`move_to`, `line_to`, `fill_rect`, `fill_text`, `stroke_color`, …): the state stack (`save`, `restore`), transforms,
paths (`moveTo`, `lineTo`, `arc`, `arcTo`, `ellipse`, `rect`, `roundRect`, Bézier curves), `fill` / `stroke` / `clip`
(also of a `Path2D`, which accepts SVG path data; `fill_svg` / `stroke_svg` in Rust), rectangles, text (`fillText`,
`strokeText`, `measureText`), linear / radial / conic gradients, line dashes, shadows, `globalAlpha`,
`globalCompositeOperation` and `drawImage` (images by URL or asset). Every member is listed in the
[Canvas API reference](https://nsh.dev/versions/main/modules/nsh-canvas.md); the [canvas guide](https://nsh.dev/versions/main/docs/canvas.md) walks through drawing
charts and animated graphics.

Coordinates are in points with the origin at the top left. `measureText` is synchronous and returns `width`. Rust's
`Painter` answers hit tests too (`is_point_in_path`, `is_point_in_stroke`).

The context draws vector operations and images: pixel access (`getImageData` / `putImageData`), `filter` and SVG
images are outside it.

## Events

The [view events](https://nsh.dev/versions/main/elements/view.md#events): `onPress`, `onLayout`, gestures and touches. To handle drawing-relative taps, read
`locationX` / `locationY` in `onTouchEnd`, or track a drag with `onResponderMove` (`.on_responder_move(..)` in Rust,
with `e.location`).

## Ref methods

None of its own.

Source: https://nsh.dev/versions/main/elements/canvas

---

# Shader

A shader is a view whose box a GPU program draws: gradients that flow, noise and grain, plasma, aurora, holographic
foil, ripples that follow a tap. You write one WGSL function, `shade`, that gives the color of each point of the box;
the platform runs it on the GPU at the screen's resolution, over the view's background and under its children.
Animated values move it natively, frame by frame, with no work in the app's code. TSX makes one with `<Shader>` from
`nsh`, Rust with `shader().source(program)`.

```rust
use nsh_core::{prelude::*, shader::Shader};

const GLOW: &str = r#"
struct Uniforms { tint: vec4f }

fn shade(uv: vec2f) -> vec4f {
  let d = distance(uv, vec2f(0.5));
  let pulse = 0.5 + 0.5 * sin(nsh.time * 2.0);
  let glow = smoothstep(0.5, 0.0, d) * (0.6 + 0.4 * pulse);
  return vec4f(uniforms.tint.rgb * glow, 1.0);
}
"#;

fn glow() -> impl IntoElement {
    let program = Shader::compile(GLOW).expect("a valid shader");
    shader()
        .source(program)
        .uniform("tint", Hsla::from(rgb(0x38bdf8)))
        .h(px(200.0))
        .rounded(px(14.0))
}
```

```tsx
import { mount, Shader } from "nsh";

const GLOW = /* wgsl */ `
struct Uniforms { tint: vec4f }

fn shade(uv: vec2f) -> vec4f {
  let d = distance(uv, vec2f(0.5));
  let pulse = 0.5 + 0.5 * sin(nsh.time * 2.0);
  let glow = smoothstep(0.5, 0.0, d) * (0.6 + 0.4 * pulse);
  return vec4f(uniforms.tint.rgb * glow, 1.0);
}`;

function Glow() {
  return <Shader source={GLOW} uniforms={{ tint: "#38bdf8" }} style={{ height: 200, borderRadius: 14 }} />;
}

mount(() => <Glow />);
```

## The shader

A shader's source is WGSL, the shading language of WebGPU. It defines one function:

```wgsl
fn shade(uv: vec2f) -> vec4f
```

- `uv` is the point of the view's box, from `(0, 0)` at its top left corner to `(1, 1)` at its bottom right, y
  growing downwards as in CSS.
- The result is the point's color: red, green, blue and alpha in 0..1, in sRGB with straight alpha, as CSS colors
  are. Values outside 0..1 are clamped.

Next to `shade` the source holds whatever helper functions, constants and `var<private>` variables it needs. NSH
supplies the entry points and reads the shader's inputs from two places.

### Built-ins

| Built-in | Type | Value |
|---|---|---|
| `nsh.size` | `vec2f` | The view's size in points. |
| `nsh.time` | `f32` | Seconds since the shader appeared. A shader that reads it animates: it draws every frame while it is on screen. |
| `nsh.scale` | `f32` | Pixels per point of the frame being drawn. |

`uv * nsh.size` is the point in points; `nsh.size.x / nsh.size.y` is the aspect ratio, which keeps circles round in
a box that is not square.

### Uniforms

Values the app sets go in a struct named `Uniforms`, which the shader reads as `uniforms`:

```wgsl
struct Uniforms {
  colors: array<vec4f, 4>,
  speed: f32,
  center: vec2f,
}

fn shade(uv: vec2f) -> vec4f {
  let t = nsh.time * uniforms.speed;
  // …
}
```

The `uniforms` prop sets its members by name. Each type takes these values:

| WGSL type | Values |
|---|---|
| `f32`, `i32`, `u32` | A number (rounded toward zero for `i32` and `u32`), or an animated value |
| `vec2f` | `[x, y]`: two numbers or animated values |
| `vec3f` | A color (its red, green and blue), an animated color, or three numbers |
| `vec4f` | A color with its alpha, an animated color, or four numbers |
| `array<vec4f, N>` | A list of up to `N` colors (or of four numbers each): a palette, the stops of a gradient |

Colors are any CSS color (`"#38bdf8"`, `"rgb(56 189 248)"`, `"hsl(199 93% 60%)"`) and reach the shader as sRGB
components in 0..1. Members the app leaves out are zero. Setting `uniforms` again draws the shader again with the new
values.

```tsx
const palettes = { Sunset: ["#ff6b6b", "#ffb86b", "#7b5cff", "#ff4fa3"], Lagoon: ["#00c2a8", "#2f80ed", "#a0f0ff", "#0b3d91"] };
const palette = signal<keyof typeof palettes>("Sunset");

<Shader source={MESH} uniforms={{ colors: palettes[palette()], speed: 0.5 }} style={{ height: 200 }} />;
```

## Animated uniforms

A uniform may be a [native animated value](https://nsh.dev/versions/main/modules/nsh.md#animation), or a node derived from one
(`interpolate`, arithmetic). The platform writes its value into the shader on every frame it changes and draws again,
on the UI thread: the animation runs at full frame rate however busy the app's code is. Numbers animate `f32`, `i32`
and `u32` members and the components of a `vec2f`; an interpolation to colors animates a `vec3f` or `vec4f`.

```rust
use nsh_core::{prelude::*, shader::Shader};

fn ripple(program: Shader) -> impl IntoElement {
    let wave = animated_value(0.0);
    wave.timing(1.0, 2200.0, Easing::Linear);
    shader()
        .source(program)
        .uniform("wave", &wave)
        .uniform("center", [0.5_f32, 0.5])
        .h(px(200.0))
}
```

```tsx
import { Animated, cleanup, createAnimatedValue, Easing, Shader } from "nsh";

const RIPPLE = /* wgsl */ `
struct Uniforms { center: vec2f, wave: f32, tint: vec4f }
fn shade(uv: vec2f) -> vec4f {
  let d = distance(uv * nsh.size, uniforms.center * nsh.size) / max(nsh.size.x, nsh.size.y);
  let ring = exp(-pow((d - uniforms.wave * 0.75) * 28.0, 2.0)) * (1.0 - uniforms.wave);
  return vec4f(vec3f(0.03, 0.03, 0.06) + uniforms.tint.rgb * ring * 1.6, 1.0);
}`;

function Ripple() {
  const wave = createAnimatedValue(0);
  const tint = wave.interpolate({ inputRange: [0, 1], outputRange: ["#38bdf8", "#c084fc"] });
  const loop = Animated.loop(Animated.timing(wave, { toValue: 1, duration: 2200, easing: Easing.out(Easing.quad) }));
  loop.start();
  cleanup(() => loop.stop());
  return <Shader source={RIPPLE} uniforms={{ center: [0.5, 0.5], wave, tint }} style={{ height: 200, borderRadius: 14 }} />;
}
```

## Pausing

`paused` stops the shader's clock: `nsh.time` keeps its value and the shader holds its picture. Setting it back to
`false` starts the clock from where it stopped. Uniforms and size changes still draw a paused shader.

```tsx
const paused = signal(false);

<Shader source={AURORA} paused={paused()} style={{ height: 200 }} onPress={() => paused.set(!paused())} />;
```

A shader that does not read `nsh.time` draws when its size or its uniforms change, and holds its picture in between.

## Children and clipping

A shader is a container: it takes every prop of a [view](https://nsh.dev/versions/main/elements/view.md) (styles, padding and layout of its children,
press and gesture props, `onLayout`, accessibility, `ref`), and its children draw over the shader. The shader fills
the view's box the way a background does, inside its rounded corners (`borderRadius`), over its `backgroundColor`.

```tsx
<Shader source={HOLO} uniforms={{ tilt }} style={{ height: 200, borderRadius: 18, padding: 20, justifyContent: "space-between" }}>
  <Text style={{ color: "#ffffff", fontSize: 13, fontWeight: "600" }}>NATIVE SHELL</Text>
  <Text style={{ color: "#ffffff", fontSize: 26, fontWeight: "700" }}>4242 0000 1717</Text>
</Shader>
```

Give the shader a size through its styles (width / height, `flex`, an aspect ratio) or let its children size it.

## Effects, transitions and the screen

A shader can also draw what other views draw. Its WGSL then reads pictures through four functions, each taking a
point `uv` of its box and returning a straight sRGB color with alpha, transparent outside the picture:

| Function | Reads |
|---|---|
| `sample_content(uv)` | an effect's children, or the whole surface for a screen effect |
| `sample_backdrop(uv)` | what is behind the view (any shader may read it) |
| `sample_from(uv)` | a transition's side it leaves |
| `sample_to(uv)` | a transition's side it comes to |

`nsh.progress` is an effect's `progress` or how far a transition is (0 to 1), and `nsh.overflow` how far beyond the
box the shader draws, in points.

**`ShaderEffect`** draws its children through the shader: they keep their presses, focus and accessibility, and what
shows is the shader's result. `progress` is a number or an animated value, which moves the effect natively.
`maxSampleOffset` lets the shader draw that many points beyond the box (a glow, a blur's edge); its `uv` then goes
below 0 and above 1. Without `source` the children draw as they are.

```tsx
import { createAnimatedValue, ShaderEffect, Text } from "nsh";

const WIPE_OUT = `
fn shade(uv: vec2f) -> vec4f {
  let c = sample_content(uv);
  let edge = smoothstep(nsh.progress - 0.05, nsh.progress + 0.05, uv.x);
  return vec4f(c.rgb, c.a * edge);
}`;

const gone = createAnimatedValue(0);

<ShaderEffect source={WIPE_OUT} progress={gone} style={{ padding: 16 }}>
  <Text>Wiped away as `gone` goes to 1</Text>
</ShaderEffect>
```

**`ShaderTransition`** changes its children through the shader when `value` (a string, number or boolean) changes,
not for its first value: `sample_from` is a picture of what they drew before, `sample_to` what they draw now, and
`nsh.progress` goes from 0 to 1 over `duration` milliseconds (300). Without `source` it runs `fallback`: `"fade"` (a
cross-fade, the default) or `"none"`.

```tsx
<ShaderTransition source={WIPE} value={card()} duration={450}>
  <Card name={card()} />
</ShaderTransition>
```

**`ScreenEffect`** and **`ScreenTransition`** do the same for the whole surface (its pages, dialogs and overlays). They
take no space and have no children; put them anywhere in the app. The last screen effect mounted with a `source`
draws.

Pages and dialogs come and go through a shader with **`transitionShader`**: `{ source, uniforms, duration }` on a
`NavPage` or a `Dialog` (Rust: `.transition_shader(TransitionShader::new(program))` on `nav_page()` or `dialog()`).
When the page is pushed or popped, or the dialog shown or closed, the lower side (the page under it, the app without
the dialog) is `sample_from` and the upper `sample_to`; `nsh.progress` goes from 0 to 1 as the page or the dialog
comes and from 1 to 0 as it goes, so one shader draws both ways.

```rust
use std::time::Duration;

use nsh_base::nav_page;
use nsh_core::{prelude::*, shader::{Shader, TransitionShader}};

fn details() -> impl IntoElement {
    let ripple = Shader::compile(RIPPLE).expect("a valid shader");
    nav_page()
        .title("Details")
        .transition_shader(TransitionShader::new(ripple).duration(Duration::from_millis(500)))
        .child(text("…"))
}
```

```tsx
<NavPage title="Details" transitionShader={{ source: RIPPLE, duration: 500 }}>…</NavPage>
```

The shader takes the place of the page's or the dialog's `animation`, whatever it is (`"none"` too). The `animation`
runs on a device without a GPU, when the user asks for less motion (Reduce Motion, Remove animations), and for a
source that does not compile; with `"none"` the change then shows at once. A push, pop, show or close that starts
while one runs completes that one first: its page or dialog arrives or leaves, its `onShow` or `onDismiss` fires, and
the new change starts from there.

The platforms take the pictures when what they show changes, at most once per display frame. A picture is drawn by
the platform's own renderer, so what it cannot draw into a picture (a video, a web page, another app's view) shows
transparent in it.

## Props

A shader takes the props of a [view](https://nsh.dev/versions/main/elements/view.md) plus:

| Prop | Rust | Type | Description |
|---|---|---|---|
| `source` | `.source(program)` | `string` | The WGSL source defining `fn shade(uv: vec2f) -> vec4f`. Rust compiles it with `Shader::compile(source)`. |
| `uniforms` | `.uniform(name, value)` | `Record<string, ShaderUniform>` | The values of the members of `struct Uniforms`, by name: numbers, colors, animated values and lists of them. |
| `paused` | `.paused(bool)` | `boolean` | Stops the clock of `nsh.time`. Default `false`. |

`ShaderEffect` and `ScreenEffect` take those (`source` optional) plus:

| Prop | Rust | Type | Description |
|---|---|---|---|
| `progress` | `.progress(n)`, `.animated_progress(&value)` | `number \| AnimatedNode` | `nsh.progress`. Default 0. |
| `maxSampleOffset` | `.max_sample_offset(px(n))` | `number` | How far beyond the box, in points, the shader draws and its pictures reach (`ShaderEffect` and `ShaderTransition`). Default 0. |

`ShaderTransition` and `ScreenTransition` take `source`, `uniforms` and `paused` plus:

| Prop | Rust | Type | Description |
|---|---|---|---|
| `value` | `.value(key)` | `string \| number \| boolean` | When it changes, the transition runs (not for the first value). |
| `duration` | `.duration(Duration)` | `number` | How long it runs, in milliseconds. Default 300. |
| `fallback` | `.fallback(TransitionFallback)` | `"fade" \| "none"` | What runs without a `source`. Default `"fade"`. |

`NavPage` and `Dialog` take:

| Prop | Rust | Type | Description |
|---|---|---|---|
| `transitionShader` | `.transition_shader(TransitionShader::new(program))`, `.uniform(name, value)`, `.duration(Duration)` | `{ source: string; uniforms?: Record<string, ShaderUniform>; duration?: number }` | The shader the page or dialog comes and goes through in place of its `animation`. `duration` in milliseconds, 350 by default. |

## Errors

NSH checks every shader when its source is set, before it reaches the GPU. A shader that does not compile logs a
warning with the line and column in its source and what is wrong, for example:

```text
the shader of node 12: 2:1: `shade` takes the point's `uv: vec2f` and returns its color, a `vec4f`
```

The view then shows its background and children. A uniform the struct lacks, or a value its type does not take,
logs a warning naming the uniform, and the other uniforms apply.

Each source compiles once: views that share a source, and a source set again, use the compiled shader.

## Rules and limits

- `shade` has exactly the signature `fn shade(uv: vec2f) -> vec4f`. The source declares its own functions,
  constants, structs and `var<private>` variables; NSH supplies the entry points and the bindings.
- The source is at most 64 KiB.
- `struct Uniforms` takes at most 4096 bytes, with members of the types in the table above.
- A frame is at most 4096 pixels a side: a larger view draws its shader at a lower scale.

For noise, hash the integer cell a point is in (`bitcast<vec2u>(vec2i(floor(p)))` mixed with multiplies and
xor-shifts) rather than `fract(sin(…) * 43758.5)`: integer hashes give the same value for a cell everywhere it is
computed, so value noise stays seamless on every GPU. The gallery's shaders show one.

## Platforms

On iOS, Android, macOS, Windows and Linux, and in GPUI apps, NSH renders shaders on the GPU with wgpu (Metal on Apple
platforms, Vulkan, Direct3D 12 or OpenGL elsewhere) at the screen's scale, and shows each frame under the view's
children. Rendering runs alongside the UI: a frame appears one or two display frames after it is drawn, and the UI
stays responsive while the GPU works. On the web, NSH translates the shader to GLSL and draws it with WebGL 2.

Shaders draw at most once per display frame, and only when what they show changes: a shader with fixed uniforms draws
once, one that reads `nsh.time` every frame, and one with animated uniforms while they move.

## Rust

`shader()` (from `nsh_core::element`) makes a shader view; `.source(program)` gives it a compiled `Shader`
(`nsh_core::shader::Shader::compile(source)`, which returns the same errors as above). Compile a program once and
share it: it is cheap to clone. The program may be bound, `.source(move || …)`, to switch programs.

| Method | Description |
|---|---|
| `.uniform(name, value)` | Sets a member of `struct Uniforms`: a number, a `Color` or `Hsla`, `[f32; 2]` / `[f32; 3]` / `[f32; 4]`, or a `Vec<UniformValue>`. A bound value (`move \|\| …`) sets it again when it changes; an animated value (`&wave`: a number, or colors for a `vec3f` / `vec4f`) moves it on every frame, natively. |
| `.paused(bool)` | Stops the clock of `nsh.time`; bindable. |

Children are added with `.child(..)`, styles with the usual typed methods. `shader_effect()`, `shader_transition()`,
`screen_effect()` and `screen_transition()` make the other elements, with the methods in the tables above.

Source: https://nsh.dev/versions/main/elements/shader

---

# WebView

A web view shows a web page, or HTML you pass in, inside the app: WKWebView on iOS and Mac Catalyst,
`android.webkit.WebView` on Android. Because NSH renders with native views, a web view sits in the layout like any other
view, in order with the views around it. Rust makes one with `web_view(url)` or `web_view_html(html, base_url)`, TSX
with `<WebView>` from `nsh`.

```rust
use nsh_core::prelude::*;

fn browser() -> impl IntoElement {
    let title = signal(SharedString::from("Loading…"));
    view()
        .flex_1()
        .child(text(title).number_of_lines(1))
        .child(
            web_view("https://example.com")
                .flex_1()
                .on_navigation_state_change(move |e: &WebNavigation| title.set(e.title.clone().into())),
        )
}
```

```tsx
import { signal, Text, View, WebView, type WebViewNavigation } from "nsh";

function Browser() {
  const nav = signal<WebViewNavigation | null>(null);
  return (
    <View style={{ flex: 1 }}>
      <Text style={{ numberOfLines: 1 }}>{nav()?.title ?? "Loading…"}</Text>
      <WebView
        src="https://example.com"
        style={{ flex: 1 }}
        onNavigationStateChange={(e) => nav.set(e)}
      />
    </View>
  );
}
```

In TSX a web view takes one of `src` and `html` (see the [WebView API](https://nsh.dev/versions/main/modules/nsh-webview.md)). The
[web view and video guide](https://nsh.dev/versions/main/docs/web-view-and-video.md) covers messaging patterns and capabilities.

## Props

A web view takes the props of a [view](https://nsh.dev/versions/main/elements/view.md) (it has no children) plus:

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `src` | `web_view(url)` | `string` | | The URL of the page to show. |
| `html` | `web_view_html(html, base_url)`, `.html(html, base_url)` | `string` | | Inline HTML, shown instead of `src`. |
| `baseUrl` | `base_url` of `web_view_html` / `.html` | `string` | | What `html`'s relative links resolve against. |
| `injectedJavaScript` | `.injected_java_script(..)` | `string` | | Runs after each page loads. |
| `injectedJavaScriptBeforeContentLoaded` | `.injected_java_script_before_content(..)` | `string` | | Runs before each page's own scripts. |
| `userAgent` | `.user_agent(..)` | `string` | | The browser's user agent string. |
| `javaScriptEnabled` | `.java_script_enabled(..)` | `boolean` | `true` | Pages run scripts. |
| `scrollable` | `.scrollable(..)` | `boolean` | `true` | The user can scroll the page. |

| `ios` key | Rust | Type | Description |
|---|---|---|---|
| `allowsBackForwardNavigationGestures` | `.back_forward_gestures(..)` | `boolean` | Swipe from the edges to go back and forward. |

| `desktop` key | Rust | Type | Description |
|---|---|---|---|
| `allowsBackForwardNavigationGestures` | `.back_forward_gestures(..)` | `boolean` | macOS: swipe with two fingers on the trackpad to go back and forward; Windows: swipe on a touchscreen; Linux: swipe on the touchpad. |

## Events

| Event | Rust | Payload | When |
|---|---|---|---|
| `onLoadStart` | `.on_load_start` | `WebViewNavigation` | A page started loading. |
| `onLoad` | `.on_load` | `WebViewNavigation` | A page finished loading. |
| `onError` | `.on_error` | `{ message, code? }` (`&str`, the message) | Loading failed; `code` is `"ERR_ACCESS_DENIED"` for a page or `html` the app's capabilities do not grant. |
| `onNavigationStateChange` | `.on_navigation_state_change` | `WebViewNavigation` | The URL, title, loading state or history changed. |
| `onMessage` | `.on_message` | `{ data: string }` (`&str`) | The page called `window.nsh.postMessage(data)`. |
| `onDownload` | | `WebViewDownload` | A download started, finished or failed (macOS). |

`WebViewNavigation` is `{ url, title, loading, canGoBack, canGoForward }`; in Rust `WebNavigation` with `url`, `title`,
`loading`, `can_go_back` and `can_go_forward`.

`WebViewDownload` is `{ state, id, url, filename, path, bytes?, message? }`: `state` is `"started"`, `"finished"`
(with the file's `bytes`) or `"failed"` (with its `message`). With an `onDownload` listener, what the page downloads
(an attachment, a type the web view does not show, a `download` link) is saved in the app's data directory as
`downloads/<id>/<filename>`, where `path` points, and the app reads it with `fs/promises`.

On macOS, adding the listener lets any loaded page allowed by the `webview` capability save downloads
automatically. The app is responsible for its storage budget and for removing completed files from `downloads/`
when it has finished using them. Removing the web view cancels downloads in progress and removes their partial
directories. Downloads report through `onDownload`; converting a navigation into a download keeps `onError`
for actual navigation failures. Filenames have control characters and bidirectional formatting controls removed,
and long names are shortened to 200 bytes while preserving an extension that fits.

## Ref methods

| Method | Rust | Description |
|---|---|---|
| `reload()` | `reload()` | Reloads the page. |
| `goBack()` / `goForward()` | `go_back()` / `go_forward()` | Moves in the page's history. |
| `stopLoading()` | `stop_loading()` | Stops loading. |
| `injectJavaScript(script)` | `inject_java_script(script)` | Runs JavaScript in the page. |
| `postMessage(data)` | `post_message(data)` | Sends a string to the page, which receives a `message` event on `window`. |

## Messaging

The app and the page exchange strings. The page posts with `window.nsh.postMessage(data)`; the app posts
with the ref's `postMessage(data)` (`post_message(..)` in Rust). Send JSON for structured data.

```rust
use nsh_core::prelude::*;

const PAGE: &str = r#"<!doctype html>
<meta name="viewport" content="width=device-width">
<button onclick="window.nsh.postMessage('hello from the page')">Post to the app</button>
<p id="got"></p>
<script>
  window.addEventListener("message", (e) => { document.getElementById("got").textContent = e.data; });
</script>"#;

fn bridge() -> impl IntoElement {
    let message = signal(String::new());
    let web = element_ref();
    view()
        .gap_3()
        .child(
            web_view_html(PAGE.to_string(), None)
                .element_ref(&web)
                .h(px(200.0))
                .on_message(move |data: &str| message.set(data.to_string())),
        )
        .child(
            text(move || format!("Post to the page · got: {}", message.get()))
                .on_press(move || web.post_message("hi from the app")),
        )
}
```

```tsx
import { signal, Text, View, WebView, type WebViewRef } from "nsh";

const page = `<!doctype html>
<meta name="viewport" content="width=device-width">
<button onclick="window.nsh.postMessage('hello from the page')">Post to the app</button>
<p id="got"></p>
<script>
  window.addEventListener("message", (e) => { document.getElementById("got").textContent = e.data; });
</script>`;

function Bridge() {
  const message = signal("");
  let web!: WebViewRef;
  return (
    <View style={{ gap: 12 }}>
      <WebView ref={web} html={page} style={{ height: 200 }} onMessage={(e) => message.set(e.data)} />
      <Text onPress={() => web.postMessage("hi from the app")}>Post to the page · got: {message()}</Text>
    </View>
  );
}
```

## Capabilities

When the app declares [capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md) in `nsh.json`, a web view shows and
navigates to the hosts listed under `webview`. A `src` on another host, or `html` in an app without `webview`, shows an
empty view; a top-level navigation to another host (a link the user taps) is cancelled natively. Each reports
`onError` with `code` `"ERR_ACCESS_DENIED"`.

```json
{
  "capabilities": {
    "webview": { "hosts": ["example.com", "*.example.com"] }
  }
}
```

## Platform notes

- iOS loads WebKit the first time a web view is created, so it costs an app something only once it shows one.
- On macOS `onDownload` saves downloads with WebKit's `WKDownload`.
- On Android the page's `postMessage` calls arrive on a background thread and are forwarded to the app in order.
- To round the corners of a web view, give it a corner radius and `overflow: "hidden"` (`.overflow_hidden()`).

Source: https://nsh.dev/versions/main/elements/web-view

---

# Video

A video view plays a video file or stream with the platform's player: AVPlayer on iOS and Mac Catalyst, MediaPlayer on
Android. Playback is controlled with props (`paused`, `muted`, `rate`, …), so the player follows your state like any
other view. Rust makes one with `video(url)`, TSX with `<Video>` from `nsh`.

```rust
use nsh_core::prelude::*;

fn player() -> impl IntoElement {
    let paused = signal(true);
    let time = signal(String::new());
    let player = element_ref();
    view()
        .gap_3()
        .child(
            video("https://example.com/clip.mp4")
                .element_ref(&player)
                .paused(paused)
                .repeat(true)
                .object_fit(ResizeMode::Contain)
                .h(px(220.0))
                .bg(black())
                .on_progress(move |p: &VideoProgress| {
                    time.set(format!("{:.1} / {:.1} s", p.current_time, p.duration))
                }),
        )
        .child(
            view()
                .flex_row()
                .gap_4()
                .child(
                    text(move || if paused.get() { "Play" } else { "Pause" })
                        .on_press(move || paused.update(|p| *p = !*p)),
                )
                .child(text("Restart").on_press(move || player.seek(0.0)))
                .child(text(move || time.get())),
        )
}
```

```tsx
import { signal, Text, Video, type VideoRef, View } from "nsh";

function Player() {
  const paused = signal(true);
  const time = signal("");
  let video!: VideoRef;
  return (
    <View style={{ gap: 12 }}>
      <Video
        ref={video}
        src="https://example.com/clip.mp4"
        paused={paused()}
        repeat
        style={{ height: 220, backgroundColor: "#000000" }}
        onProgress={(e) => time.set(`${e.currentTime.toFixed(1)} / ${e.duration.toFixed(1)} s`)}
      />
      <View style={{ flexDirection: "row", gap: 16 }}>
        <Text onPress={() => paused.set(!paused())}>{paused() ? "Play" : "Pause"}</Text>
        <Text onPress={() => video.seek(0)}>Restart</Text>
        <Text>{time()}</Text>
      </View>
    </View>
  );
}
```

In TSX `src` is required (see the [Video API](https://nsh.dev/versions/main/modules/nsh-video.md)). See the
[web view and video guide](https://nsh.dev/versions/main/docs/web-view-and-video.md).

## Props

A video takes the props of a [view](https://nsh.dev/versions/main/elements/view.md) (it has no children) plus:

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `src` | `video(url)` | `string` | | The video's URL (in Rust, an asset's `uri` too: `video(CLIP.uri)`). |
| `paused` | `.paused(..)` | `boolean` | `false` | Playback is paused. |
| `muted` | `.muted(..)` | `boolean` | `false` | No sound. |
| `volume` | `.volume(..)` | `number` | `1` | 0..1. |
| `rate` | `.rate(..)` | `number` | `1` | The playback speed. |
| `repeat` | `.repeat(..)` | `boolean` | `false` | Plays again from the start at the end. |
| `controls` | `.controls(..)` | `boolean` | `false` | Shows the platform's playback controls. |
| `objectFit` (style), `object-*` classes | `.object_fit(ResizeMode::Contain)` | `"cover" \| "contain" \| "fill" \| "none" \| "scale-down"` | `"contain"` | How the video fits its box, as CSS's `object-fit` (`class="object-cover"`). iOS, macOS and Android play `"none"` and `"scale-down"` as `"contain"`, Linux both as `"scale-down"`. |
| `progressUpdateInterval` | `.progress_interval(ms)` | `number` | `250` | Milliseconds between `onProgress` events. |

Give the video a size through its styles; its size is the one its styles give it. Use the size `onLoad` reports to set
an aspect ratio when you want the video's own proportions.

## Events

| Event | Rust | Payload | When |
|---|---|---|---|
| `onLoadStart` | `.on_load_start` | none | Loading began. |
| `onLoad` | `.on_load` | `{ duration, size }` (`VideoInfo`: `duration`, `size`) | The video is ready: its duration in seconds and its size in pixels. |
| `onProgress` | `.on_progress` | `{ currentTime, duration }` (`VideoProgress`: `current_time`, `duration`) | Every `progressUpdateInterval` while playing (seconds). |
| `onBuffer` | `.on_buffer` | `{ isBuffering }` (`bool`) | Playback stalled for data / resumed. |
| `onEnd` | `.on_end` | none | Playback reached the end (with `repeat`, at the end of each loop). |
| `onError` | `.on_error` | `{ message, code? }` (`&str`, the message) | Loading or playback failed; `code` is `"ERR_ACCESS_DENIED"` for a source the app's capabilities do not grant. |

```rust
let ratio = signal(16.0_f32 / 9.0);

video(url)
    .w_full()
    .aspect_ratio(ratio)
    .on_load(move |info: &VideoInfo| {
        ratio.set(info.size.width.0 as f32 / info.size.height.0 as f32)
    })
```

```tsx
const ratio = signal(16 / 9);
<Video src={url} style={{ width: "100%", aspectRatio: ratio() }} onLoad={(e) => ratio.set(e.size.width / e.size.height)} />;
```

## Ref methods

| Method | Rust | Description |
|---|---|---|
| `seek(seconds)` | `seek(seconds)` | Jumps to a time. |

## Capabilities

When the app declares [capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md), video sources load from the hosts `network`
allows; a source on another host shows an empty view and reports `onError` with `code` `"ERR_ACCESS_DENIED"`.

## Platform notes

- iOS draws the video in an `AVPlayerLayer`, or in the system player view with `controls`; AVFoundation is loaded the
  first time a video is created.
- Android plays with MediaPlayer on a TextureView, with a MediaController for `controls`.

Source: https://nsh.dev/versions/main/elements/video

---

# Overlay

An overlay shows its children on top of everything in the root view it is in: the window, or the dialog around it.
Its parent's size, `overflow: hidden` and scroll views do not clip it. It stays where you wrote it for everything
else: it reads the context around it, its handlers are its component's, and it goes away with its parent. Popovers,
menus, tooltips and sheets are built on it; [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md) has them ready
([Popover](https://nsh.dev/versions/main/elements/popover.md), [Menu](https://nsh.dev/versions/main/elements/menu.md), [Tooltip](https://nsh.dev/versions/main/elements/tooltip.md), [Sheet](https://nsh.dev/versions/main/elements/sheet.md)), and an overlay is what you
use to build your own.

```rust
use nsh_core::prelude::*;

fn more_button() -> impl IntoElement {
    let open = signal(false);
    let anchor = element_ref();
    view()
        .child(
            view()
                .element_ref(&anchor)
                .on_press(move || open.update(|o| *o = !*o))
                .px_3()
                .py_2()
                .child(text("More")),
        )
        .child(when(move || open.get(), move || {
            overlay()
                .anchor(&anchor)
                .placement(Placement::Bottom)
                .align(Align::Start)
                .offset(px(6.0))
                .margin(px(8.0))
                .on_press_outside(move |_: &Point<Points>| open.set(false))
                .on_cancel(move || open.set(false))
                .rounded_lg()
                .bg(white())
                .p_3()
                .shadow_lg()
                .child(text("Shown above everything"))
        }))
}
```

```tsx
import { Overlay, signal, Text, View, type ViewRef } from "nsh";

function MoreButton() {
  const open = signal(false);
  let anchor: ViewRef | undefined;
  return (
    <View>
      <View ref={anchor} onPress={() => open.set(!open())} class="px-3 py-2">
        <Text>More</Text>
      </View>
      <If when={open()}>
        <Overlay
          anchor={anchor}
          placement="bottom"
          align="start"
          offset={6}
          margin={8}
          onPressOutside={() => open.set(false)}
          onCancel={() => open.set(false)}
          class="rounded-lg bg-white p-3 shadow-lg"
        >
          <Text>Shown above everything</Text>
        </Overlay>
      </If>
    </View>
  );
}
```

`Overlay` comes from `nsh` in TSX and `overlay()` from `nsh_core::prelude` in Rust. It is shown while it is in the
view: put it in an `If` (Rust: `when(..)`) to open and close it. Overlays shown later are on top of earlier ones, and
an overlay inside another is on top of it.

## Placement

Without `anchor`, an overlay is laid out as a `position: fixed` box of its root view: its `top`, `left`, `inset`,
size and margins are against the whole window (or dialog). `class="inset-0"` covers it, which is a backdrop or a
full-window layer; `class="bottom-0 left-0 right-0"` is a bar along the bottom.

With `anchor`, NSH places it next to the anchor:

- `anchor` is a view (a `ref`), a `Point` (`{ x, y }`) in the root view's coordinates, the `pageX` / `pageY` of a touch
  (a menu where the pointer is), or a `Bounds` (`{ origin, size }`) there: an input's caret (`onCaretMove`'s `pageBounds`), where suggestions
  for what is being typed open.
- `placement` is the side it goes on: `"top"`, `"bottom"` (the default), `"left"` or `"right"`. When it does not fit
  there and fits on the other side, it goes there; when it fits on neither, it goes on the side with more room.
- `align` lines it up along that side: `"start"`, `"center"` (the default) or `"end"`. Above and below the anchor,
  start and end follow the layout direction: start is the left edge, or the right edge in a right-to-left layout.
- `offset` is the gap between the anchor and the overlay; `margin` the distance it keeps from the edges of the
  safe area, which it stays inside of: it slides along its side to fit.

An anchored overlay follows its anchor: when the anchor scrolls, moves or changes size, the overlay moves with it in
the same frame NSH lays it out. `onPosition` tells where it went, so an arrow can point at the anchor or a long menu can
limit its height:

```tsx
<Overlay
  anchor={anchor}
  onPosition={(e) => {
    side.set(e.placement); // "top" when it flipped
    maxHeight.set(e.available.height);
  }}
/>
```

## Dismissing

An overlay reports what usually closes a popup and leaves the decision to you:

- `onPressOutside` fires when a finger or a mouse button goes down outside the overlay, its anchor and the overlays
  inside it. The press goes on to what is under it.
- `onCancel` fires on Escape, the Android back button and VoiceOver's escape gesture on iOS, for the top overlay that listens to it only. It takes them
  before the pages and `BackHandler`.

To block the screen behind a popup, put a second overlay under it with `class="inset-0"` and an `onPress` that closes
both: that is how [Sheet](https://nsh.dev/versions/main/elements/sheet.md) and the phone presentation of [Popover](https://nsh.dev/versions/main/elements/popover.md) work.

## Props

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `anchor` | `.anchor(&element_ref)`, `.anchor_point(point)`, `.anchor_bounds(bounds)` | `ViewRef \| Point \| Bounds \| null` | none | The view, the point or the box it is placed against. Without one it is a fixed box of its root view. |
| `placement` | `.placement(..)` | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` | The side of the anchor it goes on. |
| `align` | `.align(..)` | `"start" \| "center" \| "end"` | `"center"` | How it lines up with the anchor along that side. |
| `offset` | `.offset(px(..))` | `number` | `0` | The gap between the anchor and the overlay. |
| `margin` | `.margin(px(..))` | `number` | `0` | The distance it keeps from the edges of the safe area. |
| `children` | `.child(..)` | `JSX.Element` | none | What it shows. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | Its look and, without an anchor, where it is. |

It also takes the [common props](https://nsh.dev/versions/main/elements.md#common-props) of a view.

## Events

| Event | Rust | Description |
|---|---|---|
| `onPressOutside` | `.on_press_outside(\|point\| ..)` | A press went down outside it, its anchor and the overlays inside it (`pagePosition`, a `Point`). |
| `onCancel` | `.on_cancel(\|\| ..)` | Escape, the Android back button or VoiceOver's escape gesture, while it is the top overlay listening. |
| `onPosition` | `.on_position(\|position\| ..)` | NSH placed it: `placement` (the side it went on), `bounds` in the root view, and `available` (a `Size`: the room on that side). |

## Platform notes

- Every platform shows an overlay as a native view of the window's (or the dialog's) root view, drawn and hit-tested
  as the views around it are: UIKit, Android views, AppKit, GTK, Win32, GPUI and the DOM.
- An overlay inside a [Dialog](https://nsh.dev/versions/main/elements/dialog.md) shows in that dialog, above its content.
- Overlays stay in their window: a menu that would reach past the window's edge slides back inside it.

Source: https://nsh.dev/versions/main/elements/overlay

---

# Safe area

The safe area keeps content clear of the notch or Dynamic Island, the status bar, the home indicator, a navigation
header and the Mac Catalyst title bar. Any view pads itself by it with CSS's `env()`:
`env(safe-area-inset-top)`, `env(safe-area-inset-right)`, `env(safe-area-inset-bottom)` and
`env(safe-area-inset-left)`, in its padding or margin. They are the insets of the root view the node renders in:
inside a [NavPage](https://nsh.dev/versions/main/elements/nav-stack.md) the insets below the page's header, inside a [Dialog](https://nsh.dev/versions/main/elements/dialog.md) the dialog's
insets, and elsewhere the surface's safe area. In a browser the page is the root, and the variables are the browser's
own.

```rust
use nsh_core::prelude::*;

fn app() -> impl IntoElement {
    view()
        .flex_1()
        .bg(rgb(0xfff8c5))
        .p_safe_area()
        .child(text("Clear of the notch").text_2xl().font_weight(FontWeight::BOLD))
}
```

```tsx
import { mount, Text, View } from "nsh";

function App() {
  return (
    <View
      style={{
        flex: 1,
        backgroundColor: "#fff8c5",
        paddingTop: "env(safe-area-inset-top)",
        paddingRight: "env(safe-area-inset-right)",
        paddingBottom: "env(safe-area-inset-bottom)",
        paddingLeft: "env(safe-area-inset-left)",
      }}
    >
      <Text style={{ fontSize: 24, fontWeight: "700" }}>Clear of the notch</Text>
    </View>
  );
}

mount(App);
```

The background color fills the whole area, including the area behind the status bar, and the content starts below
it. The values follow the insets: on rotation, in another page or dialog, the padding updates natively.

## Values

| Value | Example | Means |
|---|---|---|
| `env(name)` | `paddingTop: "env(safe-area-inset-top)"` | The inset. |
| `env(name, <length>)` | `env(safe-area-inset-top, 20px)` | The inset; the length stands in for an unknown name, as in CSS. |
| `calc(env(name) + <length>)` | `calc(env(safe-area-inset-bottom) + 16px)` | The inset plus a length, for content that keeps its own spacing. |
| `calc(<length> + env(name))` | `calc(16px + env(safe-area-inset-left))` | The same. |

They apply to `padding`, `paddingHorizontal`, `paddingVertical`, `paddingTop`, `paddingRight`, `paddingBottom`,
`paddingLeft` and the same `margin` keys. In Tailwind they are arbitrary values of `p`, `px`, `py`, `pt`, `pr`, `pb`,
`pl` and the `m` utilities (spaces may be left out): `pt-[env(safe-area-inset-top)]`,
`pb-[calc(env(safe-area-inset-bottom)+16px)]`. The TypeScript type of these values is `EnvValue`. See
[the style reference](https://nsh.dev/versions/main/modules/style-reference.md).

In Rust the `Styled` methods set them: `.p_safe_area()`, `.px_safe_area()`, `.py_safe_area()`, `.pt_safe_area()`,
`.pr_safe_area()`, `.pb_safe_area()`, `.pl_safe_area()`, the same `m` methods, and `.pt_safe_area_plus(px(16.0))`
(and `pr`, `pb`, `pl`, `mt`, `mr`, `mb`, `ml`) for an inset plus a length.

## Choosing the edges

Pad only the edges that need it, for example when a tab bar or a bottom bar of your own handles the bottom inset:

```rust
view()
    .flex_1()
    .pt_safe_area()
    .px_safe_area()
```

```tsx
<View class="flex-1 pt-[env(safe-area-inset-top)] px-[calc(env(safe-area-inset-left)+16px)]">
  …
</View>
```

## Where to use it

A [NavPage](https://nsh.dev/versions/main/elements/nav-stack.md) with a visible, opaque header already places its content below the header, so the top
inset there is 0. The safe area insets are for:

- the root of an app without a navigation stack,
- a page with `headerVisible={false}` or `headerTransparent`,
- the content of a full-screen [Dialog](https://nsh.dev/versions/main/elements/dialog.md),
- bars of your own at the edges of the screen.

## safeArea and safeAreaInsets

When you need the numbers in code, read them directly. Both TSX accessors come from `nsh`, return an `Edges` object
(`{ top, right, bottom, left }` in points) and are reactive: code that reads them runs again when they change, for
example on rotation.

| TSX | Rust | Returns |
|---|---|---|
| `safeArea()` | `safe_area()` | The surface's safe area: the parts clear of system UI (notch, home indicator, title bar). |
| `safeAreaInsets()` | `cx.insets()` | The insets where the component renders: the nearest page's (below its header), the nearest dialog's, or else the surface's safe area. These are the values of the `safe-area-inset-*` variables. In TSX, call it in a component; it returns an accessor. A Rust component of your crate reads them with `cx.insets()`. |

```rust
use nsh_core::prelude::*;

fn bottom_bar() -> impl IntoElement {
    view()
        .flex_row()
        .p_2()
        .pb(move || if safe_area().bottom > Points::ZERO { px(4.0) } else { px(8.0) })
        .child(text("Bottom bar"))
}
```

```tsx
import { Text, View, safeArea } from "nsh";

function BottomBar() {
  const insets = safeArea();
  return (
    <View style={{ flexDirection: "row", padding: 8, paddingBottom: insets().bottom > 0 ? 4 : 8 }}>
      <Text>Bottom bar</Text>
    </View>
  );
}
```

For padding by the inset itself, `env()` is the simpler form: it updates natively, without running code.

## Platform notes

- **iOS**: the insets come from UIKit's safe area: the status bar, the notch or Dynamic Island, and the home
  indicator.
- **Android**: NSH reports the parts of the system bars and the display cutout that overlap the NSH view. When NSH is
  [embedded](https://nsh.dev/versions/main/docs/android.md) below a native toolbar, the view's top inset is 0.
- **Mac Catalyst**: the top inset is the window's title bar.
- **Desktops (macOS, Windows, Linux, GPUI) and the web**: a page's content starts below its `header`, and a dialog
  gives its content insets of its own, as on the phones.

## Related

- [Keyboard](https://nsh.dev/versions/main/elements/keyboard.md): `env(keyboard-inset-height)`, content kept above the software keyboard.
- [Device and environment](https://nsh.dev/versions/main/docs/device-and-environment.md): the safe area among the device's other values.

Source: https://nsh.dev/versions/main/elements/safe-area

---

# Keyboard

`env(keyboard-inset-height)` is the software keyboard's height over the surface, 0 while it is hidden. As a view's
bottom padding or margin it keeps the content above the keyboard: when the keyboard shows or hides, the view makes room
by its height, and the change animates with the keyboard natively. Use it for content outside scroll views, such as a
message bar at the bottom of a chat screen; inputs inside a [scroll view](https://nsh.dev/versions/main/elements/scroll.md) or a [List](https://nsh.dev/versions/main/elements/list.md) are
scrolled into view natively. With it come `Keyboard.dismiss()`, which hides the keyboard, and the keyboard's height,
for layouts of your own.

```rust
use nsh_core::prelude::*;

fn chat() -> impl IntoElement {
    let draft = signal(String::new());
    view()
        .flex_1()
        .bg(white())
        .pb_keyboard()
        .child(scroll().flex_1().child(text("Messages…").p_4()))
        .child(
            view()
                .flex_row()
                .gap_2()
                .p_2()
                .border_t_1()
                .border_color(rgb(0xe5e5e5))
                .child(
                    input()
                        .value(draft)
                        .on_change(move |v: &str| draft.set(v.to_owned()))
                        .placeholder("Message")
                        .flex_1()
                        .p_2(),
                ),
        )
}
```

```tsx
import { mount, Scroll, signal, Text, View } from "nsh";
import { Input } from "nsh/base";

function App() {
  const draft = signal("");
  return (
    <View style={{ flex: 1, backgroundColor: "#ffffff", paddingBottom: "env(keyboard-inset-height)" }}>
      <Scroll style={{ flex: 1 }} keyboardDismissMode="interactive">
        <Text style={{ padding: 16, paddingTop: 48 }}>Messages…</Text>
      </Scroll>
      <View style={{ flexDirection: "row", gap: 8, padding: 8, borderTopWidth: 1, borderTopColor: "#e5e5e5" }}>
        <Input
          value={draft()}
          onChange={({ value }) => draft.set(value)}
          placeholder="Message"
          style={{ flex: 1, fontSize: 16, padding: 8 }}
        />
      </View>
    </View>
  );
}

mount(App);
```

The full keyboard height suits a view that reaches the bottom of the screen, as a screen's content does. When
something is below it, such as a tab bar, subtract that with a length: `calc(env(keyboard-inset-height) + -49px)`
keeps a view above a 49 pt tab bar, and `calc(env(keyboard-inset-height) + 12px)` adds spacing above the keyboard. A
padding is at least 0.

## Padding or margin

| Style | How it makes room |
|---|---|
| `paddingBottom: "env(keyboard-inset-height)"` (Tailwind `pb-[env(keyboard-inset-height)]`, Rust `.pb_keyboard()`) | The content above shrinks; the background still reaches the bottom of the screen. |
| `marginBottom: "env(keyboard-inset-height)"` (Tailwind `mb-[env(keyboard-inset-height)]`, Rust `.mb_keyboard()`) | The whole view, including its background, ends at the top of the keyboard. |

The keyboard's height is added to the length in the same declaration only, so a view combines it with spacing of its
own in `calc()`. In Rust, `.pb_keyboard_plus(px(..))` and `.mb_keyboard_plus(px(..))` add a length.

```rust
use nsh_core::prelude::*;

fn sign_in() -> impl IntoElement {
    view()
        .mb_keyboard_plus(px(-49.0))
        .flex_1()
        .p_4()
        .gap_3()
        .child(input().placeholder("E-mail").keyboard_type(KeyboardType::Email))
}
```

```tsx
<View class="flex-1 gap-3 p-4 mb-[calc(env(keyboard-inset-height)+-49px)]">
  <Input placeholder="E-mail" keyboardType="email-address" class="rounded-lg border border-neutral-300 px-3 py-2" />
</View>
```

Here a 49 pt tab bar below the view already covers part of the keyboard's height. To turn the room off, leave the
variable out of the style, for example with a condition on a signal.

## Hiding the keyboard

`Keyboard.dismiss()`, from `nsh`, unfocuses the focused input, which hides the keyboard. With no input focused, it leaves
everything as it is. Rust components call `dismiss_keyboard()`.

```rust
use nsh_base::button;
use nsh_core::prelude::*;

fn done() -> impl IntoElement {
    button()
        .on_press(|| dismiss_keyboard())
        .rounded_lg()
        .bg(rgb(0x2563eb))
        .px_4()
        .py_3()
        .child(text("Done").text_color(white()))
}
```

```tsx
import { Text, Keyboard } from "nsh";
import { Button } from "nsh/base";

function Done() {
  return (
    <Button onPress={() => Keyboard.dismiss()} class="rounded-lg bg-blue-600 px-4 py-3 active:bg-blue-700">
      <Text class="text-center font-semibold text-white">Done</Text>
    </Button>
  );
}
```

> [!TIP]
> To hide the keyboard when the user drags a scroll view, set `keyboardDismissMode="on-drag"` or `"interactive"` on
> the [scroll view](https://nsh.dev/versions/main/elements/scroll.md) or [List](https://nsh.dev/versions/main/elements/list.md).

## The keyboard's height

| TSX | Rust | Returns |
|---|---|---|
| `keyboardFrame()` | `keyboard_height()`, `keyboard_duration()` | The height of the software keyboard over the NSH surface, in points (0 while it is hidden), and the duration of its show or hide animation, in milliseconds. |

Both are reactive: an effect, a JSX expression or a style closure that reads them runs again when the keyboard shows,
hides or changes height.

```rust
use nsh_core::prelude::*;

fn message_bar() -> impl IntoElement {
    view()
        .flex_row()
        .p_2()
        .pb(move || {
            // The home indicator's inset only matters while the keyboard is hidden.
            let home = if keyboard_height() > Points::ZERO {
                Points::ZERO
            } else {
                safe_area().bottom
            };
            px(8.0) + home
        })
        .child(input().placeholder("Message").flex_1())
}
```

```tsx
import { View, keyboardFrame, safeArea } from "nsh";
import { Input } from "nsh/base";

function MessageBar() {
  const insets = safeArea();
  return (
    <View
      style={{
        flexDirection: "row",
        padding: 8,
        // The home indicator's inset only matters while the keyboard is hidden.
        paddingBottom: 8 + (keyboardFrame().height > 0 ? 0 : insets().bottom),
      }}
    >
      <Input placeholder="Message" style={{ flex: 1 }} />
    </View>
  );
}
```

The height is the part of the keyboard that overlaps the NSH surface. When the window itself shrinks for the keyboard
(an Android activity that resizes), or when NSH is embedded in a view that ends above the keyboard, the height is 0.

> [!NOTE]
> To keep content above the keyboard, `env(keyboard-inset-height)` is the simpler form: it animates with the keyboard
> natively, without running code.

## Platform notes

- **iOS**: the room animates with the keyboard's own duration and an ease-in-ease-out curve.
- **Android**: where the window shrinks for the keyboard (an activity that resizes), the content already ends above
  the keyboard and the variable is 0. Where the keyboard overlaps the view, it makes room as on iOS.
- **Desktops and Mac Catalyst** type with a hardware keyboard: the variable is 0 and the view keeps its layout.
- **Web**: the variable is the browser's own (the VirtualKeyboard API's).

See [Forms and keyboard](https://nsh.dev/versions/main/docs/forms-and-keyboard.md) for focus order, return keys and input accessories, and
[Safe area](https://nsh.dev/versions/main/elements/safe-area.md) for the other environment variables.

Source: https://nsh.dev/versions/main/elements/keyboard

---

# Text selection

A [`View`](https://nsh.dev/versions/main/elements/view.md) with `selectable` makes the texts inside it select together, as a web page's do: one selection
runs from a place in one text to a place in another, across views, [`Text`](https://nsh.dev/versions/main/elements/text.md) elements and
[`TextView`](https://nsh.dev/versions/main/elements/text-view.md)s, in reading order. Make a chat transcript selectable and a selection can start in one
message and end in the next; Copy puts the selected text on the clipboard, with texts side by side joined by a tab and
the others by a line break. Rust sets it with `view().selectable(true)`, TSX with `<View selectable>`; whether a single
text can be selected is its `userSelect` style.

```rust
use nsh_base::text_view;
use nsh_core::prelude::*;

fn release_notes(notes: &'static str) -> impl IntoElement {
    view()
        .selectable(true)
        .gap_3()
        .p_4()
        .child(text("Release notes").font_weight(FontWeight::SEMIBOLD))
        .child(text_view().markdown(notes))
        .child(
            view()
                .flex_row()
                .gap_2()
                .child(text("Updated").select_none().text_color(rgb(0x737373)))
                .child(text("October 21")),
        )
}
```

```tsx
import { Text, View } from "nsh";
import { TextView } from "nsh/base";

function ReleaseNotes(props: { notes: string }) {
  return (
    <View selectable class="gap-3 p-4">
      <Text class="font-semibold">Release notes</Text>
      <TextView markdown={props.notes} />
      <View class="flex-row gap-2">
        <Text style={{ userSelect: "none" }} class="text-neutral-500">Updated</Text>
        <Text>October 21</Text>
      </View>
    </View>
  );
}
```

The view's layout and look are the app's styles, and its content is its children. The selection itself is the
platform's: the view draws nothing of its own for it.

## A chat transcript

A transcript in one selectable view selects as one page: a drag starts in one reply and ends in another, and Copy
takes the text of every message in between.

```rust
use nsh_base::text_view;
use nsh_core::prelude::*;

fn transcript(replies: Signal<Vec<SharedString>>) -> impl IntoElement {
    scroll().flex_1().child(
        view().selectable(true).p_4().gap_4().child(each(
            replies,
            |reply: &SharedString| reply.clone(),
            |reply, _index| text_view().markdown(move || reply.get()),
        )),
    )
}
```

```tsx
import { Scroll, View } from "nsh";
import { TextView } from "nsh/base";

<Scroll class="flex-1">
  <View selectable class="gap-4 p-4">
    <Each of={replies}>{(reply) => <TextView markdown={reply()} />}</Each>
  </View>
</Scroll>
```

## How a selection is made

| Platform | How a selection is made |
|---|---|
| macOS, Windows, Linux, GPUI | Drag across the texts; a double click selects a word, a triple click a paragraph, and a drag after them goes on by words or paragraphs. Shift+click extends the selection. Ctrl / Cmd+A selects everything in the view, Ctrl / Cmd+C copies, Escape or a press outside clears. |
| iOS, Android | A long press selects a word; the platform's handles extend it, and its edit menu has Copy and Select All. |
| Web | The browser's own selection, with its gestures, menu and shortcuts. |

## What it selects

- **Texts that stay out**: a text with `userSelect: "none"` (`.select_none()` in Rust, the class `select-none`; a
  label, a button's caption) is skipped by the selection and its gestures.
- **Nested views**: a selectable view inside another is part of the outer one, so one selection covers both.
- **TextView**: a [`TextView`](https://nsh.dev/versions/main/elements/text-view.md) with `selectable` selects as one of its own: its paragraphs, list
  items, cells and code blocks select together. Inside a selectable view it joins the outer selection.
- **Single texts**: a text with `userSelect: "text"` in no selectable view selects on its own, as
  [Text](https://nsh.dev/versions/main/elements/text.md#props) describes.
- **The look** is the platform's highlight in each text's `selectionColor` (`selection:text-*`).
- **A line in several texts**: a Rust component that lays one line out as several texts (a soft-wrapped line of
  code) marks the later parts with `.continues_text(true)`; a copy then gives the line whole, with no line break where
  it was cut, and a triple click selects all of its parts. [`DiffView`](https://nsh.dev/versions/main/elements/diff-view.md) does this for its wrapped lines.
- **Lists**: in a virtualized [List](https://nsh.dev/versions/main/elements/list.md), a selection covers the rows that are mounted; rows recycled out of
  view leave it.

## Related

- [View](https://nsh.dev/versions/main/elements/view.md): the `selectable` prop.
- [Text](https://nsh.dev/versions/main/elements/text.md): `userSelect`, `selectionColor` and the selection of a single text.
- [TextView](https://nsh.dev/versions/main/elements/text-view.md): documents whose blocks select as one.

Source: https://nsh.dev/versions/main/elements/text-selection

---

# If / Each

`If` and `Each` decide which elements exist: conditional and repeated content. They make no native view of their own.
The native renderer updates only what changed: `If` swaps a branch when its condition flips, `Each` adds, moves and
removes rows by key instead of rebuilding the list. Rust has `when(..)`, `each(..)` and `dynamic(..)` in
`nsh_core::prelude`; TSX has `<If>` and `<Each>`, globals that need no import.

```rust
use nsh_core::prelude::*;

view()
    .child(
        when(move || user.with(|u| u.is_some()), move || {
            text(move || format!("Hello, {}", user.with(|u| u.as_ref().map(|u| u.name.clone()).unwrap_or_default())))
        })
        .otherwise(|| text("Signed out")),
    )
    .child(each(todos, |t: &Todo| t.id, |todo, _index| text(move || todo.get().title)))
```

```tsx
<View>
  <If when={user()} else={<Text>Signed out</Text>}>
    {(u) => <Text>Hello, {u().name}</Text>}
  </If>
  <Each of={todos()}>{(todo) => <Text>{todo().title}</Text>}</Each>
</View>
```

In TSX they are globals (a binding of the same name in scope takes their place). Inside JSX expressions you can still
use plain JavaScript (`cond ? a : b`, `items.map(…)`), and in Rust `dynamic(move || ..)`: those make their elements
again every time what they read changes, while `If` and `Each` (`when` and `each` in Rust) keep the elements that stay.

## If

Renders its branch while the condition holds, else the other branch (or nothing).

| Prop | Rust | Type | Description |
|---|---|---|---|
| `when` | `when(cond, ..)` | `T` | The condition: a value, a signal or a closure in Rust; in TSX its truthiness. |
| `else` | `.otherwise(\|\| ..)` | `JSX.Element` | Rendered while `when` does not hold. |
| `children` | `when(.., \|\| ..)` | `JSX.Element` \| `(value: () => NonNullable<T>) => JSX.Element` | Rendered while `when` holds. In TSX, a function gets an accessor of `when`'s value. |

A branch is made when the condition flips to it, and what it made goes when it flips away. A TSX `when` that goes from
one truthy value to another (`user()` changing from one object to another) keeps the branch, and the expressions inside
it update on their own.

```rust
let loading = signal(true);

when(move || !loading.get(), || profile())
    .otherwise(|| text("Loading…").text_color(rgb(0x6e7781)))
```

```tsx
const loading = signal(true);

<If when={!loading()} else={<Text style={{ color: "#6e7781" }}>Loading…</Text>}>
  <Profile />
</If>;
```

In TSX, a function child reads the value `when` gave, without `null` or `undefined` in its type, so the branch needs no
`!`. In Rust, the branch reads the signal itself, or `dynamic` maps the value to elements:

```rust
let user = signal(None::<User>);

dynamic(move || user.get().map(|u| text(u.name)))
```

```tsx
const user = signal<User | null>(null);

<If when={user()}>{(u) => <Text>{u().name}</Text>}</If>;
```

## Each

Renders a row for each item of a list.

| Prop | Rust | Type | Description |
|---|---|---|---|
| `of` | `each(items, ..)` | `readonly any[] \| null \| undefined` | The items: in Rust a `Vec`, a signal of one or a closure returning one. `null` and `undefined` render nothing. |
| `key` | `each(.., \|item\| key, ..)` | `(item: any) => unknown` | The identity of an item. TSX's default: the item itself (objects by identity, primitives by value). |
| `children` | `each(.., .., \|item, index\| row)` | `(item: () => any, index: () => number) => JSX.Element` | Renders one row. |

The row function gets **accessors**, not values: call `item()` and `index()` in TSX, `item.get()` and `index.get()` in
Rust (both are `ReadSignal`s). When the items change, rows whose key is still there are kept (and moved if their position
changed); their item and index update, and only the expressions reading them run again. New keys get new rows; rows
whose key is gone are removed.

```rust
#[derive(Clone, PartialEq)]
struct Todo {
    id: u32,
    title: String,
    done: bool,
}

let todos = signal(Vec::<Todo>::new());

each(todos, |t: &Todo| t.id, |todo, index| {
    view()
        .flex_row()
        .gap_2()
        .child(text(move || format!("{}.", index.get() + 1)))
        .child(
            text(move || todo.get().title)
                .style_when(move || todo.get().done, |s| s.line_through()),
        )
})
```

```tsx
interface Todo {
  id: number;
  title: string;
  done: boolean;
}

const todos = signal<Todo[]>([]);

<Each of={todos()} key={(t: Todo) => t.id}>
  {(todo, index) => (
    <View style={{ flexDirection: "row", gap: 8 }}>
      <Text>{index() + 1}.</Text>
      <Text style={{ textDecorationLine: todo().done ? "line-through" : "none" }}>{todo().title}</Text>
    </View>
  )}
</Each>;
```

### Choosing a key

- Items replaced by new objects on every update (immutable updates, `{ ...t, done: true }`) need a `key`, usually an id.
  Without it each new object is a new row and its elements are made again. Rust always takes a key.
- In TSX, arrays of strings or numbers work without a key: they are compared by value.
- Each row has its own owner: effects and cleanups created in a row end when the row is removed.

> [!NOTE]
> `Each` and `each` are generic: TypeScript infers the item type from `of`, and Rust from the items, so the row's `todo()` and
> the `key` parameter are typed without annotations.

## Each or a list

`Each` creates every row. That is right for tens or a few hundred items, in a view or a [scroll view](https://nsh.dev/versions/main/elements/scroll.md).
For long or unbounded data, use a [list](https://nsh.dev/versions/main/elements/list.md): it creates the rows near the viewport and recycles them.

See [JSX and components](https://nsh.dev/versions/main/docs/jsx-and-components.md) and [reactivity](https://nsh.dev/versions/main/docs/reactivity.md) for how expressions
update.

Source: https://nsh.dev/versions/main/elements/control-flow

---

# Accordion

An accordion stacks sections that expand and collapse under their headings: the questions of an FAQ, the groups of a
settings page, the steps of a checkout. Five parts make it, each owning one piece of behavior and none of the look:

- `Accordion`, the stack: it holds the app's `value`, the values of the open items, and reports the next one with
  `onChange`. One item opens at a time, or several with `multiple`.
- `AccordionItem`, one section, identified by its `value`. It is open while the accordion's `value` holds it.
- `AccordionHeader`, the item's heading, of a `level` screen readers announce.
- `AccordionTrigger`, the button in the heading that expands and collapses its item, and says whether it is expanded.
- `AccordionPanel`, the item's content, shown while it is open; with `reveal` its height springs open and shut.

```rust
use nsh_base::{accordion, accordion_header, accordion_item, accordion_panel, accordion_trigger, theme};
use nsh_core::prelude::*;

const FAQ: [(&str, &str, &str); 2] = [
    ("shipping", "When will my order ship?", "Orders placed before 2 pm leave the same day."),
    ("returns", "How do I return an item?", "Print the label from your order within 30 days."),
];

fn faq() -> impl IntoElement {
    let open = signal(vec![SharedString::from("shipping")]);
    let mut list = accordion()
        .value(open)
        .on_change(move |value: &Vec<SharedString>| open.set(value.clone()));
    for (value, question, answer) in FAQ {
        list = list.child(
            accordion_item()
                .value(value)
                .border_b_1()
                .border_color(move || theme().border)
                .child(
                    accordion_header().child(
                        accordion_trigger()
                            .flex_row()
                            .items_center()
                            .justify_between()
                            .py_3()
                            .child(text(question).font_weight(FontWeight::MEDIUM))
                            .child(text("⌄").transition_transform().rotate(move || {
                                let open = open.get().iter().any(|v| &**v == value);
                                if open { deg(180.0) } else { deg(0.0) }
                            })),
                    ),
                )
                .child(
                    accordion_panel()
                        .reveal(true)
                        .accessibility_label(question)
                        .child(view().pb_3().child(text(answer).text_color(move || theme().muted_foreground))),
                ),
        );
    }
    list
}
```

```tsx
import { mount, signal, Text, View } from "nsh";
import { Accordion, AccordionHeader, AccordionItem, AccordionPanel, AccordionTrigger } from "nsh/base";

const FAQ = [
  { value: "shipping", question: "When will my order ship?", answer: "Orders placed before 2 pm leave the same day." },
  { value: "returns", question: "How do I return an item?", answer: "Print the label from your order within 30 days." },
];

function App() {
  const open = signal(["shipping"]);
  return (
    <Accordion value={open()} onChange={({ value }) => open.set(value)}>
      {FAQ.map((item) => (
        <AccordionItem value={item.value} class="border-b border-border">
          <AccordionHeader>
            <AccordionTrigger class="group flex-row items-center justify-between py-3 active:opacity-70">
              <Text class="font-medium">{item.question}</Text>
              <Text class="transition-transform group-aria-expanded:rotate-180">⌄</Text>
            </AccordionTrigger>
          </AccordionHeader>
          <AccordionPanel reveal accessibilityLabel={item.question}>
            <View class="pb-3">
              <Text class="text-muted-foreground">{item.answer}</Text>
            </View>
          </AccordionPanel>
        </AccordionItem>
      ))}
    </Accordion>
  );
}

mount(App);
```

The parts come from [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md), the `nsh-base` crate in Rust. The value is the app's: a
trigger's press reports the next `value` with `onChange`, and the accordion opens the items whose values the app passes
back. Each part finds the one around it on its own, so the app arranges them freely: dividers between the items, a badge
in a heading, an icon before a title. In Rust, `accordion()`, `accordion_item()`, `accordion_header()`,
`accordion_trigger()` and `accordion_panel()` make them, with a setter per prop and `.child(..)` for what is inside.

## Props

### Accordion

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `value` | `.value(..)` | `string[]` | `[]` | The open items' `value`s. The app owns them: a trigger's press reports the next ones with `onChange`, and the accordion shows the ones the app passes back. |
| `multiple` | `.multiple(..)` | `boolean` | `false` | Several items open at once: opening one leaves the others open. Without it, opening an item closes the one that was. |
| `disabled` | `.disabled(..)` | `boolean` | `false` | Every item is disabled: no trigger takes presses, and screen readers say each is dimmed. |
| `children` | `.child(..)` | `JSX.Element` | none | The items, and whatever the app lays out between them (dividers). |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The stack's layout and look: a card around the items, the gap between them. |

### AccordionItem

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `value` | `.value(..)` | `string` | required | What identifies the item in the accordion's `value`: the app's own id, never its title, which changes with the language. |
| `disabled` | `.disabled(..)` | `boolean` | `false` | Its trigger takes no presses, and screen readers say it is dimmed. It stays open or closed as the accordion's `value` says. |
| `children` | `.child(..)` | `JSX.Element` | none | The item's header and panel, and whatever else the app lays out in it. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The section: a divider under it, a card around it. |

### AccordionHeader

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `level` | `.level(..)` | `number` | `3` | The heading's level among the page's headings, for screen readers (1 the top). |
| `children` | `.child(..)` | `JSX.Element` | none | The item's trigger, and whatever else the header holds (a badge, an action of its own). |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The heading's layout. |

### AccordionTrigger

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `expandedStyle` | `.expanded_style(\|s\| ..)` | `StyleProp<ViewStyle>` | none | The trigger's style while its item is open, as `aria-expanded:` classes. |
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | none | What screen readers say, when the children have no text that says it. |
| `children` | `.child(..)` | `JSX.Element` | none | The title and the chevron; `group-aria-expanded:` classes inside follow the trigger with `group` on its `class`. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The trigger itself: the row the user presses. |
| `activeStyle`, `hoverStyle`, `focusStyle`, `disabledStyle` | `.active(\|s\| ..)`, `.hover(..)`, `.focus(..)`, `.disabled_style(..)` | `StyleProp<ViewStyle>` | none | The trigger's style while pressed, hovered, focused or disabled, as the `<state>:` classes. |

### AccordionPanel

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `reveal` | `.reveal(..)` | `boolean` | `false` | Opens and closes with a reveal, as `Collapsible`'s: the panel clips its content and its height springs from zero to the content's own and back, critically damped (about 265 ms, no overshoot), and the items after it move along. With reduced motion it opens and closes at once. |
| `keepMounted` | `.keep_mounted(..)` | `boolean` | `false` | The content stays in the tree while the item is closed, out of sight, of the keyboard focus and of screen readers: a video keeps its place, a web view its page. Without it the content leaves the tree as the panel closes (once the reveal has closed it) and comes back as it was. |
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | none | What screen readers call the region: usually the item's title, as its header says it. |
| `children` | `.child(..)` | `JSX.Element` | none | The content. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The region's layout and look. With `reveal` the panel is in the layout while closed, zero high, so its padding and borders go on a view of its content. |

## Events

| Event | Rust | Description |
|---|---|---|
| `onChange({ value })` (`Accordion`) | `.on_change(\|value: &Vec<SharedString>\| ..)` | A trigger was pressed: a tap, a click, Space or Return while it has the keyboard focus, or a screen reader's activation. `value` is the open items' values as they would be: an open item's value leaves it, a closed one's joins it at the end, or, without `multiple`, replaces it. It runs before anything changes: set `value` to follow it. |

## Parts

| Part | Inside | Styled with | States |
|---|---|---|---|
| The stack | | `Accordion`'s `class`, `style` | |
| An item | the stack | `AccordionItem`'s `class`, `style` | the app's value |
| The heading | the item | `AccordionHeader`'s `class`, `style` | |
| The trigger | the heading | `AccordionTrigger`'s `class`, `style` | `aria-expanded:`, `disabled:`, `active:`, `hover:`, `focus:` (or `expandedStyle`, `disabledStyle`, ...) |
| The title and chevron | the trigger | their own elements (`children`) | `group-aria-expanded:`, `group-disabled:` with `group` on the trigger's `class` |
| The panel | the item, after the heading | `AccordionPanel`'s `class`, `style` | |
| The content | the panel | its own elements (`children`) | |

Without `reveal`, a closed panel is out of the layout and its content out of the tree. With `reveal`, the change is a
layout animation of the commit that changes `value` (as `LayoutAnimation.configureNext`, run natively, so no
JavaScript runs while it moves): the opening panel grows from zero to its content's height, the closing one shrinks
back, both in the same spring, and the items after them move along. A transition of the app's goes with it: the
chevron turns (`transition-transform group-aria-expanded:rotate-180`).

## Disabled

A disabled item's trigger takes no presses, and screen readers announce it as dimmed; `disabled:` classes on the
trigger and `group-disabled:` inside it follow. The accordion's `disabled` disables every item. A disabled item still
shows what the app's `value` says: the app can open it.

## Accessibility

- The stack is a group, each header a heading of its `level`, and each trigger a button inside it that says whether
  its item is expanded. Screen readers can move from heading to heading.
- An open panel is a region, named by its `accessibilityLabel`; a closed one is hidden from screen readers, kept
  content included.
- The look of the open item is the app's, and should not rest on color alone: turn the chevron, as the examples do.

See [Accessibility](https://nsh.dev/versions/main/docs/accessibility.md) for labels, roles and announcements in general.

## Keyboard

Where views that take presses are stops of the keyboard focus (macOS and the web), each trigger is a stop, in the
order of the page, and Space and Return press it. Disabled triggers are skipped, and so is the content of a closed
panel. Tab moves from a trigger into its open panel's controls and on to the next trigger.

## Platform notes

- Every platform shows an open item's panel under its heading and leaves a closed one out of the layout (zero high
  with `reveal`).
- With `reveal`, every platform springs the panels' heights on its own animator (iOS, Android, macOS, Windows, Linux,
  GPUI and the web), and opens and closes them at once while the system asks for reduced motion.
- Each platform's screen reader hears the heading and its level as it reads headings, and the trigger inside it as
  a button with its expanded state; on iOS, VoiceOver reads the trigger itself.
- iOS, Android and Mac Catalyst: a trigger's press is a tap. Desktops (macOS, Windows, Linux, GPUI) and the web: a
  click, and Space or Return on the focused trigger on macOS and the web.

Source: https://nsh.dev/versions/main/elements/accordion

---

# AlertDialog

`AlertDialog` shows the platform's own alert or action sheet: `UIAlertController` on iOS and Mac Catalyst, an
`AlertDialog` (or a list dialog for an action sheet) on Android, and an alert in the platform's dialog look on the
other platforms. `AlertDialog.show` (`alert_dialog()`'s `.show()` in Rust) returns a promise (a future in Rust) that resolves with `{ action }`: the `id` of the action the user chose.
Every label comes from the app, so an alert says what your app says, in its language.

```rust
use nsh_base::{alert_dialog, button};
use nsh_core::prelude::*;

fn app() -> impl IntoElement {
    let answer = signal(SharedString::from("–"));
    let confirm = move || {
        spawn(async move {
            let choice = alert_dialog()
                .title("Delete the photo?")
                .description("This cannot be undone.")
                .cancel("cancel", "Cancel")
                .destructive("delete", "Delete")
                .show()
                .await;
            let deleted = matches!(choice, Ok(r) if r.action.as_deref() == Some("delete"));
            answer.set(if deleted { "deleted" } else { "kept" }.into());
        });
    };
    view()
        .flex_1()
        .p_4()
        .pt(px(48.0))
        .gap_3()
        .child(
            button()
                .on_press(confirm)
                .rounded_lg()
                .bg(rgb(0xdc2626))
                .px_4()
                .py_3()
                .child(text("Delete…").text_color(white()).font_weight(FontWeight::SEMIBOLD)),
        )
        .child(text(answer))
}
```

```tsx
import { mount, signal, Text, View } from "nsh";
import { AlertDialog, Button } from "nsh/base";

function App() {
  const answer = signal("–");
  const confirm = async () => {
    const { action } = await AlertDialog.show({
      title: "Delete the photo?",
      description: "This cannot be undone.",
      actions: [
        { label: "Cancel", role: "cancel", id: "cancel" },
        { label: "Delete", role: "destructive", id: "delete" },
      ],
    });
    answer.set(action === "delete" ? "deleted" : "kept");
  };
  return (
    <View style={{ flex: 1, padding: 16, paddingTop: 48, gap: 12 }}>
      <Button onPress={confirm} class="rounded-lg bg-red-600 px-4 py-3 active:bg-red-700">
        <Text class="text-center font-semibold text-white">Delete…</Text>
      </Button>
      <Text>{answer()}</Text>
    </View>
  );
}

mount(App);
```

For dialogs with a look of your own (a card, a sheet, a full-screen flow), use [Dialog](https://nsh.dev/versions/main/elements/dialog.md).

## AlertDialog.show

```ts
AlertDialog.show(options: AlertDialogOptions): Promise<AlertDialogResult>
```

```rust
alert_dialog().title(..).description(..).action(..).cancel(..).destructive(..).show()
    -> impl Future<Output = Result<AlertDialogResult, String>>
```

The result is `{ action }` (`AlertDialogResult`): the chosen action's `id`, or `null` (`None`) when the dialog closed
without an action: a press outside it, Escape or the back button, where
`closeOnBackdropPress` and `closeOnEscape` allow it. Without actions the promise rejects with a `TypeError` (an `Err`
in Rust). In Rust, `nsh_base::alert_dialog()` sets the dialog up with a method per option and per action, in the order
the actions show, and `.show()` shows it; await its answer in a task (`spawn`).

## Action sheets

An action sheet takes the same options with the `"actionSheet"` presentation:

```rust
use nsh_base::alert_dialog;
use nsh_core::prelude::*;

fn share() {
    spawn(async move {
        let choice = alert_dialog()
            .title("Share the photo")
            .action_sheet()
            .action("copy", "Copy link")
            .action("save", "Save")
            .destructive("delete", "Delete")
            .cancel("cancel", "Cancel")
            .show()
            .await;
        match choice.ok().and_then(|r| r.action).as_deref() {
            Some("copy") => { /* … */ }
            Some("save") => { /* … */ }
            Some("delete") => { /* … */ }
            _ => {} // "cancel", or closed without an action.
        }
    });
}
```

```tsx
const { action } = await AlertDialog.show({
  title: "Share the photo",
  presentation: "actionSheet",
  actions: [
    { label: "Copy link", id: "copy" },
    { label: "Save", id: "save" },
    { label: "Delete", role: "destructive", id: "delete" },
    { label: "Cancel", role: "cancel", id: "cancel" },
  ],
});
```

## AlertDialogOptions

| Field | Rust | Type | Default | Description |
|---|---|---|---|---|
| `title` | `.title(..)` | `string \| null` | none | Above the description. |
| `description` | `.description(..)` | `string \| null` | none | Below the title. |
| `actions` | `.action(..)`, `.cancel(..)`, `.destructive(..)`, one per action | `AlertDialogAction[]` | required | The actions, in order (at least one; at most three in an Android alert). |
| `presentation` | `.action_sheet()` | `"alert" \| "actionSheet"` | `"alert"` | An alert in the middle, or a sheet of actions from the bottom (a list dialog on Android). |
| `closeOnEscape` | `.close_on_escape(..)` | `boolean \| null` | `false` for an alert, `true` for an action sheet | Escape and the Android back button close it without an action. |
| `closeOnBackdropPress` | `.close_on_backdrop_press(..)` | `boolean \| null` | `false` for an alert, `true` for an action sheet | A press outside it closes it without an action. |

## AlertDialogResult

| Field | Rust | Type | Description |
|---|---|---|---|
| `action` | `action` | `string \| null` (`Option<SharedString>`) | The chosen action's `id`, or `null` when the dialog closed without an action. |

## AlertDialogAction

| Field | Rust | Type | Default | Description |
|---|---|---|---|---|
| `id` | the method's first argument | `string` | required | What `show` reports as `action` when it is chosen: the app's name for it, which stays the same whatever language the labels are in. |
| `label` | the method's second argument | `string` | required | What it says. |
| `role` | `.action(..)`, `.cancel(..)`, `.destructive(..)` | `"default" \| "cancel" \| "destructive"` | `"default"` | What it means: the platform places and draws it by its role (a destructive action is red on iOS). |

> [!TIP]
> Because the main thread never waits for JS or Rust, the dialog is shown and answered natively, and your code
> continues when the result arrives. You can await an alert dialog inside any event handler, for example to confirm
> leaving a page with [`popOnBack`](https://nsh.dev/versions/main/elements/nav-stack.md#leaving-a-page).

## Platform notes

- **iOS**: `UIAlertController` lays out the actions. An action with the `"cancel"` role is placed where iOS puts
  cancel actions, and an action sheet shows it separately at its bottom. On iPad and Mac Catalyst the action sheet is
  a popover, with an untitled cancel action: a tap outside it closes it, and `action` is `null`.
- **Android**: an `AlertDialog` shows up to three actions, mapped by position: the last action is the positive
  button, the one before it the negative button, and the one before that the neutral button. An action sheet is a
  list of the actions in a dialog, with a tap outside or the back button in place of its cancel action (`action` is
  then `null`). The list dialog shows the `title`, or the `description` when the sheet has no title.
- **Windows, Linux, GPUI and the web**: NSH draws the alert or action sheet in the platform's dialog look.

Source: https://nsh.dev/versions/main/elements/alert-dialog

---

# Avatar

An avatar shows a person's picture: a member of a team, the author of a comment, the account in a header. Until the
picture has loaded, when it fails and when there is none, it shows a fallback: the initials of the person's `name`, or
the app's own content (an icon). It owns the picture's loading state, run natively from the image's own load and error
events with no JavaScript, and what screen readers get: an image labelled with the person's name. The look is the
app's: an `Avatar` has no size, shape, colors or font of its own. An `AvatarGroup` shows the first few avatars of a
row and an overflow that stands for the others ("+5").

```rust
use nsh_base::{avatar, theme};
use nsh_core::prelude::*;

fn author(name: &'static str, picture: &'static str) -> impl IntoElement {
    avatar()
        .src(picture)
        .name(name)
        .size(px(40.0))
        .image_style(|s| s.rounded_full())
        .fallback_style(|s| {
            s.rounded_full()
                .items_center()
                .justify_center()
                .bg(move || theme().muted)
                .text_color(move || theme().muted_foreground)
                .text_sm()
        })
}
```

```tsx
import { mount } from "nsh";
import { Avatar } from "nsh/base";

function App() {
  return (
    <Avatar
      src="https://example.com/ada.png"
      name="Ada Lovelace"
      class="size-10"
      imageClass="rounded-full"
      fallbackClass="items-center justify-center rounded-full bg-muted text-sm text-muted-foreground"
    />
  );
}

mount(App);
```

`Avatar` and `AvatarGroup` come from [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md), the `nsh-base` crate in Rust. In Rust,
`avatar()` and `avatar_group()` make them with a setter per prop (`.src(..)`, `.fallback_delay(..)`), the typed style
methods for the avatar itself and `.child(..)` for what sits over the picture.

## Props

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `src` | `.src(..)` | `string \| ImageAsset` | none | The picture, as [`<Image>`](https://nsh.dev/versions/main/elements/image.md)'s `src` takes it: a URL, an `asset:/` or `data:` URI, a `blob:` URL (a photo the user picked: `URL.createObjectURL(file)`), or an imported image. It shows once it has loaded; an empty string is no picture. |
| `name` | `.name(..)` | `string` | none | The person's name: what screen readers say, and the initials the fallback shows when the app passes no `fallback`. |
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | `name` | What screen readers say, over `name`. `""` makes the avatar decorative, hidden from screen readers. |
| `fallbackDelay` | `.fallback_delay(..)` | `number` (ms) | `0` | How long the fallback waits while the picture loads, so a picture that loads quickly shows without the fallback flashing first. `Infinity`: no fallback while it loads, only when it fails or is missing. |
| `imageClass`, `imageStyle` | `.image_style(\|s\| ..)` | `string`, `StyleProp<ViewStyle>` | none | The picture: its fit, radius and motion. |
| `fallbackClass`, `fallbackStyle` | `.fallback_style(\|s\| ..)` | `string`, `StyleProp<ViewStyle>` | none | The fallback: its background, text color and size, and how it aligns its content. |
| `fallback` | `.fallback(..)` | `JSX.Element` | the initials | The fallback's content in place of the initials: an icon, a placeholder for someone without a name. |
| `children` | `.child(..)` | `JSX.Element` | none | What shows over the picture: a presence dot, a badge. Screen readers hear the avatar's label, not these (see [Accessibility](#accessibility)). |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The avatar itself: its size and shape. |

| Event | Rust | Payload | Description |
|---|---|---|---|
| `onStatusChange` | `.on_status_change(..)` | `{ status: AvatarStatus }` | The picture's status changed: `"idle"` (no `src`), `"loading"`, `"loaded"` or `"error"`. |

## Parts

| Part | Inside | Styled with |
|---|---|---|
| The avatar | | `class`, `style` |
| The fallback | the avatar, first, as large as it; there while the picture loads (after `fallbackDelay`), fails or is missing | `fallbackClass`, `fallbackStyle`; its content the initials or `fallback` |
| The picture | the avatar, over the fallback, filling it | `imageClass`, `imageStyle` |
| The app's content | the avatar, last | its own elements (`children`) |

Give the avatar its size (`class="size-10"`): the fallback and the picture fill it, so the fallback leaving lays
nothing out again. The picture is laid out from the start, transparent, and turns opaque once it has loaded; the fallback then leaves.
A `transition-opacity` in `imageClass` fades it in (reduced motion shows it at once). Round the picture and the
fallback (`rounded-full` on each) rather than clipping the avatar, so a presence dot placed at its edge
(`absolute bottom-0 right-0`) stays whole.

The initials are the first letters of the name's first two words, in upper case ("Ada Lovelace" is "AL"); a single
word gives its first two letters ("huacnlee" is "HU"), and a name in a script without letter case its first character
("王小明" is "王").

## Groups

```tsx
import { Text } from "nsh";
import { Avatar, AvatarGroup } from "nsh/base";

<AvatarGroup
  limit={3}
  total={members.length}
  accessibilityLabel={`${members.length} members`}
  class="flex-row"
  overflowClass="-ml-2 size-8 items-center justify-center rounded-full bg-muted ring-2 ring-background"
  overflowAccessibilityLabel={`${members.length - 3} more people`}
  overflow={<Text class="text-xs">{`+${members.length - 3}`}</Text>}
>
  <Each of={members.slice(0, 3)} key={(m) => m.id}>
    {(m, i) => <Avatar src={m().picture} name={m().name} class={i() > 0 ? "-ml-2 size-8" : "size-8"} />}
  </Each>
</AvatarGroup>
```

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `limit` | `.limit(..)` | `number` | `3` | At most this many of its avatars show, the first ones; the others make no views. |
| `total` | `.total(..)` | `number` | the number of children | How many people the group stands for, when the app passes only the first of them. |
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | none | What screen readers say of the group. |
| `overflowClass`, `overflowStyle` | `.overflow_style(\|s\| ..)` | `string`, `StyleProp<ViewStyle>` | none | The overflow part, after the avatars shown. |
| `overflow` | `.overflow(..)` | `JSX.Element` | none | What stands for the people not shown ("+5", "⋯"), there while more than the avatars shown are in the group. |
| `overflowAccessibilityLabel` | `.overflow_accessibility_label(..)` | `string` | none | What screen readers say of the overflow in place of its content: "5 more people" for a "+5". |
| `children` | `.child(..)` | `JSX.Element` | none | The avatars, in order. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The row: its direction (`flex-row`) and spacing. |

The overlap, the rings and the overflow's shape are the app's: a negative margin on every avatar after the first
(`-ml-2`) stacks them, and a ring of the background's color separates them. For a long list, pass the first `limit`
people and `total`: only the avatars shown are made. The count the overflow stands for is `total` less the avatars
shown, which are the fewer of the children and `limit`: `total={8}` with two children shows two avatars and "+6".

## Accessibility

- An avatar is one image for screen readers, labelled with `accessibilityLabel` or `name`: the name is said once. The
  fallback and the picture are hidden from them, so the initials are not read apart. An avatar with neither, or with `accessibilityLabel=""`, is decorative: hidden from screen readers, as an
  avatar beside the name it shows should be.
- A group is a group, labelled with its `accessibilityLabel` ("Ada, Grace and 5 others"); the avatars shown are images
  inside it. The overflow is read as its content ("+5"), or as `overflowAccessibilityLabel` ("5 more people") when the
  app gives one: NSH writes no words of its own.
- An avatar is one element for screen readers, so what its children show is not read apart, and on iOS a button or
  a link among them cannot be reached at all. Say what a presence dot or a badge means in `accessibilityLabel` ("Ada
  Lovelace, online"), and put what can be pressed beside the avatar, not inside it.
- Neither takes presses or keyboard focus: put an avatar in a `Button` to make it one.

See [Accessibility](https://nsh.dev/versions/main/docs/accessibility.md) for labels, roles and announcements in general.

## Platform notes

- Every platform loads the picture with its own image loader and caches (see [Image](https://nsh.dev/versions/main/elements/image.md)); its load and error
  events change the avatar's state in Rust, so a loading or failed picture changes the picture and the fallback and
  nothing else.
- The picture starts loading once it has a frame, so it stays laid out while transparent.

Source: https://nsh.dev/versions/main/elements/avatar

---

# Button

A button is a press target. It owns the behavior: presses, press feedback through the app's state styles, the
disabled and selected states, keyboard focus, and its role for screen readers. The look is the app's: a `Button` has no colors, sizes, paddings or label of its own, so one component becomes a primary button,
an icon button, a tab, a toolbar toggle or the row of a list, depending on the styles and children you give it.

```rust
use nsh_base::button;
use nsh_core::prelude::*;

fn counter() -> impl IntoElement {
    let count = signal(0_u32);
    button()
        .on_press(move || count.update(|n| *n += 1))
        .self_center()
        .px_5()
        .py_3()
        .rounded_xl()
        .bg(rgb(0x2563eb))
        .active(|s| s.bg(rgb(0x1d4ed8)))
        .child(
            text(move || format!("Pressed {}", count.get()))
                .text_color(white())
                .font_weight(FontWeight::SEMIBOLD),
        )
}
```

```tsx
import { mount, signal, Text } from "nsh";
import { Button } from "nsh/base";

function App() {
  const count = signal(0);
  return (
    <Button
      onPress={() => count.update((n) => n + 1)}
      class="self-center rounded-xl bg-blue-600 px-5 py-3 active:bg-blue-700"
    >
      <Text class="text-base font-semibold text-white">{`Pressed ${count()}`}</Text>
    </Button>
  );
}

mount(App);
```

`Button` comes from [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md), the `nsh-base` crate in Rust. In TSX its look is `class` and
`style`, with the state variants `active:`, `hover:`, `focus:`, `selected:` and `disabled:` (or the matching
`activeStyle`, `hoverStyle`, `focusStyle`, `selectedStyle` and `disabledStyle`). In Rust, `button()` makes one as
`view()` makes a view: a setter per prop (`.disabled(..)`, `.selected(..)`), a listener per event (`.on_press(..)`),
the typed style methods (`.px_4()`, `.bg(..)`) for its look, the state methods (`.active(..)`, `.hover(..)`,
`.focus(..)`, `.selected_style(..)`, `.disabled_style(..)`) for its states and `.child(..)` for its content.

## Props

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `disabled` | `.disabled(..)` | `boolean` | `false` | No presses and no press feedback; `disabled:` styles apply and screen readers say it is dimmed. |
| `selected` | `.selected(..)` | `boolean` | `false` | Selected: a toggle that is on, the current tab. Screen readers say so. The app owns the value and styles it. |
| `selectedStyle` | `.selected_style(\|s\| ..)` | `StyleProp<ViewStyle>` | none | The style while `selected` and not disabled, as `selected:` classes. |
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | none | What screen readers say when the content is not enough, as for an icon. |
| `role` | `.role(..)` | `AccessibilityRole` | `"button"` | What it is for screen readers when no `nsh/base` component is that control: `"link"` (it opens a URL), ... |
| `hitSlop` | `.hit_slop(..)` | `number \| Partial<Edges>` | none | How far outside its bounds presses still count, in points: one number for every side, or the sides named. As a view's `hitSlop`. |
| `children` | `.child(..)` | `JSX.Element` | none | The content: text, an icon, any layout. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | Its look, all of it. |
| `activeStyle`, `hoverStyle`, `focusStyle`, `disabledStyle` | `.active(\|s\| ..)`, `.hover(..)`, `.focus(..)`, `.disabled_style(..)` | `StyleProp<ViewStyle>` | none | The style while pressed, hovered, focused or disabled, as the `<state>:` classes. Later states win; `disabled` wins over all. |

In Rust each prop is a setter that takes a value, a signal or a closure; the props you leave out keep their defaults:

```rust
button()
    .disabled(move || saving.get())
    .accessibility_label("Save")
```

## Events

| Event | Rust | Description |
|---|---|---|
| `onPress` | `.on_press(\|\| ..)` | The button was pressed: a tap, a click, Return or Space while it has the keyboard focus, or a screen reader's activation. |
| `onPressDown` | `.on_press_down(\|\| ..)` | A press went down on it. |
| `onPressUp` | `.on_press_up(\|\| ..)` | The press ended: released, moved away or cancelled. |

`onPressDown` and `onPressUp` are for press feedback of your own, such as a spring or a highlight that the state
styles do not express. A disabled button reports none of them.

## Styling

The look of a button is your app's: the app decides what a primary or a secondary button is. A pair of small components keeps
that decision in one place:

```rust
use nsh_base::button;
use nsh_core::prelude::*;

/// A filled button, darker while pressed.
fn primary(label: &'static str, on_press: impl Fn() + 'static) -> impl IntoElement {
    button()
        .on_press(on_press)
        .items_center()
        .rounded_lg()
        .px_4()
        .py_3()
        .bg(rgb(0x2563eb))
        .active(|s| s.bg(rgb(0x1d4ed8)))
        .disabled_style(|s| s.opacity(0.4))
        .child(text(label).text_color(white()).font_weight(FontWeight::SEMIBOLD))
}

/// An outlined button.
fn secondary(label: &'static str, on_press: impl Fn() + 'static) -> impl IntoElement {
    button()
        .on_press(on_press)
        .items_center()
        .rounded_lg()
        .px_4()
        .py_3()
        .border_1()
        .border_color(rgb(0xd4d4d4))
        .hover(|s| s.bg(rgb(0xfafafa)))
        .active(|s| s.bg(rgb(0xf5f5f5)))
        .child(text(label).text_color(rgb(0x171717)))
}
```

```tsx
import { Text } from "nsh";
import { Button } from "nsh/base";

function Primary(props: { label: string; onPress: () => void; disabled?: boolean }) {
  return (
    <Button
      onPress={props.onPress}
      disabled={props.disabled}
      class="items-center rounded-lg bg-blue-600 px-4 py-3 active:bg-blue-700 disabled:opacity-40"
    >
      <Text class="font-semibold text-white">{props.label}</Text>
    </Button>
  );
}

function Secondary(props: { label: string; onPress: () => void }) {
  return (
    <Button
      onPress={props.onPress}
      class="items-center rounded-lg border border-neutral-300 px-4 py-3 active:bg-neutral-100 hover:bg-neutral-50"
    >
      <Text class="text-neutral-900">{props.label}</Text>
    </Button>
  );
}
```

The state variants are applied natively: a press darkens the button on the main thread with no JS or Rust running.
In Rust the state methods are the same variants: `.active(..)`, `.hover(..)`, `.focus(..)`, `.selected_style(..)` and
`.disabled_style(..)` follow the button's own states. Your theme's colors work the same way: `bg-primary` in TSX,
`theme().primary` in Rust (see [Theme tokens](https://nsh.dev/versions/main/docs/tailwind.md#theme-tokens)).

## Disabled

A disabled button takes no presses and gives no feedback, and screen readers announce it as dimmed. Its look while
disabled is yours, with `disabled:` classes or `disabledStyle`:

```rust
fn save(saving: Signal<bool>) -> impl IntoElement {
    button()
        .disabled(saving)
        .on_press(move || saving.set(true))
        .rounded_lg()
        .px_4()
        .py_3()
        .bg(rgb(0x2563eb))
        .disabled_style(|s| s.opacity(0.4))
        .child(text("Save").text_color(white()))
}
```

```tsx
<Button disabled={saving()} onPress={save} class="rounded-lg bg-blue-600 px-4 py-3 disabled:opacity-40">
  <Text class="text-white">Save</Text>
</Button>
```

## A toggle with selected

`selected` makes a button a toggle: a toolbar's bold button, a filter chip, the current tab. The app holds the value,
flips it in `onPress` and styles the selected state; screen readers announce the button as selected.

```rust
fn bold(on: Signal<bool>) -> impl IntoElement {
    button()
        .selected(on)
        .accessibility_label("Bold")
        .on_press(move || on.update(|on| *on = !*on))
        .size(px(40.0))
        .items_center()
        .justify_center()
        .rounded_md()
        .selected_style(|s| s.bg(rgb(0xdbeafe)))
        .child(text("B").font_weight(FontWeight::BOLD))
}
```

```tsx
<Button
  selected={bold()}
  onPress={() => bold.set(!bold())}
  accessibilityLabel="Bold"
  class="size-10 items-center justify-center rounded-md selected:bg-blue-100"
>
  <Text class="font-bold">B</Text>
</Button>
```

A row of tabs is [`Tabs`](https://nsh.dev/versions/main/elements/tabs.md) and an on / off control is [`Switch`](https://nsh.dev/versions/main/elements/switch.md), from `nsh/base`: they own the role, the selected state and the keyboard of their kind, which a `Button` with `role="tab"` or `role="switch"` does not.

## A small target with hitSlop

An icon button can be smaller than a finger. `hitSlop` makes presses that land near it count, in points past each side,
without changing its layout or its look: one number for every side, or the sides named (`{ top: 8, bottom: 8 }`), as
a [view's `hitSlop`](https://nsh.dev/versions/main/elements.md#presses-and-feedback) takes them.

```rust
fn close(open: Signal<bool>) -> impl IntoElement {
    button()
        .hit_slop(EdgeInsets::all(px(12.0)))
        .accessibility_label("Close")
        .on_press(move || open.set(false))
        .size(px(20.0))
        .items_center()
        .justify_center()
        .child(text("×"))
}
```

```tsx
<Button hitSlop={12} accessibilityLabel="Close" onPress={() => open.set(false)} class="size-5 items-center justify-center">
  <Text>×</Text>
</Button>
```

## Accessibility

- A button is one element for screen readers, with the role `"button"` unless `role` says otherwise. Its label is its
  text content; give `accessibilityLabel` when the content is an icon or says too little.
- `disabled` and `selected` are announced as the platform announces them (VoiceOver, TalkBack, UI Automation, the
  browser's accessibility tree).
- On macOS and the web a button is a stop of the keyboard focus: Tab reaches it, Return and Space press it, and
  `focus:` styles show where the focus is.

See [Accessibility](https://nsh.dev/versions/main/docs/accessibility.md) for labels, roles and announcements in general.

## Platform notes

- iOS, Android and Mac Catalyst: a press is a tap that ends on the button; moving away cancels it, as with the
  system's own buttons.
- Desktops (macOS, Windows, Linux, GPUI) and the web: a press is a click. On macOS and the web, Return and Space also
  press the button that has the keyboard focus. `hover:` styles apply under a mouse or a trackpad's pointer.
- Every platform draws what the app styles: press feedback is `active:` / `activeStyle` or an animation of your own.

Source: https://nsh.dev/versions/main/elements/button

---

# Calendar

A calendar picks a date, or with `range` a range of dates, from months of days laid out in weeks: a due date in a
form, the nights of a stay, the days of a report. It shows one month or several side by side, turns the months with
Previous and Next, and switches to a view of the year's months or a page of years to go far. It is the calendar in
[DatePicker](https://nsh.dev/versions/main/elements/date-picker.md)'s popup, on its own in the page.

The calendar owns the behavior: the value (the app's, or its own), the shown month, the views, the days that cannot
be picked, the keyboard and what screen readers hear. The look is the app's: it styles the header, the body, each
month, each row and each item, and draws the items' content (the months' and weekdays' names, today's mark, the
range's band). The grid fills the width it is given, as a table's columns do: the months share it and the items of a
row share the row equally, so a calendar in a phone's sheet spans the screen and one in a popup sized to its content
keeps its items' widths (`flex-none` in `itemClass` or `monthClass` keeps an item or a month at its own width).

```rust
use nsh_base::{CalendarEntry, CalendarItemKind, Date, Matcher, calendar};
use nsh_core::prelude::*;

const MONTHS: [&str; 12] = [
    "January", "February", "March", "April", "May", "June",
    "July", "August", "September", "October", "November", "December",
];
const WEEKDAYS: [&str; 7] = ["Su", "Mo", "Tu", "We", "Th", "Fr", "Sa"];

fn due_date() -> impl IntoElement {
    let due = signal(Date::default());
    calendar()
        .value(move || due.get())
        .on_change(move |next: &Date| due.set(*next))
        .disabled_matcher(Matcher::DayOfWeek(vec![0, 6]))
        .previous_accessibility_label("Previous month")
        .next_accessibility_label("Next month")
        .item_class("rounded-md selected:bg-primary selected:text-primary-foreground disabled:opacity-50")
        .render_item(|item: &CalendarEntry| {
            let label = match item.kind {
                CalendarItemKind::Previous => "‹".to_string(),
                CalendarItemKind::Next => "›".to_string(),
                CalendarItemKind::Weekday => WEEKDAYS[item.value as usize].to_string(),
                CalendarItemKind::MonthToggle | CalendarItemKind::Month => {
                    MONTHS[item.value as usize - 1].to_string()
                }
                _ => item.value.to_string(),
            };
            view()
                .w_8()
                .h_8()
                .items_center()
                .justify_center()
                .child(text(label).text_sm())
        })
}
```

```tsx
import { mount, signal, Text } from "nsh";
import { Calendar, type CalendarValue } from "nsh/base";

const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
const WEEKDAYS = ["Su", "Mo", "Tu", "We", "Th", "Fr", "Sa"];

function App() {
  const due = signal<CalendarValue>(null);
  return (
    <Calendar
      value={due()}
      onChange={({ value }) => due.set(value)}
      disabledMatcher={[0, 6]}
      previousAccessibilityLabel="Previous month"
      nextAccessibilityLabel="Next month"
      class="w-72 gap-2 rounded-lg border border-border p-3"
      headerClass="flex-row items-center justify-between"
      rowClass="flex-row justify-between"
      itemClass="group h-8 min-w-8 items-center justify-center rounded-md text-sm focus:ring-2 focus:ring-ring selected:bg-primary selected:text-primary-foreground data-range-middle:rounded-none data-range-middle:bg-accent data-range-middle:text-accent-foreground data-outside:text-muted-foreground disabled:opacity-50"
      renderItem={(item) => (
        <Text class={item.today ? "font-semibold" : ""}>
          {item.kind === "weekday"
            ? WEEKDAYS[item.value]
            : item.kind === "month" || item.kind === "monthToggle"
              ? MONTHS[item.value - 1]
              : item.kind === "previous"
                ? "‹"
                : item.kind === "next"
                  ? "›"
                  : String(item.value)}
        </Text>
      )}
    />
  );
}

mount(App);
```

`Calendar` comes from [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md), the `nsh-base` crate in Rust. In Rust, `calendar()` makes
one with a setter per prop (`.value(..)`, `.range(..)`, `.number_of_months(..)`) and a listener per event
(`.on_change(..)`). Its value is a `Date` (`Date::Single`, `Date::Range`, from a `chrono::NaiveDate` or a pair of
them), the days it disables a `Matcher`.

## Value

The value is an ISO date, `"2026-10-28"`, as an HTML `<input type="date">`'s; with `range` it is `[start, end]`, and
`null` is no date. With `value`, the app owns it: the calendar shows it as selected and reports a pick with
`onChange({ value })`; the app sets `value` to follow it. Left out, the calendar keeps its own value, from
`defaultValue` at first.

`onChange` reports complete values only, as `gpui-base`'s `Selected`: a pressed day, or a range's end.

- Without `range`, a press on a day picks it.
- With `range`, the first press starts the range and the second ends it, the days between them in the range (each
  `selected`, its ends included, see [Items](#items)). A second press on an earlier day starts the range over from it,
  as does a press once the range is complete. A half range shows until it is complete and only then is reported.

The calendar opens on the month of the value (a range's start), else today's.

## Months and views

`numberOfMonths` shows that many months side by side, from the shown one on; Previous and Next turn them one month at
a time. `firstDayOfWeek` is the day the weeks start on, `0` Sunday (the default) to `6` Saturday.

The header holds Previous, two toggles and Next:

- The day view shows the months' days, each month a column of its weekdays' row and its weeks; the days of the
  months before and after fill the weeks (`outside`, `data-outside`).
- The month toggle (`monthToggle`) opens the month view: the twelve months, in rows of three. Picking one shows it in
  the day view.
- The year toggle (`yearToggle`) opens the year view: a page of 20 years, in rows of five, Previous and Next turning
  the page. Picking one shows that year in the day view. `yearRange` is the years the pages run through,
  `[start, end)` (default: 50 years before this one to 50 after).

With several months, the header shows each month's title instead of the toggles (a `monthToggle` item that takes no
press), as `gpui-base`'s.

## Disabled dates

`disabledMatcher` is the days the user cannot pick, `gpui-base`'s `Matcher`, in one of four forms:

| Form | Disables |
|---|---|
| `[0, 6]` | Those days of the week, `0` Sunday to `6` Saturday. |
| `{ before, after }` | The days before `before` and after `after` (either left out). |
| `{ from, to }` | The days from `from` to `to`, inclusive (either left out is open). |
| `(date) => boolean` | The days for which the function returns `true`, given each shown day's ISO date. |

The function is asked once per shown day, in the next JS turn, and not again for a day it answered: turning the
months asks only about the days they bring, so its answer is a pure function of the date. Passing another function
asks again. A disabled day is `disabled:`: it takes no press, and Return and Space do not pick it.

## Items

Every press target and label of the calendar is an item: Previous, the toggles, Next, the weekdays, the days, the
months and the years. Each is drawn in a part styled by `itemClass` and `itemStyle`, whose variants follow its state:

| Variant | The item |
|---|---|
| `selected:` | Is selected: the date, every day of a complete range (its ends included, as React Aria's range calendar), a half range's start, the shown month or year, the open view's toggle. Screen readers hear it selected. |
| `disabled:` | Is unavailable: a disabled date, Previous and Next in the month view or at the ends of the years. The weekdays and the months' titles are labels, which screen readers hear as column headers and headers: they take no press and keep their own look. |
| `focus:` | Has the keyboard. |
| `data-range-start:`, `data-range-end:` | Is a complete range's first or last day (a range of one day is both). |
| `data-range-middle:` | Is a day inside a complete range, not an end. |
| `data-today:` | Is today. |
| `data-outside:` | Is a day of the month before or after, filling its weeks. |

The `data-*` variants are Tailwind's (`data-range-start:` matches `[data-range-start]`), as shadcn's calendar styles
its days; with `group` in `itemClass`, the content follows them with `group-selected:`, `group-data-range-middle:`,
and so on. `selected:` means every day of a range, so a range's ends take their look over it (later variants win:
`data-*` comes after `selected:`), and its middle days theirs:

```tsx
<Calendar
  range
  itemClass="group rounded-md selected:bg-primary selected:text-primary-foreground data-range-middle:rounded-none data-range-middle:bg-accent data-range-middle:text-accent-foreground data-range-start:rounded-r-none data-range-end:rounded-l-none data-range-start:data-range-end:rounded-md"
/>
```

`renderItem` draws an item's content from what it is, a `CalendarEntry`, never from its state: the drawing is made
once and kept while the item is selected, focused or put in a range, so the keys, a pick and the focus draw nothing
again, and a turn of the months draws the days it brings once each (a day keeps its drawing by its month and date:
with several months, the months still shown keep theirs).

| Field | Meaning |
|---|---|
| `kind` | `"previous"`, `"monthToggle"`, `"yearToggle"`, `"next"`, `"weekday"`, `"day"`, `"month"` or `"year"`. |
| `value` | Its number: the day of the month, the month (1 to 12), the year, the day of the week (`0` Sunday to `6`); `0` for Previous and Next. |
| `date` | A day's ISO date. |
| `year`, `month` | The year and month it belongs to: a day's (the month whose weeks show it), a month toggle's or title's, a month's of the month view; a year toggle's and a year's own year. `0` for Previous, Next and the weekdays (and `month` for the year toggle and the years). |
| `today` | The day is today. |
| `outside` | The day is of the month before or after. |

Without `renderItem`, an item shows its number, and Previous and Next show `‹` and `›`, as `gpui-base`'s; a weekday
shows its number too, `0` to `6`, since the names of the months and weekdays are the app's words in the app's
language.

## Props

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `value` | `.value(..)` | `CalendarValue` | none | The value, owned by the app. |
| `defaultValue` | `.default_value(..)` | `CalendarValue` | `null` | The value at first, without `value`. |
| `range` | `.range(..)` | `boolean` | `false` | Pick a range: the first press starts it, the second ends it. |
| `numberOfMonths` | `.number_of_months(..)` | `number` | `1` | How many months show side by side. |
| `firstDayOfWeek` | `.first_day_of_week(..)` | `number` | `0` | The day the weeks start on, `0` Sunday to `6` Saturday. |
| `disabledMatcher` | `.disabled_matcher(..)` | `DateMatcher` | none | The dates that cannot be picked. |
| `yearRange` | `.year_range(..)` | `[number, number]` | 50 years either way | The years the year view pages through, `[start, end)`. |
| `previousAccessibilityLabel` | `.previous_accessibility_label(..)` | `string` | none | What screen readers say for Previous. |
| `nextAccessibilityLabel` | `.next_accessibility_label(..)` | `string` | none | What screen readers say for Next. |
| `headerClass`, `headerStyle` | `.header_class(..)`, `.header_style(..)` | `string`, `StyleProp<ViewStyle>` | none | The header: Previous, the toggles (or the months' titles), Next. |
| `bodyClass`, `bodyStyle` | `.body_class(..)`, `.body_style(..)` | `string`, `StyleProp<ViewStyle>` | none | The body: the months side by side, or the month or year view's rows. |
| `monthClass`, `monthStyle` | `.month_class(..)`, `.month_style(..)` | `string`, `StyleProp<ViewStyle>` | none | Each month of the day view. |
| `rowClass`, `rowStyle` | `.row_class(..)`, `.row_style(..)` | `string`, `StyleProp<ViewStyle>` | none | Each row: the weekdays, a week, a row of months or years. |
| `itemClass`, `itemStyle` | `.item_class(..)`, `.item_style(..)` | `string`, `StyleProp<TextStyle>` | none | Each item: `selected:`, `disabled:`, `focus:`; a day's `data-range-start:`, `data-range-end:`, `data-range-middle:`, `data-today:`, `data-outside:` ([Items](#items)). |
| `renderItem` | `.render_item(..)` | `(item: CalendarEntry) => JSX.Element` | none | An item's content, drawn by the app from what the item is; its number otherwise. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The calendar: the header above the body. |

## Events

| Event | Rust | Description |
|---|---|---|
| `onChange` | `.on_change(\|value\| ..)` | The user picked a complete value: `{ value }`, a day or a range. Set `value` to follow it. A `value` the app passes is never reported. |

## Parts

| Part | Where | Styled with |
|---|---|---|
| The calendar | the root | `class`, `style` |
| The header | the calendar, first | `headerClass`, `headerStyle` |
| The body | the calendar, after the header | `bodyClass`, `bodyStyle` |
| A month | the body (day view) | `monthClass`, `monthStyle` |
| A row | a month, or the body (month and year views) | `rowClass`, `rowStyle` |
| An item | the header and the rows | `itemClass`, `itemStyle`, `renderItem` (`group-selected:`, `group-data-range-middle:`, ... inside, under `group` in `itemClass`) |

## Keyboard

The days are one stop of Tab: it lands on the selected day, else today, else the first shown day, passing over
disabled days, which take no focus. Then:

| Key | Action |
|---|---|
| Left / Right | The day before or after. |
| Up / Down | The same day a week before or after. |
| Home / End | The first or last day of the week. |
| Page Up / Page Down | The same day a month before or after. |
| Shift+Page Up / Shift+Page Down | The same day a year before or after. |
| Return, Space | Picks the day. |

In a right-to-left layout the weeks run from the right, so Left is the day after and Right the day before; Up and Down
keep the weeks. A key that reaches a disabled day goes on to the next day that is not, in the direction it moves (Home
and End back toward the day they left). Moving past the shown months turns them. Previous, the toggles, Next, the months and the years take
presses.
`gpui-base`'s days take presses only; the keys are NSH's, after the WAI-ARIA date picker dialog.

## Accessibility

- Each day is a button named by its ISO date, selected while it is the date or a day of the range (its ends included, as
  React Aria's range calendar), dimmed while disabled.
- Previous and Next are buttons named by `previousAccessibilityLabel` and `nextAccessibilityLabel`; the toggles,
  months and years are buttons named by what they show.

See [Accessibility](https://nsh.dev/versions/main/docs/accessibility.md) for labels, roles and announcements in general.

Source: https://nsh.dev/versions/main/elements/calendar

---

# Carousel

A carousel shows slides one place at a time: the photos of a product, the steps of an onboarding, a banner that moves
on by itself, a row of cards. `Carousel` owns the behavior: which slide shows, swiping between them, the previous and
next controls, a pagination, the arrow keys, going around the ends, and what screen readers hear. Its parts find it through
context, so the app arranges them freely in its own layout. The look is the app's: no colors, sizes, arrows, dots or
labels of its own.

The content is a native scroll view. A finger, the wheel and the touchpad move the slides on the platform's main
thread, in the same frame as the pointer, and on release the content snaps to the nearest slide, one slide per fling.
When it comes to rest the carousel reports the slide with `onChange`. The controls, the pagination, the keys and the
app's `index` scroll the content natively to the slide, animated.

```rust
use nsh_base::{
    carousel, carousel_content, carousel_item, carousel_next, carousel_pagination,
    carousel_pagination_item, carousel_previous, theme,
};
use nsh_core::prelude::*;

fn photos() -> impl IntoElement {
    let index = signal(0u32);
    let names = ["Harbor", "Dunes", "Glacier"];
    carousel()
        .index(move || Some(index.get()))
        .on_change(move |i: &u32| index.set(*i))
        .accessibility_label("Photos")
        .gap_3()
        .child(
            carousel_content().w_full().h(px(180.0)).gap_3().child(
                names
                    .iter()
                    .enumerate()
                    .map(|(i, name)| {
                        carousel_item()
                            .accessibility_label(format!("{} of 3: {name}", i + 1))
                            .w_full()
                            .rounded(move || theme().radius)
                            .bg(move || theme().muted)
                            .items_center()
                            .justify_center()
                            .child(text(*name))
                    })
                    .collect::<Vec<_>>(),
            ),
        )
        .child(
            view()
                .flex_row()
                .items_center()
                .gap_2()
                .child(carousel_previous().accessibility_label("Previous photo").child(text("‹")))
                .child(
                    carousel_pagination()
                        .flex_row()
                        .gap_1()
                        .child(
                            (0..3)
                                .map(|i| {
                                    carousel_pagination_item()
                                        .index(i)
                                        .accessibility_label(format!("Photo {}", i + 1))
                                        .size_2()
                                        .rounded_full()
                                        .bg(move || theme().border)
                                        .selected_style(|s| s.bg(move || theme().primary))
                                })
                                .collect::<Vec<_>>(),
                        ),
                )
                .child(carousel_next().accessibility_label("Next photo").child(text("›"))),
        )
}
```

```tsx
import { mount, signal, Text, View } from "nsh";
import {
  Carousel,
  CarouselContent,
  CarouselItem,
  CarouselNext,
  CarouselPagination,
  CarouselPaginationItem,
  CarouselPrevious,
} from "nsh/base";

const NAMES = ["Harbor", "Dunes", "Glacier"];

function App() {
  const index = signal(0);
  return (
    <Carousel index={index()} onChange={({ index: next }) => index.set(next)} accessibilityLabel="Photos" class="gap-3">
      <CarouselContent class="h-[180px] w-full gap-3">
        {NAMES.map((name, i) => (
          <CarouselItem
            accessibilityLabel={`${i + 1} of ${NAMES.length}: ${name}`}
            class="w-full items-center justify-center rounded-(--radius) bg-muted"
          >
            <Text>{name}</Text>
          </CarouselItem>
        ))}
      </CarouselContent>
      <View class="flex-row items-center gap-2">
        <CarouselPrevious accessibilityLabel="Previous photo" class="disabled:opacity-40">
          <Text>‹</Text>
        </CarouselPrevious>
        <CarouselPagination class="flex-row gap-1">
          {NAMES.map((_, i) => (
            <CarouselPaginationItem
              index={i}
              accessibilityLabel={`Photo ${i + 1}`}
              class="size-2 rounded-full bg-border selected:bg-primary"
            />
          ))}
        </CarouselPagination>
        <CarouselNext accessibilityLabel="Next photo" class="disabled:opacity-40">
          <Text>›</Text>
        </CarouselNext>
      </View>
    </Carousel>
  );
}

mount(App);
```

`Carousel` and its parts come from [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md), the `nsh-base` crate in Rust. The slide
shown is the app's `index`: a swipe, a control or a key reports the next one with `onChange`, and the
carousel scrolls to the `index` the app passes back. The slide a swipe rests on shows until the app has answered its
`onChange`: it stays when the app passes it back as `index`, and the content springs back to the app's slide,
animated, when the app keeps the `index` it had. Without `index` the carousel keeps its own, from `defaultIndex`. In Rust,
`carousel()`, `carousel_content()`, `carousel_item()`, `carousel_previous()`, `carousel_next()`,
`carousel_pagination()` and `carousel_pagination_item()` make the parts, with a setter per prop
(`.index(..)`), a listener per event (`.on_change(..)`), the typed style methods and `.child(..)` for their content.

## Props

### Carousel

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `index` | `.index(..)` | `number` | none | The slide shown, from 0, held to the slides there are. The app owns it: changes are reported with `onChange`, and a new `index` scrolls there, animated. |
| `defaultIndex` | `.default_index(..)` | `number` | `0` | The slide shown at first, while `index` is not set. |
| `axis` | `.axis(..)` | `"horizontal" \| "vertical"` | `"horizontal"` | The direction the slides follow each other; read when the carousel is made. A vertical carousel's arrow keys are Up and Down. |
| `looping` | `.looping(..)` | `boolean` | `false` | The slides go around: after the last comes the first, and before the first the last, seamlessly, for a swipe, previous, next, the keys and the app's `index` alike ([Looping](#looping)). Read when the carousel is made. |
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | none | What screen readers call the carousel, a region: what its slides are (`"Featured products"`). |
| `children` | `.child(..)` | `JSX.Element` | none | The `CarouselContent`, the controls and whatever the app lays out around them. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The carousel's layout: where the content and the controls go. |

### CarouselContent

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `children` | `.child(..)` | `JSX.Element` | none | The `CarouselItem`s, each a child of the content. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The viewport's size, and the track the slides make in it: a `gap` between them, padding that shows a peek of the slides beside the one in view. |

### CarouselItem

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | none | What screen readers call the slide, a group: its place among the others and what it shows (`"2 of 5: Ocean view"`). |
| `children` | `.child(..)` | `JSX.Element` | none | The slide's content. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | Its size along the axis (`w-full` for one slide per view, `basis-1/3` for three) and its look. In a carousel that loops, its translation is the carousel's: put a `transform` on a view inside it. |

### CarouselPrevious, CarouselNext

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | none | The control's name, when its children have no text that says it (an arrow icon). |
| `children` | `.child(..)` | `JSX.Element` | none | The app's icon or label. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | Its look and place: beside the content, or `absolute` over its edge. |
| `activeStyle`, `hoverStyle`, `focusStyle`, `disabledStyle` | `.active(\|s\| ..)`, `.hover(..)`, `.focus(..)`, `.disabled_style(..)` | `StyleProp<ViewStyle>` | none | Its style while pressed, hovered, focused, or disabled at an end, as the `<state>:` classes. |

### CarouselPagination

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | none | What screen readers call the group of pagination items (`"Choose a slide"`). |
| `indicatorClass` | `.indicator_class(..)` | `string` | none | The Tailwind classes of the indicator, a view on the item of the slide shown (a pill behind the dots, an underline): its look and its place across the row (`inset-y-0`, `bottom-0 h-0.5`). Along the row it spans that item and springs to the next one natively. |
| `indicatorStyle` | `.indicator_style(\|s\| ..)` | `StyleProp<ViewStyle>` | none | The style of the indicator, over `indicatorClass`. With neither, the pagination has no indicator. |
| `children` | `.child(..)` | `JSX.Element` | none | The `CarouselPaginationItem`s, and whatever the app lays out between them. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The row's layout (`flex-row gap-2`). |

### CarouselPaginationItem

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `index` | `.index(..)` | `number` | required | The slide it shows, from 0. An index past the last slide is disabled. |
| `selectedStyle` | `.selected_style(\|s\| ..)` | `StyleProp<ViewStyle>` | none | Its style while its slide shows, as `selected:` classes. |
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | none | Which slide it shows (`"Slide 3"`), when its children have no text that says it (a dot). |
| `children` | `.child(..)` | `JSX.Element` | none | The app's dot, thumbnail or number. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | Its look; `group-selected:` classes inside it follow it under `group`. |

## Events

| Event | Rust | Description |
|---|---|---|
| `onChange` (`Carousel`) | `.on_change(\|index: &u32\| ..)` | The user moved to another slide: a swipe, the wheel or the touchpad came to rest on it, or a control, a pagination item or a key asked for it. `{ index }` is that slide. A new `index` from the app reports nothing. |
| `onDragStart` (`Carousel`) | `.on_drag_start(\|\| ..)` | The user started dragging the content (a finger, the touchpad). |
| `onDragEnd` (`Carousel`) | `.on_drag_end(\|\| ..)` | The content the user dragged came to rest. |
| `onFocus` (`Carousel`) | `.on_focus(\|\| ..)` | The keyboard focus came into the carousel: to its own view, its previous or next control, a pagination item or a focusable view in a slide. Moving between them reports nothing. |
| `onBlur` (`Carousel`) | `.on_blur(\|\| ..)` | The keyboard focus left the carousel: its own view, its controls, its pagination items and the slides' content. |

## Parts

| Part | Inside | Styled with | States |
|---|---|---|---|
| The carousel | | `Carousel`'s `class`, `style` | `focus:` |
| The content | the carousel | `CarouselContent`'s `class`, `style` | |
| A slide | the content | `CarouselItem`'s `class`, `style` | |
| Previous, next | the carousel | their `class`, `style` | `disabled:`, `active:`, `hover:`, `focus:` |
| The pagination | the carousel | `CarouselPagination`'s `class`, `style` | |
| The indicator | the pagination | `indicatorClass`, `indicatorStyle` | |
| A pagination item | the pagination | its `class`, `style` | `selected:`, `disabled:`, `active:`, `hover:`, `focus:` |

## Several slides per view

A slide's width is its own class's, so a row of cards is several slides in the viewport. Each slide is a snap point
where it starts: the content rests with that slide where the first one rests, so a padding before the first is kept
before each. At the end of the range the slides that cannot reach that place rest with the last one, and next stops
there. `index` names the slide in the first place; the slides that rest with the last one show the same place, and a
swipe there reports the first of them:

```tsx
<Carousel accessibilityLabel="Collections">
  <CarouselContent class="w-full gap-4 px-4">
    <Each of={collections()}>
      {(c) => (
        <CarouselItem class="basis-1/3">
          <Card collection={c()} />
        </CarouselItem>
      )}
    </Each>
  </CarouselContent>
</Carousel>
```

`basis-1/2` at a phone's width, or `basis-[85%]`, shows a peek of the next card. A vertical carousel
(`axis="vertical"`) sizes its slides by their height.

## Looping

With `looping`, the slides go around seamlessly: after the last comes the first, swiped, stepped with next or the
keys, or set by the app's `index`, with no rewind across the slides between. The content keeps room of a whole turn
of slides before and after them, and draws each slide where it is nearest the middle of the view; the animation runs
this on the platform's own frames, with the scroll. Each slide is there once: screen readers and the pagination see
it once.

The loop is seamless while the slides span the viewport and one slide more (three full-width slides, or five a
third wide). With fewer, previous, next and the keys still go around, scrolling back across the slides.

## Slides that move on by themselves

A banner that rolls on is the app's: a timer that sets `index`. The carousel reports when the user is at it, so the
timer waits then, as the [WAI-ARIA carousel pattern](https://www.w3.org/WAI/ARIA/apg/patterns/carousel/) asks:
`onDragStart` / `onDragEnd` around a drag, `onFocus` / `onBlur` while the keyboard focus is in the carousel (on it,
its controls, its pagination or the slides' content), and the pointer over a view around it. Leave it off with reduced motion, and give users a button that stops it (the rotation
control):

```tsx
import { cleanup, effect, reduceMotion, signal, Text, View } from "nsh";
import { Button, Carousel, CarouselContent } from "nsh/base";

const index = signal(0);
const playing = signal(true);
const held = signal(0);
const hold = (on: boolean) => held.set(held() + (on ? 1 : -1));

effect(() => {
  index();
  if (!playing() || held() > 0 || reduceMotion()) return;
  const timer = setInterval(() => index.set((index() + 1) % SLIDES.length), 4000);
  cleanup(() => clearInterval(timer));
});

<View onMouseEnter={() => hold(true)} onMouseLeave={() => hold(false)}>
  <Carousel
    looping
    index={index()}
    onChange={({ index: next }) => index.set(next)}
    onDragStart={() => hold(true)}
    onDragEnd={() => hold(false)}
    onFocus={() => hold(true)}
    onBlur={() => hold(false)}
    accessibilityLabel="Highlights"
  >
    <CarouselContent class="w-full">{/* the slides */}</CarouselContent>
    <Button onPress={() => playing.set(!playing())} class="self-start px-3 py-1">
      <Text>{playing() ? "Pause slides" : "Play slides"}</Text>
    </Button>
  </Carousel>
</View>
```

Reading `index()` in the effect starts a whole interval again after each change, the user's included. With
`looping`, going from the last slide to the first moves forward across the seam.

## Accessibility

- The carousel is a region named by `accessibilityLabel`; each slide is a group named by its own (its place among the
  others and what it shows).
- Previous and next are buttons, disabled at the ends unless the carousel loops; each pagination item is a button,
  selected while its slide shows.
- Every label is the app's, in the app's language.
- A looping carousel's slides are each there once, wherever they are drawn.

See [Accessibility](https://nsh.dev/versions/main/docs/accessibility.md) for labels, roles and announcements in general.

## Keyboard

On macOS and the web, where Tab reaches the views that take presses, the carousel is a stop of the keyboard focus,
and so are its controls and pagination items. While one of them has the focus:

| Key | What it does |
|---|---|
| Left, Right (Up, Down when vertical) | Moves to the previous or the next slide, around the ends while looping. |
| Home, End | Moves to the first or the last slide. |
| Space, Return | Presses the focused control or pagination item. |

In a right-to-left layout a horizontal carousel's slides run from the right, so Left moves to the next slide and Right
to the previous; a vertical carousel keeps Up and Down. A control that turns disabled while it has the focus (next on
the last slide) hands the focus to the carousel, so the keys go on working there. Focusable views of the app's in the
slides keep their own keys: an input's arrows move its caret.

## Motion

- A swipe, the wheel and the touchpad move the slides with the pointer, in the same frame: the platform scrolls them.
- On release the content glides to the nearest slide, one slide per fling, as the platform snaps.
- Previous, next, a pagination item, a key and the app's `index` scroll the content to the slide, animated;
  with reduced motion, at once.
- The pagination's indicator springs to the item of the slide shown; with reduced motion it moves at once.
- `looping` goes from the last slide to the first one step forward, across the seam; once the content rests, it
  moves back by a whole turn without animation, which changes nothing on screen.

## Platform notes

- iOS, Android and Mac Catalyst: a finger swipes the slides; a tap presses a control.
- Desktops (macOS, Windows, Linux, GPUI) and the web: the wheel and the touchpad scroll the slides, and a click
  presses a control. A mouse drag over the content is the app's, as on every scroll view there.
- Every platform draws what the app styles: the slides, the controls, the pagination and its indicator.

Source: https://nsh.dev/versions/main/elements/carousel

---

# Checkbox

A checkbox selects an option, an item of a list, or all of them. It is checked, unchecked or indeterminate (neither:
a "select all" over a partial selection). It owns the behavior: presses, keyboard activation, the disabled state, and
the checkbox role and its value for screen readers. The look is the app's: a `Checkbox` has no box, mark, colors,
sizes or label of its own. It is made of an indicator (the box) with the app's mark inside it, then its children (a
label), and the app styles each part, with `checked:`, `indeterminate:` and `disabled:` classes that follow the
checkbox.

```rust
use nsh_base::{checkbox, theme};
use nsh_core::prelude::*;

fn notify() -> impl IntoElement {
    let on = signal(false);
    checkbox()
        .checked(on)
        .on_change(move |next: &bool| on.set(*next))
        .flex_row()
        .items_center()
        .gap_2()
        .indicator_style(|s| {
            s.size(px(20.0))
                .items_center()
                .justify_center()
                .rounded_md()
                .border_2()
                .border_color(move || theme().border)
                .transition_colors()
                .checked(|s| s.bg(move || theme().primary).border_color(move || theme().primary))
        })
        .indicator(text(move || if on.get() { "✓" } else { "" }).text_color(move || theme().primary_foreground))
        .child(text("Notify me"))
}
```

```tsx
import { mount, signal, Text } from "nsh";
import { Checkbox } from "nsh/base";

function App() {
  const on = signal(false);
  return (
    <Checkbox
      checked={on()}
      onChange={({ checked }) => on.set(checked)}
      class="flex-row items-center gap-2"
      indicatorClass="size-5 items-center justify-center rounded-md border-2 border-border transition-colors checked:border-primary checked:bg-primary"
      indicator={<Text class="text-primary-foreground">{on() ? "✓" : ""}</Text>}
    >
      <Text>Notify me</Text>
    </Checkbox>
  );
}

mount(App);
```

`Checkbox` comes from [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md), the `nsh-base` crate in Rust. The value is the app's: a
press reports the next value with `onChange`, and the checkbox shows the `checked` and `indeterminate` the app passes
back. In Rust, `checkbox()` makes one with a setter per prop (`.checked(..)`, `.indicator_style(..)`), a listener per
event (`.on_change(..)`), the typed style methods for the checkbox itself and `.child(..)` for its label; the
indicator's style takes the state methods (`.checked(..)`, `.indeterminate(..)`, `.disabled_style(..)`) that follow
the checkbox.

## Props

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `checked` | `.checked(..)` | `boolean` | `false` | Checked or not. A press reports the next value with `onChange`; the checkbox shows the value the app passes back. |
| `indeterminate` | `.indeterminate(..)` | `boolean` | `false` | Neither checked nor unchecked, over `checked` while it holds: screen readers say it is mixed, and a press asks for checked. |
| `disabled` | `.disabled(..)` | `boolean` | `false` | No presses and no press feedback; `disabled:` styles apply to the checkbox and its indicator, and screen readers say it is dimmed. |
| `checkedStyle` | `.checked_style(\|s\| ..)` | `StyleProp<ViewStyle>` | none | The checkbox's style while checked and not disabled, as `checked:` classes. |
| `indeterminateStyle` | `.indeterminate_style(\|s\| ..)` | `StyleProp<ViewStyle>` | none | The checkbox's style while indeterminate and not disabled, as `indeterminate:` classes. |
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | none | What screen readers say: what the checkbox selects, when its children have no text that says it. |
| `role` | `.role(..)` | `AccessibilityRole` | `"checkbox"` | What it is for screen readers, when it is something more specific (a checked menu item: `"menuitem"`). |
| `indicatorClass`, `indicatorStyle` | `.indicator_style(\|s\| ..)` | `string`, `StyleProp<ViewStyle>` | none | The indicator, the box that shows the value. |
| `indicator` | `.indicator(..)` | `JSX.Element` | none | The content of the indicator: the mark (a check, a dash), which the app shows by its value. |
| `hitSlop` | `.hit_slop(..)` | `number \| Partial<Edges>` | none | How far outside its bounds presses still count, in points: one number for every side, or the sides named. As a view's `hitSlop`. |
| `children` | `.child(..)` | `JSX.Element` | none | The content after the indicator: a label, which screen readers say. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The checkbox itself: the row around the indicator and the label. |
| `activeStyle`, `hoverStyle`, `focusStyle`, `disabledStyle` | `.active(\|s\| ..)`, `.hover(..)`, `.focus(..)`, `.disabled_style(..)` | `StyleProp<ViewStyle>` | none | The checkbox's style while pressed, hovered, focused or disabled, as the `<state>:` classes. |

## Events

| Event | Rust | Description |
|---|---|---|
| `onChange` | `.on_change(\|checked: &bool\| ..)` | The checkbox was pressed: a tap, a click, Space or Return while it has the keyboard focus, or a screen reader's activation. It reports the value the checkbox asks for as `checked`: `true` from unchecked and from indeterminate, `false` from checked. |

A disabled checkbox reports nothing.

## Parts

| Part | Inside | Styled with | States |
|---|---|---|---|
| The checkbox | | `class`, `style` | `checked:`, `indeterminate:`, `disabled:`, `active:`, `hover:`, `focus:` (or `checkedStyle`, `indeterminateStyle`, `disabledStyle`, ...) |
| The indicator | the checkbox, first | `indicatorClass`, `indicatorStyle` | `checked:`, `indeterminate:`, `disabled:` follow the checkbox |
| The mark | the indicator | its own elements (`indicator`) | `group-checked:`, `group-indeterminate:` and the other `group-*:` variants with `group` on `indicatorClass` |
| The label | the checkbox, after the indicator | its own elements (`children`) | `group-*:` variants with `group` on the checkbox's `class` |

The mark is the app's content, so it shows what the app decides: a check while checked and a dash while
indeterminate, chosen from the value the app holds, or both marks with `group-checked:` / `group-indeterminate:`
classes picking the one shown.

## Indeterminate

A "select all" checkbox is indeterminate while some items are selected. A press asks for checked, and the app selects
every item:

```tsx
const selected = signal<string[]>([]);
const all = () => selected().length === items.length;
const some = () => selected().length > 0 && !all();

<Checkbox
  checked={all()}
  indeterminate={some()}
  onChange={({ checked }) => selected.set(checked ? items.map((i) => i.id) : [])}
  class="flex-row items-center gap-2"
  indicatorClass="group size-5 items-center justify-center rounded-md border-2 border-border checked:border-primary checked:bg-primary indeterminate:border-primary indeterminate:bg-primary"
  indicator={
    <>
      <Text class="hidden text-primary-foreground group-checked:flex">✓</Text>
      <View class="hidden h-0.5 w-2.5 bg-primary-foreground group-indeterminate:flex" />
    </>
  }
>
  <Text>Select all</Text>
</Checkbox>
```

## Disabled

A disabled checkbox takes no presses, and screen readers announce it as dimmed. Its `disabled:` classes and those of
its indicator apply, over their `checked:` and `indeterminate:` ones:

```tsx
<Checkbox
  checked={on()}
  disabled={locked()}
  onChange={({ checked }) => on.set(checked)}
  class="flex-row items-center gap-2 disabled:opacity-50"
  indicatorClass="size-5 rounded-md border-2 border-border checked:border-primary checked:bg-primary disabled:border-border disabled:bg-muted"
>
  <Text>Share usage data</Text>
</Checkbox>
```

## A small target with hitSlop

A checkbox with no label beside it (a row's selection box) can be smaller than a finger. `hitSlop` makes presses that
land near it count, in points past each side, without changing its layout or its look: one number for every side, or the
sides named (`{ top: 8, bottom: 8 }`), as a [view's `hitSlop`](https://nsh.dev/versions/main/elements.md#presses-and-feedback) takes them.

```tsx
<Checkbox
  checked={selected()}
  hitSlop={12}
  accessibilityLabel="Select row"
  onChange={({ checked }) => selected.set(checked)}
  indicatorClass="size-4 rounded border border-border checked:bg-primary"
/>
```

## Accessibility

- A checkbox is one element for screen readers, with the role `"checkbox"` (or its `role`) and its value: checked,
  unchecked, or mixed while indeterminate. The indicator and the mark are parts of it. Its label is the text of its
  children; give `accessibilityLabel` when it has none.
- `disabled` is announced as the platform announces it (VoiceOver, TalkBack, UI Automation, the browser's accessibility
  tree).
- On macOS and the web a checkbox is a stop of the keyboard focus: Tab reaches it, Space and Return toggle it, and
  `focus:` styles show where the focus is.

See [Accessibility](https://nsh.dev/versions/main/docs/accessibility.md) for labels, roles and announcements in general.

## Platform notes

- iOS, Android and Mac Catalyst: a press is a tap that ends on the checkbox, its label included.
- Desktops (macOS, Windows, Linux, GPUI) and the web: a press is a click. On macOS and the web, Space and Return also
  toggle the checkbox that has the keyboard focus.
- Every platform draws what the app styles: the indicator, the mark and their transitions.

Source: https://nsh.dev/versions/main/elements/checkbox

---

# Collapsible

A collapsible is a region whose content expands and collapses: details under a summary, a "show more", a section of
advanced settings. It renders its children always and its `content` after them while `open`. The app owns `open` and
the trigger that flips it (one of the children), and the look is the app's: a `Collapsible` has no trigger, chevron or
label of its own. With `reveal`, the content opens and closes with motion: its region's height springs from nothing to
the content's own and back, and what follows the collapsible moves along.

```rust
use nsh_base::{collapsible, theme};
use nsh_core::{AccessibilityState, prelude::*};

fn storage() -> impl IntoElement {
    let open = signal(false);
    collapsible()
        .open(open)
        .reveal(true)
        .gap_2()
        .child(
            view()
                .role(AccessibilityRole::Button)
                .accessibility_state(move || AccessibilityState {
                    expanded: Some(open.get()),
                    ..AccessibilityState::default()
                })
                .on_press(move || open.update(|o| *o = !*o))
                .flex_row()
                .items_center()
                .justify_between()
                .child(text("Storage"))
                .child(text("›").transition_transform().rotate(move || {
                    if open.get() { deg(90.0) } else { deg(0.0) }
                })),
        )
        .content(text("Photos 120 GB · Apps 54 GB · System 38 GB").text_color(move || theme().muted_foreground))
}
```

```tsx
import { mount, signal, Text, View } from "nsh";
import { Collapsible } from "nsh/base";

function App() {
  const open = signal(false);
  return (
    <Collapsible
      open={open()}
      reveal
      class="gap-2"
      content={<Text class="text-muted-foreground">Photos 120 GB · Apps 54 GB · System 38 GB</Text>}
    >
      <View
        role="button"
        accessibilityState={{ expanded: open() }}
        onPress={() => open.set(!open())}
        class="flex-row items-center justify-between active:opacity-70"
      >
        <Text class="font-medium">Storage</Text>
        <Text class={`transition-transform ${open() ? "rotate-90" : ""}`}>›</Text>
      </View>
    </Collapsible>
  );
}

mount(App);
```

`Collapsible` comes from [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md), the `nsh-base` crate in Rust. The value is the app's:
its trigger flips `open`, and the collapsible shows the value the app passes. In Rust, `collapsible()` makes one with a
setter per prop (`.open(..)`, `.reveal(..)`, `.content(..)`), the typed style methods for the region and `.child(..)` for what shows
always.

## Props

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `open` | `.open(..)` | `boolean` | `false` | Expanded: the `content` is in the tree, after the children. The app owns the value. |
| `reveal` | `.reveal(..)` | `boolean` | `false` | Opens and closes with a reveal: the content sits in a region that clips it, whose height springs from zero to the content's own as `open` turns on and back as it turns off, critically damped (about 265 ms, no overshoot). What follows the collapsible moves with it, and the content stays in the tree until the region has closed. With reduced motion it opens and closes at once. The region is in the layout while closed too, zero high, so a `gap` of the collapsible's also comes before it. |
| `content` | `.content(..)` | `JSX.Element` | none | What expands. It is made once and kept while collapsed, so what is inside keeps its state (an input's text, a scroll position, a switch) from one opening to the next. |
| `children` | `.child(..)` | `JSX.Element` | none | What shows either way: a summary, the trigger that flips `open`. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The region around the children and the content (`gap-2` spaces them). |

## Events

A collapsible reports nothing of its own: the trigger is the app's, and its press (`onPress` of the `View` with
`role="button"`) is where the app flips `open`.

## Parts

| Part | Inside | Styled with |
|---|---|---|
| The region | | `class`, `style` |
| The children | the region, first | their own elements |
| The reveal's region | the region, after the children, with `reveal` | none: it clips the content and takes its height |
| The content | the region, after the children (in the reveal's region with `reveal`), while `open` | its own elements (`content`) |

Without `reveal`, the content comes and goes at once, and each platform lays the region out again when it arrives or
leaves. With `reveal`, the change is a layout animation of the commit that changes `open` (as
`LayoutAnimation.configureNext`, run natively, so no JavaScript runs while it moves): the reveal's region grows from
zero to the content's height and shrinks back, and the frames of whatever the same change moves, the views after the
collapsible among them, move with it. A transition of the app's goes along: the trigger's chevron turns
(`transition-transform`), and the content can fade in with its own classes.

## Accessibility

- The region is no element of its own for screen readers: its children and content are read as they are.
- The trigger says whether the region is expanded: give it `accessibilityState={{ expanded: open }}` and a button role
  (`role="button"` on a `View`), and screen readers announce "expanded" or "collapsed" with its label.
- On macOS and the web the trigger is a stop of the keyboard focus when it takes presses: Tab reaches it, Space and
  Return flip the region.

See [Accessibility](https://nsh.dev/versions/main/docs/accessibility.md) for labels, roles and announcements in general.

## Platform notes

- Every platform shows the content after the children while `open`, and leaves it out of the layout otherwise.
- With `reveal`, every platform springs the region's height on its own animator (iOS, Android, macOS, Windows, Linux,
  GPUI and the web), and opens and closes it at once while the system asks for reduced motion.
- iOS, Android and Mac Catalyst: the trigger's press is a tap. Desktops (macOS, Windows, Linux, GPUI) and the web: a
  click, and Space or Return on the focused trigger on macOS and the web.

Source: https://nsh.dev/versions/main/elements/collapsible

---

# ColorPicker

A color picker holds one color, and the parts inside it show and change it: a `ColorArea` of saturation and
brightness, `ColorSlider`s of any channel of RGB, HSL, HSB or OKLCH and of the alpha, `ColorField`s that take the
color as text or one channel as a number, `ColorSwatch`es of preset colors and a `ColorEyeDropper` that picks a color
anywhere on the screen. The app lays the parts out with its
own elements in between (a row per channel with its letter, the space picked with `Tabs`, the picker in a `Popover`),
and styles each of them: the parts draw the colors of the channels, and every size, radius, border and shadow is the
app's.

```rust
use nsh_base::{
    ColorChannel, ColorPickerEvent, ColorSpace, color_area, color_field, color_picker,
    color_slider, color_swatch, theme,
};
use nsh_core::prelude::*;

fn primary(color: Signal<Hsla>) -> impl IntoElement {
    // A channel of OKLCH: its letter, its slider, its number.
    let channel = move |channel: ColorChannel, letter: &'static str| {
        view()
            .flex_row()
            .items_center()
            .gap_2()
            .child(text(letter).w(px(14.0)).text_sm().text_color(move || theme().muted_foreground))
            .child(
                color_slider()
                    .color_space(ColorSpace::Oklch)
                    .channel(channel)
                    .accessibility_label(letter)
                    .flex_1()
                    .h(px(18.0))
                    .justify_center()
                    .px(px(8.0))
                    .track_style(|s| s.h(px(10.0)).rounded_full())
                    .thumb_style(|s| s.size(px(16.0)).rounded_full().border_2().border_color(white()))
                    .fill_thumb(true),
            )
            .child(
                color_field()
                    .color_space(ColorSpace::Oklch)
                    .channel(channel)
                    .accessibility_label(letter)
                    .w(px(64.0))
                    .h(px(28.0))
                    .px_2()
                    .rounded_md()
                    .border_1()
                    .border_color(move || theme().border)
                    .text_sm(),
            )
    };
    color_picker()
        .value(move || Some(color.get()))
        .on_change(move |e: &ColorPickerEvent| {
            if let ColorPickerEvent::Change(value, _) = e {
                color.set(*value);
            }
        })
        .gap_3()
        .child(
            color_area()
                .accessibility_label("Saturation and brightness")
                .h(px(160.0))
                .panel_style(|s| s.rounded_lg())
                .thumb_style(|s| s.size(px(18.0)).rounded_full().border_2().border_color(white()))
                .fill_thumb(true),
        )
        .child(channel(ColorChannel::Lightness, "L"))
        .child(channel(ColorChannel::Chroma, "C"))
        .child(channel(ColorChannel::Hue, "H"))
        .child(color_swatch().size(px(28.0)).rounded_md())
}
```

```tsx
import { mount, signal, Text, View } from "nsh";
import { type ColorChannel, ColorArea, ColorField, ColorPicker, ColorSlider, ColorSwatch } from "nsh/base";

const thumb = "rounded-full border-2 border-white";

function Channel(props: { channel: ColorChannel; letter: string }) {
  return (
    <View class="flex-row items-center gap-2">
      <Text class="w-[14px] text-sm text-muted-foreground">{props.letter}</Text>
      <ColorSlider
        colorSpace="oklch"
        channel={props.channel}
        accessibilityLabel={props.letter}
        class="flex-1 h-[18px] justify-center px-2"
        trackClass="h-[10px] rounded-full"
        thumbClass={`size-4 ${thumb}`}
        fillThumb
      />
      <ColorField
        colorSpace="oklch"
        channel={props.channel}
        accessibilityLabel={props.letter}
        class="w-16 h-7 px-2 rounded-md border border-border text-sm text-right"
      />
    </View>
  );
}

function App() {
  const primary = signal("oklch(54.6% 0.215 262.9)");
  return (
    <ColorPicker value={primary()} format="oklch" onChange={({ formatted }) => primary.set(formatted)} class="gap-3">
      <ColorArea accessibilityLabel="Saturation and brightness" class="h-40" panelClass="rounded-lg" thumbClass={`size-[18px] ${thumb}`} fillThumb />
      <Channel channel="lightness" letter="L" />
      <Channel channel="chroma" letter="C" />
      <Channel channel="hue" letter="H" />
      <View class="flex-row items-center gap-2">
        <ColorSwatch class="size-7 rounded-md" />
        <Text class="font-mono text-sm">{`--primary: ${primary()}`}</Text>
      </View>
    </ColorPicker>
  );
}

mount(App);
```

`ColorPicker`, `ColorArea`, `ColorSlider`, `ColorField`, `ColorSwatch` and `ColorEyeDropper` come from [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md),
the `nsh-base` crate in Rust. In Rust, `color_picker()` and its parts' functions make them with a setter per prop
(`.channel(..)`, `.thumb_style(..)`), a listener method per event (`.on_change(..)`) and the typed style methods; the
color is an `Hsla`, the spaces, channels and formats are `ColorSpace`, `ColorChannel` and `ColorFormat`.

## Value

The color is a CSS color: hex (`#3b82f6`, `#3b82f680` with its alpha), `rgb()`, `hsl()`, `hsb()`, `oklch()` or a CSS
name; in Rust an `Hsla`. The app owns it with `value` and sets the one `onChange` reports, as for every control of
`nsh/base`; or it leaves the color to the picker with `defaultValue` and hears the changes all the same.

- `onChange({ value, formatted })` reports each color the user asks for: at each step of a drag on the area or a slider,
  for each key, a field's number as it is typed, a swatch pressed. `value` is the color, `formatted` the same color
  written as `format` says (`"hex"`, `"rgb"`, `"hsl"`, `"hsb"` or `"oklch"`), ready to save or to set as a token.
- `onChangeEnd({ value, formatted })` reports the color the change ended at, once: when the pointer lifts, after each key,
  when a field is left or submitted, when a swatch is pressed.
- The picker keeps the color in each space as the user set it. A gray keeps its hue and saturation, so the hue slider
  stays where the user left it; a color edited in OKLCH keeps its lightness, chroma and hue as typed, also past what
  sRGB shows (the color reported is the nearest one sRGB shows, and `formatted` in `"oklch"` keeps the channels).
- A `value` the app sets that the picker did not report replaces the color in every space.

## Spaces and channels

| `colorSpace` | Channels (`channel`) | Ranges |
|---|---|---|
| `"rgb"` | `"red"`, `"green"`, `"blue"` | 0 to 255 |
| `"hsl"` | `"hue"`, `"saturation"`, `"lightness"` | hue 0 to 360, the others 0 to 100 |
| `"hsb"` | `"hue"`, `"saturation"`, `"brightness"` | hue 0 to 360, the others 0 to 100 |
| `"oklch"` | `"lightness"`, `"chroma"`, `"hue"` | lightness 0 to 100 (by 0.1), chroma 0 to 0.4 (by 0.001), hue 0 to 360 (by 0.1) |
| any | `"alpha"` | 0 to 100 |

A slider's track draws its channel's colors with the other channels held, so it shows where each value leads. A
channel its space does not have is the space's first (a warning says so).

## Props

### ColorPicker

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `value` | `.value(..)` | `string` | none | The color (controlled). The app sets the one `onChange` reports. |
| `defaultValue` | `.default_value(..)` | `string` | `"#000000"` | The color at first while `value` is not set; the picker then keeps its own. |
| `format` | `.format(..)` | `"hex" \| "rgb" \| "hsl" \| "hsb" \| "oklch"` | `"hex"` | How `formatted` writes the color. |
| `disabled` | `.disabled(..)` | `boolean` | `false` | No changes from any part; `disabled:` classes apply to the picker and its parts. |
| `children` | `.child(..)` | `JSX.Element` | none | The parts and the app's elements between them. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The picker itself: the column (or row) around its parts. |

### ColorArea

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `panelClass`, `panelStyle` | `.panel_style(\|s\| ..)` | `string`, `StyleProp<ViewStyle>` | none | The panel, filling the area: the hue's colors, saturation from left to right (from right to left in a right-to-left layout) and brightness from bottom to top, clipped to its corners. |
| `thumbClass`, `thumbStyle` | `.thumb_style(\|s\| ..)` | `string`, `StyleProp<ViewStyle>` | none | The thumb, centered on the color. |
| `fillThumb` | `.fill_thumb(..)` | `boolean` | `false` | The thumb's background is the color. |
| `disabled` | `.disabled(..)` | `boolean` | `false` | No pointer, keyboard or screen reader changes. |
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | none | What screen readers say for the thumb. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The area: its size is the app's. |

### ColorSlider

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `colorSpace` | `.color_space(..)` | `"rgb" \| "hsl" \| "hsb" \| "oklch"` | `"hsb"` | The space of the channel. |
| `channel` | `.channel(..)` | `ColorChannel` | `"hue"` | The channel it changes: one of the space's, or `"alpha"`. |
| `axis` | `.axis(..)` | `"horizontal" \| "vertical"` | `"horizontal"` | The track's direction: the smallest value at the start (the left, the right in a right-to-left layout), or at the bottom. Read when the slider is made. |
| `trackClass`, `trackStyle` | `.track_style(\|s\| ..)` | `string`, `StyleProp<ViewStyle>` | none | The track: the channel's colors along it, clipped to its corners; the thumb is placed on it. |
| `thumbClass`, `thumbStyle` | `.thumb_style(\|s\| ..)` | `string`, `StyleProp<ViewStyle>` | none | The thumb, centered on the value. |
| `fillThumb` | `.fill_thumb(..)` | `boolean` | `false` | The thumb's background is the color (with its alpha on an alpha slider). |
| `checkerboardColor` | `.checkerboard_color(..)` | `string` | none | The color of a checkerboard under the track, which shows through an alpha slider's colors. |
| `checkerboardSize` | `.checkerboard_size(..)` | `number` | `4` | The side of the checkerboard's squares. |
| `disabled` | `.disabled(..)` | `boolean` | `false` | No pointer, keyboard or screen reader changes. |
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | none | What screen readers say for the thumb. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The slider: the band around the track that takes presses and drags. |

### ColorField

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `channel` | `.channel(..)` | `ColorChannel` | none | The channel it takes as a number. Without it, the field takes the whole color as text. |
| `colorSpace` | `.color_space(..)` | `ColorSpace` | `"hsb"` | The space of `channel`. |
| `format` | `.format(..)` | `ColorFormat` | `"hex"` | How the field writes the whole color. It reads any CSS form. |
| `placeholder` | `.placeholder(..)` | `string` | none | Shown while the field is empty. |
| `disabled` | `.disabled(..)` | `boolean` | `false` | No typing. |
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | none | What screen readers say for the field. |
| `class`, `style` | style methods | `string`, `StyleProp<TextStyle>` | none | The field, a text input. |

A channel's field changes the color as a number is typed, held to the channel's range; the whole color's field changes
it when the field is left or submitted, if the text reads as a color. Leaving a field writes its value again in its
form.

### ColorSwatch

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `color` | `.color(..)` | `string` | none | The color it shows; a press picks it in the picker around it. Without it, the picker's own color: a preview, which is no stop of Tab. |
| `selectedStyle` | `.selected_style(..)` | `StyleProp<ViewStyle>` | none | The style while it is the picker's color, as `selected:` classes. |
| `checkerboardColor` | `.checkerboard_color(..)` | `string` | none | A checkerboard under a translucent color. |
| `checkerboardSize` | `.checkerboard_size(..)` | `number` | `4` | The side of its squares. |
| `disabled` | `.disabled(..)` | `boolean` | `false` | No presses. |
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | the color in hex | What screen readers say. |
| `children` | `.child(..)` | `JSX.Element` | none | Content over the color: a check on the selected swatch (`group-selected:`). |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The swatch: its size, shape and border; its corners clip the color. |

### ColorEyeDropper

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `disabled` | `.disabled(..)` | `boolean` | `false` | No presses. It is disabled too where the platform has no eyedropper. |
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | none | What screen readers say. |
| `children` | `.child(..)` | `JSX.Element` | none | Its content: the app's icon or label. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The button. |

A press shows the system's eyedropper: AppKit's color sampler on macOS, the browser's `EyeDropper` on the web (Chrome
and Edge). The color picked becomes the picker's (`onChange`, then `onChangeEnd`); Escape picks none. Where the platform
has no eyedropper the button is disabled, and `disabled:hidden` hides it there.

## Events

| Event | Of | Rust | Payload | When |
|---|---|---|---|---|
| `onChange` | `ColorPicker` | `.on_change(\|e: &ColorPickerEvent\| ..)` | `({ value: string, formatted: string })` | The user changed the color. |
| `onChangeEnd` | `ColorPicker` | `.on_change_end(\|e: &ColorPickerEvent\| ..)` | `({ value: string, formatted: string })` | The change ended. Once per change. |
| `onPress` | `ColorSwatch` | `.on_press(\|color: &Hsla\| ..)` | `({ color: string })` | The swatch was pressed; it works alone too, as a palette's chip. |
| `onPick` | `ColorEyeDropper` | `.on_pick(\|color: &Hsla\| ..)` | `({ color: string })` | The user picked a color on the screen; it works alone too. |

In Rust, `ColorPickerEvent::Change(Hsla, SharedString)` and `ColorPickerEvent::ChangeEnd(Hsla, SharedString)` carry the
color and its `formatted` text.

## Parts

| Part | Inside | Styled with |
|---|---|---|
| `ColorArea` | the picker | `class`, `style` |
| The area's panel | the area, filling it | `panelClass`, `panelStyle` |
| The area's thumb | the area, centered on the color | `thumbClass`, `thumbStyle` |
| `ColorSlider` | the picker | `class`, `style` |
| The slider's track | the slider | `trackClass`, `trackStyle` |
| The slider's thumb | the slider, centered on the value on the track | `thumbClass`, `thumbStyle` |
| `ColorField` | the picker | `class`, `style` |
| `ColorSwatch` | the picker, or alone | `class`, `style`, `selectedStyle` |
| `ColorEyeDropper` | the picker, or alone | `class`, `style` |

A slider's thumb is centered on the track's ends at the channel's ends. Padding on the slider of half the thumb's
width (`h-6 justify-center px-2.5` around an `h-3` track) keeps the whole thumb inside the slider, where it takes
presses at both ends. States the parts show: a thumb's `active:` while it is dragged and `focus:` with the keyboard
focus, a swatch's `selected:`, and every part's `disabled:`.

## Keyboard

On macOS and the web each thumb is a stop of the keyboard focus (Tab):

| Key | On a slider | On the area |
|---|---|---|
| Right, Up | One step up | Right: more saturation; Up: more brightness |
| Left, Down | One step down | Left: less saturation; Down: less brightness |
| Shift with an arrow | Ten steps | Ten steps |
| Page Up, Page Down | Ten steps | Ten steps of brightness |
| Home, End | The channel's ends | |

In a right-to-left layout a horizontal slider and the area run from the right, the smallest value (the least
saturation) at the right end: Left is a step up and Right a step down, and a press or a drag picks the value under the
pointer as it is drawn. A vertical slider keeps Right and Up as a step up; Up and Down on the area keep the brightness.

A swatch takes Space and Return. Each key reports `onChange` and then `onChangeEnd`; arrows repeat while held.

## Accessibility

- The area's and each slider's thumb are adjustable elements (`"adjustable"`, a slider in the browser) with their
  label, value and range; screen readers' increment and decrement step them.
- Each field is a text field with its label; each swatch a button, selected while it is the picker's color, named by
  its color in hex unless `accessibilityLabel` names it. The eyedropper is a button with the app's label.
- While disabled, screen readers say the parts are dimmed, and they take no actions.

See [Accessibility](https://nsh.dev/versions/main/docs/accessibility.md) for labels, roles and actions in general.

## Platform notes

- Every platform draws what the app styles; the tracks' and the panel's colors are gradients drawn by the platform.
  Presses and drags are followed in the core, for a mouse, a pen or a finger, and a scroll view around the picker
  keeps its scrolling to drags that start elsewhere.
- `ColorEyeDropper` picks with AppKit's color sampler on macOS and the browser's `EyeDropper` on the web; the color
  arrives in sRGB.

Source: https://nsh.dev/versions/main/elements/color-picker

---

# Combobox

A combobox chooses values from a list of items, one or, with `multiple`, several: the tags of a post, the members of
a channel, the languages of a document. Its trigger is an input: typing opens the list and filters it, as shadcn/ui's
combobox does. It is [Select](https://nsh.dev/versions/main/elements/select.md)'s sibling and shares its list, presented as each device expects:

- On the desktops and in desktop browsers, a popup under the field, as wide as the field (the app's `popupStyle` / `popupClass` width sets another) and as tall as its rows up
  to the room beside it.
- On phones and tablets, a sheet at the bottom of the screen over a backdrop.

The combobox owns the behavior: the value (the app's, or its own), the open state, the keyboard, search, sections,
the highlighted row and what screen readers hear. With `multiple`, a choice toggles the item in the value and the
list stays open, so several are picked in one go. The look is the app's: it styles the field, the popup, the list,
the rows, the sections' headers, the input and the footer, or draws the rows itself.

```rust
use nsh_base::{SelectEntry, SelectItem, combobox, theme};
use nsh_core::prelude::*;

const TAGS: [(&str, &str); 5] = [
    ("bug", "Bug"),
    ("design", "Design"),
    ("docs", "Docs"),
    ("perf", "Performance"),
    ("security", "Security"),
];

fn tag_picker() -> impl IntoElement {
    let tags = signal(Vec::<SharedString>::new());
    let title = move || match tags.get().len() {
        0 => "Add tags".to_string(),
        n => format!("{n} tags"),
    };
    combobox()
        .items(
            TAGS.iter()
                .map(|&(value, title)| SelectItem::new(value, title))
                .collect::<Vec<_>>(),
        )
        .multiple(true)
        .placeholder(title)
        .value(move || Some(tags.get()))
        .on_change(move |next: &Vec<SharedString>| tags.set(next.clone()))
        .accessibility_label("Tags")
        .offset(px(4.0))
        .popup_style(|s| {
            s.p_1()
                .rounded_lg()
                .border_1()
                .border_color(move || theme().border)
                .bg(move || theme().popover)
                .shadow_md()
        })
        .h_9()
        .w_48()
        .px_3()
        .flex_row()
        .items_center()
        .rounded_md()
        .border_1()
        .border_color(move || theme().input)
        .input_style(|s| s.flex_1().text_sm())
        .trigger_button(text("⌄"))
        .item_class("rounded-md focus:bg-accent selected:font-medium disabled:opacity-50")
        .render_item(|item: &SelectEntry| view().px_2().py_1p5().child(text(item.title.clone()).text_sm()))
}
```

```tsx
import { mount, signal, Text, View } from "nsh";
import { Combobox } from "nsh/base";

const TAGS = [
  { value: "bug", title: "Bug" },
  { value: "design", title: "Design" },
  { value: "docs", title: "Docs" },
  { value: "perf", title: "Performance" },
  { value: "security", title: "Security" },
];

function App() {
  const tags = signal<string[]>([]);
  return (
    <Combobox
      items={TAGS}
      multiple
      placeholder={tags().length ? `${tags().length} tags` : "Add tags"}
      value={tags()}
      onChange={({ value }) => tags.set(value)}
      accessibilityLabel="Tags"
      offset={4}
      popupClass="rounded-lg border border-border bg-popover p-1 text-popover-foreground shadow-md"
      backdropClass="bg-black/40"
      class="h-9 w-48 flex-row items-center rounded-md border border-input px-3"
      inputClass="flex-1 text-sm placeholder:text-muted-foreground"
      itemClass="group rounded-md px-2 py-1.5 text-sm focus:bg-accent focus:text-accent-foreground"
      triggerButton={<Text class="px-1 text-muted-foreground">⌄</Text>}
      renderItem={(item) => (
        <View class="flex-row justify-between">
          <Text>{item.title}</Text>
          <Text class="opacity-0 group-selected:opacity-100">✓</Text>
        </View>
      )}
    />
  );
}

mount(App);
```

`Combobox` comes from [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md), the `nsh-base` crate in Rust. In Rust, `combobox()` makes
one with a setter per prop (`.items(..)`, `.value(..)`, `.multiple(..)`) and a listener per event (`.on_change(..)`).
Its items are `Select`'s: `SelectItem::new(value, title)`, with `.disabled(..)` and `.group(..)`, in sections as a
select's are (see [Items](https://nsh.dev/versions/main/elements/select.md#items)).

## Value

The value is an array of the selected items' values. With `value`, the app owns it: the combobox shows those items
as selected and reports each change with `onChange({ value })`; the app sets `value` to follow it, or keeps its own.
Left out, the combobox keeps its own value, from `defaultValue` at first.

- With `multiple`, a press, Return or Space toggles the highlighted item: in the value if it was out, out if it was
  in. The list stays open.
- Without it, a choice replaces the value with that item's and closes the list; choosing the selected item again only
  closes it.

`onConfirm({ value })` tells the value as the list closes: once per opening, however it closes (a choice, Escape, a
press outside, the trigger button, Tab or Shift+Tab from the open list, `reason: "focus"`), with the value as the user
left it. Cmd+Return on a Mac (Ctrl+Return elsewhere) closes
the list and confirms.

`cleanable` adds a clear button while an item is selected: a press empties the value (`onChange({ value: [] })`).
The button comes after the input, before the trigger button; a press on it never opens the list. The app fills it, as
a [select's clear button](https://nsh.dev/versions/main/elements/select.md#value).

## Input

The trigger is a text input in the combobox's row (its `class` and `style`: the field's border and fill), with the
app's `prefix` before it (the chosen items as chips, an icon) and, after it, the clear button, the app's
`triggerButton` (a chevron) and `suffix`.

- Typing opens the list and filters the items by title, ignoring case; `empty` shows while nothing matches. Down and
  Up open it too, and a press on the input or the trigger button opens and closes it; on touch screens the tap that
  focuses the input opens it.
- With one value, the input shows the chosen item's title (`placeholder` while there is none). It is selected when
  the input gets the focus, so what is typed replaces it.
- With `multiple`, the input shows the query; the app shows the chosen items, in `prefix` or beside the combobox.

The query is the combobox's own, starting each opening from `defaultQuery` (else empty), or the app's with `query`:
`onQueryChange({ query })` reports what is typed, and the app sets `query` to follow it, to filter its own way or to
suggest a starting point.

## Footer

`footer` is content below the rows, in a part of its own (`footerClass`, `footerStyle`): an action ("Manage tags"),
a count, a hint. It stays in place while the rows scroll.

## Props

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `items` | `.items(..)` | `SelectItem[]` | `[]` | The items, in order. |
| `multiple` | `.multiple(..)` | `boolean` | `false` | A choice toggles the item in the value and the list stays open. |
| `value` | `.value(..)` | `string[]` | none | The selected items' values, owned by the app. |
| `defaultValue` | `.default_value(..)` | `string[]` | `[]` | The value at first, without `value`. |
| `open`, `defaultOpen` | `.open(..)`, `.default_open(..)` | `boolean` | `false` | The open state, the app's or the combobox's own. |
| `placeholder` | `.placeholder(..)` | `string` | none | The input's placeholder, while it is empty. |
| `query` | `.query(..)` | `string` | none | The query, owned by the app. |
| `defaultQuery` | `.default_query(..)` | `string` | none | The query each opening starts with, without `query`. |
| `cleanable` | `.cleanable(..)` | `boolean` | `false` | A clear button while an item is selected; a press empties the value. |
| `disabled` | `.disabled(..)` | `boolean` | `false` | It stays closed and takes no presses or keyboard focus. |
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | none | What the choice is about, for screen readers. |
| `placement`, `align`, `offset`, `margin` | `.placement(..)`, ... | as `Select`'s | `"bottom"`, `"start"`, 0, 0 | Desktops: where the popup goes against the field. |
| `popupClass`, `popupStyle` | `.popup_class(..)`, `.popup_style(..)` | `string`, `StyleProp<ViewStyle>` | none | The popup (desktops) or the sheet (touch screens). |
| `backdropClass`, `backdropStyle` | `.backdrop_class(..)`, `.backdrop_style(..)` | `string`, `StyleProp<ViewStyle>` | none | The backdrop behind the sheet. |
| `listClass`, `listStyle` | `.list_class(..)`, `.list_style(..)` | `string`, `StyleProp<ViewStyle>` | none | The list, the scroll view of the rows. |
| `itemClass`, `itemStyle` | `.item_class(..)`, `.item_style(..)` | `string`, `StyleProp<TextStyle>` | none | Each item's row: `focus:` while highlighted, `selected:` while selected, `disabled:` while it cannot be. |
| `groupClass`, `groupStyle` | `.group_class(..)`, `.group_style(..)` | `string`, `StyleProp<ViewStyle>` | none | Each section's header. |
| `inputClass`, `inputStyle` | `.input_class(..)`, `.input_style(..)` | `string`, `StyleProp<InputStyle>` | none | The input: `focus:` while it edits, `disabled:` with the combobox. |
| `footerClass`, `footerStyle` | `.footer_class(..)`, `.footer_style(..)` | `string`, `StyleProp<ViewStyle>` | none | The footer, below the rows. |
| `clearButtonClass`, `clearButtonStyle` | `.clear_button_class(..)`, `.clear_button_style(..)` | `string`, `StyleProp<ViewStyle>` | none | The clear button (`cleanable`). |
| `clearButton` | `.clear_button(..)` | `JSX.Element` | none | The content of the clear button. |
| `clearButtonAccessibilityLabel` | `.clear_button_accessibility_label(..)` | `string` | none | What screen readers call the clear button. |
| `triggerButton` | `.trigger_button(..)` | `JSX.Element` | none | A button after the input (a chevron): a press opens and closes the list. |
| `prefix` | `.prefix(..)` | `JSX.Element` | none | Content before the input: chips, an icon. |
| `suffix` | `.suffix(..)` | `JSX.Element` | none | Content after the trigger button. |
| `empty` | `.empty(..)` | `JSX.Element` | none | What the list shows while no item does. |
| `footer` | `.footer(..)` | `JSX.Element` | none | What shows below the rows. |
| `renderItem` | `.render_item(..)` | `(item: SelectEntry) => JSX.Element` | none | An item's row, drawn by the app from what the item is, never its state: the content follows the row's `group-focus:`, `group-selected:` and `group-disabled:` (`group` in `itemClass`), so a move of the highlight or a toggle draws nothing again; the item's title otherwise. |
| `renderGroup` | `.render_group(..)` | `(group: SelectGroup) => JSX.Element` | none | A section's header, drawn by the app; its title otherwise. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The field: the row of the prefix, the input, the buttons and the suffix; the list is as wide as it. |

## Events

| Event | Rust | Description |
|---|---|---|
| `onChange` | `.on_change(\|value\| ..)` | The value changed (a choice, a toggle, the clear button): `{ value }`, the selected items' values. Set `value` to follow it. |
| `onConfirm` | `.on_confirm(\|value\| ..)` | The list closed: `{ value }` as it is then, once per opening. |
| `onQueryChange` | `.on_query_change(\|query\| ..)` | The user typed in the input: `{ query }`. Set `query` to follow it. |
| `onOpenChange` | `.on_open_change(\|e\| ..)` | The list opened or closed, with why (`{ open, reason }`). Set `open` to follow it. |
| `onOpen`, `onClose` | `.on_open(..)`, `.on_close(..)` | The list is shown, or gone. |
| `onCancel` | `.on_cancel(..)` | The user closed the list without a choice that closes it (Escape or back, a press outside or on the backdrop). |

They come in this order: `onChange` for a choice, or `onCancel` for a close without one, then `onOpenChange`, then
`onConfirm` as the list closes, then `onOpen` or `onClose` once the list is shown or gone.

## Parts

| Part | Where | Styled with |
|---|---|---|
| The field | the combobox's view, a row | `class`, `style` |
| The prefix | the field, first | the app's own element (`prefix`) |
| The input | the field, after the prefix | `inputClass`, `inputStyle`, `placeholder` |
| The clear button | the field, after the input (`cleanable`, while an item is selected) | `clearButtonClass`, `clearButtonStyle`; its content `clearButton` |
| The trigger button | the field, after the clear button | the app's own element (`triggerButton`) |
| The suffix | the field, last | the app's own element (`suffix`) |
| The popup or sheet | over everything, under the field (desktops) or at the bottom (touch screens) | `popupClass`, `popupStyle` |
| The backdrop | behind the sheet (touch screens) | `backdropClass`, `backdropStyle` |
| The list | the popup | `listClass`, `listStyle` |
| A section's header | the list, before its items | `groupClass`, `groupStyle`, `renderGroup` |
| An item's row | the list | `itemClass`, `itemStyle`, `renderItem` (`group-focus:`, `group-selected:`, `group-disabled:` inside, under `group` in `itemClass`) |
| The empty state | the popup, while no item shows | its own element (`empty`) |
| The footer | the popup, last | `footerClass`, `footerStyle`; its content `footer` |

## Keyboard

The keys are a select's (see [Keyboard](https://nsh.dev/versions/main/elements/select.md#keyboard)) while the input keeps the focus, with these
differences: letters and digits are typed into the input, which filters the list, rather than typeahead; Down and Up
open the closed list; Return toggles the highlighted item with `multiple` and keeps the list open; Cmd+Return on a
Mac (Ctrl+Return elsewhere) closes it and confirms. Tab and Shift+Tab close the open list and move the focus to the
next or previous control. When the list closes otherwise on the desktops, the input keeps the focus.

## Accessibility

- The input is a combobox for screen readers: its label is `accessibilityLabel`, its value the selected items'
  titles, joined with commas, and it says whether the list is expanded. `disabled` dims it.
- The list is a listbox and each row an option, named by its title; the selected options are selected and a disabled
  one dimmed. Sections' headers are headers.
- The clear button is a button named by `clearButtonAccessibilityLabel`; it is no stop of Tab. The trigger button
  is hidden from screen readers, as the input says whether the list is open, and is no stop of Tab either.

See [Accessibility](https://nsh.dev/versions/main/docs/accessibility.md) for labels, roles and announcements in general.

Source: https://nsh.dev/versions/main/elements/combobox

---

# Command

A command palette is a search field over a list of commands: the user types a few letters, the list narrows to the
commands that match, the arrow keys move the highlight and Return runs the highlighted command. `Command` owns the
behavior of one: filtering, sections, the highlight, the keyboard and what screen readers hear. Filtering runs
natively and the rows are virtualized: only the rows in view are made, so a palette of thousands of commands, files or
emoji filters at every keystroke. The look is the app's: the command draws nothing of its own, the app styles each part
(`itemClass`, `groupClass`, `searchClass`, ...) and draws the rows' content (`renderItem`: an icon, the label, the
shortcut's keys).

```rust
use nsh_base::{CommandEntry, CommandItem, command, theme};
use nsh_core::prelude::*;

fn palette() -> impl IntoElement {
    let items = vec![
        CommandItem::new("new", "New File").group("File").shortcut("mod+n"),
        CommandItem::new("open", "Open…").group("File").shortcut("mod+o"),
        CommandItem::new("theme", "Toggle Theme").group("View").keywords(["dark", "light"]),
        CommandItem::new("settings", "Settings").group("View").shortcut("mod+,"),
    ];
    let chosen = signal(SharedString::from("none"));
    command()
        .items(items)
        .placeholder("Type a command or search…")
        .accessibility_label("Commands")
        .auto_focus(true)
        .on_select(move |id: &SharedString| chosen.set(id.clone()))
        .empty(text("No results.").text_color(move || theme().muted_foreground))
        .h(px(360.0))
        .render_item(|entry: &CommandEntry| {
            view()
                .flex_row()
                .items_center()
                .h_8()
                .px_2()
                .child(text(entry.label.clone()).flex_1())
                .child(
                    text(entry.shortcut_label.clone().unwrap_or_default())
                        .text_color(move || theme().muted_foreground),
                )
        })
}
```

```tsx
import { mount, signal, Text, View } from "nsh";
import { Command, type CommandItem } from "nsh/base";

const commands: CommandItem[] = [
  { id: "new", label: "New File", group: "File", shortcut: "mod+n" },
  { id: "open", label: "Open…", group: "File", shortcut: "mod+o" },
  { id: "theme", label: "Toggle Theme", group: "View", keywords: ["dark", "light"] },
  { id: "settings", label: "Settings", group: "View", shortcut: "mod+," },
];

function App() {
  const chosen = signal("none");
  return (
    <Command
      items={commands}
      placeholder="Type a command or search…"
      accessibilityLabel="Commands"
      searchAccessibilityLabel="Search commands"
      autoFocus
      onSelect={({ id }) => chosen.set(id)}
      class="w-96 overflow-hidden rounded-lg border border-border bg-popover"
      searchBarClass="flex-row items-center gap-2 border-b border-border px-3"
      searchClass="h-11 flex-1 text-sm text-foreground placeholder:text-muted-foreground"
      listClass="max-h-80 p-1"
      groupClass="px-2 py-1.5 text-xs font-medium text-muted-foreground"
      separatorClass="-mx-1 my-1 h-px bg-border"
      itemClass="group h-8 flex-row items-center rounded-md px-2 focus:bg-accent disabled:opacity-50"
      empty={<Text class="py-6 text-center text-sm text-muted-foreground">No results.</Text>}
      renderItem={(entry) => (
        <View class="flex-1 flex-row items-center gap-2">
          <Text class="flex-1 text-sm text-foreground group-focus:text-accent-foreground">{entry.label}</Text>
          <Text class="text-xs text-muted-foreground">{entry.shortcutLabel ?? ""}</Text>
        </View>
      )}
    />
  );
}

mount(App);
```

`Command` comes from [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md), the `nsh-base` crate in Rust. The query is the app's when it
sets `query`, which it updates in `onQueryChange`; without it the search field keeps its own, starting from
`defaultQuery`. Items are identified by their `id`, the app's own, never by their label: `onSelect({ id })` says which
one the user chose. In Rust, `command()` makes it, with a setter per prop (`.items(..)`, `.query(..)`,
`.render_item(..)`), a listener method per event and the typed style methods.

## Items

`items` is the commands, in order, each a `CommandItem`:

| Field | Type | Description |
|---|---|---|
| `id` | `string` | What identifies it in `onSelect` and `onHighlightChange`: unique among the items. |
| `label` | `string` | What its row shows unless `renderItem` draws it, what screen readers say and what the query matches. |
| `keywords` | `string[]` | More words the query matches: synonyms, an English name beside a translated label. |
| `group` | `string` | Its section: adjacent items of one group show under a header with this heading. |
| `shortcut` | `string` | The keystroke of the same command, as [`keymap`](https://nsh.dev/versions/main/modules/nsh.md#keymap) names it (`"mod+shift+p"`), for its row to show. The app binds it with `keymap.bind`. |
| `disabled` | `boolean` | It cannot be chosen: the keys pass over it, presses do nothing, `disabled:` styles apply. |
| `checked` | `boolean` | It is the one in effect (a theme, a language): `checked:` styles apply and screen readers say it is checked. |

The query matches an item when its label or one of its keywords holds it, ignoring case and the spaces around it. The
items keep their order, and a section with no match goes with its header. `renderItem` gets a `CommandEntry` for each
row in view: the item's fields, and `shortcutLabel`, its `shortcut` as hints show it here (`⇧⌘P` on Apple's platforms,
`Ctrl+Shift+P` elsewhere). It is what the item is, and the highlight is the row's `focus:`: the drawing is made once per
item and keeps its views while the highlight moves.

## Props

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `items` | `.items(..)` | `CommandItem[]` | `[]` | The commands, in order. |
| `query` | `.query(..)` | `string` | none | The query (controlled), which the app sets in `onQueryChange`. |
| `defaultQuery` | `.default_query(..)` | `string` | none | The query at first, while `query` is not set. |
| `searchable` | `.searchable(..)` | `boolean` | `true` | A search field above the rows. Without it every item shows, and the command is one stop of the keyboard focus with typeahead. |
| `filterable` | `.filterable(..)` | `boolean` | `true` | The query filters the items. Turned off, every item shows: for a search the app answers itself (a server's results set as `items`). A new query still highlights the first item. |
| `loading` | `.loading(..)` | `boolean` | `false` | A search is under way: `empty` waits, and the list is busy for screen readers. Show your indicator in `searchSuffix`. |
| `placeholder` | `.placeholder(..)` | `string` | none | The search field's placeholder. |
| `autoFocus` | `.auto_focus(..)` | `boolean` | `false` | The search field takes the keyboard focus once shown: a palette that opens to be typed in. |
| `separator` | `.separator(..)` | `boolean` | `true` | A separator row between two sections shown, styled by `separatorClass`; never first, last or doubled. |
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | none | What screen readers call the list ("Commands"), and the search field while `searchAccessibilityLabel` is not set. |
| `searchAccessibilityLabel` | `.search_accessibility_label(..)` | `string` | `accessibilityLabel` | What screen readers call the search field: what it searches ("Search commands"). |
| `header`, `footer` | `.header(..)`, `.footer(..)` | `JSX.Element` | none | What shows above the search field (a title) and below the rows (the keys' hints, a count). |
| `empty` | `.empty(..)` | `JSX.Element` | none | What shows while no item does: a query that matches nothing, no items. |
| `searchPrefix`, `searchSuffix` | `.search_prefix(..)`, `.search_suffix(..)` | `JSX.Element` | none | What shows before and after the search field in its bar: a search icon, a spinner while `loading`. |
| `renderItem` | `.render_item(..)` | `(entry: CommandEntry) => JSX.Element` | none | A row's content, for the rows in view; without it a row shows the item's label. |
| `renderGroup` | `.render_group(..)` | `(group: CommandGroup) => JSX.Element` | none | A section's header (`{ heading }`); without it a header shows its heading. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The command itself: its size, frame and surface. |
| `searchBarClass`, `searchBarStyle` | `.search_bar_class(..)`, `.search_bar_style(..)` | `string`, `StyleProp<ViewStyle>` | none | The row of `searchPrefix`, the search field and `searchSuffix`. |
| `searchClass`, `searchStyle` | `.search_class(..)`, `.search_style(..)` | `string`, `StyleProp<TextStyle>` | none | The search field. |
| `listClass`, `listStyle` | `.list_class(..)`, `.list_style(..)` | `string`, `StyleProp<ViewStyle>` | none | The scroll view of the rows. Give it a height (`max-h-80`, or a sized command): the rows scroll inside it, and only those in view are made. |
| `itemClass`, `itemStyle` | `.item_class(..)`, `.item_style(..)` | `string`, `StyleProp<TextStyle>` | none | Each item's row and its states (below); its text styles reach the label. |
| `groupClass`, `groupStyle` | `.group_class(..)`, `.group_style(..)` | `string`, `StyleProp<TextStyle>` | none | Each section's header. |
| `separatorClass`, `separatorStyle` | `.separator_class(..)`, `.separator_style(..)` | `string`, `StyleProp<ViewStyle>` | none | Each separator: a rule's height and color. |

## Events

| Event | Rust | Payload | When |
|---|---|---|---|
| `onSelect` | `.on_select(..)` | `{ id: string }` | The user chose an item: Return, or a press on its row. |
| `onHighlightChange` | `.on_highlight_change(..)` | `{ highlighted: string \| null }` | The highlight moved (the keys, the pointer, a new query or new items, `highlight`): to preview what Return would run. |
| `onQueryChange` | `.on_query_change(..)` | `{ query: string }` | The user typed in the search field, or Escape cleared it. |
| `onCancel` | `.on_cancel(..)` | none | Escape with an empty query: close what holds the command (a dialog's `open`). |

## Parts

| Part | Inside | Styled with | States |
|---|---|---|---|
| The command | | `class`, `style` | |
| `header` | the command | the app's element | |
| The search bar | the command | `searchBarClass`, `searchBarStyle` | |
| `searchPrefix`, the search field, `searchSuffix` | the search bar | the app's elements; `searchClass`, `searchStyle` | the field's `focus:` |
| The list | the command | `listClass`, `listStyle` | |
| A section's header | the list | `groupClass`, `groupStyle`, `renderGroup` | |
| A separator | the list | `separatorClass`, `separatorStyle` | |
| A row | the list | `itemClass`, `itemStyle` | `focus:` (highlighted), `checked:`, `disabled:`, `hover:`, `active:` |
| A row's content | a row | `renderItem` | `group-focus:`, `group-checked:`, `group-disabled:` under `group` in `itemClass` |
| `empty` | the command | the app's element | |
| `footer` | the command | the app's element | |

Show the highlighted row with `focus:` (see [Design guides](https://nsh.dev/versions/main/docs/design-guides.md#interaction-states)).

## Ref

| Method | Description |
|---|---|
| `focus()` | Gives the search field the keyboard focus (without one, the command). |
| `highlight(id)` | Highlights the item of `id` and scrolls its row into view; an item not shown or disabled stays as it is. |
| `matchedCount()` | `Promise<number>`: how many items the query shows, disabled ones included. |

```tsx
let palette: CommandRef | undefined;

<Command ref={(r) => (palette = r)} items={items} />;
palette?.focus();
```

## A palette in a dialog

Put the command in a [`Dialog`](https://nsh.dev/versions/main/elements/dialog.md) and open it with the app's shortcut. Escape clears the query first; with
an empty query it is `onCancel`, where the app closes the dialog.

```tsx
import { keymap } from "nsh";

const open = signal(false);
keymap.bind("mod+k", () => open.set(!open()));

<Dialog open={open()} onOpenChange={({ open: next }) => open.set(next)}>
  <Command
    items={commands}
    autoFocus
    onCancel={() => open.set(false)}
    onSelect={({ id }) => {
      open.set(false);
      run(id);
    }}
  />
</Dialog>;
```

## A search the app answers

With `filterable={false}` every item the app gives shows: the app searches in `onQueryChange` (a server, a database)
and sets `items` with the results, `loading` while it waits.

```tsx
<Command
  items={results()}
  filterable={false}
  loading={searching()}
  onQueryChange={({ query }) => search(query)}
  searchSuffix={searching() ? <Spinner /> : undefined}
  empty={<Text>No matches</Text>}
/>
```

## Accessibility

- The list has the role `"listbox"`, named by `accessibilityLabel`; each row is an `"option"` named by its item's
  label, checked and disabled as its item is; a section's header is a `"header"`, a separator is hidden.
- The search field is a text field named by `searchAccessibilityLabel` (else `accessibilityLabel`); its placeholder is
  a hint shown while it is empty.
- The search field keeps the keyboard focus while the arrow keys move the highlight, and screen readers hear the
  highlighted label. Without a search field, the highlighted row takes the screen reader's focus.
- While `loading`, the list is busy.

See [Accessibility](https://nsh.dev/versions/main/docs/accessibility.md) for labels, roles and announcements in general.

## Keyboard

| Key | What it does |
|---|---|
| Typing | Filters the items; the first enabled match is highlighted. |
| Down, Up | Highlights the next or the previous item, past disabled ones, from the last to the first and back. |
| Page Down, Page Up | Moves the highlight by the rows in view. |
| Return | Chooses the highlighted item (`onSelect`). |
| Escape | Clears the query; with an empty query, reports `onCancel`. |
| Home, End | Without a search field: the first or the last item (in the field they move its caret). |
| Space, letters, digits | Without a search field: Space chooses, letters and digits highlight by typeahead. |

## Platform notes

- Desktops (macOS, Windows, Linux, GPUI) and the web: the pointer highlights the row it moves over, and a click chooses
  as the button goes down, so the search field keeps the keyboard focus.
- iOS, Android and Mac Catalyst: a tap chooses a row, and the keyboard's return key chooses the highlighted item and
  keeps the field for the next query.
- Every platform draws what the app styles: the command, its search bar, its rows and their content.

Source: https://nsh.dev/versions/main/elements/command

---

# DataTable

`DataTable` shows rows and columns as a spreadsheet does and scrolls both ways over any number of either. Only the
cells in view are made, so a table of a million rows and ten thousand columns scrolls as a small one does. Rows,
columns or cells select, with the pointer and the keyboard; columns have fixed widths, resize with a drag of their
edge, move with a drag of their title, stay at the left while the others scroll, and sort. Titles can sit under group
labels, and a cell or a title can be drawn by the app.

`DataTable` supplies layout, alignment, virtualization and interaction. The app gives its parts their padding,
colors, borders and selection feedback through `classes` and `styles`. Rust makes one with
`nsh_base::data_table()`, TSX with `<DataTable>` from `nsh/base`.

```rust
use nsh_base::{DataTableColumn, data_table};
use nsh_core::prelude::*;

fn column(key: &str, title: &str) -> DataTableColumn {
    let mut column = DataTableColumn::default();
    column.key = key.into();
    column.title = Some(title.into());
    column
}

fn table() -> impl IntoElement {
    data_table()
        .columns(vec![column("name", "Name"), column("city", "City")])
        .flex_1()
}
```

```tsx
import { mount } from "nsh";
import { DataTable, type DataTableColumn } from "nsh/base";

const columns: DataTableColumn[] = [
  { key: "name", title: "Name", width: 160, sortable: true },
  { key: "city", title: "City", width: 120 },
  { key: "score", title: "Score", width: 90, align: "end" },
];

const rows = [
  { name: "Ada", city: "Oslo", score: 91 },
  { name: "Grace", city: "Lima", score: 87 },
  { name: "Linus", city: "Kyoto", score: 78 },
];

function App() {
  return <DataTable columns={columns} data={rows} class="flex-1" />;
}

mount(App);
```

The table fills the box the app gives it (`flex-1`, a height) and scrolls inside: vertically through the rows and
sideways through the columns, with scroll bars (`scrollbar={false}` hides them, `bounces={false}` stops the bounce at the ends where a platform has one).

## Rows and columns

`data` is the rows: objects whose fields the columns' `key`s name, or arrays the columns index by position. Numbers,
booleans and strings show as text. Rust gives the rows a field at a time, each of one type:
`DataTableRows::new(2).texts("symbol", ["AAPL", "MSFT"]).numbers("change", [1.2, -0.4])`. A column is a
`DataTableColumn`:

| Field | Description |
|---|---|
| `key` | Who it is, unique among the columns: the field of the rows its cells show, and the name that events and the ref use. |
| `title` | The text of its title. Default its `key`. |
| `width` | Its width, in points. Default `120`. |
| `minWidth`, `maxWidth` | The narrowest and widest a drag or a fit makes it. Default `20` and `1200`. |
| `fitPadding` | Extra room for the app's padding, icons or badges, added to the widest title or cell text when fitting the column. |
| `align` | `"start"` (the default), `"center"` or `"end"`, for numbers. Cells and title alike. |
| `sortable` | Its title has a sort button that asks for a sort (see [Sorting](#sorting)). |
| `fixed` | It stays at the left while the other columns scroll under it. Fixed columns lead the others, in their order. |
| `resizable`, `movable` | Whether a drag of its edge resizes it and a drag of its title moves it. Default the table's `resizableColumns` and `movableColumns`. |
| `selectable` | Whether it takes part in selection. A column of buttons or checkboxes sets `false`. Default `true`. |
| `cellClass` | Classes of the column's cells, after the `cell` part's: paddings or alignment of one column. |
| `headerClass` | Classes of the column's title, after the `headerCell` part's. |
| `positiveClass` | Classes of the column's cells that hold a rise: a number above zero, or a text starting with `+`. |
| `negativeClass` | Classes of the column's cells that hold a fall: a number below zero, or a text starting with `-`. |

`rowHeight` is the height of a body row (default `32`) and `headerHeight` the height of a title row (default the row
height). `rowHeader` adds a column of row numbers at the left, which selects rows. `stripe` gives the odd rows the
`rowOdd` part.

### Group labels

`groups` puts labels above the columns, the lowest level first. Each level is a list of `{ label, span }` whose spans
add up to the number of columns, or of the level below.

```tsx
<DataTable
  columns={columns}
  data={rows}
  groups={[
    [{ label: "Person", span: 2 }, { label: "Result", span: 1 }],
  ]}
  class="flex-1"
/>
```

## Any number of rows

The table asks for rows by position, and the app serves them. `rowCount` is the total number of rows, `data` the rows
the app holds, and `dataStart` the position of the first of them. Rows outside `data` are empty until the app supplies
them. `onVisibleRowsChange` reports the rows in view, `{ range: { start, end } }`, at every scroll step, and is the place to fetch
the page around them.

```tsx
const ROWS = 1_000_000;
const page = signal({ start: 0, rows: load(0) });

<DataTable
  columns={columns}
  data={page().rows}
  dataStart={page().start}
  rowCount={ROWS}
  onVisibleRowsChange={({ range: { start, end } }) => {
    // Keep the rows in view inside the page held.
    const held = page();
    if (start < held.start || end > held.start + held.rows.length) {
      const first = Math.max(0, start - 200);
      page.set({ start: first, rows: load(first) });
    }
  }}
  class="flex-1"
/>
```

For a list that grows at its end, set `hasMore`: `onLoadMore` fires once for each number of rows when the rows in view
come within `loadMoreThreshold` (default `20`) of the last. While `loading` is true it waits, and the `loadingView`
slot shows over the rows. The `empty` slot shows when there are no rows.

Past a few million points of content the scroll bars span a scaled range, so a million rows still scroll to every row.

## Selection

Three switches decide what a press selects, as in gpui-component:

| Prop | A press selects | `selection` |
|---|---|---|
| `rowSelectable` (default `true`) | A row: any of its cells, or its row header | `{ row }` |
| `columnSelectable` (default `true`) | A column: its title | `{ column }` |
| `cellSelectable` (default `false`) | A cell; the row header (shown by default with it) selects rows | `{ row, column }` |

With `cellSelectable` and the row header hidden (`rowHeader={false}`), pressing the selected cell again selects its
row. A press with Shift or the platform's command key held selects a row only while `selectOnModifierPress` (default
`true`), so an app that keeps its own multi-row selection handles those presses itself: `onRowPress` reports every
press of the body with its row, the column under the pointer, the clicks in a row and the modifier keys held. A column whose `selectable` is
`false` selects neither itself nor its cells.

Rows count from 0 in the data, and a column is its index among `columns`, whatever order the user moved them to.
`onSelectionChange` reports what the user selected (`null` for nothing). The `selection` prop sets the selection from
the app; leave it unset and the table keeps it. `onDoublePress` reports a row, a cell or a title pressed twice, and
`onContextMenu` a secondary or long press with the point to open the app's [`Menu`](https://nsh.dev/versions/main/elements/menu.md) at. Both name the
cell under the pointer (its `row` and `column`), a row's number (`row` only) or a title (`column` only). Until the next
press, the cell a menu was asked for has the `cellActive` part, or its row the `rowActive` part where cells do not
select.

Screen readers get a grid (named by `accessibilityLabel`) of column headers and cells, the selected ones said to be
selected.

## Keyboard

Pressing the table, or reaching it with Tab (macOS, the web), gives it the keyboard until another press, the focus
moving elsewhere or `blur()`; `focus()` gives it from the app. The table is one stop of Tab: inside it Tab moves the
selection, and Escape gives the keyboard back. Its columns' resize handles take the pointer only, in a terminal too, where a handle shows its line while the pointer is on it and a title's sort is one glyph (`▲`, `▼`, `↕` unsorted).

| Keys | What they do |
|---|---|
| Arrow keys | Move the selection by a row, a column or a cell, scrolling it into view. |
| Tab, Shift+Tab | Move to the next or the previous column. |
| Page Up, Page Down | Move by a page of rows. |
| Home, End | Move to the first or the last. |
| Escape | Clears the selection, then gives the keyboard back. |
| Copy shortcut | Puts the selection's text on the clipboard (`copy()`). |

`loopSelection` (default `true`) makes the arrow keys go around the ends.

## Sorting

A `sortable` column has a sort button at the end of its title, a small ghost button dimmed while the column is unsorted. Pressing it reports the next sort (`{ key, direction }`) in the cycle of unsorted,
ascending, descending and unsorted again, with `onSortChange({ sort })` (`null` to clear). The table does
not reorder the rows: the app sorts its data, or asks its server for rows in the new order, and sets `sort` so the
title shows it. Because the app owns the order, sorting works the same over a million rows the app never holds.

```tsx
<DataTable
  columns={columns}
  data={rows()}
  sort={sort()}
  onSortChange={({ sort: next }) => {
    sort.set(next ?? undefined);
    rows.set(sorted(people, next));
  }}
  class="flex-1"
/>
```

## Resizing and moving columns

A drag of a column's trailing edge resizes it within its `minWidth` and `maxWidth`, and `onColumnResize({ key, width })`
reports every step. Pressing the edge twice in a row fits the column to its widest text and title. A drag of a title moves the column, and a line shows where it will drop; `onColumnMove` reports
`{ key, from, to, order }`, `order` being the `key`s of all the columns in the order shown. Fixed columns stay among
the fixed ones. `resizableColumns` and `movableColumns` turn both off for the table, and a column's `resizable` and
`movable` win over them.

## Live data

A quote table changes many times a second. The app formats the rows in view and a reach around them (it knows them
from `onVisibleRowsChange`) and hands those over as `data` from `dataStart`, so an update costs what is on screen,
whatever the number of rows. Rises and falls take their colors from the column's `positiveClass` and `negativeClass`,
applied natively to the cells whose value is above or below zero (or whose text starts with `+` or `-`).

```tsx
const tone = { positiveClass: "text-green-600", negativeClass: "text-red-600" };
const columns: DataTableColumn[] = [
  { key: "symbol", title: "Symbol", fixed: true },
  { key: "price", title: "Price", align: "end", sortable: true },
  { key: "change", title: "Chg%", align: "end", ...tone },
];
```

Rows and columns are slots the table makes once and keeps: scrolling gives them other rows and columns to show, so a
scroll, however long, changes texts and places only.

## Drawing cells and titles

`renderCell` draws the cells of the app's own where a column is not just text (a badge, a button). It is called for the
cells in view only, with a `DataTableCell`: `row`, `column`, `key`, `text` (what the table would show) and `selected`.
The app looks up its own data by `row`. `renderHeaderCell` draws a title across its cell, told a `DataTableHeaderCell`:
`column`, `key`, `title`, `sort` (the direction, or none) and `selected`.

```tsx
<DataTable
  columns={columns}
  data={rows()}
  renderCell={(cell) =>
    cell.key === "status" ? (
      <View class={cell.text === "open" ? "rounded bg-green-500/20 px-2" : "rounded bg-muted px-2"}>
        <Text class="text-xs">{cell.text}</Text>
      </View>
    ) : (
      <Text class="px-2 text-sm">{cell.text}</Text>
    )
  }
  class="flex-1"
/>
```

`fontFamily` and `fontSize` (default `14`) set the font of the cells, which the table also measures texts in to fit
columns.

## The ref

`ref` gives a `DataTableRef`. A method given a row, a column or a column key the table does not have changes nothing
and logs a warning naming the method and the value; `fitColumn` rejects with a `TypeError` for an unknown key.

| Method | Description |
|---|---|
| `scrollToRow(row, animated?)` | Scrolls a row into view. |
| `scrollToColumn(key, animated?)` | Scrolls a column into view. |
| `selection()` | What is selected, `null` for nothing. |
| `select(selection)` | Selects (`null`: nothing) and brings it into view, without `onSelectionChange`. |
| `visibleRows()`, `visibleColumns()` | The rows and the scrolling columns in view, as `{ start, end }` (`end` excluded). |
| `columnWidths()` | The widths now, in the order of `columns`. |
| `setColumnWidth(key, width)` | Sets a column's width, within its limits. |
| `fitColumn(key)` | Sets a column as wide as its widest text and its title need, among the rows in view and up to a thousand more around them. It returns the width. |
| `dump(start?, end?)` | The texts of the rows given (default all those held) and of the titles, as shown: `{ headers, rows }`, for export. |
| `copy()` | Puts the selection's text on the clipboard: a row's cells with tabs between, a column's with line breaks, a cell's text. |
| `focus()`, `blur()` | Gives the keyboard to the table or takes it. |
| `menuTarget()`, `clearMenuTarget()` | What the last context menu was asked for at (`{ row?, column? }`, marked by `cellActive` / `rowActive`), and dropping that mark when the app's menu closes. |

## Styling the parts

`class` and `style` style the table's box. `classes` takes Tailwind classes by part and `styles` inline styles by part;
parts provide the table's structure and alignment; their classes supply the appearance, and `styles` win over classes.

```tsx
<DataTable
  columns={columns}
  data={rows()}
  stripe
  class="flex-1 rounded-lg border border-border"
  classes={{
    header: "bg-secondary",
    headerCell: "pl-2 pr-1",
    headerContent: "gap-1",
    cell: "px-2",
    resizeHandle: "bg-border group-hover:bg-primary",
    sortAscending: "text-muted-foreground opacity-60 selected:text-foreground selected:opacity-100",
    sortDescending: "text-muted-foreground opacity-60 selected:text-foreground selected:opacity-100",
    rowSelected: "bg-primary/10",
    rowHover: "bg-muted/50",
    fixedEdge: "bg-border",
  }}
/>
```

| Part | What it is |
|---|---|
| `root` | The table's box: its border, radius and background |
| `header` | The header across the table, its rows of group labels and titles |
| `groupCell` | A group label above the columns it spans |
| `headerCell` | Every column's title cell |
| `headerContent` | The label and sort button's layout row; set their gap here |
| `headerCellDragging` | The dragged title, after `headerCell` |
| `headerCellSorted` | The title of the column the table is sorted by, after `headerCell` |
| `headerCellSelected` | The title of the selected column, after `headerCell` |
| `sortIndicator` | The sort button of a sortable column |
| `sortAscending`, `sortDescending` | Its two chevrons; `selected:` applies to the sorted direction |
| `resizeHandle` | The line at a column's trailing edge that a drag resizes |
| `moveIndicator` | The line where a dragged column will drop |
| `row` | Every body row |
| `rowOdd` | The odd rows, after `row` (`stripe`) |
| `rowHover` | The row the pointer is over, after `row` |
| `rowSelected` | The selected row, after `row` |
| `rowActive` | The row a context menu was asked for where cells do not select, until the next press, after `row` |
| `cell` | Every body cell |
| `cellSelected` | The selected cell, after `cell` |
| `cellActive` | The cell a context menu was asked for, until the next press, after `cell` |
| `cellColumnSelected` | The cells of the selected column, after `cell` |
| `rowHeader` | The row header cells, the row numbers |
| `rowHeaderCorner` | The corner above the row headers |
| `fixedEdge` | The line at the fixed columns' trailing edge, over the columns that scroll under them |
| `empty` | The box of the `empty` slot |

## Props

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `columns` | `.columns(..)` | `DataTableColumn[]` | `[]` | The columns, left to right. Fixed ones lead. |
| `data` | `.data(..)` | `Row[]` | `[]` | The rows: objects by column `key`, or arrays by position. |
| `rowCount` | `.row_count(..)` | `number` | the rows held | How many rows there are in all. |
| `dataStart` | `.data_start(..)` | `number` | `0` | The row of the first row of `data`. |
| `rowClasses` | `.row_classes(..)` | `string[]` | `[]` | Classes of the rows given, by their place in `data`: a row's own look, with no call into JS per row. |
| `rowHeight` | `.row_height(..)` | `number` | `32` | The height of a body row, in points; in a terminal a row is one Cell. |
| `headerHeight` | `.header_height(..)` | `number` | the row height | The height of a title row; in a terminal a title row is one Cell. |
| `groups` | `.groups(..)` | `DataTableColumnGroup[][]` | `[]` | Labels above the columns, lowest level first. |
| `sort` | `.sort(..)` | `DataTableSort` | | What the data is sorted by, shown on the title. |
| `rowSelectable` | `.row_selectable(..)` | `boolean` | `true` | Presses and keys select rows. |
| `columnSelectable` | `.column_selectable(..)` | `boolean` | `true` | A title's press selects its column, and the horizontal keys move between columns. |
| `cellSelectable` | `.cell_selectable(..)` | `boolean` | `false` | Presses and keys select cells. |
| `selectOnModifierPress` | `.select_on_modifier_press(..)` | `boolean` | `true` | A press with Shift or the command key held selects a row. |
| `selection` | `.selection(..)` | `DataTableSelection` | | What is selected, when the app sets it. |
| `loopSelection` | `.loop_selection(..)` | `boolean` | `true` | The arrow keys go around the ends. |
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | none | What screen readers call the table. |
| `rowHeader` | `.row_header(..)` | `boolean` | shown with `cellSelectable` | A column of row numbers at the left. |
| `stripe` | `.stripe(..)` | `boolean` | `false` | Odd rows get the `rowOdd` part. |
| `resizableColumns` | `.resizable_columns(..)` | `boolean` | `true` | A drag of a column's edge resizes it. |
| `movableColumns` | `.movable_columns(..)` | `boolean` | `true` | A drag of a title moves its column. |
| `loading` | `.loading(..)` | `boolean` | `false` | The table is loading: `onLoadMore` waits and `loadingView` shows. |
| `hasMore` | `.has_more(..)` | `boolean` | `false` | There are more rows to load. |
| `loadMoreThreshold` | `.load_more_threshold(..)` | `number` | `20` | How many rows from the last make `onLoadMore` fire. |
| `fontFamily` | `.font_family(..)` | `string` | inherited | The font of the cells. |
| `fontSize` | `.font_size(..)` | `number` | `14` | The font size of the cells, in points. |
| `scrollbar` | `.scrollbar(..)` | `boolean` | `true` | The scroll bars. |
| `verticalScrollbar`, `horizontalScrollbar` | `.vertical_scrollbar(..)`, `.horizontal_scrollbar(..)` | `boolean` | `scrollbar` | One axis's scroll bar (the horizontal one is the desktops' bar under the table). |
| `bounces` | `.bounces(..)` | `boolean` | `true` | Whether scrolling bounces at the ends, where the platform does so. |
| `renderCell` | `.render_cell(..)` | `(cell: DataTableCell) => JSX.Element` | | Draws the cells in view. |
| `renderHeaderCell` | `.render_header_cell(..)` | `(cell: DataTableHeaderCell) => JSX.Element` | | Draws the titles. |
| `empty` | `.empty(..)` | `JSX.Element` | | What shows when there are no rows. |
| `loadingView` | `.loading_view(..)` | `JSX.Element` | | What shows over the rows while `loading`. |
| `classes` | `.classes(..)` | `DataTableClasses` | `{}` | Tailwind classes by part. |
| `styles` | `.styles(..)` | `DataTableStyles` | `{}` | Inline styles by part, over the classes. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | | The table's box. |

## Events

| Event | Rust | Description |
|---|---|---|
| `onSelectionChange` | `.on_selection_change(\|selection: &Option<DataTableSelection>\| ..)` | The user changed the selection: `{ selection }`, a `{ row?, column? }` or `null`. |
| `onRowPress` | `.on_row_press(\|event: &DataTablePress\| ..)` | A row or cell was pressed: `{ row, column?, clicks, shift, control, alt, platform }`. |
| `onDoublePress` | `.on_double_press(\|target: &DataTableTarget\| ..)` | A row, cell or title was pressed twice: `{ target }`, a `{ row?, column? }`. |
| `onContextMenu` | `.on_context_menu(\|event: &DataTableContextMenu\| ..)` | A context menu was asked for: `{ row?, column?, x, y }`, the point in the root view. |
| `onSortChange` | `.on_sort_change(\|sort: &Option<DataTableSort>\| ..)` | A sort button was pressed: `{ sort }`, the next sort `{ key, direction }` or `null`. |
| `onColumnResize` | `.on_column_resize(\|key: &SharedString, width: &Points\| ..)` | A column was resized (`{ key, width }`), at every step of a drag and once more when a fit sets it. |
| `onColumnMove` | `.on_column_move(\|event: &DataTableColumnMove\| ..)` | A column was moved: `{ key, from, to, order }`. |
| `onVisibleRowsChange` | `.on_visible_rows_change(\|range: &DataTableRange\| ..)` | The rows in view changed: `{ range }`, a `{ start, end }`. Fetch rows from here. |
| `onVisibleColumnsChange` | `.on_visible_columns_change(\|range: &DataTableRange\| ..)` | The scrolling columns in view changed: `{ range }`. |
| `onLoadMore` | `.on_load_more(\|\| ..)` | The rows in view came within `loadMoreThreshold` of the last while `hasMore` and not `loading`. |

## Related

- [Editor](https://nsh.dev/versions/main/elements/editor.md) and [DiffView](https://nsh.dev/versions/main/elements/diff-view.md): the other data-heavy base components.
- [Menu](https://nsh.dev/versions/main/elements/menu.md): the menu to open from `onContextMenu`.
- [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md): the other base components.

Source: https://nsh.dev/versions/main/elements/data-table

---

# DatePicker

A date picker sets a date from a [Calendar](https://nsh.dev/versions/main/elements/calendar.md) that opens from the app's trigger: a due date, a birthday,
with `range` the days of a trip, with `timePrecision` a date and a time of day. Like [Select](https://nsh.dev/versions/main/elements/select.md), it opens as
each device expects:

- On the desktops and in desktop browsers, a popup at the trigger; opening it puts the keyboard on the days.
- On phones and tablets, a sheet at the bottom of the screen over a backdrop.

The picker owns the behavior: the value (the app's, or its own), the open state, the calendar, the time, the presets,
the keyboard and what screen readers hear. The look is the app's: it draws the trigger (with the value, a
placeholder, an icon) and styles the popup, the calendar's parts, the presets and the time field.

```rust
use chrono::NaiveDate;
use nsh_base::{DateRangePreset, DateTime, PickedDate, date_picker, theme};
use nsh_core::prelude::*;

fn trip_dates() -> impl IntoElement {
    let trip = signal(DateTime::Range(None, None));
    let title = move || {
        trip.get()
            .format("%b %-d")
            .map(|s| s.to_string())
            .unwrap_or_else(|| "Pick dates".to_string())
    };
    let day = |m, d| NaiveDate::from_ymd_opt(2026, m, d).unwrap();
    date_picker()
        .range(true)
        .number_of_months(2)
        .value(move || trip.get())
        .on_change(move |next: &PickedDate| trip.set(next.value))
        .presets(vec![
            DateRangePreset::range("This week", day(10, 25), day(10, 31)),
            DateRangePreset::range("Next week", day(11, 1), day(11, 7)),
        ])
        .accessibility_label("Trip")
        .offset(px(4.0))
        .popup_style(|s| {
            s.p_3()
                .rounded_lg()
                .border_1()
                .border_color(move || theme().border)
                .bg(move || theme().popover)
                .shadow_md()
        })
        .trigger(
            view()
                .h_9()
                .w_56()
                .px_3()
                .justify_center()
                .rounded_md()
                .border_1()
                .border_color(move || theme().input)
                .child(text(title)),
        )
}
```

```tsx
import { mount, signal, Text, View } from "nsh";
import { DatePicker, type DatePickerValue } from "nsh/base";

function App() {
  const due = signal<DatePickerValue>(null);
  return (
    <DatePicker
      value={due()}
      onChange={({ value }) => due.set(value)}
      timePrecision="minute"
      cleanable
      clearButton={<Text>×</Text>}
      clearButtonAccessibilityLabel="Clear the due date"
      presets={[{ label: "Tomorrow 9:00", value: "2026-10-29T09:00" }]}
      accessibilityLabel="Due"
      offset={4}
      popupClass="rounded-lg border border-border bg-popover p-3 text-popover-foreground shadow-md"
      backdropClass="bg-black/40"
      contentClass="flex-row gap-3"
      presetClass="rounded-md px-2 py-1.5 text-sm hover:bg-accent"
      headerClass="flex-row items-center justify-between"
      rowClass="flex-row justify-between"
      itemClass="h-8 min-w-8 items-center justify-center rounded-md text-sm focus:ring-2 focus:ring-ring selected:bg-primary selected:text-primary-foreground disabled:opacity-50"
      timeClass="mt-2 gap-3"
      timeLabel={<Text class="text-sm">Time</Text>}
      timeAccessibilityLabel="Due time"
      timeFieldClass="flex-row rounded-md border border-input px-2 py-1"
      segmentClass="text-sm tabular-nums focus:bg-accent"
      trigger={
        <View class="h-9 w-56 justify-center rounded-md border border-input px-3 hover:bg-accent focus-visible:ring-2 focus-visible:ring-ring">
          <Text>{typeof due() === "string" ? (due() as string).replace("T", " ") : "Pick a date"}</Text>
        </View>
      }
    />
  );
}

mount(App);
```

`DatePicker` comes from [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md), the `nsh-base` crate in Rust. In Rust, `date_picker()`
makes one with a setter per prop (`.value(..)`, `.range(..)`, `.time_precision(..)`) and a listener per event
(`.on_change(..)`). Its value is a `DateTime` (`DateTime::Single`, `DateTime::Range`, from `chrono` dates or dates and
times); `onChange` gives a `PickedDate`, the value with the picker's time precision.

## Value

The value is in the forms of the HTML inputs: an ISO date, `"2026-10-28"`, as `<input type="date">`'s; with `range`
`[start, end]`; with `timePrecision` a date and time, `"2026-10-28T09:30"` (`"2026-10-28T09:30:15"` at seconds), as
`<input type="datetime-local">`'s; `null` is none. With `value`, the app owns it: the picker shows it and reports each
change with `onChange({ value })`; the app sets `value` to follow it. Left out, the picker keeps its own value, from
`defaultValue` at first.

- A single date: a press on a day sets the value and closes the popup.
- With `range`, the first press starts the range and the second ends it, as a [calendar's](https://nsh.dev/versions/main/elements/calendar.md#value); the
  complete range sets the value and closes the popup.
- With `timePrecision` (a single date only), a time field shows under the calendar and every edit of the time is
  reported. On the desktops, picking a day keeps the popup open for the time and reports the date with its time; a
  press on the selected day again closes the popup. On phones and tablets, a tap on a day picks it at its time and
  closes the sheet, as a single date does; the sheet opens again for the time. A day picked before any time gets
  `defaultTime` (default `00:00`). `hourCycle` is how the field counts the hours.

`cleanable` adds a clear button while there is a value: a press clears it (`onChange({ value: null })`). It comes
after the trigger, not inside it, so a press on it never opens the popup; the app places it and fills it
(`clearButton`), as a [select's clear button](https://nsh.dev/versions/main/elements/select.md#value).

## Presets

`presets` are buttons beside the calendar that set the value: "Today", "Last 7 days", "Tomorrow at 9". Each is
`{ label, value }`, `value` a date, a range or dates and times, kept as given; a press sets it and closes the popup.
`contentClass` lays out the presets' column and the calendar with the time (a row, `flex-row`); `presetsClass` styles
the column, `presetClass` each button.

## The calendar

Every prop of [Calendar](https://nsh.dev/versions/main/elements/calendar.md) but its value passes on to the picker's: `numberOfMonths`, `firstDayOfWeek`,
`disabledMatcher`, `yearRange`, `previousAccessibilityLabel`, `nextAccessibilityLabel`, the parts (`headerClass` to
`itemStyle`) and `renderItem`. `calendarClass` and `calendarStyle` style the calendar itself. Its views and keys are a
calendar's.

The time row (`timeClass`, `timeStyle`) holds `timeLabel`, the app's words for it ("Time"), at its start and the time
field (`timeFieldClass`, `timeFieldStyle`, `timeAccessibilityLabel`) at its end: a row with its items centered and
spread apart (`flex-row items-center justify-between`, as `gpui-component`'s). The field's segments are a
[TimeField](https://nsh.dev/versions/main/elements/time-field.md)'s (`segmentClass`, `separatorClass`, `renderSegment`).

## Props

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `value` | `.value(..)` | `DatePickerValue` | none | The value, owned by the app. |
| `defaultValue` | `.default_value(..)` | `DatePickerValue` | `null` | The value at first, without `value`. |
| `range` | `.range(..)` | `boolean` | `false` | Pick a range of dates. |
| `open`, `defaultOpen` | `.open(..)`, `.default_open(..)` | `boolean` | `false` | The open state, the app's or the picker's own. |
| `disabled` | `.disabled(..)` | `boolean` | `false` | It stays closed and takes no presses or keyboard focus. |
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | none | What screen readers call it. |
| `dateFormat` | `.date_format(..)` | `string` | `"%Y/%m/%d"` and the time | How screen readers hear the value, in `chrono`'s format. |
| `timePrecision` | `.time_precision(..)` | `"minute" \| "second"` | none | Edit the time of day too, down to this. |
| `hourCycle` | `.hour_cycle(..)` | `"h23" \| "h12"` | `"h23"` | How the time field counts the hours. |
| `defaultTime` | `.default_time(..)` | `string` | `"00:00"` | The time a date gets before the user sets one. |
| `cleanable` | `.cleanable(..)` | `boolean` | `false` | A clear button while there is a value. |
| `presets` | `.presets(..)` | `DateRangePreset[]` | `[]` | Buttons in the popup that set the value. |
| `numberOfMonths`, `firstDayOfWeek`, `disabledMatcher`, `yearRange` | as `Calendar`'s | as `Calendar`'s | as `Calendar`'s | The calendar's months, weeks, disabled dates and years. |
| `previousAccessibilityLabel`, `nextAccessibilityLabel` | as `Calendar`'s | `string` | none | What screen readers say for the calendar's Previous and Next. |
| `placement`, `align`, `offset`, `margin` | `.placement(..)`, ... | as `Select`'s | `"bottom"`, `"start"`, 0, 0 | Desktops: where the popup goes against the trigger. |
| `popupClass`, `popupStyle` | `.popup_class(..)`, `.popup_style(..)` | `string`, `StyleProp<ViewStyle>` | none | The popup (desktops) or the sheet (touch screens). |
| `backdropClass`, `backdropStyle` | `.backdrop_class(..)`, `.backdrop_style(..)` | `string`, `StyleProp<ViewStyle>` | none | The backdrop behind the sheet. |
| `contentClass`, `contentStyle` | `.content_class(..)`, `.content_style(..)` | `string`, `StyleProp<ViewStyle>` | none | The popup's content: the presets beside the calendar and the time. |
| `presetsClass`, `presetsStyle` | `.presets_class(..)`, `.presets_style(..)` | `string`, `StyleProp<ViewStyle>` | none | The presets' column. |
| `presetClass`, `presetStyle` | `.preset_class(..)`, `.preset_style(..)` | `string`, `StyleProp<TextStyle>` | none | Each preset's button. |
| `calendarClass`, `calendarStyle` | `.calendar_class(..)`, `.calendar_style(..)` | `string`, `StyleProp<ViewStyle>` | none | The calendar. |
| `headerClass` … `itemStyle` | as `Calendar`'s | as `Calendar`'s | none | The calendar's header, body, months, rows and items. |
| `renderItem` | `.render_item(..)` | `(item: CalendarEntry) => JSX.Element` | none | Each item of the calendar, drawn by the app from what it is; its states are the items' classes, as `Calendar`'s. |
| `timeClass`, `timeStyle` | `.time_class(..)`, `.time_style(..)` | `string`, `StyleProp<ViewStyle>` | none | The time's row: its label at the start, the field at the end. |
| `timeLabel` | `.time_label(..)` | `JSX.Element` | none | What the time's row shows before the field. |
| `timeFieldClass`, `timeFieldStyle` | `.time_field_class(..)`, `.time_field_style(..)` | `string`, `StyleProp<ViewStyle>` | none | The time field. |
| `timeAccessibilityLabel` | `.time_accessibility_label(..)` | `string` | none | What screen readers call the time field. |
| `segmentClass`, `segmentStyle`, `separatorClass`, `separatorStyle`, `renderSegment` | as `TimeField`'s | as `TimeField`'s | none | The time field's segments and `:`. |
| `clearButtonClass`, `clearButtonStyle` | `.clear_button_class(..)`, `.clear_button_style(..)` | `string`, `StyleProp<ViewStyle>` | none | The clear button (`cleanable`). |
| `clearButton` | `.clear_button(..)` | `JSX.Element` | none | The content of the clear button. |
| `clearButtonAccessibilityLabel` | `.clear_button_accessibility_label(..)` | `string` | none | What screen readers call the clear button. |
| `trigger` | `.trigger(..)` | `JSX.Element` | none | What opens the popup when pressed; the popup is placed against it. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The view around the trigger. |

## Events

| Event | Rust | Description |
|---|---|---|
| `onChange` | `.on_change(\|value\| ..)` | The value changed (a day, a range's end, a preset, the time, the clear button): `{ value }`. Set `value` to follow it. |
| `onOpenChange` | `.on_open_change(\|e\| ..)` | The popup opened or closed, with why (`{ open, reason }`). Set `open` to follow it. |
| `onOpen`, `onClose` | `.on_open(..)`, `.on_close(..)` | The popup is shown, or gone. |
| `onCancel` | `.on_cancel(..)` | The user closed the popup without a choice (Escape or back, a press outside or on the backdrop). |

## Parts

| Part | Where | Styled with |
|---|---|---|
| The trigger | the picker's view | the app's own element (`trigger`) |
| The clear button | the picker's view, after the trigger (`cleanable`, while there is a value) | `clearButtonClass`, `clearButtonStyle`; its content `clearButton` |
| The popup or sheet | over everything, at the trigger (desktops) or at the bottom (touch screens) | `popupClass`, `popupStyle` |
| The backdrop | behind the sheet (touch screens) | `backdropClass`, `backdropStyle` |
| The content | the popup | `contentClass`, `contentStyle` |
| The presets | the content, first (`presets`) | `presetsClass`, `presetsStyle`; each `presetClass`, `presetStyle` |
| The calendar | the content | `calendarClass`, `calendarStyle`, and [Calendar](https://nsh.dev/versions/main/elements/calendar.md#parts)'s parts |
| The time's row | under the calendar (`timePrecision`) | `timeClass`, `timeStyle`; its label `timeLabel` |
| The time field | the time's row | `timeFieldClass`, `timeFieldStyle`, and [TimeField](https://nsh.dev/versions/main/elements/time-field.md#parts)'s parts |

## Keyboard

| Key | Action |
|---|---|
| Return (on the trigger) | Opens the popup, or closes it. |
| Delete, Backspace (on the trigger) | Clears the value while the popup is closed. |
| Escape | Closes the popup without a choice. |

In the popup, the calendar's keys move between days and pick one (see [Keyboard](https://nsh.dev/versions/main/elements/calendar.md#keyboard)) and the
time field's edit the time (see [Keyboard](https://nsh.dev/versions/main/elements/time-field.md#keyboard)).

## Accessibility

- The trigger is a combobox for screen readers: its label is `accessibilityLabel`, its value the date as `dateFormat`
  writes it (by default `2026/10/28`, with the time at `timePrecision`), and it says whether the popup is expanded.
  `disabled` dims it.
- The calendar's days are buttons named by their ISO dates (see [Accessibility](https://nsh.dev/versions/main/elements/calendar.md#accessibility)); the
  presets are buttons named by their labels; the time field is named by `timeAccessibilityLabel`.
- The clear button is a button named by `clearButtonAccessibilityLabel`.

See [Accessibility](https://nsh.dev/versions/main/docs/accessibility.md) for labels, roles and announcements in general.

Source: https://nsh.dev/versions/main/elements/date-picker

---

# Dialog

A dialog presents content over the rest of the app in its own native window layer: a presented view controller on iOS
and Mac Catalyst, a Dialog on Android, a layer over the whole window on the desktops and the web. It is used for
full-screen flows, sheets and dialogs. The system's own gestures (swiping a sheet down, the Android back button,
Escape) work, and are decided natively. Rust makes one with `nsh_base::dialog()`, TSX with `<Dialog>` from `nsh/base`.

The dialog owns its behavior and leaves its look to the app: its styles style the popup (the view holding the
children), and in TSX `backdropClass` / `backdropStyle` add a backdrop behind it.

```rust
use nsh_base::{button, dialog};
use nsh_core::prelude::*;

/// A blue button with a white label.
fn primary(label: &'static str, on_press: impl Fn() + 'static) -> impl IntoElement {
    button()
        .on_press(on_press)
        .items_center()
        .rounded_lg()
        .bg(rgb(0x2563eb))
        .px_4()
        .py_3()
        .active(|s| s.opacity(0.7))
        .child(text(label).font_weight(FontWeight::SEMIBOLD).text_color(white()))
}

fn example() -> impl IntoElement {
    let open = signal(false);
    view()
        .flex_1()
        .justify_center()
        .p_6()
        .child(primary("Open", move || open.set(true)))
        .child(when(open, move || {
            dialog()
                .presentation(ModalPresentation::PageSheet)
                .on_cancel(move || open.set(false))
                .flex_1()
                .bg(white())
                .child(
                    view()
                        .flex_1()
                        .px_5()
                        .pt_safe_area_plus(px(20.0))
                        .pb_safe_area_plus(px(20.0))
                        .gap_3()
                        .child(text("A sheet").text_2xl().font_weight(FontWeight::BOLD))
                        .child(primary("Close", move || open.set(false))),
                )
        }))
}
```

```tsx
import { signal, Text, View } from "nsh";
import { Button, Dialog } from "nsh/base";

function Example() {
  const open = signal(false);
  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Button onPress={() => open.set(true)} class="items-center rounded-lg bg-blue-600 px-4 py-3 active:opacity-70">
        <Text class="font-semibold text-white">Open</Text>
      </Button>
      <Dialog open={open()} presentation="pageSheet" onOpenChange={(e) => open.set(e.open)} class="flex-1 bg-white">
        <View
          style={{
            flex: 1,
            gap: 12,
            paddingHorizontal: 20,
            paddingTop: "calc(env(safe-area-inset-top) + 20px)",
            paddingBottom: "calc(env(safe-area-inset-bottom) + 20px)",
          }}
        >
          <Text style={{ fontSize: 24, fontWeight: "700" }}>A sheet</Text>
          <Button onPress={() => open.set(false)} class="items-center rounded-lg bg-blue-600 px-4 py-3 active:opacity-70">
            <Text class="font-semibold text-white">Close</Text>
          </Button>
        </View>
      </Dialog>
    </View>
  );
}
```

In TSX, the dialog is shown while `open` is not `false` and closed when it becomes `false`. In Rust, it is presented
while it is in the view and dismissed when it leaves it, so `when` holds it. Either way it gives its content the dialog's
safe-area insets, which the [`env(safe-area-inset-*)`](https://nsh.dev/versions/main/elements/safe-area.md) variables and `safeAreaInsets()` (`cx.insets()` in a Rust
component) inside it read. [`Button`](https://nsh.dev/versions/main/elements/button.md), also from `nsh/base`, is a press target styled by the app.

`nsh_core::prelude` also has an older, deprecated `dialog` function: import `nsh_base::dialog` by name, as above,
and the explicit import takes its place. For the system's alert or action sheet, use
[`AlertDialog`](https://nsh.dev/versions/main/elements/alert-dialog.md).

## Props

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `open` | in the view while open (`when(open, ..)`) | `boolean` | `true` | Shown while true. |
| `animation` | `.animation(ModalAnimation::Fade)` | `"slide" \| "fade" \| "none"` | `"slide"` | How it comes in and goes. |
| `transitionShader` | `.transition_shader(TransitionShader::new(program))` | `{ source: string; uniforms?: Record<string, ShaderUniform>; duration?: number }` | none | It comes in and goes through a WGSL shader in place of its `animation`: `shade(uv)` reads what is behind as `sample_from` and the dialog as `sample_to` while `nsh.progress` runs from 0 to 1 over `duration` milliseconds (350 by default), and from 1 back to 0 as it closes. When the system asks for less motion, it takes its own `animation`. See [Shader](https://nsh.dev/versions/main/elements/shader.md). |
| `presentation` | `.presentation(ModalPresentation::PageSheet)` | `"fullScreen" \| "pageSheet" \| "formSheet"` | `"fullScreen"` | Its form on iOS: `fullScreen` covers the screen with a clear background; `pageSheet` and `formSheet` are system sheets that keep what is behind visible (`formSheet` is a smaller centered sheet on large screens). |
| `closeOnEscape` | `.close_on_escape(..)` | `boolean` | `true` | Escape and the Android back button close it natively. |
| `closeOnBackdropPress` | `.close_on_backdrop_press(..)` | `boolean` | `true` | A press on the backdrop closes it. |
| `closeOnSwipe` | `.close_on_swipe(..)` | `boolean` | `true` | Swiping a sheet down (iOS, phone browsers) closes it natively. |
| `statusBar` | `.status_bar(..)` | `{ foreground?, hidden?, animated? }` | none | iOS and Android: the status bar while the dialog is open, over the pages' ([Status bar](https://nsh.dev/versions/main/modules/nsh-base.md#status-bar)). |
| `onOpen` | `.on_open(..)` | `() => void` | | It finished appearing. |
| `onClose` | `.on_close(..)` | `() => void` | | It went away: the user closed it, or the app removed it. |
| `onCancel` | `.on_cancel(..)` | `() => void` | | The user tried to close it (Escape, back, a backdrop press, a swipe down), whether or not a `closeOn*` flag let it close. |
| `onOpenChange` | `.on_cancel(..)` | `(e: { open: boolean; reason: "cancel" \| "backdropPress" \| "swipe" }) => void` | | The user closed it: keep `open` in sync here. In Rust, `on_cancel` removes the dialog from the view. |
| `class`, `style` | `Styled` methods | `string`, `StyleProp<ViewStyle>` | | The popup: the view holding the children. |
| `backdropClass`, `backdropStyle` | a child view filling the dialog | `string`, `StyleProp<ViewStyle>` | | A backdrop filling the dialog behind the popup, present when either is set. |
| `children` | `.child(..)` | `JSX.Element` | | The content. |

| `ios` key | Rust | Type | Default | Description |
|---|---|---|---|---|
| `supportedOrientations` | `.supported_orientations(..)` | `("portrait" \| "portrait-upside-down" \| "landscape" \| "landscape-left" \| "landscape-right")[]` | the presenter's | The orientations the dialog allows. |

| `android` key | Rust | Type | Default | Description |
|---|---|---|---|---|
| `statusBarTranslucent` | `.status_bar_translucent(..)` | `boolean` | `false` | The content reaches under the status bar; otherwise it starts below it. |

## Opening and closing

The dialog's state is the app's. When the user closes the dialog (Escape, the Android back button, a press on the
backdrop, a sheet swiped down), it closes natively and tells the app, which sets its state to match: TSX's
`onOpenChange({ open: false, reason })`, Rust's `on_cancel`. In TSX, while `open` stays `true` the dialog stays closed, and it
opens again when `open` goes from `false` to `true`.

Each `closeOn*` flag is read natively when the user acts, since the main thread never waits for the app's code. To
confirm before closing, set the flags to `false`: the attempt then calls `onCancel`, and the app closes the dialog
itself (in TSX by setting `open` to `false`, in Rust by taking it out of the view):

```rust
dialog()
    .presentation(ModalPresentation::PageSheet)
    .close_on_escape(false)
    .close_on_backdrop_press(false)
    .close_on_swipe(false)
    .on_cancel(move || ask_to_discard.set(true))
    .flex_1()
    .bg(white())
    .child(form())
```

```tsx
<Dialog
  open={open()}
  presentation="pageSheet"
  closeOnEscape={false}
  closeOnBackdropPress={false}
  closeOnSwipe={false}
  onCancel={() => askToDiscard.set(true)}
  class="flex-1 bg-white"
>
  …
</Dialog>
```

`onCancel` is called on every attempt, whether the flags let the dialog close or not.

## A dialog with a backdrop

A dialog with the default `fullScreen` presentation shows what the app draws: here a dimmed backdrop and a card centered
over it. A press on the backdrop closes it:

```rust
when(confirm, move || {
    dialog()
        .animation(ModalAnimation::Fade)
        .on_cancel(move || confirm.set(false))
        .flex_1()
        .child(
            // The backdrop: a press on it closes the dialog.
            view()
                .absolute()
                .inset_0()
                .bg(rgba(0x00000066))
                .on_press(move || confirm.set(false)),
        )
        .child(
            view()
                .m(auto())
                .w_80()
                .gap_3()
                .rounded_2xl()
                .bg(white())
                .p_5()
                .child(text("Delete this item?").text_xl().font_weight(FontWeight::BOLD))
                .child(
                    button()
                        .on_press(remove)
                        .items_center()
                        .rounded_lg()
                        .bg(rgb(0xdc2626))
                        .px_4()
                        .py_3()
                        .active(|s| s.opacity(0.7))
                        .child(text("Delete").font_weight(FontWeight::SEMIBOLD).text_color(white())),
                ),
        )
})
```

```tsx
<Dialog
  open={confirm()}
  animation="fade"
  onOpenChange={({ open }) => confirm.set(open)}
  backdropClass="bg-black/40"
  class="m-auto w-80 gap-3 rounded-2xl bg-white p-5"
>
  <Text style={{ fontSize: 20, fontWeight: "700" }}>Delete this item?</Text>
  <Button onPress={remove} class="items-center rounded-lg bg-red-600 px-4 py-3 active:opacity-70">
    <Text class="font-semibold text-white">Delete</Text>
  </Button>
</Dialog>
```

For the system's alert or action sheet, use [`AlertDialog`](https://nsh.dev/versions/main/elements/alert-dialog.md) from `nsh/base`.

## Ref methods

None.

## Platform notes

- iOS and Mac Catalyst: `presentation` picks the form. `fullScreen` presents over the full screen with a clear
  background; `pageSheet` and `formSheet` are system sheets with the system background, which follow the finger when
  swiped down (`closeOnSwipe`).
- Android: the dialog fills the window and shows the app's popup and backdrop. The back button goes to the topmost
  dialog first, before stacks and `BackHandler` listeners.
- Desktops (macOS, Windows, Linux, GPUI) and the web: the dialog is a transparent layer over the whole window that
  shows the app's popup and backdrop. Escape is a close attempt.
- `supportedOrientations` is iOS's; `statusBarTranslucent` is Android's. An Android dialog's content starts below the
  status bar unless `statusBarTranslucent` is set.

Source: https://nsh.dev/versions/main/elements/dialog

---

# DiffView

`DiffView` shows the changes between two texts as code review tools do: side by side, the old text on the left and the
new on the right with their lines aligned, or unified, the deleted lines above the added ones. Within a changed line
the words that changed are highlighted, the unchanged lines between changes fold into separators that expand, and the
text is highlighted in the [`Editor`](https://nsh.dev/versions/main/elements/editor.md)'s syntax colors. It shows two texts (`oldValue` and `newValue`) or the
files of a unified diff (`patch`: `git diff`'s, a pull request's), each under its header, and it is made for reviewing changes, an AI's
proposed edits among them: the app's actions on each change keep it or revert it. Only the rows in view are made, so a
long file scrolls as a short one does.

`DiffView` owns behavior and comes with a look of its own built from the theme's tokens: the theme's `font-mono` at
13pt in 20pt rows, line numbers in `muted-foreground`, added lines tinted green and deleted lines red, the changed
words in a stronger tint, a bar at the gutter's edge of each changed line, and separators on `muted`. Each part takes
the app's styles over these defaults (`classes` and `styles`). Rust makes one with `nsh_base::diff_view()`, TSX with
`<DiffView>` from `nsh/base`.

```rust
use nsh_base::diff_view;
use nsh_core::prelude::*;

const OLD: &str = "fn total(prices: &[u32]) -> u32 {\n    prices.iter().sum()\n}\n";
const NEW: &str = "fn total(prices: &[u64]) -> u64 {\n    prices.iter().copied().sum()\n}\n";

fn review() -> impl IntoElement {
    diff_view().old_value(OLD).new_value(NEW).language("rust").flex_1()
}
```

```tsx
import { mount } from "nsh";
import { DiffView } from "nsh/base";

const OLD = `fn total(prices: &[u32]) -> u32 {
    prices.iter().sum()
}
`;
const NEW = `fn total(prices: &[u64]) -> u64 {
    prices.iter().copied().sum()
}
`;

function App() {
  return <DiffView oldValue={OLD} newValue={NEW} language="rust" class="flex-1" />;
}

mount(App);
```

The view fills the box the app gives it (`flex-1`, a height) and scrolls inside: vertically through the rows, and
sideways to the longest line, the two sides of a split view together. With `softWrap` long lines wrap at the side's
width instead, and a split row is as tall as its taller side, so the sides stay aligned.

## Two texts or a patch

- **Two texts**: `oldValue` and `newValue`. The lines are compared as they are, so a final line break added or
  removed is a change, as git shows it.
- **A patch**: `patch`, a unified diff of one file or several (`git diff`, `git format-patch`, `diff -u`; renames,
  modes, new, deleted and binary files, and a commit message before it, read as git writes them). The view shows its
  hunks' lines, numbered as in the file, each hunk under a separator of its header (the function it is in), and each
  file of several under a header of its own ([Files of a patch](#files-of-a-patch)). Each file's path names its
  language when `language` is not set.

```tsx
const PATCH = `diff --git a/src/total.rs b/src/total.rs
--- a/src/total.rs
+++ b/src/total.rs
@@ -10,3 +10,3 @@ impl Cart {
-    fn total(&self) -> u32 {
+    fn total(&self) -> u64 {
         self.prices.iter().sum()
     }
`;

<DiffView patch={PATCH} layout="unified" class="flex-1" />
```

`language` names the language as the `Editor`'s does: a name, an alias, an extension or a file name (`"rust"`,
`"tsx"`, `"main.go"`, `"Dockerfile"`).

## Files of a patch

A patch of several files shows each file under a header row: by default its path (`old → new` when renamed), its
added and deleted line counts, and `▾`, and a press on it collapses the file to its header (`▸`) or expands it.
`renderFileHeader` draws the headers the app's way (and shows one above a patch of a single file too), told the file
(`DiffFile`): `index`, `path`, `oldPath` (renamed or copied from), `status` (`"modified"`, `"added"`, `"deleted"`,
`"renamed"`, `"copied"`), `binary` (the patch shows no lines of it), `added`, `deleted`, `hunks`, `firstHunk` and
`collapsed`. The app's header calls the ref's `toggleFile(path)`; `collapseFile` and `expandFile` set the state, and
every change is reported with `onFileToggle({ file })`. A collapsed file stays collapsed while a new `patch` still has it.

Changes count across files, in order: a file's changes are `firstHunk` to `firstHunk + hunks - 1`, which
`goToHunk`, `renderHunkActions` and `hunks()` use (a `DiffHunk`'s `file` is its file's index and its lines count in
that file), and `stats()` adds up every file's. `goToHunk` expands a collapsed file first.

```tsx
let diff!: DiffViewRef;
const files = signal<DiffFile[]>([]);

<View class="flex-1 flex-row">
  <View class="w-48">
    <Each of={files()}>
      {(file) => (
        <Button onPress={() => diff.scrollToFile(file().path)} class="px-2 py-1">
          <Text class="text-sm">{file().path} +{file().added} −{file().deleted}</Text>
        </Button>
      )}
    </Each>
  </View>
  <DiffView
    ref={(r) => {
      diff = r;
      r.files().then((list) => files.set(list));
    }}
    patch={PULL_REQUEST}
    renderFileHeader={(file) => (
      <Button onPress={() => diff.toggleFile(file.path)} class="flex-1 flex-row items-center gap-2 bg-muted px-2">
        <Text>{file.collapsed ? "▸" : "▾"}</Text>
        <Text class="flex-1 text-sm font-medium">{file.oldPath ? `${file.oldPath} → ${file.path}` : file.path}</Text>
        <Text class="text-xs text-muted-foreground">{file.binary ? "Binary" : file.status}</Text>
      </Button>
    )}
    class="flex-1"
  />
</View>
```

## Layout and inline changes

`layout` is `"split"` (the default: side by side, each deleted line beside the added line most like it) or
`"unified"` (one column, a change's deleted lines above its added lines, with both line numbers). `inline` decides
what is highlighted within a changed line:

| `inline` | What is highlighted |
|---|---|
| `"wordAlt"` (default) | The words that changed, joined when one character apart, so a changed phrase reads as one |
| `"word"` | Each word that changed |
| `"char"` | Each character that changed |
| `"none"` | Nothing: the lines' tints alone |

Words are runs of letters, digits and `_`; each CJK character, kana and hangul syllable is a word of its own, so a
changed character in a sentence marks only itself. A line that changed almost entirely shows its tint alone.

`indicators` marks changed lines beside their numbers: `"bars"` (the default, a bar at the gutter's edge),
`"classic"` (`+` and `−` before the text) or `"none"`. `background={false}` leaves the changed lines untinted, and
`lineNumbers={false}` hides the numbers.

```tsx
<DiffView oldValue={before()} newValue={after()} language="md" layout="unified" inline="word" indicators="classic" class="flex-1" />
```

## Collapsed lines

Around each change `contextLines` unchanged lines show (3 by default); the unchanged lines between changes, and those
before the first and after the last, collapse into a separator that says how many lines it hides. Pressing it shows
them all. `expandAll` shows every line; the ref's `expand`, `expandAll()` and `collapseAll()` reveal and fold them
from the app.

`renderSeparator` draws the separators the app's way. It gets the separator (`DiffSeparator`): `gap`, the index of
the collapsed run (0 before the first change, `i` between changes `i - 1` and `i`), `lines`, how many lines it hides,
`first` and `last`, and for a patch the hunk's `header`. `expand(gap, direction, lines)` shows `"all"` its lines (the
default), or `lines` (default 20) `"up"`, just above the change below the separator, or `"down"`, just below the
change above it. The first separator expands up and the last one down.

```tsx
let diff!: DiffViewRef;

<DiffView
  ref={diff}
  oldValue={before()}
  newValue={after()}
  language="ts"
  renderSeparator={(sep) => (
    <View class="flex-1 flex-row items-center gap-1 bg-muted px-2">
      <If when={!sep.first}>
        <Button onPress={() => diff.expand(sep.gap, "down")} class="px-1"><Text>↓</Text></Button>
      </If>
      <If when={!sep.last}>
        <Button onPress={() => diff.expand(sep.gap, "up")} class="px-1"><Text>↑</Text></Button>
      </If>
      <Button onPress={() => diff.expand(sep.gap)} class="flex-1">
        <Text class="text-xs text-muted-foreground">{sep.header ?? `${sep.lines} unchanged lines`}</Text>
      </Button>
    </View>
  )}
  class="flex-1"
/>
```

## Keeping and reverting changes

`renderHunkActions` puts the app's actions at the top right of each change in view, told the change (`DiffHunk`:
`index`, `oldStart`, `oldLines`, `newStart`, `newLines`, lines from 0, and `file`, its file's index in a patch). They call the ref: `revertHunk(index)` puts
the change's old lines back into the new text, `acceptHunk(index)` makes its new lines the old text's. The view shows
the result at once and reports both texts with `onChange({ change })` (`{ oldValue, newValue }`), which the app sets as the props.
Keeping or reverting an AI's edit one change at a time is this:

```tsx
import { signal, Text, View } from "nsh";
import { Button, DiffView, type DiffViewRef } from "nsh/base";

function Proposal(props: { file: string; current: string; proposed: string; onApply: (text: string) => void }) {
  let diff!: DiffViewRef;
  const current = signal(props.current);
  const proposed = signal(props.proposed);
  return (
    <View class="flex-1">
      <DiffView
        ref={diff}
        oldValue={current()}
        newValue={proposed()}
        language={props.file}
        onChange={({ change: { oldValue, newValue } }) => {
          current.set(oldValue);
          proposed.set(newValue);
          props.onApply(oldValue);
        }}
        renderHunkActions={(hunk) => (
          <View class="flex-row gap-1">
            <Button onPress={() => diff.revertHunk(hunk.index)} class="rounded bg-background px-2 py-0.5 border border-border">
              <Text class="text-xs">Revert</Text>
            </Button>
            <Button onPress={() => diff.acceptHunk(hunk.index)} class="rounded bg-primary px-2 py-0.5">
              <Text class="text-xs text-primary-foreground">Keep</Text>
            </Button>
          </View>
        )}
        class="flex-1"
      />
    </View>
  );
}
```

Here the old text is the file as it is: keeping a change applies it to the file (`onApply`), reverting it takes it
out of the proposal. A view showing a `patch` shows excerpts of the files, and its changes stay as they are.

## Methods

`ref={diff}` gives the view's methods (`DiffViewRef`). Methods that return a value (`hunks()`, `stats()`) return a
`Promise` of it in JS, so `await` them: `const changes = await diff.hunks()`. For counts shown on screen,
`onStatsChange` reports them as they change. A method given a change, a separator or a file the diff does not have
changes nothing and logs a warning naming the method and the value.

| Method | Description |
|---|---|
| `hunks()` | `Promise<DiffHunk[]>`: the changes, in order. |
| `stats()` | `Promise<DiffStats>`: `{ added, deleted, hunks }`, the lines added and deleted and the number of changes. |
| `goToHunk(index)` | Scrolls change `index` into view, its first row at the top. |
| `revertHunk(index)` | Puts change `index`'s old lines back into the new text and reports the texts (`onChange`). |
| `acceptHunk(index)` | Makes change `index`'s new lines the old text's and reports the texts (`onChange`). |
| `expand(gap, direction?, lines?)` | Shows the lines separator `gap` hides: `"all"` (default), or `lines` (default 20) `"up"` or `"down"`. |
| `expandAll()` | Shows every unchanged line. |
| `collapseAll()` | Collapses the unchanged lines again. |
| `nextHunk()` | `Promise<number \| null>`: scrolls the next change to the top and gives its index (after the last, the first). |
| `previousHunk()` | `Promise<number \| null>`: scrolls the previous change to the top and gives its index (before the first, the last). |
| `currentHunk()` | `Promise<number \| null>`: the change gone to last while the view stays there, else the one at the top of the view or the first in view. |
| `selectedLines()` | `Promise<DiffLineRange \| null>`: the lines selected on the line numbers. |
| `setSelectedLines(range)` | Selects lines of a side (`null`: none), without `onLineSelectionChange`. |
| `selectedText()` | `Promise<string>`: the selected lines' text. |
| `files()` | `Promise<DiffFile[]>`: the patch's files, in order, with their counts (none for two texts). |
| `scrollToFile(path)` | Scrolls the header of the file at `path` to the top. |
| `collapseFile(path)` | Shows only the header of the file at `path`. |
| `expandFile(path)` | Shows the lines of the file at `path` again. |
| `toggleFile(path)` | Collapses the file at `path`, or expands it when collapsed. |
| `hunkBounds()` | `Promise<DiffHunkBounds[]>`: where each change is in the rows, in order ([An overview ruler](#an-overview-ruler)). |
| `scrollOffset()` | `Promise<Point>`: how far the rows are scrolled (`x` is 0). |
| `setScrollOffset(offset)` | Scrolls the rows to `offset.y` at once, as far as they go, as a thumb follows the pointer that drags it. |

`nextHunk()` and `previousHunk()` go on from the change they went to while the view stays there, and otherwise from
the top of the view, so a change near the end that cannot scroll to the top still counts. Next and previous change
buttons, with the counts from `onStatsChange`:

```tsx
let diff!: DiffViewRef;
const stats = signal<DiffStats>({ added: 0, deleted: 0, hunks: 0 });

<View class="flex-row items-center gap-2 p-2">
  <Text class="text-sm text-green-600">+{stats().added}</Text>
  <Text class="text-sm text-red-600">−{stats().deleted}</Text>
  <Text class="text-sm text-muted-foreground">{stats().hunks} changes</Text>
  <Button onPress={() => diff.previousHunk()}><Text>Previous</Text></Button>
  <Button onPress={() => diff.nextHunk()}><Text>Next</Text></Button>
</View>
<DiffView ref={diff} oldValue={before()} newValue={after()} onStatsChange={(e) => stats.set(e.stats)} class="flex-1" />
```

## An overview ruler

`onScroll({ offset, contentSize, size })` reports where the rows are, with the keys of a [`Scroll`](https://nsh.dev/versions/main/elements/scroll.md)'s:
`offset.y`, how far they are scrolled (the rows scroll vertically, as wide as the view, and the sides sideways on their
own: `offset.x` is 0), `contentSize`, the size of every row together, and `size`, the viewport's. It fires once the
view is laid out and again whenever one of them changes: as the rows scroll, when the view resizes, and when the rows
change height (other texts, `layout`, `softWrap`, a file or a separator expanded or collapsed, an annotation laid out).
`hunkBounds()` gives where each change is in the rows (`DiffHunkBounds`: `{ index, bounds }`, `bounds` from the top
of its first row to the bottom of its last, with the annotations under them, across the view), the changes that show:
a collapsed file's have no rows. `onHunkBoundsChange({ hunkBounds })` gives the same list once the view is laid out and
again whenever a change moves or changes size, even when the rows keep their height (one changed line becoming
another): a ruler draws its marks from it rather than reading them on `onScroll`. `scrollOffset()` reads how far the rows are scrolled,
and `setScrollOffset({ x, y })` scrolls the rows to `y` at once, so a dragged thumb follows the pointer in the same frame.

Together they make an overview ruler beside the view, as code editors have: a mark for each change, a thumb over the
rows in view, and a press or a drag that scrolls there. Here the ruler is as tall as the view:

```rust
use nsh_base::{DiffHunkBounds, DiffView, DiffViewApi, DiffViewEvent, diff_view, theme};
use nsh_core::prelude::*;

fn review(old: SharedString, new: SharedString) -> impl IntoElement {
    let diff = component_ref::<DiffView>();
    let ruler = element_ref();
    let ruler_top = stored(px(0.0));
    // How far the rows are scrolled, their height and the viewport's.
    let rows = signal((px(0.0), px(0.0), px(0.0)));
    let marks = signal(Vec::<DiffHunkBounds>::new());
    // Points of the rows per point of the ruler.
    let scale = move || {
        let (_, height, view) = rows.get();
        height.max(px(1.0)) / view.max(px(1.0))
    };
    // The thumb's middle at the pointer.
    let follow = move |page_y: Points| {
        let view = rows.get_untracked().2;
        let y = (page_y - ruler_top.get()) * scale() - view / 2.0;
        if let Some(api) = diff.api::<DiffViewApi>() {
            api.set_scroll_offset(point(px(0.0), y));
        }
    };
    view()
        .flex_1()
        .flex_row()
        .child(
            diff_view()
                .old_value(old)
                .new_value(new)
                .on_scroll(move |e: &DiffViewEvent| {
                    if let DiffViewEvent::Scroll(offset, content, size) = e {
                        rows.set((offset.y, content.height, size.height));
                    }
                })
                .on_hunk_bounds_change(move |list: &Vec<DiffHunkBounds>| marks.set(list.clone()))
                .component_ref(&diff)
                .flex_1(),
        )
        .child(
            view()
                .element_ref(&ruler)
                .w(px(12.0))
                .bg(move || theme().muted)
                .claim_touches(TouchClaim::on_start())
                .on_responder_grant(move |e: &ResponderEvent| {
                    let y = e.page.y;
                    spawn(async move {
                        ruler_top.replace(ruler.measure().await.map_or(px(0.0), |m| m.page.y));
                        follow(y);
                    });
                })
                .on_responder_move(move |e: &ResponderEvent| follow(e.page.y))
                .child(each(
                    marks,
                    |mark: &DiffHunkBounds| mark.index,
                    move |mark, _| {
                        view()
                            .absolute()
                            .left(px(0.0))
                            .right(px(0.0))
                            .bg(rgb(0xf59e0b))
                            .top(move || mark.get().bounds.origin.y / scale())
                            .h(move || (mark.get().bounds.size.height / scale()).max(px(2.0)))
                    },
                ))
                .child(
                    view()
                        .absolute()
                        .left(px(0.0))
                        .right(px(0.0))
                        .bg(move || theme().foreground.opacity(0.2))
                        .top(move || rows.get().0 / scale())
                        .h(move || rows.get().2 / scale()),
                ),
        )
}
```

```tsx
import { Each, signal, View, type ViewRef } from "nsh";
import { DiffView, type DiffHunkBounds, type DiffViewRef } from "nsh/base";

let diff!: DiffViewRef;
let ruler!: ViewRef;
let rulerTop = 0;
const rows = signal({ y: 0, height: 0, view: 0 });
const marks = signal<DiffHunkBounds[]>([]);
// Points of the rows per point of the ruler.
const scale = () => Math.max(rows().height, 1) / Math.max(rows().view, 1);
// The thumb's middle at the pointer.
const follow = (pageY: number) => diff.setScrollOffset({ x: 0, y: (pageY - rulerTop) * scale() - rows().view / 2 });

<View class="flex-1 flex-row">
  <DiffView
    ref={diff}
    oldValue={before()}
    newValue={after()}
    onScroll={({ offset, contentSize, size }) => rows.set({ y: offset.y, height: contentSize.height, view: size.height })}
    onHunkBoundsChange={({ hunkBounds }) => marks.set(hunkBounds)}
    class="flex-1"
  />
  <View
    ref={ruler}
    class="w-3 bg-muted"
    onStartShouldSetResponder={() => true}
    onResponderGrant={async (e) => {
      const y = e.pageY;
      rulerTop = (await ruler.measure())?.pagePosition.y ?? 0;
      follow(y);
    }}
    onResponderMove={(e) => follow(e.pageY)}
  >
    <Each of={marks()}>
      {(mark) => (
        <View
          class="absolute inset-x-0 bg-amber-500"
          style={{ top: mark().bounds.origin.y / scale(), height: Math.max(mark().bounds.size.height / scale(), 2) }}
        />
      )}
    </Each>
    <View class="absolute inset-x-0 bg-foreground/20" style={{ top: rows().y / scale(), height: rows().view / scale() }} />
  </View>
</View>
```

A mark's `index` is the change's in `hunks()`, whose `oldLines` and `newLines` tell an added change (no old lines)
from a deleted one (no new lines), to color its mark.

## Selecting the code

The code is selectable text: dragging over it selects across lines, a double click selects a word and a triple click a
line, Shift extends the selection, and the platform's copy (Cmd+C or Ctrl+C; Ctrl+Shift+C in a terminal) copies it.
Each side of a split view selects on its own, so a selection stays on the side it starts on; a unified view's column
is one text. The line numbers, the `+` / `−` marks and bars, the separators, the file headers and the app's controls
and annotations stay out of the selection, so a copy holds only code. With `softWrap`, a wrapped line copies whole,
without a line break where it wraps, and a triple click selects all of its rows. Selecting lines on the line numbers
works as below, beside it.

## Review comments

The line numbers select lines of a side: a press selects one, a Shift-press extends the selection to it, and dragging
the mouse over the numbers selects those it goes over. `onLineSelectionChange` reports the lines as `range` (`DiffLineRange`:
`{ side, start, end }`, lines from 0, `null` for none), and a press of a number also reports
`onLineNumberPress({ line })` (`{ side, line }`). The ref reads the selection (`selectedLines()`, `selectedText()`) and sets it.

`annotations` puts the app's content under lines: each `{ id, side, line }` is drawn by `renderAnnotation` across its
line's side (the whole view when unified), as tall as it lays out, and shows while its line does. `renderAddAnnotation`
is the app's control to add one, at the right of the gutter of the line the pointer is over and of the last selected
line; it gets the selected lines when its line is one of them, else that line.

```tsx
type Comment = { id: string; side: "old" | "new"; line: number; text: string };
const comments = signal<Comment[]>([]);
const drafting = signal<DiffLineRange | null>(null);

<DiffView
  oldValue={before()}
  newValue={after()}
  annotations={comments().map(({ id, side, line }) => ({ id, side, line }))}
  renderAnnotation={(a) => (
    <View class="m-2 rounded-md border border-border bg-card p-2">
      <Text class="text-sm">{comments().find((c) => c.id === a.id)?.text}</Text>
    </View>
  )}
  renderAddAnnotation={(range) => (
    <Button onPress={() => drafting.set(range)} class="size-4 items-center justify-center rounded bg-primary">
      <Text class="text-xs text-primary-foreground">+</Text>
    </Button>
  )}
  class="flex-1"
/>
```

## Styling the parts

`class` and `style` style the view's box. `classes` takes Tailwind classes by part and `styles` inline styles by part;
a part's classes come after its own default styles, so they win, and its `styles` win over its classes. The font is
set with `fontFamily`, `fontSize` and `lineHeight`.

```tsx
<DiffView
  oldValue={before()}
  newValue={after()}
  language="py"
  fontSize={12}
  lineHeight={18}
  class="flex-1 rounded-lg border border-border"
  classes={{
    gutter: "bg-muted",
    lineAdded: "bg-blue-500/10",
    wordAdded: "bg-blue-500/30",
    indicatorAdded: "bg-blue-500",
    separator: "bg-transparent",
  }}
/>
```

| Part | What it is | Default |
|---|---|---|
| `side` | Each side (split) or the one column (unified) | A `border` line between the sides |
| `gutter` | A side's line numbers and indicators | |
| `lineNumber` | Every line number | Right-aligned, `muted-foreground` |
| `lineNumberAdded` | The numbers of added lines, after `lineNumber` | |
| `lineNumberDeleted` | The numbers of deleted lines, after `lineNumber` | |
| `content` | A side's text, beside its gutter | 8pt before and after the text |
| `line` | Every row of a side | |
| `lineAdded` | Added lines' rows, after `line` | A green tint |
| `lineDeleted` | Deleted lines' rows, after `line` | A red tint |
| `filler` | The empty half of a split row beside a line the other side lacks | A faint `muted` fill |
| `wordAdded` | The words changed within an added line | A stronger green |
| `wordDeleted` | The words changed within a deleted line | A stronger red |
| `indicatorAdded` | An added line's bar (`"bars"`) or `+` (`"classic"`) | Green, 3pt wide |
| `indicatorDeleted` | A deleted line's bar or `−` | Red, 3pt wide |
| `separator` | A separator of collapsed lines, or a patch's hunk header | `⋯` and the count on `muted` |
| `hunkActions` | The box of the app's actions on a change | At the change's top right |
| `lineSelected` | Over the selected lines' rows of their side | The theme's selection color (as the `Editor`'s selections) |
| `annotation` | The box of an annotation, under its line | Across its line's side |
| `addAnnotation` | The box of the add control, the gutter's width and a line tall | The control at its right |
| `fileHeader` | The header of a file of a patch | The path and counts on `secondary`, a `border` line below |

## Props

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `oldValue` | `.old_value(..)` | `string` | | The old text. |
| `newValue` | `.new_value(..)` | `string` | | The new text. |
| `patch` | `.patch(..)` | `string` | | A unified diff of one file or several, shown when `oldValue` and `newValue` are not set. |
| `language` | `.language(..)` | `string` | plain text (a patch: each file's) | A language's name, alias, extension or file name. |
| `layout` | `.layout(..)` | `"split" \| "unified"` | `"split"` | Side by side or one column. |
| `inline` | `.inline(..)` | `"wordAlt" \| "word" \| "char" \| "none"` | `"wordAlt"` | What is highlighted within changed lines. |
| `indicators` | `.indicators(..)` | `"bars" \| "classic" \| "none"` | `"bars"` | How changed lines are marked beside their numbers. |
| `contextLines` | `.context_lines(..)` | `number` | `3` | Unchanged lines shown around each change. |
| `expandAll` | `.expand_all(..)` | `boolean` | `false` | Every unchanged line shows. |
| `lineNumbers` | `.line_numbers(..)` | `boolean` | `true` | The line numbers. |
| `background` | `.background(..)` | `boolean` | `true` | Changed lines are tinted. |
| `fontFamily` | `.font_family(..)` | `string` | the theme's `font-mono` | The font of the text. |
| `fontSize` | `.font_size(..)` | `number` | `13` | The font size, in points. |
| `lineHeight` | `.line_height(..)` | `number` | `20` | The height of a row, in points; in a terminal a row is one Cell. |
| `renderSeparator` | `.render_separator(..)` | `(separator: DiffSeparator) => JSX.Element` | | Draws the separators of collapsed lines. |
| `renderHunkActions` | `.render_hunk_actions(..)` | `(hunk: DiffHunk) => JSX.Element` | | The app's actions on each change. |
| `softWrap` | `.soft_wrap(..)` | `boolean` | `false` | Long lines wrap at the side's width. |
| `annotations` | `.annotations(..)` | `DiffAnnotation[]` | `[]` | The app's content under lines: `{ id, side, line }`. |
| `renderAnnotation` | `.render_annotation(..)` | `(annotation: DiffAnnotation) => JSX.Element` | | Draws an annotation under its line. |
| `renderAddAnnotation` | `.render_add_annotation(..)` | `(range: DiffLineRange) => JSX.Element` | | The app's control to add an annotation, beside the hovered line and the last selected one. |
| `renderFileHeader` | `.render_file_header(..)` | `(file: DiffFile) => JSX.Element` | | Draws the header of each file of a patch, one row tall. |
| `classes` | `.classes(..)` | `DiffViewClasses` | `{}` | Tailwind classes by part. |
| `styles` | `.styles(..)` | `DiffViewStyles` | `{}` | Inline styles by part, over the classes. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | | The view's box. |

## Events

| Event | Rust | Description |
|---|---|---|
| `onChange` | `.on_change(\|change: &DiffChange\| ..)` | A change was kept or reverted: `{ change }`, the texts now (`{ oldValue, newValue }`). |
| `onLineNumberPress` | `.on_line_number_press(\|line: &DiffLine\| ..)` | A line number was pressed: `{ line }`, a `{ side, line }`. |
| `onLineSelectionChange` | `.on_line_selection_change(\|range: &Option<DiffLineRange>\| ..)` | The selected lines changed: `{ range }`, a `{ side, start, end }` or `null`. |
| `onStatsChange` | `.on_stats_change(\|stats: &DiffStats\| ..)` | The counts changed: `{ stats }`, a `{ added, deleted, hunks }`. It fires once when the view is made and again each time the texts are diffed to other counts, for a "+8 −8 · 5 changes" line. |
| `onFileToggle` | `.on_file_toggle(\|file: &DiffFile\| ..)` | A file of the patch was collapsed or expanded (its header, or the ref): `{ file }`, the `DiffFile` now. |
| `onScroll` | `.on_scroll(\|e: &DiffViewEvent\| ..)` | The rows scrolled, or they or the viewport changed size: `{ offset, contentSize, size }`, as a `Scroll`'s (`DiffViewEvent::Scroll(offset, content_size, size)` in Rust). It fires once the view is laid out and again when one of them changes. |
| `onHunkBoundsChange` | `.on_hunk_bounds_change(\|bounds: &Vec<DiffHunkBounds>\| ..)` | Where the changes are in the rows changed: `{ hunkBounds }`, the list `hunkBounds()` gives. It fires once the view is laid out and again when a change moves or changes size, the rows' height kept or not, for an overview ruler's marks. |

## Related

- [Editor](https://nsh.dev/versions/main/elements/editor.md): the code editor whose syntax colors and languages `DiffView` uses.
- [TextView](https://nsh.dev/versions/main/elements/text-view.md): documents of Markdown and HTML, for the text around a review.
- [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md): the other base components.

Source: https://nsh.dev/versions/main/elements/diff-view

---

# Dock

A dock area is a workspace the user arranges: panels in tab groups, groups split side by side or stacked, and docks on
the left, right and bottom edges that open, close and resize. A tab dragged onto another group joins it, dragged to a
group's edge splits it, and every panel keeps what it holds as it moves. `DockArea` owns the behavior: tab drags and
drops, which run natively frame by frame, resizing splits and docks, opening and closing docks, zoom and the lock. The
look is the app's: the tabs, the tab bars, the handles, the drop indicator and each panel's content are what the app
renders and styles, and the area draws nothing of its own.

```rust
use nsh_base::{
    dock::{DockAreaLayout, DockLayout, DockPanel, DockPlacement, DockRegion, DockTab},
    dock_area, theme,
};
use nsh_core::prelude::*;

fn workspace() -> impl IntoElement {
    let layout = signal(
        DockAreaLayout::new(
            DockLayout::h_split()
                .child(DockLayout::tabs().panel("readme").panel("main"), None)
                .child(DockLayout::tabs().panel("preview"), Some(px(320.0))),
        )
        .with_dock(DockPlacement::Left, DockRegion::new(DockLayout::tabs().panel("files")))
        .with_dock(DockPlacement::Bottom, DockRegion::new(DockLayout::tabs().panel("terminal"))),
    );
    dock_area()
        .layout(move || layout.get())
        .on_layout_change(move |next: &DockAreaLayout| layout.set(next.clone()))
        .handle_style(|s| s.bg(move || theme().border()))
        .tab_bar_style(|s| s.flex_row().border_b_1().border_color(move || theme().border()))
        .tab_style(|s| s.px_3().py_1().selected(|s| s.bg(move || theme().muted())))
        .render_tab(|tab: &DockTab| text(tab.panel.to_string()).text_sm().text_color(move || theme().foreground()))
        .render_panel(|panel: &DockPanel| {
            text(format!("{} content", panel.id)).p_4().text_color(move || theme().foreground())
        })
}
```

```tsx
import { mount, signal, Text } from "nsh";
import { DockArea, type DockAreaLayout } from "nsh/base";

const titles: Record<string, string> = {
  files: "Files", readme: "README.md", main: "main.rs", preview: "Preview", terminal: "Terminal",
};

function App() {
  const layout = signal<DockAreaLayout>({
    center: {
      type: "split",
      axis: "horizontal",
      children: [
        { type: "tabs", panels: ["readme", "main"] },
        { type: "tabs", panels: ["preview"] },
      ],
      sizes: [null, 320],
    },
    left: { layout: { type: "tabs", panels: ["files"] }, size: 240 },
    bottom: { layout: { type: "tabs", panels: ["terminal"] }, size: 180 },
  });
  return (
    <DockArea
      class="size-full bg-background"
      layout={layout()}
      onLayoutChange={(e) => layout.set(e.layout)}
      handleClass="bg-border group-active:bg-primary"
      tabBarClass="flex-row border-b border-border"
      tabClass="px-3 py-1.5 selected:bg-muted"
      renderTab={(tab) => <Text class="text-sm text-foreground">{titles[tab.panel]}</Text>}
      renderPanel={(panel) => <Text class="p-4 text-foreground">{titles[panel.id]} content</Text>}
    />
  );
}

mount(App);
```

`DockArea` and the values it takes come from [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md), the `nsh-base` crate in Rust
(`nsh_base::dock_area()`, the values in `nsh_base::dock`). In Rust, `dock_area()` makes it, with a setter per
prop, a listener per event and the typed style methods; `DockLayout` describes a layout by the panels' keys
(`h_split()`, `v_split()`, `tabs()`, `.child(layout, size)`, `.panel(key)`).

## The layout

The layout is a value, `DockAreaLayout`: the center, and a dock on each of the left, right and bottom edges, each
optional. Each region is a tree of two kinds of node:

| Node | Holds | Fields |
|---|---|---|
| `{ type: "split" }` | Other nodes, side by side (`axis: "horizontal"`) or stacked (`"vertical"`) | `children`, and `sizes`: each child's length along the axis in points, `null` to share the rest |
| `{ type: "tabs" }` | Panels, by key, one shown at a time | `panels` (the keys, in tab order), `activeIndex` (the one shown, default 0) |

A panel always lives in a tab group: a region with one panel is a tab group of one. A panel's key is the app's string
for it (`"files"`, a document's id), and a key appears once in the whole layout. A dock (`DockRegion`) is its tree
(`layout`), its size across its edge (`size`, default 200, at least 100), whether it is open (`open`, default `true`)
and whether dragging its edge below its smallest size closes it (`collapsible`, default `true`).

Every node has an `id`. A layout the app writes may leave ids out: the area assigns them, and every layout it reports
carries them. Passing a reported layout back keeps each group's identity, which the ref's methods name groups by. The
area also tidies what it is given: an empty group or split goes, a split of one child becomes that child, a split
inside a split of the same axis joins its parent, `activeIndex` stays in range, a key listed twice keeps its first
place. The layouts it reports are always in that one canonical shape.

The layout is the app's (`layout`): every change the user makes (a tab selected, dragged or closed, a split or dock
resized, a dock opened or closed) is reported as the whole new layout (`onLayoutChange`), and the area shows the
layout the app passes back. The app changes the layout itself by passing a new value: a saved layout restored, a
command that rearranges the workspace. An area without `layout` keeps its own, starting from `defaultLayout`, and
still reports every change.

## Panels' content

What a panel shows is the app's: `renderPanel` renders it from the panel's key (`panel.id`). Every panel of a group is
placed and only the displayed one shown, so switching tabs keeps each panel's content; and when a panel moves (to
another group, into a dock, into a zoom and back), the same content moves with it: the signals it created, an input's
text, a scroll position, a web view's page all stay. The area renders a panel once, when it first appears, and lets its
content go when the panel leaves the layout (`onPanelRemove`).

```tsx
<DockArea
  layout={layout()}
  onLayoutChange={(e) => layout.set(e.layout)}
  renderPanel={(panel) => (panel.id === "terminal" ? <Terminal /> : <Editor file={panel.id} />)}
  onPanelActiveChange={({ panel, active }) => active && setTitle(panel)}
  onPanelRemove={({ panel }) => closeFile(panel)}
/>
```

`panels` sets what each panel allows, by key; a panel not listed allows everything:

| Field | Default | Description |
|---|---|---|
| `id` | | The panel's key. |
| `closable` | `true` | It may be closed. |
| `zoomable` | `true` | Its group may zoom while it is displayed. |
| `visible` | `true` | It shows. A hidden panel keeps its place and comes back there; a group or split whose panels are all hidden takes no room. |

## Tabs

Each group has a tab bar with a tab per visible panel, in the order of its `panels`. `renderTab` renders what a tab
shows (its title, an icon, a close button of the app's); without it a tab shows the panel's key. The area makes it the
tab: a press selects it, a drag moves its panel, screen readers hear it as a tab with its selected state, and
`tabClass`'s `selected:` classes style the displayed one. A tab's value says what the app needs to draw it:

| Field | Type | Description |
|---|---|---|
| `panel` | `string` | The panel's key. |
| `group` | `number` | The id of the tab group it is in. |
| `index` | `number` | Its place among the group's visible tabs. |
| `active` | `boolean` | It is the group's displayed tab. |
| `closable` | `boolean` | The area would close it: it is closable, the area is not locked, and its group may give it away. |
| `zoomed` | `boolean` | Its group is zoomed. |

```tsx
let area!: DockAreaRef;

<DockArea
  ref={area}
  layout={layout()}
  onLayoutChange={(e) => layout.set(e.layout)}
  renderTab={(tab) => (
    <View class="flex-row items-center gap-2">
      <Text class="text-sm">{titles[tab.panel]}</Text>
      <If when={tab.closable}>
        <Button onPress={() => area.closePanel(tab.panel)} accessibilityLabel="Close" class="rounded-sm px-1 hover:bg-muted">
          <Text class="text-xs">×</Text>
        </Button>
      </If>
    </View>
  )}
  renderPanel={(panel) => <Editor file={panel.id} />}
/>
```

## Drag and drop

A tab dragged over a group shows where it would land, and the drop puts it there:

| Dropped on | The panel |
|---|---|
| A tab bar | Joins that group, between the tabs it is dropped by |
| The middle of a group's content | Joins that group |
| An edge of a group's content (its outer 35% on each side) | Splits that group: a new group of its own on that side |

While a drag hovers, the area shows the drop indicator over the part of the group the panel would take (all of its
content to join, half of it to split): a part the
app styles (`dropIndicatorClass`), with content of its own if the app renders some (`renderDropIndicator`, told the
`group`, the `side` it splits off or the tab bar `index`). It moves to each new place natively, easing there and fading in on another group as the last one fades out (at once when the user asks for less motion). What follows the pointer or finger is the app's too
(`renderDragPreview`). A drop is one change of the layout, reported once; a drop that would change nothing changes nothing.

A locked area, a zoomed one, and a group's last panel when nothing sits beside the group drag nothing.

## Docks

A dock opens and closes without losing its panels or its size: closing it keeps its tree, and opening it shows the
same groups at the same size. The edge between a dock and the center is a handle the user drags to resize the dock;
it stays at least 100 points and the center keeps at least 100 points, and a collapsible dock let go below 50 points
closes and keeps its size for when it opens. The area always fits its bounds: a dock shows at its `size` within what
the area leaves it, and when even that does not fit, the docks shrink with the rest and the splits' minimum sizes
yield. `renderDock` draws a dock's own chrome before its layout (a title strip, a collapse button), told its
`placement`, `open`, `size` and `collapsible`; `dockClass` styles its frame.

Open, close and resize docks from the app through the ref (`toggleDock`, `setDockOpen`, `setDockSize`), which work
in both presentations, or by writing the dock's `open` and `size` in the layout it passes (`open` is the full
presentation's). `onDockOpenChange` reports
each time a dock shows or hides, measured against the layout's `open` (an area that is compact from the start reports
each layout-open dock hidden), so a toggle that starts from the layout's `open` and follows `onDockOpenChange` always
shows the dock's state:

```tsx
const terminalOpen = signal(true);

<DockArea
  ref={area}
  layout={layout()}
  onLayoutChange={(e) => layout.set(e.layout)}
  onDockOpenChange={({ placement, open }) => placement === "bottom" && terminalOpen.set(open)}
  renderPanel={(panel) => <Editor file={panel.id} />}
/>

<Button selected={terminalOpen()} onPress={() => area.toggleDock("bottom")} class="px-3 py-1.5 selected:bg-muted">
  <Text>Terminal</Text>
</Button>
```

## Zoom

A zoomed group fills the whole area until it is zoomed out or leaves the layout (`area.toggleZoom(group)`, and `area.toggleZoom()` to zoom
out), and `onZoomChange` reports the panel it displays, or `null`. The zoom belongs to the group, so it stays zoomed
when its displayed panel closes and the next one takes over. A panel with `zoomable: false` keeps its group from
zooming while it is displayed.

## Locking

`locked` keeps the arrangement as it is: no tab drags, no drops, no closes. Selecting tabs, resizing and opening and
closing docks still work, so a locked workspace is still a workspace to use.

## Methods

`ref={area}` gives the area's methods (`DockAreaRef`), for commands, shortcuts and menus of the app's. Each edit is
reported with `onLayoutChange` as the user's are. A method given a panel, a group, a tab index or a dock the layout
does not have leaves the layout as it is and logs a warning naming the method and the value.

| Method | Description |
|---|---|
| `layout()` | `Promise<DockAreaLayout>`: the layout shown. |
| `addPanel(panel, placement?, size?)` | Adds a panel to a region (`"center"`, the default, `"left"`, `"right"`, `"bottom"`), into its first tab group, displayed; a missing dock is made, `size` across. A panel the area holds moves there. |
| `removePanel(panel)` | Removes a panel, whatever its options say. |
| `closePanel(panel)` | Closes a panel as its tab would: unless the area is locked, the panel is not closable, or it is the last panel of a group with nothing beside it. |
| `movePanel(panel, target)` | Moves a panel to `target`: `{ group, side?, index?, activate?, size? }`, into tab group `group` (at `index`) or a new group on its `side` (`size` points along the new split). |
| `splitAt(group, panel, side)` | Puts a panel in a new tab group on a side (`"left"`, `"right"`, `"top"`, `"bottom"`) of a container. |
| `selectPanel(panel)` | Displays a panel in its group. |
| `selectTab(group, index)` | Displays a tab of a group. |
| `toggleDock(placement)`, `setDockOpen(placement, open)` | Opens or closes a dock. |
| `setDockSize(placement, size)` | Sets a dock's size across its edge (at least 100). |
| `toggleZoom(group?)` | Zooms a group in, or out when it is zoomed; without `group`, the zoomed group out. |
| `zoomedGroup()` | `Promise<number \| null>`: the zoomed group's id. |
| `groupOf(panel)` | `Promise<number \| null>`: the id of the tab group holding a panel. |

In Rust, `component_ref::<DockArea>()` and `.component_ref(&r)` on the area give a ref whose `r.api::<DockAreaApi>()` has
the same methods in snake case.

## Saving and restoring

A reported layout is plain data, so saving it is `JSON.stringify(layout)` into [storage](https://nsh.dev/versions/main/modules/nsh.md#storage),
and restoring it is passing the parsed value as `layout`. `onLayoutChange` reports every change, a resize and a tab
selection included, so write to storage once the changes settle (a short timer reset on each report).

In Rust, `DockAreaLayout::to_state` and `from_state` read and write `DockAreaState`, the layout file format
`gpui-base`'s dock uses too.

## Phones and narrow windows

The dock adapts to its own width. An area 600 points wide and wider (in a window on a desktop, the web, a tablet, an
iPad full screen, a foldable open) is the whole workspace: splits, groups and docks side by side, as a tablet's
multi-pane apps are. With a finger on a phone or tablet, a tab drag starts on a long press, as iPadOS drag and drop does, so a tab bar
still scrolls under a swipe, and handles take a wider touch area with the same look.

An area narrower than 600 points (on a phone, an iPad in Slide Over, in a narrow desktop or browser window, or in a
narrow column of a wide one) presents the same layout for one screen, as iPad's split views collapse their columns and Material Design's supporting
pane becomes a bottom sheet:

- The center shows one group at a time, full size. Its tab bar lists every visible panel of the center, and selecting
  a panel of another group makes that group the one shown.
- The left and right docks are drawers over the center from their edge, as wide as the dock, and the bottom dock is a
  sheet as tall as the dock. One shows at a time, when the app presents it (`toggleDock`, `setDockOpen`, which
  dismiss the other); it slides in and out, and a press on its backdrop, Escape or back dismiss it. Entering the
  compact presentation shows none.
- A tab dragged (a finger after a long press, a pointer at once) moves within the tab bar to reorder it.

Every panel stays placed in both presentations, so switching keeps its content. The drawer or sheet shown is the
compact presentation's own: the layout's `open` belongs to the full presentation, and presenting or dismissing a
drawer reports no `onLayoutChange`, so an area that widens again shows the docks exactly as they were.
`onDockOpenChange` reports both: a dock whose layout `open` changes in the full presentation, a drawer or sheet shown
or dismissed in the compact one, and each dock whose shown state changes when the presentation switches. In
`renderDock`, `open` is whether the dock shows in the current presentation. The layout stays the same value too,
so an area that crosses 600 points (a foldable opening, an iPad joining Split View, a window or a column resized)
keeps every panel where it was, and the app saves one layout. The area's width decides once it is laid out (the
window's width stands in before that), and `compact` chooses the presentation instead of the width. The
drawers, the sheet and the backdrop are parts the app styles (`drawerClass`, `sheetClass`, `backdropClass`), as the
rest of the area.

```tsx
<DockArea
  layout={layout()}
  onLayoutChange={(e) => layout.set(e.layout)}
  drawerClass="bg-background border-r border-border"
  sheetClass="rounded-t-(--radius-lg) bg-background"
  backdropClass="bg-black/40"
  renderTab={(tab) => <Text>{titles[tab.panel]}</Text>}
  renderPanel={(panel) => <Editor file={panel.id} />}
/>
```

## Props

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `layout` | `.layout(..)` | `DockAreaLayout` | none | The layout shown (controlled): pass back what `onLayoutChange` reports. |
| `defaultLayout` | `.default_layout(..)` | `DockAreaLayout` | an empty center | The layout at first, when `layout` is not set; the area keeps its own from then on. |
| `locked` | `.locked(..)` | `boolean` | `false` | No tab drags, drops or closes. |
| `compact` | `.compact(..)` | `boolean` | by width | The phone presentation (`true`) or the full one (`false`); without it, compact while the area is narrower than 600 points. |
| `panels` | `.panels(..)` | `DockPanelOptions[]` | `[]` | What each panel allows, by key: `closable`, `zoomable`, `visible`. |
| `renderPanel` | `.render_panel(\|panel\| ..)` | `(panel: DockPanel) => JSX.Element` | none | A panel's content, by its key (`panel.id`). |
| `renderTab` | `.render_tab(\|tab\| ..)` | `(tab: DockTab) => JSX.Element` | the key | What a tab shows. |
| `renderDropIndicator` | `.render_drop_indicator(\|drop\| ..)` | `(drop: DockDropIndicator) => JSX.Element` | none | What is inside the drop indicator: `group`, `side`, `index`. |
| `renderDock` | `.render_dock(\|dock\| ..)` | `(dock: DockInfo) => JSX.Element` | none | A dock's own chrome, before its layout: `placement`, `open` (shown in the current presentation), `size`, `collapsible`. |
| `renderEmpty` | `.render_empty(\|placement\| ..)` | `(placement: DockPlacement) => JSX.Element` | none | What an empty center shows. |
| `renderDragPreview` | `.render_drag_preview(\|tab\| ..)` | `(tab: DockTab) => JSX.Element` | none | What follows the pointer or finger while a tab is dragged. |
| `groupClass`, `groupStyle` | `.group_style(\|s\| ..)` | `string`, `StyleProp<ViewStyle>` | none | Each tab group's frame. |
| `tabBarClass`, `tabBarStyle` | `.tab_bar_style(\|s\| ..)` | `string`, `StyleProp<ViewStyle>` | none | Each tab bar (`flex-row` for a row). |
| `tabClass`, `tabStyle` | `.tab_style(\|s\| ..)` | `string`, `StyleProp<ViewStyle>` | none | Each tab; `selected:` for the displayed one. |
| `contentClass`, `contentStyle` | `.content_style(\|s\| ..)` | `string`, `StyleProp<ViewStyle>` | none | Each group's content frame, where its panels show. |
| `dropIndicatorClass`, `dropIndicatorStyle` | `.drop_indicator_style(\|s\| ..)` | `string`, `StyleProp<ViewStyle>` | none | The drop indicator. |
| `handleClass`, `handleStyle` | `.handle_style(\|s\| ..)` | `string`, `StyleProp<ViewStyle>` | none | The indicator of each handle, between a split's groups and at each dock's edge; `group-hover:` and `group-active:` follow the handle. It is 1 point across the handle and runs its full length unless it says otherwise, so `bg-border` is a hairline either way; `w-[3px]` / `h-[3px]` thicken it. |
| `handleThumbClass`, `handleThumbStyle` | `.handle_thumb_class(..)`, `.handle_thumb_style(\|s\| ..)` | `string`, `StyleProp<ViewStyle>` | none | Each handle's thumb: a grip centered on the line, drawn upright as on a vertical line and turned a quarter on a horizontal one, so one class serves both axes. It stays the same view while the handle is hovered, pressed and dragged, so `group-hover:` and `group-active:` classes transition it (`h-11 w-[3px] rounded-full bg-muted-foreground opacity-0 scale-y-0 transition group-hover:opacity-40 group-hover:scale-y-[0.45] group-active:opacity-90 group-active:scale-y-100`). |
| `dockClass`, `dockStyle` | `.dock_style(\|s\| ..)` | `string`, `StyleProp<ViewStyle>` | none | Each dock's frame. |
| `drawerClass`, `drawerStyle` | `.drawer_style(\|s\| ..)` | `string`, `StyleProp<ViewStyle>` | none | Compact: the side docks' drawers. |
| `sheetClass`, `sheetStyle` | `.sheet_style(\|s\| ..)` | `string`, `StyleProp<ViewStyle>` | none | Compact: the bottom dock's sheet. |
| `backdropClass`, `backdropStyle` | `.backdrop_style(\|s\| ..)` | `string`, `StyleProp<ViewStyle>` | none | Compact: the backdrop behind an open drawer or sheet, whose press closes it. |
| `handleAccessibilityLabel` | `.handle_accessibility_label(..)` | `string` | none | What screen readers say for every handle, between a split's groups and at each dock's edge. |
| `ref` | `.component_ref(&r)` (`component_ref::<DockArea>()`) | `DockAreaRef` | | The area's [methods](#methods). |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The area itself: its size in its parent (`flex-1`), its background. It stays within its bounds and takes no minimum size from its content. |

## Events

| Event | Rust | Description |
|---|---|---|
| `onLayoutChange` | `.on_layout_change(\|layout: &DockAreaLayout\| ..)` | The layout changed (a drag, a selection, a resize, a dock opened or closed, a method): `{ layout }`, the whole new layout, every id in it. |
| `onPanelActiveChange` | `.on_panel_active_change(\|e: &DockAreaEvent\| ..)` (`PanelActiveChange(panel, active)`) | `{ panel, active }`: a panel became, or stopped being, its group's displayed tab (a closed dock displays none). Once per change; a panel that leaves is not told `false`: `onPanelRemove` is its end. |
| `onPanelRemove` | `.on_panel_remove(\|panel: &PanelId\| ..)` | `{ panel }`: a panel left the area for good: closed, removed, or missing from a new layout. A panel that moves never hears it. |
| `onZoomChange` | `.on_zoom_change(\|panel: &Option<PanelId>\| ..)` | A group zoomed in or out: `{ panel }`, the panel it displays, or `null`. |
| `onDockOpenChange` | `.on_dock_open_change(\|e: &DockAreaEvent\| ..)` (`DockOpenChange(placement, open)`) | `{ placement, open }`: a dock showed or hid: its layout `open` changed in the full presentation, its drawer or sheet was shown or dismissed in the compact one, or the presentation switched. |

## Parts

| Part | Inside | Styled with | States |
|---|---|---|---|
| The area | | `class`, `style` | |
| A tab group | a region | `groupClass`, `groupStyle` | |
| A tab bar | a group | `tabBarClass`, `tabBarStyle` | |
| A tab | a tab bar | `tabClass`, `tabStyle`; `renderTab` | `selected:`, `active:`, `hover:` |
| A group's content | a group | `contentClass`, `contentStyle`; `renderPanel` | |
| A handle's indicator | between a split's groups, at a dock's edge | `handleClass`, `handleStyle` | `group-hover:`, `group-active:` |
| A handle's thumb | centered on a handle's line | `handleThumbClass`, `handleThumbStyle` | `group-hover:`, `group-active:` (pressed until the drag ends) |
| A dock | an edge | `dockClass`, `dockStyle`; `renderDock` | |
| The drop indicator | over a group during a drag | `dropIndicatorClass`, `dropIndicatorStyle`; `renderDropIndicator` | |
| The drag preview | under the pointer or finger | `renderDragPreview` | |
| The empty center | the center | `renderEmpty` | |
| A drawer, the sheet, the backdrop | over the center, compact | `drawerClass`, `sheetClass`, `backdropClass` (and their styles) | |

## Accessibility

- Each tab is a tab with its selected state for screen readers, as [`Tab`](https://nsh.dev/versions/main/elements/tabs.md) is, and activating it selects
  it. Its label is the text `renderTab` draws.
- Every handle, between a split's groups and at each dock's edge, is an adjustable element labeled
  `handleAccessibilityLabel`. The handles between a split's groups are [Resizable](https://nsh.dev/versions/main/elements/resizable.md)'s: a screen reader
  moves them 10 points at a time, reported with `onLayoutChange`.
- In the compact presentation, Escape and back dismiss the drawer or sheet shown.

See [Accessibility](https://nsh.dev/versions/main/docs/accessibility.md) for labels, roles and announcements in general.

## Platform notes

- A pointer (a mouse, a trackpad, a pen hovering over the screen) drags a tab once it moves 4 points with the button
  down, on every platform: an iPad with a trackpad and a narrow browser window driven by a mouse drag as a desktop
  does. On macOS, Windows, Linux and GPUI every press counts as a pointer's, a finger on a touchscreen laptop's
  included.
- A finger on iOS, iPadOS and Android drags a tab after a long press, as iPadOS drag and drop does, so a swipe over
  the tab bar scrolls it.
- Desktops and the web: handles show the resize cursor of their axis.
- Phones and narrow areas: the compact presentation, with drawers and a bottom sheet.
- Every platform draws what the app styles: tabs, tab bars, handles, the drop indicator, docks, drawers and the sheet.

Source: https://nsh.dev/versions/main/elements/dock

---

# Editor

`Editor` is a code editor: syntax highlighting for more than fifty languages, line numbers, several carets, folding,
soft wrap, find and replace, diagnostics and decorations, with the keys of code editors (moving and duplicating lines,
comments, indentation, brackets and quotes that close as they are typed). It holds files of any length: only the rows
in view are made, and highlighting follows each edit line by line, so a long file scrolls and types as a short one
does. Typing goes through the platform's input, so input methods (pinyin, kana, dead keys) and soft keyboards work as
they do in any text field.

The editor owns behavior and comes with a look of its own built from the theme's tokens: the theme's `font-mono` at
13pt in 20pt rows, line numbers in `muted-foreground`, a faint `muted` band behind the lines with a caret, selections
in a tint of `primary`, indent guides in `border`, and the built-in syntax colors that [`TextView`](https://nsh.dev/versions/main/elements/text-view.md)'s
code blocks use, in light and dark. Each part takes the app's styles over these defaults (`classes` and `styles`).
Rust makes one with `nsh_base::editor()`, TSX with `<Editor>` from `nsh/base`.

```rust
use nsh_base::editor;
use nsh_core::prelude::*;

const MAIN: &str = "fn main() {\n    println!(\"Hello, world!\");\n}\n";

fn code() -> impl IntoElement {
    let source = signal(SharedString::from(MAIN));
    editor()
        .value(move || Some(source.get()))
        .language("rust")
        .on_change(move |value: &SharedString| source.set(value.clone()))
        .flex_1()
}
```

```tsx
import { mount, signal } from "nsh";
import { Editor } from "nsh/base";

const MAIN = `fn main() {
    println!("Hello, world!");
}
`;

function App() {
  const source = signal(MAIN);
  return <Editor value={source()} onChange={({ value }) => source.set(value)} language="rust" class="flex-1" />;
}

mount(App);
```

The editor fills the box the app gives it (`flex-1`, a height) and scrolls its text inside: vertically always,
sideways when lines are longer than the box, or not at all with `softWrap`, where long lines wrap at the editor's
width.

## The text

- **Controlled**: pass `value` and set it again in `onChange`, which reports the whole new text. A `value` the app
  changes (a file loaded, a formatter's output) replaces the text as one edit undo takes back, and the carets and
  folds away from what changed stay where they are.
- **Uncontrolled**: pass `defaultValue` and read the text from `onChange` or the ref's `value()`.

Line breaks are `\n`: `\r\n` and `\r` in a text that comes in become `\n`.

## Languages

`language` names the language by its name, an alias, an extension or a file name, in any case: `"rust"`, `"rs"`,
`"typescript"`, `"tsx"`, `"main.go"`, `"Dockerfile"`, `"Makefile"`. It decides the highlighting, the comment that
`mod+/` toggles, the brackets that match and indent, the pairs typing closes, the characters words are made of, and
the default indentation: four spaces, two for web languages (JavaScript, TypeScript, JSON, HTML, CSS, YAML, ...), tabs
for Go and Makefiles. `tabSize` and `hardTabs` set the indentation for every language. Any other name is plain text,
unless the app registered it ([its own languages](#your-own-languages)).

The languages: Rust, JavaScript, JSX, TypeScript, TSX, JSON, Python, Go, C, C++, C#, Java, Kotlin, Swift, Objective-C,
Objective-C++, Ruby, PHP, Lua, Shell, Fish, PowerShell, SQL, HTML, XML, Vue, Svelte, CSS, SCSS, Sass, Less, Markdown,
YAML, TOML, INI, Dockerfile, Makefile, CMake, Dart, Scala, Elixir, Erlang, Haskell, OCaml, F#, Clojure, Zig, Perl, R,
Julia, Nix, Terraform, Protocol Buffers, GraphQL and Diff.

```tsx
<Editor value={source()} onChange={({ value }) => source.set(value)} language={file().name} tabSize={2} softWrap class="flex-1" />
```

### Your own languages

Rust code teaches an app's editors more languages, and highlights any language with a highlighter of its own (a
tree-sitter grammar, a parser of the app's). `register_language` registers an `EditorLanguage`: its name, aliases,
extensions and file names, and its editing rules (comments, brackets, the pairs typing closes, word characters,
indentation), with `syntax` naming a built-in grammar to highlight it with. `register_highlighter` gives a language,
built-in or registered, the app's highlighter: a type implementing `EditorHighlighter`, which hears every edit (lines,
bytes and positions, as tree-sitter's edits take them) and gives each line's tokens (`EditorToken`, or a tree-sitter
capture or TextMate scope through `EditorToken::from_scope`) within a time budget, off the UI thread. The editor keeps
the tokens, moves them with the text as it is edited and asks again for the lines in view, as it does of the built-in
highlighter. `language` finds the registered languages first, by name, alias, extension or path, in editors and diff
views alike.

Each engine keeps its own languages. A Rust app registers them in its root before it mounts its editors; an app's
crate registers them for the TSX app in the setup of its UI set, which every engine running the app calls first.

```rust
use nsh_base::editor::{EditorLanguage, register_highlighter, register_language};
use nsh_core::prelude::*;

static NIMBLE: EditorLanguage = EditorLanguage::new("Nimble")
    .extensions(&["nb"])
    .line_comment("#")
    .tab_size(2);

#[native_module("my-app/native")]
fn native(registry: &mut Registry) {
    registry.setup(|| {
        register_language(&NIMBLE);
        register_highlighter("nimble", || Box::new(NimbleHighlighter::default()));
    });
}
```

```tsx
<Editor value={source()} onChange={({ value }) => source.set(value)} language="build.nb" class="flex-1" />
```

## Editing

The editor works as code editors do:

- **Several carets.** Alt-click (Option-click) adds a caret, `mod+d` selects the next occurrence of the selection,
  `mod+shift+l` all of them, and the add-caret keys add one on the row above or below. Typing, deleting, moving and
  every command act at each one; Escape goes back to one. `undoSelection` (`cmd+u`, `ctrl+u`) goes back to the
  selections before the last move.
- **Selections grow** by units with `expandSelection` (`ctrl+shift+cmd+right`, `shift+alt+right`): the word, a
  string's contents and the string, a bracket pair's contents and the pair, the line, the text; `shrinkSelection`
  goes back the same way. `splitSelectionIntoLines` (`shift+alt+i`) turns a selection over several lines into one
  selection per line.
- **Indentation.** A new line keeps the line's indentation and adds a level after an opening bracket (Python's `:`,
  Ruby's `do`, ...); Enter between a pair of brackets puts the closing one on its own line. Tab and Shift+Tab indent
  and outdent the selected lines; Backspace in leading spaces goes back to the previous indent stop. `autoIndent` turns
  this off.
- **Brackets and quotes** close as they are typed, wrap a selection, and step over the closing one when it is typed
  again (`autoClose`). The bracket at the caret and its partner are outlined.
- **Undo** takes back whole runs of typing: a word, a deletion, a command. A move or a press starts a new step.
- **Folding.** A line followed by lines indented deeper folds them away with the marker in the gutter: `⌄` to fold,
  `›` and the `⋯` after the line to unfold. A caret that moves into a fold opens it ([Folding](#folding)).
- **Presses.** With a pointer, a click places the caret, a double click selects a word, a triple click a line,
  Shift-click extends the selection and a drag selects by what the click selected. An Alt+Shift drag
  (Option+Shift; Control+Alt on Linux too) selects a block: one selection per row, between the same columns, which
  keep going past the end of short lines. On touch screens a tap places the caret, a double tap or a long press selects
  the word under the finger, and handles at the ends of that selection move each end as a finger drags them (the
  text around them still scrolls).
- **Clipboard.** Copy and cut with no selection take the whole lines of the carets, and those paste back as whole
  lines above the caret's line.

`readOnly` keeps the text as it is while it is still selected, searched and copied.

## Keys

The editor's keys work while it has the focus; other inputs keep theirs. `mod` is Command on macOS and iOS and Control
elsewhere (`keymap`'s keystrokes).

| Keys (macOS) | Keys (Windows, Linux) | Command |
|---|---|---|
| Arrows, with Shift to select | Arrows, with Shift to select | Move by character and row |
| `alt+left` / `alt+right` | `ctrl+left` / `ctrl+right` | Move by word |
| `cmd+left` / `cmd+right`, `home` / `end`, `ctrl+a` / `ctrl+e` | `home` / `end` | The line's first non-blank character (then its start) / the line's end |
| `cmd+up` / `cmd+down` | `ctrl+home` / `ctrl+end` | The start / end of the text |
| `pageup` / `pagedown` | `pageup` / `pagedown` | Up / down a page |
| `alt+backspace` / `alt+delete` | `ctrl+backspace` / `ctrl+delete` | Delete a word left / right |
| `cmd+backspace` / `cmd+delete`, `ctrl+k` | `ctrl+shift+backspace` / `ctrl+shift+delete` | Delete to the line's start / end |
| `cmd+z` / `cmd+shift+z` | `ctrl+z` / `ctrl+shift+z`, `ctrl+y` | Undo / redo |
| `cmd+a` | `ctrl+a` | Select all |
| `cmd+l` | `ctrl+l` | Select the line (again: the next one too) |
| `cmd+d` | `ctrl+d` | Select the next occurrence |
| `cmd+shift+l` | `ctrl+shift+l` | Select every occurrence |
| `cmd+alt+up` / `cmd+alt+down` | `ctrl+alt+up` / `ctrl+alt+down` | Add a caret above / below |
| `escape` | `escape` | Back to one selection |
| `alt+up` / `alt+down` | `alt+up` / `alt+down` | Move the lines up / down |
| `alt+shift+up` / `alt+shift+down` | `alt+shift+up` / `alt+shift+down` | Duplicate the lines up / down |
| `cmd+shift+k` | `ctrl+shift+k` | Delete the lines |
| `cmd+enter` / `cmd+shift+enter` | `ctrl+enter` / `ctrl+shift+enter` | A new line below / above |
| `tab` / `shift+tab`, `cmd+]` / `cmd+[` | `tab` / `shift+tab`, `ctrl+]` / `ctrl+[` | Indent / outdent |
| `cmd+/` | `ctrl+/` | Toggle the line comment |
| `cmd+shift+\` | `ctrl+shift+\` | Go to the matching bracket |
| `ctrl+j` | `ctrl+j` | Join the lines |
| `ctrl+t` | | Swap the characters around the caret |
| `ctrl+alt+left` / `ctrl+alt+right`, with Shift to select | | Move by part of a word (camelCase, snake_case) |
| `shift+alt+a` | `shift+alt+a` | Toggle the block comment |
| `shift+alt+i` | `shift+alt+i` | Split the selection into lines |
| `ctrl+shift+cmd+right` / `ctrl+shift+cmd+left` | `shift+alt+right` / `shift+alt+left` | Expand / shrink the selection |
| `cmd+u` | `ctrl+u` | Back to the previous selections |
| `cmd+g` / `cmd+shift+g`, `f3` / `shift+f3` | `f3` / `shift+f3` | Find the next / previous match |
| `cmd+e` | | Find the selection (`onFindWithSelection`) |
| `cmd+alt+[` / `cmd+alt+]` | `ctrl+shift+[` / `ctrl+shift+]` | Fold / unfold the caret's line |
| `f12` | `f12` | Go to the definition at the caret (`onDefinitionRequest`) |
| `cmd+.` | `ctrl+.` | Code actions at the selection (`onCodeActionRequest`) |
| `cmd+c` / `cmd+x` / `cmd+v` | `ctrl+c` / `ctrl+x` / `ctrl+v` | Copy / cut / paste |

macOS and iOS also have Cocoa's text keys: `ctrl+b` / `ctrl+f` / `ctrl+p` / `ctrl+n` move, `ctrl+h` / `ctrl+d`
delete.

The commands without default keys, and the app's own, take the keys the app binds with
[`keymap`](https://nsh.dev/versions/main/modules/nsh.md#keymap), running them through the ref's `run`:

```tsx
import { keymap } from "nsh";

let editor!: EditorRef;

keymap.bind({
  "f9": () => editor.run("sortLinesAscending"),
  "mod+shift+u": () => editor.run("transformToUppercase"),
  "mod+alt+0": () => editor.run("foldAll"),
  "mod+alt+j": () => editor.run("unfoldAll"),
});
```

## Find and replace

`search` is what to find: `{ query, caseSensitive?, wholeWord?, regex?, inSelection? }`. Its matches are highlighted, the one the
selection is on more strongly, and `onSearchChange` reports `{ result }`, a `{ count, current, error }`: how many matches, which one
the selection is on (from 0), and why a regular expression is not valid. `findNext` and `findPrevious` select the next
and previous match, wrapping around; `replace(text)` replaces the current match and selects the next one, and
`replaceAll(text)` replaces every match as one edit and returns `{ count }`, how many. A regular expression's replacement refers to
its groups as `$1` and `${name}`.

`inSelection` finds only inside what was selected when it turned on (the carets' lines when nothing was): the scope
stays while it stays on, through edits, as the selection moves from match to match. `findWithSelection` (`cmd+e` on
macOS) reports the selected text, or the word at the caret, with `onFindWithSelection`, for the find bar to take as
its query.

The find bar is the app's own:

```tsx
import { signal, Text, View } from "nsh";
import { Button, Editor, type EditorRef, type EditorSearchResult, Input } from "nsh/base";

function Find(props: { source: string; onChange: (value: string) => void }) {
  let editor!: EditorRef;
  const query = signal("");
  const replacement = signal("");
  const result = signal<EditorSearchResult>({ count: 0 });
  const status = () =>
    result().error ?? (result().current != null ? `${result().current! + 1} of ${result().count}` : `${result().count} found`);
  return (
    <View class="flex-1">
      <View class="flex-row items-center gap-2 border-b border-border p-2">
        <Input value={query()} onChange={({ value }) => query.set(value)} onSubmit={() => editor.run("findNext")} placeholder="Find" class="flex-1" />
        <Text class="text-sm text-muted-foreground">{status()}</Text>
        <Button onPress={() => editor.run("findPrevious")} class="px-2"><Text>↑</Text></Button>
        <Button onPress={() => editor.run("findNext")} class="px-2"><Text>↓</Text></Button>
        <Input value={replacement()} onChange={({ value }) => replacement.set(value)} placeholder="Replace" class="flex-1" />
        <Button onPress={() => editor.replace(replacement())} class="px-2"><Text>Replace</Text></Button>
        <Button onPress={async () => console.log("replaced", (await editor.replaceAll(replacement())).count)} class="px-2"><Text>All</Text></Button>
      </View>
      <Editor
        ref={editor}
        value={props.source}
        onChange={(e) => props.onChange(e.value)}
        language="ts"
        search={query() ? { query: query() } : undefined}
        onSearchChange={(e) => result.set(e.result)}
        class="flex-1"
      />
    </View>
  );
}
```

## Diagnostics

`diagnostics` marks the problems a language server or a linter reports: a thin wavy underline under each range in its
severity's color (`error`, `warning`, `info`, `hint`). Positions are lines and UTF-16 columns from 0, as a language server's, so
its diagnostics pass through as they come. The marks stay on their text while the user types, until the app passes
new ones; showing the messages (a list, a hover card at the line) is the app's.

A diagnostic carries the rest of a language server's `Diagnostic` too. Its `tags` draw its text as language clients do:
`unnecessary` code (an unused variable, unreachable code) is faded and `deprecated` code struck through, in the
`unnecessaryText` and `deprecatedText` parts; a hint with a tag shows in its text alone. `codeDescription.href` is the
page that describes its code (a lint rule's), and `relatedInformation` lists the other places that tell about it
(`{ location: { uri?, range }, message }`): the hover hands both to the app, which shows them in its hover card and
opens the page. A language server sends tags as numbers (`1`, `2`); the editor takes their names.

```tsx
const problems = signal<EditorDiagnostic[]>([]);

async function lint(text: string) {
  // [{ range, severity, message, source?, code?, codeDescription?, tags?, relatedInformation? }]
  problems.set(await check(text));
}

<Editor
  value={source()}
  onChange={({ value }) => {
    source.set(value);
    lint(value);
  }}
  language="ts"
  diagnostics={problems()}
  classes={{ diagnosticWarning: "bg-orange-500", unnecessaryText: "text-zinc-400" }}
  class="flex-1"
/>
```

## Decorations

`decorations` style ranges the app chooses: semantic highlighting from a language server, the statement being run, the
lines a review changed. A decoration's `class` and `style` style its text; `lineClass` and `lineStyle` style the rows
of its lines, behind the text. Like diagnostics, they stay on their text through edits until the app sets new ones.

```tsx
const range = (line: number, start: number, end: number) => ({ start: { line, column: start }, end: { line, column: end } });

<Editor
  value={source()}
  language="sql"
  readOnly
  decorations={[
    { range: range(4, 0, 0), lineClass: "bg-green-500/10" },
    { range: range(7, 6, 18), class: "underline text-blue-600" },
  ]}
  class="flex-1"
/>
```

### Gutter and overview ruler marks

A decoration's `gutter` puts a mark in a strip before the line numbers, beside every line its range covers: the lines
a version-control diff added or modified, or a breakpoint (an empty range covers its line, as with `lineClass`). With
`placement: "before"` it is a line across the strip at the boundary before the range's start, where lines were
deleted. The strip is `gutterDecorationsWidth` points wide (3 by default) and stays while a decoration has a gutter
mark, so the text keeps its place as marks come and go. A range inside a fold marks the fold's row.

A decoration's `overviewRuler` puts a mark on the overview ruler, the strip along the editor's right edge, 14 points
wide (a scroll bar's; the `overviewRuler` part sets another width), that maps the whole text to its height, as Monaco's does. A mark is at
least 6 points tall and takes a `lane` of the ruler: `left`, `center` (the default), `right` or `full`. The ruler shows
while a decoration has a mark there.

Each mark takes the app's `class` and `style`, drawn in the foreground color without them. Both follow edits as the
decoration's range does; an edit that deletes a marked range leaves an empty one where it was.

```tsx
<Editor
  value={source()}
  onChange={({ value }) => source.set(value)}
  language="ts"
  decorations={[
    { range: range(2, 0, 0), gutter: { class: "bg-yellow-500" }, overviewRuler: { lane: "left", class: "bg-yellow-500" } },
    { range: { start: { line: 3, column: 0 }, end: { line: 5, column: 0 } }, gutter: { class: "bg-green-500" } },
    { range: range(6, 0, 0), gutter: { class: "bg-red-500", placement: "before" }, overviewRuler: { lane: "left", class: "bg-red-500" } },
  ]}
  class="flex-1"
/>
```

### Your own highlighting

A decoration's `token` colors its text as the built-in highlighting colors that kind of token (`comment`, `keyword`,
`string`, `number`, `title`, `attr`, `built`, `deletion`), in place of what the built-in highlighter found there: the
app's own highlighter (a language server's semantic tokens, a parser of its own) maps its tokens onto these and gets
the editor's colors in light and dark. The innermost decoration's token wins; `class` and `style` apply over it.
`highlighting={false}` turns the built-in highlighter off, so the app's tokens color the text alone, while `language`
still decides comments, brackets and indentation.

```tsx
const kinds: Record<string, EditorToken> = { keyword: "keyword", function: "title", string: "string", type: "built" };

<Editor
  value={source()}
  onChange={({ value }) => source.set(value)}
  language="ts"
  highlighting={false}
  decorations={semanticTokens().map((t) => ({ range: range(t.line, t.start, t.end), token: kinds[t.type] }))}
  class="flex-1"
/>
```

## Folding

Folds start where lines are indented deeper than the line before them. `foldRanges` gives the editor the app's
own ranges instead (`{ startLine, endLine }`, the shape of a language server's folding ranges, which pass through as
they come): line `startLine` shows the fold and the lines after it through `endLine` fold away. They stay on their
lines through edits until the app passes new ones.

Folds nest: folding a block keeps the folds inside it folded, so unfolding the block shows them as they were.
`foldRecursive` folds a block and every block inside it, `unfoldRecursive` unfolds them all, `foldLevel(n)` folds
every block at nesting level `n`, and `foldSelection` (or `foldRange(range)`) folds any lines, wherever folds start.
`onFoldChange` reports the folded ranges after every change, and `folds()` / `setFolds(ranges)` read and restore
them, to keep them with the file.

```tsx
const ranges = signal<EditorFoldRange[]>([]);
const folded = new Map<string, EditorFoldRange[]>();

<Editor
  ref={editor}
  value={file().text}
  language={file().name}
  foldRanges={ranges()} // from the language server's textDocument/foldingRange
  onFoldChange={({ folds }) => folded.set(file().name, folds)}
  class="flex-1"
/>
<Button onPress={() => editor.foldLevel(2)}><Text>Fold the methods</Text></Button>
```

## Breakpoints and context menus

A press on a line number reports `onLineNumberPress({ line })`, the place for a breakpoint the app draws as a decoration.
The secondary button (a right click, Control-click on a Mac) reports `onContextMenu({ position, x, y })`: the
position in the text under the pointer and the point in the root view, where the app opens its own menu. On touch
screens a long press, a double tap, a handle let go and a tap on the selection report it too, with `selection`: the
selection's box in the root view (`{ x, y, width, height }`), and `x` / `y` at its top middle, for the edit menu.

```tsx
<Editor
  value={source()}
  onContextMenu={({ x, y, selection }) =>
    Menu.popup(selection ? editItems : contextItems, { x, y })
  }
/>
```

```tsx
const breakpoints = signal<number[]>([]);

<Editor
  value={source()}
  language="py"
  onLineNumberPress={({ line }) =>
    breakpoints.set(breakpoints().includes(line) ? breakpoints().filter((l) => l !== line) : [...breakpoints(), line])
  }
  decorations={breakpoints().map((line) => ({ range: range(line, 0, 0), lineClass: "bg-red-500/15" }))}
  class="flex-1"
/>
```

## Language features

Suggestions, hover information, go to definition and code actions come from the app's language server. The editor
draws the completion list, the inline completion and the definition link itself, with their keys; for the rest it
gives the app the moments and the places, and the app draws its popups (an [`Overlay`](https://nsh.dev/versions/main/elements/overlay.md) anchored to a
`pageBounds`).

### Completion

With `completion`, the editor asks the app for suggestions and shows them as a list under the word being typed (above
it near the bottom of the window):

- Typing a letter, digit or `_` at the end of a word asks with `onCompletionRequest(event)`, trigger `"typing"`: `event`
  has its `id`, the caret's `offset` and `position`, the `query` (the word typed so far) and the `queryStart` offset
  where it starts. Each of `completionTriggerCharacters` (`["."]`, `["::", "<"]`) asks with an empty query after it,
  trigger `"character"` (and the `character`), and `showCompletions()` or `run("showCompletions")` asks at the caret,
  trigger `"invoked"`.
- The app answers with `presentCompletions(event.id, items)`. Each item is a language server's `CompletionItem` shape:
  `label`, and optionally `kind` (`"function"`, `"variable"`, `"class"`, ...), `detail`, `documentation`,
  `insertText`, `filterText`, `sortText` and `range`. The answer to the latest request shows; an earlier one, or one
  for a word the caret has left, is set aside.
- Typing on filters the list in place: the query matches each item's `filterText` (else its label) as letters in
  order, in any case, words starting with the query first, then the closest matches, then by `sortText`. The matched
  letters stand out. Pass `incomplete: true` (`presentCompletions(id, items, true)`) for the editor to ask again as
  typing goes on.
- Up and Down (and Control+P / Control+N) move through the list, Page Up and Page Down by a page, Enter and Tab
  accept, Escape closes it. The pointer marks an item and a click (a tap on touch screens) accepts it. The selected
  item's `documentation` shows beside the list.
- Accepting replaces the item's `range` (else the query) with its `insertText` (else its label), as one step undo
  takes back, at the caret and at every other caret with the same text before it, and reports
  `onCompletionAccept({ item })`.
- The list closes as the caret leaves the word, on a space or other punctuation, when the editor loses the focus and
  when the caret scrolls out of view.

A pause in typing (`inlineCompletionDelay`, 300 ms by default) with no list showing asks for an inline completion:
`onInlineCompletionRequest({ id, offset, position })`. `presentInlineCompletion(id, text)` shows `text` at the caret in
a muted color, Tab inserts it, and Escape, an edit or a move clears it.

```tsx
let editor!: EditorRef;

<Editor
  ref={(r) => (editor = r)}
  value={source()}
  onChange={({ value }) => source.set(value)}
  language="ts"
  completion
  completionTriggerCharacters={["."]}
  onCompletionRequest={async (e) => {
    const items = await server.completion(e.position);
    editor.presentCompletions(e.id, items);
  }}
  onInlineCompletionRequest={async (e) => {
    editor.presentInlineCompletion(e.id, await assistant.suggest(e.offset));
  }}
  class="flex-1"
/>
```

### Hovers and presses

- `onHover(event)`: the mouse rests over a character with no button down (desktops and the web; a drag selects
  text). `event` has its `position`, its UTF-16 `offset`, the `range` of its word, the pointer's `pagePosition`, the
  word's `pageBounds`, the `modifiers` held and the `diagnostics` there, whose messages the app shows. Moving to
  another word reports the next hover at once.
- `onHoverEnd()`: the mouse left the word or the editor, or the text changed or scrolled under it.
- `onTextPress(event)`: a character was pressed, after the editor placed its caret: `{ position, offset, range,
  pagePosition, modifiers, clicks }`.
- `caretBounds()` and `rangeBounds(range)`: where the caret and a range are, `{ bounds, pageBounds }` (in the editor
  and in the root view): a popup of the app's opens there.

```tsx
const hover = signal<EditorHoverEvent | null>(null);

<Editor
  ref={editor}
  value={source()}
  language="ts"
  onHover={(event) => hover.set(event)}
  onHoverEnd={() => hover.set(null)}
  class="flex-1"
/>
<If when={hover()}>
  {(event) => (
    <Overlay anchor={event().pageBounds} placement="top" class="rounded-md border border-border bg-popover p-2">
      <Text>{event().diagnostics.map((d) => d.message).join("\n") || describe(event().range)}</Text>
    </Overlay>
  )}
</If>
```

### Go to definition and code actions

Holding Mod (Command on macOS and iOS, Control elsewhere) turns the words under the mouse into links, as in code
editors:

- With Mod held over a word (pressed while the mouse rests there, or the mouse moved there with it held), the editor
  asks with `onDefinitionRequest(event)`, trigger `"hover"`: `event` has its `id`, the character's `position` and
  `offset`, and the word's `range`. Answer with `presentDefinitionLink(event.id, range)` when the language server
  finds a definition: the range is underlined (the `definitionLink` part) and the pointer becomes a hand over it. The
  link goes when Mod is released, the mouse leaves it or the text changes or scrolls, or with `hideDefinitionLink()`.
  The answer to the latest request shows; an earlier one is set aside.
- A Mod-click on a word asks with trigger `"press"`; on the link the caret stays where it is. F12 (`goToDefinition`,
  `run("goToDefinition")`) asks for the word at the caret, trigger `"key"`. The app goes to the definition:
  `revealPosition` and `setSelections` for one in the same text, its own navigation for another file.
- Mod+. (`showCodeActions`, `run("showCodeActions")`) reports `onCodeActionRequest({ range, position, bounds })`: the
  primary selection (start first), the caret and its box. The app asks its language server for actions, shows its
  menu at `bounds.pageBounds` (a [`Menu`](https://nsh.dev/versions/main/elements/menu.md) or an `Overlay`), and applies the chosen one's edits with
  `edit(edits)`.

```tsx
let editor!: EditorRef;

<Editor
  ref={(r) => (editor = r)}
  value={source()}
  onChange={({ value }) => source.set(value)}
  language="ts"
  onDefinitionRequest={async (e) => {
    const target = await server.definition(e.position);
    if (!target) return;
    if (e.trigger === "hover") editor.presentDefinitionLink(e.id, target.originRange ?? e.range);
    else editor.revealPosition(target.range.start, true);
  }}
  onCodeActionRequest={async (e) => {
    const actions = await server.codeActions(e.range);
    const picked = await choose(actions, e.bounds?.pageBounds);
    if (picked) editor.edit(picked.edits);
  }}
  class="flex-1"
/>
```

## Size and scrolling

With `minRows` and / or `maxRows` the editor grows with its text: it is as tall as its rows, at least `minRows`
of them, and from `maxRows` on its text scrolls, as a message box or a cell of a notebook does. Otherwise the
app sizes it, and `scrollBeyondLastLine` lets the text scroll on past its last line: up to a screen (`true`, the
default), not at all (`false`) or a number of rows. As the caret moves, `cursorSurroundingLines` rows stay in view
around it. Dragging a selection past the editor's edges scrolls on, faster the farther out the pointer goes.

`showWhitespaces` shows a `·` for each space and a `→` for each tab (the `whitespace` part), and `rulers` draws a
line at each of its columns (the `ruler` part), as guides of a line's length.

```tsx
<Editor
  defaultValue={message()}
  language="markdown"
  minRows={2}
  maxRows={8}
  rulers={[72]}
  showWhitespaces
/>
```

## Methods

`ref={editor}` gives the editor's methods (`EditorRef`), for the app's buttons, menus and keys. Methods that return a
value (`value()`, `selections()`, `replaceAll()`, `canUndo()`, `caretBounds()`, `folds()`, ...) return a `Promise` of it in JS, so `await`
them: `const text = await editor.value()`. A method given a line past the text (`fold`, `scrollToLine`, `goToLine`,
...) changes nothing and logs a warning naming the method and the line.

| Method | Description |
|---|---|
| `focus()`, `blur()` | Takes the focus, or gives it up. |
| `value()` | `Promise<string>`: the text. |
| `setValue(value)` | Replaces the text, as an edit undo takes back. |
| `insert(text)` | Types `text` at each selection, as it is (brackets do not close). |
| `edit(edits)` | Applies `{ range, text }` replacements (ranges of the current text; one overlapping an earlier one is skipped) as one step undo takes back; the selections move with the text around them. Code actions and formatting edits go here. |
| `selections()` | `Promise<EditorSelection[]>`: every selection, `{ anchor, head }`, the primary (newest) last. |
| `setSelections(selections)` | Sets the selections (the last one primary) and scrolls the primary one into view. |
| `run(command)` | Runs a command, as its keys would ([Commands](#commands)). |
| `replace(text)` | Replaces the current match and selects the next. |
| `replaceAll(text)` | `Promise<EditorReplaceAll>`: replaces every match as one edit; `{ count }`, how many. |
| `fold(line)`, `unfold(line)` | Folds the lines under line `line` (from 0), or unfolds it. |
| `foldRecursive(line)`, `unfoldRecursive(line)` | Folds the fold on line `line` and every fold inside it, or unfolds them all. |
| `foldLevel(level)` | Folds every fold at nesting level `level` (1: the outermost). |
| `foldRange(range)` | Folds the lines of `range` (`{ startLine, endLine }`), wherever folds start. |
| `folds()` | `Promise<EditorFoldRange[]>`: the folded ranges, nested ones included. |
| `setFolds(folds)` | Folds exactly `folds`. |
| `scrollToLine(line)` | Scrolls line `line` into view, unfolding what hides it. |
| `canUndo()`, `canRedo()` | `Promise<boolean>`: whether there is an edit to take back, or to do again. |
| `caretBounds()` | `Promise<EditorBounds \| null>`: the primary caret's box, `{ bounds, pageBounds }`, in the editor (its scrolling applied) and in the root view; `null` before the editor is laid out. |
| `rangeBounds(range)` | `Promise<EditorBounds[]>`: the boxes of `range`, one per row it covers. |
| `scrollOffset()`, `setScrollOffset(offset)` | `Promise<Point>`: how far the text is scrolled; scrolls it to `{ x, y }`. |
| `visibleRange()` | `Promise<EditorRange>`: the text the viewport shows, from its first row's start to its last row's end. |
| `selectedText()` | `Promise<string>`: the primary selection's text. |
| `offsetToPosition(offset)`, `positionToOffset(position)` | `Promise<EditorPosition>`, `Promise<number>`: between UTF-16 offsets of `value()` and positions. |
| `revealPosition(position, center)` | Scrolls `position` into view, unfolding what hides it; to the middle with `center`. |
| `goToLine(line)` | Puts the caret at line `line`'s start (from 0) and scrolls it to the middle. |
| `showCompletions()` | Asks for completions at the caret, the word before it the query ([Completion](#completion)). |
| `presentCompletions(id, items, incomplete?)` | Answers completion request `id`: the list shows `items`, filtered by what has been typed since; with `incomplete`, typing on asks again. No items close the list. |
| `hideCompletions()` | Closes the completion list. |
| `presentInlineCompletion(id, text)`, `hideInlineCompletion()` | Answers inline completion request `id` with `text`, shown at the caret; clears it. |
| `presentDefinitionLink(id, range)`, `hideDefinitionLink()` | Answers definition request `id` (trigger `"hover"`): `range` is underlined as a link ([Go to definition](#go-to-definition-and-code-actions)); hides it. |

```tsx
let editor!: EditorRef;

<Button onPress={() => editor.run("toggleComment")}><Text>Comment</Text></Button>
<Button onPress={async () => save(await editor.value())}><Text>Save</Text></Button>
<Button onPress={async () => (await editor.canUndo()) && editor.run("undo")}><Text>Undo</Text></Button>
<Button onPress={() => editor.setSelections([{ anchor: { line: 0, column: 0 }, head: { line: 0, column: 0 } }])}>
  <Text>Go to the top</Text>
</Button>
<Editor ref={editor} value={source()} onChange={({ value }) => source.set(value)} language="rs" class="flex-1" />
```

### Commands

`run` takes the editor's commands by name (`EditorCommand`):

| Commands | What they do |
|---|---|
| `moveLeft`, `moveRight`, `moveUp`, `moveDown`, `moveWordLeft`, `moveWordRight`, `moveLineStart`, `moveLineEnd`, `movePageUp`, `movePageDown`, `moveDocumentStart`, `moveDocumentEnd` | Move the carets. |
| `selectLeft`, `selectRight`, `selectUp`, `selectDown`, `selectWordLeft`, `selectWordRight`, `selectLineStart`, `selectLineEnd`, `selectPageUp`, `selectPageDown`, `selectDocumentStart`, `selectDocumentEnd` | Extend the selections. |
| `moveToMatchingBracket` | To the bracket matching the one at the caret. |
| `selectAll`, `selectLine`, `selectWord`, `selectNextOccurrence`, `selectPreviousOccurrence`, `selectAllOccurrences` | Select. |
| `moveSubwordLeft`, `moveSubwordRight`, `selectSubwordLeft`, `selectSubwordRight` | Move or extend by part of a word (camelCase humps, snake_case parts). |
| `moveParagraphUp`, `moveParagraphDown`, `selectParagraphUp`, `selectParagraphDown` | Move or extend to the blank line before or after the paragraph. |
| `expandSelection`, `shrinkSelection` | Grow the selections by a unit, or back. |
| `undoSelection`, `redoSelection` | Back to the selections before the last move, or forward again. |
| `splitSelectionIntoLines` | One selection per line of each selection. |
| `addCaretAbove`, `addCaretBelow`, `singleSelection` | Add a caret; back to one selection. |
| `deleteBackward`, `deleteForward`, `deleteWordLeft`, `deleteWordRight`, `deleteToLineStart`, `deleteToLineEnd`, `deleteLine` | Delete. |
| `newline`, `newlineBelow`, `newlineAbove`, `indent`, `outdent`, `toggleComment`, `toggleBlockComment` | Lines, indentation and comments. |
| `sortLinesAscending`, `sortLinesDescending` | Sort the selected lines (every line with only a caret). |
| `transformToUppercase`, `transformToLowercase`, `transformToTitleCase` | Change the case of the selections (a caret: its word). |
| `trimTrailingWhitespace` | Remove the whitespace at the end of every line. |
| `moveLinesUp`, `moveLinesDown`, `duplicateLinesUp`, `duplicateLinesDown`, `joinLines`, `transposeCharacters` | Rearrange. |
| `undo`, `redo` | Undo and redo. |
| `fold`, `unfold`, `foldAll`, `unfoldAll` | Fold at the caret's line, or everything. |
| `foldRecursive`, `unfoldRecursive` | Fold the caret's fold and every fold inside it, or unfold them. |
| `foldSelection` | Fold the lines of each selection that spans several. |
| `findNext`, `findPrevious` | Select the next or previous match of `search`. |
| `findWithSelection` | Report the selected text for the find bar (`onFindWithSelection`). |
| `copy`, `cut`, `paste` | The clipboard. |
| `showCompletions` | Ask for completions at the caret ([Completion](#completion)). |
| `goToDefinition` | Ask for the definition of the word at the caret (`onDefinitionRequest`, trigger `"key"`). |
| `showCodeActions` | Ask for the code actions at the selection (`onCodeActionRequest`). |

## Styling the parts

`class` and `style` style the editor's box. `classes` takes Tailwind classes by part and `styles` inline styles by
part; a part's classes come after its own default styles, so they win, and its `styles` win over its classes. The font
is set with `fontFamily`, `fontSize` and `lineHeight`, which the editor measures its text in.

```tsx
<Editor
  value={source()}
  onChange={({ value }) => source.set(value)}
  language="tsx"
  fontFamily="JetBrains Mono"
  fontSize={14}
  lineHeight={22}
  class="flex-1 rounded-lg border border-border"
  classes={{
    gutter: "bg-muted",
    lineNumber: "text-xs",
    activeLine: "bg-yellow-500/10",
    selection: "bg-blue-500/30",
  }}
  styles={{ caret: { backgroundColor: "#f59e0b", width: 3 } }}
/>
```

| Part | What it is | Default |
|---|---|---|
| `gutter` | The column of line numbers and fold markers | 12pt before the numbers, 4pt after the markers |
| `lineNumber` | Every line number | Right-aligned, `muted-foreground` |
| `activeLineNumber` | The numbers of the lines with a caret, after `lineNumber` | `foreground` |
| `foldMarker` | The marker of a line where a fold starts | `⌄`, `›` folded, `muted-foreground` |
| `overviewRuler` | The overview ruler along the right edge, while a decoration has a mark there | none |
| `content` | The text area beside the gutter | 4pt before the text |
| `line` | Every row of text | |
| `activeLine` | Behind the rows of the lines with a caret, below the scroll indicators | `muted`, faint |
| `selection` | Behind selected text | A tint of `primary` |
| `caret` | The carets | 2pt wide, `foreground`, blinking |
| `composition` | The text an input method is composing | Underlined |
| `searchMatch` | The matches of `search` | Translucent amber |
| `currentSearchMatch` | The match the selection is on, after `searchMatch` | Stronger amber |
| `matchingBracket` | The bracket at the caret and its partner | A 1pt border |
| `indentGuide` | A guide per indentation level | A 1pt line of `border` |
| `foldPlaceholder` | What a folded line shows after its text | ` ⋯ `, `muted-foreground` |
| `placeholder` | Shown while the text is empty | `muted-foreground` |
| `diagnosticError` | The line under an error | `destructive` |
| `diagnosticWarning` | The line under a warning | Amber |
| `diagnosticInfo` | The line under an information | Blue |
| `diagnosticHint` | The line under a hint | `muted-foreground` |
| `unnecessaryText` | The text of an `unnecessary` diagnostic | `muted-foreground` |
| `deprecatedText` | The text of a `deprecated` diagnostic | Struck through |
| `whitespace` | The marks of spaces and tabs (`showWhitespaces`) | `·` and `→`, `muted-foreground` at 60 % |
| `ruler` | The lines of `rulers` | A 1 point line of `border` |
| `selectionHandle` | The knobs of the handles at the ends of a touch selection | A 10pt dot of `primary` |
| `selectionHandleStart`, `selectionHandleEnd` | The start's knob (above its line) and the end's (below), after `selectionHandle` | |
| `completionMenu` | The completion list's box | `popover`, a 1pt `border`, rounded, a shadow |
| `completionItem` | Every item of the list | A row's height, 8pt of padding |
| `selectedCompletionItem` | The selected item, after `completionItem` | `accent` |
| `completionMatch` | The letters of a label the query matched | Semibold, `primary` |
| `completionDetail` | An item's detail, after its label | Right-aligned, `muted-foreground` |
| `completionKind` | An item's kind, before its label | A short name (`fn`, `var`, `cls`), `muted-foreground` |
| `completionDocumentation` | The selected item's documentation, beside the list | As `completionMenu`, at most 320pt wide |
| `inlineCompletion` | The inline completion at the caret | `muted-foreground` |
| `definitionLink` | The underline of the definition link | A 1pt line of `primary` under the text |

## Props

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `value` | `.value(..)` | `string` | | The text, controlled by the app (set it again from `onChange`). |
| `defaultValue` | `.default_value(..)` | `string` | | The first text, when the editor keeps its own. |
| `language` | `.language(..)` | `string` | plain text | A language's name, alias, extension or file name ([Languages](#languages)). |
| `placeholder` | `.placeholder(..)` | `string` | | Shown while the text is empty. |
| `readOnly` | `.read_only(..)` | `boolean` | `false` | The text is selected and copied, not changed. |
| `autoFocus` | `.auto_focus(..)` | `boolean` | `false` | Takes the focus when it appears. |
| `lineNumbers` | `.line_numbers(..)` | `boolean` | `true` | The gutter's line numbers. |
| `softWrap` | `.soft_wrap(..)` | `boolean` | `false` | Long lines wrap at the editor's width. |
| `tabSize` | `.tab_size(..)` | `number` | the language's | The columns of a tab and of an indentation level. |
| `hardTabs` | `.hard_tabs(..)` | `boolean` | the language's | Indents with tabs. |
| `folding` | `.folding(..)` | `boolean` | `true` | Indented lines fold with the gutter's markers. |
| `foldRanges` | `.fold_ranges(..)` | `EditorFoldRange[]` | by indentation | Where folds start, the app's ([Folding](#folding)). |
| `highlighting` | `.highlighting(..)` | `boolean` | `true` | The built-in syntax highlighting ([Your own highlighting](#your-own-highlighting)). |
| `autoClose` | `.auto_close(..)` | `boolean` | `true` | Brackets and quotes close as they are typed. |
| `autoIndent` | `.auto_indent(..)` | `boolean` | `true` | A new line keeps the indentation and indents after an opening bracket. |
| `activeLine` | `.active_line(..)` | `boolean` | `true` | The rows of the lines with a caret are highlighted. |
| `indentGuides` | `.indent_guides(..)` | `boolean` | `true` | The guides of indentation. |
| `scrollBeyondLastLine` | `.scroll_beyond_last_line(..)` | `boolean \| number` | `true` | The text scrolls on past its last line: up to a screen (`true`), not at all (`false`) or that many rows. |
| `fontFamily` | `.font_family(..)` | `string` | the theme's `font-mono` | The font the text is drawn and measured in. |
| `fontSize` | `.font_size(..)` | `number` | `13` | The font size, in points. |
| `lineHeight` | `.line_height(..)` | `number` | `20` | The height of a row, in points; in a terminal a row is one Cell. |
| `search` | `.search(..)` | `EditorSearch` | | What to find ([Find and replace](#find-and-replace)). |
| `diagnostics` | `.diagnostics(..)` | `EditorDiagnostic[]` | `[]` | Problems to mark ([Diagnostics](#diagnostics)). |
| `decorations` | `.decorations(..)` | `EditorDecoration[]` | `[]` | Ranges the app styles ([Decorations](#decorations)). |
| `gutterDecorationsWidth` | `.gutter_decorations_width(..)` | `number` | `3` | The width of the gutter's strip of decorations' marks, in points. |
| `classes` | `.classes(..)` | `EditorClasses` | `{}` | Tailwind classes by part. |
| `styles` | `.styles(..)` | `EditorStyles` | `{}` | Inline styles by part, over the classes. |
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | | What screen readers call the editor. |
| `showWhitespaces` | `.show_whitespaces(..)` | `boolean` | `false` | Spaces and tabs show as `·` and `→`. |
| `rulers` | `.rulers(..)` | `number[]` | `[]` | Columns to draw a vertical line at. |
| `minRows` | `.min_rows(..)` | `number` | | The editor grows with its text from this many rows ([Size and scrolling](#size-and-scrolling)). |
| `maxRows` | `.max_rows(..)` | `number` | | The editor grows with its text up to this many rows, then scrolls. |
| `cursorSurroundingLines` | `.cursor_surrounding_lines(..)` | `number` | `1` | The rows kept in view above and below the caret. |
| `completion` | `.completion(..)` | `boolean` | `false` | The editor asks for suggestions and shows them as a list ([Completion](#completion)). |
| `completionTriggerCharacters` | `.completion_trigger_characters(..)` | `string[]` | `[]` | What else asks for completions as it is typed. |
| `inlineCompletionDelay` | `.inline_completion_delay(..)` | `number` | `300` | Milliseconds typing pauses before an inline completion is asked for. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | | The editor's box. |

## Events

| Event | Rust | Description |
|---|---|---|
| `onChange` | `.on_change(\|value: &SharedString\| ..)` | The text changed: `{ value }`, the whole new text. |
| `onSelectionChange` | `.on_selection_change(\|selections: &Vec<EditorSelection>\| ..)` | The selections changed: `{ selections }`, every one, the primary last. |
| `onFocus`, `onBlur` | `.on_focus(\|\| ..)`, `.on_blur(\|\| ..)` | The editor took or lost the focus. |
| `onSearchChange` | `.on_search_change(\|result: &EditorSearchResult\| ..)` | The search's matches changed: `{ result }`, a `{ count, current, error }`. |
| `onLineNumberPress` | `.on_line_number_press(\|line: &u32\| ..)` | A line number was pressed: `{ line }`, the line, from 0. |
| `onContextMenu` | `.on_context_menu(\|event: &EditorContextMenuEvent\| ..)` | The secondary button was pressed over the text, or a touch selected text: `{ position, x, y, selection? }`. |
| `onHover` | `.on_hover(\|event: &EditorHoverEvent\| ..)` | The mouse rests over a character ([Language features](#language-features)). |
| `onHoverEnd` | `.on_hover_end(\|\| ..)` | The hover ended. |
| `onTextPress` | `.on_text_press(\|event: &EditorTextPressEvent\| ..)` | A character was pressed: with its word, the modifiers and the clicks. |
| `onFindWithSelection` | `.on_find_with_selection(\|query: &String\| ..)` | `findWithSelection` ran: `{ query }`, the text for the find bar's query. |
| `onFoldChange` | `.on_fold_change(\|folds: &Vec<EditorFoldRange>\| ..)` | The folded ranges changed: `{ folds }`, every one, nested ones included. |
| `onCompletionRequest` | `.on_completion_request(\|event: &EditorCompletionRequest\| ..)` | The editor asks for completions: `{ id, offset, position, query, queryStart, trigger, character? }` ([Completion](#completion)). |
| `onCompletionAccept` | `.on_completion_accept(\|event: &EditorCompletionAcceptEvent\| ..)` | An item was accepted and inserted: `{ item }`. |
| `onInlineCompletionRequest` | `.on_inline_completion_request(\|event: &EditorInlineCompletionRequest\| ..)` | Typing paused: `{ id, offset, position }`, for an inline completion. |
| `onDefinitionRequest` | `.on_definition_request(\|event: &EditorDefinitionRequest\| ..)` | The editor asks for a definition: `{ id, position, offset, range, trigger }` ([Go to definition](#go-to-definition-and-code-actions)). |
| `onCodeActionRequest` | `.on_code_action_request(\|event: &EditorCodeActionRequest\| ..)` | The user asked for code actions: `{ range, position, bounds? }`. |

## Accessibility

Screen readers call the editor by its `accessibilityLabel`; its focus is a text input's, so the platform's text
services (input methods, dictation, soft keyboards) work in it.

## Related

- [TextView](https://nsh.dev/versions/main/elements/text-view.md): documents of Markdown and HTML, whose code blocks share the editor's syntax colors.
- [DiffView](https://nsh.dev/versions/main/elements/diff-view.md): the changes between two texts, in the editor's syntax colors.
- [Input](https://nsh.dev/versions/main/elements/input.md): single and multiline text fields with the platform's own editing.
- [`keymap`](https://nsh.dev/versions/main/modules/nsh.md#keymap): the app's keys for the editor's commands.
- [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md): the other base components.

Source: https://nsh.dev/versions/main/elements/editor

---

# HoverCard

A hover card previews what its trigger points at without leaving the page: the profile behind a mention, the page
behind a link, the quote behind a ticker. On the desktops and in desktop browsers it opens once the pointer has rested
on the trigger for `openDelay` (600 ms), or once the keyboard focus comes to the trigger. It stays open while the
pointer moves from the trigger onto the card and back, and while the keyboard focus is on the trigger or on a link or
button in the card, so everything in the card can be used with the pointer and the keyboard alike. It closes
`closeDelay` (300 ms) after the pointer has left both and the focus is in neither. Escape and a press outside close it
at once. On phones and
tablets a press on the trigger opens and closes it, and a press outside closes it.

`HoverCard` from [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md) draws nothing of its own: the trigger is your element, the
popup and its content are yours.

```rust
use nsh_base::hover_card;
use nsh_core::prelude::*;

fn mention() -> impl IntoElement {
    hover_card()
        .offset(px(8.0))
        .popup_class("w-72 gap-2 rounded-xl border border-border bg-popover p-4 shadow-lg")
        .trigger(text("@ada").text_color(rgb(0x2563eb)))
        .child(text("Ada Lovelace").font_weight(FontWeight::SEMIBOLD))
        .child(text("Writes the first programs for the Analytical Engine."))
}
```

```tsx
import { Text } from "nsh";
import { HoverCard } from "nsh/base";

function Mention() {
  return (
    <HoverCard
      offset={8}
      popupClass="w-72 gap-2 rounded-xl border border-border bg-popover p-4 shadow-lg"
      trigger={<Text class="text-blue-600">@ada</Text>}
    >
      <Text class="font-semibold">Ada Lovelace</Text>
      <Text>Writes the first programs for the Analytical Engine.</Text>
    </HoverCard>
  );
}
```

The trigger keeps its own role, presses and look: a view with `role="link"` and its own `onPress` still goes where it
goes when pressed, and the card adds a preview to it. The content is made each time the card opens, so it can load what it shows then. On
phones and tablets, where a press opens the card, the trigger tells screen readers whether its card is open. In a
[Toolbar](https://nsh.dev/versions/main/elements/toolbar.md) the trigger can be one of its items; what the card shows is not: its buttons and links keep
their own Tab stops and the toolbar's `disabled` leaves them as they are.

## Delays

`openDelay` keeps the card from flashing open as the pointer crosses the trigger on its way elsewhere; `closeDelay`
gives the pointer time to cross the gap between the trigger and the card. Both are milliseconds. The pointer and the
delays are followed natively, so resting on a trigger and moving between it and the card run none of your code until
the card opens or closes. An `openDelay` of `Infinity` leaves opening to the app (and to a press on a touch screen); a
`closeDelay` of `Infinity` leaves closing to Escape, a press outside and the app.

```tsx
<HoverCard openDelay={300} closeDelay={150} trigger={<Text>AAPL</Text>}>
  <Quote symbol="AAPL" />
</HoverCard>
```

## Open state

Without `open`, the card keeps its own state, starting from `defaultOpen`. With `open`, the app owns it: change it in
`onOpenChange({ open, reason })`, which reports every request to open or close with its reason: `"hover"` (the
pointer), `"focus"` (the keyboard focus), `"triggerPress"` (a press on a touch screen), `"pressOutside"` or
`"cancel"` (Escape or back).

```tsx
const open = signal(false);

<HoverCard open={open()} onOpenChange={(e) => open.set(e.open)} trigger={<Text>@ada</Text>}>
  <Profile id="ada" />
</HoverCard>
```

## Entrance and exit

A hover card comes and goes with your transitions, as a [Popover](https://nsh.dev/versions/main/elements/popover.md) does. `popupStartingClass` is the
popup's look in its first frame, and the `transition-*` classes of `popupClass` carry it to its own look.
`popupEndingClass` is its look once closed: the card stays, taking no pointer, while those transitions run, then goes,
and `onClose` follows. Resting on the trigger again while it goes takes it back. When the user asks for less motion, it
appears and goes at once.

```tsx
<HoverCard
  popupClass="rounded-xl bg-popover p-4 shadow-lg transition-all duration-150 ease-out"
  popupStartingClass="opacity-0 scale-95"
  popupEndingClass="opacity-0 scale-95"
  trigger={<Text>@ada</Text>}
>
  <Profile id="ada" />
</HoverCard>
```

It goes below the trigger by default (`placement`, `align`), on the other side when there is no room, and stays
inside the safe area. `onPosition({ placement, bounds, available })` says where it went.

## Props

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `open` | `.open(..)` | `boolean` | none | Open, controlled by the app. |
| `defaultOpen` | `.default_open(..)` | `boolean` | `false` | Open at first, without `open`. |
| `openDelay` | `.open_delay(..)` | `number` | `600` | Milliseconds the pointer rests on the trigger, or the focus stays on it, before it opens; `Infinity`: never by itself. |
| `closeDelay` | `.close_delay(..)` | `number` | `300` | Milliseconds the pointer is away from the trigger and the card, with the focus in neither, before it closes; `Infinity`: never by itself. |
| `placement` | `.placement(..)` | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` | The side of the trigger it goes on. |
| `align` | `.align(..)` | `"start" \| "center" \| "end"` | `"center"` | How it lines up with the trigger along that side. |
| `offset` | `.offset(..)` | `number` | `0` | The gap between the trigger and the card. |
| `margin` | `.margin(..)` | `number` | `0` | The distance it keeps from the edges of the safe area. |
| `popupClass`, `popupStyle` | `.popup_class(..)`, `.popup_style(..)` | `string`, `StyleProp<ViewStyle>` | none | The look of the popup, the card the content is in. |
| `popupStartingClass`, `popupStartingStyle` | `.popup_starting_class(..)`, `.popup_starting_style(..)` | `string`, `StyleProp<ViewStyle>` | none | The popup's look in its first frame, over its own: its transitions run from it. |
| `popupEndingClass`, `popupEndingStyle` | `.popup_ending_class(..)`, `.popup_ending_style(..)` | `string`, `StyleProp<ViewStyle>` | none | The popup's look once closed, over its own: it stays while its transitions run. |
| `trigger` | `.trigger(..)` | `JSX.Element` | none | What it previews; it is placed against it. |
| `children` | `.child(..)` | `JSX.Element` | none | The content, made each time it opens. |

## Events

| Event | Rust | Description |
|---|---|---|
| `onOpenChange` | `.on_open_change(\|e\| ..)` | It asks to open or close, with why: `"hover"`, `"focus"`, `"triggerPress"`, `"pressOutside"` or `"cancel"`. |
| `onOpen` | `.on_open(\|\| ..)` | It is shown. |
| `onClose` | `.on_close(\|\| ..)` | It is gone, after its exit; also when the app closed it. |
| `onPosition` | `.on_position(\|e\| ..)` | The popup was placed: `placement` (the side it went on), `bounds` (its frame), `available` (the room on that side). |

## Accessibility

A hover card adds to its trigger: the trigger keeps its role and label, and what it opens or does when pressed stays
the same. Keyboard users get the card when the focus rests on the trigger, and Escape closes it. The card takes no
focus of its own, so Tab moves on from the trigger as before. Links and buttons in the card take the focus as anywhere
else, and the card stays open while one of them has it; what matters in the card should also be reachable from the
page the trigger leads to.

Source: https://nsh.dev/versions/main/elements/hover-card

---

# Input

`Input` is a native text field: a UITextField (single line) or UITextView (multiline) on iOS and Mac Catalyst, an
EditText on Android. Typing, the caret, selection, autocorrection and autofill are the platform's own. Rust makes one
with `nsh_base::input()`, TSX with `<Input>` from `nsh/base`.

```rust
use nsh_base::input;
use nsh_core::prelude::*;

fn name_field() -> impl IntoElement {
    let name = signal(String::new());
    input()
        .value(name)
        .on_change(move |text: &str| name.set(text.to_string()))
        .placeholder("Your name")
        .auto_capitalize(AutoCapitalize::Words)
        .return_key_type(ReturnKeyType::Done)
        .text_base()
        .p_3()
        .border_1()
        .border_color(rgb(0xd0d7de))
        .rounded(px(8.0))
}
```

```tsx
import { signal } from "nsh";
import { Input } from "nsh/base";

function NameField() {
  const name = signal("");
  return (
    <Input
      value={name()}
      onChange={({ value }) => name.set(value)}
      placeholder="Your name"
      autoCapitalize="words"
      returnKeyType="done"
      style={{ fontSize: 16, padding: 12, borderWidth: 1, borderColor: "#d0d7de", borderRadius: 8 }}
    />
  );
}
```

With no width from its style or its parent, an input is as wide as twenty digits in its font, as an HTML `<input>` is: what it holds does not change its width.

## Controlled and uncontrolled

- **Controlled**: pass `value` and update it in `onChange`. The app can rewrite what the user typed (trim it, format
  it): the text shows the edit at once and is corrected when the new `value` arrives. Each native edit carries a count,
  and a `value` from the app is applied when it is based on the latest edit, so newer typing always wins over a slow
  update.
- **Uncontrolled**: pass `defaultValue` (`.default_value(..)`, or nothing) and read the text from `onChange` or
  `onSubmit`.

Rules that must hold while the user types are props, answered natively: `maxLength` limits the length and
`submitBehavior` decides what return does. See [forms and the keyboard](https://nsh.dev/versions/main/docs/forms-and-keyboard.md).

## Props

Besides the [common props](https://nsh.dev/versions/main/elements.md#common-props) (with `style` typed as `TextStyle`: font, color, alignment and the
view styles apply):

### Text

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `value` | `.value(..)` | `string` | | The text, controlled by the app. |
| `defaultValue` | `.default_value(..)` | `string` | | The initial text. |
| `placeholder` | `.placeholder(..)` | `string` | | Shown while the input is empty. |
| `multiline` | `.multiline(..)` | `boolean` | `false` | Several lines; return inserts a line break unless `submitBehavior` says otherwise. |
| `scrollbar` | `.scrollbar(..)` | `boolean \| ScrollbarTheme` | `true` | A multiline input's scroll bar: the platform's indicator, or the app's built-in bar once it set one ([Scrollbar](https://nsh.dev/versions/main/elements/scrollbar.md#built-in-bars)); an object is a theme of its own, `false` none. |
| `maxLength` | `.max_length(..)` | `number` | | The most characters the user can enter. |
| `readonly` | `.readonly(..)` | `boolean` | `false` | The user can select and copy the text but not change it. |
| `masked` | `.masked(..)` | `boolean` | `false` | The text is hidden (passwords). |
| `allowFontScaling` | | `boolean` | `true` | Follow the system text size. |
| `maxFontSizeMultiplier` | | `number` | `0` | The upper bound of the system scale (0 is none). |

### Keyboard

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `keyboardType` | `.keyboard_type(KeyboardType::Email)` | `"default" \| "number-pad" \| "decimal-pad" \| "numeric" \| "numbers-and-punctuation" \| "email-address" \| "phone-pad" \| "url"` | `"default"` | The keyboard layout ([the values](https://nsh.dev/versions/main/docs/forms-and-keyboard.md#keyboards-and-autofill); `numbers-and-punctuation` has a minus sign on iOS). |
| `returnKeyType` | `.return_key_type(ReturnKeyType::Next)` | `"default" \| "done" \| "go" \| "next" \| "search" \| "send"` | `"default"` | The label of the return key. |
| `autoCapitalize` | `.auto_capitalize(AutoCapitalize::None)` | `"none" \| "sentences" \| "words" \| "characters"` | `"sentences"` | Automatic capitalization. |
| `autoCorrect` | `.auto_correct(..)` | `boolean` | `true` | The system's corrections. |
| `autoComplete` | `.auto_fill(AutoFill::OneTimeCode)` | `AutoComplete \| TextContentType` | | What the input holds, for autofill on iOS, Android and the web: `"username"`, `"current-password"`, `"new-password"`, `"one-time-code"`, `"email"`, `"tel"`, `"postal-code"`, `"cc-number"`, `"off"`, … |
| `pasteBehavior` | `.paste_behavior(PasteBehavior::Report)` | `"insert" \| "report"` | `"insert"` | What a paste does: `"insert"` inserts the pasted text, `"report"` inserts nothing, for the app to handle what `onPaste` reports. Images and files are never inserted. |
| `submitBehavior` | `.submit_behavior(SubmitBehavior::Submit)` | `"submit" \| "blurAndSubmit" \| "newline"` | `"blurAndSubmit"` (single line), `"newline"` (multiline) | What return does: `"submit"` reports `onSubmit` and keeps the focus, `"blurAndSubmit"` also unfocuses, `"newline"` inserts a line break (multiline; a single line submits). A multiline input that submits still takes line breaks from Shift+Return or Option / Alt+Return on hardware keyboards. `"submit"` keeps the keyboard up (e.g. to send several messages). |
| `autoFocus` | `.auto_focus(..)` | `boolean` | `false` | Focused when it appears. |

### Caret and selection

| Prop | Rust | Type | Description |
|---|---|---|---|
| `caret` | `.caret(..)` | `boolean` | The caret is drawn (default `true`; `false` hides it). |
| `selectedRange` | `.selected_range((start, end))` | `{ start: number; end?: number }` | The controlled selection, in UTF-16 units; `end` defaults to `start` (a caret). |

The caret blinks while its window is shown and active. In GPUI windows on Linux it stays shown after ten seconds
without typing or moving it, as in GTK apps, so a focused field left alone costs no frames.

### Colors

The colors of the placeholder, the caret and the selection highlight are style keys, with their Tailwind classes, and
methods in Rust (UIKit tints the caret and the selection with one color, the caret's when set):

| Style key | Rust | Class | Description |
|---|---|---|---|
| `placeholderColor` | `.placeholder_color(..)` | `placeholder:text-*` | The placeholder's color. |
| `caretColor` | `.caret_color(..)` | `caret-*` | The caret's color. |
| `selectionColor` | `.selection_color(..)` | `selection:text-*` | The selection highlight's color. |

```rust
input()
    .placeholder("Search")
    .text_color(rgb(0x18181b))
    .placeholder_color(rgb(0x9ca3af))
    .caret_color(rgb(0x2563eb))
    .selection_color(rgb(0x93c5fd))
```

```tsx
<Input placeholder="Search" class="text-zinc-900 placeholder:text-zinc-400 selection:text-blue-600" />
<Input placeholder="Search" style={{ placeholderColor: "#9ca3af", caretColor: "#2563eb", selectionColor: "#93c5fd" }} />
```

### iOS

| `ios` key | Rust | Type | Description |
|---|---|---|---|
| `textContentType` | `.auto_fill(..)` | `AutoComplete \| TextContentType` | iOS's names for `autoComplete` (`"oneTimeCode"`, `"newPassword"`, …). |
| `inputAccessoryViewID` | `.input_accessory(id)` | `string` | The `nativeID` of an `InputAccessoryView` ([`InputAccessoryView`](https://nsh.dev/versions/main/modules/nsh-mobile.md#inputaccessoryview)) shown over the keyboard while the input has focus. |
| `keyboardAppearance` | `.keyboard_appearance(KeyboardAppearance::Dark)` | `"default" \| "light" \| "dark"` | The keyboard's look; `"default"` follows the system's appearance. Android's keyboards follow the system's theme. |

```rust
use nsh_core::element::AutoFill;

input().auto_fill(AutoFill::OneTimeCode).keyboard_type(KeyboardType::Number)
```

```tsx
<Input autoComplete="one-time-code" keyboardType="number-pad" ios={{ textContentType: "oneTimeCode" }} />
```

## Events

| Event | Rust | Payload | When |
|---|---|---|---|
| `onChange` | `.on_change(\|text: &str\| ..)` | `{ value }` | The user changed the text: `value` is the text now. |
| `onSubmit` | `.on_submit(\|text: &str\| ..)` | `{ text }` | The return key was pressed in an input that submits (single line, or `submitBehavior` `"submit"` / `"blurAndSubmit"`). |
| `onFocus` / `onBlur` | `.on_focus` / `.on_blur` | none | The input gained / lost focus. |
| `onSelectionChange` | `.on_selection_change(\|s: &Selection\| ..)` | `{ start, end }` | The caret or selection moved (UTF-16 units). |
| `onPaste` | `.on_paste(\|e: &PasteEvent\| ..)` | `{ text, html, files, uris }` | The user pasted: the text, its formatting as HTML (Linux, web), images (a screenshot) as `File`s, local files' `file:` URLs. Before the `onChange` of the text it inserts ([forms and keyboard](https://nsh.dev/versions/main/docs/forms-and-keyboard.md#pasting-images-and-files)). |
| `onCaretMove` | `.on_caret_move(\|e: &CaretEvent\| ..)` | `{ bounds, pageBounds }` | The caret moved, with the selection or as the text scrolled or wrapped: `bounds` is where it is in the input, `pageBounds` in the window, an `Overlay`'s `anchor` ([forms and keyboard](https://nsh.dev/versions/main/docs/forms-and-keyboard.md#the-caret)). |
| `onKeyPress` | `.on_key_press(\|key: &str\| ..)` | `{ key }` | Before the text changes: `key` is the typed text, `"Backspace"` or `"Enter"`. |
| `onContentSizeChange` | `.on_content_size_change(\|size: &Size<Points>\| ..)` | `{ size }` | The size of the text changed (at the input's width when multiline), as it is typed; an empty input reports one empty line, whatever its placeholder. |
| `onCompositionChange` | `.on_composition_change(\|e: &Composition\| ..)` | `{ composing, text }` | An input method's composition started, changed or ended: `text` is what is being composed (pinyin before a character is chosen, kana before conversion), `""` once it ends. The committed text reaches `onChange` before the end. |

A multiline input that grows with its text:

```rust
let height = signal(px(40.0));

input()
    .multiline(true)
    .on_content_size_change(move |size: &Size<Points>| {
        height.set(px((size.height.0 + 16.0).clamp(40.0, 120.0)));
    })
    .h(move || height.get())
    .px_3()
    .py_2()
```

```tsx
const height = signal(40);
<Input
  multiline
  onContentSizeChange={({ size }) => height.set(Math.min(120, Math.max(40, size.height + 16)))}
  style={{ height: height(), paddingHorizontal: 12, paddingVertical: 8 }}
/>;
```

## Ref methods

| Method | Rust | Description |
|---|---|---|
| `focus()` | `focus()` | Focuses the input and shows the keyboard. |
| `blur()` | `blur()` | Unfocuses it. |
| `setSelection(start, end?)` | `set_selection(start, end)` | Selects `start..end` (UTF-16 units); a caret when they are equal. |

Moving focus to the next field on return:

```rust
use nsh_core::element::AutoFill;

let password = element_ref();

view()
    .child(input().return_key_type(ReturnKeyType::Next).on_submit(move |_: &str| password.focus()))
    .child(input().element_ref(&password).masked(true).auto_fill(AutoFill::Password))
```

```tsx
let password!: InputRef;
<>
  <Input returnKeyType="next" onSubmit={() => password.focus()} />
  <Input ref={password} masked autoComplete="current-password" />
</>;
```

`Keyboard.dismiss()` from `nsh` (`dismiss_keyboard()` in Rust) hides the keyboard whichever input has it.

## Platform notes

- On macOS, single-line text, placeholders and carets share the native field's font metrics and are centered together
  inside the content box. `lineHeight` participates in layout; multiline editors also use it for paragraph spacing.
- Inputs inside a [scroll view](https://nsh.dev/versions/main/elements/scroll.md#keyboard) are kept clear of the keyboard natively. Elsewhere use
  a bottom padding or margin of [`env(keyboard-inset-height)`](https://nsh.dev/versions/main/elements/keyboard.md).
- `disabled` disables the input (no focus) as well as applying the disabled styles; a `readonly` input keeps its
  focus and selection.
- `inputAccessoryViewID` applies on iOS, where the keyboard has an accessory bar.

Source: https://nsh.dev/versions/main/elements/input

---

# Link

A link takes the user somewhere: a web page, another app (`mailto:`, `tel:`), or a screen of the app itself. It owns
the behavior: presses, Return and Space while it has the keyboard focus, the disabled state, and the link role for
screen readers. The look is the app's: a `Link` has no color, underline or label of its own, and its children are what
shows. `href` says where it goes; it is data for the opening, never text on screen.

```rust
use nsh_base::{link, theme};
use nsh_core::prelude::*;

fn docs() -> impl IntoElement {
    link()
        .href("https://example.com/docs")
        .text_color(move || theme().primary)
        .underline()
        .hover(|s| s.opacity(0.8))
        .focus(|s| s.rounded_sm().outline(px(2.0)).outline_color(move || theme().ring))
        .child(text("Read the docs"))
}
```

```tsx
import { mount, Text } from "nsh";
import { Link } from "nsh/base";

function App() {
  return (
    <Link
      href="https://example.com/docs"
      class="self-start text-primary underline hover:opacity-80 focus:rounded-sm focus:outline-2 focus:outline-ring"
    >
      <Text>Read the docs</Text>
    </Link>
  );
}

mount(App);
```

`Link` comes from [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md), the `nsh-base` crate in Rust. In Rust, `link()` makes one
with a setter per prop (`.href(..)`, `.open_with(..)`), a listener per event (`.on_open(..)`, `.on_press(..)`), the
typed style methods for the link and `.child(..)` for its content.

## Opening

A press, a click, or Return or Space on the focused link opens its `href`:

1. `onOpen({ href })` reports where it goes.
2. With `openWith="system"` (the default), a URL of another app or site, one with a scheme (`https:`, `mailto:`,
   `tel:`, a scheme another app registered), opens outside the app, as [`openUrl`](https://nsh.dev/versions/main/modules/nsh.md) opens it: the
   embedding app's router takes it first, then the system does. Any other `href`, a path of the app's (`/orders/42`)
   or `#anchor`, is reported and stays with the app.
3. `onPress()` reports the press.

With `openWith="app"`, the app's `onOpen` handler is how the link opens: a route of its own, a page in an in-app web
view, a confirmation first.

```tsx
import { Link } from "nsh/base";

<Link href={`/orders/${order.id}`} openWith="app" onOpen={({ href }) => router.push(href)} class="text-primary">
  <Text>Order #{order.id}</Text>
</Link>
```

Opening a URL outside the app takes the `openUrl` capability when the app declares capabilities in `nsh.json`
(`"openUrl": true`, or `{ "schemes": ["https", "mailto"] }`).

## Props

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `href` | `.href(..)` | `string` | none | Where the link goes: a URL, or a path of the app's. Reported with `onOpen`, never shown. |
| `openWith` | `.open_with(LinkOpenWith::App)` | `"system" \| "app"` (`LinkOpenWith`) | `"system"` | Who opens `href`: the system opens a URL of another app or site; `"app"` leaves it to `onOpen`. |
| `disabled` | `.disabled(..)` | `boolean` | `false` | No presses, no press feedback, no keyboard focus; `disabled:` styles apply, and screen readers say it is dimmed. |
| `current` | `.current(..)` | `boolean` | `false` | The link to the page the user is on, in a navigation or a breadcrumb: screen readers say it is the current page. |
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | none | What screen readers say, when the content says too little (an icon). |
| `hitSlop` | `.hit_slop(..)` | `number \| Partial<Edges>` | none | How far outside its bounds presses still count, in points: one number for every side, or the sides named. As a view's `hitSlop`. |
| `children` | `.child(..)` | `JSX.Element` | none | The content: a label, an icon, anything the app shows. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The link's look: its color, underline, padding; text properties pass to the texts inside it. |
| `activeStyle`, `hoverStyle`, `focusStyle`, `disabledStyle` | `.active(\|s\| ..)`, `.hover(..)`, `.focus(..)`, `.disabled_style(..)` | `StyleProp<ViewStyle>` | none | The link's style while pressed, hovered, focused or disabled, as the `<state>:` classes. |

## Events

| Event | Rust | Description |
|---|---|---|
| `onOpen` | `.on_open(\|href: &SharedString\| ..)` | The link opens `href`: with `openWith="app"` the handler opens it, with `"system"` it hears what the system was asked to open. It comes before `onPress`. |
| `onPress` | `.on_press(\|\| ..)` | The link was pressed: a tap, a click, or Return or Space while it has the keyboard focus. |

A disabled link reports nothing, and a press on it reaches no pressable view around it.

## States

The app styles each state with classes or style props:

```tsx
<Link
  href="https://example.com/changelog"
  class="self-start text-primary underline decoration-primary/40 transition-colors hover:decoration-primary active:opacity-70 focus:outline-2 focus:outline-ring disabled:text-muted-foreground disabled:no-underline"
>
  <Text>Changelog</Text>
</Link>
```

A visited link is the app's to remember: it keeps the hrefs it opened and styles those links by its own state.

```tsx
const visited = signal(new Set<string>());

<Link
  href={href}
  onOpen={({ href }) => visited.set(new Set(visited()).add(href))}
  class={visited().has(href) ? "text-violet-600 underline" : "text-primary underline"}
>
  <Text>{label}</Text>
</Link>
```

## Inside text

A `Link` inside a `<Text>` is an inline box of the paragraph, as every view inside a text is: it sits in the line,
keeps its own states, focus and role, and stays on one line. `align-text-bottom` places a link with one line of text on
the paragraph's baseline:

```tsx
<Text class="text-[15px] text-foreground">
  By continuing you accept the{" "}
  <Link href="https://example.com/terms" class="align-text-bottom">
    <Text class="text-[15px] text-primary underline">terms of service</Text>
  </Link>
  .
</Text>
```

A link that wraps with the paragraph's lines is a nested `<Text>` with `role="link"` and `onPress` (see
[Text](https://nsh.dev/versions/main/elements/text.md)), as [TextView](https://nsh.dev/versions/main/elements/text-view.md) draws the links of a document.

## A small target with hitSlop

A link can be smaller than a finger: an icon, a short word. `hitSlop` makes presses that land near it count, in points
past each side, without changing its layout or its look: one number for every side, or the sides named
(`{ top: 8, bottom: 8 }`), as a [view's `hitSlop`](https://nsh.dev/versions/main/elements.md#presses-and-feedback) takes them.

```tsx
<Link href="https://example.com/help" hitSlop={12} accessibilityLabel="Help" class="size-5 items-center justify-center">
  <Text>?</Text>
</Link>
```

## Accessibility

- A link is one element for screen readers, with the role `"link"`; its label is the text of its children, or
  `accessibilityLabel`. `href` stays data: screen readers say the label.
- `current` is said as the current page (ARIA's `aria-current="page"`), and `disabled` as the platform says a dimmed
  element.
- On macOS and the web a link is a stop of the keyboard focus: Tab reaches it, Return and Space open it, and `focus:`
  styles show where the focus is.

See [Accessibility](https://nsh.dev/versions/main/docs/accessibility.md) for labels, roles and announcements in general.

## Platform notes

- iOS, Android and Mac Catalyst: a press is a tap that ends on the link.
- Desktops (macOS, Windows, Linux, GPUI) and the web: a press is a click. On macOS and the web, Return and Space also
  open the link that has the keyboard focus.
- The web renders a link as an element with `role="link"`.
- Every platform draws what the app styles.

Source: https://nsh.dev/versions/main/elements/link

---

# Menu

A menu is a list of actions its trigger opens. One structure serves every device, presented as each expects:

- On the desktops and in desktop browsers, a popup at the trigger; a `Submenu` cascades beside its item as the
  pointer comes over it or presses it.
- On phones and tablets, a sheet at the bottom of the screen over a backdrop; a `Submenu` shows its items in the
  sheet in place of the menu's, with a row of yours leading back.

Choosing an item, a press outside, Escape, the Android back button and VoiceOver's escape gesture close it. `ContextMenu` is the same menu opened
by the secondary button (a right click) at the pointer, or by a finger held on its trigger on touch screens.

Return, Space or Down on the focused trigger opens the menu with the keyboard focus on its first enabled item, and Up
with it on its last; the arrow keys then move between the items. A press opens it with no item focused.
On the desktops and in a terminal, Right, Return or Space on a `Submenu`'s item opens it with the keyboard focus on
its first enabled item; Left on one of its items, or Escape, closes it and puts the focus back on its item.

```rust
use nsh_base::{menu, menu_item, menu_separator, submenu};
use nsh_core::prelude::*;

fn item(label: &'static str, on_select: impl Fn() + 'static) -> impl IntoElement {
    menu_item()
        .on_select(on_select)
        .px_3()
        .py_2()
        .rounded_md()
        .child(text(label))
}

fn file_menu() -> impl IntoElement {
    menu()
        .offset(px(4.0))
        .trigger(view().px_3().py_2().child(text("File")))
        .child(item("New", || log::info!("new")))
        .child(item("Open…", || log::info!("open")))
        .child(menu_separator().h(px(1.0)).my_1().bg(rgb(0xe5e7eb)))
        .child(
            submenu()
                .trigger(view().px_3().py_2().child(text("Share ›")))
                .back(view().px_3().py_2().child(text("‹ Back")))
                .child(item("Mail", || log::info!("mail")))
                .child(item("Copy link", || log::info!("link"))),
        )
}
```

```tsx
import { Text, View } from "nsh";
import { Menu, MenuItem, MenuSeparator, Submenu } from "nsh/base";

function Item(props: { label: string; onSelect: () => void }) {
  return (
    <MenuItem onSelect={props.onSelect} class="rounded-md px-3 py-2 hover:bg-gray-100 active:bg-gray-200">
      <Text>{props.label}</Text>
    </MenuItem>
  );
}

function FileMenu() {
  return (
    <Menu
      offset={4}
      popupClass="min-w-48 rounded-lg bg-white p-1 shadow-lg"
      backdropClass="bg-black/40"
      trigger={<View class="px-3 py-2"><Text>File</Text></View>}
    >
      <Item label="New" onSelect={newFile} />
      <Item label="Open…" onSelect={openFile} />
      <MenuSeparator class="my-1 h-px bg-gray-200" />
      <Submenu
        trigger={<View class="px-3 py-2"><Text>Share ›</Text></View>}
        back={<View class="px-3 py-2"><Text>‹ Back</Text></View>}
      >
        <Item label="Mail" onSelect={mail} />
        <Item label="Copy link" onSelect={copyLink} />
      </Submenu>
    </Menu>
  );
}
```

All five come from [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md). The items reach their menu on their own, so you arrange them
freely: groups in views, labels, items that come and go with `If`. `popupClass` styles the popup on desktops and the
sheet on phones; a style that differs between them can compare `platform.idiom` (`nsh`) with `"desktop"`.

## Menu bars

Menus whose triggers are items of one `Toolbar` form a menu bar: with one of its menus open, the pointer over another
menu's trigger opens that menu in its place, and the arrow keys move between the triggers.

```tsx
<Toolbar accessibilityLabel="Menu bar">
  <Menu trigger={<View><Text>File</Text></View>}>{/* … */}</Menu>
  <Menu trigger={<View><Text>Edit</Text></View>}>{/* … */}</Menu>
</Toolbar>
```

## Context menus

```tsx
import { ContextMenu, MenuItem } from "nsh/base";

<ContextMenu
  popupClass="min-w-40 rounded-lg bg-white p-1 shadow-lg"
  backdropClass="bg-black/40"
  trigger={<PhotoTile photo={photo} />}
>
  <MenuItem onSelect={() => share(photo)}><Text>Share</Text></MenuItem>
  <MenuItem onSelect={() => remove(photo)}><Text>Delete</Text></MenuItem>
</ContextMenu>
```

On the desktops the secondary button opens it where the pointer is. On touch screens a finger held on the trigger
opens it as a sheet; the trigger's own presses and the scroll views around it keep working, and moving the finger
cancels the hold.

## Checkable items

`checked` makes an item checkable: a setting the menu shows ("Show sidebar") or, with `role="menuitemradio"`, one
choice of a group ("Sort by"). The value is yours: choosing the item calls `onSelect`, you set the next value, and the
item shows it. While it is checked, its `checked:` classes and `checkedStyle` apply, and so do those of its
indicator: the part before its content (`indicatorClass`, `indicatorStyle`) around the mark you give it
(`indicator`). The mark is made once and kept; the indicator's `checked:` classes show and hide it, or the mark's own
`group-checked:` classes with `group` in `indicatorClass`. `closeOnSelect={false}` keeps the menu open, so a setting
shows its new value at once.

```rust
use nsh_base::{menu, menu_item};
use nsh_core::{element::StyleRefinement, prelude::*};

fn view_menu(sidebar: Signal<bool>, sort: Signal<&'static str>) -> impl IntoElement {
    // The indicator part shows the mark while the item is checked.
    let part = |s: StyleRefinement| s.w(px(16.0)).opacity(0.0).checked(|s| s.opacity(1.0));
    let by = move |label: &'static str| {
        menu_item()
            .role(AccessibilityRole::MenuItemRadio)
            .checked(move || Some(sort.get() == label))
            .indicator_style(part)
            .indicator(text("✓"))
            .on_select(move || sort.set(label))
            .flex_row()
            .gap_2()
            .px_3()
            .py_2()
            .child(text(label))
    };
    menu()
        .trigger(view().px_3().py_2().child(text("View")))
        .child(
            menu_item()
                .checked(move || Some(sidebar.get()))
                .close_on_select(false)
                .indicator_style(part)
                .indicator(text("✓"))
                .on_select(move || sidebar.set(!sidebar.get_untracked()))
                .flex_row()
                .gap_2()
                .px_3()
                .py_2()
                .child(text("Show sidebar")),
        )
        .child(by("Name"))
        .child(by("Date modified"))
}
```

```tsx
import { Text, View, signal } from "nsh";
import { Menu, MenuItem } from "nsh/base";

// The indicator part shows the mark while the item is checked.
const part = "w-4 opacity-0 transition-opacity checked:opacity-100";

function ViewMenu() {
  const sidebar = signal(true);
  const sort = signal("Name");
  return (
    <Menu popupClass="min-w-48 rounded-lg bg-white p-1 shadow-lg" trigger={<View class="px-3 py-2"><Text>View</Text></View>}>
      <MenuItem
        checked={sidebar()}
        closeOnSelect={false}
        indicatorClass={part}
        indicator={<Text>✓</Text>}
        onSelect={() => sidebar.set(!sidebar())}
        class="flex-row gap-2 rounded-md px-3 py-2 hover:bg-gray-100"
      >
        <Text>Show sidebar</Text>
      </MenuItem>
      <Each of={["Name", "Date modified", "Size"]}>
        {(by) => (
          <MenuItem
            role="menuitemradio"
            checked={sort() === by()}
            indicatorClass={part}
            indicator={<Text>✓</Text>}
            onSelect={() => sort.set(by())}
            class="flex-row gap-2 rounded-md px-3 py-2 hover:bg-gray-100 checked:font-semibold"
          >
            <Text>{by()}</Text>
          </MenuItem>
        )}
      </Each>
    </Menu>
  );
}
```

A mark at the trailing edge goes in the content instead, styled with `group-checked:` classes under `group` on the
item.

## Entrance and exit

On the desktops the popup comes and goes with your transitions, as a [Popover](https://nsh.dev/versions/main/elements/popover.md#entrance-and-exit)'s:
`popupStartingClass` is its look in its first frame, `popupEndingClass` its look once closed, which it keeps while the
`transition-*` classes of `popupClass` run, and `onClose` follows. Submenus take the same looks and close with their
menu. The sheet of phones slides in and out on its own.

```tsx
<Menu
  popupClass="min-w-40 rounded-lg bg-white p-1 shadow-lg transition-all duration-100"
  popupStartingClass="opacity-0 -translate-y-1"
  popupEndingClass="opacity-0"
  trigger={<Text>File</Text>}
>
  <MenuItem onSelect={newFile}><Text>New</Text></MenuItem>
</Menu>
```

## Open state

Without `open`, a menu keeps its own state (from `defaultOpen` for `Menu`). With `open`, the app owns it and changes
it in `onOpenChange({ open, reason })`: `"triggerPress"`, `"select"`, `"pressOutside"`, `"backdropPress"`, `"cancel"`,
`"contextMenu"` or `"longPress"`.

## Props

### Menu

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `open` | `.open(..)` | `boolean` | none | Open, controlled by the app. |
| `defaultOpen` | `.default_open(..)` | `boolean` | `false` | Open at first, without `open`. |
| `placement` | `.placement(..)` | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` | Desktops: the side of the trigger it goes on. |
| `align` | `.align(..)` | `"start" \| "center" \| "end"` | `"start"` | Desktops: how it lines up with the trigger. |
| `offset` | `.offset(..)` | `number` | `0` | Desktops: the gap between the trigger and the popup. |
| `margin` | `.margin(..)` | `number` | `0` | Desktops: the distance it keeps from the edges of the safe area. |
| `popupClass`, `popupStyle` | `.popup_class(..)`, `.popup_style(..)` | `string`, `StyleProp<ViewStyle>` | none | The popup (desktops) or the sheet (phones), and the submenus' popups. |
| `popupStartingClass`, `popupStartingStyle` | `.popup_starting_class(..)`, `.popup_starting_style(..)` | `string`, `StyleProp<ViewStyle>` | none | Desktops: the popups' look in their first frame, over their own. |
| `popupEndingClass`, `popupEndingStyle` | `.popup_ending_class(..)`, `.popup_ending_style(..)` | `string`, `StyleProp<ViewStyle>` | none | Desktops: the popups' look once closed, kept while their transitions run. |
| `backdropClass`, `backdropStyle` | `.backdrop_class(..)`, `.backdrop_style(..)` | `string`, `StyleProp<ViewStyle>` | none | Phones: the backdrop behind the sheet. |
| `trigger` | `.trigger(..)` | `JSX.Element` | none | What opens it when pressed. While the menu is open its `aria-expanded:` classes and `expandedStyle` apply. |
| `children` | `.child(..)` | `JSX.Element` | none | The items, made each time it opens. |

### ContextMenu

`open`, `popupClass` / `popupStyle`, the starting and ending looks, `backdropClass` / `backdropStyle`, `trigger` and
`children` as for `Menu`, and:

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `disabled` | `.disabled(..)` | `boolean` | `false` | The secondary button and held fingers do nothing. |
| `offset` | `.offset(..)` | `number` | `0` | Desktops: the gap between the pointer and the popup. |
| `margin` | `.margin(..)` | `number` | `0` | Desktops: the distance it keeps from the edges of the safe area. |

### MenuItem

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `disabled` | `.disabled(..)` | `boolean` | `false` | Not chosen; `disabled:` styles apply. |
| `checked` | `.checked(..)` | `boolean` | none | Checked or not, which makes it a checkable item; owned by the app. |
| `checkedStyle` | `.checked_style(..)` | `StyleProp<ViewStyle>` | none | Its style while checked, as `checked:` classes. |
| `role` | `.role(..)` | `AccessibilityRole` | `"menuitemcheckbox"` with `checked`, else `"menuitem"` | What it is for screen readers; `"menuitemradio"` for one choice of a group. |
| `indicatorClass`, `indicatorStyle` | `.indicator_class(..)`, `.indicator_style(..)` | `string`, `StyleProp<ViewStyle>` | none | The indicator, the part before its content; its `checked:` and `disabled:` classes follow the item. |
| `indicator` | `.indicator(..)` | `JSX.Element` | none | The mark inside the indicator. |
| `closeOnSelect` | `.close_on_select(..)` | `boolean` | `true` | Choosing it closes the menu. |
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | none | What screen readers say, when the content is not enough. |
| `children`, `class`, `style` | `.child(..)`, style methods | | none | Its content and look, with `hover:`, `active:` and `checked:` states. |

### Submenu

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `trigger` | `.trigger(..)` | `JSX.Element` | none | The item that opens it. |
| `back` | `.back(..)` | `JSX.Element` | none | Phones: the row above its items that returns to the items around it. |
| `disabled` | `.disabled(..)` | `boolean` | `false` | It does not open. |
| `offset` | `.offset(..)` | `number` | `0` | Desktops: the gap between the menu around it and its popup. |
| `children` | `.child(..)` | `JSX.Element` | none | Its items. |

`MenuSeparator` is a view you style (`class`, `style`), shown with the items of its level.

## Events

| Event | Rust | Description |
|---|---|---|
| `onOpenChange` (`Menu`, `ContextMenu`) | `.on_open_change(\|e\| ..)` | It opened or closed, with why. |
| `onOpen` (`Menu`, `ContextMenu`) | `.on_open(\|\| ..)` | It is shown; as a sheet, once it came in. |
| `onClose` (`Menu`, `ContextMenu`) | `.on_close(\|\| ..)` | It is gone: as a sheet once it went, as a popup after its exit. Also when the app closed it. |
| `onPosition` (`Menu`, `ContextMenu`) | `.on_position(\|e\| ..)` | Desktops: the popup was placed: `placement` (the side it went on), `bounds`, `available`. |
| `onCancel` (`Menu`, `ContextMenu`) | `.on_cancel(\|\| ..)` | The user tried to close it without choosing (Escape or back, a press outside or on the backdrop). |
| `onSelect` (`MenuItem`) | `.on_select(\|\| ..)` | The item was chosen; a checkable item asks for its other value. |

## Accessibility

The popup or sheet is a menu and its items menu items for screen readers; the trigger tells whether the menu is
expanded. A checkable item is a checkbox or radio menu item, read as checked or not checked; its indicator is part of
the item. In TSX the trigger is the element you pass, a `Button` or a view of your own: it takes the presses and the
expanded state itself, so its own `active:` classes and `activeStyle` show while it is pressed, and its own `onPress` runs too. Only the items of the level shown are on screen, so screen readers read what is there.

Source: https://nsh.dev/versions/main/elements/menu

---

# NavStack

A navigation stack shows one page at a time and keeps the pages below it: `UINavigationController` on iOS and Mac
Catalyst, with the system header and swipe back, and a stack of pages with a toolbar and predictive back on Android.
On the desktops (macOS, Windows, Linux, GPUI) and the web, each page shows the app's own header at its top, and the
back keys and the browser's back button pop the page. `NavStack` is the stack, `NavPage` one of its pages.

The stack owns the navigation behavior (transitions, the back gestures and buttons, the pages' state while they are
covered); the pages' content and the desktop header are the app's own.

```rust
use nsh_base::{button, nav_page, nav_stack};
use nsh_core::prelude::*;

/// A button with the app's look.
fn action(title: &'static str, on_press: impl Fn() + 'static) -> impl IntoElement {
    button()
        .on_press(on_press)
        .rounded_lg()
        .bg(rgb(0x2563eb))
        .px_4()
        .py_3()
        .child(text(title).text_color(white()).font_weight(FontWeight::SEMIBOLD))
}

/// The header on the desktops and the web, with a back button over the first page.
fn bar(title: impl Into<SharedString>, routes: Signal<Vec<u32>>) -> impl IntoElement {
    view()
        .flex_row()
        .items_center()
        .gap_3()
        .px_4()
        .py_3()
        .border_b_1()
        .border_color(rgb(0xe5e5e5))
        .child(when(
            move || !routes.with(Vec::is_empty),
            move || {
                action("Back", move || {
                    routes.update(|r| {
                        r.pop();
                    })
                })
            },
        ))
        .child(text(title.into()).text_lg().font_weight(FontWeight::SEMIBOLD))
}

fn app() -> impl IntoElement {
    // The messages pushed over the inbox, bottom to top.
    let routes = signal(Vec::<u32>::new());
    nav_stack()
        .flex_1()
        .child(
            nav_page()
                .title("Inbox")
                .header(bar("Inbox", routes))
                .child(view().flex_1().p_4().child(action("Open message 1", move || {
                    routes.update(|r| r.push(1))
                }))),
        )
        .child(each(
            move || routes.get(),
            |id: &u32| *id,
            move |id, depth| {
                let title: SharedString = format!("Message {}", id.get_untracked()).into();
                nav_page()
                    .title(title.clone())
                    .header(bar(title, routes))
                    // The user went back natively: this page and those above it are gone.
                    .on_dismiss(move || routes.update(|r| r.truncate(depth.get_untracked())))
                    .child(view().flex_1().p_4().child(text("The message.")))
            },
        ))
}
```

```tsx
import { mount, Text, View } from "nsh";
import { Button, createNavStack, NavPage, NavStack } from "nsh/base";

type Route = { name: "home" } | { name: "detail"; id: number };

const nav = createNavStack<Route>([{ name: "home" }]);

function Action(props: { title: string; onPress: () => void }) {
  return (
    <Button onPress={props.onPress} class="rounded-lg bg-blue-600 px-4 py-3 active:bg-blue-700">
      <Text class="text-center text-base font-semibold text-white">{props.title}</Text>
    </Button>
  );
}

function Bar(props: { title: string }) {
  return (
    <View class="flex-row items-center gap-3 border-b border-neutral-200 px-4 py-3">
      {nav.routes().length > 1 && <Action title="Back" onPress={() => nav.pop()} />}
      <Text class="text-lg font-semibold">{props.title}</Text>
    </View>
  );
}

function Home() {
  return (
    <NavPage title="Inbox" header={<Bar title="Inbox" />}>
      <View style={{ flex: 1, padding: 16 }}>
        <Action title="Open message 1" onPress={() => nav.push({ name: "detail", id: 1 })} />
      </View>
    </NavPage>
  );
}

function Detail(props: { id: number }) {
  const title = `Message ${props.id}`;
  return (
    <NavPage title={title} header={<Bar title={title} />}>
      <View style={{ flex: 1, padding: 16 }}>
        <Text>The message.</Text>
      </View>
    </NavPage>
  );
}

function App() {
  return (
    <NavStack state={nav} style={{ flex: 1 }}>
      {(route) => (route.name === "home" ? <Home /> : <Detail id={route.id} />)}
    </NavStack>
  );
}

mount(App);
```

On iOS and Android the page shows the system header with `title` and a back button; on the desktops and the web it
shows `header`. An app that targets only phones leaves `header` out; one that targets only desktops leaves out the
system header's options. The [Navigation guide](https://nsh.dev/versions/main/docs/navigation.md) walks through a whole app's navigation: the
stack's state, dialogs, the Android back button and tabs.

## How a stack works

- The stack's pages are **routes**: values of your choosing, from the bottom of the stack to the top. A route usually
  names the page and carries its parameters.
- In TSX the routes live in the state `createNavStack` makes. `NavStack` calls its child function once for each push
  and shows the result as a page. It keeps that page while its route is in the stack, so a page keeps its state
  (signals, scroll position, inputs) while other pages cover it.
- In Rust the stack's children are its pages: a `nav_page()` put into `nav_stack()` is pushed, and one left out is
  popped. Keep the routes in a signal and render the pages with `each(..)`, keyed by route, so that the pages below keep
  their state.
- Each push is a page of its own, the same route value pushed twice included.
- When the user leaves a page natively (the back button, swipe back, Android back, the desktops' back keys, the
  browser's back), the page goes. In TSX the stack removes its route from the state, so `nav.routes()` always matches
  what the user sees. In Rust the page reports `on_dismiss`, where you drop its route (and the routes above it).
- In TSX, a child function that returns something other than a `<NavPage>` gets a page with default options. Return
  a `<NavPage>` to set its header and other options.

## createNavStack

```ts
function createNavStack<R>(routes: R[]): NavStackState<R>
```

Creates the state of a stack that starts with `routes`, bottom to top. Create it once, for example at module level,
and pass it to `<NavStack state>`. Any code can import it to navigate.

| Member | Description |
|---|---|
| `routes: Accessor<readonly R[]>` | The routes, bottom to top. Reactive. |
| `push(route: R): void` | Pushes a page. |
| `pop(count?: number): void` | Pops `count` pages (default 1). At least one page always stays. |
| `popToRoot(): void` | Pops back to the first page. |
| `replace(route: R): void` | Replaces the top page. |
| `setRoutes(routes: R[]): void` | Replaces the pages; a route that stays (the same value) keeps its page and its state. |
| `remove(route: R): void` | Removes the topmost page of `route` (compared with `===`), wherever it is in the stack. |

In Rust the same operations are changes of your routes signal: `routes.update(|r| r.push(route))` pushes,
`r.pop()` pops, `r.truncate(1)` pops back to the first page you keep in it, and `routes.set(..)` replaces the pages.

```rust
routes.update(|r| r.push(7));
routes.update(|r| r.truncate(r.len().saturating_sub(2)));
routes.set(vec![1, 2]);
let depth = move || routes.with(Vec::len);
```

```tsx
nav.push({ name: "detail", id: 7 });
nav.pop(2);
nav.setRoutes([{ name: "home" }, { name: "detail", id: 1 }]);
const depth = () => nav.routes().length;
```

## NavStack props

| Prop | Rust | Type | Description |
|---|---|---|---|
| `state` | the pages are its children | `NavStackState<R>` | The state that holds the routes (`createNavStack`). Required. |
| `children` | `.child(..)` | `(route: R, index: Accessor<number>) => JSX.Element` | Renders a route. Return a `<NavPage>` for its options. Required. |
| `style`, `class` | style methods | | The stack's style; usually `flex: 1`. |
| `testID` | `.test_id(..)` | `string` | Finds the stack in tests and `nsh test --trace`. |

The TSX child function receives the route value itself and an accessor of its position in the stack.

## NavPage props

`NavPage` is one page of a stack. It holds the page's content, its `header` on the desktops and the web, and the
options of the system header on iOS and Android. In Rust, `nav_page()` returns the page and its builder methods are
the props' snake-case names.

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `header` | `.header(..)` | `JSX.Element` | none | Desktops and the web: the page's header, placed at the top of the page, as wide as the page and as tall as it lays out, with the content below it. |
| `title` | `.title(..)` | `string` | none | iOS and Android: the system header's title. |
| `headerVisible` | `.header_visible(..)` | `boolean` | `true` | iOS and Android: the system header shows. |
| `headerTransparent` | `.header_transparent(..)` | `boolean` | `false` | iOS and Android: the content extends under a transparent system header. |
| `hidesBottomBarWhenPushed` | `.hides_bottom_bar_when_pushed(..)` | `boolean` | `false` | iOS: the system tab bar leaves while this page is on top, moving in the transition — the same animation as the page, and the bar is never rebuilt; it comes back when the page pops. |
| `headerLargeTitle` | `.header_large_title(..)` | `boolean` | `false` | iOS: a large title that shrinks into the bar as the content scrolls; the content scrolls under the header. |
| `headerBackTitle` | `.header_back_title(..)` | `string` | none | iOS and Android: the label of the back button that leads back to this page (on Android, its description for screen readers). |
| `headerBackVisible` | `.header_back_visible(..)` | `boolean` | `true` | iOS and Android: the back button shows. |
| `headerLeft` | `.header_left(..)` | `JSX.Element` | none | iOS and Android: content at the leading edge of the system header, in place of the back button. |
| `headerRight` | `.header_right(..)` | `JSX.Element` | none | iOS and Android: content at the trailing edge of the system header. |
| `headerTitle` | `.header_title(..)` | `JSX.Element` | none | iOS and Android: content that replaces the title. |
| `headerStyle` | `.header_style(..)` | `{ backgroundColor?, color?, tintColor? }` | platform | iOS and Android: the system header's colors: its background, the title's (`color`) and the buttons' (`tintColor`). |
| `headerClass` | `.header_style_with(\|s\| ..)` | `string` | none | The same colors as classes: `bg-*`, `text-*` for the title, `tint-*` for the buttons (in Rust `.bg(..)`, `.text_color(..)`, `.tint_color(..)`, theme colors following the appearance). `headerStyle` wins over them. |
| `popOnBack` | `.pop_on_back(..)` | `boolean` | `true` | The back buttons and the swipe back pop the page. See [Leaving a page](#leaving-a-page). |
| `popOnSwipe` | `.pop_on_swipe(..)` | `boolean` | `true` | The interactive back gesture pops the page: iOS swipe back, Android predictive back that follows the finger. The back buttons pop either way. |
| `animation` | `.animation(..)` | `"default" \| "slide" \| "fade" \| "none"` | `"default"` | How the page enters and leaves. |
| `transitionShader` | `.transition_shader(TransitionShader::new(program))` | `{ source: string; uniforms?: Record<string, ShaderUniform>; duration?: number }` | none | The page enters and leaves through a WGSL shader in place of its `animation`: `shade(uv)` reads the page below as `sample_from` and this page as `sample_to` while `nsh.progress` runs from 0 to 1 over `duration` milliseconds (350 by default), and from 1 back to 0 as the page leaves. When the system asks for less motion, the page takes its own `animation`. See [Shader](https://nsh.dev/versions/main/elements/shader.md). |
| `statusBar` | `.status_bar(..)` | `{ foreground?, hidden?, animated? }` | none | iOS and Android: the status bar while the page is on top. See [Status bar](https://nsh.dev/versions/main/modules/nsh-base.md#status-bar). |
| `style`, `class` | style methods | | none | The page's style. |
| `children` | `.child(..)` | `JSX.Element` | none | The content. |
| `testID` | `.test_id(..)` | `string` | none | Finds the page in tests and `nsh test --trace`. |

## NavPage events

| Event | Rust | Description |
|---|---|---|
| `onBackPress` | `.on_back_press(..)` | The user pressed back on the page (the header's back button, Android back, Escape, Alt+Left or a mouse's back button on the desktops, the browser's back), whether or not `popOnBack` let it pop. |
| `onDismiss` | `.on_dismiss(..)` | The user popped the page (back button, swipe); its route is gone in TSX, and Rust drops it here. |

## Header slots

`header`, `headerLeft`, `headerRight` and `headerTitle` are slots: ordinary elements that read signals, handle presses
and update while the page is shown. `header` is the app's whole header on the desktops and the web; the other three
go into the system header on iOS and Android.

```rust
use nsh_base::nav_page;
use nsh_core::prelude::*;

fn profile(edit: impl Fn() + 'static) -> Screen {
    nav_page()
        .title("Profile")
        .header(profile_bar())
        .header_style_with(|s| s.bg(rgb(0x1a7f37)).text_color(white()).tint_color(white()))
        .header_right(text("Edit").text_color(white()).on_press(move || edit()))
        .child(scroll().flex_1())
}
```

```tsx
<NavPage
  title="Profile"
  header={<ProfileBar />}
  headerStyle={{ backgroundColor: "#1a7f37", color: "#ffffff", tintColor: "#ffffff" }}
  headerRight={<Text onPress={edit} style={{ color: "#ffffff", fontSize: 17 }}>Edit</Text>}
>
  <Scroll style={{ flex: 1 }}>…</Scroll>
</NavPage>
```

The page's content starts below the header: below an opaque system header on iOS and Android, below `header` on the
desktops and the web. With `headerTransparent`, `headerLargeTitle` or `headerVisible={false}`, it starts at the top of
the page on iOS and Android; use [`env(safe-area-inset-top)`](https://nsh.dev/versions/main/elements/safe-area.md) or `safeAreaInsets()` to keep it clear of the
header and the status bar.

On iOS, `headerVisible={false}` keeps swipe back enabled while `popOnSwipe` and `popOnBack` are true.
An accepted interactive back gesture ends editing as the transition starts, so the keyboard dismisses during the
drag. Cancelling the transition restores the same editor's focus when another control has not taken it.

```rust
nav_page()
    .title("Large title")
    .header_large_title(true)
    .child(scroll().flex_1())
```

```tsx
<NavPage title="Large title" headerLargeTitle>
  <Scroll style={{ flex: 1 }}>…</Scroll>
</NavPage>
```

## Leaving a page

`popOnBack={false}` keeps the user on a page, for example while a form has unsaved changes. While it is false, swipe
back is off and the back buttons and keys call `onBackPress` without popping. Ask the user, then pop yourself:

```rust
use nsh_base::{alert_dialog, nav_page};
use nsh_core::prelude::*;

fn edit_note(routes: Signal<Vec<u32>>) -> Screen {
    let note = signal(String::new());
    let confirm = move || {
        spawn(async move {
            let choice = alert_dialog()
                .title("Discard your changes?")
                .cancel("keep", "Keep editing")
                .destructive("discard", "Discard")
                .show()
                .await;
            if choice.is_ok_and(|r| r.action.as_deref() == Some("discard")) {
                routes.update(|r| {
                    r.pop();
                });
            }
        });
    };
    nav_page()
        .title("Edit")
        .pop_on_back(move || note.with(String::is_empty))
        .on_back_press(move || {
            if !note.with(String::is_empty) {
                confirm();
            }
        })
        .child(
            input()
                .value(note)
                .on_change(move |v: &str| note.set(v.to_owned()))
                .placeholder("A note"),
        )
}
```

```tsx
import { signal } from "nsh";
import { AlertDialog, NavPage, Input } from "nsh/base";

function EditNote() {
  const text = signal("");
  const confirm = async () => {
    const { action } = await AlertDialog.show({
      title: "Discard your changes?",
      actions: [
        { label: "Keep editing", role: "cancel", id: "keep" },
        { label: "Discard", role: "destructive", id: "discard" },
      ],
    });
    if (action === "discard") nav.pop();
  };
  return (
    <NavPage title="Edit" popOnBack={text().length === 0} onBackPress={() => text().length > 0 && confirm()}>
      <Input value={text()} onChange={({ value }) => text.set(value)} placeholder="A note" />
    </NavPage>
  );
}
```

> [!IMPORTANT]
> The system asks whether the user may go back on the main thread, at the moment the user acts, and the main thread
> never waits for JS or for your Rust code. So NSH answers from the `popOnBack` value already mounted. Set
> `popOnBack={false}` as soon as there is something to lose, before the user goes back.

`onBackPress` is called on every back press, also when the page pops, so it also tells you that the user went back.
To turn off only the swipe gesture and keep the back buttons, use `popOnSwipe={false}`. The confirmation itself is an
[AlertDialog](https://nsh.dev/versions/main/elements/alert-dialog.md).

## Platform notes

- **iOS**: `UINavigationController` with the system header, back button and swipe back; `headerLargeTitle` is UIKit's
  large title. Stack changes that arrive during a running transition are applied when it ends.
- **Android**: a stack with a toolbar. The system back button pops the top page, with predictive back on Android
  versions that have it; the up arrow's description for screen readers is the lower page's `headerBackTitle`, or the
  system's. See `BackHandler` in [`BackHandler`](https://nsh.dev/versions/main/modules/nsh-mobile.md#backhandler) to handle the back button yourself.
- **Mac Catalyst**: as on iOS.
- **Desktops (macOS, Windows, Linux, GPUI) and the web**: each page shows its `header` at the top and its content
  below it. Escape, Alt+Left and a mouse's back button go back on the desktops, the browser's back button on the web.

For content shown over the stack and its header, such as a sheet or a full-screen flow, use a
[Dialog](https://nsh.dev/versions/main/elements/dialog.md).

Source: https://nsh.dev/versions/main/elements/nav-stack

---

# NumberInput

A number input holds a number the user types or steps: a quantity, a price, a size. It owns its behavior: its field
takes a number, or the text on the way to one (`-`, `1.`), and refuses anything else, other keyboards' digits and signs
included; its buttons, Up and Down and a screen reader's increment and decrement step the number by `step`, keeping its
decimals, and stop at `min` and `max`; leaving the field holds a typed number to them. The look is the app's: a
`NumberInput` has no colors, sizes, borders, icons or strings of its own. It is made of the decrement button, the field
between the app's `prefix` and `suffix`, and the increment button (or the field between them and a column with both
buttons, `controlsRight`), and the app styles each part and fills the buttons.

```rust
use nsh_base::{number_input, theme};
use nsh_core::prelude::*;

fn tickets(count: Signal<Option<f64>>) -> impl IntoElement {
    number_input()
        .value(move || count.get())
        .min(1.0)
        .max(10.0)
        .accessibility_label("Tickets")
        .on_change(move |next: &Option<f64>| count.set(*next))
        .h(px(32.0))
        .flex_row()
        .rounded(px(8.0))
        .border_1()
        .border_color(move || theme().input)
        .input_style(|s| s.flex_1().text_center().text_color(move || theme().foreground))
        .decrement_button_style(|s| s.w(px(32.0)).items_center().justify_center())
        .increment_button_style(|s| s.w(px(32.0)).items_center().justify_center())
        .decrement_button(text("−"))
        .increment_button(text("+"))
}
```

```tsx
import { mount, signal, Text } from "nsh";
import { NumberInput } from "nsh/base";

function App() {
  const tickets = signal<number | null>(2);
  return (
    <NumberInput
      value={tickets()}
      onChange={({ value }) => tickets.set(value)}
      min={1}
      max={10}
      accessibilityLabel="Tickets"
      class="h-8 flex-row overflow-hidden rounded-lg border border-input bg-field focus-within:outline-2 focus-within:outline-ring"
      inputClass="flex-1 text-center text-foreground"
      decrementButtonClass="w-8 items-center justify-center enabled:hover:bg-accent active:bg-muted disabled:opacity-40"
      incrementButtonClass="w-8 items-center justify-center enabled:hover:bg-accent active:bg-muted disabled:opacity-40"
      decrementButton={<Text>−</Text>}
      incrementButton={<Text>+</Text>}
    />
  );
}

mount(App);
```

`NumberInput` comes from [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md), the `nsh-base` crate in Rust. In Rust, `number_input()`
makes one with a setter per prop (`.value(..)`, `.input_style(..)`), a listener method per event (`.on_change(..)`), the
typed style methods for the input itself, and `.prefix(..)` / `.suffix(..)` for what goes around the field. Its value is
an `Option<f64>`.

## Value

The value is a number, or `null` for an empty field. The app owns it with `value` and sets the one `onChange` reports,
as for every control of `nsh/base`; or it leaves the value to the input with `defaultValue`, and hears the changes all
the same.

The field's text and the value are kept apart where they must be, so the user can type freely:

- `onChange` reports the number the text reads as whenever that number changes: `null` while the text reads as none
  (empty, `-`, `.`); typing `1.` after `1`, or `1.50` after `1.5`, reports nothing.
- The text stays as the user types it while it reads as the value the input holds, so a controlled input that passes
  each reported value back keeps `1.` and `2.50`. A value the app sets that the input did not report shows in the
  field, as the shortest text that reads as it (`0.3`, `12`).
- While typing, a number may be outside `min` and `max` (1 on the way to 15 with `min={10}`), and is reported as typed.
  When the field is left, or on Return / Enter, it is held to the range and that is reported; a text that reads as no
  number stays as it is.
- A step (a button, a key, a screen reader's action) asks for the next value with `onChange`; with a controlled value
  the field moves when the app passes it back, keeping the step's decimals (`99.5` up to `max={100}` shows `100.0`), so
  an app that refuses a step keeps the field where it is. An edit the app refuses stays in the field while it edits, and
  goes when the field is left.

```tsx
const price = signal<number | null>(19.95);

<NumberInput
  value={price()}
  onChange={({ value }) => price.set(value)}
  onSubmit={({ value }) => save(value)}
  min={0}
  step={0.05}
  placeholder="Price"
  accessibilityLabel="Price"
/>;
```

The field takes:

- Digits, one decimal point and a sign first (`+` or `-`); a letter, a second point or sign, or a sign elsewhere is
  refused, and the field goes back to its text.
- Full-width digits, signs and point, the minus sign (U+2212) and the ideographic full stop (`。`), read as their ASCII
  forms, as Chinese and Japanese input methods type them.
- A comma as the decimal point while the text has no point (`3,25` is 3.25), as the decimal key of many languages'
  keyboards types it.

## Props

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `value` | `.value(..)` | `number \| null` | none | The value (controlled): a number, or `null` for an empty field. The app sets the one `onChange` reports. |
| `defaultValue` | `.default_value(..)` | `number \| null` | none | The value at first while `value` is not set; the input then keeps its own. |
| `min` | `.min(..)` | `number` | none | The smallest value: steps stop at it, a typed value below it is held to it when the field is left. |
| `max` | `.max(..)` | `number` | none | The largest value, as `min` from above; one below `min` is `min`. |
| `step` | `.step(..)` | `number` | `1` | How far a step goes (Page Up / Page Down: ten steps); one that is not a positive number is `1`. |
| `disabled` | `.disabled(..)` | `boolean` | `false` | No typing, steps or focus; `disabled:` classes apply to the input and its parts. |
| `readonly` | `.readonly(..)` | `boolean` | `false` | The text can be selected and copied but not changed, by typing or by steps; the buttons are disabled. |
| `placeholder` | `.placeholder(..)` | `string` | none | Shown while the field is empty. |
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | none | What screen readers say for the field, when no visible label names it. |
| `controlsRight` | `.controls_right(..)` | `boolean` | `false` | Both buttons in a column on the right of the field, the increment over the decrement. Read when the input is made. |
| `inputClass`, `inputStyle` | `.input_style(\|s\| ..)` | `string`, `StyleProp<InputStyle>` | none | The field: its box and its text (`color`, `fontSize`, `textAlign`, `placeholderColor`, `caretColor`). |
| `decrementButtonClass`, `decrementButtonStyle` | `.decrement_button_style(\|s\| ..)` | `string`, `StyleProp<ViewStyle>` | none | The decrement button. |
| `incrementButtonClass`, `incrementButtonStyle` | `.increment_button_style(\|s\| ..)` | `string`, `StyleProp<ViewStyle>` | none | The increment button. |
| `decrementButton`, `incrementButton` | `.decrement_button(..)`, `.increment_button(..)` | `JSX.Element` | none | The content of the buttons: a sign, an icon. |
| `controlsClass`, `controlsStyle` | `.controls_style(\|s\| ..)` | `string`, `StyleProp<ViewStyle>` | none | The column that holds both buttons with `controlsRight`. |
| `prefix` | `.prefix(..)` | `JSX.Element` | none | What goes before the field, after the button on its left: a currency sign, an icon. |
| `suffix` | `.suffix(..)` | `JSX.Element` | none | What follows the field, before the buttons on its right: a unit, a currency. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The input itself: the row around the field and the buttons. |

## Events

| Event | Rust | Payload | When |
|---|---|---|---|
| `onChange` | `.on_change(\|value: &Option<f64>\| ..)` | `{ value: number \| null }` | The number the field reads as changed (typing, a step, a screen reader's increment or decrement, the field left with a value out of range). |
| `onSubmit` | `.on_submit(\|value: &Option<f64>\| ..)` | `{ value: number \| null }` | Return / Enter in the field: the value, held to `min` and `max`. |
| `onFocus` | `.on_focus(..)` | none | The field took the keyboard focus. |
| `onBlur` | `.on_blur(..)` | none | The field lost the keyboard focus (its value held to `min` and `max` first). |

## Parts

| Part | Inside | Styled with |
|---|---|---|
| The input | | `class`, `style` |
| The decrement button | the input, first (with `controlsRight`: the controls column, second) | `decrementButtonClass`, `decrementButtonStyle`; its content `decrementButton` |
| The field | the input | `inputClass`, `inputStyle` |
| The prefix | the input, before the field | its own elements (`prefix`) |
| The suffix | the input, after the field | its own elements (`suffix`) |
| The increment button | the input, last (with `controlsRight`: the controls column, first) | `incrementButtonClass`, `incrementButtonStyle`; its content `incrementButton` |
| The controls column | the input, last, with `controlsRight` | `controlsClass`, `controlsStyle` |

The input is a row the app lays out: `flex-row` on `class`, and `flex-1` on the field to give it the room the buttons
leave. States the parts show:

- The input: `focus-within:` while its field edits (a ring around the whole input), `disabled:`.
- The field: `focus:` while it edits, `disabled:`.
- A button: `hover:` under the pointer, `active:` while pressed, `disabled:` while the input is disabled or read-only and
  where a step would do nothing (the decrement at `min`, the increment at `max`). Put the hover behind `enabled:`
  (`enabled:hover:bg-accent`) so a disabled button does not light up.

Motion of the states is the app's choice (`transition-colors`), and `motion-reduce:` keeps it still for people who ask
for less motion.

## Keyboard

While the field edits, the input takes WAI-ARIA's spin button keys, which repeat while held:

| Key | Does |
|---|---|
| Up | One step up. |
| Down | One step down. |
| Page Up, Page Down | Ten steps up or down. |

Home and End stay the field's: they move the caret in the text. The buttons are not stops of the keyboard focus: Tab
goes from the field to what follows the input, and a press on a button leaves the focus in the field (on the desktops
a press moves the focus to the field when it was elsewhere; on touch screens it leaves it, so no keyboard comes up).

## Accessibility

- The field is a spin button (`"spinbutton"`) with its label, its value (the number it reads as, between `min` and
  `max`) and its text.
- A screen reader's increment and decrement actions (VoiceOver's swipe up and down) step it, as Up and Down do.
- The buttons are hidden from screen readers, as a browser's number field's are: the field's own increment and
  decrement step it.
- While `disabled`, screen readers say the field is dimmed.

See [Accessibility](https://nsh.dev/versions/main/docs/accessibility.md) for labels, roles and actions in general.

## Platform notes

- The field is the platform's text field ([Input](https://nsh.dev/versions/main/elements/input.md)): the keyboard, the caret, selection, copy and paste,
  input methods are the system's. Phones show a decimal keyboard, with a sign when `min` is below 0 or unset.
- Every platform draws what the app styles. Up / Down and Page Up / Page Down reach the input from a hardware keyboard
  on every platform.

Source: https://nsh.dev/versions/main/elements/number-input

---

# OtpInput

A one-time-code input takes a fixed number of digits (a verification code from a text message, an authenticator's
code) and shows them in cells. It owns the behavior: one native text field, transparent and over the cells, takes the
keyboard, so typing, input methods, paste, the number pad and the system's code autofill (iOS's "From Messages",
Android's SMS suggestions) are the platform's own, and screen readers find one text field. Digits only go in, up to
`length`; Backspace removes the last one, and `onComplete` tells when the code is full. The look is the app's: an
`OtpInput` has no colors, sizes, borders or label of its own. Its parts are the cells, the groups they are split into
and a caret, and the app styles each.

```rust
use nsh_base::{OtpInputCompleteEvent, otp_input, theme};
use nsh_core::prelude::*;

fn verification(verify: impl Fn(&str) + 'static) -> impl IntoElement {
    let code = signal(SharedString::default());
    otp_input()
        .length(6)
        .groups(2)
        .value(move || Some(code.get()))
        .on_change(move |next: &SharedString| code.set(next.clone()))
        .on_complete(move |e: &OtpInputCompleteEvent| verify(&e.value))
        .accessibility_label("Verification code, 6 digits")
        .flex_row()
        .gap_3()
        .group_style(|s| s.flex_row().gap_2())
        .cell_style(|s| {
            s.w(px(40.0))
                .h(px(48.0))
                .items_center()
                .justify_center()
                .rounded(px(8.0))
                .border_1()
                .border_color(move || theme().input)
                .text_xl()
        })
        // The cell that takes the next digit, while the code has the focus,
        // and the cells that hold a digit.
        .cell_class("focus:border-ring data-filled:bg-muted")
        .caret_style(|s| s.w(px(2.0)).h(px(24.0)).bg(move || theme().foreground))
}
```

```tsx
import { mount, signal } from "nsh";
import { OtpInput } from "nsh/base";

function App() {
  const code = signal("");
  const verify = (value: string) => console.log(`checking ${value}`);
  return (
    <OtpInput
      length={6}
      groups={2}
      value={code()}
      onChange={({ value }) => code.set(value)}
      onComplete={({ value }) => verify(value)}
      accessibilityLabel="Verification code, 6 digits"
      class="flex-row gap-3"
      groupClass="flex-row gap-2"
      cellClass="w-10 h-12 items-center justify-center rounded-lg border border-input text-xl focus:border-ring data-filled:bg-muted"
      caretClass="w-0.5 h-6 bg-foreground"
    />
  );
}

mount(App);
```

`OtpInput` comes from [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md), the `nsh-base` crate in Rust. In Rust, `otp_input()`
makes one with a setter per prop (`.length(..)`, `.cell_style(..)`), a listener method per event (`.on_complete(..)`)
and the typed style methods for the input itself.

## The code

- **Controlled**: pass `value` and set it in `onChange`. The cells show the `value` the app passes, as it is; a value
  the app sets (clearing the code after a wrong one) is never reported.
- **Uncontrolled**: pass `defaultValue` (or nothing), and read the code from `onChange` and `onComplete`.

What the user does is read from the field, with the caret always at its end:

| The user | The code |
|---|---|
| Types a digit | It is added at the end while the code is shorter than `length`; once full, nothing changes. |
| Types a full-width digit (`０`–`９`, an East Asian input method's) | The ASCII digit is added. |
| Types anything else | Nothing changes; the field drops it. |
| Presses Backspace | The last digit is removed. |
| Pastes, or the system autofills a code | Its digits are added the same way; text with `length` digits or more (`123-456`, a message's code) replaces the code with its first `length` digits. |

`onChange` reports each change with the new code, and `onComplete` follows it when the change filled the last cell,
so the app verifies the code there.

## Props

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `length` | `.length(..)` | `number` | required | How many digits the code has: one cell each. |
| `value` | `.value(..)` | `string` | none | The code, controlled by the app (shown as it is). Without it the input keeps its own. |
| `defaultValue` | `.default_value(..)` | `string` | none | The code at first, while `value` is not set. |
| `masked` | `.masked(..)` | `boolean` | `false` | Filled cells show a bullet instead of their digit, and the field is a secure one: screen readers do not read the code, and the system keeps it out of its suggestions. |
| `disabled` | `.disabled(..)` | `boolean` | `false` | No focus and no editing; `disabled:` styles apply to the input and its parts, and screen readers say it is dimmed. |
| `groups` | `.groups(..)` | `number` | `1` | How many groups the cells are split into, as evenly as they go (3 + 3 for six digits in two); at least one, at most one per cell. |
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | none | What screen readers say for the field: what the code is for and how many digits it has. |
| `cellClass`, `cellStyle` | `.cell_class(..)`, `.cell_style(\|s\| ..)` | `string`, `StyleProp<TextStyle>` | none | Each cell: its size, border and text (`color`, `fontSize`, which its digit inherits); `focus:` and `data-filled:` style its states (see Parts). |
| `groupClass`, `groupStyle` | `.group_class(..)`, `.group_style(\|s\| ..)` | `string`, `StyleProp<ViewStyle>` | none | Each group of cells (`flex-row gap-2`). |
| `caretClass`, `caretStyle` | `.caret_class(..)`, `.caret_style(\|s\| ..)` | `string`, `StyleProp<ViewStyle>` | none | The caret: its width, height and color. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The input itself: the row (or column) around its groups. |

## Events

| Event | Rust | Payload | When |
|---|---|---|---|
| `onChange` | `.on_change(\|value: &SharedString\| ..)` | `(e: { value: string })` | The user changed the code: typed, deleted, pasted or autofilled. |
| `onComplete` | `.on_complete(\|e: &OtpInputCompleteEvent\| ..)` | `{ value }` | The user's change filled the last cell, after its `onChange`. |
| `onFocus` / `onBlur` | `.on_focus` / `.on_blur` | none | The input took / lost the keyboard focus. |

## Ref methods

| Method | Rust | Description |
|---|---|---|
| `focus()` | `focus()` (`OtpInputApi`) | Takes the keyboard focus and shows the software keyboard, as a press on the input does. |

## Parts

| Part | Inside | Styled with |
|---|---|---|
| The input | | `class`, `style` |
| A group | the input, one per group | `groupClass`, `groupStyle`; `disabled:` follows the input |
| A cell | its group, one per digit | `cellClass`, `cellStyle`; `focus:` on the cell that takes the next digit while the input has the focus, `data-filled:` on each cell that holds a digit, `disabled:` follows the input |
| The digit | a filled cell | the cell's text styles (`text-xl`, `font-semibold`); `•` while `masked` |
| The caret | the empty cell that takes the next digit, while the input has the focus | `caretClass`, `caretStyle` |

The cell that takes the next digit is the one after the last digit, or the last cell once the code is full. The
caret blinks as a text field's does (half a second on, half off, and steady for a moment after each edit), by its
opacity, natively, while it keeps its place in the layout; with reduced motion it stays still. A press anywhere on the input focuses it: the field lies over the cells.

A cell that holds a digit, masked or not, has the attribute `data-filled`, so `data-filled:` classes style the cells
the user has filled (a stronger border, a fill: `data-filled:border-foreground data-filled:bg-muted`), as shadcn/ui
writes its states. With `group` in `cellClass`, `group-data-filled:` classes style what is inside a filled cell, its
digit. The cells change their classes, never their content, so a key restyles one cell and draws nothing again.

## Accessibility

- Screen readers find one text field, named by `accessibilityLabel` (say what the code is for and its length:
  "Verification code, 6 digits") with the code as its value; the cells are hidden from them. While `masked` the
  field is a secure one, so the code is not read aloud.
- The keyboard is the platform's: the number pad on phones, any keyboard on desktops (digits only go in), and
  Backspace. Tab reaches the input as any text field.
- While `disabled` it takes no focus, and screen readers say it is dimmed.

See [Accessibility](https://nsh.dev/versions/main/docs/accessibility.md) for labels, roles and announcements in general.

## Platform notes

- iOS: the field is a code field (`textContentType` `oneTimeCode`), so the QuickType bar offers a code from Messages
  or Mail; the number pad comes up. A `masked` field starts over when typed in again after it lost the focus, as
  iOS's secure fields do.
- Android: `autofillHints` `smsOTPCode` lets the keyboard and the autofill service offer the code of a text message;
  the number keyboard comes up.
- macOS, Windows, Linux and the web: typing and paste go to the field (in the browser, with `inputmode="numeric"`
  for a phone's number keyboard), and the I-beam pointer shows over the cells.

Source: https://nsh.dev/versions/main/elements/otp-input

---

# Pagination

A pagination moves among the pages of a set: search results, the rows of a table, an archive. It shows Previous, the
pages around the current one (the first and the last always, an ellipsis for each run left out), the app's children and
Next. It owns the behavior: which pages show, presses, the keyboard, Previous and Next disabled at the ends, the
navigation landmark and the current page for screen readers. The look is the app's: the items have no color, size or
label of their own, and the app styles them or draws them.

```rust
use nsh_base::{pagination, theme};
use nsh_core::prelude::*;

fn results() -> impl IntoElement {
    let page = signal(1u32);
    pagination()
        .page(move || page.get())
        .total_pages(24)
        .accessibility_label("Search results")
        .previous_accessibility_label("Previous")
        .next_accessibility_label("Next")
        .item_class("min-w-9 h-9 px-2 items-center justify-center rounded-md hover:bg-accent selected:bg-primary selected:text-primary-foreground disabled:opacity-50")
        .gap_1()
        .on_change(move |p: &u32| page.set(*p))
}
```

```tsx
import { mount, signal } from "nsh";
import { Pagination } from "nsh/base";

function App() {
  const page = signal(1);
  return (
    <Pagination
      page={page()}
      totalPages={24}
      accessibilityLabel="Search results"
      previousAccessibilityLabel="Previous"
      nextAccessibilityLabel="Next"
      class="gap-1"
      itemClass="min-w-9 h-9 px-2 items-center justify-center rounded-md hover:bg-accent selected:bg-primary selected:text-primary-foreground disabled:opacity-50"
      onChange={({ page: next }) => page.set(next)}
    />
  );
}

mount(App);
```

`Pagination` comes from [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md), the `nsh-base` crate in Rust. In Rust,
`pagination()` makes one with a setter per prop (`.page(..)`, `.total_pages(..)`), `.on_change(..)` for the page the
user picks, the typed style methods for the row and `.child(..)` for the app's content.

## The page

The page is the app's: `page` is the current one, from 1, and `onChange({ page })` reports the page the user picked
with a press on a page, on Previous or on Next. The app sets it, loads that page and shows its rows. `totalPages` is
how many there are; a `page` past the last shows the last. The current page reports nothing when pressed, and neither
do Previous on the first page and Next on the last.

## The pages shown

With `visiblePages` (at least 5, the default) the row shows every page while they fit. Past that it shows the first and
the last page, the current one with as many pages on each side as fit, `(visiblePages - 3) / 2`, and an ellipsis for
each run of pages left out:

| `page` of 20, `visiblePages={7}` | Shown |
|---|---|
| 1 | `1 2 3 4 5 … 20` |
| 6 | `1 … 4 5 6 7 8 … 20` |
| 20 | `1 … 16 17 18 19 20` |

Ten thousand pages show the same seven items. An odd `visiblePages` centers the current page.

## Items

Each item takes the app's `itemClass` and `itemStyle`: the current page is `selected:`, an item that takes no press
`disabled:`, the item with the keyboard focus `focus:`. The row is the app's to lay out with `class` (a row by
default; `gap-*`, `justify-*`).

Without `renderItem` a page shows its number, an ellipsis `…`, and Previous and Next their accessibility labels (`‹` and
`›` without them). `renderItem` draws each item's content from a `PaginationItemState`:

| Field | Type | Description |
|---|---|---|
| `kind` | `"previous" \| "page" \| "ellipsis" \| "next"` | What the item is. |
| `page` | `number` | A page's number; the page Previous or Next goes to (the current one at the ends); an ellipsis's first hidden page. |
| `start`, `end` | `number` | An ellipsis's hidden pages: `start` included, `end` (the next page shown) not. |
| `current` | `boolean` | The current page. |
| `disabled` | `boolean` | It takes no press: Previous on the first page, Next on the last, everything of a disabled pagination. |

```tsx
<Pagination
  page={page()}
  totalPages={pages()}
  previousAccessibilityLabel="Previous page"
  nextAccessibilityLabel="Next page"
  itemClass="size-9 items-center justify-center rounded-md selected:bg-primary"
  renderItem={(item) =>
    item.kind === "previous" ? <Icon name="chevron-left" /> :
    item.kind === "next" ? <Icon name="chevron-right" /> :
    item.kind === "ellipsis" ? <JumpMenu from={item.start!} to={item.end!} onPick={(p) => page.set(p)} /> :
    <Text class={item.current ? "font-semibold text-primary-foreground" : "text-foreground"}>{item.page}</Text>
  }
  onChange={({ page: next }) => page.set(next)}
/>
```

An ellipsis takes no press of its own: what it does is the app's. A `Menu` drawn in it lists the pages it hides, as
`JumpMenu` above does.

## Compact

`compact` shows Previous, the children and Next only: a pager for a narrow screen, the page told in the children.

```tsx
<Pagination compact page={page()} totalPages={12} onChange={({ page: next }) => page.set(next)} class="items-center gap-3">
  <Text class="text-sm text-muted-foreground">{`${page()} of 12`}</Text>
</Pagination>
```

The children sit after the pages and before Next in either form: a page count, a field to go to a page.

## Props

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `page` | `.page(..)` | `number` | required | The current page, from 1; the app sets it in `onChange`. |
| `totalPages` | `.total_pages(..)` | `number` | required | How many pages there are, at least 1. |
| `visiblePages` | `.visible_pages(..)` | `number` | `5` | The most pages shown at once, the first and the last included; at least 5. |
| `compact` | `.compact(..)` | `boolean` | `false` | Previous, the children and Next only. |
| `disabled` | `.disabled(..)` | `boolean` | `false` | No item takes a press or the keyboard focus; `disabled:` styles apply, and screen readers say they are dimmed. |
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | none | What screen readers call the navigation: what it pages through. |
| `previousAccessibilityLabel`, `nextAccessibilityLabel` | `.previous_accessibility_label(..)`, `.next_accessibility_label(..)` | `string` | none | What screen readers say for Previous and Next, and their content without `renderItem`. |
| `itemClass`, `itemStyle` | `.item_class(..)`, `.item_style(\|s\| ..)` | `string`, `StyleProp<TextStyle>` | none | Each item's look: `selected:` on the current page, `disabled:`, `focus:`; text styles pass to its content. |
| `renderItem` | `.render_item(\|s: &PaginationItemState\| ..)` | `(item: PaginationItemState) => JSX.Element` | none | Draws each item's content from its state. |
| `children` | `.child(..)` | `JSX.Element` | none | The app's content after the pages, before Next. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The row's look and layout. |

## Events

| Event | Rust | Description |
|---|---|---|
| `onChange` | `.on_change(\|page: &u32\| ..)` | `{ page }`: the page the user picked with a page, Previous or Next. The current page is never reported. |

## Motion

The current page moves from item to item as the app's `selected:` classes say: `transition-colors` on `itemClass` fades
the highlight from the page left to the page reached. A page change keeps every item in place and changes what the items
show, so the row never flickers; the app's transitions stand still with reduced motion (`motion-reduce:transition-none`).

## Accessibility

- The row is a navigation landmark named by `accessibilityLabel`.
- Each page, Previous and Next is a button. The current page is said as the current page (ARIA's
  `aria-current="page"`) and is selected; Previous on the first page and Next on the last are dimmed.
- On macOS and the web each page, Previous and Next is a stop of the keyboard focus, and Return and Space press it. A
  page pressed from the keyboard keeps the focus once the app shows it, wherever it lands in the row, and so does the
  first or the last page when Previous or Next reaches it.

See [Accessibility](https://nsh.dev/versions/main/docs/accessibility.md) for labels, roles and announcements in general.

## Platform notes

- iOS, Android and Mac Catalyst: a press is a tap that ends on an item.
- Desktops (macOS, Windows, Linux, GPUI) and the web: a press is a click; on macOS and the web, Tab reaches the items.
- Every platform draws what the app styles.

Source: https://nsh.dev/versions/main/elements/pagination

---

# Plot

A plot is the frame of a chart: the rows of data it shows, the scales of its x and y axes, the pointer over it and its
motion. Its marks draw what it holds: a `Line` through a series, an `Area` between a series and a baseline, a `Bar`
per row in the bands of a band scale, a `Rule` per row from a start to an end (a candle's wick), a `Dot` per row where two of its values meet (a scatter's points, a bubble chart's bubbles), a `Cell` per row in the bands of two categories, colored by its value (a heatmap), a `Grid` of lines across, a `Pie` of the rows' shares (a donut with a hole), an
`Arc` between two angles, and a `RadialLine` around the center with the rings and spokes of a `RadialGrid` behind it (a
radar), a `Sankey` of flows between the rows, and a `Treemap` of nested rectangles, each leaf's area its value (a market map); a `PlotAxis` labels an edge with the ticks of its scale, and a `PlotLabel` writes texts at
points of the scales. Each mark is one canvas filling the plot, drawn natively from the rows: the app's rows are read once when
it sets them, then scaled, recorded and drawn in Rust, so a chart of a thousand points runs no JS per point. The pointer
is followed in Rust too: the hover's cross line, dots and tooltip move and fade on the platform's animator, and the app
hears of a new row, nothing more. The look is the app's: marks paint with CSS's paint properties of SVG shapes
(`stroke-*`, `fill-*`), `currentColor` where none is set, an area or a bar shows a background (a gradient,
`bg-linear-*`) inside its shape, and the hover's parts (each mark's dot among them) and the axes' labels, tick marks and
lines are the app's to style and fill.

```rust
use nsh_base::{
    plot::{area, grid, line, plot},
    theme,
};
use nsh_core::{element::{RowAccessor, Rows}, prelude::*};

fn week(visitors: Vec<f64>, hovered: Signal<Option<u32>>) -> impl IntoElement {
    let rows = Rows::from_columns(visitors.len(), [("visitors".into(), visitors)]);
    plot()
        .data(rows)
        .y(RowAccessor::key("visitors"))
        .accessibility_label("Visitors per day")
        .h(px(160.0))
        .on_hover_change(move |index: &Option<u32>| hovered.set(*index))
        .child(grid().y(vec![0.0, 1500.0, 3000.0]).stroke_color(move || theme().border))
        .child(area().fill_color(move || theme().chart_1.opacity(0.2)))
        .child(line().stroke_color(move || theme().chart_1).stroke_width(px(2.0)))
}
```

```tsx
import { mount, signal, Text, View } from "nsh";
import { Area, Grid, Line, Plot } from "nsh/base/plot";

const rows = [
  { day: "Mon", visitors: 1820 },
  { day: "Tue", visitors: 2140 },
  { day: "Wed", visitors: 1960 },
  { day: "Thu", visitors: 2480 },
  { day: "Fri", visitors: 2310 },
];

function App() {
  const hovered = signal<number | null>(null);
  return (
    <View class="gap-2 p-4">
      <Text class="text-sm text-muted-foreground tabular-nums">
        {hovered() == null ? "Visitors" : `${rows[hovered()!].day}: ${rows[hovered()!].visitors}`}
      </Text>
      <Plot
        data={rows}
        y="visitors"
        yScale={{ type: "linear", domain: [0, 3000] }}
        accessibilityLabel="Visitors per day, highest on Thursday"
        onHoverChange={({ index }) => hovered.set(index)}
        crossLineClass="w-px h-full bg-border"
        dotClass="size-2.5 rounded-full border-2 border-background bg-chart-1"
        class="h-40"
      >
        <Grid y={[0, 1500, 3000]} class="stroke-border" />
        <Area class="fill-chart-1/20" />
        <Line class="stroke-chart-1 stroke-2" />
      </Plot>
    </View>
  );
}

mount(App);
```

`Plot`, `Line`, `Area`, `Bar`, `Rule`, `Dot`, `Cell`, `Grid`, `Pie`, `Arc`, `RadialLine`, `RadialGrid`, `Sankey`, `Treemap`, `PlotAxis` and `PlotLabel` come from `nsh/base/plot`, a module of [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md) of their
own (in Rust, `nsh_base::plot`). In TypeScript a plot's props are generic over the type of its rows: field names are
checked against them, and a function of a row gets the row's type. In Rust, `plot()` makes one with a setter per prop,
the rows a `Rows` (columns of numbers by key), the values a `RowAccessor` (a key or a function of the row's index), and
the marks take the typed paint methods (`.stroke_color(..)`, `.fill_color(..)`, `.stroke_width(..)`).

## Plot

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `data` | `.data(..)` | `T[]` | (required) | The rows, one object per point. The marks read their values once, when the app sets the rows; a row without a value (a field that is not a number, `null`) is skipped. |
| `x` | `.x(..)` | `keyof T \| (d: T, index: number) => number` | the row's index | What places a row along the x axis on a `linear` x scale. A `point` scale places the rows in order. |
| `y` | `.y(..)` | `keyof T \| (d: T, index: number) => number` | none | What the marks draw unless they name their own. |
| `xScale` | `.x_scale(..)` | `Scale` | `{ type: "point" }` | How the x axis places rows: `point` (in order, evenly from the left edge to the right one; one row in the middle), `linear` with an optional `domain`, or `band` (a band per row, for bars, [Bar](#bar); or a band per category, for cells, [Cell](#cell)). With a `band` y scale it defaults to `linear`, for bars across. `reverse: true` runs it from the right edge ([Reversed scales](#reversed-scales)). |
| `yScale` | `.y_scale(..)` | `Scale` | `{ type: "linear" }` | How the y axis places values: the domain's smallest value at the bottom edge, its largest at the top. Without a `domain`, the extent of what the marks draw. `band` lays a band per row from the top edge down, for bars across. `reverse: true` runs it the other way: the smallest value at the top edge, the rows from the bottom edge up ([Reversed scales](#reversed-scales)). |
| `y2Scale` | `.y2_scale(..)` | `LinearScale` | none | A second y scale, `{ type: "linear", domain?, reverse? }`, for the marks that name it (`scale="y2"`): a dual-axis chart's right-hand scale ([Dual axes](#dual-axes)). Without a `domain`, the extent of the values on it. |
| `alignTicks` | `.align_ticks(..)` | `boolean` | `true` | While neither y scale names a domain and marks are on both, both are widened to the same round steps so their ticks fall on the same lines ([Dual axes](#dual-axes)). `false` keeps each the extent of its values. |
| `interactive` | `.interactive(..)` | `boolean` | `true` | The plot follows the pointer and the keyboard: it reports the row under it and shows the hover's parts, and it is a stop of Tab whose arrow keys move the hover ([Keyboard](#keyboard)). `false` draws the marks only (a sparkline in a list), and presses on it go to the views around it. Whether the plot offers the keyboard at all is set when it is made. |
| `motion` | `.motion(..)` | `PlotMotion` | none | The timing of the appear, the hover's fade in and out, and the spring the hover glides on when the keys move it (below). |
| `appearGeneration` | `.appear_generation(..)` | `number \| string` | none | Opts in to the appear: the marks draw in when the plot is first shown, and again whenever this changes (another symbol, another period). Inside a [`PlotAppearScope`](#plotappearscope), a generation that finished there shows whole at once. |
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | none | What screen readers say of the chart: what it shows and what stands out. |
| `accessibilityValue` | `.accessibility_value(..)` | `{ min?, max?, now?, text? }` | none | What screen readers hear as its value: the app's words for the row under the pointer. |
| `crossLineClass`, `crossLineStyle` | `.cross_line_class(..)`, `.cross_line_style(..)` | `string`, `StyleProp<ViewStyle>` | none | The cross line: a view as tall as the plot, centered on the row under the pointer. On a band scale it sits in the row's band, as wide as the band (across the plot on a band y scale). |
| `dotClass`, `dotStyle` | `.dot_class(..)`, `.dot_style(..)` | `string`, `StyleProp<ViewStyle>` | none | The hover's dots: a view per `Line`, `Area` and `RadialLine`, centered on its point at the row under the pointer, and a `Dot`'s as big as its dot under the pointer. A mark's `hoverDotClass` / `hoverDotStyle` replace them for its own dot. |
| `tooltipContent` | `.tooltip_content(..)` | `JSX.Element` | none | The app's tooltip, placed by `tooltipPlacement` and moved and faded with the cross line. |
| `tooltipPlacement` | `.tooltip_placement(..)` | `"top" \| "pointer"` | `"top"` | Where the tooltip goes: at the top of the plot, centered on the cross line; or beside the pointer, on the side of the cross line toward the plot's middle and below the pointer in the upper half, above it in the lower one. At the top it stays between the plot's left and right edges (its offset from the top edge is the app's: a tag under the plot takes the plot's height and more); beside the pointer it stays inside the plot. With the keyboard, it goes beside the first line's or area's point at the row (the middle of a bar's band, the middle of a pie's slice). |
| `tooltipOffset` | `.tooltip_offset(..)` | `number` | `0` | The distance between the tooltip and what places it: the top edge for `"top"`, the cross line and the pointer for `"pointer"`. |
| `colorScale` | `.color_scale(..)` | `ColorScale` | none | The marks' colors: of the categories their `color` reads, as d3's `scaleOrdinal` (`{ type: "ordinal", domain?, range, unknown? }`, [Colors by category](#colors-by-category)), or of the numbers a `Cell`'s `value` reads along a ramp, as d3's `scaleSequential` and `scaleDiverging` (`{ type: "sequential" \| "diverging", … }`, [Colors along a ramp](#colors-along-a-ramp)). |
| `children` | `.child(..)` | `JSX.Element` | none | The marks, drawn in order over each other, and whatever the app lays over them. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The plot's size and look; the marks inherit its paint properties, as CSS inherits them. `focus:` / `focus-visible:` classes and `focusStyle` draw its focus ring. |

| Event | Rust | Payload | When |
|---|---|---|---|
| `onHoverChange` | `.on_hover_change(..)` | `{ index: number \| null }` | The pointer came over another row: the index of the row nearest to it along the x axis (along the y axis when only it has bands), of the [pie](#pie-and-arc)'s slice under it, of the [dot](#dot) whose center is nearest to it, of the [cell](#cell) under it (across the gap between two cells, the nearer one), or of a [radial line](#radialline-and-radialgrid)'s row nearest to it by angle; `null` once it leaves the plot (over a pie, its slices; over a radial line, its outer radius). |

`Scale` is `{ type: "point"; reverse? } | { type: "linear"; domain?: [number, number]; reverse? } | { type: "band";
domain?: string[]; paddingInner?; paddingOuter?; maxBandWidth?; bandCount?; groupPadding?; reverse? }`. A `linear`
scale's `domain` is the extent of its two values, in either order; a domain of one value puts it in the middle. A
`band` scale's `domain` is its bands' categories, in order ([Cell](#cell)); its other options are in [Bar](#bar).

A function of a row (`y={(d) => d.high - d.low}`) is called once per row when the rows or the function change, in the
next turn, never while the plot draws or follows the pointer: keep it pure (the same row, the same number). A field
name is read with no JS at all.

### Reversed scales

`reverse: true` runs a scale from its other edge, as visx's scales take `reverse` and d3's take a range written
backwards. On the x axis the first row, or the domain's smallest value, is at the right edge; on the y axis the
domain's smallest value is at the top edge and the rows run from the bottom edge up. Everything placed on the scale
follows it: the marks, the bars' base and the way they grow, an area's baseline, the grid lines, the `PlotAxis` ticks,
the row the hover finds, the arrow keys ([Keyboard](#keyboard)) and the moves to a new domain. Bars hang from the top
edge on a reversed `linear` y scale, and bars across grow leftward from the right edge on a reversed `linear` x
scale:

```tsx
<Plot
  data={depths}
  y="depth"
  xScale={{ type: "band", paddingInner: 0.2 }}
  yScale={{ type: "linear", domain: [0, 40], reverse: true }}
  class="h-32"
>
  <Bar class="fill-chart-2" cornerRadii={{ bottomLeft: 3, bottomRight: 3 }} />
</Plot>
```

With the plot's appear, lines and areas draw in from the edge the x scale starts at, the right one when it is
reversed.

### Dual axes

<!-- demo: el-plot-dual -->

A plot has a second y scale for values of other units: volumes beside a price, revenue beside a margin. Every part
that places values along y takes `scale`: `"y"` (the default, the plot's `yScale`) or `"y2"` (its `y2Scale`). A
`PlotAxis` on the right with `scale="y2"` labels it:

```tsx
<Plot data={days} xScale={{ type: "band", paddingInner: 0.3 }} class="mx-10 mb-6 h-44">
  <Grid class="stroke-border" />
  <Bar value="volume" class="fill-chart-2/50" />
  <Line y="close" scale="y2" class="stroke-chart-1 stroke-2" />
  <PlotAxis placement="left" format={(v) => `${v}M`} labelClass="pr-2 text-xs text-muted-foreground" />
  <PlotAxis placement="right" scale="y2" labelClass="pl-2 text-xs text-muted-foreground" />
</Plot>
```

Each scale's domain is its own: the app's `domain`, or the extent of the values on it, and each moves to a new one
with `motion.update`. While neither scale names a domain, the plot lays both out in the same number of round steps (1,
2 or 5 times a power of ten, a step for about every 32 points of height): when both hold zero, zero falls on the same
line on both; otherwise a scale that starts at zero (volumes) gains its extra steps upward and another (a price) on
both sides. The axes' ticks are those steps, and a `Grid` with neither `x` nor `y` draws its lines at them, so one
grid serves both axes. `alignTicks={false}` turns this off; a `domain` the app names leaves both scales as they are.

The hover finds one row; each mark's dot sits on its own scale, and the read-out is the app's, which reads both values
of the row `onHoverChange` reports. Bars on both scales stand side by side in each band, and a `stack` piles only the
bars on its scale. `y2Scale` is linear: a plot whose y axis has bands has no second y scale.

## Line, Area and Grid

| Mark | Prop | Type | Default | Description |
|---|---|---|---|---|
| `Line` | `y` | `string \| (d, index) => number` | the plot's `y` | What it draws: one point per row with a value, the rows without one skipped. |
| `Line`, `Area` | `data`, `x` | `T[]`, `string \| (d, index) => number` | the plot's rows | Rows of a series of its own (other x values), placed on the plot's scales by its own `x` (a row's index without). |
| `Line`, `Area` | `curve` | `"natural" \| "linear" \| "stepAfter"` | `"natural"` | How it connects its points: a smooth curve, straight segments, or steps that hold each value until the next row. An area's bottom edge follows the same curve. |
| `Line` | `dot`, `dotClass`, `dotStyle` | `boolean`, `string`, `StyleProp<ViewStyle>` | `false` | A dot on every point: a view centered on it, its size, background and border the app's. |
| `Line`, `Area` | `hoverDotClass`, `hoverDotStyle` | `string`, `StyleProp<ViewStyle>` | the plot's `dotClass`, `dotStyle` | Its hover dot, on its point at the row under the pointer: each series' dot in its own color. Each replaces the plot's for this mark (a mark's color over the plot's size and ring); `hidden` shows none. |
| `Area` | `backgroundClass`, `backgroundStyle` | `string`, `StyleProp<ViewStyle>` | none | Its background: a box around its shape (from its first point to its last, from its highest point to its baseline, or to its bottom edge's lowest point on a band) whose background (`bg-*`, `bg-linear-to-b from-… to-…`, `backgroundImage`) shows only inside the shape, under its `fill`. With one, `fill` is `none` where none is set. |
| `Area` | `y1` | `string \| (d, index) => number` | the plot's `y` | What makes its top edge. |
| `Area` | `y0` | `number \| string \| (d, index) => number` | the y scale's low edge | Its bottom edge: a number is a baseline on the y scale; a field or a function gives each row its own bottom value, which makes the area a band (a day's low to its high, a forecast's range). Without one, the area closes to the edge where the y scale's smallest values are: the bottom edge, the top one on a reversed scale (an area hanging from the top). A row without a value at either edge is skipped. |
| `Line`, `Area`, `Grid` | `scale` | `"y" \| "y2"` | `"y"` | The y scale its values go along: the plot's `yScale` or its second one, `y2Scale` ([Dual axes](#dual-axes)). |
| `Grid` | `x` | `number[]` | none | Where its vertical lines go, as values of the x scale (row indices on a `point` scale). |
| `Grid` | `y` | `number[]` | none | Where its horizontal lines go, as values of the y scale. With neither `x` nor `y`, the lines follow the ticks of its scale, where a `PlotAxis` without `ticks` puts them (along x for bars across). |
| `Grid` | `ticks` | `number` | the axis' default | About how many lines it draws with neither `x` nor `y`, as a `PlotAxis`'s `ticks`. |
| `Line`, `Area` | `color` | `string \| (d, index) => string` | none | The category of its rows, its color from the plot's `colorScale`: its first row's category gives the line's `stroke` (the area's `fill`) where nothing sets one ([Colors by category](#colors-by-category)). |

Each mark fills the plot and paints with its [SVG paint properties](https://nsh.dev/versions/main/modules/style-reference.md#svg-paint), its own
over those of the plot, as CSS inherits them:

| Mark | Paints with | Where none is set |
|---|---|---|
| `Line` | `stroke`, `strokeWidth`, `strokeDasharray` | `currentColor`, 1 wide, solid |
| `Area` | `fill` (over its `background` part); its top edge `stroke`, `strokeWidth`, `strokeDasharray` | `fill` `currentColor` (`none` beside a background); no stroke |
| `Grid` | `stroke`, `strokeWidth`, `strokeDasharray` | `currentColor`, 1 wide, solid; each line on whole device pixels, so a thin one stays sharp |

The values a `Line` or an `Area` draws, an area's `y0` too (its baseline, or each row's bottom value), make the y
scale's domain when the plot has none; a grid's do not. A mark draws again only when what it draws changes (its rows,
values, curve, the plot's size or scales, its paint); the pointer moves the hover's parts and never draws a mark again.

A band is an `Area` whose `y0` reads the rows: its top edge runs through `y1`, its bottom edge back through `y0`, both
with the area's `curve`, and the appear draws both in from the leading edge. Its hover dot sits on the top edge; a
`Line` over it marks the middle value:

```tsx
<Plot data={days} y="close">
  <Area y1="high" y0="low" class="fill-chart-1/15" hoverDotClass="hidden" />
  <Line class="stroke-chart-1 stroke-2" />
</Plot>
```

`fill` is CSS's, as in a browser: a color. A gradient under a line is an area's background, the way a page shows a
gradient in a shape (a box's `background-image` under `clip-path`): `backgroundClass="bg-linear-to-b from-chart-1/20
to-transparent"` fades from the area's highest point to its baseline, in the theme's tokens and the appearance's
colors like any view's background.

## Bar

A `Bar` draws a bar per row in the row's band of a `band` scale: upright on a band x scale, across on a band y scale
(the x scale then `linear`). Each bar runs from `base` to the row's value on the other scale, so a negative value
grows the other way, and a row without a value has no bar. On a reversed value scale the bars grow down from the top
edge or leftward from the right one, and a reversed band scale puts the first row's band at the right or the bottom
([Reversed scales](#reversed-scales)).

```tsx
import { Bar, Grid, Plot } from "nsh/base/plot";

const sales = [
  { month: "Jan", online: 42, store: 31 },
  { month: "Feb", online: 51, store: 28 },
  { month: "Mar", online: 48, store: 36 },
];

<Plot
  data={sales}
  xScale={{ type: "band", paddingInner: 0.3, paddingOuter: 0.15, groupPadding: 0.1 }}
  yScale={{ type: "linear", domain: [0, 60] }}
  class="h-40"
>
  <Grid y={[20, 40, 60]} class="stroke-border" />
  <Bar value="online" class="fill-chart-1" cornerRadii={{ topLeft: 4, topRight: 4 }} />
  <Bar value="store" class="fill-chart-2" cornerRadii={{ topLeft: 4, topRight: 4 }} />
</Plot>
```

Bars outside a stack stand side by side in each band, in the order of the marks; bars with the same `stack` pile up,
each row's bar starting where the one before it in the stack ends:

```tsx
<Bar value="online" stack="sales" class="fill-chart-1" />
<Bar value="store" stack="sales" class="fill-chart-2" cornerRadii={{ topLeft: 4, topRight: 4 }} label={(d) => `${d.online + d.store}`} />
```

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` | `string \| (d, index) => number` | the plot's `y` | What each bar shows. |
| `base` | `number \| string \| (d, index) => number` | `0` | The value its bars grow from, on the value scale: one for every row, or a field or function giving each row its own, so each bar spans its row's base to its value (a row without one has no bar). It counts in the domain. A stack grows from its first bar's, row by row. |
| `stack` | `string` | none | The stack it joins: the bars with the same `stack` pile up in order (a row without a value adds nothing). |
| `scale` | `"y" \| "y2"` | `"y"` | The y scale its upright bars' values go along ([Dual axes](#dual-axes)); bars on both stand side by side, and a stack piles only the bars on its scale. |
| `cornerRadii` | `number \| { topLeft?, topRight?, bottomRight?, bottomLeft? }` | `0` | The radius of each corner of its bars; `{ topLeft: 4, topRight: 4 }` rounds the tips of upright bars. A radius larger than half a bar fits it. |
| `stagger` | `number` | `0` | With the plot's appear, the bars start one after another, row by row, over this share of it (0 to 0.95), each growing for the rest; 0 grows them together. |
| `inactiveOpacity` | `number` | none | The opacity of its bars away from the row under the pointer while the pointer is over the plot, so that row stands out: it fades in and out with the hover and passes from bar to bar with it. |
| `label` | `string \| (d, index) => string` | none | The text at each bar's value end: a field (its text, or its number) or a function returning the text the app formats. |
| `labelClass`, `labelStyle` | `string`, `StyleProp<TextStyle>` | none | The `label` part: a text centered on the bar, above an upright bar's end (below one growing down), after a bar across (before one growing back). Its padding is its distance from the bar. |
| `backgroundClass`, `backgroundStyle` | `string`, `StyleProp<ViewStyle>` | none | Its background: each bar's box, whose background (`bg-linear-to-t from-… to-…`, from the bottom of the bar to its top) shows only inside the bar, under its `fill`. With one, `fill` is `none` where none is set. |
| `color` | `string \| (d, index) => string` | none | Each bar's category, its color from the plot's `colorScale`: the bar's `fill` where nothing sets one ([Colors by category](#colors-by-category)). |

The band scale lays out a band per row of the plot, in order, or a band per category of its `domain`, as d3's `scaleBand` does:

| Option | Default | Description |
|---|---|---|
| `domain` | none | The categories of its bands, in order (d3's `scaleBand().domain()`): a [`Cell`](#cell) goes in the band of its row's category, and a `PlotAxis` writes each band's category; a category written twice keeps its first place. Without one, the bands are the rows, or over cells the categories the cells name along the axis, in the order the rows bring them. |
| `paddingInner` | `0` | The gap between neighbouring bands, a share of each band's step (0 to 1). |
| `paddingOuter` | `0` | The gap before the first band and after the last, a share of a step. Half of `paddingInner` puts the bands' middles at equal steps across the plot. |
| `maxBandWidth` | none | The widest a band may be, in points: a few bands across a wide plot stay narrow, each in the middle of its place. |
| `bandCount` | the rows | The bands the axis is laid out for when more than the rows: the rows take the leading ones and keep their width and place as rows come. |
| `groupPadding` | `0` | The gap between the bars side by side in a band, a share of each bar's place. |
| `reverse` | `false` | The bands run from the other edge: the first row's at the right of the x axis, at the bottom of the y axis; the bars side by side in a band keep their order. |

A bar paints with its `fill` (`fill-*`; inherited from the plot as CSS inherits it), `currentColor` where none is set
(its category's color with `color`), and shows no hover dot. On a band scale, the hover finds the band under the pointer, and the plot's cross line sits in
that band, as wide as it: `crossLineClass="w-full h-full bg-foreground/5"` tints the band, `w-px` keeps a line in its
middle. The bars' values and base make the value scale's domain when the plot has none. With the plot's appear, each
bar grows out of its stack's base; the motion, the fading and the gliding run on the platform's animator, and the
pointer draws no bar again.

### Ranges

<!-- demo: el-plot-ranges -->

With `base` a field or a function, each bar spans two values of its row: a waterfall's step from the running total
before it to the one after, a candle's body from its open to its close, a task from its start to its end. A bar grows
from its own base as it appears, and its label sits at its value end, above a bar that rises and below one that falls.

```tsx
const bridge = [
  { step: "Revenue", from: 0, to: 120, kind: "total" },
  { step: "Costs", from: 120, to: 72, kind: "down" },
  { step: "Other", from: 72, to: 81, kind: "up" },
  { step: "Profit", from: 0, to: 81, kind: "total" },
];

<Plot
  data={bridge}
  xScale={{ type: "band", paddingInner: 0.3 }}
  colorScale={{ type: "ordinal", domain: ["total", "up", "down"], range: ["#64748b", "#16a34a", "#dc2626"] }}
  class="h-40"
>
  <Bar value="to" base="from" color="kind" label={(d) => `${d.to - d.from}`} labelClass="text-xs pb-1" />
</Plot>
```

A funnel is bars across, centered: `base={(d) => -d.users / 2}` and `value={(d) => d.users / 2}` on a band y scale.

## Rule

A `Rule` draws a straight line per row along the value axis, from `base` to the row's value: in the middle of the row's
band on a band scale (across the plot on a band y scale), at the row's place along the x axis on a point or linear
one. A candle's wick, a box plot's whisker, an error bar and a lollipop's stem are rules; a candlestick is a `Bar` over
a `Rule`:

```tsx
import { Bar, Plot, Rule } from "nsh/base/plot";

<Plot
  data={days}
  xScale={{ type: "band", paddingInner: 0.4 }}
  colorScale={{ type: "ordinal", domain: ["up", "down"], range: ["#16a34a", "#dc2626"] }}
  class="h-48"
>
  <Rule value="high" base="low" color={(d) => (d.close >= d.open ? "up" : "down")} />
  <Bar value="close" base="open" color={(d) => (d.close >= d.open ? "up" : "down")} />
</Plot>
```

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` | `string \| (d, index) => number` | the plot's `y` | Where each line ends. A row without a value has no line. |
| `base` | `number \| string \| (d, index) => number` | `0` | Where each line starts: one value for every row (a lollipop's stem from the zero line), or a field or function giving each row its own (a candle's low). It counts in the domain. |
| `scale` | `"y" \| "y2"` | `"y"` | The y scale its values go along ([Dual axes](#dual-axes)). |
| `stagger` | `number` | `0` | With the plot's appear, the lines start one after another, row by row, over this share of it (0 to 0.95), each growing from its start for the rest. |
| `inactiveOpacity` | `number` | none | The opacity of its lines away from the row under the pointer while the pointer is over the plot, as `Bar`'s. |
| `color` | `string \| (d, index) => string` | none | Each line's category, its color from the plot's `colorScale`: the line's `stroke` where nothing sets one. |

A rule strokes with its `stroke` (`stroke-*`, `strokeWidth`, `strokeDasharray`; inherited from the plot as CSS inherits
it), `currentColor` where none is set, and shows no hover dot. Its values and base make the value scale's domain when
the plot has none; it grows from its start with the plot's appear and moves with the scales' domains, on the
platform's animator.

## Dot

<!-- demo: el-plot-dots -->

A `Dot` draws a dot per row where two values of the row meet: its `x` along a `linear` x scale and its `value` up the
y axis make a scatter plot; on a band x scale each dot sits in the middle of its row's band; across a band y scale
(the x scale `linear`), its value runs along x and its row's band down the plot, a dot plot. Its radius `r` is one
number for every dot, or a value of each row that `rScale` turns into a radius, a bubble chart. A row without a value
has no dot.

```tsx
import { Dot, Grid, Plot } from "nsh/base/plot";
import { token } from "nsh";

const sessions = [
  { minutes: 12, trades: 5, platform: "iOS" },
  { minutes: 8, trades: 3, platform: "Android" },
  { minutes: 26, trades: 11, platform: "Web" },
  { minutes: 17, trades: 8, platform: "iOS" },
];

<Plot
  data={sessions}
  x="minutes"
  xScale={{ type: "linear", domain: [0, 40] }}
  yScale={{ type: "linear", domain: [0, 20] }}
  colorScale={{ type: "ordinal", domain: ["iOS", "Android", "Web"], range: [token("chart-1"), token("chart-2"), token("chart-3")] }}
  class="h-48"
>
  <Grid x={[10, 20, 30]} y={[5, 10, 15]} class="stroke-border" />
  <Dot
    value="trades"
    r={4}
    color="platform"
    inactiveOpacity={0.3}
    class="stroke-card stroke-2"
    hoverDotClass="rounded-full outline-2 outline-offset-1 outline-foreground"
  />
</Plot>
```

With `r` a field or a function, each row's value sizes its dot. `rScale={{ type: "sqrt", range: [min, max] }}` maps
the square roots of the values onto radii in points, as d3's `scaleSqrt` does, so with a range from 0 a bubble's
area is in proportion to its value; a range from more than 0 keeps the smallest bubbles in sight. The domain is 0 to
the largest value unless the scale names one. The bigger dots draw first, so the smaller ones stay in sight over them:

```tsx
<Plot
  data={countries}
  x="gdp"
  xScale={{ type: "linear", domain: [-10, 95] }}
  yScale={{ type: "linear", domain: [48, 90] }}
  colorScale={{ type: "ordinal", range: [token("chart-1"), token("chart-2"), token("chart-3"), token("chart-4")] }}
  class="h-56"
>
  <Dot value="life" r="population" rScale={{ type: "sqrt", range: [3, 24] }} color="region" class="stroke-card" />
</Plot>
```

A dot's values make the value scale's domain when the plot has none, without reaching for 0, so a scatter's axes fit
its points. Give the plot `domain`s with some room around the values when the dots are big: a bubble at the edge of
the domain is drawn across the plot's edge.

Two marks in the same bands make the charts that compare two values of a row: a lollipop is a `Rule` from 0 under a
`Dot` at its value, and a dumbbell is a `Rule` from one value to the other with a `Dot` at each end, across a band y
scale:

```tsx
<Plot data={stocks} yScale={{ type: "band", paddingInner: 0.3 }} xScale={{ type: "linear", domain: [-50, 80] }} class="h-48">
  <Rule value="high" base="low" class="stroke-border stroke-2" />
  <Dot value="before" r={3.5} class="fill-card stroke-muted-foreground" hoverDotClass="hidden" />
  <Dot value="now" r={5} class="fill-chart-1 stroke-card stroke-2" hitRadius={24} />
</Plot>
```

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` | `string \| (d, index) => number` | the plot's `y` | Where each dot goes along the value axis: up the y axis, or along x across a band y scale. A row without a value has no dot. |
| `r` | `number \| string \| (d, index) => number` | `3` | The dots' radius in points, or a field or function giving each row a value that `rScale` makes a radius (the value is the radius without one). A row whose value is missing has no dot. |
| `rScale` | `{ type: "sqrt"; domain?: [number, number]; range: [number, number] }` | none | How the values of `r` become radii: their square roots over the `domain` (0 to the largest value without one) onto the `range` of radii, so a range from 0 makes each dot's area in proportion to its value. Values outside the domain take the range's ends. |
| `stagger` | `number` | `0` | With the plot's appear, the dots start growing one after another, row by row, over this share of it (0 to 0.95); 0 grows them together. |
| `inactiveOpacity` | `number` | none | The opacity of its other dots while one is under the pointer or the keys: they fade in and out with the hover. |
| `color` | `string \| (d, index) => string` | none | Each dot's category, its color from the plot's `colorScale`: the dot's `fill` where nothing sets one ([Colors by category](#colors-by-category)). |
| `hitRadius` | `number` | `8` | How far past a dot's edge the pointer still finds it: of the dots within this distance, the pointer finds the one whose center is nearest to it (Voronoi's cells), so a small bubble over a big one is found around its own center. A dot plot's row is found from anywhere along it with a radius as large as a row. |
| `scale` | `"y" \| "y2"` | `"y"` | The y scale its values go along ([Dual axes](#dual-axes)); dots across a band y scale put their values along x. |
| `hoverDotClass`, `hoverDotStyle` | `string`, `StyleProp<ViewStyle>` | the plot's `dotClass`, `dotStyle` | The `hoverDot` part: a view as wide and tall as the dot under the pointer, centered on it. `rounded-full outline-2 outline-offset-1` rings it; `hidden` shows none for this mark. |

A dot fills with its `fill` (`fill-*`; inherited from the plot as CSS inherits it), `currentColor` where none is set
(its category's color with `color`), and strokes with its `stroke` where one is set (`stroke-*`, `strokeWidth`): a ring
in the card's color keeps overlapping dots apart. Over a plot with dots, the plot reports the row of the dot whose
center is nearest to the pointer (`null` away from every dot), the keys step through the rows in their order (sort the rows by
x, and the keys walk the dots from left to right), and the `hoverDot` part marks the dot. With the plot's appear, the
dots grow from nothing; with `motion.update`, they move to their new values and sizes, a new row's dot grows in and the
dot of a row that is gone shrinks away; all on the platform's animator, with no mark drawn again.

## Cell

<!-- demo: el-plot-cells -->

A `Cell` draws a rectangle per row in two bands at once: the band of its `x` category along a `band` x scale and the
band of its `y` category along a `band` y scale, so the rows make a grid, a heatmap. A correlation matrix, a calendar
of monthly returns and a week of trades per hour are cells. Each cell fills its two bands, so the scales'
`paddingInner` and `paddingOuter` are the gaps between and around the cells. Its color is its `value` along the
plot's `colorScale`, a ramp of colors ([Colors along a ramp](#colors-along-a-ramp)), or its `color` category's
through an ordinal one. Cells sit on the plot's x and y scales.

```tsx
import { Cell, Plot, PlotAxis } from "nsh/base/plot";
import { token } from "nsh";

const months = [
  { year: "2025", month: "Jan", ret: 2.7 },
  { year: "2025", month: "Feb", ret: -1.4 },
  { year: "2025", month: "Mar", ret: -5.8 },
  { year: "2026", month: "Jan", ret: 1.9 },
  { year: "2026", month: "Feb", ret: 3.2 },
];

<Plot
  data={months}
  xScale={{ type: "band", domain: ["Jan", "Feb", "Mar"], paddingInner: 0.08 }}
  yScale={{ type: "band", paddingInner: 0.08 }}
  colorScale={{ type: "diverging", range: [token("destructive"), token("muted"), token("chart-1")] }}
  class="ml-10 mt-6 h-24"
>
  <Cell
    x="month"
    y="year"
    value="ret"
    cornerRadii={3}
    inactiveOpacity={0.4}
    label={(d) => d.ret.toFixed(1)}
    labelClass="text-xs tabular-nums text-black/70 data-dark:text-white"
    hoverCellClass="rounded-sm outline-2 outline-offset-1 outline-foreground"
  />
  <PlotAxis placement="top" labelClass="pb-1.5 text-xs text-muted-foreground" />
  <PlotAxis placement="left" labelClass="w-10 pr-2 text-right text-xs text-muted-foreground" />
</Plot>
```

A band scale's `domain` names its bands' categories in order, as d3's `scaleBand().domain()` does: the months of a
calendar from January to December, each with its band whether its rows have come or not, so March 2026 above is a
blank place in the grid. Without a domain, the bands are the categories the cells name along the axis, in the order
the rows bring them (2025 above 2026). A `PlotAxis` along a band scale of categories writes each band's category,
with no `format`.

A correlation matrix names the same holdings along both axes, its `domain` the coefficients' whole range, so a
coefficient of 0 takes the ramp's middle whatever the holdings:

```tsx
const tickers = ["NVDA", "AMD", "MSFT", "GLD"];

<Plot
  data={pairs}
  xScale={{ type: "band", domain: tickers, paddingInner: 0.06 }}
  yScale={{ type: "band", domain: tickers, paddingInner: 0.06 }}
  colorScale={{ type: "diverging", domain: [-1, 1], range: [token("chart-2"), token("muted"), token("chart-1")] }}
  class="aspect-square"
>
  <Cell x="b" y="a" value="r" label={(d) => d.r.toFixed(2)} labelClass="text-xs text-black/70 data-dark:text-white" />
</Plot>
```

| Prop | Type | Default | Description |
|---|---|---|---|
| `x` | `string \| (d, index) => string` | none | The column of each row: a field (its text, or its number) or a function returning the category. The row's cell goes in that category's band of the x scale; a row without one has no cell. |
| `y` | `string \| (d, index) => string` | none | The line of each row, as `x` along the y scale. |
| `value` | `string \| (d, index) => number` | none | The number of each cell, which a `sequential` or `diverging` `colorScale` makes its color. A row without one takes the scale's `unknown` color, and without that has no cell. |
| `color` | `string \| (d, index) => string` | none | Each cell's category, its color from an `ordinal` `colorScale` ([Colors by category](#colors-by-category)). |
| `cornerRadii` | `number \| { topLeft?, topRight?, bottomRight?, bottomLeft? }` | `0` | The radius of each corner of its cells. |
| `stagger` | `number` | `0` | With the plot's appear, the cells start growing one after another, row by row, over this share of it (0 to 0.95), each from its middle for the rest; 0 grows them together. |
| `inactiveOpacity` | `number` | none | The opacity of its other cells and their labels while one is under the pointer or the keys: they fade in and out with the hover. |
| `label` | `string \| (d, index) => string` | none | The `label` part: a text in the middle of each cell, a field (its text, or its number) or a function returning the text the app formats. Each label shows where its laid-out size fits inside its cell, so a narrow plot shows the colors alone. |
| `labelClass`, `labelStyle` | `string`, `StyleProp<TextStyle>` | none | The labels' font, size and color. A label on a cell whose `colorScale` color is dark has the attribute `data-dark` (where light text reads better), so `data-dark:text-white` writes it light there. |
| `hoverCellClass`, `hoverCellStyle` | `string`, `StyleProp<ViewStyle>` | none | The `hoverCell` part: a view as big as the cell under the pointer or the keys, over it; `rounded-sm outline-2 outline-foreground` rings it. It moves with the pointer in the same frame and glides on the `pointer` spring when the keys move it. |

A cell fills with its color of the plot's `colorScale` where the app sets no `fill` (`fill-*` classes and styles come
first, inherited from the plot as CSS inherits them), `currentColor` where nothing sets one, and strokes with its
`stroke` where one is set. Over a plot with cells, the plot reports the row of the cell under the pointer, and
across the gap between two cells the nearer one; the arrow keys step across the grid on the screen
([Keyboard](#keyboard)), and screen readers through the rows in their order. With the plot's appear, the cells grow
from their middles; with `motion.update`, a cell's color glides to its new one, a new row's cell grows in, the cell
of a row that is gone shrinks away, and cells move to their new bands; all on the platform's animator, with no mark
drawn again.

## Pie and Arc

A `Pie` splits a turn into a slice per row, each its share of the rows' values, clockwise from 12 o'clock in the rows'
order, around the plot's center. An `innerRadius` makes it a donut. Each slice is a canvas of its own, the `slice`
part, so each paints with its own classes: `sliceClass` is the same classes on every slice, or a function of the
slice's row that gives each its own. Over a pie, the plot reports the row of the slice under the pointer (none in the
hole or outside the ring), its tooltip follows the pointer, and that slice grows by `hoverLift` while the others fade
by `hoverDim`, on the platform's animator with the plot's `motion`. An `Arc` draws one sector between two angles: a
gauge's track and its value, or a ring behind a pie.

<!-- demo: el-plot-pie -->

```tsx
import { signal, Text, View } from "nsh";
import { Pie, Plot } from "nsh/base/plot";

type Plan = { name: string; seats: number };

const FILLS = ["fill-chart-1", "fill-chart-2", "fill-chart-3", "fill-chart-4"];
const KEYS = ["bg-chart-1", "bg-chart-2", "bg-chart-3", "bg-chart-4"];

export function Seats(props: { plans: Plan[] }) {
  const hovered = signal<number | null>(null);
  const total = () => props.plans.reduce((sum, p) => sum + p.seats, 0);
  const shown = () => (hovered() == null ? undefined : props.plans[hovered()!]);
  const share = (n: number) => `${((n / total()) * 100).toFixed(1)}%`;
  return (
    <View class="flex-row items-center gap-6 rounded-xl border border-border bg-card p-4">
      <Plot
        data={props.plans}
        accessibilityLabel={`Seats by plan, ${total()} in all`}
        accessibilityValue={{ text: shown() && `${shown()!.name}, ${shown()!.seats} seats, ${share(shown()!.seats)}` }}
        appearGeneration={1}
        motion={{ appear: { duration: 900, easing: "easeOut" }, enter: { duration: 120 }, exit: { duration: 160 }, pointer: { stiffness: 400, damping: 32 } }}
        onHoverChange={({ index }) => hovered.set(index)}
        class="size-44"
      >
        {/* A donut with 2-point gaps (0.025 of a turn at its 80-point rim). */}
        <Pie
          value="seats"
          innerRadius="62%"
          padAngle={0.025}
          sliceClass={(_, i) => FILLS[i % FILLS.length]}
          hoverLift={6}
          hoverDim={0.64}
        />
        {/* The hovered plan, or the total, in the hole. */}
        <View class="absolute inset-0 items-center justify-center gap-1">
          <Text class="text-xs text-muted-foreground">{shown()?.name ?? "Total"}</Text>
          <Text class="text-2xl font-semibold tabular-nums text-foreground">{shown()?.seats ?? total()}</Text>
        </View>
      </Plot>
      {/* The legend: a key in each slice's color, the value and the share at the end. */}
      <View class="flex-1 gap-1">
        {props.plans.map((plan, i) => (
          <View class="flex-row items-center gap-3 rounded-md px-2 py-1.5" style={{ opacity: hovered() == null || hovered() === i ? 1 : 0.45 }}>
            <View class={`size-2 rounded-sm ${KEYS[i % KEYS.length]}`} />
            <Text class="flex-1 text-sm text-foreground">{plan.name}</Text>
            <Text class="text-right text-sm tabular-nums text-foreground">{plan.seats}</Text>
            <Text class="w-14 text-right text-sm tabular-nums text-muted-foreground">{share(plan.seats)}</Text>
          </View>
        ))}
      </View>
    </View>
  );
}
```

```rust
use nsh_base::plot::{SliceClass, pie, plot};
use nsh_core::{element::{RowAccessor, Rows}, prelude::*};

fn seats(seats: Vec<f64>) -> impl IntoElement {
    let rows = Rows::from_columns(seats.len(), [("seats".into(), seats)]);
    plot()
        .data(rows)
        .accessibility_label("Seats by plan")
        .w(px(176.0))
        .h(px(176.0))
        .child(
            pie()
                .value(RowAccessor::key("seats"))
                .inner_radius(relative(0.62))
                .slice_class(SliceClass::from_fn(|i| format!("fill-chart-{}", i % 4 + 1).into())),
        )
}
```

| Mark | Prop | Rust | Type | Default | Description |
|---|---|---|---|---|---|
| `Pie` | `value` | `.value(..)` | `keyof T \| (d: T, index: number) => number` | the plot's `y` | What each row is worth. A row worth nothing, less, or no number has no slice. |
| `Pie`, `Arc` | `startAngle`, `endAngle` | `.start_angle(..)`, `.end_angle(..)` | `number` (radians) | `0`, `2 * Math.PI` | Where the first slice starts and the last one ends (an arc's ends): radians from 12 o'clock, clockwise. An `endAngle` below `startAngle` lays a pie's slices out the other way. |
| `Pie` | `padAngle` | `.pad_angle(..)` | `number` (radians) | `0` | The angle between neighbouring slices at the rim. Each gap keeps that width (about `padAngle * outerRadius` points) at every radius, its edges parallel, so it is as wide at the center or the hole as at the rim; a slice too narrow to reach the center ends where its edges meet. A pie of one slice has none. |
| `Pie`, `Arc` | `innerRadius`, `outerRadius` | `.inner_radius(..)`, `.outer_radius(..)` | ``number \| `${number}%` `` | `0`, `"100%"` | The radii of the hole and of the rim: points, or a percentage of the largest circle the plot holds (half its smaller side). |
| `Pie`, `Arc` | `cornerRadius` | `.corner_radius(..)` | `number` | `0` | The radius of each slice's corners (an arc's), in points, as d3's `arc.cornerRadius`: each corner a circle touching the edge and the rim or the hole, the gaps' parallel edges included. It is at most half the ring's thickness, which gives an arc round caps, and on a slice too narrow for two whole corners they meet on its middle. A whole ring keeps its round edges only. |
| `Pie` | `sliceClass` | `.slice_class(..)` | `string \| (d: T, index: number) => string` | none | The classes of each slice (`fill-*`, `stroke-*`): the same on every slice, or a function of the slice's row and its index, called once per row when the rows or the function change. |
| `Pie` | `sliceStyle` | `.slice_style(..)` | `StyleProp<ViewStyle>` | none | The style of every slice, over its classes (`fill`, `stroke`, `strokeWidth`). |
| `Pie` | `hoverLift` | `.hover_lift(..)` | `number` | `0` | How far the slice under the pointer grows past the others, in points: on the plot's `pointer` spring, faded in and out with the hover. |
| `Pie` | `hoverDim` | `.hover_dim(..)` | `number` (0 to 1) | `0` | How much the other slices fade while one is under the pointer, as a share of their opacity, with the hover's fade. |
| `Pie` | `color` | `.color(..)` | `keyof T \| (d: T, index: number) => string` | none | Each slice's category, its color from the plot's `colorScale`: the slice's `fill` where nothing sets one ([Colors by category](#colors-by-category)). |
| `Pie` | `label` | `.label(..)` | `string \| (d: T, index: number) => string` | none | The text beside each slice: a field (its number) or a function returning the text the app formats. A row whose text is empty, or a slice narrower than half a degree, has none. |
| `Pie` | `labelClass`, `labelStyle` | `.label_class(..)`, `.label_style(..)` | `string`, `StyleProp<TextStyle>` | none | The `label` part: a text outside the ring at the end of its leader line, centered on it, after it on the right half of the pie and before it on the left. Its padding is its distance from the line's end. |
| `Pie` | `labelGap` | `.label_gap(..)` | `number` | `15` | How far past the rim the labels sit, in points. |
| `Pie` | `labelLineClass`, `labelLineStyle` | `.label_line_class(..)`, `.label_line_style(..)` | `string \| (d: T, index: number) => string`, `StyleProp<ViewStyle>` | none | The `labelLine` part: each label's leader line, from the rim at the slice's middle out to the label's radius, then across to the text. Its `stroke` (`currentColor` where none is set), `strokeWidth` and `strokeDasharray`, the same on every line or a function of the slice's row; shown once styled. |

A slice and an arc fill with `fill` (`currentColor` where none is set, a slice's category's color with `color`) and stroke their edges with `stroke` (none where
none is set), their own over the pie's and the plot's as CSS inherits them: a stroke in the surface's color
(`stroke-card stroke-2`) cuts gaps between the slices too. Their values take no part in the plot's scales. A pie's
slices are drawn again only when the rows, their values, the angles, the radii or the plot's size change; the pointer
moves the lift and the fade on the animator.

Plots with a pie usually place the tooltip by the pointer (`tooltipPlacement="pointer"`), since a pie's rows have no
place along an axis: the cross line and the tooltip follow the pointer over it, and it shows no hover dots. A donut's
center is the app's own element laid over the plot (the hovered slice's value, or the total), and so is its legend,
with each key in its slice's color.

A pie's labels name its slices outside the ring: each text sits `labelGap` past the rim toward its slice's middle (the
slice's centroid at that radius), then across to that radius on the slice's side of the pie, and a styled leader line
joins it to the rim. The labels sweep in with their slices on the plot's appear and fade in over its end, move with
them on `motion.update`, and lift with the hovered slice; all of it runs on the platform's animator. Give the plot
room for them: an `outerRadius` below `"100%"`, or space around the plot. Content of the app's own at a slice is an
element laid over the plot, as a donut's center is.

```tsx
<Pie
  value="seats"
  outerRadius="64%"
  sliceClass={(_, i) => FILLS[i % FILLS.length]}
  label={(d) => share(d.seats)}
  labelGap={12}
  labelClass="px-1 text-xs tabular-nums text-muted-foreground"
  labelLineClass="stroke-border"
/>
```

## Colors by category

A plot's `colorScale` gives categories their colors, as d3's `scaleOrdinal` does, and a mark's `color` names the
category of each row: a field (its text, or its number) or a function of the row. The `domain`'s categories take the
`range`'s colors in order, and the range starts again from its first color when the domain is longer. A category
outside the domain takes `unknown`; without one, it joins the domain the first time a mark meets it (the marks in
order, each its rows in order) and takes the next color, so with no `domain` at all the categories take the colors
in the order the rows bring them. The colors are the app's: CSS colors, the theme's tokens among them.

```tsx
import { Pie, Plot } from "nsh/base/plot";
import { token } from "nsh";

const regions = [
  { name: "North America", revenue: 482 },
  { name: "EMEA", revenue: 312 },
  { name: "APAC", revenue: 268 },
];

<Plot data={regions} colorScale={{ type: "ordinal", range: [token("chart-1"), token("chart-2"), token("chart-3")] }} class="size-44">
  <Pie value="revenue" color="name" innerRadius="62%" />
</Plot>
```

A slice, a bar and a dot take their row's color; a `Line` and an `Area` are one series each and take their first row's,
so a line of rows of its own (`data`) is in its rows' color, and one scale keeps a category's color the same across
a pie, bars and lines. The color is the mark's `fill` (a line's `stroke`) where nothing sets one, in the place of
`currentColor`: the app's classes and styles come first, the part's (`sliceClass`, `sliceStyle`), the mark's and
those it inherits from the plot, so `sliceClass={(d) => (d.name === "Other" ? "fill-muted" : "")}` sets one slice
apart while the scale colors the others. Beside a `background` part, a bar's and an area's `fill` stays `none`.

| `OrdinalScale` | Type | Default | Description |
|---|---|---|---|
| `type` | `"ordinal"` | (required) | The kind of scale. |
| `domain` | `string[]` | none | The categories, in order. A category written twice keeps its first place. |
| `range` | `string[]` | (required) | The colors, in order (CSS colors); category `i` takes color `i % range.length`. |
| `unknown` | `string` | none | The color of every category outside the domain; without one, each takes the next color. |

### Colors along a ramp

A `colorScale` of `type: "sequential"` or `"diverging"` gives numbers their colors along a ramp, as d3's
`scaleSequential` and `scaleDiverging` do, for the `value` of a [`Cell`](#cell). Its `range` is two or more colors
spread evenly along the ramp from its low end to its high one and mixed in OKLab between them: the steps look even to
the eye, and two hues meet through their own mix. A value past the `domain` takes the ramp's end, and a row without a
value takes `unknown`.

`sequential` spreads its `domain` over the whole ramp, the domain the extent of the cells' values unless the app names
one: counts, volumes, activity. `diverging` puts its `pivot` (0 by default) at the ramp's middle color, the values
below it along the first half and those above it along the second: losses in one hue, gains in another, a flat month
in the neutral middle. Unless the app names a domain, it is the extent of the values made even on both sides of the
pivot (Observable Plot's `symmetric`), so a loss and a gain of the same size are as strong; a correlation matrix names
`domain: [-1, 1]`.

```tsx
colorScale={{ type: "sequential", range: [token("muted"), token("chart-1")] }}
colorScale={{ type: "diverging", pivot: 0, range: [token("destructive"), token("muted"), token("chart-1")] }}
```

| `SequentialScale`, `DivergingScale` | Type | Default | Description |
|---|---|---|---|
| `type` | `"sequential" \| "diverging"` | (required) | The kind of ramp. |
| `domain` | `[number, number]` | the values' extent (made even about the pivot for `diverging`) | The values of the ramp's two ends. |
| `pivot` | `number` | `0` | `diverging` only: the value of the ramp's middle color. |
| `range` | `string[]` | (required) | The colors along the ramp, from the low end to the high one (CSS colors), mixed in OKLab between them. |
| `unknown` | `string` | none | The color of a row without a value; without one, that row has no cell. |

## RadialLine and RadialGrid

A `RadialLine` draws a series around the plot's center: a radar's polygon, or a line round a dial. Each row with a value
is a point at the row's angle, as far out as the plot's y scale puts its value, from `innerRadius` (the domain's
smallest value) to `outerRadius` (its largest). Without an `angle`, the rows go evenly round the turn from 12 o'clock,
clockwise, in order, so six rows are a hexagon; `closed` joins the last point to the first. A line strokes its points
and fills its area down to `innerRadius` (the center by default), so one mark is a radar's outline and its wash. A
`RadialGrid` draws the radar's grid behind it: `rings` at values of the y scale, polygons through the rows' angles or
`circular`, and `spokes` out to each row. Over a radial line, the plot reports the row whose angle is nearest to the
pointer's within the line's outer radius, and each line's hover dot sits on its point of that row.

```tsx
import { signal, Text, View } from "nsh";
import { Plot, RadialGrid, RadialLine } from "nsh/base/plot";

type Metric = { name: string; ours: number; theirs: number };

export function Compare(props: { metrics: Metric[] }) {
  const hovered = signal<number | null>(null);
  const shown = () => (hovered() == null ? undefined : props.metrics[hovered()!]);
  return (
    <View class="items-center gap-3 rounded-xl border border-border bg-card p-4">
      <Text class="text-sm tabular-nums text-muted-foreground">
        {shown() ? `${shown()!.name}: ${shown()!.ours} against ${shown()!.theirs}` : "Ours against theirs"}
      </Text>
      <Plot
        data={props.metrics}
        yScale={{ type: "linear", domain: [0, 100] }}
        accessibilityLabel="Ours against theirs on six metrics"
        accessibilityValue={{ text: shown() && `${shown()!.name}: ours ${shown()!.ours}, theirs ${shown()!.theirs}` }}
        appearGeneration={1}
        motion={{ appear: { duration: 700, easing: "easeOut" }, update: { duration: 400, easing: "easeInOut" }, enter: { duration: 120 }, exit: { duration: 160 }, pointer: { stiffness: 380, damping: 34 } }}
        onHoverChange={({ index }) => hovered.set(index)}
        class="size-56"
      >
        <RadialGrid rings={[25, 50, 75, 100]} spokes outerRadius="80%" class="stroke-border" />
        <RadialLine radius="theirs" closed outerRadius="80%" class="fill-chart-2/15 stroke-chart-2" hoverDotClass="size-2 rounded-full border-2 border-card bg-chart-2" />
        <RadialLine radius="ours" closed outerRadius="80%" class="fill-chart-1/25 stroke-chart-1 stroke-2" hoverDotClass="size-2.5 rounded-full border-2 border-card bg-chart-1" />
        {/* Each metric's name past the rim at its row's angle, growing away from the center. */}
        {props.metrics.map((m, i) => {
          const angle = (2 * Math.PI * i) / props.metrics.length;
          const away = (v: number) => (v > 0.01 ? "flex-start" : v < -0.01 ? "flex-end" : "center");
          const align = (v: number) => (v > 0.01 ? "left" : v < -0.01 ? "right" : "center");
          return (
            <View
              class="absolute size-0"
              style={{
                left: `${50 + 44 * Math.sin(angle)}%`,
                top: `${50 - 44 * Math.cos(angle)}%`,
                alignItems: away(Math.sin(angle)),
                justifyContent: away(-Math.cos(angle)),
                pointerEvents: "none",
              }}
            >
              <Text class="w-24 text-xs text-muted-foreground" style={{ textAlign: align(Math.sin(angle)) }}>{m.name}</Text>
            </View>
          );
        })}
      </Plot>
    </View>
  );
}
```

| Mark | Prop | Rust | Type | Default | Description |
|---|---|---|---|---|---|
| `RadialLine` | `radius` | `.radius(..)` | `keyof T \| (d: T, index: number) => number` | the plot's `y` | What places each row out from the center: a value of the y scale, from `innerRadius` at the domain's smallest value to `outerRadius` at its largest. A row without one is skipped. |
| `RadialLine` | `angle` | `.angle(..)` | `keyof T \| (d: T, index: number) => number` | the rows evenly round the turn | Where each row goes round the center: radians from 12 o'clock, clockwise. |
| `RadialLine`, `RadialGrid` | `startAngle`, `endAngle` | `.start_angle(..)`, `.end_angle(..)` | `number` (radians) | `0`, `2 * Math.PI` | Where the rows go without an `angle`: from `startAngle`, evenly. Round a whole turn they are a step of a turn's `1 / rows` apart, the last a step before the first; over a part of a turn the first is on `startAngle` and the last on `endAngle`. |
| `RadialLine`, `RadialGrid` | `innerRadius`, `outerRadius` | `.inner_radius(..)`, `.outer_radius(..)` | ``number \| `${number}%` `` | `0`, `"100%"` | Where the y domain's smallest and largest values go: points, or a percentage of the largest circle the plot holds (half its smaller side), as a pie's radii. A line's area fills down to `innerRadius`; a grid's spokes run between the two. |
| `RadialLine` | `curve` | `.curve(..)` | `"linear" \| "natural" \| "stepAfter"` | `"linear"` | How it connects its points: straight segments, a smooth curve (closed, a smooth loop), or steps. |
| `RadialLine` | `closed` | `.closed(..)` | `boolean` | `false` | It goes on from its last point back to its first: a radar's polygon. Open, its area closes to the center (or along its inner edge). |
| `RadialLine` | `dot`, `dotClass`, `dotStyle` | `.dot(..)`, `.dot_class(..)`, `.dot_style(..)` | `boolean`, `string`, `StyleProp<ViewStyle>` | `false` | A dot on every point: a view centered on it, its size, background and border the app's. The dots grow out and move with the line. |
| `RadialLine` | `backgroundClass`, `backgroundStyle` | `.background_class(..)`, `.background_style(..)` | `string`, `StyleProp<ViewStyle>` | none | Its background: a box around its outer circle whose background (`bg-*`, a gradient) shows only inside its area, under its `fill`, as an area's. |
| `RadialLine` | `hoverDotClass`, `hoverDotStyle` | `.hover_dot_class(..)`, `.hover_dot_style(..)` | `string`, `StyleProp<ViewStyle>` | the plot's `dotClass`, `dotStyle` | Its hover dot, on its point of the row under the pointer, with the pointer in the same frame and gliding to the next row on the plot's `pointer` spring when the keys step; `hidden` shows none. |
| `RadialGrid` | `rings` | `.rings(..)` | `number[]` | none | Where its rings go, as values of the y scale: each as far out as a radial line puts that value. |
| `RadialGrid` | `spokes` | `.spokes(..)` | `boolean` | `false` | A line from `innerRadius` to `outerRadius` at each row's angle. |
| `RadialGrid` | `circular` | `.circular(..)` | `boolean` | `false` | Its rings are circles (arcs over a part of a turn). By default they are polygons through the rows' angles, and circles while the plot has fewer than three rows. |

A radial line strokes with `stroke`, `strokeWidth` and `strokeDasharray` (`currentColor`, 1 wide and solid where none
is set) and fills its area with `fill` (none where none is set); a radial grid strokes as a grid does. Their paint
inherits from the plot. A line's values, with 0, make the y scale's domain when the plot has none, so a radar of
positive values grows from its center; a grid's rings do not. Give the plot a y `domain` to keep the rings and the
radar's scale fixed while the values change.

Labels around a radar are the app's elements laid over the plot, as a donut's center is. Without an `angle`, row `i`
of `n` sits at `a = 2π·i / n` from 12 o'clock, so in a square plot a box with no size at `left: 50% + r·sin(a)`,
`top: 50% − r·cos(a)` (`r` a percentage of the plot's side a little past half the outer radius's share) marks the
place past the rim, and the name grows from it away from the center: right of it on the right half, left of it on the
left, above it at the top and below it at the bottom, as above.

```rust
use nsh_base::plot::{plot, radial_grid, radial_line};
use nsh_core::{element::{RowAccessor, Rows}, prelude::*};

fn compare(ours: Vec<f64>, theirs: Vec<f64>) -> impl IntoElement {
    let rows = Rows::from_columns(ours.len(), [("ours".into(), ours), ("theirs".into(), theirs)]);
    plot()
        .data(rows)
        .accessibility_label("Ours against theirs")
        .w(px(224.0))
        .h(px(224.0))
        .child(radial_grid().rings(vec![25.0, 50.0, 75.0, 100.0]).spokes(true))
        .child(radial_line().radius(RowAccessor::key("theirs")).closed(true))
        .child(radial_line().radius(RowAccessor::key("ours")).closed(true))
}
```

## Sankey

A `Sankey` draws flows between the plot's rows: each row is a node and `links` names the flows between them, `{
source, target, value }` with the indices of two rows in the plot's `data`. It lays them out as d3-sankey does, in the
plot's size: the nodes in columns (`nodeAlign`), each as tall as the most that flows into or out of it, the nodes of a
column `nodePadding` apart, relaxed toward their flows over `iterations` passes; and a ribbon per link from its
source's right edge to its target's left edge, as wide at each end as its share of that node's side, so both sides of
every node are covered even where its flows in and out differ. Each column is centered in the plot, and a run of equal
single-node columns is staggered a little so the ribbons between them curve. `valueScale="sqrt"` sizes by the square
root of the values, so one dominant flow does not dwarf the small ones.

Each node and each ribbon is a canvas of its own, the `node` and `link` parts, so each paints with its own classes:
`nodeClass` is the same classes on every node or a function of the node's row, and `linkClass` the same on every
ribbon or a function of the link. The `linkBackground` part shows a background inside each ribbon, a box from its
source to its target: a function of the link gives each ribbon a gradient from its source's color to its target's.
The ribbons draw under the nodes, and both draw in from the leading edge with the plot's appear.

Over a sankey, the plot reports the node under the pointer (`onHoverChange`, the node's row; none over a ribbon), its
tooltip follows the pointer, and the links not attached to that node fade by `hoverDim`, on the platform's animator
with the plot's `motion`. The keys step through the nodes in the rows' order, the tooltip beside each node's middle.
`nodeLabel` names each node and `valueLabel` gives its value, the value over the name when both are set: left of a node
in the first column, right of one in the last, centered above one between them, as `gpui-component`'s chart places
them; a label beside a node stays between the plot's top and bottom, and one past the plot's edge sits in the room the
app leaves around it (its margin). The `nodeLabel` part's padding is the gap to its node and its classes its text
(`max-w-20 truncate` cuts a long name short); the labels fade in with the appear. When the app changes the flows, every
node and ribbon moves from its old place to its new one with the plot's `motion.update`, its label with it: a node new
to the flows grows from its middle, a link new to them from its least width, and the ones that go leave at once; a change while they move goes on from where they are drawn. Links
are told apart by their source and target, so reordering `links` moves nothing.

```tsx
import { signal } from "nsh";
import { Plot, Sankey } from "nsh/base/plot";

type Step = { name: string };

const steps: Step[] = [{ name: "Visits" }, { name: "Sign-ups" }, { name: "Bounced" }, { name: "Trials" }, { name: "Paid" }, { name: "Churned" }];
const flows = [
  { source: 0, target: 1, value: 4200 },
  { source: 0, target: 2, value: 5800 },
  { source: 1, target: 3, value: 2600 },
  { source: 3, target: 4, value: 1100 },
  { source: 3, target: 5, value: 1500 },
];
// Each step's color: its node's fill, and its ribbons' gradient ends.
const FILLS = ["fill-chart-1", "fill-chart-2", "fill-muted", "fill-chart-3", "fill-chart-4", "fill-muted"];
const FROM = ["from-chart-1/40", "from-chart-2/40", "from-muted/40", "from-chart-3/40", "from-chart-4/40", "from-muted/40"];
const TO = ["to-chart-1/40", "to-chart-2/40", "to-muted/40", "to-chart-3/40", "to-chart-4/40", "to-muted/40"];

export function Funnel() {
  const hovered = signal<number | null>(null);
  return (
    <Plot
      data={steps}
      accessibilityLabel="Visits to paid: 10,000 visits, 1,100 paid"
      accessibilityValue={{ text: hovered() == null ? undefined : steps[hovered()!].name }}
      onHoverChange={({ index }) => hovered.set(index)}
      appearGeneration={1}
      motion={{ appear: { duration: 900, easing: "easeOut" }, update: { duration: 500 }, enter: { duration: 120 }, exit: { duration: 160 } }}
      class="mx-20 h-64"
    >
      <Sankey
        links={flows}
        nodeWidth={8}
        nodePadding={16}
        nodeCornerRadius={2}
        nodeClass={(_, i) => FILLS[i]}
        linkBackgroundClass={(link) => `bg-linear-to-r ${FROM[link.source]} ${TO[link.target]}`}
        hoverDim={0.7}
        nodeLabel={(d: Step) => d.name}
        valueLabel={(_: Step, value: number) => value.toLocaleString("en-US")}
        nodeLabelClass="px-2 py-1 text-xs text-muted-foreground"
        valueLabelClass="font-medium text-foreground"
      />
    </Plot>
  );
}
```

```rust
use nsh_base::plot::{RowClass, SankeyLinkClass, SankeyLinks, plot, sankey};
use nsh_core::{element::Rows, prelude::*};

fn funnel() -> impl IntoElement {
    plot()
        .data(Rows::from_columns(4, []))
        .accessibility_label("Visits to paid")
        .h(px(256.0))
        .child(
            sankey()
                .links(SankeyLinks::new([(0, 1, 4200.0), (1, 2, 2600.0), (2, 3, 1100.0)]))
                .node_width(px(8.0))
                .node_class(RowClass::from_fn(|i| format!("fill-chart-{}", i + 1).into()))
                .link_class(SankeyLinkClass::from("fill-foreground/10")),
        )
}
```

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `links` | `.links(..)` | `SankeyLink[]` (`{ source: number; target: number; value: number }`) | required | The flows: from the row `source` to the row `target` (their indices in the plot's `data`), `value` its size. A value that is no number or below zero carries nothing and draws no ribbon. |
| `nodeWidth` | `.node_width(..)` | `number` | `24` | The width of each node, in points. |
| `nodePadding` | `.node_padding(..)` | `number` | `8` | The gap between the nodes of a column, in points; less in a column too crowded for it. |
| `nodeAlign` | `.node_align(..)` | `"justify" \| "left" \| "right" \| "center"` | `"justify"` | Which column each node goes in, as d3-sankey's: its depth from the first column (`"left"`), as far right as its flows let it (`"right"`), its depth with a node that only starts flows next to its targets (`"center"`), or its depth with the nodes that end flows in the last column (`"justify"`). |
| `iterations` | `.iterations(..)` | `number` | `6` | How many passes relax the nodes toward their flows. |
| `valueScale` | `.value_scale(..)` | `"linear" \| "sqrt"` | `"linear"` | Heights and widths in proportion to the values, or to their square roots. |
| `minLinkWidth` | `.min_link_width(..)` | `number` | `1` | The thinnest a ribbon draws, in points, so a small flow stays visible. |
| `nodeCornerRadius` | `.node_corner_radius(..)` | `number` | `0` | The radius of each node's corners, in points. |
| `nodeClass` | `.node_class(..)` | `string \| (d: T, index: number) => string` | none | The classes of each node (`fill-*`, `stroke-*`): the same on every node, or a function of the node's row and its index, called once per row when the rows or the function change. |
| `nodeStyle` | `.node_style(..)` | `StyleProp<ViewStyle>` | none | The style of every node, over its classes. |
| `linkClass` | `.link_class(..)` | `string \| (link: SankeyLink, index: number) => string` | none | The classes of each ribbon: the same on every ribbon, or a function of the link and its index in `links`. |
| `linkStyle` | `.link_style(..)` | `StyleProp<ViewStyle>` | none | The style of every ribbon, over its classes. |
| `linkBackgroundClass` | `.link_background_class(..)` | `string \| (link: SankeyLink, index: number) => string` | none | The classes of each ribbon's background (`bg-*`, a gradient: `bg-linear-to-r from-… to-…`), shown inside the ribbon over a box from its source to its target, under its `fill`. With a background, a ribbon's `fill` is `none` where none is set. |
| `linkBackgroundStyle` | `.link_background_style(..)` | `StyleProp<ViewStyle>` | none | The style of every ribbon's background, over its classes. |
| `hoverDim` | `.hover_dim(..)` | `number` (0 to 1) | `0` | How much the links not attached to the node under the pointer fade, as a share of their opacity, on the plot's `pointer` spring and with the hover's fade. |
| `nodeLabel` | `.node_label(..)` | `keyof T \| (d: T, index: number) => string` | none | The name beside each node: a field, or a function of the node's row and its index. |
| `valueLabel` | `.value_label(..)` | `(d: T, value: number, index: number) => string` | none | The value beside each node, over its name: a function of its row and the most that flows into or out of it (in the links' values, whatever the `valueScale`). |
| `nodeLabelClass` | `.node_label_class(..)` | `string` | none | The classes of each label, the `nodeLabel` part: its padding the gap to its node, its text styles both lines'. |
| `nodeLabelStyle` | `.node_label_style(..)` | `StyleProp<TextStyle>` | none | The style of each label, over its classes. |
| `valueLabelClass` | `.value_label_class(..)` | `string` | none | The classes of the value line, the `valueLabel` part, over the label's. |
| `valueLabelStyle` | `.value_label_style(..)` | `StyleProp<TextStyle>` | none | The style of the value line, over its classes. |

A node and a ribbon fill with `fill` (`currentColor` where none is set) and stroke with `stroke` (none where none is
set), their own over the sankey's and the plot's as CSS inherits them. A node with nothing through it is a point tall.
The layout runs again only when the links, the options or the plot's size change, never for the pointer or the
appear; the plot's size changing moves nothing. Links that make a cycle, or name a row the plot does not have, draw nothing and log a warning. Its values take
no part in the plot's scales.


## Treemap

A `Treemap` draws the plot's rows as a hierarchy of nested rectangles: each row is a node, its `id` and the `parent`
it names make the tree (d3's `stratify`), each leaf's area is in proportion to its `value`, and each group is the box
of what is under it, its value the sum of its leaves' (whatever its own row holds). A row without a `parent`, or whose
parent names no row, is a top-level node; without an `id` a row's id is its index, so `parent` can name a row by its
index too. A tree in the nested form gpt-vis writes (`{ name, value, children }`) is a few lines of the app's to make
rows of; there is no limit to the levels.

The tiles are squarified, as d3's `treemapSquarify` makes them: each level's nodes in order of value, largest first
from the top left (`sort="value"`), near the aspect ratio `ratio` (the golden ratio); `sort="data"` keeps the rows'
order, so the nodes keep their places as their values change. `paddingInner` is the gap between siblings, along no
outer edge of their parent; `paddingOuter` is the room inside a group around its children; `paddingTop` is a band at
the top of each group, where its `groupLabel` is written. Each takes a number for every level or one per level from
the top one down (`[3, 1]`: 3 between the top-level nodes, 1 below them). A level's band goes on all the siblings of
a parent or on none, left off where one is too small for it, so the groups of a level read alike.

A leaf whose value is 0, below 0 or not a number takes no area: it is not drawn, has no label and is not found by the
pointer, and neither is a group whose leaves all are.
A treemap's areas are shares of a whole, so the app shows what is left out in its own words (a note under the map).
Negative numbers are for colors: a market map's change of the day.

A node's color is its row's of the plot's `colorScale`: `colorValue` is a number along a ramp (`sequential`,
`diverging`: losses red, gains green, flat neutral, over the extent of the values without a `domain`), `color` a
category (`ordinal`: `"parent"` colors a group's leaves alike). The leaves are the `leaf` part (`leafClass`,
`leafStyle`) and the groups the `group` part (`groupClass`, `groupStyle`), drawn only with a class or a style: a
rectangle under its children, showing in the gaps, its padding and its band. Each part is the same on every node or a
function of the node's row. `cornerRadii` rounds every rectangle.

`label` writes each leaf's name and `valueLabel` its value under it, a function of the row and its value (a group's is
its leaves' sum): at the top left (`labelPlacement="start"`) or in the middle (`"center"`). The `label` part is a box
as big as its leaf: its padding is the room from the leaf's edges and its text styles the lines'. The name is cut
with an ellipsis where the leaf is narrower and shown only where it fits; the value is shown whole or not at all. A label whose leaf's color is dark has the attribute `data-dark`,
so `data-dark:text-white` keeps it readable on a deep red.

Over a treemap, the plot reports the node under the pointer (`onHoverChange`, the node's row): a leaf, or a group in
its band or padding; across a gap between siblings, one of them, so the hover does not flicker. The others fade
to `inactiveOpacity` (a leaf keeps its groups, a group what is under it), and the `hover` part, a view as big as the
node, outlines it. The arrow keys step to the leaf beside on the screen, Home and End to the first and the last.
With the plot's appear the top-level nodes grow from their middles, one after another with `stagger`; when the rows
change, every node moves to its new box and color with `motion.update`, known by its `id`: a node new to the rows
grows from its middle and one that is gone shrinks to its own. The plot's x and y scales are not used.

<!-- demo: el-plot-treemap -->

```tsx
import { signal } from "nsh";
import { Plot, Treemap } from "nsh/base/plot";

type Row = { id: string; parent?: string; name: string; cap?: number; chg?: number };

const rows: Row[] = [
  { id: "tech", name: "Technology" },
  { id: "fin", name: "Financials" },
  { id: "NVDA", parent: "tech", name: "NVIDIA", cap: 4300, chg: 2.4 },
  { id: "MSFT", parent: "tech", name: "Microsoft", cap: 3700, chg: -0.6 },
  { id: "AVGO", parent: "tech", name: "Broadcom", cap: 1600, chg: 3.1 },
  { id: "JPM", parent: "fin", name: "JPMorgan", cap: 830, chg: 1.3 },
  { id: "V", parent: "fin", name: "Visa", cap: 670, chg: -0.3 },
];

export function MarketMap() {
  const hovered = signal<number | null>(null);
  return (
    <Plot
      data={rows}
      colorScale={{ type: "diverging", domain: [-3, 3], range: ["#dc2626", "#e5e5e5", "#16a34a"] }}
      accessibilityLabel="Market map of 5 stocks in 2 sectors"
      accessibilityValue={{ text: hovered() == null ? undefined : rows[hovered()!].name }}
      onHoverChange={({ index }) => hovered.set(index)}
      appearGeneration={1}
      motion={{ appear: { duration: 800 }, update: { duration: 500 }, enter: { duration: 120 }, exit: { duration: 160 } }}
      class="h-72"
    >
      <Treemap
        id="id"
        parent="parent"
        value="cap"
        colorValue="chg"
        paddingInner={[3, 1]}
        paddingTop={18}
        cornerRadii={2}
        inactiveOpacity={0.35}
        label="id"
        valueLabel={(d: Row) => `${d.chg! > 0 ? "+" : ""}${d.chg}%`}
        labelPlacement="center"
        labelClass="p-1 text-xs font-semibold text-foreground data-dark:text-white"
        groupLabel="name"
        groupLabelClass="px-1 text-xs text-muted-foreground"
        hoverClass="rounded-xs outline-2 outline-foreground"
      />
    </Plot>
  );
}
```

```rust
use nsh_base::plot::{ColorScale, DivergingScale, TreemapPadding, plot, treemap};
use nsh_core::{element::{RowAccessor, RowText, Rows}, prelude::*};

const IDS: [&str; 5] = ["tech", "fin", "NVDA", "MSFT", "JPM"];
const PARENTS: [&str; 5] = ["", "", "tech", "tech", "fin"];

fn market_map() -> impl IntoElement {
    let rows = Rows::from_columns(
        5,
        [
            ("cap".into(), vec![0.0, 0.0, 4300.0, 3700.0, 830.0]),
            ("chg".into(), vec![0.0, 0.0, 2.4, -0.6, 1.3]),
        ],
    );
    plot()
        .data(rows)
        .color_scale(ColorScale::from(
            DivergingScale::new([rgb(0xdc2626), rgb(0xe5e5e5), rgb(0x16a34a)]).domain([-3.0, 3.0]),
        ))
        .accessibility_label("Market map")
        .h(px(288.0))
        .child(
            treemap()
                .id(RowText::from_fn(|i| IDS[i].into()))
                .parent(RowText::from_fn(|i| PARENTS[i].into()))
                .value(RowAccessor::key("cap"))
                .color_value(RowAccessor::key("chg"))
                .padding_inner(TreemapPadding::from([px(3.0), px(1.0)]))
                .padding_top(TreemapPadding::from(px(18.0)))
                .label(RowText::from_fn(|i| IDS[i].into())),
        )
}
```

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `id` | `.id(..)` | `keyof T \| (d: T, index: number) => string` | the row's index | The id of each row's node: what `parent` names, and what a node is known by when the rows change. |
| `parent` | `.parent(..)` | `keyof T \| (d: T, index: number) => string` | none: every row is a top-level node | The id of each row's parent; empty, or no row's id, for a top-level node. |
| `value` | `.value(..)` | `keyof T \| (d: T, index: number) => number` | required | The size of each leaf; a group's is the sum of its children's. A leaf of 0, below 0 or no number takes no area. |
| `sort` | `.sort(..)` | `"value" \| "data"` | `"value"` | Siblings largest first from the top left, or in the rows' order. |
| `ratio` | `.ratio(..)` | `number` | the golden ratio | The aspect ratio the tiles approach, at least 1. |
| `paddingInner` | `.padding_inner(..)` | `number \| number[]` | `0` | The gap between siblings, in points, per level from the top one down (the last for those below). |
| `paddingOuter` | `.padding_outer(..)` | `number \| number[]` | `0` | The room inside each group around its children, per level. |
| `paddingTop` | `.padding_top(..)` | `number \| number[]` | `0` | The band at the top of each group, for its `groupLabel`, per level; on all the siblings of a parent or none. |
| `cornerRadii` | `.corner_radii(..)` | `number \| { topLeft?, topRight?, bottomRight?, bottomLeft? }` | square | The radius of each corner of its rectangles. |
| `color` | `.color(..)` | `keyof T \| (d: T, index: number) => string` | none | The category of each node, which an `ordinal` `colorScale` gives a color. |
| `colorValue` | `.color_value(..)` | `keyof T \| (d: T, index: number) => number` | none | The number of each node, which a `sequential` or `diverging` `colorScale` makes its color. |
| `leafClass` | `.leaf_class(..)` | `string \| (d: T, index: number) => string` | none | The classes of each leaf (`fill-*`, `stroke-*`), the same on every leaf or a function of its row. |
| `leafStyle` | `.leaf_style(..)` | `StyleProp<ViewStyle>` | none | The style of every leaf, over its classes. |
| `groupClass` | `.group_class(..)` | `string \| (d: T, index: number) => string` | none | The classes of each group, a rectangle under its children; groups are drawn only with a class or a style. |
| `groupStyle` | `.group_style(..)` | `StyleProp<ViewStyle>` | none | The style of every group, over its classes. |
| `inactiveOpacity` | `.inactive_opacity(..)` | `number` (0 to 1) | none | The opacity of the nodes away from the hovered one, and of their labels, with the hover's fade. |
| `label` | `.label(..)` | `keyof T \| (d: T, index: number) => string` | none | The name in each leaf, on one line, cut with an ellipsis. |
| `valueLabel` | `.value_label(..)` | `(d: T, value: number, index: number) => string` | none | The value in each leaf, under its name, shown only where it fits whole. |
| `labelPlacement` | `.label_placement(..)` | `"start" \| "center"` | `"start"` | The labels at their leaves' top left, or in their middle. |
| `labelClass` | `.label_class(..)` | `string` | none | The classes of each leaf's label, a box as big as the leaf: its padding and text styles; `data-dark:` on dark leaves. |
| `labelStyle` | `.label_style(..)` | `StyleProp<TextStyle>` | none | The style of each leaf's label, over its classes. |
| `valueLabelClass` | `.value_label_class(..)` | `string` | none | The classes of the value line, over the label's. |
| `valueLabelStyle` | `.value_label_style(..)` | `StyleProp<TextStyle>` | none | The style of the value line, over its classes. |
| `groupLabel` | `.group_label(..)` | `keyof T \| (d: T, index: number) => string` | none | The name of each group, in its band, cut with an ellipsis. |
| `groupLabelClass` | `.group_label_class(..)` | `string` | none | The classes of each group's label, a box as big as the band. |
| `groupLabelStyle` | `.group_label_style(..)` | `StyleProp<TextStyle>` | none | The style of each group's label, over its classes. |
| `stagger` | `.stagger(..)` | `number` (0 to 0.95) | `0` | How the top-level nodes appear one after another: the share of the appear over which they start. |
| `hoverClass` | `.hover_class(..)` | `string` | none | The classes of the `hover` part, a view as big as the hovered node over it (`rounded-xs outline-2 outline-foreground`). |
| `hoverStyle` | `.hover_style(..)` | `StyleProp<ViewStyle>` | none | The style of the hover part, over its classes. |

A rectangle fills with `fill` (the `colorScale`'s color, else `currentColor`, where none is set) and strokes with
`stroke` (none where none is set), its own over the treemap's and the plot's as CSS inherits them. The layout runs
again only when the rows, the options or the plot's size change, never for the pointer or the appear; the plot's size
changing moves nothing. A repeated `id`, a `parent` that names no row and a row that is its own ancestor log a warning
once: the first row keeps the id, the orphan is a top-level node, the cycle is not drawn.

## PlotAxis

A `PlotAxis` labels an edge of the plot with the ticks of the scale that edge carries: the bottom and top edges the x
scale's, the left and right ones the y scale's, as d3's `axisBottom`, `axisTop`, `axisLeft` and `axisRight`. Its ticks
come from the scale: round values on a `linear` one (1, 2 or 5 times a power of ten, inside the domain), rows on a
`point` or `band` one. Its labels are texts the plot's layout places, so the app says what they read and how they
look, and the layout puts them in place: each label is centered on its tick along the edge. Along the bottom and top
edges, the first and last move inward just as far as they need to stay within the plot's ends; beside the left and
right edges, every label stays on its tick, so it reads as its grid line's, and where a label near an end would pass
the plot's top or bottom edge, the plot's linear y scales start that far in from it (half the label's height for a tick
at the end), so every label stays within the plot, on its grid line.

```tsx
import { Area, Grid, Line, Plot, PlotAxis } from "nsh/base/plot";

const rows = [
  { day: "Mon", visitors: 1820 },
  { day: "Tue", visitors: 2140 },
  { day: "Wed", visitors: 1960 },
  { day: "Thu", visitors: 2480 },
  { day: "Fri", visitors: 2310 },
];

<Plot data={rows} y="visitors" yScale={{ type: "linear", domain: [0, 3000] }} class="mb-6 ml-10 h-40">
  <Grid y={[0, 1000, 2000, 3000]} class="stroke-border" />
  <Area class="fill-chart-1/20" />
  <Line class="stroke-chart-1 stroke-2" />
  {/* 0, 1,000, 2,000 and 3,000 left of the plot; a day under each row. */}
  <PlotAxis placement="left" ticks={3} labelClass="pr-2 text-xs tabular-nums text-muted-foreground" />
  <PlotAxis
    format={(i) => rows[i].day}
    labelClass="pt-2 text-xs text-muted-foreground"
    tickClass="h-1 w-px bg-border"
    lineClass="h-px bg-border"
  />
</Plot>
```

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `placement` | `.placement(..)` | `"bottom" \| "top" \| "left" \| "right"` | `"bottom"` | The edge it runs along: the bottom and top edges carry the x scale's ticks, the left and right ones the y scale's. |
| `scale` | `.scale(..)` | `"y" \| "y2"` | `"y"` | The y scale a left or right axis labels: the plot's `yScale` or its second one, `y2Scale` ([Dual axes](#dual-axes)). |
| `labelPlacement` | `.label_placement(..)` | `"outside" \| "inside"` | `"outside"` | Where its labels sit: past the edge, in the room the app leaves around the plot, where they stay clear of the marks; or over the plot along the edge, so the plot keeps its whole size (beside a left or right edge, each label sits on its grid line's upper side). |
| `ticks` | `.ticks(..)` | `number` | `10` on a `linear` scale (every step of aligned scales), every row on the others | About how many ticks it takes: on a `linear` scale, round values inside the domain, about this many; on a `point` or `band` scale, this many rows spread evenly from the first to the last. |
| `tickValues` | `.tick_values(..)` | `number[]` | none | The values of its ticks, in place of `ticks`: values of the scale, row indices on a `point` or `band` scale (`[0, 3, 6]` labels every third row). The values inside the domain each get a tick. |
| `format` | `.format(..)` | `(value: number, index: number) => string` | a band's category on a band scale of categories, else the value, with the decimals the step between ticks needs, thousands grouped | The text of each tick: the app's function of its value (a row's index on a `point` or `band` scale) and its index among the axis' ticks. |
| `labelClass`, `labelStyle` | `.label_class(..)`, `.label_style(..)` | `string`, `StyleProp<TextStyle>` | none | The `label` part: a text per tick, its font, color and padding the app's; its padding toward the plot is its distance from the edge (`pt-2` under a bottom axis). |
| `tickClass`, `tickStyle` | `.tick_class(..)`, `.tick_style(..)` | `string`, `StyleProp<ViewStyle>` | none | The `tick` part: a view per tick on the edge, centered on its tick and reaching toward the labels (`h-1 w-px bg-border` under a bottom axis); shown once styled. |
| `lineClass`, `lineStyle` | `.line_class(..)`, `.line_style(..)` | `string`, `StyleProp<ViewStyle>` | none | The `line` part: a view along the whole edge, on the labels' side (`h-px bg-border` under a bottom axis); shown once styled. |

Outside, the labels sit in the plot's margin, as d3's axes sit in a chart's margins: the plot keeps the size the app
gives it, and the app gives it a margin on the axis' side as deep as the labels (`mb-6` for `pt-2 text-xs` labels
under it), or its parent padding there. Two axes on one edge each label their own values, in their own style: the
ends of a range faint and its middle firmer.

`format` is called once per tick when the ticks or the function change, in the next turn, never while the plot draws
or follows the pointer: keep it pure (the same value, the same text). Without it, a tick reads as d3 writes it:
`1,500`, `0.25`, `−2`. In Rust, `plot_axis()` makes an axis, its `format` a `TickFormat::from_fn(|value, index| ..)`.
An axis takes no pointer, and screen readers hear the plot rather than its labels.

## PlotLabel

A `PlotLabel` writes texts at points of the plot: a caption over a peak, a tag at a line's last point, a note at a
grid line's end. Each of its `texts` names its point with values of the plot's scales, as the marks do: a row's index
on a `point` or `band` scale (the middle of the row's band), a value on a `linear` one. The text's top edge sits on
the point, and its `align` starts it there, centers it on it or ends it there. The plot's layout places the texts, so
they follow the plot's size; they glide with the scales' domains (`motion.update`) and fade in with the appear.

```tsx
import { Area, Line, Plot, PlotLabel } from "nsh/base/plot";

const rows = [
  { day: "Mon", visitors: 1820 },
  { day: "Tue", visitors: 2140 },
  { day: "Wed", visitors: 1960 },
  { day: "Thu", visitors: 2480 },
  { day: "Fri", visitors: 2310 },
];
const [peak, last] = [3, rows.length - 1];

<Plot data={rows} y="visitors" yScale={{ type: "linear", domain: [0, 3000] }} class="mr-12 h-40">
  <Area class="fill-chart-1/20" />
  <Line class="stroke-chart-1 stroke-2" />
  {/* The peak's value over it, and a tag right of the last point, its middle at the point's height. */}
  <PlotLabel
    class="text-xs tabular-nums text-muted-foreground"
    texts={[
      { text: `High ${rows[peak].visitors}`, x: peak, y: rows[peak].visitors, align: "center", class: "-translate-y-full pb-1" },
      { text: `${rows[last].visitors}`, x: last, y: rows[last].visitors, class: "-translate-y-1/2 ml-2 rounded bg-chart-1 px-1.5 text-white" },
    ]}
  />
</Plot>
```

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `texts` | `.texts(..)` | `PlotText[]` | `[]` | The texts it writes, each at its own point. |
| `scale` | `.scale(..)` | `"y" \| "y2"` | `"y"` | The y scale its texts' `y` are values of ([Dual axes](#dual-axes)). |

Each text is a `PlotText`:

| Field | Type | Default | Description |
|---|---|---|---|
| `text` | `string` | | What it reads. |
| `x` | `number` | | Where it goes along the x axis: a value of the x scale, a row's index on a `point` or `band` scale (`0.5` is halfway between the first two rows). |
| `y` | `number` | | Where its top edge goes along the y axis: a value of the y scale. |
| `align` | `"left" \| "center" \| "right"` | `"left"` | How it sits along x from its point: starting at it, centered on it, or ending at it. |
| `class`, `style` | `string`, `StyleProp<TextStyle>` | none | The text's own classes and style, over what it inherits from the label: its box (a tag's background and padding) and its distance from the point. |

The look is the app's: the label's `class` gives every text the text styles they inherit (font, size, color), and a
text's own `class` and `style` style it alone. A text goes above its point with `-translate-y-full`, and its padding
is its gap from the point (`pb-1`); a tag beside a line's last point sits in the margin the app leaves on that side
(`mr-12`), as an axis' labels do. In Rust, `plot_label()` makes a label, each text a
`PlotText::new(text, x, y)` with `.align(PlotTextAlign::Center)`, `.class(..)` and `.style(..)`. The pointer passes
through the texts to the plot, and screen readers hear the plot, whose `accessibilityLabel` says what the texts
point out.

## Motion

Motion is the app's, and none by default: everything shows at once. `motion` takes the timings of
[`nsh`](https://nsh.dev/versions/main/modules/nsh.md#animation) (`{ duration, easing, delay }` and `{ stiffness, damping, mass }`):

| Key | Type | What moves |
|---|---|---|
| `appear` | timing | The marks draw in, with an `appearGeneration`: lines and areas from the leading edge, bars growing out of their base (one after another with a bar's `stagger`); dots growing from nothing (one after another with a dot's `stagger`); cells growing from their middles (one after another with a cell's `stagger`); a pie's and an arc's ring sweeps in clockwise from its start; a radial line grows out of its inner radius, its dots with it; a sankey's nodes and ribbons from the leading edge, its labels fading in. |
| `update` | timing | Marks move to the new shape when the app changes it: dots to their new values and sizes, a new row's dot growing in and a gone row's shrinking away; cells to their new colors (mixed in OKLab) and bands, a new row's cell growing in and a gone row's shrinking away; a pie's and an arc's radii, so a donut's hole opens and closes, and their angles, so a gauge or a slice sweeps round to its new value (d3's `arcTween`: the angles move, not the outline; a new slice opens from where the one before it ends; a change while one moves goes on from where it is drawn); a radial line's points to their new values, angles and radii (a new row growing out of the inner radius), a radial grid's rings with them; and a linear scale's domain, the app's `domain` or the extent of the marks' values as rows come, which glides from the old one to the new one, the marks, the grid lines, the `PlotAxis`es and the `PlotLabel`s with it; and a sankey's nodes, ribbons and labels, from the old flows' layout to the new one, a change while they move going on from where they are drawn. |
| `enter` | timing | The hover's parts fade in when the pointer comes over the plot. |
| `exit` | timing | They fade out after it leaves. |
| `pointer` | spring | They glide from one row to the next when the keys or a screen reader step the hover; a pie's slice lifts on it. |

The hover's parts follow the pointer in the same frame: as it moves, the cross line, the dots and the tooltip are on
the row under it at once, so they track the hand, while their fade in and out (`enter`, `exit`) still animates.

The motion runs on the platform's animator, with no JS per frame, and is complete at once for people who ask for
reduced motion. A plot that a list makes again for a row that comes back draws in again, unless a
[`PlotAppearScope`](#plotappearscope) around the list saw its appear finish.

A domain moves as d3 transitions a scale's domain: the scale in between places every value, so the marks keep their
shapes, the grid lines and the hover's parts move with them, bars keep their corners, and a row that comes in with the
new domain moves with the rest. A live chart that fits its y scale to its rows now and then (with some room, so the
grid holds still between fits) glides to each new fit with an `update` timing. When the plot's size changes, the marks
take the new size at once.

It is the plot's own motion, the timings of what a chart moves: its marks' clip and its hover's parts. A view's
entrances, exits and attention seekers are [`createMotion`](https://nsh.dev/versions/main/modules/nsh.md#createmotion)'s presets and
keyframes, which an app can still play on the plot's view or on the elements around it.

## PlotAppearScope

A list makes a row's plot again each time the row comes back into view, so a sparkline with an appear draws in again
whenever the list scrolls back to it. A `PlotAppearScope` around the list remembers the appears that have finished in
it: a plot made again there whose `appearGeneration` finished shows its marks whole at once.
A plot is remembered by its generation, so each row's plot gets its own, the row's key with whatever should replay it
(`` `${symbol} ${period}` ``).

```tsx
import { List } from "nsh";
import { Line, Plot, PlotAppearScope } from "nsh/base/plot";

<PlotAppearScope id={watchlist().id} class="flex-1">
  <List each={watchlist().rows} keyExtractor={(row) => row.symbol} estimatedItemSize={48} class="flex-1">
    {(row) => (
      <Plot
        data={row().closes}
        y="close"
        interactive={false}
        appearGeneration={`${row().symbol} ${period()}`}
        motion={{ appear: { duration: 400, easing: "easeOut" } }}
        class="h-8 w-24"
      >
        <Line class="stroke-chart-1 stroke-[1.5]" />
      </Plot>
    )}
  </List>
</PlotAppearScope>
```

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `id` | `.id(..)` | `number \| string` | none | What the scope remembers for: when it changes, the scope forgets and its plots draw in afresh, where they are. Name it after the content, such as a watchlist or a conversation; without one, the scope remembers for as long as it is shown. |
| `children` | `.child(..)` | `JSX.Element` | none | What it holds: the list, or whatever makes its plots again as they come and go. |

A new generation still draws the plot in, and so does a plot taken away before its appear finished, from the start.
Once a plot has finished a new generation, its scope forgets the one before, so switching back to an earlier period
draws the plot in again. The memory goes with the scope: a scope that is no longer shown, or one with a new `id`,
draws its plots in afresh, and a plot remembers in the innermost scope around it. Its look is the app's: `class` and
`style` lay it out as any view's (`flex-1` around a list that fills the screen). In Rust,
`plot_appear_scope()` makes one.

## Keyboard

An interactive plot is a stop of Tab (macOS, the web), and while it has the keyboard focus its keys move the same hover
the pointer does: the cross line, the dots and the tooltip glide on the `pointer` spring, a pie's slice lifts,
`onHoverChange` reports the row, and screen readers read the `accessibilityValue` the app gives for it. Its focus ring
is the app's: a `focus-visible:` class or a `focusStyle` (`focus-visible:outline-2 focus-visible:outline-ring`).

| Keys | What they do |
|---|---|
| Right, Left | Move to the row on that side: the next or the previous row, the other way round on a reversed x scale, whose first row is at the right (over a pie, its slices in the rows' order; over a sankey, its nodes; over a treemap, the leaf beside on the screen, as Up and Down do); with no row hovered, Right starts at the row at the left end and Left at the one at the right end (over a pie, the first and the last slice). |
| Home, End | Move to the first or the last row. |
| Up, Down | Over cells: move to the cell above or below in the same column. Over cells the keys follow the grid on the screen (WAI-ARIA's data grid): Right and Left move to the next cell along the line, Home and End to the line's first and last cell; with no cell hovered, the first key starts at the top left cell (Left, Up and End at the bottom right one). At an edge the hover stays. |
| Escape | Clears the hover. |

The plot answers its keys while it has the focus, and Escape while a row is hovered; the rest of the time they go to
the app and the views around it. Moving the focus away clears a hover the keys made. The plot takes no presses, so a
plot inside a pressable card leaves the card its presses. Screen readers step through the rows too: VoiceOver's
swipe up and down, TalkBack's scroll forward and back, and every screen reader that offers an element's `increment` and
`decrement` actions move to the next and the previous row, in the rows' order on a reversed scale as well.

## Building charts

A chart is a plot, its marks, its axes and the app's own elements around them. Give the y scale a `domain` and its axis
the grid's values (`tickValues`): each label then sits at its grid line. The hover's cross line, dots and tooltip are
the plot's parts, styled and filled by the app; the row's values go where the app shows them.

Grids read best as solid hairlines with a firmer baseline, which leaves a dashed line free to mean a reference value
(the opening price below). An area reads lighter as a wash that fades out toward its baseline than as a flat fill.
Each series' hover dot takes its series' color, and the color of the surface the chart sits on as its ring, so it
cuts out of its line, and the tooltip sits at the top of the plot, inside its edges at the first and last rows: a
`domain` with room above the highest value keeps it off the line.

```tsx
import { signal, Text, View } from "nsh";
import { Area, Grid, Line, Plot, PlotAxis } from "nsh/base/plot";

type Row = { time: string; price: number };

export function PriceChart(props: { rows: Row[]; low: number; high: number }) {
  const hovered = signal<number | null>(null);
  const shown = () => props.rows[hovered() ?? props.rows.length - 1];
  const middle = () => (props.low + props.high) / 2;
  return (
    <View class="gap-3 rounded-xl border border-border bg-card p-4">
      {/* The value of the row under the pointer, or the last one. */}
      <View class="flex-row items-baseline">
        <Text class="flex-1 text-sm text-muted-foreground">{shown().time}</Text>
        <Text class="text-right text-xl font-semibold tabular-nums text-foreground">{shown().price.toFixed(2)}</Text>
      </View>
      <Plot
        data={props.rows}
        y="price"
        yScale={{ type: "linear", domain: [props.low, props.high] }}
        accessibilityLabel={`Price, from ${props.rows[0].price} to ${props.rows[props.rows.length - 1].price}`}
        accessibilityValue={{ text: `${shown().time}, ${shown().price.toFixed(2)}` }}
        appearGeneration={props.rows.length}
        motion={{ appear: { duration: 600, easing: "easeOut" }, enter: { duration: 120 }, exit: { duration: 160 }, pointer: { stiffness: 300, damping: 30 } }}
        crossLineClass="w-px h-full bg-muted-foreground/50"
        tooltipOffset={4}
        tooltipContent={
          <View class="flex-row items-center gap-1.5 rounded-lg border border-border bg-popover px-2 py-1 shadow-md">
            <View class="h-0.5 w-2.5 rounded-full bg-chart-1" />
            <Text class="text-xs tabular-nums text-popover-foreground">{shown().price.toFixed(2)}</Text>
          </View>
        }
        onHoverChange={({ index }) => hovered.set(index)}
        class="mr-10 mb-6 h-48"
      >
        <Grid y={[middle(), props.high]} class="stroke-border" />
        {/* A wash that fades out toward the baseline. */}
        <Area backgroundClass="bg-linear-to-b from-chart-1/20 to-transparent" />
        <Grid y={[props.low]} class="stroke-muted-foreground/40" />
        <Grid y={[props.rows[0].price]} class="stroke-muted-foreground" style={{ strokeDasharray: "3 3" }} />
        <Line class="stroke-chart-1 stroke-2" hoverDotClass="size-2.5 rounded-full border-2 border-card bg-chart-1" />
        {/* The grid's values right of the plot, and the first and last times under it. */}
        <PlotAxis
          placement="right"
          tickValues={[props.low, middle(), props.high]}
          format={(v) => v.toFixed(0)}
          labelClass="pl-2 text-xs tabular-nums text-muted-foreground"
        />
        <PlotAxis
          tickValues={[0, props.rows.length - 1]}
          format={(i) => props.rows[i].time}
          labelClass="pt-2 text-xs text-muted-foreground"
        />
      </Plot>
    </View>
  );
}
```

A bar chart reads best with the tips of its bars rounded and their bases square (`cornerRadii={{ topLeft: 4,
topRight: 4 }}`; in a stack only on its top bar), a hair of room between the bars of a band (`groupPadding`), the
bars of the other rows muted while one is hovered (`inactiveOpacity`) and its band tinted (`crossLineClass`), and
the values in small tabular figures over the bars, with the total over a stack. With `paddingOuter` half of
`paddingInner`, the bands' middles fall at equal steps, and a `PlotAxis` centers each month under its band; a
`maxBandWidth` keeps a few bars narrow in a wide card.

```tsx
import { signal, Text, View } from "nsh";
import { Bar, Grid, Plot, PlotAxis } from "nsh/base/plot";

type Sale = { month: string; online: number; store: number };

export function SalesChart(props: { rows: Sale[]; stacked: boolean }) {
  const hovered = signal<number | null>(null);
  const shown = () => props.rows[hovered() ?? props.rows.length - 1];
  const tip = { topLeft: 4, topRight: 4 };
  return (
    <View class="gap-3 rounded-xl border border-border bg-card p-4">
      <View class="flex-row items-baseline">
        <Text class="flex-1 text-sm text-muted-foreground">{shown().month}</Text>
        <Text class="text-right text-sm tabular-nums text-foreground">{`${shown().online + shown().store}k`}</Text>
      </View>
      <Plot
        data={props.rows}
        xScale={{ type: "band", paddingInner: 0.3, paddingOuter: 0.15, maxBandWidth: 56, groupPadding: 0.1 }}
        yScale={{ type: "linear", domain: [0, 130] }}
        accessibilityLabel="Sales per month, online and in store"
        appearGeneration={props.stacked ? 1 : 0}
        motion={{ appear: { duration: 600, easing: "easeOut" }, enter: { duration: 150 }, exit: { duration: 150 }, pointer: { stiffness: 320, damping: 32 } }}
        crossLineClass="w-full h-full bg-foreground/5"
        onHoverChange={({ index }) => hovered.set(index)}
        class="mb-6 h-44"
      >
        <Grid y={[40, 80, 120]} class="stroke-border" />
        <Bar
          value="online"
          stack={props.stacked ? "sales" : undefined}
          cornerRadii={props.stacked ? 0 : tip}
          stagger={0.4}
          inactiveOpacity={0.45}
          label={props.stacked ? undefined : "online"}
          labelClass="pb-1 text-[11px] tabular-nums text-muted-foreground"
          class="fill-chart-1"
        />
        <Bar
          value="store"
          stack={props.stacked ? "sales" : undefined}
          cornerRadii={tip}
          stagger={0.4}
          inactiveOpacity={0.45}
          label={props.stacked ? (d) => String(d.online + d.store) : "store"}
          labelClass="pb-1 text-[11px] tabular-nums text-muted-foreground"
          class="fill-chart-2"
        />
        {/* A month centered under each band. */}
        <PlotAxis format={(i) => props.rows[i].month} labelClass="pt-2 text-xs text-muted-foreground" />
      </Plot>
    </View>
  );
}
```

A sparkline in a list row is a plot with `interactive={false}`: it draws its marks and follows no pointer.

## Accessibility

- A plot is one element for screen readers, with the image role and the app's `accessibilityLabel`; its marks, its
  axes' labels, its `PlotLabel`s and the hover's parts are parts of it and say nothing themselves. Say in the label what the chart shows and what stands out
  (the range, the highest value), and give `accessibilityValue` the words for the row under the pointer, so a screen
  reader says the value as it changes.
- The row under the pointer is reported with `onHoverChange` on platforms with a pointer (desktops, the web, an iPad
  with a trackpad). Touch screens report no hover: show the values a touch user needs in the app's own elements, or
  offer the rows as text or a list where the numbers matter.
- Over a pie the row reported is the slice's under the pointer: give `accessibilityValue` its name, value and share
  (`"Team, 340 seats, 34.0%"`), and say the total and the largest share in the label. Over a radar it is the axis
  nearest the pointer: give it the axis' name and each series' value there.
- An interactive plot is a stop of the keyboard focus whose arrow keys move the hover ([Keyboard](#keyboard)), and it
  offers screen readers `increment` and `decrement` to step through the rows (VoiceOver reads it as adjustable); a plot
  with `interactive={false}` is neither, and it takes no presses either way.

See [Accessibility](https://nsh.dev/versions/main/docs/accessibility.md) for labels and roles in general.

## Platform notes

- Every platform draws the marks the same way, from one drawing per mark recorded in Rust; a change of the rows draws
  the marks that read them again in one batch, and a change of a paint class (the appearance, `dark:`) sends the
  drawing again without recording it.
- The appear clips lines and areas, and grows bars, with values the platform's animator moves; a bar's fading away
  from the hovered row is an opacity the animator computes from the hover's place; the hover's parts are views the
  animator moves and fades, and it keeps the tooltip inside the plot from the plot's size and the tooltip's.
- An area's background is drawn in its own canvas, clipped to the area's shape, with the same gradient the platform
  draws for a view's `bg-linear-*`; a change of its classes (the appearance, `dark:`) sends the drawing again without
  recording it.
- A pie draws each slice in its own canvas; the slice under the pointer is found in Rust from the slices' angles and
  radii, its lift is a radius and the others' fade an opacity the animator moves, and the appear's sweep moves the
  slices' angles the same way, so neither records a drawing again.
- A radial line's row under the pointer is found in Rust from its points' angles; its hover dot is a view the animator
  places on the row under the pointer (gliding on the `pointer` spring as the keys step), and while it appears or moves to new values its points are numbers the animator moves
  from where they were, so the line is recorded once per change.
- A dot mark is drawn in one canvas; the dot under the pointer is found in Rust from the dots' centers and radii, and
  its hover dot is a view the animator places on it, as big as it; the appear's growth, a change's moves and the hover's
  fade are values the animator moves, so the dots are recorded once per change.
- A cell mark is drawn in one canvas; the cell under the pointer is found in Rust from the cells' boxes, and its hover
  cell is a view the animator places on it; the growth, a change's colors and moves and the hover's fade are values
  the animator moves, so the cells are recorded once per change. Each label is a text of the
  platform's, shown where its laid-out size fits inside its cell.
- An axis' labels, tick marks and line are the platform's own texts and views, placed by the layout in Rust from the
  plot's size and scales: they move with the marks when the plot's size changes, and a new domain writes the labels
  again.

Source: https://nsh.dev/versions/main/elements/plot

---

# Popover

A popover shows content next to its trigger, on top of everything else: details, a small form, a color picker.
Pressing the trigger opens and closes it; a press outside, Escape, the Android back button and VoiceOver's escape gesture close it. It is placed
on a side of the trigger, moves to the other side when there is no room, stays inside the safe area and follows the
trigger as it scrolls. It draws nothing of its own: the popup and its content are the app's.

```rust
use nsh_base::{OpenChangeReason, PopoverEvent, popover};
use nsh_core::prelude::*;

fn details() -> impl IntoElement {
    popover()
        .offset(px(6.0))
        .margin(px(8.0))
        .trigger(view().px_3().py_2().rounded_md().bg(rgb(0xe5e7eb)).child(text("Details")))
        .on_open_change(|e: &PopoverEvent| {
            if let PopoverEvent::OpenChange(open, OpenChangeReason::PressOutside) = e {
                log::info!("closed by a press outside: {open}");
            }
        })
        .child(
            view()
                .w(px(240.0))
                .gap_1()
                .p_3()
                .rounded_lg()
                .bg(white())
                .shadow_lg()
                .child(text("Order #1024").font_weight(FontWeight::SEMIBOLD))
                .child(text("Shipped yesterday, arriving Friday.")),
        )
}
```

```tsx
import { Text, View } from "nsh";
import { Popover } from "nsh/base";

function Details() {
  return (
    <Popover
      offset={6}
      margin={8}
      popupClass="w-60 gap-1 rounded-lg bg-white p-3 shadow-lg"
      trigger={
        <View class="rounded-md bg-gray-200 px-3 py-2">
          <Text>Details</Text>
        </View>
      }
    >
      <Text class="font-semibold">Order #1024</Text>
      <Text>Shipped yesterday, arriving Friday.</Text>
    </Popover>
  );
}
```

`Popover` comes from [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md). Its content is made each time it opens, so state inside it
starts fresh.

## Open state

Without `open`, the popover keeps its own state, starting from `defaultOpen`. With `open`, the app owns it: change it
in `onOpenChange({ open, reason })`, which reports every request to open or close with its reason (`"triggerPress"`,
`"pressOutside"`, `"cancel"`).

```tsx
const open = signal(false);

<Popover open={open()} onOpenChange={(e) => open.set(e.open)} trigger={<Text>Filters</Text>}>
  <FilterForm onApply={() => open.set(false)} />
</Popover>
```

`closeOnEscape={false}` keeps it open on Escape and back (`onCancel` still hears them, to ask first);
`closeOnPressOutside={false}` keeps it open on presses outside.

## Phones and desktops

A popover is anchored to its trigger on every device: what it shows belongs next to what opened it.

- On the desktops and in desktop browsers, a press outside closes it and goes on to what is under the pointer, so
  one click both closes the popover and presses the button it landed on.
- On phones and tablets, a press outside only closes it: a transparent backdrop takes the press, as the system's
  popovers do.

For a list of actions use a [Menu](https://nsh.dev/versions/main/elements/menu.md), which becomes a sheet on phones; for a panel use a [Sheet](https://nsh.dev/versions/main/elements/sheet.md).

## Entrance and exit

A popover comes and goes with your transitions. `popupStartingClass` is the popup's look in its first frame, and the
`transition-*` classes of `popupClass` carry it to its own look: its entrance. `popupEndingClass` is its look once
closed: the popover stays, taking no presses, while those transitions run, then goes, and `onClose` follows. Opened
again on its way out, it returns to its look from where it is. `popupStartingStyle` and `popupEndingStyle` do the same
with inline styles. When the user asks for less motion, it appears and goes at once.

```tsx
<Popover
  popupClass="rounded-lg bg-white p-3 shadow-lg transition-all duration-150 ease-out"
  popupStartingClass="opacity-0 scale-95"
  popupEndingClass="opacity-0 scale-95"
  onPosition={({ placement }) => side.set(placement)}
  trigger={<Text>Details</Text>}
>
  <OrderSummary />
</Popover>
```

`onPosition({ placement, bounds, available })` says where the popup went: the side of the trigger (the other one when
`placement` had no room), its frame and the room on that side, so an arrow or an entrance can point at the trigger.

## Props

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `open` | `.open(..)` | `boolean` | none | Open, controlled by the app. |
| `defaultOpen` | `.default_open(..)` | `boolean` | `false` | Open at first, without `open`. |
| `placement` | `.placement(..)` | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` | The side of the trigger it goes on. |
| `align` | `.align(..)` | `"start" \| "center" \| "end"` | `"center"` | How it lines up with the trigger along that side. |
| `offset` | `.offset(..)` | `number` | `0` | The gap between the trigger and the popup. |
| `margin` | `.margin(..)` | `number` | `0` | The distance it keeps from the edges of the safe area. |
| `closeOnEscape` | `.close_on_escape(..)` | `boolean` | `true` | Escape and the Android back button close it. |
| `closeOnPressOutside` | `.close_on_press_outside(..)` | `boolean` | `true` | A press outside closes it. |
| `popupClass`, `popupStyle` | `.popup_class(..)`, `.popup_style(..)` | `string`, `StyleProp<ViewStyle>` | none | The look of the popup, the box the content is in. |
| `popupStartingClass`, `popupStartingStyle` | `.popup_starting_class(..)`, `.popup_starting_style(..)` | `string`, `StyleProp<ViewStyle>` | none | The popup's look in its first frame, over its own: its transitions run from it. |
| `popupEndingClass`, `popupEndingStyle` | `.popup_ending_class(..)`, `.popup_ending_style(..)` | `string`, `StyleProp<ViewStyle>` | none | The popup's look once closed, over its own: it stays while its transitions run. |
| `trigger` | `.trigger(..)` | `JSX.Element` | none | What opens it; it is placed against it. While the popover is open its `aria-expanded:` classes and `expandedStyle` apply. |
| `children` | `.child(..)` | `JSX.Element` | none | The content. |

## Events

| Event | Rust | Description |
|---|---|---|
| `onOpenChange` | `.on_open_change(\|e\| ..)` | It opened or closed, with why: `"triggerPress"`, `"pressOutside"` or `"cancel"`. |
| `onOpen` | `.on_open(\|\| ..)` | It is shown. |
| `onClose` | `.on_close(\|\| ..)` | It is gone, after its exit; also when the app closed it. |
| `onCancel` | `.on_cancel(\|\| ..)` | The user tried to close it (Escape or back, a press outside), whether or not it closed. |
| `onPosition` | `.on_position(\|e\| ..)` | The popup was placed: `placement` (the side it went on), `bounds` (its frame), `available` (the room on that side). |

## Accessibility

The trigger tells screen readers whether the popover is expanded. Escape and the back button close it, as users expect
of a popup. In TSX the trigger is the element you pass, a `Button` or a view of your own: it takes the presses and the
expanded state itself, so its own `active:` classes and `activeStyle` show while it is pressed, and its own `onPress`
runs too.

Source: https://nsh.dev/versions/main/elements/popover

---

# Progress

A progress bar shows how far a task with a known extent is (a download, an upload, a step of a setup), or, while
`indeterminate`, that a task of unknown extent is under way. It owns what screen readers get, the progress bar role
with the range 0 to 100 and the value, and the indicator's width: `value` percent of the track's. The look is the
app's: a `Progress` has no colors, sizes, radii, motion or label of its own. It is made of a track with an indicator
inside it, then its children (a label, the value as text), and the app styles each part.

```rust
use nsh_base::{progress, theme};
use nsh_core::prelude::*;

fn upload(sent: Signal<f32>) -> impl IntoElement {
    progress()
        .value(sent)
        .accessibility_label("Uploading photos")
        .gap_2()
        .track_style(|s| s.h(px(8.0)).rounded_full().overflow_hidden().bg(move || theme().muted))
        .indicator_style(|s| s.h_full().rounded_full().bg(move || theme().primary))
        .child(
            text(move || format!("{:.0}%", sent.get()))
                .text_sm()
                .text_color(move || theme().muted_foreground),
        )
}
```

```tsx
import { mount, signal, Text } from "nsh";
import { Progress } from "nsh/base";

function App() {
  const sent = signal(40);
  return (
    <Progress
      value={sent()}
      accessibilityLabel="Uploading photos"
      class="gap-2"
      trackClass="h-2 overflow-hidden rounded-full bg-muted"
      indicatorClass="h-full rounded-full bg-primary"
    >
      <Text class="text-sm text-muted-foreground">{`${sent()}%`}</Text>
    </Progress>
  );
}

mount(App);
```

`Progress` comes from [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md), the `nsh-base` crate in Rust. The value is the app's: the
progress bar shows the `value` the app passes, held to 0 to 100. In Rust, `progress()` makes one with a setter per prop
(`.value(..)`, `.indicator_style(..)`), the typed style methods for the progress bar itself and `.child(..)` for its
label.

## Props

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `value` | `.value(..)` | `number` | `0` | How far the task is, as a percentage from 0 to 100 (outside the range, the nearest end). The indicator is that share of the track's width, and screen readers say it. |
| `indeterminate` | `.indeterminate(..)` | `boolean` | `false` | The task's extent is unknown: screen readers hear a progress bar with no value, and the indicator's width is the app's (`indicatorClass`). |
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | none | What screen readers say: what is in progress, when its children have no text that says it. |
| `trackClass`, `trackStyle` | `.track_style(\|s\| ..)` | `string`, `StyleProp<ViewStyle>` | none | The track, the part the indicator fills. |
| `indicatorClass`, `indicatorStyle` | `.indicator_style(\|s\| ..)` | `string`, `StyleProp<ViewStyle>` | none | The indicator, inside the track: its height, color and motion. |
| `children` | `.child(..)` | `JSX.Element` | none | The content after the track: a label or the value as text, which screen readers say. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The progress bar itself: the column (or row) around the track and the label. |

## Parts

| Part | Inside | Styled with |
|---|---|---|
| The progress bar | | `class`, `style` |
| The track | the progress bar, first | `trackClass`, `trackStyle` |
| The indicator | the track | `indicatorClass`, `indicatorStyle`; its width is `value` percent of the track's |
| The label | the progress bar, after the track | its own elements (`children`) |

The indicator starts at the track's leading edge; `overflow-hidden` and a radius on the track round its end with the
track's. A `w-*` class or a `width` in `indicatorStyle` takes the place of the value's width, which is how an
indeterminate bar gets its own.

## Indeterminate

While the extent is unknown, set `indeterminate` and give the indicator a width and motion of the app's. Motion is
the app's choice, and `motion-reduce:` keeps it still for people who ask for less motion:

```tsx
<Progress
  value={0}
  indeterminate={connecting()}
  trackClass="h-2 overflow-hidden rounded-full bg-muted"
  indicatorClass={
    connecting()
      ? "h-full w-1/3 rounded-full bg-primary animate-pulse motion-reduce:animate-none"
      : "h-full rounded-full bg-primary"
  }
/>
```

## Accessibility

- A progress bar is one element for screen readers, with the role `"progressbar"`, the range 0 to 100 and its value
  (VoiceOver and TalkBack say it as a percentage); the track and the indicator are parts of it. Its label is the text
  of its children; give `accessibilityLabel` when it has none.
- While `indeterminate`, it keeps the role and the range and has no value (in the browser: `aria-valuenow` is left out,
  as ARIA says an indeterminate progress bar is).
- It takes no presses and no keyboard focus: it reports, and the controls that start or stop the task are the app's.

See [Accessibility](https://nsh.dev/versions/main/docs/accessibility.md) for labels, roles and announcements in general.

## Platform notes

- Every platform draws what the app styles; the indicator's width follows `value` at once, and a change animates
  when the app animates it.
- Screen readers: VoiceOver (iOS, macOS) hears the value as a percentage and the bar as updating frequently;
  TalkBack, UI Automation (Windows), GTK's accessibility (Linux) and the browser (`aria-valuenow`) get the range and the
  value.

Source: https://nsh.dev/versions/main/elements/progress

---

# Radio

Radios offer a set of options the user picks exactly one of: a plan, a sort order, a theme. Each `Radio` owns the
behavior of one option: presses, keyboard activation, the disabled state, and the radio role and its checked state for
screen readers. A `RadioGroup` around them is the set, which screen readers announce as one group. The look is the
app's: a radio has no circle, dot, colors, sizes or label of its own. Its children are the app's indicator and label,
and `checked:` classes on the radio, or `group-checked:` classes on what is inside it, follow its state.

```rust
use nsh_base::{radio, radio_group, theme};
use nsh_core::prelude::*;

fn plans() -> impl IntoElement {
    let plan = signal("basic");
    let option = move |value: &'static str, label: &'static str| {
        let checked = move || plan.get() == value;
        radio()
            .checked(checked)
            .on_change(move |_: &bool| plan.set(value))
            .flex_row()
            .items_center()
            .gap_2()
            .child(
                view()
                    .size(px(20.0))
                    .items_center()
                    .justify_center()
                    .rounded_full()
                    .border_2()
                    .border_color(move || theme().border)
                    .child(
                        view()
                            .size(px(10.0))
                            .rounded_full()
                            .bg(move || theme().primary)
                            .opacity(move || if checked() { 1.0_f32 } else { 0.0 }),
                    ),
            )
            .child(text(label))
    };
    radio_group()
        .gap_3()
        .child(option("basic", "Basic"))
        .child(option("pro", "Pro"))
}
```

```tsx
import { mount, signal, Text, View } from "nsh";
import { Radio, RadioGroup } from "nsh/base";

function App() {
  const plan = signal("basic");
  const option = (value: string, label: string) => (
    <Radio
      checked={plan() === value}
      onChange={() => plan.set(value)}
      class="group flex-row items-center gap-2"
    >
      <View class="size-5 items-center justify-center rounded-full border-2 border-border group-checked:border-primary">
        <View class="size-2.5 rounded-full group-checked:bg-primary" />
      </View>
      <Text>{label}</Text>
    </Radio>
  );
  return (
    <RadioGroup class="gap-3">
      {option("basic", "Basic")}
      {option("pro", "Pro")}
    </RadioGroup>
  );
}

mount(App);
```

`Radio` and `RadioGroup` come from [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md), the `nsh-base` crate in Rust. The value is
the app's: the group holds none. Each radio is told whether it is checked; a press on an unchecked radio reports
`onChange({ checked: true })`, the app sets its value, and every radio shows the `checked` the app passes back. In Rust, `radio()`
and `radio_group()` make them, with a setter per prop (`.checked(..)`), a listener per event (`.on_change(..)`), the
typed style methods and `.child(..)` for their content.

## Props

### Radio

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `checked` | `.checked(..)` | `boolean` | `false` | Checked or not. A press on an unchecked radio reports `true` with `onChange`; the radio shows the value the app passes back. |
| `disabled` | `.disabled(..)` | `boolean` | `false` | No presses and no press feedback; `disabled:` styles apply, and screen readers say it is dimmed. |
| `checkedStyle` | `.checked_style(\|s\| ..)` | `StyleProp<ViewStyle>` | none | The radio's style while checked and not disabled, as `checked:` classes. |
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | none | What screen readers say: the option, when its children have no text that says it. |
| `hitSlop` | `.hit_slop(..)` | `number \| Partial<Edges>` | none | How far outside its bounds presses still count, in points: one number for every side, or the sides named. As a view's `hitSlop`. |
| `children` | `.child(..)` | `JSX.Element` | none | The app's indicator and label, which screen readers say. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The radio itself: the row around the indicator and the label. |
| `activeStyle`, `hoverStyle`, `focusStyle`, `disabledStyle` | `.active(\|s\| ..)`, `.hover(..)`, `.focus(..)`, `.disabled_style(..)` | `StyleProp<ViewStyle>` | none | The radio's style while pressed, hovered, focused or disabled, as the `<state>:` classes. |

### RadioGroup

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `children` | `.child(..)` | `JSX.Element` | none | The radios of the set, and whatever the app lays out between them. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The group's layout and look: a column by default, `flex-row` for a row. |

## Events

| Event | Rust | Description |
|---|---|---|
| `onChange` (`Radio`) | `.on_change(\|checked: &bool\| ..)` | An unchecked radio was pressed: a tap, a click, Space or Return while it has the keyboard focus, or a screen reader's activation; or an arrow key of its group moved the keyboard focus to it. It asks to be checked, so `checked` is `true`. It runs before anything changes: the radio shows the `checked` the app passes back. |

A checked radio stays checked and reports nothing, as a radio cannot uncheck itself; a disabled radio reports nothing
either.

## Parts

| Part | Inside | Styled with | States |
|---|---|---|---|
| The group | | `RadioGroup`'s `class`, `style` | |
| The radio | the group | `Radio`'s `class`, `style` | `checked:`, `disabled:`, `active:`, `hover:`, `focus:` (or `checkedStyle`, `disabledStyle`, ...) |
| The indicator and the label | the radio | their own elements (`children`) | `group-checked:`, `group-disabled:` and the other `group-*:` variants with `group` on the radio's `class` |

The indicator is the app's content: a ring with a dot, a check, a highlighted card. With `group` on the radio's
`class`, its `group-checked:` classes show the dot while the radio is checked.

## Disabled

A disabled radio takes no presses, and screen readers announce it as dimmed. Its `disabled:` classes apply over its
`checked:` ones, and `group-disabled:` classes inside it follow:

```tsx
<Radio
  checked={plan() === "team"}
  disabled={!eligible()}
  onChange={() => plan.set("team")}
  class="group flex-row items-center gap-2 disabled:opacity-50"
>
  <View class="size-5 items-center justify-center rounded-full border-2 border-border group-checked:border-primary">
    <View class="size-2.5 rounded-full group-checked:bg-primary" />
  </View>
  <Text>Team</Text>
</Radio>
```

## A small target with hitSlop

A radio with no label beside it (a dot in a table's row) can be smaller than a finger. `hitSlop` makes presses that land
near it count, in points past each side, without changing its layout or its look: one number for every side, or the
sides named (`{ top: 8, bottom: 8 }`), as a [view's `hitSlop`](https://nsh.dev/versions/main/elements.md#presses-and-feedback) takes them.

```tsx
<Radio
  checked={plan() === "team"}
  hitSlop={12}
  accessibilityLabel="Team"
  onChange={() => plan.set("team")}
  class="group size-5 items-center justify-center rounded-full border-2 border-border group-checked:border-primary"
>
  <View class="size-2.5 rounded-full group-checked:bg-primary" />
</Radio>
```

## Accessibility

- A radio is one element for screen readers, with the role `"radio"` and its state: checked or not, and selected while
  checked, since some screen readers read the one and some the other (UI Automation's radios are selection items). Its
  indicator and label are parts of it; its label is the text of its children, or `accessibilityLabel`.
- A `RadioGroup` has the role `"radiogroup"`: screen readers hear the radios inside it as one set, each still an
  element of its own.
- `disabled` is announced as the platform announces it (VoiceOver, TalkBack, UI Automation, the browser's accessibility
  tree).
- On macOS and the web a `RadioGroup` is one stop of the keyboard focus, and the arrow keys move between its radios
  and check them (below).

See [Accessibility](https://nsh.dev/versions/main/docs/accessibility.md) for labels, roles and announcements in general.

## Keyboard

On macOS and the web, where Tab reaches the views that take presses, a `RadioGroup` follows the
[WAI-ARIA radio group pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio/):

| Key | What it does |
|---|---|
| Tab, Shift+Tab | Enters the group at the checked radio (the first radio that is not disabled while none is), and leaves it in one step. |
| Down, Right | Moves the focus to the next radio, from the last to the first, and checks it. |
| Up, Left | Moves the focus to the previous radio, from the first to the last, and checks it. |
| Space | Checks the focused radio. |

The arrow keys skip disabled radios; the radio they move to asks to be checked with `onChange`, and the app checks it.
In a right-to-left layout Left and Right trade places: Left moves to the next radio and Right to the previous; Up and
Down keep theirs. `focus:` styles show where the focus is. A `Radio` outside a `RadioGroup` is a stop of its own, which Tab reaches
and Space and Return check.

## Platform notes

- iOS, Android and Mac Catalyst: a press is a tap that ends on the radio, its label included.
- Desktops (macOS, Windows, Linux, GPUI) and the web: a press is a click. On macOS and the web, Space and Return also
  check the radio that has the keyboard focus, and the arrow keys move it ([Keyboard](#keyboard)).
- Every platform draws what the app styles: the indicator, the label and their transitions.

Source: https://nsh.dev/versions/main/elements/radio

---

# Resizable

A resizable group lays out panels side by side or stacked, with a handle on each boundary between two of them: a
sidebar beside a document, an editor above its console, a list beside its detail. The user drags a handle to move the
boundary, and each panel stays within the sizes the app allows it. `ResizablePanelGroup` owns the behavior: the drag,
which runs natively frame by frame, how the room is shared, the resize cursor and a larger touch area for a finger.
The look is the app's: a handle is a band with no line, color or grip of its own, and what it draws is the app's
indicator; the panels are the app's views.

```rust
use nsh_base::{h_resizable, resizable_panel, theme};
use nsh_core::prelude::*;

fn workspace() -> impl IntoElement {
    h_resizable()
        .handle_style(|s| s.bg(move || theme().border()))
        .handle_accessibility_label("Resize the sidebar")
        .on_resize(|sizes: &Vec<Points>| log::info!("sizes: {sizes:?}"))
        .child(
            resizable_panel()
                .size(px(240.0))
                .size_range(px(160.0)..px(480.0))
                .p_4()
                .child(text("Files").text_color(move || theme().muted_foreground())),
        )
        .child(
            resizable_panel()
                .p_4()
                .child(text("Editor").text_color(move || theme().foreground())),
        )
}
```

```tsx
import { mount, signal, Text } from "nsh";
import { ResizablePanel, ResizablePanelGroup } from "nsh/base";

function App() {
  const sidebar = signal(240);
  return (
    <ResizablePanelGroup
      axis="horizontal"
      handleClass="bg-border group-hover:bg-ring group-active:bg-primary"
      handleAccessibilityLabel="Resize the sidebar"
    >
      <ResizablePanel size={sidebar()} minSize={160} maxSize={480} onResize={({ size }) => sidebar.set(size)} class="p-4">
        <Text class="text-muted-foreground">Files</Text>
      </ResizablePanel>
      <ResizablePanel class="p-4">
        <Text class="text-foreground">Editor</Text>
      </ResizablePanel>
    </ResizablePanelGroup>
  );
}

mount(App);
```

`ResizablePanelGroup` and `ResizablePanel` come from [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md), the `nsh-base` crate in
Rust. The panels are the group's direct children. In Rust, `h_resizable()` and `v_resizable()` make a group along each
axis (`resizable_panel_group().axis(..)` takes the axis as a value) and `resizable_panel()` a panel, with a setter per
prop, a listener per event, the typed style methods and `.child(..)` for their content; `.size_range(min..max)` sets
both limits at once.

## Sizes

A panel's `size` is the size it wants, within its `minSize` and `maxSize`. The panels without one share what is left
evenly, whatever their content; when every panel has a size, the room left over is shared in proportion to them.
While the user drags a handle, the group moves the room between the panels in the core, with no JS on the way:

- Growing the panel before the handle takes room from the panels after it, nearest first, each down to its `minSize`,
  passing over `fixed` ones.
- Shrinking it below its `minSize` takes room from the panels before it.
- No panel grows beyond its `maxSize`, and the panels never add up to more than the group.

When a drag ends having changed the sizes, the group reports every visible panel's size, in the order they are laid
out (`onResize` on the group), and each panel whose size changed reports its own (`onResize` on the panel). The panels
a drag moved keep the user's sizes until the app passes a new `size`; the app keeps them beyond the group's life by
passing the reported sizes back as `size`, so a layout it restores from [storage](https://nsh.dev/versions/main/modules/nsh.md#storage) opens at
the sizes the user left. Only drags and screen readers' steps report: a window resized or a panel shown or hidden
reports nothing.

When the group grows or shrinks (the window is resized), the panels with a size keep it and the panels without one
take the difference. When the group is too small for the sizes, the panels shrink, `fixed` ones (a sidebar, an
inspector) aside, and they come back to their sizes when the room returns. A panel with `visible={false}` takes no
room: the others share its space, and it comes back at its size when it shows again.

```tsx
<ResizablePanelGroup axis="vertical" handleClass="bg-border">
  <ResizablePanel>
    <Editor />
  </ResizablePanel>
  <ResizablePanel size={180} minSize={120} fixed visible={consoleOpen()}>
    <Console />
  </ResizablePanel>
</ResizablePanelGroup>
```

## Handles

There is a handle on each boundary between two visible panels: a band 9 points thick across the axis, centered on the
boundary, with the resize cursor of its axis. On touch screens its touch area reaches 10 points further on either
side, so a one-point line is still easy to grab. The handle is a `group`: what it draws is the app's indicator, styled
with `handleClass` / `handleStyle`: 1 point across and the boundary's full length, so `bg-border` alone is a hairline on
either axis, and `w-[3px]` or `h-[3px]` thickens it, and its `group-hover:` and `group-active:` classes follow
the pointer over the band and the press or drag. For more than a line (a grip of dots, an icon), `renderHandle` renders
the indicator's content, told the handle's `index`, `axis` and `state`; it is drawn again when the state changes, a
few times per drag, never on every move. A grip that animates is the handle's thumb (`handleThumbClass` /
`handleThumbStyle`): one view centered on the line, drawn upright and turned a quarter on a horizontal line so one class
serves both axes, which `group-hover:` and `group-active:` classes show and transition; the handle stays pressed for
the whole drag, wherever the pointer goes.

```tsx
<ResizablePanelGroup
  handleClass="w-[3px] items-center justify-center bg-border"
  renderHandle={(handle) => (
    <View class={handle.state === "dragging" ? "h-8 w-1 rounded-full bg-primary" : "h-6 w-1 rounded-full bg-muted-foreground"} />
  )}
>
  {/* panels */}
</ResizablePanelGroup>
```

`disabled` keeps every handle where it is (a locked layout).

## Props

### ResizablePanelGroup

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `axis` | `h_resizable()`, `v_resizable()`, `.axis(..)` | `"horizontal" \| "vertical"` | `"horizontal"` | Side by side (the handles are dragged left and right) or stacked (up and down). |
| `disabled` | `.disabled(..)` | `boolean` | `false` | No drags: the handles stay where they are. |
| `handleClass`, `handleStyle` | `.handle_style(\|s\| ..)` | `string`, `StyleProp<ViewStyle>` | none | Each handle's indicator, on the boundary in the handle's band: 1 point across the axis and the boundary's full length unless it says otherwise (`w-[3px]`, `h-[3px]`); `group-hover:` and `group-active:` follow the band. |
| `handleThumbClass`, `handleThumbStyle` | `.handle_thumb_class(..)`, `.handle_thumb_style(\|s\| ..)` | `string`, `StyleProp<ViewStyle>` | none | Each handle's thumb: a grip centered on the line, drawn upright as on a vertical line and turned a quarter on a horizontal one, so one class serves both axes. It stays the same view while the handle is hovered, pressed and dragged, so `group-hover:` and `group-active:` classes transition it (`h-11 w-[3px] rounded-full bg-muted-foreground opacity-0 scale-y-0 transition group-hover:opacity-40 group-hover:scale-y-[0.45] group-active:opacity-90 group-active:scale-y-100`). |
| `renderHandle` | `.render_handle(\|handle\| ..)` | `(handle: ResizeHandleContext) => JSX.Element` | none | What is inside each indicator, drawn again when the handle's `state` changes. |
| `handleAccessibilityLabel` | `.handle_accessibility_label(..)` | `string` | none | What screen readers say for each handle: what it resizes. They adjust it 10 points at a time. |
| `children` | `.child(..)` | `JSX.Element` | none | The `ResizablePanel`s, its direct children. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | `size-full` | The group itself; it fills its parent unless its class says otherwise. |

### ResizablePanel

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `size` | `.size(..)` | `number` | none | The length it wants along the group's axis, in points, within `minSize` and `maxSize`; a new value resizes it. Without one it shares what is left. |
| `minSize` | `.min_size(..)`, `.size_range(..)` | `number` | `100` | The smallest it gets. |
| `maxSize` | `.max_size(..)`, `.size_range(..)` | `number` | no limit | The largest it gets. |
| `fixed` | `.fixed(..)` | `boolean` | `false` | Keeps its size when the group is too small for the panels; dragging its own handle still resizes it. It takes a `size`. |
| `visible` | `.visible(..)` | `boolean` | `true` | Hidden, it takes no room and the others share its space. |
| `children` | `.child(..)` | `JSX.Element` | none | Its content. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The panel's own surface. Its size along the axis is the group's. |

### ResizeHandleContext

| Field | Type | Description |
|---|---|---|
| `index` | `number` | The boundary after the `index`th visible panel. |
| `axis` | `"horizontal" \| "vertical"` | The axis it resizes along. |
| `state` | `"idle" \| "hovered" \| "pressed" \| "dragging"` | How far the pointer or finger has gone with it. |

## Events

| Event | Rust | Description |
|---|---|---|
| `onResize` (`ResizablePanelGroup`) | `.on_resize(\|sizes: &Vec<Points>\| ..)` | A drag ended and moved a handle, or a screen reader adjusted one: `sizes`, every visible panel's size, in the order they are laid out (left to right, top to bottom). |
| `onResize` (`ResizablePanel`) | `.on_resize(\|size: &Points\| ..)` | A drag ended and changed this panel's size: `size`, the new one, to pass back as its `size`. |

## Parts

| Part | Inside | Styled with | States |
|---|---|---|---|
| The group | | `ResizablePanelGroup`'s `class`, `style` | |
| A panel | the group | `ResizablePanel`'s `class`, `style` | |
| A handle's indicator | the handle's band, on a boundary | `handleClass`, `handleStyle`, `renderHandle` | `group-hover:` under a pointer, `group-active:` while pressed or dragged; `state` in `renderHandle` |
| A handle's thumb | centered on a handle's line | `handleThumbClass`, `handleThumbStyle` | `group-hover:`, `group-active:` (pressed until the drag ends) |

## Accessibility

- Each handle is an adjustable element for screen readers, with `handleAccessibilityLabel` as its label. Its value
  is the size of the panel before it, within that panel's `minSize` and `maxSize`.
- Swiping up or down on a handle with VoiceOver, or TalkBack's volume keys, moves it 10 points, as a drag would; the
  group reports it with `onResize`. A `disabled` group's handles stay where they are.
- The panels' content is the app's and is read as it is anywhere else.

See [Accessibility](https://nsh.dev/versions/main/docs/accessibility.md) for labels, roles and announcements in general.

## Platform notes

- Desktops (macOS, Windows, Linux, GPUI) and the web: the pointer over a handle shows the column or row resize cursor,
  and a drag with the mouse or a touchpad moves the boundary.
- iOS, Android and Mac Catalyst: a finger drags the handle, within a touch area 10 points wider on either side than
  the band.
- In right-to-left layouts the panels and their sizes follow the layout's order.
- Every platform draws what the app styles: the indicators and the panels.
- [Dock](https://nsh.dev/versions/main/elements/dock.md)'s splits are resizable groups: they are resized the same way.

Source: https://nsh.dev/versions/main/elements/resizable

---

# RichEditor

`RichEditor` is a rich text editor built after ProseMirror's architecture. The app defines what a document is made
of with a schema (paragraphs, headings, lists, mentions, whatever node and mark types it needs), and the editor keeps
every document valid against it. Changes are steps grouped into transactions, so they undo, map positions and travel
as JSON; behavior comes from plugins (history, keymaps, input rules, Markdown shortcuts, the app's own); commands are
values a toolbar runs and asks about. The editor's state, its commands and its plugins run in Rust: typing, key
bindings and input rules never wait for JS, and the app reads the state as JSON when it asks for it.

An editor has two parts: the session (`createRichEditor`), which owns the state and which the app's code drives, and
the view (`<RichEditor editor={…} />`), which renders the session natively and turns the platform's input into
transactions. Several views can show one session.

The editor's kernel is a Rust port of [ProseMirror](https://prosemirror.net) by Marijn Haverbeke, and its extension
layer follows [Tiptap](https://tiptap.dev): their data structures, commands and names carry over, and so does what
you know of them. Both are MIT-licensed, and their licenses apply to what is ported from them.

```tsx
import { mount } from "nsh";
import { RichEditor, createRichEditor, history, inputRules, keymap, markdown, markdownRules, starterKeymap, baseKeymap, toggleMark } from "nsh/base";

const editor = createRichEditor({
  content: "# Notes\n\nStart typing…",
  format: "markdown",
  plugins: [
    history(),
    keymap({ "Mod-b": toggleMark("bold"), "Mod-i": toggleMark("italic") }),
    starterKeymap(),
    baseKeymap(),
    inputRules(markdownRules()),
    markdown(),
  ],
});

function App() {
  return <RichEditor editor={editor} class="flex-1" />;
}

mount(App);
```

Without `schema` an editor uses the starter schema (`starterSchema()`); without `plugins` it gets the starter kit
(`starterKit()`: the starter's input rules and key bindings, the base key bindings and the history). An empty
`plugins` array makes an editor with no plugins at all.

## Styling

The editor draws the document with the app's look: `classes` and `styles` style its parts (`root`, `content`, `caret`,
`selection`, `placeholder`, `composition`, `selectedNode`, `listMarker`, and for tables `selectedCell`,
`tableGrip`, `tableResizeHandle`, `tableDropIndicator`), its nodes by type (`nodes: { heading:
"text-2xl font-bold", "heading[level=2]": "text-xl" }`) and its marks (`marks: { bold: "font-bold" }`). The items of
lists whose node spec sets `extra.listMarker` to `"bullet"` or `"ordered"` (the starter schema's lists) show a marker
in the `listMarker` part: `•`, `◦`, `▪` by depth, or numbers from the list's `start`, placed before the item, in the list's indent (`pl-6` on the list, as a browser indents `ul`).

```tsx
<RichEditor
  editor={editor}
  classes={{
    nodes: { heading: "text-2xl font-bold", bulletList: "pl-6", codeBlock: "font-mono bg-muted p-3 rounded-md" },
    marks: { bold: "font-bold", italic: "italic", code: "font-mono bg-muted" },
    listMarker: "text-muted-foreground",
  }}
/>
```

The `content` part is the box of the document inside the editor's scroll view: its padding (`content: "px-6 py-5"`)
is the room around the text, and the scroll bar runs along the editor's own edge. A drag that selects past the top
or bottom of the editor scrolls the document along, faster the further the pointer goes.

### Bubble menu

`bubbleMenu` is Tiptap's bubble menu: the app's content shown next to the selection, above it by default
(`bubbleMenuPlacement`, flipping to the other side where there is no room) at `bubbleMenuOffset` points (8), in an
overlay that follows the text as it scrolls. The app passes it while it wants it shown, from the session's state:

```tsx
const revision = signal(editor.revision);
editor.on("revision", ({ revision: r }) => revision.set(r));
const inLink = () => (revision(), editor.isActive("link"));

<RichEditor
  editor={editor}
  bubbleMenu={inLink() ? <LinkMenu href={editor.getAttributes("link").href} /> : undefined}
  bubbleMenuPlacement="bottom"
/>
```

A link menu edits the link under the caret with `chain([extendMarkRange("link"), command("setLink", { href })])`
and removes it with `command("unsetLink")` after the same `extendMarkRange`.

## Schemas

`defineSchema(spec)` reads a schema in ProseMirror's shape and throws with what is wrong in it. Node types name their
`content` (a content expression: `"inline*"`, `"paragraph+"`, `"(heading | paragraph) block*"`), their `group`,
whether they are `inline` or an `atom`, the `marks` they allow and their `attrs` with defaults and validation
(`"string"`, `"number"`, `"boolean"`). The first block type is the default one: what Enter creates and what fills
required content. Keys a spec does not know are kept as the type's extra data, for frameworks built on the editor.

```tsx
import { createRichEditor, defineSchema } from "nsh/base";

const schema = defineSchema({
  nodes: {
    doc: { content: "block+" },
    paragraph: { content: "inline*", group: "block" },
    mention: { group: "inline", inline: true, atom: true, attrs: { id: {}, label: { default: "" } } },
    text: { group: "inline" },
  },
  marks: { bold: {}, link: { attrs: { href: {} }, inclusive: false } },
});

const editor = createRichEditor({ schema, doc: schema.parse("Hello") });
```

A `RichSchema` reads and writes documents: `parse(content, format?)` (plain text by default, `"markdown"`, or JSON),
`parseMarkdown(markdown)`, `serialize(doc, format?)` (Markdown by default, `"text"`, `"json"`) and `check(doc)`, which
returns the document with its attribute defaults filled in. `nodes`, `marks` and `topNode` name its types. Markdown
maps to the starter schema's names (`paragraph`, `heading`, `blockquote`, `codeBlock`, `bulletList`,
`orderedList`, `listItem`, `bold`, `italic`, `code`, `link`, `strike`).

## Commands

A command is a value: `toggleMark("bold")` makes an object the app keeps, binds to keys and passes to the editor.
`editor.run(command)` runs it and returns whether it applied; `editor.can(command)` asks without changing anything,
which is how a toolbar enables its buttons. `editor.isActive(name, attrs?)` tells whether a mark or a node is active
at the selection (`isActive("heading", { level: 2 })`).

| Command | What it does |
| --- | --- |
| `toggleMark(name, attrs?)` | Adds the mark to the selection, or removes it where present; at a cursor, for the text typed next |
| `setMark(name, attrs?)` / `unsetMark(name)` | Adds or removes a mark |
| `setBlockType(name, attrs?)` | Makes the selected textblocks of a type (`setBlockType("heading", { level: 2 })`) |
| `wrapIn(name, attrs?)` / `lift()` | Wraps the selected blocks in a node (a quote) / lifts them out of their parent |
| `wrapInList(name, attrs?)` | Wraps the selected blocks in a list |
| `splitListItem(name)` / `sinkListItem(name)` / `liftListItem(name)` | Splits, indents or outdents list items |
| `undo()` / `redo()` | Undoes or redoes a change (with `history()`) |
| `selectAll()`, `setTextSelection(anchor, head?)`, `setNodeSelection(pos)` | Selects |
| `insertText(text)`, `insertContent(content, format?)` | Inserts text or content over the selection |
| `setNodeAttribute(pos, attr, value)` | Sets an attribute of the node at a position, as one undoable change |
| `command(name)` | A command without parameters by name: `"splitBlock"`, `"joinBackward"`, `"exitCode"`, `"newlineInCode"`, `"selectParentNode"`, … |
| `chain(commands)` | Runs commands one after another as one transaction (one undo step); applies only when every one does |
| `first(commands)` | Runs the first command that applies |

```tsx
editor.run(chain([setBlockType("heading", { level: 1 }), toggleMark("bold")]));
const canIndent = editor.can(sinkListItem("listItem"));
```

## The session

| Member | What it is |
| --- | --- |
| `state`, `doc`, `selection` | The state, the document and the selection as JSON, made when read |
| `revision` | How many transactions the state has applied |
| `isEmpty`, `undoDepth`, `redoDepth`, `composing` | What a UI shows about the editor |
| `setContent(content, format?)` | Replaces the document, as one undoable change |
| `insertContent(content, format?)` | Inserts content over the selection |
| `getJSON()`, `getMarkdown()`, `getText()`, `textBetween(from?, to?, separator?)` | The document in a format |
| `dispatch(tr)` | Applies a transaction given as JSON (its steps against the current document) |
| `on(event, listener)` | Calls `listener` with the payload of every `event`, in JS's next turn: `revision` (`{ revision }`, after every change, from any source), `update`, `selectionUpdate`, `transaction`, `focus`, `blur`, `delete`. Returns a function that stops it; a listener added while a component renders stops with the component |
| `focus()`, `blur()` | Moves the keyboard focus to or from the views showing the editor |

Positions count as ProseMirror's do: a text counts its UTF-16 code units, a leaf node one, a node with content its
two boundaries. Anything that must outlive edits keeps an id in a node's attributes or a mark. A position query
(`resolve(pos)`, `nodeAt(pos)`, `coordsAtPos(pos)`, `findParentNode(name, pos)`, ...) throws a `RangeError` for a
position outside the document (`0` to `doc.content.size`), as ProseMirror's `resolve` does, and answers `null` where
nothing is there (`nodeAt` at the end of a node, `coordsAtPos` with no view showing the editor). `run` and `can` throw
a `TypeError` for a command, node or mark type the editor does not know.

### Taking over transactions

`editor.dispatchTransaction = (tr) => { … }` makes the app commit every transaction itself: the handler gets each
one as JSON and commits it with `editor.applyTransaction(tr)`, or drops it. Collaboration, logging and transactions
that must pass the app's checks use it; `null` hands committing back to the editor. The handler hears typing in JS's
next turn, and the document changes when it commits.

## Extensions

Extensions are Tiptap's: each one brings, together, its node or mark type, its key bindings, input and paste rules,
plugins and named commands, and an editor made from extensions gets its schema, keymap, rules and command table from
them. The built-in ones are classes named as Tiptap's, used as they are or configured:

```tsx
import { RichEditor, StarterKit, Underline, command, createRichEditor } from "nsh/base";

const editor = createRichEditor({
  extensions: [StarterKit.configure({ heading: { levels: [1, 2, 3] }, codeBlock: false })],
  content: "Hello",
  editable: true,
});

editor.run(command("toggleHeading", { level: 2 }));
editor.run(command("toggleBold"));
```

`StarterKit` brings `Document`, `Paragraph`, the text node, `Heading`, `Blockquote`, `BulletList`, `OrderedList`,
`ListItem`, `TaskList`, `TaskItem`, `CodeBlock`, `HardBreak`, `HorizontalRule`, `RichImage` (Tiptap's `Image`),
`Bold`, `Italic`, `Strike`, `Code`, `Underline`, `RichLink` (Tiptap's `Link`), `Highlight`, `Subscript`, `Superscript`, `RichTextStyle` (Tiptap's `TextStyle`),
`TextAlign`, `History`, `TrailingNode`, `Typography` and `ListKeymap`. An option named as one set to `false` leaves
it out, an object configures it (`heading: { levels }`, `history: { depth }`, `textAlign: { types }`,
`codeBlock: { enableTabIndentation }`). Each class's `configure(options)` and `extend({...})` make a
`RichExtension`, which has `name`, `type`, `priority` and `options`. Every editor also gets the core keymap (Enter,
Backspace, Delete, select all).

Each extension adds Tiptap's commands, which `command(name, args)` runs: `toggleBold`, `setItalic`,
`unsetStrike`, `toggleHeading({ level })`, `setParagraph`, `toggleBlockquote`, `toggleBulletList`,
`toggleOrderedList`, `toggleTaskList`, `toggleCodeBlock({ language })`, `setHardBreak`, `setHorizontalRule`,
`setImage({ src })`, `toggleHighlight({ color })`, `setTextAlign("center")`, `unsetTextAlign`, and the link,
character count and suggestion commands below.

The list toggles work on whole lists, as a word processor's list buttons do: `toggleOrderedList` in a bulleted list
numbers it at every level, nested lists included, and a list's own toggle takes the selected blocks out of every
list around them.

The order of `extensions` is their priority among equals: an extension listed later binds its keys before the ones
before it; `priority` (100 by default) ranks them otherwise. With `extensions`, an editor's `plugins` come after the
extensions' plugins.

### The app's extensions

`defineExtension` makes one. Its functions run once, when an editor is made with it, with the extension's options,
and return data: commands, rules and plugins as the factories above make them.

```tsx
import { StarterKit, command, createRichEditor, defineExtension, insertText, textRule } from "nsh/base";

const Signature = defineExtension({
  name: "signature",
  priority: 200,
  addOptions: () => ({ text: "— Sent from NSH" }),
  addCommands: (options) => ({ insertSignature: insertText(options.text) }),
  addKeyboardShortcuts: () => ({ "Mod-Alt-s": command("insertSignature") }),
  addInputRules: () => [textRule("\\(sig\\)$", "✍")],
});

const editor = createRichEditor({ extensions: [StarterKit, Signature.configure({ text: "Best, Ana" })] });
```

`node` or `mark` (in `defineSchema`'s form) makes it a node or mark extension; `addGlobalAttributes` adds attributes
to other types; `addProseMirrorPlugins` returns plugins, `RichEditorPlugin`s included; `addPasteRules` returns
`textRule` and `markRule` rules for pasted text. A built-in class's `extend({...})` replaces the parts it gives:
`Underline.extend({ addKeyboardShortcuts: () => ({ "Mod-Alt-u": toggleMark("underline") }) })`.

An app's crate registers extensions written in Rust through its UI set, and JS takes them by name:

```rust
use nsh_base::rich_editor::extensions::{Extension, RichExtensionRegistry};

#[native_module("app/native")]
fn native(registry: &mut Registry) {
    registry.rich_extension("mention", || Extension::new("mention") /* .add_plugins(...) */);
}
```

```tsx
const editor = createRichEditor({ extensions: [StarterKit, richExtension("mention", { char: "@" })] });
```

`richExtension(name, options)` also finds every built-in extension by its name (`"text"`, `"bold"`, ...).

## Plugins

| Factory | What it adds |
| --- | --- |
| `history({ depth?, newGroupDelay? })` | Undo history; changes within `newGroupDelay` milliseconds (500) undo together |
| `keymap(bindings)` | Commands by key name: `"Mod-b"` (Cmd on Apple platforms, Ctrl elsewhere), `"Shift-Enter"`, `"Alt-ArrowUp"` |
| `baseKeymap()` | Enter, Backspace, Delete, select all and the platform's text editing keys |
| `starterKeymap()` | The starter schema's bindings: marks, headings, lists, code blocks, hard breaks |
| `inputRules(rules)` | Text typed before the cursor that matches a rule turns into what the rule makes; Backspace right after undoes it |
| `markdown(options?)` | Markdown as you type, Markdown paste and Markdown copy (`blockRules`, `inlineRules`, `paste`, `copyAsMarkdown`) |
| `starterKit()` | The starter's input rules and bindings, the base bindings and the history |

A plugin's place in the list is its priority: keymaps and input rules earlier in the list handle a key or a text
first. Input rules come from `markdownRules()` (headings, quotes, lists, code fences, rules, the common marks),
`typographyRules()` (smart quotes, ellipsis, em dash), `textRule(match, replacement)`, `markRule(match, mark)`,
`wrappingRule(match, node)` and `textblockRule(match, node)`. A rule's `match` is a regular expression ending in `$`,
matched against the text before the cursor.

### The app's plugins

`new RichEditorPlugin(key)` makes a plugin whose behavior is the app's, set with chained calls:

```tsx
import { RichEditorPlugin, createRichEditor, starterKit } from "nsh/base";

const suggestions = new RichEditorPlugin("suggestions")
  .captureKeys(["ArrowUp", "ArrowDown", "Enter", "Escape"], (key) => moveSuggestion(key))
  .filterTransaction((tr) => tr.meta?.locked !== true)
  .appendTransaction((trs, state) => null);

const editor = createRichEditor({ plugins: [starterKit(), suggestions] });

// While the suggestion list is open, its keys are the list's.
suggestions.capturing = true;
editor.setDecorations("suggestions", [{ from: 5, to: 9, kind: "inline", attrs: { class: "bg-accent" } }]);
```

- `captureKeys(keys, handler)`: while `capturing` is true the editor consumes these keys and tells `handler` which
  one was pressed, right after; the keyboard stays as quick as with no plugin.
- `editor.setDecorations(key, decorations)`: inline attributes, node attributes and widgets the view draws over the
  document without changing it. They follow every change until set again.
- `filterTransaction(hook)` and `appendTransaction(hook)` see the transactions the app's own calls make (`run`,
  `dispatch`, `setContent`, …) in that call: `filterTransaction` may drop one, `appendTransaction` may return one
  more to apply with it. `on("revision", …)` hears every change, typing included.

## Links, character counts and suggestions

Three plugins carry Tiptap's Link, CharacterCount and Suggestion behavior, all of it native:

```tsx
import { RichEditor, characterCount, createRichEditor, insertMention, link, starterKit, starterSchema, suggestion, withMention } from "nsh/base";

const editor = createRichEditor({
  schema: withMention(starterSchema()),
  plugins: [
    starterKit(),
    link({ defaultProtocol: "https" }),
    characterCount({ limit: 280 }),
    suggestion({ key: "mention", char: "@", decorationClass: "text-primary", captureKeys: ["ArrowUp", "ArrowDown", "Enter"] }),
  ],
});

editor.on("transaction", () => {
  const s = editor.suggestion("mention");
  if (s?.active) showPeople(s.query, editor.coordsAtPos(s.range.from), s.lastKey);
  setCount(`${editor.characters()} / ${editor.characterLimit}`);
});

// The list picked someone:
editor.run(insertMention(editor.suggestion("mention")!.range, "u1", "Joan"));
```

- `link(options?)`: a URL typed before a space or Enter becomes a link, as do the URLs in pasted text (`autolink`);
  a URL pasted over a selection links the selection (`linkOnPaste`); a press on a link with Mod held, or while the
  editor is read-only, opens it through the app's URL handling (`openOnClick`); `enableClickSelection` selects the
  whole link on a press. URLs are found with or without a protocol (`nsh.dev`, `https://nsh.dev/docs`, e-mail
  addresses), and the protocol a bare host gets is `defaultProtocol` (`http`). Links take the protocols `http`,
  `https`, `ftp`, `ftps`, `mailto`, `tel`, `callto`, `sms`, `cid`, `xmpp` and those in `protocols`, so
  `setLink({ href })`, `toggleLink(attrs?)` and autolinking keep scripts (`javascript:`) and data URLs out.
  `unsetLink()` removes the link around the selection.
- `characterCount(options?)`: `editor.characters(mode?)` counts the text's characters (`"textSize"`, UTF-16 units as
  JS's `length`) or the document's positions (`"nodeSize"`); `editor.words()` counts its words (Unicode word
  boundaries). With `limit`, changes that would go past it are refused and pasted content is trimmed to what fits;
  a first document over the limit is trimmed (`autoTrim`). `setCharacterLimit(limit)` changes the limit and
  `editor.characterLimit` reads it.
- `suggestion(options?)`: follows a trigger (`char`, `@` by default) typed before the cursor. `allowSpaces` lets the
  query hold spaces, `allowedPrefixes` lists what may precede the trigger (a space by default; `anyPrefix` takes
  anything), `startOfLine` asks for it at the line's start (a `/` command menu). `editor.suggestion(key)` gives
  `{ active, range, query, text, lastKey, keyCount }`; the active range carries the app's `decorationClass` (and
  `decorationEmptyClass` while the query is empty). While a suggestion is active the keys in `captureKeys` belong
  to the app's list: the editor takes them and records the last one in the state, and Escape dismisses the
  suggestion (`exitSuggestion(key)` does too). `replaceSuggestion(content, key?)` replaces the trigger and the query
  with text or JSON content.
- `withMention(schema, { name?, char? })` adds Tiptap's mention node: an inline atom with `id`, `label` and its
  trigger, written as `@label` in text and as `<span data-type="mention">` in HTML. `insertMention(range, id, label?)`
  replaces a suggestion's range with a mention and a space.

The popup is the app's: it reads the suggestion's state, places itself at `coordsAtPos(range.from)` and draws the
items its own way.

## Tables

`TableKit` brings Tiptap's tables: `RichTable` (Tiptap's `Table`), `RichTableRow`, `RichTableHeader` and
`RichTableCell`. It is added next to `StarterKit`:

```tsx
import { RichEditor, StarterKit, TableKit, addRowAfter, createRichEditor, insertTable, mergeCells } from "nsh/base";

const editor = createRichEditor({
  extensions: [StarterKit, TableKit.configure({ table: { cellMinWidth: 40 } })],
});

editor.run(insertTable({ rows: 3, cols: 3, withHeaderRow: true }));
editor.run(addRowAfter());
```

The table takes the options `resizable` (true), `cellMinWidth` (25), `lastColumnResizable` (true),
`allowTableNodeSelection` (false) and `HTMLAttributes`; `TableKit.configure({ tableHeader: false })` leaves one
extension out. Cells hold blocks and have `colspan`, `rowspan` and `colwidth` (a width in points per column they
span); rows have a `height`.

Tab and Shift-Tab move between cells, and Tab in the last cell adds a row. Arrow keys at a cell's edge go on to the
next cell; Shift with an arrow, or a drag across cells, selects a rectangle of cells (a selection of the type
`"cell"`, whose `anchor` and `head` are the positions before its first and last cells). Backspace and Delete empty
the selected cells, and delete the table when all its cells are selected.

In the editor a table is a grid of its cells: each column as wide as its cells' `colwidth`, columns without one
sharing the room (at least `cellMinWidth` wide), each row at least its `height`. Its look starts from the theme: a
1-point `border` grid, header cells on `muted`, padded cells, and each selected cell under the `selectedCell` part in
the selection color. `classes.nodes` (`table`, `tableCell`, `tableHeader`) and the parts restyle
all of it. Up and Down on a cell's first or last line go to the cell above or below.

While the document can be edited:

- On desktops, the right border of each column and the bottom border of each row resize them: the pointer shows the
  resize cursor and the `tableResizeHandle` line, the table follows the drag, and the release sets `colwidth` or
  `height` in one step that undo takes back. `resizable: false` turns this off, `lastColumnResizable: false` keeps the
  last column's width.
- The table the selection is in shows grips (`tableGrip`) on its top border over each column and on its left border
  beside each row. Pressing one selects that column or row; dragging it on desktops shows where it drops
  (`tableDropIndicator`) and moves it there on release.

```tsx
<RichEditor
  editor={editor}
  classes={{
    nodes: { tableHeader: "font-semibold", tableCell: "px-3 py-2" },
    selectedCell: "bg-primary/10",
    tableGrip: "bg-muted-foreground/60 rounded-full",
  }}
/>
```

The commands, each a helper of `nsh/base`:

- `insertTable({ rows, cols, withHeaderRow })` (3 × 3 with a header row by default) and `deleteTable()`.
- `addColumnBefore()`, `addColumnAfter()`, `deleteColumn()`, `addRowBefore()`, `addRowAfter()`, `deleteRow()`.
- `mergeCells()`, `splitCell()` and `mergeOrSplit()`.
- `toggleHeaderRow()`, `toggleHeaderColumn()` and `toggleHeaderCell()`.
- `setCellAttribute(name, value)`, `setCellSelection({ anchorCell, headCell })`, `goToNextCell()`,
  `goToPreviousCell()` and `fixTables()`, which repairs tables with missing or overlapping cells.
- `moveTableRow({ from, to, select })` and `moveTableColumn({ from, to, select })` move a row or column, together
  with the rows or columns its merged cells span; `setColumnWidth({ col, width })` and
  `setRowHeight({ row, height })` size them (`null` sizes them to their content). These take `table`, the position
  before a table, to act on a table other than the selection's.

Tables read from and write to HTML (`<table>` with `<th>` / `<td>`, `colspan`, `rowspan` and `data-colwidth`) and
Markdown: a table with a header row whose cells are each one paragraph is a GFM pipe table, and any other table is
written as its HTML, which reads back the same. In plain text a row is a line of its cells separated by tabs.

Source: https://nsh.dev/versions/main/elements/rich-editor

---

# Scrollbar

A scrollbar gives a scroll view or a list a bar in the app's own look: a thin pill that widens under the pointer, a
track in the brand's tone, a bar beside a fixed header or along two panes. Set once as the app's theme, every scroll
view and list draws one in place of the platform's indicator ([Built-in bars](#built-in-bars)); placed by the app, it
names the scroll view it moves and sits wherever the app puts it. It owns its behavior: the thumb's length and place follow the content, the viewport and
the offset (also while a list grows or the window resizes); dragging the thumb scrolls the content, and a press on the
track brings the thumb's middle there; it shows while the content scrolls, while the pointer is over it, or always,
and fades in and out natively. The look and the timing are the app's: a `Scrollbar` has no colors, sizes or radii of
its own, and its fades take no time until the app gives them some.

```rust
use nsh_base::{ScrollbarEntrance, ScrollbarMode, ScrollbarMotion, scrollbar, theme};
use nsh_core::prelude::*;

fn inbox(rows: impl IntoElement) -> impl IntoElement {
    let list = element_ref();
    // In over 300 ms and out over 500 ms, 2 s after the last scroll; pointing
    // at the hidden thumb slides it in from the edge.
    let mut motion = ScrollbarMotion::default();
    motion.enter = 300.0;
    motion.exit = 500.0;
    motion.thumb_hover_entrance = ScrollbarEntrance::SlideAndFade;
    view()
        .relative()
        .flex_1()
        // The scroll view's own indicator gives way to the app's bar.
        .child(scroll().element_ref(&list).flex_1().scrollbar(false).child(rows))
        .child(
            scrollbar()
                .scroll(list)
                .mode(ScrollbarMode::Hover)
                .motion(motion)
                .accessibility_label("Messages")
                // The track over the right edge; the thumb right-aligned in it.
                .absolute()
                .top_0()
                .bottom_0()
                .right_0()
                .w(px(16.0))
                .items_end()
                .p(px(4.0))
                .thumb_style(|s| {
                    s.w(px(6.0))
                        .rounded_full()
                        .bg(move || theme().muted_foreground)
                        .opacity(0.6)
                        .group_hover(|s| s.w(px(8.0)).opacity(0.9))
                }),
        )
}
```

```tsx
import { mount, Scroll, Text, View, type YNode } from "nsh";
import { Scrollbar } from "nsh/base";

function App() {
  let list: YNode | undefined;
  return (
    <View class="relative flex-1">
      <Scroll ref={list} scrollbar={false} class="flex-1">
        {Array.from({ length: 60 }, (_, i) => (
          <Text class="px-4 py-3">{`Message ${i + 1}`}</Text>
        ))}
      </Scroll>
      <Scrollbar
        scroll={list}
        mode="hover"
        motion={{ enter: 300, exit: 500, thumbHoverEntrance: "slideAndFade" }}
        accessibilityLabel="Messages"
        class="absolute inset-y-0 right-0 w-4 items-end p-1"
        thumbClass="w-1.5 rounded-full bg-muted-foreground opacity-60 transition-all duration-300 hover:w-2 hover:opacity-90 active:w-2 active:opacity-100"
      />
    </View>
  );
}

mount(App);
```

`Scrollbar` comes from [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md), the `nsh-base` crate in Rust. In Rust, `scrollbar()` makes
one with a setter per prop (`.scroll(..)`, `.thumb_style(..)`) and the typed style methods for the bar itself; its
`scroll` takes an `ElementRef` (or a `ScrollbarTarget`).

## Built-in bars

Every scroll view and list can draw a `Scrollbar` in place of the platform's indicator, with no bar to place:
`Scrollbar.setTheme` gives the app's look to the bar of each view whose `scrollbar` is `true`, once, wherever the
app starts. Each view gets its own bar over its viewport, which stays there as the content scrolls (on the main
thread, as sticky views do) and draws above the content; it follows, scrolls and fades as a placed `Scrollbar` does.

```rust
use nsh_base::{ScrollbarLook, ScrollbarMode, ScrollbarTheme, set_scrollbar_theme};

fn use_app_scrollbars() {
    let mut vertical = ScrollbarLook::default();
    vertical.class = Some("absolute inset-y-0 right-0 w-4 items-end p-1".into());
    vertical.thumb_class = Some("w-1.5 rounded-full bg-muted-foreground opacity-60 hover:w-2".into());
    let mut horizontal = ScrollbarLook::default();
    horizontal.class = Some("absolute inset-x-0 bottom-0 h-4 items-end p-1".into());
    horizontal.thumb_class = Some("h-1.5 rounded-full bg-muted-foreground opacity-60 hover:h-2".into());
    let mut theme = ScrollbarTheme::default();
    theme.mode = ScrollbarMode::Hover;
    theme.motion.enter = 300.0;
    theme.motion.exit = 500.0;
    theme.vertical = Some(vertical);
    theme.horizontal = Some(horizontal);
    set_scrollbar_theme(Some(theme));
}
```

```tsx
import { Scrollbar } from "nsh/base";

Scrollbar.setTheme({
  mode: "hover",
  motion: { enter: 300, exit: 500 },
  vertical: {
    class: "absolute inset-y-0 right-0 w-4 items-end p-1",
    thumbClass: "w-1.5 rounded-full bg-muted-foreground opacity-60 transition-all duration-300 hover:w-2",
  },
  horizontal: {
    class: "absolute inset-x-0 bottom-0 h-4 items-end p-1",
    thumbClass: "h-1.5 rounded-full bg-muted-foreground opacity-60 transition-all duration-300 hover:h-2",
  },
});
```

A `ScrollbarTheme` has the props of a bar that are the same for every view, and the look of each axis:

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | `"scrolling" \| "hover" \| "always"` | `"scrolling"` | When the bars show: [When it shows](#when-it-shows). |
| `motion` | `ScrollbarMotion` | snaps, `idle` `2000` | How they show and hide: [Motion](#motion). |
| `minThumbLength` | `number` | `48` | The shortest a thumb gets. |
| `vertical`, `horizontal` | `ScrollbarLook` | none | The look of the bars of vertical and of horizontal views: `class` and `style` for the track, placed in the view's viewport; `thumbClass` and `thumbStyle`; `accessibilityLabel`. A view whose axis has no look keeps the platform's indicator. |

A later `setTheme` restyles the bars, and `Scrollbar.setTheme(null)` gives the views the platform's indicator back. One
view takes a theme of its own as its `scrollbar` prop (`<Scroll scrollbar={{ mode: "always", vertical: { … } }}>`),
whether or not the app set one; `scrollbar={false}` leaves a view without a bar. A list laid out in its parent's
viewport (`viewport="parent"`) scrolls with that view and its bar. A multiline `Input` gets the bar of its vertical look
too, over its text, which it scrolls as the text view's own indicator does.

## The scroll view it moves

`scroll` names the scroll view or the list the bar follows: its `ref`. The bar finds it once it is on screen, so the
`ref` may be set by an element later in the same render; write the bar after its scroll view (or keep the `ref` in a
signal). Turn the scroll view's own indicator off with `scrollbar={false}`, and place the bar with `class`: over the
scroll view's edge in a `relative` box around both, or anywhere else on the screen.

- The thumb is as long as the share of the content the viewport shows, along the track's content box (inside its
  padding), and no shorter than `minThumbLength`. Its place is how far the content is scrolled; while the content
  bounces past an end, the thumb stays at that end.
- A drag of the thumb scrolls the content by as much as the thumb moves. A press on the track brings the thumb's middle
  under the pointer, and a drag goes on from there.
- A vertical bar follows a vertical scroll view; `axis="horizontal"` makes a bar for a horizontal one (place it along
  the bottom edge). One bar per axis.
- Lists work alike: the thumb follows the list's whole length as rows are measured and added.

## When it shows

| `mode` | Shows |
|---|---|
| `"scrolling"` (default) | While the content scrolls, and until `motion.idle` after it stops; the pointer on the bar while it shows keeps it. |
| `"hover"` | While the pointer is over the bar (where it shows, even while hidden), and as `"scrolling"` does. |
| `"always"` | Always. |

In every mode it shows while its thumb is dragged, and stays `motion.idle` after the last scroll, drag or hover. While
the content fits the viewport, it stays hidden. Hidden, the bar is at `opacity: 0` and passes presses through to what
is under it.

## Motion

`motion` times the bar's fades, which run natively, as `gpui-base`'s `ScrollbarMotion` does:

| Field | Default | Description |
|---|---|---|
| `idle` | `2000` | How long the bar stays after the last scroll, drag or hover, in milliseconds. |
| `enter` | `0` | How long it takes to appear: its opacity rises linearly, a slide eases out. |
| `exit` | `0` | How long it takes to fade away once `idle` is over, easing in; it slides out of its track as it fades. |
| `entrance` | `"fade"` | How it comes in: `"fade"` in place, or `"slideAndFade"` from the edge it is on (the right, the bottom). |
| `thumbHoverEntrance` | `"fade"` | How it comes in when the pointer on its hidden thumb shows it (`"hover"`). |

With no durations the bar snaps in and out. A fade reversed halfway keeps its speed: it runs for the share of its
duration still to cover. An `"always"` bar never animates, nor does any while the user asks for less motion. The
track clips what slides. The thumb's own motion, such as a width that grows on `hover:`, is its style's
(`transition-all` on `thumbClass`).

## Props

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `scroll` | `.scroll(..)` | `YNode` | none | The scroll view or list the bar follows and moves (its `ref`). |
| `axis` | `.axis(..)` | `"horizontal" \| "vertical"` | `"vertical"` | The axis of the scroll view: the track runs along it. Read when the bar is made. |
| `mode` | `.mode(..)` | `"scrolling" \| "hover" \| "always"` | `"scrolling"` | When the bar shows. |
| `motion` | `.motion(..)` | `ScrollbarMotion` | snaps, `idle` `2000` | How it shows and hides: [Motion](#motion). |
| `minThumbLength` | `.min_thumb_length(..)` | `number` | `48` | The shortest the thumb gets on a long content, so it stays easy to grab. |
| `thumbClass`, `thumbStyle` | `.thumb_style(\|s\| ..)` | `string`, `StyleProp<ViewStyle>` | none | The thumb. |
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | none | What screen readers say of the bar. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The bar: its track, where the app places it. |

## Parts

| Part | Inside | Styled with |
|---|---|---|
| The track | where the app places it | `class`, `style` |
| The thumb | the track's content box | `thumbClass`, `thumbStyle` |

The bar sizes the thumb along the axis and moves it; its thickness and its place across the track are the app's
(`w-1.5` and `items-end` on the track put a 6-point thumb at the right). The track's padding keeps the thumb off its
ends and sides.

States the parts show:

- The track: `hover:` under the pointer; it is a `group`, so the thumb takes `group-hover:` from it (a thumb that
  widens as the pointer comes near).
- The thumb: `hover:` under the pointer, `active:` while it is dragged.

The bar's visibility is its opacity: give the colors' transparency to the track's background or the thumb. A thumb
that widens takes `transition-all` (it never delays the thumb's place, which the bar sets apart from the thumb's
styles), and `motion-reduce:` keeps it still for people who ask for less motion.

## Accessibility

- The scroll view stays what screen readers scroll: they move it with their own gestures and read its content.
- The bar is labelled by `accessibilityLabel` for the screen readers that reach it.

See [Accessibility](https://nsh.dev/versions/main/docs/accessibility.md) for labels, roles and actions in general.

## Platform notes

- Every platform draws what the app styles, and the thumb follows the offset each platform reports for the scroll
  view. Drags of the thumb and presses on the track work with a mouse, a pen or a finger.
- `"hover"` follows a mouse or a touchpad pointer (the desktops and the web); on a touch screen, the bar shows while
  the content scrolls, and its hidden track lets touches through.

Source: https://nsh.dev/versions/main/elements/scrollbar

---

# Select

A select chooses one value from a list of items: a setting, a filter, a country, a time zone. The app's trigger
opens the list, presented as each device expects:

- On the desktops and in desktop browsers, a popup over the trigger with the selected row laid over the trigger, so
  the chosen title stays where it was (shadcn/ui's `item-aligned` position), as wide as the trigger (the app's
  `popupStyle` / `popupClass` width sets another, as `gpui-component`'s `menu_width`) and as tall as its rows up to the room on the screen; with nothing selected it opens below the trigger. The keyboard moves
  through the items and chooses one.
- On phones and tablets, a sheet at the bottom of the screen over a backdrop.

The select owns the behavior: the value (the app's, or its own), the open state, the keyboard, typeahead, search,
sections, the highlighted row and what screen readers hear. The look is the app's: it styles the trigger, the popup,
the list, the rows, the sections' headers and the search field, or draws the rows itself.

```rust
use nsh_base::{SelectEntry, SelectItem, select, theme};
use nsh_core::prelude::*;

const FRUITS: [(&str, &str); 5] = [
    ("apple", "Apple"),
    ("banana", "Banana"),
    ("blueberry", "Blueberry"),
    ("grapes", "Grapes"),
    ("pineapple", "Pineapple"),
];

fn fruit_select() -> impl IntoElement {
    let fruit = signal(None::<SharedString>);
    let title = move || {
        let chosen = fruit.get();
        FRUITS
            .iter()
            .find(|(value, _)| Some(*value) == chosen.as_deref())
            .map_or("Pick a fruit", |(_, title)| *title)
            .to_string()
    };
    select()
        .items(
            FRUITS
                .iter()
                .map(|&(value, title)| SelectItem::new(value, title).disabled(value == "grapes"))
                .collect::<Vec<_>>(),
        )
        .value(move || fruit.get())
        .on_change(move |next: &Option<SharedString>| fruit.set(next.clone()))
        .accessibility_label("Fruit")
        .offset(px(4.0))
        .popup_style(|s| {
            s.p_1()
                .rounded_lg()
                .border_1()
                .border_color(move || theme().border)
                .bg(move || theme().popover)
                .text_color(move || theme().popover_foreground)
                .shadow_md()
        })
        .item_class("rounded-md focus:bg-accent selected:font-medium disabled:opacity-50")
        .trigger(
            view()
                .h_9()
                .w_48()
                .flex_row()
                .items_center()
                .justify_between()
                .px_3()
                .rounded_md()
                .border_1()
                .border_color(move || theme().input)
                .hover(|s| s.bg(move || theme().accent))
                .child(text(title))
                .child(text("▾").text_color(move || theme().muted_foreground)),
        )
        .render_item(|item: &SelectEntry| {
            view()
                .flex_row()
                .items_center()
                .px_2()
                .py_1p5()
                .child(text(item.title.clone()).text_sm())
        })
}
```

```tsx
import { mount, signal, Text, View } from "nsh";
import { Select } from "nsh/base";

const FRUITS = [
  { value: "apple", title: "Apple" },
  { value: "banana", title: "Banana" },
  { value: "blueberry", title: "Blueberry" },
  { value: "grapes", title: "Grapes", disabled: true },
  { value: "pineapple", title: "Pineapple" },
];

function App() {
  const fruit = signal<string | null>(null);
  const title = () => FRUITS.find((f) => f.value === fruit())?.title;
  return (
    <Select
      items={FRUITS}
      value={fruit()}
      onChange={({ value }) => fruit.set(value)}
      accessibilityLabel="Fruit"
      offset={4}
      popupClass="rounded-lg border border-border bg-popover p-1 text-popover-foreground shadow-md"
      backdropClass="bg-black/40"
      itemClass="rounded-md px-2 py-1.5 text-sm focus:bg-accent focus:text-accent-foreground disabled:opacity-50"
      trigger={
        <View class="h-9 w-48 flex-row items-center justify-between rounded-md border border-input px-3 hover:bg-accent active:bg-accent focus-visible:ring-2 focus-visible:ring-ring">
          <Text class={fruit() ? "text-foreground" : "text-muted-foreground"}>{title() ?? "Pick a fruit"}</Text>
          <Text class="text-muted-foreground">▾</Text>
        </View>
      }
    />
  );
}

mount(App);
```

`Select` comes from [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md), the `nsh-base` crate in Rust. In Rust, `select()` makes one
with a setter per prop (`.items(..)`, `.value(..)`, `.item_style(..)`) and a listener per event (`.on_change(..)`);
`SelectItem::new(value, title)` makes an item, with `.disabled(..)` and `.group(..)`.

## Items

`items` is the list as data: each item has a `value` (unique among the items: what choosing it sets), a `title` (what
its row shows, what search and typeahead match and what screen readers say), and optionally `disabled` and a `group`.
Adjacent items of one `group` form a section under a header with that title:

```tsx
<Select
  items={[
    { value: "lisbon", title: "Lisbon", group: "Europe" },
    { value: "london", title: "London", group: "Europe" },
    { value: "tokyo", title: "Tokyo", group: "Asia" },
    { value: "seoul", title: "Seoul", group: "Asia", disabled: true },
  ]}
  groupClass="px-2 pb-1 pt-2 text-xs text-muted-foreground"
  trigger={trigger}
/>
```

The rows are a virtualized list in the popup's scroll view: a list of thousands of items makes only the rows in view,
and the popup scrolls when its rows are taller than the room it has.

## Value

With `value`, the app owns the chosen item: the select shows the item of that value and reports a choice with
`onChange({ value })`; the app sets `value` to follow it, or keeps its own. `value={null}` is nothing chosen. Left out, the
select keeps its own value, from `defaultValue` at first. `onChange` reports changes: choosing the chosen item again
closes the list.

`cleanable` adds a clear button while an item is chosen: a press clears the value, reported as `onChange({ value: null })`, and
the list stays closed. The button comes after the trigger in the select's view, not inside it, so a press on it never
opens the list; the app places it (over the trigger's end with `absolute`, where a chevron would be) and fills it:

```tsx
<Select
  items={fonts}
  value={font()}
  onChange={({ value }) => font.set(value)}
  cleanable
  clearButtonAccessibilityLabel="Clear the font"
  clearButtonClass="absolute right-2 top-2 size-5 items-center justify-center rounded-full hover:bg-accent"
  clearButton={<Text class="text-xs text-muted-foreground">✕</Text>}
  trigger={trigger}
/>
```

The trigger is the app's element, so it shows whatever the app wants for the chosen item: its title, an icon, a
placeholder while nothing is chosen. In TSX it is the element you pass: it is the combobox and takes the presses, the
keyboard focus, the expanded state and `disabled` itself, so its own `active:`, `focus:` and `disabled:` classes
follow the select, its own `onPress` runs too, and the list is placed against it and is as wide.

## Open state

Without `open`, the select keeps its own open state (from `defaultOpen`). With `open`, the app owns it and changes it
in `onOpenChange({ open, reason })`: `"triggerPress"` (a press of the trigger, or one of its keys), `"select"` (a choice),
`"pressOutside"`, `"backdropPress"`, `"cancel"` (Escape or back) or `"focus"` (Tab or Shift+Tab moving the keyboard focus on from the open list). `onOpen` and `onClose` tell when the list is
shown and gone (a sheet once it came in and once it went), `onCancel` that the user closed it without choosing.

## Search

`searchable` puts a search field above the items: typing filters them by title, ignoring case, and a section with no
match goes with its header. The highlight moves to the first match, the keys keep moving it while the field has the
keyboard, and Return chooses it. `empty` is what the list shows while nothing matches:

```tsx
<Select
  items={zones}
  searchable
  searchPlaceholder="Search time zones"
  searchAccessibilityLabel="Search time zones"
  searchClass="mx-1 mb-1 rounded-md border border-input px-2 py-1.5 text-sm"
  empty={<Text class="px-2 py-6 text-center text-sm text-muted-foreground">No time zone found</Text>}
  trigger={trigger}
/>
```

On the desktops the search field takes the keyboard as the list opens; on touch screens the keyboard comes up when
the field is pressed. Each opening starts with an empty search.

## Rows the app draws

`itemClass` styles each item's row, which shows the item's title until `renderItem` draws it: `focus:` applies to the highlighted row (where the
keys or the pointer are), `selected:` to the chosen one and `disabled:` to a disabled one. To draw a row, give
`renderItem`: it gets what the item is ([`SelectEntry`](#types)) and returns the row's content, for the rows in view.
It never gets the row's state: with `group` in `itemClass`, the content follows the row's states with `group-focus:`,
`group-selected:` and `group-disabled:` classes, so the drawing is made once per item and a move of the highlight or a
choice draws nothing again. `renderGroup` draws a section's header the same way:

```tsx
<Select
  items={fonts}
  itemClass="group rounded-md focus:bg-accent disabled:opacity-50"
  renderItem={(item) => (
    <View class="flex-row items-center gap-2 px-2 py-1.5">
      <Text class="flex-1 text-sm" style={{ fontFamily: item.value }}>{item.title}</Text>
      <Text class="w-4 text-right text-sm opacity-0 group-selected:opacity-100">✓</Text>
    </View>
  )}
  renderGroup={(group) => <Text class="px-2 pt-2 text-xs font-medium text-muted-foreground">{group.title}</Text>}
  trigger={trigger}
/>
```

## Props

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `items` | `.items(..)` | `SelectItem[]` | `[]` | The items, in order. |
| `value` | `.value(..)` | `string \| null` | none | The chosen item's `value`, owned by the app; `null` for none. Left out, the select keeps its own. |
| `defaultValue` | `.default_value(..)` | `string` | none | The value at first, without `value`. |
| `open` | `.open(..)` | `boolean` | none | Open, owned by the app. |
| `defaultOpen` | `.default_open(..)` | `boolean` | `false` | Open at first, without `open`. |
| `placeholder` | `.placeholder(..)` | `string` | none | What the trigger says while no item is chosen: shown by a terminal's trigger without `trigger`, and heard by screen readers as its value. |
| `searchable` | `.searchable(..)` | `boolean` | `false` | A search field above the items filters them by title. |
| `searchPlaceholder` | `.search_placeholder(..)` | `string` | none | The search field's placeholder. |
| `searchAccessibilityLabel` | `.search_accessibility_label(..)` | `string` | none | What screen readers call the search field: what it searches. |
| `cleanable` | `.cleanable(..)` | `boolean` | `false` | A clear button while an item is chosen; a press clears the value (`onChange({ value: null })`). |
| `disabled` | `.disabled(..)` | `boolean` | `false` | It stays closed: the trigger takes no presses and no keyboard focus, and `disabled:` styles apply to it. |
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | none | What screen readers call it: what the choice is about. |
| `placement` | `.placement(..)` | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` | Desktops: the side of the trigger the list goes on, the other side when only that one has room. |
| `align` | `.align(..)` | `"start" \| "center" \| "end"` | `"start"` | Desktops: how it lines up with the trigger. |
| `offset` | `.offset(..)` | `number` | `0` | Desktops: the gap between the trigger and the list. |
| `margin` | `.margin(..)` | `number` | `0` | Desktops: the distance it keeps from the edges of the safe area. |
| `popupClass`, `popupStyle` | `.popup_class(..)`, `.popup_style(..)` | `string`, `StyleProp<ViewStyle>` | none | The popup (desktops) or the sheet (touch screens) the list is in. |
| `backdropClass`, `backdropStyle` | `.backdrop_class(..)`, `.backdrop_style(..)` | `string`, `StyleProp<ViewStyle>` | none | Touch screens: the backdrop behind the sheet. |
| `listClass`, `listStyle` | `.list_class(..)`, `.list_style(..)` | `string`, `StyleProp<ViewStyle>` | none | The list, the scroll view of the rows. |
| `itemClass`, `itemStyle` | `.item_class(..)`, `.item_style(..)` | `string`, `StyleProp<TextStyle>` | none | Each item's row, its text styles inherited by its title: `focus:` while highlighted, `selected:` while chosen, `disabled:` while it cannot be. |
| `groupClass`, `groupStyle` | `.group_class(..)`, `.group_style(..)` | `string`, `StyleProp<ViewStyle>` | none | Each section's header. |
| `searchClass`, `searchStyle` | `.search_class(..)`, `.search_style(..)` | `string`, `StyleProp<InputStyle>` | none | The search field: its box and its text (`color`, `fontSize`, `placeholderColor`). |
| `clearButtonClass`, `clearButtonStyle` | `.clear_button_class(..)`, `.clear_button_style(..)` | `string`, `StyleProp<ViewStyle>` | none | The clear button (`cleanable`); `disabled:` with the select. |
| `clearButton` | `.clear_button(..)` | `JSX.Element` | none | The content of the clear button: a cross, an icon. |
| `clearButtonAccessibilityLabel` | `.clear_button_accessibility_label(..)` | `string` | none | What screen readers call the clear button. |
| `trigger` | `.trigger(..)` | `JSX.Element` | none | What opens the list when pressed; the list is placed against it. |
| `empty` | `.empty(..)` | `JSX.Element` | none | What the list shows while no item does (a search with no match). |
| `renderItem` | `.render_item(..)` | `(item: SelectEntry) => JSX.Element` | none | An item's row, drawn by the app from what the item is (its states are the row's classes); the item's title otherwise. |
| `renderGroup` | `.render_group(..)` | `(group: SelectGroup) => JSX.Element` | none | A section's header, drawn by the app; its title otherwise. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The view around the trigger. |

## Events

| Event | Rust | Description |
|---|---|---|
| `onChange` | `.on_change(\|value\| ..)` | The user chose another item (a press, Return or Space, typeahead on the trigger): its `value`; `null` when the clear button cleared it. Set `value` to follow it. |
| `onOpenChange` | `.on_open_change(\|e\| ..)` | The list opened or closed, with why. Set `open` to follow it. |
| `onOpen` | `.on_open(\|\| ..)` | The list is shown; as a sheet, once it came in. |
| `onClose` | `.on_close(\|\| ..)` | The list is gone; as a sheet, once it went. Also when the app closed it. |
| `onCancel` | `.on_cancel(\|\| ..)` | The user closed the list without choosing (Escape or back, a press outside or on the backdrop). |

They come in this order: `onChange` for a choice, or `onCancel` for a close without one, then `onOpenChange`, then
`onOpen` or `onClose` once the list is shown or gone.

<a id="types"></a>

## Types

| Type | Members | Description |
|---|---|---|
| `SelectItem` | `value: string`, `title: string`, `disabled?: boolean`, `group?: string` | An item of `items`. |
| `SelectEntry` | `value`, `title`, `disabled`, `group?` (the item's), `index: number` | What `renderItem` gets: the item and its index among the `items`, never its state (the row's `focus:`, `selected:` and `disabled:`). |
| `SelectGroup` | `title: string` | What `renderGroup` gets: the section's `group`. |

In Rust they are `nsh_base::SelectItem`, `SelectEntry` and `SelectGroup`; `value` is a `SelectValue`
(`Controlled(Some(..))` for a value, `Controlled(None)` for `null`), which `.value(..)` makes from an
`Option<SharedString>` or a string.

## Parts

| Part | Where | Styled with |
|---|---|---|
| The trigger | the select's view | the app's own element (`trigger`) |
| The clear button | the select's view, after the trigger (`cleanable`, while an item is chosen) | `clearButtonClass`, `clearButtonStyle`; its content `clearButton` |
| The popup or sheet | over everything, at the trigger (desktops) or at the bottom (touch screens) | `popupClass`, `popupStyle` |
| The backdrop | behind the sheet (touch screens) | `backdropClass`, `backdropStyle` |
| The search field | the popup, first (`searchable`) | `searchClass`, `searchStyle`, `searchPlaceholder`, `searchAccessibilityLabel` |
| The list | the popup, after the search field | `listClass`, `listStyle` |
| A section's header | the list, before its items | `groupClass`, `groupStyle`, `renderGroup` |
| An item's row | the list | `itemClass`, `itemStyle`, `renderItem` (`group-focus:`, `group-selected:`, `group-disabled:` inside, under `group` in `itemClass`) |
| The empty state | the popup, while no item shows | its own element (`empty`) |

The popup is a column: its height follows the search field and the rows, so a `max-h-*` on `popupClass` caps it and
the list scrolls within it.

## Keyboard

On the desktops, Tab reaches the trigger of a select that is not `disabled`. With the list closed, Down, Up, Return
and Space open it on the chosen item (with none chosen, Up on the last enabled item and the others on the first), and
letters and digits choose the item whose title starts with what was typed, as a native select does. With the list
open:

| Key | Action |
|---|---|
| Down, Up | The next or previous enabled item, around the ends. |
| Home, End | The first or last enabled item (the search field's own while it has the keyboard). |
| Page Down, Page Up | A page of rows on, or back. |
| Return | Chooses the highlighted item and closes the list. |
| Space | Chooses the highlighted item (without a search field). |
| Letters, digits | The next item whose title starts with what was typed in the last second (without a search field). |
| Escape | Closes the list without choosing. |
| Tab, Shift+Tab | Closes the list (`reason: "focus"`) and moves the focus to the next or previous control. |

Once the list closes, the keyboard focus returns to the trigger, unless a press outside or Tab took it elsewhere. The
pointer highlights the row it moves over; the highlighted row is revealed as the keys move to it.

## On each device

| | Desktops and desktop browsers | Phones and tablets |
| --- | --- | --- |
| The list | a popup over the trigger, the selected row on it (below it while none is), as wide as the trigger unless `popupStyle` sets a width, as tall as its rows up to the room on the screen | a sheet at the bottom over a backdrop, as tall as its rows up to the status bar |
| Closing it | a choice, Escape, a press outside (which goes on to what is under the pointer) | a choice, the backdrop, the Android back button |
| Search | the field takes the keyboard as the list opens | the keyboard comes up when the field is pressed |
| A choice | the press going down chooses, so the search field keeps the keyboard | a tap |

`popupClass` styles the popup on desktops and the sheet on phones; a style that differs between them can compare
`platform.idiom` (`nsh/device`) with `"desktop"`.

## Accessibility

- The trigger is a combobox for screen readers: its label is `accessibilityLabel`, its value the chosen item's title
  (the `placeholder` while none is chosen), and it says whether the list is expanded. `disabled` dims it.
- The clear button is a button named by `clearButtonAccessibilityLabel`; it is no stop of Tab.
- The search field is a text field named by `searchAccessibilityLabel`; its placeholder is a hint shown while it is
  empty.
- The list is a listbox and each row an option, named by its title; the chosen option is selected and a disabled one
  dimmed. Sections' headers are headers.
- As the keys move the highlight, the screen reader's focus moves to the highlighted row; while the search field has
  the keyboard, the highlighted item's title is announced instead, so typing goes on.

See [Accessibility](https://nsh.dev/versions/main/docs/accessibility.md) for labels, roles and announcements in general.

Source: https://nsh.dev/versions/main/elements/select

---

# Sheet

A sheet is a panel at an edge of the screen over a backdrop that covers the rest: filters, a share panel, a side
drawer. A press on the backdrop, Escape, the Android back button and VoiceOver's escape gesture close it. It shows on top of everything in its
window, the same on every device, and draws nothing of its own: the panel and the backdrop are the app's.

```rust
use nsh_base::{SheetEvent, sheet};
use nsh_core::prelude::*;

fn filters(open: Signal<bool>) -> impl IntoElement {
    sheet()
        .open(move || Some(open.get()))
        .on_open_change(move |e: &SheetEvent| {
            if let SheetEvent::OpenChange(next, _) = e {
                open.set(*next);
            }
        })
        .child(
            view()
                .gap_3()
                .p_6()
                .rounded_t(px(16.0))
                .bg(white())
                .child(text("Filters").font_weight(FontWeight::SEMIBOLD))
                .child(view().on_press(move || open.set(false)).child(text("Done"))),
        )
}
```

```tsx
import { signal, Text, View } from "nsh";
import { Sheet } from "nsh/base";

function Filters() {
  const open = signal(false);
  return (
    <>
      <View onPress={() => open.set(true)}><Text>Filters</Text></View>
      <Sheet
        open={open()}
        onOpenChange={(e) => open.set(e.open)}
        popupClass="gap-3 rounded-t-2xl bg-white p-6"
        backdropClass="bg-black/40"
      >
        <Text class="font-semibold">Filters</Text>
        <View onPress={() => open.set(false)}><Text>Done</Text></View>
      </Sheet>
    </>
  );
}
```

`Sheet` comes from [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md). Its content is made each time it opens. `side` puts it at
the `"bottom"` (the default) or `"top"` of the screen, as wide as the screen, or at the `"left"` or `"right"`, as tall
as the screen; its size across is the panel's, from its content or `popupClass`.

Its slide follows the panel's measured size as content is created or grows during the entrance. Lazy content and
asynchronous size updates share the same animation progress; the panel settles at its current size.

## Open state

Without `open`, the sheet keeps its own state, starting from `defaultOpen`. With `open`, the app owns it: change it in
`onOpenChange({ open, reason })`, which reports each request to close with its reason (`"backdropPress"`, `"cancel"`, `"swipe"`).
`onOpen` and `onClose` follow it in and out, whoever opened or closed it.

`closeOnEscape={false}` keeps it open on Escape and back, `closeOnBackdropPress={false}` on presses on the backdrop;
`onCancel` still hears them, to ask first.

## Dragging a bottom sheet

Set `closeOnSwipe` to let a bottom panel follow downward dragging. Its backdrop fades with the distance; releasing
past 30% of the panel's height, or downward at 800 points per second, requests closing with reason `"swipe"`.
A shorter drag returns smoothly. A controlled owner can keep `open` true to return the panel after a close request.
With reduced motion, release and programmatic opening/closing settle immediately; direct dragging still follows the finger.

The panel fits its content, including short menus; use `popupStyle` or a child's height to constrain taller content.
The app draws its own handle, which can be any view inside the panel. On iOS, an inner vertical `Scroll` or `List`
consumes the drag until its top and hands the remaining downward motion to the panel within the same gesture.
On Android, desktops and the web, dragging the handle or content outside a scroll uses their native pan support;
inner scrolls keep their platform's normal gesture arbitration. Setting `closeOnSwipe` to false keeps the panel
stationary and preserves the mounted content and scroll position. Other sides retain their existing behavior.

## Native sheets

A sheet is drawn by NSH in the app's window, styled by the app. For the platform's own presented sheet (a page sheet
on iOS), use a [Dialog](https://nsh.dev/versions/main/elements/dialog.md) with `presentation="pageSheet"`.

## Props

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `open` | `.open(..)` | `boolean` | none | Open, controlled by the app. |
| `defaultOpen` | `.default_open(..)` | `boolean` | `false` | Open at first, without `open`. |
| `side` | `.side(..)` | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` | The edge it is on. |
| `closeOnEscape` | `.close_on_escape(..)` | `boolean` | `true` | Escape and the Android back button close it. |
| `closeOnBackdropPress` | `.close_on_backdrop_press(..)` | `boolean` | `true` | A press on the backdrop closes it. |
| `closeOnSwipe` | `.close_on_swipe(..)` | `boolean` | `false` | A bottom panel follows downward dragging and closes on a sufficient release. |
| `popupClass`, `popupStyle` | `.popup_class(..)`, `.popup_style(..)` | `string`, `StyleProp<ViewStyle>` | none | The look of the panel. |
| `backdropClass`, `backdropStyle` | `.backdrop_class(..)`, `.backdrop_style(..)` | `string`, `StyleProp<ViewStyle>` | none | The look of the backdrop, such as a translucent color. |
| `children` | `.child(..)` | `JSX.Element` | none | The content. |

## Events

| Event | Rust | Description |
|---|---|---|
| `onOpenChange` | `.on_open_change(\|e\| ..)` | A close request, with why: `"backdropPress"`, `"cancel"` or `"swipe"`. |
| `onOpen` | `.on_open(\|\| ..)` | It came in: it is all there. |
| `onClose` | `.on_close(\|\| ..)` | It went: it is all gone. Also when the app closed it. |
| `onCancel` | `.on_cancel(\|\| ..)` | The user tried to close it (Escape or back, a press on the backdrop, an enabled swipe), whether or not it closed. |

On the web, embedding with `dialogs: "viewport"` presents the sheet and its backdrop over the host page,
including a same-origin iframe. Cross-origin frames use [`hostPlayerFrame`](https://nsh.dev/versions/main/docs/web.md#embed-it-in-a-page).

Source: https://nsh.dev/versions/main/elements/sheet

---

# Slider

A slider picks a value along a track (a volume, a brightness), or a range of two values with a thumb each (a price
range). It owns its behavior: a press on the track moves the nearer thumb there, a thumb follows a drag, with a mouse
or a finger; values snap to the `step`; each thumb is a stop of the keyboard focus and moves with the arrow keys, and is
an adjustable element for screen readers with its own value. The look is the app's: a `Slider` has no colors, sizes,
radii or motion of its own. It is made of a track with an indicator inside it, the range and the thumbs on the
indicator, then its children (a label, the value as text), and the app styles each part.

```rust
use nsh_base::{SliderValue, slider, theme};
use nsh_core::prelude::*;

fn strength(level: Signal<SliderValue>) -> impl IntoElement {
    let percent = move || format!("{}%", level.get().end());
    slider()
        .value(move || level.get())
        .accessibility_label("Option strength")
        .on_change(move |next: &SliderValue| level.set(*next))
        // The value in a column after the rail.
        .flex_row()
        .items_center()
        .gap_2()
        // An 8-point rail; the thumbs travel inside it.
        .track_style(|s| s.h(px(8.0)).flex_1().px(px(8.0)).rounded_full().bg(move || theme().muted))
        .indicator_style(|s| s.h_full())
        // The fill, from the rail's edge, fading into the thumb's tone.
        .range_style(|s| {
            s.ml(-px(8.0))
                .rounded_full()
                .bg_linear_to_r()
                .gradient_from(move || theme().primary)
                .gradient_to(move || theme().muted_foreground)
        })
        // A 16 x 8 pill sitting in the rail.
        .thumb_style(|s| {
            s.w(px(16.0))
                .h(px(8.0))
                .rounded_full()
                .bg(move || theme().muted_foreground)
                .hover(|s| s.brightness(1.1))
                .active(|s| s.brightness(1.25))
        })
        .child(
            text(percent)
                .w(px(42.0))
                .text_right()
                .text_xs()
                .tabular_nums()
                .text_color(move || theme().muted_foreground),
        )
}
```

```tsx
import { mount, signal, Text } from "nsh";
import { Slider } from "nsh/base";

function App() {
  const strength = signal(64);
  return (
    <Slider
      value={strength()}
      onChange={({ value }) => strength.set(value as number)}
      accessibilityLabel="Option strength"
      class="flex-row items-center gap-2"
      trackClass="h-2 flex-1 px-2 rounded-full bg-muted focus-within:ring-2 focus-within:ring-primary/36 focus-within:ring-offset-2 focus-within:ring-offset-background disabled:opacity-35"
      indicatorClass="h-full"
      rangeClass="-ml-2 rounded-full bg-linear-to-r from-primary via-primary to-muted-foreground"
      thumbClass="h-2 w-4 rounded-full bg-muted-foreground transition hover:brightness-110 active:brightness-125 focus:outline-none disabled:brightness-100 motion-reduce:transition-none"
      thumbStyle={{ boxShadow: "inset 0 1px 0 rgba(255, 255, 255, 0.18), 0 0 0 1px rgba(0, 0, 0, 0.42)" }}
    >
      <Text class="w-[42px] text-right font-mono text-[11px] text-muted-foreground">{`${strength()}%`}</Text>
    </Slider>
  );
}

mount(App);
```

`Slider` comes from [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md), the `nsh-base` crate in Rust. In Rust, `slider()` makes one
with a setter per prop (`.value(..)`, `.thumb_style(..)`), a listener method per event (`.on_change(..)`), the typed
style methods for the slider itself and `.child(..)` for its label. Its value is a `SliderValue`: `Single(f64)` or
`Range(f64, f64)`.

## Value

The value is a number, or `[start, end]` for a range with two thumbs; the shape of the value decides how many thumbs
there are. The app owns it with `value` and sets the one `onChange` reports, as for every control of `nsh/base`; or it
leaves the value to the slider with `defaultValue`, and hears the changes all the same. During a drag the thumbs and the
range follow the pointer in the same frame, natively; when the pointer lifts, the app's `value` shows again, as the app
set it for the drag's last change; screen readers hear the drag's values as it goes while one runs, and its end value
otherwise.

```tsx
const price = signal<[number, number]>([200, 800]);

<Slider
  value={price()}
  onChange={({ value }) => price.set(value as [number, number])}
  onChangeEnd={({ value }) => save(value)}
  min={0}
  max={1000}
  step={10}
  accessibilityLabel="Maximum price"
  startAccessibilityLabel="Minimum price"
/>;
```

- `onChange` reports each new value the user asks for: on a press on the track, at each step of a drag, for each key.
  Each report is a new value.
- `onChangeEnd` reports the value the change ended at, once: when the pointer lifts after a press or a drag that set a
  value, and after each key or screen reader step (each is a whole change). Save or send the value there.
- Values snap to `step`, counted from `min` (`min={1} step={2}` gives 1, 3, 5, ...), and stay between `min` and `max`;
  `max` is always reachable, so the last step is shorter when the range is not a whole number of steps. `step={0}`
  takes any value.
- A range's thumbs never cross: a dragged thumb stops at the other one. A drag that starts on two thumbs at one value
  moves the one that can go the pointer's way.
- The value shown is the app's, held to `min` and `max` (a range's ends in order), and a value off the step's grid
  shows where it is; the user's next change snaps.

## Props

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `value` | `.value(..)` | `number \| [number, number]` | none | The value (controlled): a number, or a range with two thumbs. The app sets the one `onChange` reports. |
| `defaultValue` | `.default_value(..)` | `number \| [number, number]` | `0` | The value at first while `value` is not set; the slider then keeps its own. |
| `min` | `.min(..)` | `number` | `0` | The smallest value. |
| `max` | `.max(..)` | `number` | `100` | The largest value; one below `min` is `min`. |
| `step` | `.step(..)` | `number` | `1` | The step values snap to, counted from `min`; `0` takes any value. |
| `scale` | `.scale(..)` | `"linear" \| "logarithmic"` | `"linear"` | How values spread along the track: evenly, or by orders of magnitude (from 1 to 1000, a third of the way is 10). Logarithmic needs `min` above 0; with a lower `min` it is linear. |
| `axis` | `.axis(..)` | `"horizontal" \| "vertical"` | `"horizontal"` | The track's direction: `min` at the start (the left, the right in a right-to-left layout), or at the bottom. Read when the slider is made. |
| `disabled` | `.disabled(..)` | `boolean` | `false` | No pointer, keyboard or screen reader changes; `disabled:` classes apply to the slider and its parts. |
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | none | What screen readers say for the thumb (on a range, the end's). |
| `startAccessibilityLabel` | `.start_accessibility_label(..)` | `string` | `accessibilityLabel` | What screen readers say for a range's start thumb. |
| `trackClass`, `trackStyle` | `.track_style(\|s\| ..)` | `string`, `StyleProp<ViewStyle>` | none | The track: the area that takes presses and drags. |
| `indicatorClass`, `indicatorStyle` | `.indicator_style(\|s\| ..)` | `string`, `StyleProp<ViewStyle>` | none | The indicator, the rail the values map onto. |
| `rangeClass`, `rangeStyle` | `.range_style(\|s\| ..)` | `string`, `StyleProp<ViewStyle>` | none | The range, from `min` to the thumb (between a range's thumbs), placed by the slider. |
| `thumbClass`, `thumbStyle` | `.thumb_style(\|s\| ..)` | `string`, `StyleProp<ViewStyle>` | none | Each thumb, centered on its value. |
| `children` | `.child(..)` | `JSX.Element` | none | The content after the track: a label, the value as text. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The slider itself: the column (or row) around the track and the label. |

## Events

| Event | Rust | Payload | When |
|---|---|---|---|
| `onChange` | `.on_change(\|value: &SliderValue\| ..)` | `{ value: number \| [number, number] }` | The user asked for a new value: a press on the track, a step of a drag, a key, a screen reader's increment or decrement. |
| `onChangeEnd` | `.on_change_end(\|value: &SliderValue\| ..)` | `{ value: number \| [number, number] }` | The change ended: the pointer lifted, a key or a screen reader's step was done. Once per change. |

## Parts

| Part | Inside | Styled with |
|---|---|---|
| The slider | | `class`, `style` |
| The track | the slider, first | `trackClass`, `trackStyle` |
| The indicator | the track | `indicatorClass`, `indicatorStyle` |
| The range | the indicator, placed by the values | `rangeClass`, `rangeStyle` |
| A thumb (two on a range) | the indicator, centered on its value | `thumbClass`, `thumbStyle` |
| The label | the slider, after the track | its own elements (`children`) |

The track takes presses and drags. The indicator's length is the range of values, from `min` at its leading edge (at
its bottom when vertical); the slider places the range and the thumbs on it, a thumb centered on its value whatever its
size. Two ways to lay them out:

- The track is the rail (the example above): `h-2 px-2 rounded-full bg-muted` with an `h-full` indicator. The padding
  keeps the thumbs inside the rail at both ends, and the range's `-ml-2` starts the fill at the rail's own edge.
- The track is a band around the rail, taller so a finger finds it on a touch screen: `h-8 justify-center` with an
  `h-2 rounded-full` indicator (`w-8 items-center` and `w-2 h-full` on a vertical slider).

States the parts show:

- A thumb: `hover:` under the pointer, `active:` while it is dragged, `focus:` with the keyboard focus, `disabled:`.
- The track: `active:` while a press on it drags; it is a `group`, so the indicator, the range and the thumbs take
  `group-hover:` and `group-active:` from it.
- Every part: `disabled:` while the slider is.

The thumbs move as the value changes, and follow a drag at once. Motion of the thumbs' states is the app's choice
(`transition` for a thumb that brightens on `hover:` and `active:`), and `motion-reduce:` keeps it still for
people who ask for less motion. The keyboard focus is a thumb's: `focus-within:` on the track rings the whole rail
while a thumb has it, and the thumb's `focus:outline-none` takes the place of the platform's own focus outline.

## Keyboard

On macOS and the web each thumb is a stop of the keyboard focus (Tab), and the focused thumb takes WAI-ARIA's slider
keys:

| Key | Does |
|---|---|
| Right, Up | One step up (also on a vertical slider). |
| Left, Down | One step down. |
| Page Up, Page Down | A tenth of the range up or down (along the scale), by at least one step. |
| Home, End | As far down or up as the thumb goes (a range's start up to its end). |

In a right-to-left layout a horizontal slider runs from the right, its `min` at the right end: Left is a step up and
Right a step down, and a drag to the left raises the value. A vertical slider keeps Right and Up as a step up.

Each key that changes the value reports `onChange` and then `onChangeEnd`. Arrows and pages repeat while held. The keys
reach the slider only while no text input edits.

## Accessibility

- Each thumb is an adjustable element (`"adjustable"`, a slider in the browser) with its label, its value and the
  values it can take: a range's start from `min` up to the end, its end from the start up to `max`, so screen readers
  read and set both. The value is spoken as the number with the step's decimals (`2.5`).
- A screen reader's increment and decrement actions (VoiceOver's swipe up and down) step the thumb, as the arrow keys
  do.
- The thumbs are the slider's elements for screen readers, named by `accessibilityLabel` (and a range's start by
  `startAccessibilityLabel`); a visible label among its children is read where it is.
- While `disabled`, screen readers say the thumbs are dimmed, and they take no actions.

See [Accessibility](https://nsh.dev/versions/main/docs/accessibility.md) for labels, roles and actions in general.

## Platform notes

- Every platform draws what the app styles. Presses and drags are followed in the core, for a mouse, a pen or a
  finger, and a scroll view around the slider does not take a drag that started on it.
- Tab moves the keyboard focus between thumbs on macOS and the web, where the focused thumb takes the slider keys.
- Screen readers: VoiceOver (iOS, macOS) and TalkBack adjust each thumb; UI Automation (Windows), GTK's accessibility
  (Linux) and the browser (`role="slider"`, `aria-valuenow`, `aria-valuetext`) get its range and value.

Source: https://nsh.dev/versions/main/elements/slider

---

# Switch

A switch turns a setting on or off, and the change takes effect at once. It owns the behavior: presses, keyboard
activation, the disabled state, and the switch role and its value for screen readers. The look is the app's: a
`Switch` has no colors, sizes, motion or label of its own. It is made of a track with a thumb inside it, then its
children (a label), and the app styles each part, with `checked:` and `disabled:` classes that follow the switch.

```rust
use nsh_base::{switch, theme};
use nsh_core::prelude::*;

fn wifi() -> impl IntoElement {
    let on = signal(false);
    switch()
        .checked(on)
        .on_change(move |next: &bool| on.set(*next))
        .flex_row()
        .items_center()
        .gap_3()
        .track_style(|s| {
            s.w(px(44.0))
                .p(px(2.0))
                .rounded_full()
                .bg(move || theme().muted)
                .transition_colors()
                .checked(|s| s.bg(move || theme().primary))
        })
        .thumb_style(|s| {
            s.size(px(20.0))
                .rounded_full()
                .bg(move || theme().background)
                .shadow_sm()
                .transition_transform()
                .checked(|s| s.translate_x(px(20.0)))
        })
        .child(text("Wi-Fi"))
}
```

```tsx
import { mount, signal, Text } from "nsh";
import { Switch } from "nsh/base";

function App() {
  const on = signal(false);
  return (
    <Switch
      checked={on()}
      onChange={({ checked }) => on.set(checked)}
      class="flex-row items-center gap-3"
      trackClass="w-11 rounded-full bg-muted p-0.5 transition-colors checked:bg-primary"
      thumbClass="size-5 rounded-full bg-background shadow-sm transition-transform checked:translate-x-5"
    >
      <Text>Wi-Fi</Text>
    </Switch>
  );
}

mount(App);
```

`Switch` comes from [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md), the `nsh-base` crate in Rust. The value is the app's: a
press reports the next value with `onChange`, and the switch shows the `checked` the app passes back. In Rust,
`switch()` makes one with a setter per prop (`.checked(..)`, `.track_style(..)`), a listener per event
(`.on_change(..)`), the typed style methods for the switch itself and `.child(..)` for its label; a part's style takes
the state methods (`.checked(..)`, `.disabled_style(..)`) that follow the switch.

## Props

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `checked` | `.checked(..)` | `boolean` | `false` | On or off. A press reports the next value with `onChange`; the switch shows the value the app passes back. |
| `disabled` | `.disabled(..)` | `boolean` | `false` | No presses and no press feedback; `disabled:` styles apply to the switch and its parts, and screen readers say it is dimmed. |
| `checkedStyle` | `.checked_style(\|s\| ..)` | `StyleProp<ViewStyle>` | none | The switch's style while `checked` and not disabled, as `checked:` classes. |
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | none | What screen readers say: what the switch turns on, when its children have no text that says it. |
| `trackClass`, `trackStyle` | `.track_style(\|s\| ..)` | `string`, `StyleProp<ViewStyle>` | none | The track, the part the thumb moves along. |
| `thumbClass`, `thumbStyle` | `.thumb_style(\|s\| ..)` | `string`, `StyleProp<ViewStyle>` | none | The thumb, inside the track. |
| `hitSlop` | `.hit_slop(..)` | `number \| Partial<Edges>` | none | How far outside its bounds presses still count, in points: one number for every side, or the sides named. As a view's `hitSlop`. |
| `children` | `.child(..)` | `JSX.Element` | none | The content after the track: a label, which screen readers say. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The switch itself: the row around the track and the label. |
| `activeStyle`, `hoverStyle`, `focusStyle`, `disabledStyle` | `.active(\|s\| ..)`, `.hover(..)`, `.focus(..)`, `.disabled_style(..)` | `StyleProp<ViewStyle>` | none | The switch's style while pressed, hovered, focused or disabled, as the `<state>:` classes. |

## Events

| Event | Rust | Description |
|---|---|---|
| `onChange` | `.on_change(\|checked: &bool\| ..)` | The switch was pressed: a tap, a click, Space or Return while it has the keyboard focus, or a screen reader's activation. It reports the value the switch asks for as `checked`, the opposite of the `checked` it has. |

A disabled switch reports nothing.

## Parts

| Part | Inside | Styled with | States |
|---|---|---|---|
| The switch | | `class`, `style` | `checked:`, `disabled:`, `active:`, `hover:`, `focus:` (or `checkedStyle`, `disabledStyle`, ...) |
| The track | the switch, first | `trackClass`, `trackStyle` | `checked:`, `disabled:` follow the switch |
| The thumb | the track | `thumbClass`, `thumbStyle` | `checked:`, `disabled:` follow the switch |
| The label | the switch, after the track | its own elements (`children`) | `group-checked:` and the other `group-*:` variants with `group` on the switch's `class` |

The thumb moves by its own `checked:` styles: a translation (`checked:translate-x-5`), or a margin or the track's
alignment (`checked:justify-end` on the track). A `transition-*` class animates the change natively. To place the
label before the track, reverse the row: `class="flex-row-reverse justify-between"`.

## Disabled

A disabled switch takes no presses, and screen readers announce it as dimmed. Its `disabled:` classes and those of
its track and thumb apply, over their `checked:` ones:

```tsx
<Switch
  checked={on()}
  disabled={!online()}
  onChange={({ checked }) => on.set(checked)}
  class="flex-row items-center gap-3 disabled:opacity-50"
  trackClass="w-11 rounded-full bg-muted p-0.5 checked:bg-primary disabled:bg-muted"
  thumbClass="size-5 rounded-full bg-background checked:translate-x-5"
>
  <Text>Sync over cellular</Text>
</Switch>
```

## A small target with hitSlop

A switch with no label beside it can be smaller than a finger. `hitSlop` makes presses that land near it count, in
points past each side, without changing its layout or its look: one number for every side, or the sides named
(`{ top: 8, bottom: 8 }`), as a [view's `hitSlop`](https://nsh.dev/versions/main/elements.md#presses-and-feedback) takes them.

```tsx
<Switch
  checked={on()}
  hitSlop={{ top: 8, bottom: 8 }}
  accessibilityLabel="Notifications"
  onChange={({ checked }) => on.set(checked)}
  trackClass="w-9 rounded-full bg-muted p-0.5 checked:bg-primary"
  thumbClass="size-4 rounded-full bg-background checked:translate-x-4"
/>
```

## Accessibility

- A switch is one element for screen readers, with the role `"switch"` and its value (on or off); the track and the
  thumb are parts of it. Its label is the text of its children; give `accessibilityLabel` when it has none.
- `disabled` is announced as the platform announces it (VoiceOver, TalkBack, UI Automation, the browser's accessibility
  tree).
- On macOS and the web a switch is a stop of the keyboard focus: Tab reaches it, Space and Return toggle it, and
  `focus:` styles show where the focus is.

See [Accessibility](https://nsh.dev/versions/main/docs/accessibility.md) for labels, roles and announcements in general.

## Platform notes

- iOS, Android and Mac Catalyst: a press is a tap that ends on the switch, its label included.
- Desktops (macOS, Windows, Linux, GPUI) and the web: a press is a click. On macOS and the web, Space and Return also
  toggle the switch that has the keyboard focus.
- Every platform draws what the app styles; the thumb moves as the app's styles and transitions say.

Source: https://nsh.dev/versions/main/elements/switch

---

# Table

A `Table` lays out a few rows the app writes as children (invoices, a summary, a comparison) and gives screen readers
a table: the table itself, groups of rows, rows, column headers and cells, each with its role. Its parts are
`TableHeader`, `TableBody` and `TableFooter` (groups of rows), `TableRow` (its cells side by side), `TableHead` (a
column's header cell), `TableCell` and `TableCaption`. The look is the app's: no part has colors, borders, paddings or
widths of its own, and each takes the app's `class` and `style`. For many rows, sorting, selection and resizable
columns, [`DataTable`](https://nsh.dev/versions/main/elements/data-table.md) is the table.

```rust
use nsh_base::{table, table_body, table_cell, table_head, table_header, table_row, theme};
use nsh_core::prelude::*;

fn invoices() -> impl IntoElement {
    let cell = |label: &'static str| table_cell().w(px(120.0)).px_3().py_2().child(text(label));
    table()
        .accessibility_label("Recent invoices")
        .child(
            table_header().child(
                table_row()
                    .border_b_1()
                    .border_color(move || theme().border)
                    .child(table_head().w(px(120.0)).px_3().py_2().child(text("Invoice")))
                    .child(table_head().w(px(120.0)).px_3().py_2().child(text("Amount"))),
            ),
        )
        .child(table_body().child(table_row().child(cell("INV001")).child(cell("$250.00"))))
}
```

```tsx
import { mount, Text } from "nsh";
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "nsh/base";

function App() {
  return (
    <Table accessibilityLabel="Recent invoices">
      <TableHeader>
        <TableRow class="border-b border-border">
          <TableHead class="w-32 px-3 py-2"><Text>Invoice</Text></TableHead>
          <TableHead class="w-32 px-3 py-2"><Text>Amount</Text></TableHead>
        </TableRow>
      </TableHeader>
      <TableBody>
        <TableRow>
          <TableCell class="w-32 px-3 py-2"><Text>INV001</Text></TableCell>
          <TableCell class="w-32 px-3 py-2"><Text>$250.00</Text></TableCell>
        </TableRow>
      </TableBody>
    </Table>
  );
}

mount(App);
```

`Table` and its parts come from [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md), the `nsh-base` crate in Rust, where `table()`,
`table_header()`, `table_body()`, `table_footer()`, `table_row()`, `table_head()`, `table_cell()` and
`table_caption()` make them, with the typed style methods and `.child(..)`. A row lays its cells out side by side; the
app gives cells their widths, so the columns line up.

## Props

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | none | `Table` only: what screen readers call the table. |
| `children` | `.child(..)` | `JSX.Element` | none | What the part holds: groups and a caption in a `Table`, rows in a group, cells in a row, content in a cell. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The part's look and layout. |

## Parts

| Part | Inside | Role for screen readers |
|---|---|---|
| `Table` | | table |
| `TableHeader` | `Table` | row group: the rows of column headers |
| `TableBody` | `Table` | row group: the rows of data |
| `TableFooter` | `Table` | row group: totals, a summary row |
| `TableRow` | a group, or `Table` | row; its cells side by side |
| `TableHead` | a `TableRow` of the header | column header |
| `TableCell` | `TableRow` | cell |
| `TableCaption` | `Table` | content the app shows about the table |

Each platform gives the roles to its screen reader: table, row, cell and column header roles on Linux (AT-SPI), the
web (ARIA), Android and the GPUI backend; grids and groups on macOS and Windows; headers as headers on iOS.

## See also

- [DataTable](https://nsh.dev/versions/main/elements/data-table.md): a table of any number of rows and columns, with selection, sorting and resizable,
  movable columns.
- [Accessibility](https://nsh.dev/versions/main/docs/accessibility.md): the `accessibilityRole` values, `table`, `row`, `cell`, `columnheader` and `rowgroup`
  among them.

Source: https://nsh.dev/versions/main/elements/table

---

# Tabs

Tabs switch between the sections of one place: the overview and the activity of a project, the views of a document.
Each `Tab` owns the behavior of one tab: presses, keyboard activation, the disabled state, and the tab role and its
selected state for screen readers. A `Tabs` around them is the tab list, which screen readers announce as one set. The
look is the app's: a tab has no colors, sizes or label of its own. Its children are the app's label, and
`selected:` classes on the tab, or `group-selected:` classes on what is inside it, follow its state. The content of
each section is the app's too: it shows the one its value names, next to the list. The list's indicator, an
underline or a pill the app styles, sits on the selected tab and travels to the next one natively
([Indicator](#indicator)).

```rust
use nsh_base::{tab, tabs, theme};
use nsh_core::prelude::*;

fn sections() -> impl IntoElement {
    let section = signal("overview");
    let item = move |value: &'static str, label: &'static str| {
        let selected = move || section.get() == value;
        tab()
            .selected(selected)
            .on_press(move |_: &()| section.set(value))
            .rounded(move || theme().radius)
            .px_3()
            .py_2()
            .child(text(label).text_sm().text_color(move || {
                if selected() { theme().foreground } else { theme().muted_foreground }
            }))
    };
    view()
        .gap_4()
        .child(
            tabs()
                .flex_row()
                .self_start()
                .gap_1()
                .p_1()
                .rounded(move || theme().radius)
                .bg(move || theme().muted)
                .indicator_style(|s| {
                    s.top_1()
                        .bottom_1()
                        .rounded(move || theme().radius)
                        .bg(move || theme().background)
                })
                .child(item("overview", "Overview"))
                .child(item("activity", "Activity")),
        )
        .child(text(move || {
            if section.get() == "overview" {
                "Visitors, sign-ups and conversion this week."
            } else {
                "Deploys, invoices and new members, newest first."
            }
        }).text_color(move || theme().foreground))
}
```

```tsx
import { mount, signal, Text, View } from "nsh";
import { Tab, Tabs } from "nsh/base";

function App() {
  const section = signal("overview");
  const item = (value: string, label: string) => (
    <Tab
      selected={section() === value}
      onPress={() => section.set(value)}
      class="group rounded-(--radius) px-3 py-2"
    >
      <Text class="text-sm text-muted-foreground group-selected:text-foreground">{label}</Text>
    </Tab>
  );
  return (
    <View class="gap-4">
      <Tabs
        class="flex-row self-start gap-1 rounded-(--radius-lg) bg-muted p-1"
        indicatorClass="inset-y-1 rounded-(--radius) bg-background"
      >
        {item("overview", "Overview")}
        {item("activity", "Activity")}
      </Tabs>
      <Text class="text-foreground">
        {section() === "overview"
          ? "Visitors, sign-ups and conversion this week."
          : "Deploys, invoices and new members, newest first."}
      </Text>
    </View>
  );
}

mount(App);
```

`Tab` and `Tabs` come from [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md), the `nsh-base` crate in Rust. The value is the
app's: the list holds none. Each tab is told whether it is selected; a press reports `onPress`, the app sets its value
and shows that section, and every tab shows the `selected` the app passes back. The list's corners and the tabs' are
concentric: the list's padding (`p-1`) is the difference between `radius.lg` and `radius`. The selected tab's fill is
the list's indicator (`indicatorClass`, inside that padding: `inset-y-1`), which springs to the tab the app selects. In
Rust, `tab()` and `tabs()` make them, with a setter per prop (`.selected(..)`), a listener per event (`.on_press(..)`),
the typed style methods and `.child(..)` for their content.

## Props

### Tab

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `selected` | `.selected(..)` | `boolean` | `false` | The current tab of its list: screen readers say it is selected, and `selected:` styles apply. A press reports `onPress`; the tab shows the value the app passes back. |
| `disabled` | `.disabled(..)` | `boolean` | `false` | No presses and no press feedback; `disabled:` styles apply, and screen readers say it is dimmed. |
| `selectedStyle` | `.selected_style(\|s\| ..)` | `StyleProp<ViewStyle>` | none | The tab's style while selected and not disabled, as `selected:` classes. |
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | none | What screen readers say: the tab's name, when its children have no text that says it (an icon). |
| `children` | `.child(..)` | `JSX.Element` | none | The app's label, icon or badge, which screen readers say. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The tab itself: the surface around its label. |
| `activeStyle`, `hoverStyle`, `focusStyle`, `disabledStyle` | `.active(\|s\| ..)`, `.hover(..)`, `.focus(..)`, `.disabled_style(..)` | `StyleProp<ViewStyle>` | none | The tab's style while pressed, hovered, focused or disabled, as the `<state>:` classes. |

### Tabs

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `indicatorClass` | `.indicator_class(..)` | `string` | none | The Tailwind classes of the indicator on the selected tab: its look and its place across the list (`bottom-0 h-0.5` for an underline in a row, `inset-y-1` for a pill). Along the list it spans the selected tab, inside its own margins on that axis. With `indicatorClass` or `indicatorStyle` the list has an indicator. |
| `indicatorStyle` | `.indicator_style(\|s\| ..)` | `StyleProp<ViewStyle>` | none | The style of the indicator, over `indicatorClass`. |
| `children` | `.child(..)` | `JSX.Element` | none | The tabs of the list, and whatever the app lays out between them. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The list's layout and look: a column by default, `flex-row` for a row. |

## Events

| Event | Rust | Description |
|---|---|---|
| `onPress` (`Tab`) | `.on_press(\|_: &()\| ..)` | The tab was pressed: a tap, a click, Space or Return while it has the keyboard focus, or a screen reader's activation; or an arrow key, Home or End of its list moved the keyboard focus to it. It runs before anything changes: the tab shows the `selected` the app passes back. |

The selected tab reports its presses too, so the app can act on a second press (scroll its section to the top, say).
A disabled tab reports nothing.

## Parts

| Part | Inside | Styled with | States |
|---|---|---|---|
| The list | | `Tabs`' `class`, `style` | |
| The indicator | the list, behind the tabs | `indicatorClass`, `indicatorStyle` | on the selected tab |
| The tab | the list | `Tab`'s `class`, `style` | `selected:`, `disabled:`, `active:`, `hover:`, `focus:` (or `selectedStyle`, `disabledStyle`, ...) |
| The label | the tab | its own elements (`children`) | `group-selected:`, `group-disabled:` and the other `group-*:` variants with `group` on the tab's `class` |
| The section's content | next to the list | the app's elements | the app's value |

Show the selected tab through its own surface: a fill, a stronger label, a heavier weight (see
[Design guides](https://nsh.dev/versions/main/docs/design-guides.md#interaction-states)).

## Indicator

An underline under the selected tab, a pill behind it or a segmented control's raised segment is the list's
indicator: a view the app styles with `indicatorClass` and `indicatorStyle`, drawn behind the tabs and absolutely
positioned in the list. Native Shell places it on the selected tab after each layout. Along the list (a row's width,
a column's height) it spans that tab, inside the indicator's own margins on that axis (`mx-3` for an underline
shorter than its tab); across the list its classes place it:

```tsx
// An underline at the bottom of a row of tabs.
<Tabs class="flex-row gap-4 border-b border-border" indicatorClass="bottom-0 h-0.5 bg-foreground">
  {item("overview", "Overview")}
  {item("activity", "Activity")}
</Tabs>

// A pill behind the selected tab, inside the list's padding.
<Tabs class="flex-row self-start gap-1 rounded-(--radius-lg) bg-muted p-1" indicatorClass="inset-y-1 rounded-(--radius) bg-background shadow-sm">
  {item("overview", "Overview")}
  {item("activity", "Activity")}
</Tabs>
```

When the app selects another tab, the indicator springs there natively, as GPUI Kit's tab bar indicator does; with
reduced motion it moves at once. While no tab is selected it is hidden; while several are, it is on the first. A
resize or a change of a tab's width moves it in the same frame as the tabs. The
indicator needs no layout events and no code of the app's: the selected tab is the one whose `selected` is true. In a
list that scrolls, the scroll view goes around the `Tabs`, and the indicator scrolls with the tabs.

## Disabled

A disabled tab takes no presses, and screen readers announce it as dimmed. Its `disabled:` classes apply over its
`selected:` ones, and `group-disabled:` classes inside it follow:

```tsx
<Tab
  selected={section() === "billing"}
  disabled={!isOwner()}
  onPress={() => section.set("billing")}
  class="group rounded-(--radius) px-3 py-2 selected:bg-background disabled:opacity-50"
>
  <Text class="text-sm text-muted-foreground group-selected:text-foreground">Billing</Text>
</Tab>
```

## Accessibility

- A tab is one element for screen readers, with the role `"tab"` and its selected state. Its label is the text of its
  children, or `accessibilityLabel`.
- `Tabs` has the role `"tablist"`: screen readers hear the tabs inside it as one set, each still an element of its
  own.
- `disabled` is announced as the platform announces it (VoiceOver, TalkBack, UI Automation, the browser's accessibility
  tree).
- On macOS and the web the list is one stop of the keyboard focus, and the arrow keys move between its tabs (below).
- The indicator is hidden from screen readers and takes no focus: the tabs alone are the list's elements.

See [Accessibility](https://nsh.dev/versions/main/docs/accessibility.md) for labels, roles and announcements in general.

## Keyboard

On macOS and the web, where Tab reaches the views that take presses, a `Tabs` list follows the
[WAI-ARIA tabs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/):

| Key | What it does |
|---|---|
| Tab, Shift+Tab | Enters the list at the selected tab (the first tab that is not disabled while none is), and leaves it in one step. |
| Right, Down | Moves the focus to the next tab, from the last to the first. |
| Left, Up | Moves the focus to the previous tab, from the first to the last. |
| Home, End | Moves the focus to the first or the last tab. |
| Space, Return | Presses the focused tab. |

The arrow keys skip disabled tabs, and the tab they move to reports `onPress`, so the app selects it as the focus
moves: the section follows the focus. Both pairs of arrows move, whatever the list's layout, which is the app's
class. In a right-to-left layout the row runs from the right, so Left and Right trade places: Left moves to the next
tab and Right to the previous; Up, Down, Home and End keep theirs. `focus:` styles show where the focus is. A `Tab` outside a `Tabs` is a stop of its own.

## Platform notes

- iOS, Android and Mac Catalyst: a press is a tap that ends on the tab, its label included.
- Desktops (macOS, Windows, Linux, GPUI) and the web: a press is a click. On macOS and the web, Space and Return also
  press the tab that has the keyboard focus, and the arrow keys, Home and End move it ([Keyboard](#keyboard)).
- Every platform draws what the app styles: the tabs, the selected one's surface, the indicator and the sections'
  content. The indicator's travel is a native layout animation on every platform.

Source: https://nsh.dev/versions/main/elements/tabs

---

# TextView

`TextView` shows a document written in Markdown, in HTML or as blocks the app builds: headings, paragraphs, emphasis,
links, lists and task lists, quotes and GitHub's alerts, code, tables, images, formulas, footnotes and disclosures. It
is made for the replies of AI models in a chat: the reply streams in as Markdown, and each chunk shows the text with its
formatting in place. Parsing happens in Rust, and the document is drawn with [`Text`](https://nsh.dev/versions/main/elements/text.md) elements and views.

It owns behavior and comes with a reading typography of its own: 15pt text in generous 25.5pt lines, semibold
headings with room above them, links underlined in the theme's `primary` color, code in the theme's `font-mono` in a bordered, rounded box, tables ruled on every side with a tinted header row, quotes with a line at their side and
alerts as tinted boxes with an icon in GitHub's alert colors. Its colors are the theme's tokens (`foreground`, `muted-foreground`, `border`,
`muted`, `primary`, and `destructive` for a caution), so a theme and the dark appearance reach
it. Each part takes the app's styles over these defaults: `classes` and `styles` in TSX, typed styles by part
(`TextViewParts`) in Rust. Rust makes one with `nsh_base::text_view()`, TSX with `<TextView>` from `nsh/base`.

```rust
use nsh_base::{TextViewLinkPressEvent, text_view, theme};
use nsh_core::prelude::*;

const README: &str = "# Release notes

**Faster lists** and a new `TextView`:

- Markdown and HTML
- [x] Streaming replies
- [ ] Your own syntax

> [!TIP]
> Style every part with `TextViewParts`.";

fn release_notes() -> impl IntoElement {
    scroll().flex_1().child(
        text_view()
            .markdown(README)
            .on_link_press(|TextViewLinkPressEvent { url, .. }: &TextViewLinkPressEvent| log::info!("open {url}"))
            .p_5()
            .text_base()
            .text_color(theme().foreground),
    )
}
```

```tsx
import { mount, Scroll } from "nsh";
import { TextView } from "nsh/base";

const README = `# Release notes

**Faster lists** and a new \`TextView\`:

- Markdown and HTML
- [x] Streaming replies
- [ ] Your own syntax

> [!TIP]
> Style every part with \`classes\`.`;

function App() {
  return (
    <Scroll class="flex-1" contentClass="p-5">
      <TextView
        markdown={README}
        class="text-base text-neutral-900 dark:text-neutral-100"
        classes={{
          heading1: "text-3xl",
          code: "rounded bg-neutral-100 dark:bg-neutral-800",
          link: "text-blue-600",
          alertTip: "border-l-4 border-green-600 pl-3",
        }}
        onLinkPress={({ url }) => console.log("open", url)}
      />
    </Scroll>
  );
}

mount(App);
```

In Rust, `text_view()` makes one as `view()` makes a view: a setter per prop (`.markdown(..)`, `.options(..)`,
`.selectable(..)`), a closure per render function (`.render_image(|image| ..)`), a listener per event
(`.on_link_press(..)`) and the typed style methods for its root (`.p_5()`, `.text_color(..)`), whose text styles pass
to every part.

## Built on Text

`TextView` is made of [`Text`](https://nsh.dev/versions/main/elements/text.md) elements, and its text behaves exactly as the Text page describes. Every
paragraph, heading, table cell and code block is one native `Text`: one block that lays out, wraps, follows the font
scale and, with `selectable`, selects and copies. Strong, emphasis, struck-through and the other inline marks
are its [spans](https://nsh.dev/versions/main/elements/text.md#spans); inline code is a span with a [span background](https://nsh.dev/versions/main/elements/text.md#span-backgrounds), so
`code: "rounded bg-neutral-100"` gives it a rounded background; links are
[pressable spans](https://nsh.dev/versions/main/elements/text.md#links); images and inline custom nodes are
[inline attachments](https://nsh.dev/versions/main/elements/text.md#inline-views-and-images). Text styles on the root pass to every part, as
[text styles](https://nsh.dev/versions/main/elements/text.md#text-styles) pass from a `Text` to its spans.

With `selectable`, the whole document selects as one, as a web page does: a drag (or, on touch screens, a long press
and the handles) runs from one paragraph, list item, cell or code block to the next, and Copy takes the text of them
all. A `selectable` `TextView` selects as one of its own; inside a
[selectable view](https://nsh.dev/versions/main/elements/text-selection.md), its selection also runs on into the texts and other `TextView`s around it.

What `TextView` adds is the rest: reading Markdown, HTML or a document into blocks, the views around the texts (lists,
quotes, tables, code blocks, disclosures, footnotes), streaming, styles by part, render functions and extensions.

## The document

The content is one of three props, read in this order:

- **`markdown`**: CommonMark with GitHub's additions (tables, task lists, strikethrough, autolinks, footnotes, alerts),
  formulas (`$…$` and `$$…$$`) and HTML inside the Markdown.
- **`html`**: HTML as a reader shows it. Text, structure and inline formatting come through; scripts, styles, form
  controls and hidden elements stay out. A fragment or a whole page both work (a page shows its body).
- **`document`**: blocks the app builds or keeps: plain objects in TSX, `nsh_base::text_view::Document` in Rust
  ([The document model](#the-document-model)).

```rust
use nsh_base::text_view;
use nsh_base::text_view::{Block, Document, Inline};
use nsh_core::prelude::*;

fn shipping() -> impl IntoElement {
    text_view().html(r#"<h2>Shipping</h2><p>Orders ship in <b>2 days</b>. <a href="/faq">FAQ</a></p>"#)
}

fn total() -> impl IntoElement {
    text_view().document(Document::new(vec![
        Block::Heading { level: 2, content: vec![Inline::text("Total")], anchor: None },
        Block::paragraph(vec![Inline::Strong { content: vec![Inline::text("$42.00")] }]),
    ]))
}
```

```tsx
<TextView html={`<h2>Shipping</h2><p>Orders ship in <b>2 days</b>. <a href="/faq">FAQ</a></p>`} />

<TextView document={{
  blocks: [
    { type: "heading", level: 2, content: [{ type: "text", text: "Total" }] },
    { type: "paragraph", content: [{ type: "strong", content: [{ type: "text", text: "$42.00" }] }] },
  ],
}} />
```

`TextView` grows with its content. Put it in a [`Scroll`](https://nsh.dev/versions/main/elements/scroll.md) (or a row of a [`List`](https://nsh.dev/versions/main/elements/list.md)) for long
documents.

## Styling the parts

`class` and `style` style the root, a column of the blocks; text styles set there (color, size, font) pass to every
part. The root is also the part `root`: `styles.root` takes text styles with their types (`style` is typed as a
view's), and `classes.root` classes. `classes` takes Tailwind classes by part and `styles` inline styles by part. A part's classes come after its own
default styles, so they win; its `styles` win over its classes. In Rust, the parts take typed styles: `TextViewParts`
gives each `TextViewPart` a function refining its style, for every `TextView` below the view that provides it
([Typed part styles](#typed-part-styles)), and the root takes the style methods. Line heights in the defaults are set in points: a
class that changes a part's size sets its line height too (Tailwind's `text-*` classes do).

```rust
use nsh_base::{TextViewPart, TextViewParts, text_view, theme};
use nsh_core::prelude::*;

fn reply(markdown: Signal<SharedString>) -> impl IntoElement {
    provide_context(
        TextViewParts::new()
            .part(TextViewPart::Heading, |s| s.text_color(rgb(0x0a0a0a)))
            .part(TextViewPart::Heading2, |s| s.text_xl().mt_2())
            .part(TextViewPart::Blockquote, |s| {
                s.border_l(px(2.0)).border_color(rgb(0xd4d4d4)).pl_3().text_color(rgb(0x525252))
            })
            .part(TextViewPart::CodeBlock, |s| s.rounded_lg().bg(rgb(0xf5f5f5)))
            .part(TextViewPart::CodeBlockHeader, |s| s.px_3().pt_2())
            .part(TextViewPart::CodeBlockCode, |s| s.p_3().text_size(px(13.0)))
            .part(TextViewPart::Table, |s| s.rounded_lg().border_1().border_color(rgb(0xe5e5e5)))
            .part(TextViewPart::TableHead, |s| s.bg(rgb(0xfafafa)))
            .part(TextViewPart::TableCell, |s| {
                s.px_3().py_2().border_t_1().border_color(rgb(0xe5e5e5))
            })
            .part(TextViewPart::TaskMarkerChecked, |s| s.text_color(rgb(0x16a34a)))
            .part(TextViewPart::Link, |s| s.text_color(theme().primary)),
    );
    text_view()
        .markdown(move || markdown.get())
        .gap_3()
        .text_size(px(15.0))
        .line_height(px(24.0))
        .text_color(rgb(0x262626))
        .font_family("Inter")
}
```

```tsx
<TextView
  markdown={reply()}
  class="gap-3 text-[15px] leading-6 text-neutral-800"
  classes={{
    heading: "text-neutral-950",
    heading2: "text-xl mt-2",
    blockquote: "border-l-2 border-neutral-300 pl-3 text-neutral-600",
    codeBlock: "rounded-lg bg-neutral-100",
    codeBlockHeader: "px-3 pt-2",
    codeBlockCode: "p-3 text-[13px]",
    table: "rounded-lg border border-neutral-200",
    tableHead: "bg-neutral-50",
    tableCell: "px-3 py-2 border-t border-neutral-200",
    taskMarkerChecked: "text-green-600",
  }}
  styles={{ root: { fontFamily: "Inter" }, link: { color: "#2563eb" } }}
/>
```

Some nodes are several parts, which apply in order: a level 2 heading is `heading` then `heading2`; an alert is
`blockquote`, `alert`, then its kind (`alertNote`, ...); a task marker is `listMarker`, `taskMarker`, then
`taskMarkerChecked` when done; the header row is `tableRow` then `tableHead`, and its cells `tableCell` then
`tableHeaderCell`.

| Part | Rust | What it is |
|---|---|---|
| `root` | `Root` | The text view itself, a column of its blocks; text styles here pass to every part. |
| `paragraph` | `Paragraph` | Every paragraph. |
| `heading` | `Heading` | Every heading, before its level's part. |
| `heading1` … `heading6` | `Heading1` … `Heading6` | Headings of that level (27, 20, 17, then 15pt, semibold). |
| `blockquote` | `Blockquote` | Quotations and alerts: a column of their blocks with a line at their side. |
| `alert` | `Alert` | Every alert (`> [!NOTE]`), after `blockquote`: a tinted box, a row of its icon and its blocks. |
| `alertNote`, `alertTip`, `alertImportant`, `alertWarning`, `alertCaution` | `AlertNote`, `AlertTip`, `AlertImportant`, `AlertWarning`, `AlertCaution` | Alerts of that kind. |
| `alertIcon` | `AlertIcon` | The icon of an alert: a ring with a glyph in the alert's color. |
| `list` | `List` | Every list: a column of its items. |
| `orderedList`, `unorderedList` | `OrderedList`, `UnorderedList` | Numbered and bulleted lists, after `list`. |
| `listItem` | `ListItem` | Every item: a row of its marker and its blocks. |
| `listMarker` | `ListMarker` | The marker of an item (`•`, `◦`, `▪` by depth, or `1.`), right-aligned in the indent before the item. |
| `taskMarker` | `TaskMarker` | The marker of a task item: a box drawn as a view, filled with a `✓` when done; after `listMarker`. |
| `taskMarkerChecked` | `TaskMarkerChecked` | The marker of a done task item, after `taskMarker`. |
| `listItemContent` | `ListItemContent` | The column of an item's blocks. |
| `codeBlock` | `CodeBlock` | Code blocks: a bordered, rounded box of the code, with the header over it. |
| `codeBlockHeader` | `CodeBlockHeader` | The row of a code block's actions (`codeBlockActions`), floating over its top right corner. |
| `codeBlockScroll` | `CodeBlockScroll` | The horizontal scroll view around a code block's code. |
| `codeBlockCode` | `CodeBlockCode` | The code of a code block (monospace, as written). |
| `code` | `Code` | Code in text (monospace, on a rounded background). |
| `keyboard` | `Keyboard` | Keys (`<kbd>`, as code). |
| `strong` | `Strong` | Strong text (semibold). |
| `emphasis` | `Emphasis` | Emphasized text (italic). |
| `strikethrough` | `Strikethrough` | Struck-through text. |
| `underline` | `Underline` | Underlined text (`<u>`, `<ins>`). |
| `highlight` | `Highlight` | Highlighted text (`<mark>`, on a rounded yellow). |
| `superscript`, `subscript` | `Superscript`, `Subscript` | Superscript and subscript (smaller). |
| `link` | `Link` | Links (in the theme's `primary` color, underlined). |
| `image` | `Image` | Images. |
| `math` | `Math` | Formulas in text, typeset when there is no `renderMath`. |
| `mathBlock` | `MathBlock` | Formula blocks, typeset and centered when there is no `renderMath`. |
| `table` | `Table` | Tables: `renderTableActions`' content, then the scroll view of the cells. |
| `tableScroll` | `TableScroll` | The horizontal scroll view of a table's cells: columns fit their content when there is room, wrap down to a floor when the view is narrower, and past that the table scrolls. |
| `tableRow` | `TableRow` | Every row of a table: a view behind its cells, for backgrounds and borders (text styles go on `tableCell`). |
| `tableHead` | `TableHead` | The header row, after `tableRow`. |
| `tableCell` | `TableCell` | Every cell. |
| `tableHeaderCell` | `TableHeaderCell` | The header row's cells (smaller, muted), after `tableCell`. |
| `rule` | `Rule` | Thematic breaks: a line drawn as a top border. |
| `details` | `Details` | Disclosures (`<details>`). |
| `summary` | `Summary` | The summary of a disclosure; a press opens and closes it. |
| `summaryMarker` | `SummaryMarker` | The marker of a summary (`▸`, `▾`). |
| `footnotes` | `Footnotes` | The footnotes after the blocks: a column. |
| `footnote` | `Footnote` | A footnote: a row of its number and its blocks. |
| `footnoteLabel` | `FootnoteLabel` | The number of a footnote. |
| `footnoteReference` | `FootnoteReference` | A reference to a footnote in text (its number, smaller). |
| `custom` | `Custom` | Custom nodes shown as their content (when no render function shows them). |

## Streaming AI replies

Pass the reply as it grows, with `options={{ streaming: true }}` (`MarkdownOptions { streaming: true, .. }` in Rust). The end of a text that is still arriving often leaves
syntax open (`**bold`, `` `code ``, `[a link](htt`, a table whose header just arrived); streaming shows it as it will
look once closed, so the reader never sees stray `**` or `[`. Blocks are kept by position: the blocks that are complete
keep their views, and only the block being written is made again, so a long reply stays cheap to update.

`streamingCaret` follows the end of the document: inline at the end of the last text, wherever the last block ends (a
paragraph, a list item, a code block, a table's last cell), else on a line of its own after the last block (a rule,
content of a render function). Remove it when the reply is done.

```rust
use nsh_base::{MarkdownOptions, text_view};
use nsh_core::prelude::*;

/// A reply the app appends to as chunks arrive, with `done` set at the end.
fn reply(text: Signal<SharedString>, done: Signal<bool>) -> impl IntoElement {
    text_view()
        .markdown(move || text.get())
        .options(move || MarkdownOptions { streaming: !done.get(), ..Default::default() })
        .streaming_caret(when(
            move || !done.get(),
            || view().ml_0p5().h_4().w_2().rounded_sm().bg(rgb(0xa3a3a3)),
        ))
}
```

```tsx
import { signal, View } from "nsh";
import { TextView } from "nsh/base";

function Reply(props: { stream: AsyncIterable<string> }) {
  const text = signal("");
  const done = signal(false);
  (async () => {
    for await (const chunk of props.stream) text.update((t) => t + chunk);
    done.set(true);
  })();
  return (
    <TextView
      markdown={text()}
      options={{ streaming: !done() }}
      streamingCaret={done() ? undefined : <View class="ml-0.5 h-4 w-2 rounded-sm bg-neutral-400" />}
    />
  );
}
```

The caret is the app's own view, so it can blink or pulse with [`nsh`'s animation API](https://nsh.dev/versions/main/modules/nsh.md#animation), and new
blocks can fade in with the app's animations.

## Links

Links are [pressable spans](https://nsh.dev/versions/main/elements/text.md#links). A press on one calls `onLinkPress` with `{ url }`; the app decides what it opens (a page of its own, a
[`WebView`](https://nsh.dev/versions/main/elements/web-view.md), a scroll to a heading). Headings have anchors (GitHub's: `## Getting started` is
`#getting-started`), so a link to `#getting-started` arrives as that string, and a footnote reference arrives as
`#footnote-<label>`. In a terminal Tab reaches each link and footnote reference in turn, and Return presses the focused
one: `onLinkPress` hears it as it hears a press.

```rust
use nsh_base::{TextViewLinkPressEvent, text_view};
use nsh_core::prelude::*;

fn doc(markdown: &'static str) -> impl IntoElement {
    text_view().markdown(markdown).on_link_press(|TextViewLinkPressEvent { url, .. }: &TextViewLinkPressEvent| {
        match url.strip_prefix('#') {
            Some(anchor) => scroll_to_anchor(anchor),
            None => open_web(url),
        }
    })
}
```

```tsx
<TextView
  markdown={doc}
  onLinkPress={({ url }) => {
    if (url.startsWith("#")) scrollToAnchor(url.slice(1));
    else nav.push({ name: "web", url });
  }}
/>
```

`scroll_to_anchor` and `open_web` (`scrollToAnchor` and `nav` in TSX) stand for the app's own functions.

With `links="open"`, a press on a link to another site or app (a URL with a scheme: `https:`, `mailto:`, ...) also
opens it outside the app with [`openUrl`](https://nsh.dev/versions/main/modules/nsh.md#openurl), under the app's `openUrl` capability,
after `onLinkPress` reported it; anchors in the document (`#…`) are only reported. The default, `"report"`, opens
nothing.

```rust
use nsh_base::{TextViewLinks, text_view};

text_view().markdown(doc).links(TextViewLinks::Open)
```

```tsx
<TextView markdown={doc} links="open" />
```

## Render functions

Render functions put the app's own content into the document. Each one takes the value of a part and returns its content (JSX in TSX, an element in Rust); a
part keeps what was rendered for it while its value stays the same, so during streaming only the part being written is
rendered again.

| Prop | Rust | Value | Replaces or adds |
|---|---|---|---|
| `renderCodeBlock` | `.render_code_block(\|code\| ..)` | `TextViewCodeBlock` (`CodeBlock`) | Replaces a code block (syntax highlighting of your own). |
| `renderCodeBlockAction` | `.render_code_block_action(\|action\| ..)` | `TextViewCodeAction` | The icon of a code block action of the app's (`codeBlockActions`); the button around it is `TextView`'s. |
| `renderTableActions` | `.render_table_actions(\|table\| ..)` | `TextViewTable` (`Table`) | Adds content above a table (copy, export). |
| `renderMath` | `.render_math(\|math\| ..)` | `TextViewMath` | Replaces a formula: `{ tex, display }`, `display` for a `$$…$$` block. |
| `renderImage` | `.render_image(\|image\| ..)` | `TextViewImage` (`Image`) | Replaces an image (`{ src, alt, title }`): your own loading, sizing, a viewer on press. |
| `renderCustom` | `.render_custom(\|node\| ..)` | `TextViewCustomNode` (`CustomNode`) | Shows a custom node, by its `name` ([Markdown extensions](#markdown-extensions)). |

Code blocks carry actions over their top right corner, all drawn alike: ghost buttons whose background shows while
hovered or pressed, shown while a pointer is over the block on desktops and always on touch screens. `copy` is built
in: it copies the code and shows a check for a moment. Other actions are the app's: `renderCodeBlockAction` draws
their icon and `onCodeBlockAction` reports their presses (the built-in `copy` too, after it copied). `copy` writes the
clipboard as `Clipboard` does, so it needs the app's `clipboard` capability (`nsh.json`).

```rust
use nsh_base::{TextViewCodeAction, TextViewCodeActionEvent, text_view};
use nsh_core::prelude::*;

fn reply(markdown: Signal<SharedString>) -> impl IntoElement {
    text_view()
        .markdown(move || markdown.get())
        .code_block_actions(vec![
            TextViewCodeAction::new("copy").with_label("Copy code"),
            TextViewCodeAction::new("run").with_label("Run"),
        ])
        .render_code_block_action(|_action: &TextViewCodeAction| text("▶").text_xs())
        .on_code_block_action(|event: &TextViewCodeActionEvent| {
            if event.id == "run" {
                run(&event.code.code);
            }
        })
}
```

```tsx
import { Text } from "nsh";
import { TextView } from "nsh/base";

<TextView
  markdown={reply()}
  codeBlockActions={[
    { id: "copy", label: "Copy code" },
    { id: "run", label: "Run" },
  ]}
  renderCodeBlockAction={(action) => <Text class="text-xs">▶</Text>}
  onCodeBlockAction={({ id, code }) => id === "run" && run(code.code)}
/>
```

Code blocks are highlighted out of the box: for a language named on the fence (`ts`, `tsx`, `rust`, `python`, `bash`,
`json`, `toml`, `yaml`, `diff` and about two hundred more), the code shows in Allsum's code palette, light or dark with the
appearance; a block without a language shows plain. An app with highlighting of its own shows its code with
`renderCodeBlock`, from its own component or one of its Rust crate; a Rust view gives `TextView` its highlighter with
[`CodeHighlighter`](#syntax-highlighting). Here code with highlighting of the app's own, and an image that fills the
width:

```rust
use nsh_base::text_view;
use nsh_base::text_view::{CodeBlock, Image};
use nsh_base::TextViewMath;
use nsh_core::prelude::*;

fn reply(markdown: Signal<SharedString>) -> impl IntoElement {
    text_view()
        .markdown(move || markdown.get())
        .render_code_block(|code: &CodeBlock| highlighted(code.language.clone(), code.code.clone()))
        .render_image(|img: &Image| {
            image(img.src.clone())
                .label(img.alt.clone())
                .aspect_ratio(16.0 / 9.0)
                .w_full()
                .rounded_lg()
        })
        .render_math(|math: &TextViewMath| math_view(math.tex.to_string(), math.display))
}
```

```tsx
import { Image, View } from "nsh";

<TextView
  markdown={reply()}
  renderCodeBlock={(code) => <Highlighted language={code.language} code={code.code} />}
  renderImage={(image) => (
    <Image src={image.src} accessibilityLabel={image.alt} class="aspect-video w-full rounded-lg" />
  )}
  renderMath={(math) => <MathView tex={math.tex} display={math.display} />}
/>
```

`Highlighted` and `MathView` (`highlighted` and `math_view` in Rust) stand for the app's own components (a
highlighter, a formula renderer, or a component of its Rust crate). Without `renderMath` `TextView` typesets a formula itself (`math` and `mathBlock` parts) with KaTeX's TeX support and fonts, in the text's color, the same on every platform; TeX it cannot read shows as its source in monospace.

## Markdown extensions

`extensions` turns syntax of the app's into custom nodes, which `renderCustom` shows. Each extension has a `name`
(the `name` of the nodes it makes) and one of four kinds of syntax:

| Kind | Rust | Matches | The node |
|---|---|---|---|
| `pattern` | `MarkdownExtension::pattern(name, regex)` | A regular expression in text (Rust's `regex` syntax), outside code and links | Inline; `text` is the match, `attributes` its groups: `"1"`, `"2"`, … and named groups by name |
| `language` | `MarkdownExtension::language(name, language)` | Fenced code blocks of that language (```` ```chart ````) | A block; `text` is the code, `attributes.meta` the rest of the info string |
| `tag` | `MarkdownExtension::tag(name, tag)` | HTML or MDX elements of that tag, any case (`<Callout kind="tip">`) | Its attributes, its content parsed: `children` (blocks) for an element on its own lines, `content` (inline) inside text |
| `container` | `MarkdownExtension::container(name, container)` | Containers `:::name` … `:::` | A block of the Markdown inside (`children`); `:::note[Heads up]` gives `attributes.label`, `{key=value}` the other attributes |

````rust
use nsh_base::text_view::{CustomNode, Document};
use nsh_base::{MarkdownExtension, text_view};
use nsh_core::prelude::*;

const MESSAGE: &str = r#"Thanks @ada! Here are the numbers:

```chart
12, 19, 7, 25
```

<Callout kind="tip">Charts update live.</Callout>

:::note[Heads up]
Numbers are in thousands.
:::"#;

fn custom(node: &CustomNode) -> AnyElement {
    match node.name.as_str() {
        "mention" => text(node.text.clone())
            .font_weight(FontWeight::SEMIBOLD)
            .text_color(rgb(0x2563eb))
            .into_element(),
        "chart" => bar_chart(node.text.split(',').filter_map(|v| v.trim().parse().ok()).collect())
            .into_element(),
        "callout" => view()
            .rounded_lg()
            .bg(rgb(0xfffbeb))
            .p_3()
            .child(text_view().document(Document::new(node.children.clone())))
            .into_element(),
        _ => view()
            .gap_1()
            .border_l(px(4.0))
            .border_color(rgb(0x3b82f6))
            .pl_3()
            .child(
                text(node.attributes.get("label").cloned().unwrap_or_else(|| "Note".into()))
                    .font_weight(FontWeight::SEMIBOLD),
            )
            .child(text_view().document(Document::new(node.children.clone())))
            .into_element(),
    }
}

fn message() -> impl IntoElement {
    text_view()
        .markdown(MESSAGE)
        .extensions(vec![
            MarkdownExtension::pattern("mention", r"@(\w+)"),
            MarkdownExtension::language("chart", "chart"),
            MarkdownExtension::tag("callout", "callout"),
            MarkdownExtension::container("note", "note"),
        ])
        .render_custom(custom)
}
````

````tsx
import { Text, View } from "nsh";
import { TextView } from "nsh/base";
import type { MarkdownExtension, TextViewCustomNode } from "nsh/base";

const extensions: MarkdownExtension[] = [
  { name: "mention", pattern: "@(\\w+)" },
  { name: "chart", language: "chart" },
  { name: "callout", tag: "callout" },
  { name: "note", container: "note" },
];

const message = `Thanks @ada! Here are the numbers:

\`\`\`chart
12, 19, 7, 25
\`\`\`

<Callout kind="tip">Charts update live.</Callout>

:::note[Heads up]
Numbers are in thousands.
:::`;

function Custom(props: { node: TextViewCustomNode }) {
  const node = props.node;
  switch (node.name) {
    case "mention":
      return <Text class="font-semibold text-blue-600">{node.text}</Text>;
    case "chart":
      return <BarChart values={node.text!.split(",").map(Number)} />;
    case "callout":
      return (
        <View class="rounded-lg bg-amber-50 p-3">
          <TextView document={{ blocks: node.children ?? [] }} />
        </View>
      );
    default:
      return (
        <View class="gap-1 border-l-4 border-blue-500 pl-3">
          <Text class="font-semibold">{node.attributes?.label ?? "Note"}</Text>
          <TextView document={{ blocks: node.children ?? [] }} />
        </View>
      );
  }
}

<TextView markdown={message} extensions={extensions} renderCustom={(node) => <Custom node={node} />} />;
````

`BarChart` (`bar_chart` in Rust) stands for the app's own chart. The mention pattern's group is in
`node.attributes?.["1"]` (`node.attributes["1"]` in Rust: `ada`) and the whole match in `node.text` (`@ada`). A custom node with no render function shows its content.
A view returned for an inline node (a chip) sits in its line by its own `verticalAlign`: `align-middle`
(`verticalAlign: "middle"`) centers it on the text, and its line keeps the paragraph's `lineHeight` unless the view is taller.

### Options

`options` picks the Markdown syntax read beyond CommonMark and GitHub's; in Rust it is a `MarkdownOptions` with the
same fields (`MarkdownOptions { streaming: true, ..Default::default() }`):

| Key | Type | Default | Description |
|---|---|---|---|
| `math` | `boolean` | `true` | Formulas: `$…$` in text, `$$…$$` blocks. |
| `html` | `boolean` | `true` | HTML inside the Markdown is read as the `html` prop reads it; `false` shows it as text. |
| `alerts` | `boolean` | `true` | GitHub's alerts: `> [!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, `[!CAUTION]`. |
| `frontmatter` | `boolean` | `false` | YAML front matter (`---` … `---` first) becomes a custom node `frontmatter` whose `text` is the YAML. |
| `mdx` | `boolean` | `false` | MDX: JSX elements are custom nodes named by their tag, `{expressions}` custom nodes `expression`; raw HTML is then read as text. |
| `streaming` | `boolean` | `false` | The text is still arriving: syntax its end leaves open shows as if it were closed. |

## The document model

The `document` prop and the render functions' values are plain objects, each node tagged by its `type`. The types
come from `nsh/base`: `TextViewDocument`, `TextViewBlock`, `TextViewInline`, `TextViewCodeBlock`, `TextViewTable`,
`TextViewListItem`, `TextViewImage`, `TextViewFootnote`, `TextViewAlert` and `TextViewCustomNode`. In Rust they are
the types of `nsh_base::text_view` (`Document`, `Block`, `Inline`, `CodeBlock`, `Table`, `ListItem`, `Image`,
`Footnote`, `Alert`, `CustomNode`): `Block` and `Inline` are enums whose variants are the types below in PascalCase
(`Block::Heading { level, content, anchor }`, `Inline::Strong { content }`), with the same fields in snake case.

| Block `type` | Fields |
|---|---|
| `paragraph` | `content` |
| `heading` | `level` (1–6), `content`, `anchor?` |
| `blockquote` | `children`, `alert?` (`"note"`, `"tip"`, `"important"`, `"warning"`, `"caution"`) |
| `list` | `ordered?`, `start?`, `loose?`, `items` (`{ checked?, children }`) |
| `codeBlock` | `language?`, `meta?`, `code` |
| `math` | `tex` |
| `table` | `align?` (`"none"`, `"left"`, `"center"`, `"right"` per column), `head` (cells), `rows?` (rows of cells); a cell is `{ content }` |
| `rule` | |
| `details` | `open?`, `summary` (inline), `children` |
| `custom` | `name`, `attributes?`, `text?`, `data?`, `children?`, `content?` |

| Inline `type` | Fields |
|---|---|
| `text` | `text` |
| `strong`, `emphasis`, `strikethrough`, `underline`, `highlight`, `superscript`, `subscript` | `content` |
| `code` | `code` |
| `keyboard` | `text` |
| `link` | `url`, `title?`, `content` |
| `image` | `src`, `alt?`, `title?` |
| `math` | `tex` |
| `break` | |
| `footnoteReference` | `label`, `index` |
| `custom` | as the block |

A document also has `footnotes?`: `{ label, index, children }`, shown after the blocks in the order of their first
reference. An app can store replies as documents, build them from its own data, or mix in custom nodes that
`renderCustom` shows.

### Parsing and plain text

`TextView` also reads documents without showing them, synchronously:

| Function | Rust | Returns |
|---|---|---|
| `TextView.parse(markdown, options?, extensions?)` | `TextView::parse(markdown, options, extensions)` | The `TextViewDocument` the `markdown` prop would show. |
| `TextView.parseHtml(html, extensions?)` | `TextView::parse_html(html, extensions)` | The `TextViewDocument` the `html` prop would show. |
| `TextView.plainText(document)` | `TextView::plain_text(document)`, `Document::plain_text()` | The document's text without markup: blocks separated by blank lines, list items and table rows by line breaks, cells by tabs. |

A copy button for a whole reply:

```rust
use nsh_base::{TextView, button};
use nsh_core::prelude::*;

fn copy_reply(reply: Signal<SharedString>) -> impl IntoElement {
    button()
        .on_press(move || {
            let document = TextView::parse(reply.get().to_string(), None, None);
            set_clipboard(TextView::plain_text(document));
        })
        .child(text("Copy"))
}
```

```tsx
<Button onPress={() => Clipboard.writeText(TextView.plainText(TextView.parse(reply())))}>
  <Text>Copy</Text>
</Button>
```

An app can also parse once and keep the document (`document={doc}`), or change it before showing it.

## In Rust

Rust views use the same component from the `nsh-base` crate, with the examples above in their Rust tabs. Three things
are Rust's own: an app's highlighter, typed styles by part and Markdown plugins, each given to every `TextView` below
a view with `provide_context`. The document types are under `nsh_base::text_view`, where `Parser` also reads
documents with plugins (`Parser::new().plugin(..).markdown(source)`).

### Syntax highlighting

`TextView` highlights code with syntect in Allsum's code palette (`nsh-base`'s feature `highlight`, on by default);
a large block shows plain at once and takes its colors when a background thread has highlighted it.
`CodeHighlighter` is the app's highlighter in its place, given to every `TextView` below a view with `provide_context`.
It gets each code block and returns the styles of byte ranges of its code (in order, not overlapping; what they leave
out is plain); `TextView` shows the code as spans with those styles, inside its usual code block (header, actions,
scroll view, parts). The highlighter can be anything that turns code into styled ranges: `tree-sitter`, syntect with
a theme of the app's, ...

```rust
use std::ops::Range;

use nsh_base::{CodeHighlighter, text_view::CodeBlock};
use nsh_core::{element::StyleRefinement, prelude::*};

/// The app's highlighter (here with syntect, set up once by the app).
fn highlight(code: &CodeBlock) -> Vec<(Range<usize>, StyleRefinement)> {
    my_syntect::ranges(code.language.as_deref(), &code.code)
        .map(|(range, color, bold)| {
            let style = StyleRefinement::default().text_color(color);
            (range, if bold { style.font_weight(FontWeight::BOLD) } else { style })
        })
        .collect()
}

fn chat() -> impl IntoElement {
    provide_context(CodeHighlighter::new(highlight));
    view().child(messages())
}
```

`my_syntect::ranges` stands for the app's glue to its highlighter and `messages` for the app's view of the chat.
`renderCodeBlock`, when given, shows the code block in place of all of this.

### Typed part styles

`TextViewParts` styles parts with typed styles instead of class strings, for Rust views: each `TextViewPart` (one per
part of the [table above](#styling-the-parts)) gets a function refining its `StyleRefinement`. Given with
`provide_context`, they apply to every `TextView` below, before its `classes` and `styles`; theme colors read in them
follow the light and dark appearance.

```rust
use nsh_base::{TextViewPart, TextViewParts, theme};
use nsh_core::prelude::*;

fn chat_parts() {
    provide_context(
        TextViewParts::new()
            .part(TextViewPart::Heading1, |s| s.text_2xl().font_weight(FontWeight::BOLD))
            .part(TextViewPart::Code, |s| s.bg(theme().muted).rounded(px(4.0)))
            .part(TextViewPart::Link, |s| s.text_color(theme().primary)),
    );
}
```

### Markdown plugins

A `MarkdownPlugin` reads Markdown syntax in Rust: it gets each node of the syntax tree (markdown-rs's `mdast`) before
the parser reads it, and returns a block or inline content of its own, usually a `CustomNode`; it can also show the
custom nodes it makes. A view provides plugins to every `TextView` below it:

```rust
use nsh_base::text_view::{mdast, CustomNode, Inline, MarkdownPlugin, MarkdownPlugins, ParseContext};
use nsh_core::prelude::*;

struct Tickers;

impl MarkdownPlugin for Tickers {
    fn name(&self) -> &str {
        "tickers"
    }

    /// `$AAPL` in inline code becomes a ticker node.
    fn inline(&self, node: &mdast::Node, _cx: &mut ParseContext<'_>) -> Option<Inline> {
        let mdast::Node::InlineCode(code) = node else { return None };
        let symbol = code.value.strip_prefix('$')?;
        Some(Inline::Custom(CustomNode::new("ticker").with_text(symbol)))
    }

    fn render(&self, node: &CustomNode) -> Option<AnyElement> {
        (node.name == "ticker").then(|| text(node.text.clone()).font_weight(FontWeight::BOLD).into_element())
    }
}

fn chat() -> impl IntoElement {
    provide_context(MarkdownPlugins::new().with(Tickers));
    view().child(messages())
}
```

A plugin's `render` comes first, then `renderCustom`, then the node's content. `configure` turns on more of
markdown-rs's syntax, and `ParseContext` reads a node's children as the parser does.

## Props

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `markdown` | `.markdown(..)` | `string` | | The document as Markdown. |
| `html` | `.html(..)` | `string` | | The document as HTML, when `markdown` is not given. |
| `document` | `.document(..)` | `TextViewDocument` | | The document as blocks, when neither `markdown` nor `html` is given. |
| `options` | `.options(..)` | `MarkdownOptions` | all defaults | The Markdown syntax read ([Options](#options)). |
| `extensions` | `.extensions(..)` | `MarkdownExtension[]` | `[]` | The app's syntax, as custom nodes ([Markdown extensions](#markdown-extensions)). |
| `classes` | `.classes(..)` | `TextViewClasses` | `{}` | Tailwind classes by part. |
| `styles` | `.styles(..)` | `TextViewStyles` | `{}` | Inline styles by part (each a `StyleProp<TextStyle>`), over the classes. |
| `selectable` | `.selectable(..)` | `boolean` | `false` | The document is selectable as one: a selection runs across its paragraphs, headings, cells and code blocks ([Text selection](https://nsh.dev/versions/main/elements/text-selection.md)). |
| `links` | `.links(..)` | `"report" \| "open"` | `"report"` | What a press on a link does: reports it (`onLinkPress`), and with `"open"` also opens a link to another site or app outside the app ([Links](#links)). |
| `codeBlockScrollbar` | `.code_block_scrollbar(..)` | `boolean` | `true` | Code blocks show their horizontal scroll indicator. |
| `tableScrollbar` | `.table_scrollbar(..)` | `boolean` | `true` | Tables show their horizontal scroll indicator. |
| `streamingCaret` | `.streaming_caret(..)` | `JSX.Element` | | Shown at the end of the document: inline after the last text, else on its own line. |
| `renderCustom` | `.render_custom(\|node\| ..)` | `(node: TextViewCustomNode) => JSX.Element` | | Shows custom nodes. |
| `renderCodeBlock` | `.render_code_block(\|code\| ..)` | `(code: TextViewCodeBlock) => JSX.Element` | | Shows code blocks. |
| `codeBlockActions` | `.code_block_actions(..)` | `TextViewCodeAction[]` | `[]` | The actions over each code block's top right corner: `{ id: "copy" }` built in, others the app's. |
| `renderCodeBlockAction` | `.render_code_block_action(\|action\| ..)` | `(action: TextViewCodeAction) => JSX.Element` | | The icon of an action of the app's. |
| `renderTableActions` | `.render_table_actions(\|table\| ..)` | `(table: TextViewTable) => JSX.Element` | | Content above each table. |
| `renderMath` | `.render_math(\|math\| ..)` | `(math: TextViewMath) => JSX.Element` | | Shows formulas. |
| `renderImage` | `.render_image(\|image\| ..)` | `(image: TextViewImage) => JSX.Element` | | Shows images. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | | The root, a column of the blocks; its text styles pass to every part (typed text styles: `styles.root`). |

In Rust the classes and styles by part are `TextViewClasses` and `TextViewStyles`; a Rust view usually styles the
parts with [`TextViewParts`](#typed-part-styles).

## Events

| Event | Rust | Description |
|---|---|---|
| `onLinkPress` | `.on_link_press(\|event: &TextViewLinkPressEvent\| ..)` | A link was pressed: `{ url }`: its URL, `#anchor` for a heading, `#footnote-<label>` for a footnote. |
| `onCodeBlockAction` | `.on_code_block_action(\|event: &TextViewCodeActionEvent\| ..)` | A code block's action was pressed (after `copy` copied). |
| `onImagePress` | `.on_image_press(\|image: &Image\| ..)` | An image not in a link was pressed: `{ image }`, for the app to show it larger (a zoomable viewer of its own). |

## Accessibility

Screen readers read the document in order, text by text. `TextView` gives the structure its roles: headings are
headers, links are links (their title is the hint), task markers are checkboxes with their checked state, a
disclosure's summary is a button that says whether it is expanded, and images are read by their alt text.

## Related

- [Text](https://nsh.dev/versions/main/elements/text.md): the element every text of `TextView` is, with its spans, links, inline attachments and selection.
- [Text selection](https://nsh.dev/versions/main/elements/text-selection.md): one selection across several `TextView`s and texts.
- [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md): the other base components.
- [Styling](https://nsh.dev/versions/main/docs/styling.md) and [Tailwind](https://nsh.dev/versions/main/docs/tailwind.md).

Source: https://nsh.dev/versions/main/elements/text-view

---

# TimeField

A time field edits a time of day, a segment at a time: the hour, the minute, with `precision="second"` the second,
and with `hourCycle="h12"` AM or PM. A reminder's time, a meeting's start, the hours a shop opens. It is the time
under [DatePicker](https://nsh.dev/versions/main/elements/date-picker.md)'s calendar with `timePrecision`, on its own in the page.

The field owns the behavior: the time (the app's, or its own), which segment the keys edit, typing and stepping
digits, and what screen readers hear. The look is the app's: it styles the segments and the `:` between them, or
draws the segments itself.

```rust
use chrono::NaiveTime;
use nsh_base::{HourCycle, TimeFieldSegmentEntry, TimeOfDay, time_field};
use nsh_core::prelude::*;

fn reminder_time() -> impl IntoElement {
    let at = signal(TimeOfDay(NaiveTime::from_hms_opt(9, 30, 0).unwrap()));
    time_field()
        .value(move || Some(at.get()))
        .on_change(move |next: &TimeOfDay| at.set(*next))
        .hour_cycle(HourCycle::H12)
        .accessibility_label("Reminder time")
        .segment_class("rounded-sm focus:bg-accent disabled:opacity-50")
        .render_segment(|segment: &TimeFieldSegmentEntry| view().px_1().child(text(segment.label.clone())))
}
```

```tsx
import { mount, signal } from "nsh";
import { TimeField } from "nsh/base";

function App() {
  const at = signal("09:30");
  return (
    <TimeField
      value={at()}
      onChange={({ value }) => at.set(value)}
      hourCycle="h12"
      accessibilityLabel="Reminder time"
      class="h-9 w-32 flex-row items-center rounded-md border border-input px-2"
      segmentClass="rounded-sm px-0.5 text-sm tabular-nums focus:bg-accent focus:text-accent-foreground"
      separatorClass="text-sm text-muted-foreground"
    />
  );
}

mount(App);
```

`TimeField` comes from [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md), the `nsh-base` crate in Rust. In Rust, `time_field()`
makes one with a setter per prop (`.value(..)`, `.precision(..)`, `.hour_cycle(..)`) and a listener per event
(`.on_change(..)`). Its time is a `TimeOfDay`, a `chrono::NaiveTime`.

## Value

The value is a time of day on a 24-hour clock, as an HTML `<input type="time">`'s: `"HH:MM"`, or `"HH:MM:SS"` with
`precision="second"`, whatever `hourCycle` the field shows. With `value`, the app owns it: the field shows it and
reports each edit with `onChange({ value })`; the app sets `value` to follow it. Left out, the field keeps its own
time, from `defaultValue` at first (default `00:00`).

`precision` is the smallest unit the field edits, `"minute"` (the default) or `"second"`. `hourCycle` is how it counts
the hours: `"h23"` (the default) from 00 to 23, `"h12"` from 12 to 11 with an AM/PM segment after the numbers.

## Editing

One segment is selected; the keys edit it, as `gpui-base`'s time field:

- Up and Down step the segment by one and wrap around (59 to 00) without carrying into the next segment.
- Digits type into it, two at a time: a digit that cannot start a longer value (a `7` in the hour) completes the
  segment and moves to the next.
- `a` and `p` set AM and PM.
- Backspace and Delete reset the segment.

A press on a segment selects it. A press on the selected AM/PM segment switches it, since phones have no `a` and `p`
keys. The keys go to one native text field behind the segments, transparent, as an [OtpInput](https://nsh.dev/versions/main/elements/otp-input.md)'s: on
phones and tablets it brings up the number pad.

## Props

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `value` | `.value(..)` | `string` | none | The time, owned by the app. |
| `defaultValue` | `.default_value(..)` | `string` | `"00:00"` | The time at first, without `value`. |
| `precision` | `.precision(..)` | `"minute" \| "second"` | `"minute"` | The smallest unit it edits. |
| `hourCycle` | `.hour_cycle(..)` | `"h23" \| "h12"` | `"h23"` | How it counts the hours; `"h12"` adds an AM/PM segment. |
| `disabled` | `.disabled(..)` | `boolean` | `false` | No focus and no editing; `disabled:` styles apply to the field and its segments. |
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | none | What screen readers call the field. |
| `segmentClass`, `segmentStyle` | `.segment_class(..)`, `.segment_style(..)` | `string`, `StyleProp<TextStyle>` | none | Each segment: `focus:` on the selected one while the field has the focus, `disabled:` with the field; with `group`, its content follows them (`group-focus:`, `group-disabled:`). |
| `separatorClass`, `separatorStyle` | `.separator_class(..)`, `.separator_style(..)` | `string`, `StyleProp<TextStyle>` | none | Each `:` between the numbers. |
| `renderSegment` | `.render_segment(..)` | `(segment: TimeFieldSegmentEntry) => JSX.Element` | none | A segment's content, drawn by the app from what it shows; its label otherwise. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The field, around its segments (a row). |

`renderSegment` gets a `TimeFieldSegmentEntry`: `segment` (`"hour"`, `"minute"`, `"second"` or `"period"`), `value`
(the hour on the field's clock, the minute or the second; `0` for AM and `1` for PM) and `label` (two digits, or `AM` /
`PM`). It never gets the segment's state: the segment is `focus:` while the keys edit it and `disabled:` with the
field, and with `group` in `segmentClass` its content follows with `group-focus:` and `group-disabled:`. So a segment
is drawn again only when its value changes; moving between the segments and the focus coming and going draw nothing:

```tsx
<TimeField
  segmentClass="group rounded-sm px-0.5 focus:bg-primary"
  renderSegment={(segment) => <Text class="text-sm tabular-nums text-foreground group-focus:text-primary-foreground">{segment.label}</Text>}
/>
```

## Events

| Event | Rust | Description |
|---|---|---|
| `onChange` | `.on_change(\|value\| ..)` | The user changed the time: `{ value }`. Set `value` to follow it. A `value` the app passes is never reported. |

## Parts

| Part | Where | Styled with |
|---|---|---|
| The field | the root, a row | `class`, `style` |
| A segment | the field: hour, minute, second, AM/PM | `segmentClass`, `segmentStyle`, `renderSegment` (`group-focus:`, `group-disabled:` inside, under `group` in `segmentClass`) |
| A separator | the field, between two numbers | `separatorClass`, `separatorStyle` |

## Keyboard

Tab reaches the field with its selected segment. Then:

| Key | Action |
|---|---|
| Left / Right | The segment before or after. |
| Tab / Shift+Tab | The segment after or before; Tab from the last one and Shift+Tab from the first leave the field. |
| Up / Down | Steps the segment by one, wrapping around. |
| 0 to 9 | Types into the segment. |
| A / P | AM or PM. |
| Backspace, Delete | Resets the segment. |

## Accessibility

- The field is a text field named by `accessibilityLabel`; screen readers read the time it shows. `disabled` dims it.
- Phones and tablets show the number pad.

See [Accessibility](https://nsh.dev/versions/main/docs/accessibility.md) for labels, roles and announcements in general.

Source: https://nsh.dev/versions/main/elements/time-field

---

# Toast

Toasts are short messages shown for a while over the app: "Copied", "Draft deleted · Undo", "Could not send".
`nsh/base` provides their behavior in three unstyled pieces, the same as GPUI Kit's `gpui-base`:

- **`ToastManager`** keeps the toasts in order with their lifecycle: each one is `"starting"`, then `"present"` once
  the motion's duration has passed, counts its timeout down while present and not paused, and stays `"ending"` for
  the exit's duration before it is removed.
- **`ToastStack`** measures its toasts and lays them out from an edge, the newest nearest it: overlapping layers while
  collapsed, a list while expanded (the pointer on it, or a finger down on it), moved with springs.
- **`Toast`** is each toast's root: the `alert` role, its `transitionStatus` for the app's styles, a swipe that asks to
  dismiss it, and the screen reader reading its label as it shows.

The look and the content are the app's, and so is the convenience of showing a toast from anywhere: an app builds its
own `toast(...)` on these, as the gallery does (`examples/gallery/toast.tsx`) and as GPUI Kit's notifications are
built on `gpui-base`'s toasts.

```rust
use std::time::Duration;

use nsh_core::{time::now, prelude::*};

use nsh_base::{
    Anchor, ToastManager, ToastMotion, ToastOptions, ToastStackState, theme, toast, toast_stack,
};

fn toasts() -> impl IntoElement {
    let manager = stored(ToastManager::<u64, SharedString>::new(ToastMotion::sonner()));
    let shown = signal(Vec::new());
    let state = ToastStackState::new();
    let sync = move || {
        shown.set(manager.with(|m| {
            m.visible(3)
                .map(|(id, t, s)| (*id, t.clone(), s))
                .collect::<Vec<_>>()
        }))
    };
    // Advance the lifecycle while toasts are mounted, paused while expanded.
    set_interval(Duration::from_millis(50), move || {
        if manager.with(|m| m.advance(now(), state.is_expanded()).changed) {
            sync();
        }
    });
    manager.with(|m| {
        m.push(
            1,
            "Copied".into(),
            ToastOptions::timeout(Some(Duration::from_secs(5))),
            now(),
        )
    });
    sync();
    toast_stack()
        .placement(Anchor::BottomCenter)
        .state(state)
        .w(px(340.0))
        .child(each(
            shown,
            |(id, _, _)| *id,
            move |item, _| {
                toast()
                    .transition_status(move || item.get().2)
                    .accessibility_label(move || Some(item.get().1))
                    .on_dismiss_request(move || {
                        manager.with(|m| m.dismiss(&item.get().0, now()));
                    })
                    .rounded_xl()
                    .px_4()
                    .py_3()
                    .bg(move || theme().card)
                    .shadow_lg()
                    .transition_all()
                    .duration(200.0)
                    .starting_class("opacity-0 translate-y-4")
                    .ending_class("opacity-0 scale-95")
                    .child(text(move || item.get().1))
            },
        ))
}
```

```tsx
import { Overlay, signal, Text, safeArea } from "nsh";
import { Toast, type ToastEntry, ToastManager, ToastStack } from "nsh/base";

const manager = new ToastManager();
const shown = signal<ToastEntry[]>([]);
const expanded = signal(false);
const sync = () => shown.set(manager.visible(3));
// Advance the lifecycle on a timer, paused while the stack is expanded.
setInterval(() => {
  if (manager.advance(expanded()).changed) sync();
}, 50);

export function toast(title: string) {
  manager.push(crypto.randomUUID(), { title }, { timeout: 5000 });
  sync();
}

export function Toaster() {
  return (
    <Overlay class="inset-x-0 bottom-0 items-center p-4" style={{ paddingBottom: safeArea().bottom + 16 }}>
      <ToastStack placement="bottomCenter" class="w-80" onExpandedChange={(e) => expanded.set(e.expanded)} onCancel={() => {
        const newest = shown().filter((t) => t.status !== "ending").at(-1);
        if (newest) { manager.dismiss(newest.id); sync(); }
      }}>
        <Each of={shown()} key={(t: ToastEntry) => t.id}>
          {(t) => (
            <Toast
              transitionStatus={t().status}
              accessibilityLabel={(t().value as { title: string }).title}
              onDismissRequest={() => { manager.dismiss(t().id); sync(); }}
              class="rounded-xl bg-card px-4 py-3 shadow-lg transition-all duration-200"
              startingClass="opacity-0 translate-y-4"
              endingClass="opacity-0 scale-95"
            >
              <Text class="font-semibold text-card-foreground">{(t().value as { title: string }).title}</Text>
            </Toast>
          )}
        </Each>
      </ToastStack>
    </Overlay>
  );
}
```

`Toast`, `ToastStack` and `ToastManager` come from [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md). In Rust they are
`nsh_base`'s `toast`, `toast_stack` and `ToastManager`.

## ToastManager

The manager is headless: it renders nothing and runs no timer. The app pushes toasts, renders the ones
`visible(limit)` returns with their status, and calls `advance` on a timer while any is mounted, passing `paused`
while the stack is expanded. In Rust it is `ToastManager<I, T>` over the app's ids and values, with an `Instant` for
each call; in TS it is a class over string ids and any JSON value, on the engine's clock (a test's manual clock
included).

- `push(id, value, options)` adds the newest toast, replacing one with the same id (whose value it returns);
  `options.timeout` is its present time in milliseconds (none: it stays until dismissed).
- `dismiss(id)` begins a toast's exit; `dismissAll()` every toast's, returning their ids.
- `advance(paused)` moves the lifecycle on and reports what changed: `presented`, `ending` (their timeout ran out),
  `removed` (with their values), and `changed`.
- `visible(limit)` is the newest `limit` toasts that are not ending plus the ending ones, oldest first; `entries()`
  (Rust `iter()`) all of them; `get(id)`, `len()`, `isEmpty()`.

`ToastMotion` holds the tokens of both: `duration` (400 ms: the enter's deadline and the stack's spring response),
`exitDuration` (200 ms), `collapsedPeek` (14), `expandedGap` (14), `collapsedScaleStep` (0.05) and
`collapsedVisible` (3), Sonner's (`ToastMotion::sonner()` in Rust; fields left out in TS keep them).

## ToastStack

The stack's children are its toasts, oldest first. From its `placement` edge (`"topRight"` by default; the bottom
anchors lay out upward), collapsed toasts overlap `collapsedPeek` apart, each further one narrower by
`collapsedScaleStep`, and only `collapsedVisible` show; expanded, they are a list `expandedGap` apart (in a terminal three rows apart, so
each toast's frame keeps a blank row from the next's). Toasts that
arrive or leave, and expansion, move them with critically damped springs. It is expanded while the pointer is on it
or a finger is down on it (`onExpandedChange({ expanded })`; Rust `ToastStackState`, whose `is_expanded()` reads it), so
the app pauses the timeouts while the user reads or touches the toasts.

The app places the stack: in an [Overlay](https://nsh.dev/versions/main/elements/overlay.md) at the edge, inside the safe area. Its `class` and `style`
give its width. While it holds toasts it hears Escape and the Android back button (`onCancel`; `closeOnEscape={false}`
leaves them to the rest of the app): dismiss the newest.

## Toast

A toast is the `alert` role around the app's content. Its `transitionStatus` is the manager's, and its state classes
follow it over its `class`: `startingClass` in its first frame while `"starting"`, so its `transition` classes animate
from it (Tailwind's `starting:`, CSS's `@starting-style`); `endingClass` while `"ending"`, for the exit's duration;
`swipingClass` while a pointer swipes it (`transition-none` keeps it under the finger).

A finger or the mouse dragged toward `swipeDirection` (`"right"` by default; `null` turns swiping off) moves it, once
the pointer has moved, so its buttons stay buttons; let go past `swipeThreshold` points (50) or flicked, it moves on
out and asks to be dismissed (`onDismissRequest`), short of it, it goes back. The screen reader reads its
`accessibilityLabel` as it shows.

## Toast props

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `transitionStatus` | `.transition_status(..)` | `"starting" \| "present" \| "ending"` | `"starting"` | Its lifecycle phase. |
| `startingClass`, `endingClass`, `swipingClass` | `.starting_class(..)`, ... | `string` | none | Its classes in its first frame, while ending, while swiped. |
| `swipeDirection` | `.swipe_direction(..)` | `"right" \| "left" \| "up" \| "down" \| null` | `"right"` | The direction it is swiped away in. |
| `swipeThreshold` | `.swipe_threshold(..)` | `number` | `50` | How far a swipe goes before a release asks to dismiss it. |
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | none | What the screen reader reads as it shows. |
| `onDismissRequest` | `.on_dismiss_request(..)` | `() => void` | none | The user swiped it away. |

## ToastStack props

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `motion` | `.motion(..)` | `ToastMotion` | Sonner's | Its motion tokens. |
| `placement` | `.placement(..)` | `"topLeft" \| "topCenter" \| "topRight" \| "bottomLeft" \| "bottomCenter" \| "bottomRight" \| "leftCenter" \| "rightCenter"` | `"topRight"` | The edge it lays out from. |
| `closeOnEscape` | `.close_on_escape(..)` | `boolean` | `true` | It hears Escape and back while it holds toasts. |
| `onExpandedChange` | `.on_expanded_change(..)`, `.state(..)` | `(e: { expanded: boolean }) => void` | none | Interaction expanded or collapsed it. |
| `onCancel` | `.on_cancel(..)` | `() => void` | none | Escape or back: dismiss the newest. |

Source: https://nsh.dev/versions/main/elements/toast

---

# Toggle

A toggle is a button that stays on or off: bold in a text toolbar, a favorite star, a view option. `Toggle` owns the
behavior of one: presses, keyboard activation, the disabled state, and the button role with its pressed state for
screen readers, which announce it as a toggle button. A `ToggleGroup` around several is a toolbar: screen readers
announce it as one, and the keyboard reaches it in one stop and moves between its toggles with the arrow keys. The
look is the app's: a toggle has no colors, sizes, icon or label of its own. Its children are the app's icon or
label, and `aria-pressed:` classes on the toggle, or `group-aria-pressed:` classes on what is inside it, follow its
state.

```rust
use nsh_base::{theme, toggle, toggle_group};
use nsh_core::prelude::*;

fn formatting() -> impl IntoElement {
    let bold = signal(true);
    let italic = signal(false);
    let item = move |label: &'static str, on: Signal<bool>| {
        toggle()
            .pressed(on)
            .accessibility_label(label)
            .on_change(move |pressed: &bool| on.set(*pressed))
            .size_8()
            .items_center()
            .justify_center()
            .rounded(move || theme().radius)
            .pressed_style(|s| s.bg(move || theme().accent))
            .child(text(&label[..1]).text_sm().text_color(move || {
                if on.get() { theme().accent_foreground } else { theme().muted_foreground }
            }))
    };
    toggle_group()
        .flex_row()
        .self_start()
        .gap_1()
        .child(item("Bold", bold))
        .child(item("Italic", italic))
}
```

```tsx
import { mount, signal, Text } from "nsh";
import { Toggle, ToggleGroup } from "nsh/base";

function App() {
  const marks = signal<string[]>(["bold"]);
  const item = (value: string, label: string) => (
    <Toggle
      pressed={marks().includes(value)}
      accessibilityLabel={label}
      onChange={({ pressed }) =>
        marks.set(pressed ? [...marks(), value] : marks().filter((m) => m !== value))
      }
      class="group size-8 items-center justify-center rounded-(--radius) aria-pressed:bg-accent"
    >
      <Text class="text-sm text-muted-foreground group-aria-pressed:text-accent-foreground">{label[0]}</Text>
    </Toggle>
  );
  return (
    <ToggleGroup class="flex-row self-start gap-1">
      {item("bold", "Bold")}
      {item("italic", "Italic")}
    </ToggleGroup>
  );
}

mount(App);
```

`Toggle` and `ToggleGroup` come from [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md), the `nsh-base` crate in Rust. The value is
the app's: each toggle is told whether it is pressed, a press reports the value it asks for with `onChange`, and the
toggle shows the `pressed` the app passes back. The group holds no value either, so how many toggles may be pressed
is the app's too: any number (bold, italic and underline), or exactly one (an alignment, a view switcher), where the
app presses the toggle asked for, lets go of the others and keeps the pressed one pressed. In Rust, `toggle()` and
`toggle_group()` make them, with a setter per prop (`.pressed(..)`), a listener per event (`.on_change(..)`), the
typed style methods and `.child(..)` for their content.

## Props

### Toggle

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `pressed` | `.pressed(..)` | `boolean` | `false` | On or off: screen readers say it is pressed, and `aria-pressed:` styles apply. A press reports the other value with `onChange`; the toggle shows the value the app passes back. |
| `disabled` | `.disabled(..)` | `boolean` | `false` | No presses and no press feedback; `disabled:` styles apply, and screen readers say it is dimmed. A toggle in a disabled `ToggleGroup` is disabled too. |
| `pressedStyle` | `.pressed_style(\|s\| ..)` | `StyleProp<ViewStyle>` | none | The toggle's style while pressed and not disabled, as `aria-pressed:` classes. |
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | none | What screen readers say: what the toggle turns on, when its children have no text that says it (an icon). |
| `hitSlop` | `.hit_slop(..)` | `number \| Partial<Edges>` | none | How far outside its bounds presses still count, in points: one number for every side, or the sides named. As a view's `hitSlop`. |
| `children` | `.child(..)` | `JSX.Element` | none | The app's icon or label, which screen readers say. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The toggle itself: the surface around its content. |
| `activeStyle`, `hoverStyle`, `focusStyle`, `disabledStyle` | `.active(\|s\| ..)`, `.hover(..)`, `.focus(..)`, `.disabled_style(..)` | `StyleProp<ViewStyle>` | none | The toggle's style while a press is in progress, hovered, focused or disabled, as the `<state>:` classes. |

### ToggleGroup

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `disabled` | `.disabled(..)` | `boolean` | `false` | Every toggle in the group is disabled, whatever its own `disabled`. |
| `children` | `.child(..)` | `JSX.Element` | none | The toggles of the group, and whatever the app lays out between them (a separator). |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The group's layout and look: a column by default, `flex-row` for a row. |

## Events

| Event | Rust | Description |
|---|---|---|
| `onChange` (`Toggle`) | `.on_change(\|pressed: &bool\| ..)` | The toggle was pressed: a tap, a click, Space or Return while it has the keyboard focus, or a screen reader's activation. `{ pressed }` is the value it asks for, the opposite of `pressed`. It runs before anything changes: the toggle shows the `pressed` the app passes back. |

An arrow key of a `ToggleGroup` only moves the keyboard focus: it presses nothing. A disabled toggle reports nothing.

## Parts

| Part | Inside | Styled with | States |
|---|---|---|---|
| The group | | `ToggleGroup`'s `class`, `style` | |
| The toggle | the group, or anywhere | `Toggle`'s `class`, `style` | `aria-pressed:`, `disabled:`, `active:`, `hover:`, `focus:` (or `pressedStyle`, `disabledStyle`, ...) |
| The icon or label | the toggle | its own elements (`children`) | `group-aria-pressed:`, `group-disabled:` and the other `group-*:` variants with `group` on the toggle's `class` |

`aria-pressed:` is the toggle being on; `active:` is a press in progress, on or off. Show a pressed toggle through its
own surface: a fill, a raised pill, a stronger icon (see [Design guides](https://nsh.dev/versions/main/docs/design-guides.md#interaction-states)).

## Segmented

A group whose toggles are joined, one pressed at a time, is a segmented control (a view switcher): the app keeps one
value and presses the toggle that names it. The joined look is the app's classes:

```tsx
<ToggleGroup class="flex-row self-start">
  <Each of={["grid", "list"]}>
    {(value) => (
      <Toggle
        pressed={view() === value()}
        accessibilityLabel={`${value()} view`}
        onChange={({ pressed }) => pressed && view.set(value())}
        class="-ml-px h-8 px-3 border border-border first:ml-0 first:rounded-l-(--radius) last:rounded-r-(--radius) aria-pressed:bg-accent"
      >
        <Text class="text-sm">{value()}</Text>
      </Toggle>
    )}
  </Each>
</ToggleGroup>
```

## Disabled

A disabled toggle takes no presses, and screen readers announce it as dimmed. Its `disabled:` classes apply over its
`aria-pressed:` ones, and `group-disabled:` classes inside it follow. `disabled` on a `ToggleGroup` disables every
toggle in it, a toolbar the app locks:

```tsx
<ToggleGroup disabled={readonly()} class="flex-row gap-1">
  <Toggle pressed={bold()} onChange={({ pressed }) => bold.set(pressed)} class="size-8 disabled:opacity-50">
    <Text>B</Text>
  </Toggle>
</ToggleGroup>
```

## A small target with hitSlop

An icon toggle can be smaller than a finger. `hitSlop` makes presses that land near it count, in points past each side,
without changing its layout or its look: one number for every side, or the sides named (`{ top: 8, bottom: 8 }`), as a
[view's `hitSlop`](https://nsh.dev/versions/main/elements.md#presses-and-feedback) takes them.

```tsx
<Toggle
  pressed={favorite()}
  hitSlop={12}
  accessibilityLabel="Favorite"
  onChange={({ pressed }) => favorite.set(pressed)}
  class="size-5 items-center justify-center"
>
  <Text>★</Text>
</Toggle>
```

## Accessibility

- A toggle is one element for screen readers, with the role `"button"` and its pressed state: a toggle button. Its
  label is the text of its children, or `accessibilityLabel`.
- `ToggleGroup` has the role `"toolbar"`: screen readers hear the toggles inside it as one toolbar, each still an
  element of its own.
- `disabled` is announced as the platform announces it (VoiceOver, TalkBack, UI Automation, the browser's accessibility
  tree).
- On macOS and the web the group is one stop of the keyboard focus, and the arrow keys move between its toggles
  (below).

See [Accessibility](https://nsh.dev/versions/main/docs/accessibility.md) for labels, roles and announcements in general.

## Keyboard

On macOS and the web, where Tab reaches the views that take presses, a `ToggleGroup` follows the
[WAI-ARIA toolbar pattern](https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/):

| Key | What it does |
|---|---|
| Tab, Shift+Tab | Enters the group at the first pressed toggle (the first toggle that is not disabled while none is), and leaves it in one step. |
| Right, Down | Moves the focus to the next toggle, from the last to the first. |
| Left, Up | Moves the focus to the previous toggle, from the first to the last. |
| Home, End | Moves the focus to the first or the last toggle. |
| Space, Return | Presses the focused toggle. |

The arrow keys skip disabled toggles and press nothing: a toggle changes only when it is pressed. Both pairs of arrows
move, whatever the group's layout, which is the app's class. In a right-to-left layout Left and Right trade places:
Left moves to the next toggle and Right to the previous; Up, Down, Home and End keep theirs. `focus:` styles show where
the focus is. A `Toggle`
outside a `ToggleGroup` is a stop of its own.

## Platform notes

- iOS, Android and Mac Catalyst: a press is a tap that ends on the toggle, its content included.
- Desktops (macOS, Windows, Linux, GPUI) and the web: a press is a click. On macOS and the web, Space and Return also
  press the toggle that has the keyboard focus, and the arrow keys, Home and End move it ([Keyboard](#keyboard)).
- Every platform draws what the app styles: the toggles, the pressed ones' surface and the group's track.

Source: https://nsh.dev/versions/main/elements/toggle

---

# Toolbar

A toolbar is a bar of controls: a text editor's formatting, a media player's transport, a vertical palette of tools.
`Toolbar` owns the keyboard and the semantics of one: screen readers announce a toolbar (named by its
`accessibilityLabel`), and the keyboard reaches it in one stop and moves between its items with the arrow keys of its
`axis`. Its items are the `Button`s, `Toggle`s and `Link`s inside it, at any depth. A `ToolbarGroup` is a named run of
related items (undo and redo, the alignment), and a `ToolbarSeparator` a line the app draws between runs. The look is
the app's: the toolbar has no colors, padding or gaps of its own, and each control keeps its own state.

```rust
use nsh_base::{button, theme, toggle, toolbar, toolbar_group, toolbar_separator};
use nsh_core::prelude::*;

fn formatting() -> impl IntoElement {
    let bold = signal(false);
    toolbar()
        .accessibility_label("Formatting")
        .items_center()
        .gap_1()
        .child(
            toolbar_group()
                .accessibility_label("History")
                .child(button().accessibility_label("Undo").size_8().child(text("↶")))
                .child(button().accessibility_label("Redo").size_8().child(text("↷"))),
        )
        .child(toolbar_separator().w(px(1.0)).h_5().bg(move || theme().border))
        .child(
            toggle()
                .pressed(bold)
                .accessibility_label("Bold")
                .on_change(move |pressed: &bool| bold.set(*pressed))
                .size_8()
                .items_center()
                .justify_center()
                .pressed_style(|s| s.bg(move || theme().accent))
                .child(text("B")),
        )
}
```

```tsx
import { mount, signal, Text } from "nsh";
import { Button, Toggle, Toolbar, ToolbarGroup, ToolbarSeparator } from "nsh/base";

function App() {
  const bold = signal(false);
  return (
    <Toolbar accessibilityLabel="Formatting" class="items-center gap-1 self-start rounded-lg bg-muted p-1">
      <ToolbarGroup accessibilityLabel="History">
        <Button accessibilityLabel="Undo" class="size-8 items-center justify-center rounded-md hover:bg-accent">
          <Text>↶</Text>
        </Button>
        <Button accessibilityLabel="Redo" class="size-8 items-center justify-center rounded-md hover:bg-accent">
          <Text>↷</Text>
        </Button>
      </ToolbarGroup>
      <ToolbarSeparator class="h-5 w-px bg-border" />
      <Toggle
        pressed={bold()}
        accessibilityLabel="Bold"
        onChange={({ pressed }) => bold.set(pressed)}
        class="size-8 items-center justify-center rounded-md aria-pressed:bg-accent"
      >
        <Text>B</Text>
      </Toggle>
    </Toolbar>
  );
}

mount(App);
```

`Toolbar`, `ToolbarGroup` and `ToolbarSeparator` come from [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md), the `nsh-base` crate
in Rust. The toolbar holds no value: a toggle inside it is told whether it is pressed and reports `onChange`, a
button reports `onPress`, and the app keeps the state. In Rust, `toolbar()`, `toolbar_group()` and
`toolbar_separator()` make them, with a setter per prop (`.axis(..)`, `.disabled(..)`), the typed style methods and
`.child(..)` for their content.

## Props

### Toolbar

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `axis` | `.axis(..)` | `"horizontal" \| "vertical"` | `"horizontal"` | The direction its items run: the arrow keys that move along it (Left and Right, or Up and Down) and the direction it lays its children out in (a row, or a column). Read when the toolbar is made. |
| `disabled` | `.disabled(..)` | `boolean` | `false` | Every item of the toolbar is disabled, whatever its own `disabled`: no presses, no stop of the keyboard focus, dimmed for screen readers. |
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | none | What screen readers call the toolbar ("Formatting"), for a page with more than one. |
| `children` | `.child(..)` | `JSX.Element` | none | The items, their groups and separators, and whatever else the app lays out among them (a title, a spacer, an input). |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The bar's layout and look: alignment, gaps, padding, its surface. |

### ToolbarGroup

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `disabled` | `.disabled(..)` | `boolean` | `false` | Every item of the group is disabled, whatever its own `disabled`. |
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | none | What screen readers call the group ("History", "Alignment"). |
| `children` | `.child(..)` | `JSX.Element` | none | The group's items, and whatever the app lays out among them. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The group's layout and look. It runs along the toolbar's axis. |

### ToolbarSeparator

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The line: a hairline across a row (`h-5 w-px bg-border`) or a column (`h-px self-stretch bg-border`). |

## Items

The items of a toolbar are the `Button`s, `Toggle`s and `Link`s inside it, in its groups and in a
[`ToggleGroup`](https://nsh.dev/versions/main/elements/toggle.md) inside it too. A [`Menu`](https://nsh.dev/versions/main/elements/menu.md)'s or a [`Popover`](https://nsh.dev/versions/main/elements/popover.md)'s trigger is an
item as well: the view in its `trigger` slot, which the popup gives its presses, its focus and its `expanded` state. A
tool the app draws itself is a `Button` with the app's classes: a `Button` has no look of its own, so it looks as the
app styles it and is an item (a `View` with `onPress` stays a stop of its own, outside the arrow keys). A
`ToggleGroup` inside a toolbar is one of its groups: its toggles are the toolbar's items, screen readers hear a group,
and its `disabled` still disables its own toggles. Other controls (an `Input`, a `Select`, a `Slider`) stay stops of
their own and keep their arrow keys; place them at the end of the bar. What a popup an item opens shows (a popover's
fields and buttons, a menu's items, a hover card's links) is no part of the toolbar. The arrow keys go through the items in the order the
bar lays them out, however deep each one sits, and an item the app shows later takes its place among them.

## Parts

| Part | Inside | Styled with | States |
|---|---|---|---|
| The bar | | `Toolbar`'s `class`, `style` | |
| A group | the bar | `ToolbarGroup`'s `class`, `style` | |
| A separator | the bar, a group | `ToolbarSeparator`'s `class`, `style` | |
| An item | the bar, a group | the item's own `class`, `style` | its own: `aria-pressed:`, `disabled:`, `hover:`, `focus:`, `active:` |

Show the item the keyboard is on with `focus:` styles, and a pressed toggle through its own surface (see
[Design guides](https://nsh.dev/versions/main/docs/design-guides.md#interaction-states)).

## Vertical

A palette of tools is a column: `axis="vertical"` lays the items out top to bottom, and Up and Down move along them.

```tsx
<Toolbar axis="vertical" accessibilityLabel="Tools" class="gap-1 self-start rounded-lg bg-muted p-1">
  <Each of={["select", "pen", "shape", "text"]}>
    {(t) => (
      <Toggle
        pressed={tool() === t()}
        accessibilityLabel={t()}
        onChange={({ pressed }) => pressed && tool.set(t())}
        class="size-8 items-center justify-center rounded-md aria-pressed:bg-accent"
      >
        <Text>{t()[0].toUpperCase()}</Text>
      </Toggle>
    )}
  </Each>
</Toolbar>
```

## Disabled

`disabled` on a toolbar disables every item in it, a bar the app locks; on a group, the group's items. A disabled item
takes no presses, the arrow keys pass it by, and screen readers announce it as dimmed:

```tsx
<Toolbar disabled={readonly()} accessibilityLabel="Review" class="flex-row gap-1">
  <Button onPress={approve} class="h-8 px-3 disabled:opacity-50">
    <Text>Approve</Text>
  </Button>
</Toolbar>
```

## Accessibility

- `Toolbar` has the role `"toolbar"`, named by `accessibilityLabel`; its items stay elements of their own. On iOS the
  toolbar is a semantic group VoiceOver enters.
- `ToolbarGroup` has the role `"group"`, named by its `accessibilityLabel`, so a run of items reads as one unit. A
  `ToggleGroup` inside a toolbar is a group too.
- `ToolbarSeparator` is no element for screen readers.
- `disabled` is announced as the platform announces it (VoiceOver, TalkBack, UI Automation, the browser's accessibility
  tree).

See [Accessibility](https://nsh.dev/versions/main/docs/accessibility.md) for labels, roles and announcements in general.

## Keyboard

On macOS and the web, where Tab reaches the views that take presses, a `Toolbar` follows the
[WAI-ARIA toolbar pattern](https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/):

| Key | What it does |
|---|---|
| Tab, Shift+Tab | Enters the toolbar at the item the focus last left (at first, the first item that is not disabled), and leaves it in one step. |
| Right, Left (`axis="horizontal"`) | Moves the focus to the next or the previous item, from the last to the first and back. |
| Down, Up (`axis="vertical"`) | Moves the focus to the next or the previous item, from the last to the first and back. |
| Home, End | Moves the focus to the first or the last item. |
| Space, Return | Presses the focused item. |

The arrow keys skip disabled items and press nothing: a toggle changes only when it is pressed. The other pair of
arrows is left to the items (a menu's trigger opens its menu with Down). In a right-to-left layout a horizontal
toolbar runs from the right, so Left moves to the next item and Right to the previous; a vertical one keeps Down and
Up.

## Platform notes

- iOS, Android and Mac Catalyst: each item is pressed with a tap; the toolbar is a group screen readers announce.
- Desktops (macOS, Windows, Linux, GPUI) and the web: a press is a click. On macOS and the web the toolbar is one stop
  of Tab, and the arrow keys, Home and End move between its items ([Keyboard](#keyboard)).
- Every platform draws what the app styles: the bar, its groups, its separators and its items.

Source: https://nsh.dev/versions/main/elements/toolbar

---

# Tooltip

A tooltip is a short hint next to what it is about: what an icon button does, the full text of a truncated label.
On the desktops and in desktop browsers it shows once the pointer has rested on its trigger for `delay` (500 ms), and
hides when the pointer leaves or presses the trigger. On every device it also shows at once while the keyboard focus
is on its trigger, and hides when the focus leaves or Escape is pressed, so keyboard users read the same hints. Phones
and tablets otherwise show a tooltip only when the app opens it (`open`). It never takes the pointer or presses, so the
trigger works exactly as it does without it.

`Tooltip` from [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md) is given as the `tooltip` prop every element has
([Common props](https://nsh.dev/versions/main/elements.md#tooltips)), as GPUI's `.tooltip(..)`: the element is what the pointer rests on and what it
is placed against. The tooltip itself is the bubble: style it with `class` / `style`, and its children are what it says.

```rust
use nsh_base::tooltip;
use nsh_core::prelude::*;

fn save_button(on_save: impl Fn() + 'static) -> impl IntoElement {
    view()
        .on_press(on_save)
        .accessibility_label("Save")
        .p_2()
        .child(text("💾"))
        .tooltip(
            tooltip()
                .placement(Placement::Bottom)
                .rounded_md()
                .bg(rgb(0x111827))
                .px_2()
                .py_1()
                .child(text("Save the document").text_color(white())),
        )
}
```

```tsx
import { Text, View } from "nsh";
import { Tooltip } from "nsh/base";

function SaveButton(props: { onSave: () => void }) {
  return (
    <View
      onPress={props.onSave}
      accessibilityLabel="Save"
      class="p-2"
      tooltip={
        <Tooltip placement="bottom" class="rounded-md bg-gray-900 px-2 py-1">
          <Text class="text-white">Save the document</Text>
        </Tooltip>
      }
    >
      <Text>💾</Text>
    </View>
  );
}
```

It goes above its trigger by default (`placement`), on the other side when there is no room, and stays inside the safe
area. With `open` the app decides when it shows: it follows `onOpenChange`, which reports the pointer resting on the
trigger or leaving it and the keyboard focus coming and going, and can show it on any device.

In a terminal a tooltip is a line, as terminal apps show a hint: what it says shows at once on the bottom row of
the screen, in the terminal's own colors, while the keyboard focus or the pointer is on its trigger, and the row clears
when they leave. The pointer's hint shows over the focus's while the pointer is on its trigger; a toast's message takes
the row while it shows. `delay` is not waited for there (`Infinity` still keeps it to the app's `open`), and the
tooltip's own look and transitions apply only to the bubble the other devices show; its children, a shortcut's `Kbd`
included, show as they are.

It comes and goes with your transitions: `startingClass` is its look in its first frame and `endingClass` its look
once hidden, which it keeps while the `transition-*` classes of its `class` run; `onClose` follows.

```tsx
<Tooltip
  class="rounded-md bg-gray-900 px-2 py-1 transition-opacity duration-100"
  startingClass="opacity-0"
  endingClass="opacity-0"
>
  <Text class="text-white">Save the document</Text>
</Tooltip>
```

## Props

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `children` | `.child(..)` | `JSX.Element` | none | What it says. |
| `class`, `style` | `.app_class(..)`, `Styled` methods | `string`, `StyleProp<ViewStyle>` | none | The look of the bubble: the tooltip itself. |
| `startingClass`, `startingStyle` | `.starting_class(..)`, `.starting_style(..)` | `string`, `StyleProp<ViewStyle>` | none | Its look in its first frame: its transitions run from it. |
| `endingClass`, `endingStyle` | `.ending_class(..)`, `.ending_style(..)` | `string`, `StyleProp<ViewStyle>` | none | Its look once hidden: it stays while its transitions run. |
| `open` | `.open(..)` | `boolean` | none | Shown, controlled by the app. |
| `defaultOpen` | `.default_open(..)` | `boolean` | `false` | Shown at first, without `open`. |
| `delay` | `.delay(..)` | `number` | `500` | Milliseconds the pointer rests on the trigger before it shows (the keyboard focus shows it at once); `Infinity`: never by itself, neither for the pointer nor the focus, only when the app opens it. |
| `disabled` | `.disabled(..)` | `boolean` | `false` | It never shows. |
| `placement` | `.placement(..)` | `"top" \| "bottom" \| "left" \| "right"` | `"top"` | The side of the trigger it goes on. |
| `align` | `.align(..)` | `"start" \| "center" \| "end"` | `"center"` | How it lines up with the trigger along that side. |
| `offset` | `.offset(..)` | `number` | `4` | The gap between the trigger and the tooltip. |
| `margin` | `.margin(..)` | `number` | `4` | The distance it keeps from the edges of the safe area. |

## Events

| Event | Rust | Description |
|---|---|---|
| `onOpenChange` | `.on_open_change(\|e\| ..)` | The pointer rested on the trigger, or left or pressed it (`reason` `"hover"`); the keyboard focus came to it or left it (`"focus"`); Escape was pressed while it showed (`"cancel"`). |
| `onOpen` | `.on_open(\|\| ..)` | It is shown. |
| `onClose` | `.on_close(\|\| ..)` | It is gone, after its exit; also when the app hid it. |

## Accessibility

A tooltip repeats what its trigger says to screen readers: give the trigger an `accessibilityLabel` too, so the
hint is there for everyone.

Source: https://nsh.dev/versions/main/elements/tooltip

---

# Tree

A tree shows items that hold items: a project's files and folders, the sections of a settings sidebar, a document's
outline. `Tree` owns the behavior of one: which items are expanded, which one is selected, the keyboard and what
screen readers hear. Its rows are virtualized: only the rows in view are made, and the children of a collapsed item are
never made at all, so a tree of thousands of items opens and scrolls at once. The look is the app's: the tree draws
nothing of its own, the app styles each row (`itemClass`) and draws its content (`renderItem`: an icon, the label
indented by the item's depth, a chevron, a badge).

```rust
use nsh_base::{TreeEntry, TreeItem, theme, tree};
use nsh_core::prelude::*;

fn files() -> impl IntoElement {
    let items = vec![
        TreeItem::new("src", "src")
            .child(TreeItem::new("src/main.rs", "main.rs"))
            .child(TreeItem::new("src/ui", "ui").child(TreeItem::new("src/ui/tree.rs", "tree.rs"))),
        TreeItem::new("Cargo.toml", "Cargo.toml"),
    ];
    let selected = signal(None::<SharedString>);
    tree()
        .items(items)
        .default_expanded(vec!["src".into()])
        .selected(move || selected.get())
        .on_selected_change(move |id: &SharedString| selected.set(Some(id.clone())))
        .accessibility_label("Files")
        .h(px(320.0))
        .list_class("p-1")
        .item_class(
            "group rounded-md hover:bg-accent selected:bg-primary/10 \
             focus:outline-2 focus:-outline-offset-2 focus:outline-ring disabled:opacity-50",
        )
        .render_item(|entry: &TreeEntry| {
            view()
                .flex_row()
                .gap_2()
                .h_8()
                .items_center()
                .rounded_md()
                .pl(px(8.0 + 16.0 * entry.depth as f32))
                .child(text(if entry.folder { "▸" } else { " " }).text_color(move || theme().muted_foreground))
                .child(text(entry.label.clone()))
        })
}
```

```tsx
import { mount, signal, Text, View } from "nsh";
import { Tree, type TreeItem } from "nsh/base";

const files: TreeItem[] = [
  {
    id: "src",
    label: "src",
    children: [
      { id: "src/main.rs", label: "main.rs" },
      { id: "src/ui", label: "ui", children: [{ id: "src/ui/tree.rs", label: "tree.rs" }] },
    ],
  },
  { id: "Cargo.toml", label: "Cargo.toml" },
];

function App() {
  const expanded = signal(["src"]);
  const selected = signal<string | null>(null);
  return (
    <Tree
      items={files}
      expanded={expanded()}
      selected={selected()}
      onExpandedChange={({ expanded: next }) => expanded.set(next)}
      onSelectedChange={({ selected: next }) => selected.set(next)}
      accessibilityLabel="Files"
      class="h-80 w-64 rounded-lg border border-border"
      listClass="p-1"
      itemClass="group h-8 rounded-md hover:bg-accent selected:bg-primary/10 focus:outline-2 focus:-outline-offset-2 focus:outline-ring disabled:opacity-50"
      renderItem={(entry) => (
        <View class="h-8 flex-row items-center gap-2" style={{ paddingLeft: 8 + entry.depth * 16 }}>
          <Text class="w-3 text-muted-foreground transition-transform group-aria-expanded:rotate-90">
            {entry.folder ? "›" : ""}
          </Text>
          <Text class="text-sm text-foreground">{entry.label}</Text>
        </View>
      )}
    />
  );
}

mount(App);
```

`Tree` comes from [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md), the `nsh-base` crate in Rust. The expanded items and the
selected one are the app's when it sets `expanded` and `selected`, which it updates in `onExpandedChange` and
`onSelectedChange`; without them the tree keeps its own state, starting from `defaultExpanded` and `defaultSelected`.
Items are identified by their `id`, the app's own (a path, a record's key), never by their label. In Rust, `tree()`
makes it, with a setter per prop (`.items(..)`, `.expanded(..)`, `.render_item(..)`), a listener method per event and
the typed style methods.

## Items

`items` is the items at the top, each a `TreeItem`:

| Field | Type | Description |
|---|---|---|
| `id` | `string` | What identifies it in `expanded`, `selected` and the events: unique in the tree (an id given twice is logged, and only its first item expands or is selected). |
| `label` | `string` | What its row shows unless `renderItem` draws it, what screen readers say and what typeahead matches. |
| `children` | `TreeItem[]` | The items under it, in order. With any, it is a folder: it expands and collapses. |
| `disabled` | `boolean` | The user cannot select, expand or collapse it: presses and keys pass it by, `disabled:` styles apply. Its children stay as `expanded` says. |

`renderItem` gets a `TreeEntry` for each row in view: the item's `id`, `label` and `disabled`, its `depth` (0 at the
top, 1 under a top item, …) and whether it is a `folder`. It is what the item is, and the row's states are its
classes: the drawing is made once per item and keeps its views while the row is selected, expanded or collapsed, so a
chevron turns with a transition.

## Props

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `items` | `.items(..)` | `TreeItem[]` | `[]` | The items at the top, each with the items under it. |
| `expanded` | `.expanded(..)` | `string[]` | none | The ids of the expanded items (controlled). An item shows while every item above it is expanded. |
| `defaultExpanded` | `.default_expanded(..)` | `string[]` | `[]` | The expanded items at first, while `expanded` is not set. |
| `selected` | `.selected(..)` | `string \| null` | none | The selected item's id (controlled), `null` for none. |
| `defaultSelected` | `.default_selected(..)` | `string` | none | The selected item at first, while `selected` is not set. |
| `disabled` | `.disabled(..)` | `boolean` | `false` | A read-only tree: no presses or keys, no stop of the keyboard focus, `disabled:` on every row; it shows what `expanded` and `selected` say. |
| `reveal` | `.reveal(..)` | `boolean` | `false` | Expanding and collapsing move the rows after the item to their new places with a spring, run natively. Off with reduced motion. |
| `accessibilityLabel` | `.accessibility_label(..)` | `string` | none | What screen readers call the tree ("Files"). |
| `renderItem` | `.render_item(..)` | `(entry: TreeEntry) => JSX.Element` | none | A row's content, for the rows in view; without it a row shows the item's label. |
| `itemClass`, `itemStyle` | `.item_class(..)`, `.item_style(..)` | `string`, `StyleProp<TextStyle>` | none | Each row: its height, padding, surface and states (below); its text styles reach the label. |
| `listClass`, `listStyle` | `.list_class(..)`, `.list_style(..)` | `string`, `StyleProp<ViewStyle>` | none | The scroll view of the rows inside the tree: its padding and gaps. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | The tree itself. Give it a height (or `flex-1` in a parent that has one): the rows scroll inside it, and only those in view are made. |

## Events

| Event | Rust | Payload | When |
|---|---|---|---|
| `onExpandedChange` | `.on_expanded_change(..)` | `{ expanded: string[] }` | The user expanded or collapsed an item (a press, Return, Space, Right or Left, `revealItem`): the expanded ids as they would be. |
| `onSelectedChange` | `.on_selected_change(..)` | `{ selected: string }` | The user selected another item (a press, the arrow keys, Home, End, typeahead). |
| `onExpand` | `.on_expand(..)` | `{ id: string }` | The user expanded the item of `id`, after `onExpandedChange`. |
| `onCollapse` | `.on_collapse(..)` | `{ id: string }` | The user collapsed the item of `id`, after `onExpandedChange`. |
| `onAction` | `.on_action(..)` | `{ id: string }` | The user acted on the item of `id`: Return on the selected item when it has no children, or a double click or double tap on any item, after the press's own events. Disabled items and a disabled tree never report it. |

The selection follows the arrow keys, so a file explorer opens a file in `onAction`, not in `onSelectedChange`:
moving through the files previews them one by one, Return or a double click opens the one the user wants.

```tsx
<Tree
  items={files}
  onSelectedChange={({ selected }) => preview.set(selected)}
  onAction={({ id }) => openFile(id)}
/>
```

## Parts

| Part | Inside | Styled with | States |
|---|---|---|---|
| The tree | | `class`, `style` | |
| The list | the tree | `listClass`, `listStyle` | |
| A row | the list | `itemClass`, `itemStyle` | `selected:`, `aria-expanded:` (a folder that is open), `focus:` (while the tree has the keyboard focus, the row the keys act on: the selected row, the collapsed item a hidden selection is under, or the first row while nothing is selected), `disabled:`, `hover:`, `active:` |
| A row's content | a row | `renderItem` | `group-selected:`, `group-aria-expanded:`, `group-focus:`, `group-disabled:` under `group` in `itemClass` |

Show the selected row with `selected:` and the keyboard's place with `focus:` (see
[Design guides](https://nsh.dev/versions/main/docs/design-guides.md#interaction-states)). Draw the focus inside the row
(`focus:outline-2 focus:-outline-offset-2`): the list clips what reaches past its sides.

## Ref

| Method | Description |
|---|---|
| `focus()` | Takes the keyboard focus, as Tab reaching the tree does. |
| `revealItem(id)` | Expands the items above the item of `id` (reported with `onExpandedChange` and `onExpand`, the outermost first) and scrolls its row into view once it shows: when the app follows the change, at once; when it does not, the request ends there. |

```tsx
let files: TreeRef | undefined;

<Tree ref={(r) => (files = r)} items={items} />;
files?.revealItem("src/ui/tree.rs");
```

## Disabled

A disabled item takes no presses, the arrow keys pass it by, and screen readers announce it as dimmed. `disabled` on
the tree makes it read-only: it shows what the app's state says and takes no input.

```tsx
<Tree items={items} disabled={locked()} itemClass="h-8 px-2 disabled:opacity-50" />
```

## Accessibility

- The tree has the role `"tree"`, named by `accessibilityLabel`; each row is a `"treeitem"` named by its item's label,
  with its level (its depth + 1), whether it is expanded (folders), selected and disabled.
- As the tree takes the keyboard focus and as the keys move the selection, the row the keys act on takes the screen
  reader's focus.

See [Accessibility](https://nsh.dev/versions/main/docs/accessibility.md) for labels, roles and announcements in general.

## Keyboard

On the desktops and the web, where Tab reaches the views that take presses, a `Tree` follows the
[WAI-ARIA tree view pattern](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/):

| Key | What it does |
|---|---|
| Tab, Shift+Tab | Enters the tree in one step, and leaves it in one step; coming back, the keys go on from the selected row. With nothing selected, the focus shows on the first row, which Down selects. |
| Down, Up | Selects the next or the previous row, past disabled items, from the last to the first and back. |
| Right | Expands a collapsed folder; on an expanded one, selects its first enabled child. |
| Left | Collapses an expanded folder; on anything else, selects its parent. |
| Home, End | Selects the first or the last row. |
| Return | Expands or collapses the selected folder; on an item without children, acts on it (`onAction`). |
| Space | Expands or collapses the selected folder. |
| Letters, digits | Selects the next row whose label starts with what was typed. |

While the selection is hidden under a collapsed item (the app collapsed it), the keys act on that item's row: Right
or Return expands it, Down selects the row after it.

In a right-to-left layout the rows run from the right, so Left and Right trade places, as the pattern says: Left
expands a folder and enters it, Right collapses it and selects the parent. Up, Down, Home and End keep theirs.

## Platform notes

- iOS, Android and Mac Catalyst: a tap selects a row and expands or collapses a folder; a double tap acts on the item
  (`onAction`).
- Desktops (macOS, Windows, Linux, GPUI) and the web: a click does the same and gives the tree the keyboard focus, and
  the keys above move in it; a double click acts on the item.
- Every platform draws what the app styles: the tree, its rows and their content.

Source: https://nsh.dev/versions/main/elements/tree

---

# Modules

An NSH app imports everything it uses from a small set of modules. They are all native: the reactive graph, the renderer and every module are implemented in Rust inside the runtime, and the bundler keeps `import ... from "nsh/..."` as imports instead of copying code into your bundle. Your bundle only holds your own code.

```tsx
import { createAnimatedValue, mount, signal, windowSize } from "nsh";
import { Button } from "nsh/base";
import { TabBar } from "nsh/mobile";
```

## Three layers

NSH's UI is built in three layers, as GPUI Kit's is (`gpui`, `gpui-base`, `gpui-component`):

| Layer | Modules | What it gives an app |
|---|---|---|
| Primitives | `nsh`, `nsh/mobile`, `nsh/desktop` | Reactivity, the host elements, layout, lists, canvas, animation, gestures, device information and the platforms' own APIs |
| Base components | [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md) | Unstyled components that own behavior, state, focus and accessibility: a button, Markdown and HTML documents, navigation stacks and dialogs and the system's dialogs, on every platform |
| Component library | your app's, or one from the community | Buttons, cards, rows and screens with a look |

The look of an app is the app's own. Its component library is the third layer: components it writes from the [host elements](https://nsh.dev/versions/main/elements.md) and `nsh/base`, styled with `style`, [Tailwind](https://nsh.dev/versions/main/docs/tailwind.md) classes and its theme, Rust components it ships in [its own crate](https://nsh.dev/versions/main/docs/rust.md), or a library the community publishes on the same foundation.

There is no catch-all module: each API lives in exactly one place. The APIs of mobile platforms live in `nsh/mobile` (iOS and Android) and those of the desktops in `nsh/desktop` (macOS, Windows, Linux); both can be imported on every platform, so one bundle runs everywhere (on other platforms their calls return at once, and `platform.os` tells you which platform you are on).

Types are generated from the runtime: `nsh init`, `nsh build`, `nsh dev` and `nsh test` write `.nsh/types` next to your app, so the TypeScript declarations always match the runtime you build with (see [Project structure](https://nsh.dev/versions/main/docs/project-structure.md)).

## All modules

| Module | Exports | Page |
|---|---|---|
| `nsh` | `signal`, `computed`, `effect`, `batch`, `untracked`, `cleanup`, `context`, `split`, `mount`, `ErrorBoundary`; the primitives `View`, `Text`, `Scroll`, [`List`](https://nsh.dev/versions/main/modules/nsh-list.md), [`Image`](https://nsh.dev/versions/main/modules/nsh-image.md) (with `Image.getSize`, `Image.prefetch`), [`Canvas`](https://nsh.dev/versions/main/modules/nsh-canvas.md) (with `Path2D`, `CanvasRenderingContext2D`, `CanvasGradient`), [`WebView`](https://nsh.dev/versions/main/modules/nsh-webview.md), [`Video`](https://nsh.dev/versions/main/modules/nsh-video.md); `safeArea`, `safeAreaInsets`; `Keyboard`, `keyboardFrame`; [animation](https://nsh.dev/versions/main/modules/nsh.md#animation) (`createAnimatedValue`, `AnimatedValue`, `AnimatedNode`, `Animated`, `Easing`, `LayoutAnimation`); [the environment](https://nsh.dev/versions/main/modules/nsh.md#device) (`windowSize`, `colorScheme`, `setColorScheme`, `fontScale`, `pixelRatio`, `locale`, `platform`, `openUrl`); [`PanResponder`](https://nsh.dev/versions/main/modules/nsh.md#panresponder); [`Clipboard`](https://nsh.dev/versions/main/modules/nsh.md#clipboard); [`Picker`](https://nsh.dev/versions/main/modules/nsh.md#picker); [`Storage`](https://nsh.dev/versions/main/modules/nsh.md#storage); [`host`](https://nsh.dev/versions/main/modules/nsh.md#host) (`available`, `call`, `on`, plus native SDK `params` and `post`); [`keymap`](https://nsh.dev/versions/main/modules/nsh.md#keymap) (keyboard shortcuts: `mod+k`, `ctrl+shift+p`, ...); [`nativeComponent`, `nativeModule`](https://nsh.dev/versions/main/modules/nsh.md#nativecomponent-and-nativemodule) (components and functions the embedding app registers); [accessibility](https://nsh.dev/versions/main/modules/nsh.md#accessibility) (`announce`, `setAccessibilityFocus`, `screenReaderEnabled`, `reduceMotion`); the types of elements, styles, events and JSX (`ViewRef`, `InputRef`, ..., `ViewStyle`, ...) | [nsh](https://nsh.dev/versions/main/modules/nsh.md) |
| `nsh/base` | `Button`, `Input`; `TextView`; `createNavStack`, `NavStack`, `NavPage`, `Dialog`; `AlertDialog` | [nsh/base](https://nsh.dev/versions/main/modules/nsh-base.md) |
| `nsh/mobile` | `isAvailable`, `TabBar` (the system's tab bar, iOS and Android), `InputAccessoryView` (iOS), `BackHandler` (Android) | [nsh/mobile](https://nsh.dev/versions/main/modules/nsh-mobile.md) |
| `nsh/desktop` | `isAvailable`, `Window` (title, title bar, maximize, full screen), `titleBar`, `Menu` (application menu, context menus) | [nsh/desktop](https://nsh.dev/versions/main/modules/nsh-desktop.md) |
| Standard modules | `buffer`, `console`, `crypto`, `fs/promises`, `net`, `os`, `path`, `process`, `url`, `websocket`, `zlib` | [Standard modules](https://nsh.dev/versions/main/modules/standard-modules.md) |
| Globals | `fetch`, `URL`, `TextEncoder`, `Blob`, `FormData`, `AbortController`, `Intl`, timers, `console`, `requestAnimationFrame`, ... (no import) | [Global APIs](https://nsh.dev/versions/main/modules/globals.md) |

Reference pages that are not modules:

| Page | Covers |
|---|---|
| [Style reference](https://nsh.dev/versions/main/modules/style-reference.md) | Every style key, its type and meaning |
| [Tailwind reference](https://nsh.dev/versions/main/modules/tailwind-reference.md) | The Tailwind utilities and variants `class` accepts |

## Host elements

The host elements are components imported like everything else: `View`, `Text`, `Scroll`, `Image`, `List`, `Canvas`, `WebView`, `Video` and `Overlay` from `nsh`, the base components (`Button`, `Input`, `Dialog`, `NavStack`, `NavPage`) from `nsh/base`, `InputAccessoryView` from `nsh/mobile`. Only `If` and `Each` are globals. The compiler makes the elements in place, so the imports cost nothing at run time. Their props are documented under [Elements](https://nsh.dev/versions/main/elements.md).

Source: https://nsh.dev/versions/main/modules

---

# nsh

`nsh` is the core module: the reactive API (signals, computed values, effects, context), `mount`, `token`, the host elements `View`, `Text`, `Scroll` and `Overlay`, [selectable views](#selectable-views), [the safe area and the keyboard](#safe-area-and-keyboard), [animation](#animation), [the device and its environment](#device), [`PanResponder`](#panresponder), the [clipboard](#clipboard), the [photo picker](#picker), [speech recognition](#speech), [storage](#storage), the [host channel](#host), [keyboard shortcuts](#keymap), [native components and modules](#nativecomponent-and-nativemodule), [accessibility](#accessibility), and the TypeScript types of elements, styles and events. The reactive graph itself runs natively in Rust; reading a signal is a call into the runtime that costs a few nanoseconds, and only your own closures run in the JavaScript interpreter.

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

NSH's reactivity follows the same model as SolidJS: a component function runs **once**, and the parts of the UI that read signals are updated in place when those signals change. There is no re-render of the component and no virtual DOM. See [Reactivity](https://nsh.dev/versions/main/docs/reactivity.md) for the guide.

## signal

```ts
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);
}
```

A signal holds a value. Calling it reads the value and, inside a tracking scope (JSX expressions, `computed`, `effect`), subscribes that scope to it. `set` and `update` write it; everything that read it updates.

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

By default a write that is `===` to the current value does nothing. Pass `equals: false` to notify on every write (useful when you mutate an object in place and set the same object again), or your own comparison:

```ts
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

```ts
function computed<T>(fn: (previous: T | undefined) => T, options?: SignalOptions<T>): Accessor<T>;

interface Accessor<T> {
  (): T;
}
```

A value derived from signals. `fn` runs again when a signal it read changes; readers of the computed value only update when its result changes (by `equals`, `===` by default). `fn` receives the previous result.

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

Use `computed` when a derivation is expensive or read in several places. For a cheap expression, a plain function (`const full = () => first() + " " + last()`) is just as reactive.

## effect

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

Runs `fn` after rendering, and again whenever a signal it read changes. Use effects for side effects: logging, timers, talking to native modules. An effect belongs to the component (or effect) it was created in and is disposed with it.

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

To undo something before the effect runs again (or when its component goes away), call [`cleanup`](#cleanup) inside it.

## batch

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

Runs `fn` and applies all its writes together at the end, so readers update once instead of once per write. Returns what `fn` returns.

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

## untracked

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

Runs `fn` without subscribing the current scope to what it reads. Use it to read a signal inside an effect or JSX expression without depending on it.

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

## cleanup

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

Registers `fn` to run before the current effect runs again, or when the current component or effect goes away.

```tsx
function Clock() {
  const now = signal(new Date());
  const timer = setInterval(() => now.set(new Date()), 1000);
  cleanup(() => clearInterval(timer));
  return <Text>{now().toLocaleTimeString()}</Text>;
}
```

## context

```ts
function context<T>(defaultValue: T): Context<T>;

interface Context<T> extends Accessor<T> {
  Provider: (props: { value: T; children?: JSX.Element }) => JSX.Element;
}
```

A value a component provides to everything it renders, however deep. Calling the context (`Theme()`) reads the nearest provider's value, or `defaultValue` without one.

```tsx
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

```ts
function mount<P extends object>(app: Component<P>, props?: P): () => void;
```

Renders `app` into the surface (the window, or the `NshAppView` / `NshView` the app is embedded in) and returns a function that removes it. Every app's entry file ends with `mount(App)`.

```tsx
mount(App);
```

## split

```ts
function split<T extends object, K extends readonly (keyof T)[]>(
  props: T,
  keys: K,
): [Pick<T, K[number]>, Omit<T, K[number]>];
```

Splits a props object into the props named in `keys` and the rest. Both halves stay reactive: props whose values change are getters, and `split` keeps them as getters. Use it in a component that handles some props itself and passes the others on. Destructuring props (`const { label } = props`) would read them once and lose updates.

```tsx
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

```ts
function ErrorBoundary(props: {
  fallback: JSX.Element | ((error: unknown, reset: () => void) => JSX.Element);
  children?: JSX.Element;
}): JSX.Element;
```

Renders its children, or `fallback` once something under them throws: a component's body, a binding, an effect or an event handler. The part that failed is removed and the fallback shows in its place. A function `fallback` is called as `fallback(error, reset)` with the thrown value and `reset`, which renders the children again, whatever parameters it declares; a `fallback` element is shown as it is. A failure goes to the nearest boundary above it, and one in a fallback to the boundary above that. Rust components use `catch_error` ([Error boundaries](https://nsh.dev/versions/main/docs/reactivity.md#error-boundaries)).

```tsx
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

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

The design token `name` of the app's theme (`"theme"` in `nsh.json`, over shadcn/ui's tokens) in the appearance shown:
a color as `#rrggbbaa`, a length as a number of points, a font as its family name. Names are the theme's CSS variables
without `--` (`primary`, `muted-foreground`, `radius`, `font-mono`, and the app's own, such as `up`). Reading it is
reactive: a component, memo or effect that reads a token runs again when the theme or the appearance changes.
`Tokens` lists the app's tokens with their types; NSH writes it into `.nsh/types/nsh/tokens.d.ts` from the theme. For
classes, name the tokens directly (`bg-primary`, `rounded-(--radius)`): [Theme tokens](https://nsh.dev/versions/main/docs/tailwind.md#theme-tokens).

```tsx
import { effect, token } from "nsh";

effect(() => console.log("primary is", token("primary"), "radius", token("radius")));
```

## View, Text, Scroll, Overlay

```ts
function View(props: ViewProps): JSX.Element;
function Text(props: TextProps): JSX.Element;
function Scroll(props: ScrollProps): JSX.Element;
function Overlay(props: OverlayProps): JSX.Element;
```

The host elements `nsh` exports, written as tags: `<View>`, `<Text>`, `<Scroll>`, `<Overlay>` (its
children on top of the window, placed against an anchor: [Overlay](https://nsh.dev/versions/main/elements/overlay.md)). The compiler makes the
native view in place for a tag that names one of them through its import (an alias too), so importing them costs
nothing at run time. They are components like any other, so they can also be passed around (`const Tag = inline ? Text : View`).
`nsh` exports the other primitives the same way: [`List`](https://nsh.dev/versions/main/modules/nsh-list.md), [`Image`](https://nsh.dev/versions/main/modules/nsh-image.md),
[`Canvas`](https://nsh.dev/versions/main/modules/nsh-canvas.md), [`WebView`](https://nsh.dev/versions/main/modules/nsh-webview.md) and [`Video`](https://nsh.dev/versions/main/modules/nsh-video.md), each with its own reference
page. Their props are documented under [Elements](https://nsh.dev/versions/main/elements.md). The text input, `Input`, comes from
[`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md#input).

## Safe area and keyboard

CSS's environment variables keep content clear of system UI, in any view's padding and margin
(`padding`, `paddingTop`, ..., the same `margin` keys; Tailwind's `p*` / `m*` arbitrary values; the `Styled` methods
`.p_safe_area()`, `.pt_safe_area_plus(..)`, `.pb_keyboard()`, ... in Rust). Their values are `EnvValue`s:
`env(name)`, `env(name, <length>)`, `calc(env(name) + <length>)` and `calc(<length> + env(name))`.

| Variable | Value |
|---|---|
| `safe-area-inset-top`, `-right`, `-bottom`, `-left` | The insets of the root view the node renders in: the nearest page's (below its header), the nearest dialog's, or else the surface's safe area. See [Safe area](https://nsh.dev/versions/main/elements/safe-area.md). |
| `keyboard-inset-height` | The software keyboard's height over the surface, 0 while it is hidden; changes animate natively with the keyboard. See [Keyboard](https://nsh.dev/versions/main/elements/keyboard.md). |

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

### safeArea and safeAreaInsets

`safeArea()` is the surface's safe area (`safe_area()` in Rust); `safeAreaInsets()` the insets where a component
renders (`cx.insets()` in Rust), the values of the `safe-area-inset-*` variables. Both are reactive `Edges`
(`{ top, right, bottom, left }` in points). See
[safeArea and safeAreaInsets](https://nsh.dev/versions/main/elements/safe-area.md#safearea-and-safeareainsets).

### Keyboard and keyboardFrame

`Keyboard.dismiss()` hides the software keyboard (`dismiss_keyboard()` in Rust) and `keyboardFrame()` tells you how
much of the screen it covers (`keyboard_height()` and `keyboard_duration()` in Rust). See
[Hiding the keyboard](https://nsh.dev/versions/main/elements/keyboard.md#hiding-the-keyboard) and
[The keyboard's height](https://nsh.dev/versions/main/elements/keyboard.md#the-keyboards-height).

## Selectable views

`<View selectable>` (`view().selectable(true)` in Rust) makes the texts inside it select together, as a web page's
do: one selection runs across views, `Text` elements and `TextView`s, in reading order. See
[Text selection](https://nsh.dev/versions/main/elements/text-selection.md).

## Animation

The animation API animates on the UI thread. You create an **animated value**, bind it (or values derived from it) to a style property, and start an animation; from then on every frame is computed natively, without running the app's code. A busy engine or JS thread cannot make the animation stutter, and an animation costs the app no work per frame. Rust code uses `animated_value()`, `motion()`, `Animation`, `Spring`, `Timing`, `KeyframeTiming`, `MotionPreset` and `Easing` from `nsh_core::prelude` and binds values with the `.bind_*` methods of elements; TSX imports them from `nsh`.

```rust
use nsh_core::{element::LayoutAnimation, prelude::*}; // animated_value, motion, Animation, Spring, Timing, Keyframe, KeyframeTiming, MotionPreset, MotionSpec, Easing, animate_layout
```

```tsx
import { Animated, createAnimatedValue, createMotion, motions, Easing, LayoutAnimation, AnimatedNode, AnimatedValue } from "nsh";
```

See [Animation](https://nsh.dev/versions/main/docs/animation.md) for the guide.

### What an animated value can drive

| Where | Rust | TSX |
|---|---|---|
| `opacity` | `.bind_opacity(&value)` | `style={{ opacity: value }}` |
| `backgroundColor` | `.bind_background(&value.interpolate_colors(&[0.0, 1.0], &[white(), black()]))` | `style={{ backgroundColor: value.interpolate({ inputRange: [0, 1], outputRange: ["#fff", "#000"] }) }}` |
| `borderColor`, `color` | `.bind_border_color(&node)`, `.bind_color(&node)` | The same: a node of colors. `borderColor` colors every side; a `Text`'s `color` colors the whole text |
| `transform` | `.bind_translate_x(&value)`, `.bind_translate_y`, `.bind_scale`, `.bind_rotate` (degrees) | `translateX`, `translateY`, `scale`, `scaleX`, `scaleY`, `rotate`, `rotateX`, `rotateY`, `rotateZ` steps: `transform: [{ translateX: value }]` |
| Scroll position | `.scroll_value(&value)` on a scroll view or a list | `<Scroll scrollValue={value}>` and `<List scrollValue={value}>` write the scroll offset into it each frame |
| Gestures | `.pan_values(Some(&x), Some(&y))`, `.pinch_value(&scale)`, `.rotation_value(&angle)` | `pan={{ x, y }}`, `pinch={{ scale }}`, `rotation={{ angle }}` on any element: the gesture writes the values directly (see [Touch and gestures](https://nsh.dev/versions/main/docs/touch-and-gestures.md)) |
| Where views stick | `.sticky().bind_sticky_top(&value)` (`.bind_sticky_left` in a horizontal scroll view), `.bind_sticky_header_offset(&value)` on a list | `style={{ position: "sticky", top: value }}`, `<List stickyHeaderOffset={value}>`: sticky views and headers stick that far from the start of the viewport, following the value every frame |
| Canvas | an animated argument of a painter's call | Any number or color argument of a [canvas](https://nsh.dev/versions/main/modules/nsh-canvas.md) drawing call |
| Shader | `.uniform(name, &value)` | A member of a [shader](https://nsh.dev/versions/main/elements/shader.md)'s `struct Uniforms`: `uniforms={{ name: value }}` (numbers, or a node of colors for a `vec3f` / `vec4f`) |

Other style properties take plain values; to animate the layout itself (sizes, positions in the flow), use [`LayoutAnimation`](#layoutanimation).

### createAnimatedValue

```ts
function createAnimatedValue(value?: number): AnimatedValue;
```

Creates an animated value starting at `value` (default `0`). Rust: `animated_value(value)`, a `Copy` handle kept by the component that made it.

```rust
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))
}
```

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

> [!NOTE]
> An animated value lives on the UI thread and changes there every frame, so the app reads it asynchronously: `await value.getValue()` (or the `{ value }` that `stop()` resolves with) gives the value at that moment, and in Rust `value.value().await` in a task. Keep the target in a variable or a signal when your code needs it right away, as above. Gesture events report the values at their end (`PanEvent.value`).

### AnimatedValue

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

| Method | Rust | Description |
|---|---|---|
| `set(value)` | `set(value)` | Jumps to `value`, stopping any running animation. |
| `stop()` | `stop()`, then `value().await` | Stops the running animation where it is; resolves with `{ value }`, the value there. |
| `getValue()` | `value().await` | Resolves with the current value (with its offset), read on the UI thread. |
| `setOffset(offset)` | `set_offset(offset)` | An offset added to the value: bindings see value + offset; `set`, animations and drags move the value. |
| `flattenOffset()` | `flatten_offset()` | Adds the offset to the value and makes it 0. |
| `extractOffset()` | `extract_offset()` | Moves the value into the offset and makes the value 0 (a drag then starts from where the last one ended). |
| `timing(to, options)` | `timing(to, ms, easing)`, `timing_with(to, Timing { … })` | Animates to `to` along an easing curve. `duration` in ms (default 300), `easing` (default `"easeInOut"`), `delay` in ms (default 0). |
| `spring(to, options)` | `spring(to, Spring { … })` | Springs to `to`. `stiffness` (default 170), `damping` (default 26), `mass` (default 1), `velocity` (initial velocity, units per second). |
| `decay(options)` | `decay(velocity, deceleration)`, `decay_within(velocity, deceleration, (min, max), bounce)` | Coasts from `velocity` (units per second) and slows down by `deceleration` per millisecond (default 0.998). Use it after a fling, with the velocity from `onPanEnd`. With `clamp: [min, max]` it stops at a bound, or bounces back from it keeping `bounce` (0..1, default 0) of its speed. |
| `keyframes(frames, options)` | `keyframes(frames, KeyframeTiming)` | Plays [keyframes](#keyframes) as CSS keyframes play: an easing per segment, `iterations` times in `direction`. |

Each animation method returns a promise that resolves with `{ finished }`: `true` when the animation finished, `false` when it was stopped (by `stop`, `set` or another animation of the same value). In Rust it returns an `AnimationEnd`, which a task awaits for the same `bool`.

```rust
let opacity = animated_value(1.0);
spawn(async move {
    if opacity.timing(0.0, 200.0, Easing::EaseInOut).await {
        visible.set(false);
    }
});
```

```tsx
const opacity = createAnimatedValue(1);
const { finished } = await opacity.timing(0, { duration: 200 });
if (finished) visible.set(false);
```

### AnimatedNode

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

A node of the native animation graph: a `AnimatedValue`, or a value derived from others. Derived nodes are evaluated on the UI thread whenever their inputs change.

| Method | Rust | Description |
|---|---|---|
| `interpolate(config)` | `interpolate(&input, &output)`, `interpolate_colors(&input, &colors)`, `interpolate_with(&input, output, Interpolation { … })` | Maps the input through piecewise ranges. `outputRange` holds numbers, colors (`"#ff0000"`, `"rgba(…)"`) or angles (`"45deg"`, `"1rad"`). Outside `inputRange` it clamps by default; `extrapolate` (or `extrapolateLeft` / `extrapolateRight`) can be `"extend"` (continue the line), `"clamp"` or `"identity"` (pass the input through). `easing` shapes each segment. Rust takes numbers, theme colors (which follow the appearance) and angles as degrees for `bind_rotate`. |
| `diffClamp(min, max, options?)` | `diff_clamp(min, max)`, `diff_clamp_with(min, max, DiffClamp::snapping())` | Follows the input's changes but keeps the result within `min..max`: a header that hides while content scrolls up and comes back as soon as it scrolls down. `snap: true` settles it at the nearer bound in 200 ms when its scroll view comes to rest, at `max` only once the input reached `max`. |
| `add`, `sub`, `mul`, `div` | `add`, `sub`, `mul`, `div` | Arithmetic with another node or a constant. |
| `mod(b)` | `modulo(b)` | Modulo, never negative for a positive `b` (keeping angles in 0..360). |

```rust
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)))
```

```tsx
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) }] }} />
```

```rust
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)]);
```

```tsx
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

```ts
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)` plays a value through keyframes and resolves with `{ finished }`, whether they finished; `Animated.keyframes(value, { keyframes, ...options })` is the same as a step of a composite. Rust: `value.keyframes(frames, KeyframeTiming)` and `Animation::keyframes(&value, frames, KeyframeTiming)`, with `Keyframe::new(value)` (spread evenly), `Keyframe::at(offset, value)` and `.ease(easing)`, and `KeyframeTiming::new(ms)` with `.delay(ms)`, `.easing(e)`, `.iterations(Some(n))`, `.infinite()` and `.direction(PlaybackDirection::…)`.

They play as CSS keyframes play: an easing shapes one segment (a keyframe's the segment that starts at it, the timing's every other one); offsets missing from keyframes spread evenly, the first at 0 and the last at 1; each iteration starts with a jump to its first keyframe, and without a keyframe at 0 the value goes from where it is; during a `delay` the value holds the first keyframe (CSS `animation-fill-mode: backwards`); backward iterations run the segments backwards with their curves reversed; the value stays where the last iteration leaves it.

```rust
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)),
);
```

```tsx
const y = createAnimatedValue(0);
y.keyframes([0, { offset: 0.3, value: -20, easing: "easeIn" }, 0], { duration: 600, iterations: 3 });
```

### createMotion

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

Creates a motion: an animated value for each channel of a view's opacity and transform, at rest (opacity and scales 1, the others 0), and motions to play on them natively. Bind it with `style={motion.style}`, or spread `motion.style` or `motion.transform` into a style; the transform applies its translations, then its rotations, then its scales, with `scale` folded into `scaleX` and `scaleY`: 7 of a view's 8 transform steps, which leaves one for yours (`[{ perspective: 600 }, ...motion.transform]` for 3D flips). `initial` sets where channels start (`{ opacity: 0 }`; the others start at rest). With `enter`, the channels it moves start where that motion starts (over `initial`) and it plays at once, with the other options as its timing (`delay`, `duration`, ...). A motion moves opacity and transform only: spreading `motion.style` sets the view's `opacity`, so bind only `motion.transform` to keep an opacity of your own, and move colors with an animated value and `interpolate`. Rust: `motion()`, a `Copy` handle kept by the component that made it, bound with `.bind_motion(&m)`; `motion().entering(spec)` enters.

| Member | Rust (`Motion`) | Description |
|---|---|---|
| `opacity`, `translateX`, ... `scaleY` | `value(MotionChannel::Opacity)`, ... | The channels' animated values. |
| `style`, `transform` | `.bind_motion(&m)` on the element | The bindings. |
| `play(motion, options?)` | `play(spec)`, `play_ignoring_reduce_motion(spec)` | Plays a preset by name or a [`MotionSpec`](#motions) on the channels; a new one interrupts the one playing. `options` change its timing. Resolves with `{ finished }`: `true` when it finished, `false` when something stopped it (`AnimationEnd` in Rust). |
| `animation(motion, options?)` | `animation(spec)` | The same motion as a [`CompositeAnimation`](#animated), not started, to compose: `Animated.stagger(60, cards.map((m) => m.animation("fadeInUp")), { from: "center" })` (Rust: `Animation::stagger_from(60.0, StaggerFrom::Center, cards.iter().map(\|m\| m.animation(MotionPreset::FadeInUp)))`). Reduced motion is decided when it is made. |
| `stop()` | `stop()` | Stops it where it is. |
| `reset()` | `reset()` | Stops it and puts every channel back at rest. |

When the user asks for less motion (`reduceMotion()`), `play`, `animation` and `enter` land where the motion ends at once, without moving, unless `ignoreReduceMotion` is set (on the options or the motion).

```rust
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);
})
```

```tsx
const card = createMotion({ enter: "fadeInUp", delay: 80 });
<View onPress={() => card.play("pulse")} style={{ width: 120, height: 120, borderRadius: 16, backgroundColor: "#0969da", ...card.style }} />
```

### motions

```ts
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";
}
```

The ready-made motions as data: `motion.play("shake")` plays `motions.shake`. `MotionName` is one of `fadeIn`, `fadeInUp`, `fadeInDown`, `fadeInLeft`, `fadeInRight`, `zoomIn`, `popIn`, `bounceIn`, `slideInUp`, `slideInDown`, `flipInX`, `flipInY` (enter); `fadeOut`, `fadeOutUp`, `fadeOutDown`, `fadeOutLeft`, `fadeOutRight`, `zoomOut`, `popOut`, `slideOutDown`, `slideOutUp` (exit); `shake`, `headShake`, `wiggle`, `swing`, `pulse`, `heartbeat`, `rubberBand`, `jello`, `tada`, `jump`, `flash` (attention); `spin`, `float`, `breathe`, `sway`, `bob`, `glow` (loop). [Animation](https://nsh.dev/versions/main/docs/animation.md#presets) describes each one. Spread a preset to change it: `motion.play({ ...motions.fadeInUp, duration: 600 })`.

A `MotionSpec` is a motion of your own: each channel's keyframes (`{ opacity: [0, 1], translateY: [24, 0] }`), or a list of frames as the Web Animations API writes them (`[{ opacity: 0, translateY: 24 }, { opacity: 1, translateY: 0 }]`, a frame without an offset placed by its position in the list), with the [keyframe timing](#keyframes). Rust: `MotionSpec::new(KeyframeTiming)` with `.values(channel, values)` (spread evenly), `.track(channel, keyframes)` and `.timing(|t| …)`; `MotionPreset::FadeInUp` (or `.spec()`) is a preset, and `MotionChannel` names the channels.

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

```tsx
card.play({ duration: 400, keyframes: [{ opacity: 0, translateY: 24, easing: "easeOut" }, { opacity: 1, translateY: 0 }] });
```

### Animated

```ts
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` builds animations out of steps (`timing`, `spring`, `decay`, `sequence`, `parallel`, ...). Nothing runs until `start()`; then the whole tree runs natively, and each step starts on the UI thread at the exact moment the previous one ends (no frame gap, no round trip to the app's code between steps). Rust builds the same tree with `Animation`.

| Function | Rust | Description |
|---|---|---|
| `timing`, `spring`, `decay` | `Animation::timing(&value, to, Timing)`, `Animation::spring(&value, to, Spring)`, `Animation::decay(&value, velocity, deceleration)` | One animation of one value; same options and defaults as the [`AnimatedValue`](#animatedvalue) methods, with the target as `toValue`. |
| `sequence(list)` | `Animation::sequence(list)` | Runs the animations one after another. |
| `parallel(list, { stopTogether })` | `Animation::parallel(list).stop_together(…)` | Runs them at the same time. With `stopTogether` (default `true`), stopping one stops all. |
| `stagger(ms, list, { from })` | `Animation::stagger(ms, list)`, `Animation::stagger_from(ms, StaggerFrom::Center, list)` | Runs them in parallel, each starting `ms` after the previous one, counted from `from`: `"first"` (default), `"last"`, `"center"` (the middle starts at once, the others spread out from it; with an even count both middle items start at once) or an index (`StaggerFrom::First`, `Last`, `Center`, `Index(i)`). |
| `keyframes(value, { keyframes, ...timing })` | `Animation::keyframes(&value, frames, KeyframeTiming)` | A value through [keyframes](#keyframes). |
| `delay(ms)` | `Animation::delay(ms)` | Waits; useful inside `sequence`. |
| `loop(animation, { iterations, resetBeforeIteration })` | `animation.looped(iterations).reset_before_iteration(…)` | Repeats `animation` `iterations` times (forever by default), putting its values back before each run unless `resetBeforeIteration` is `false`. |
| `add`, `subtract`, `multiply`, `divide`, `modulo`, `diffClamp` | the node methods | The same as the [`AnimatedNode`](#animatednode) methods, as functions. |
| `sampleSpring`, `sampleDecay` | `nsh_core::element::sample_spring`, `sample_decay` | A spring's or decay's values one per frame (see [Easing](#easing)). |

`CompositeAnimation`:

| Method | Rust (`Animation`) | Description |
|---|---|---|
| `start(callback?)` | `start()`, an `AnimationEnd` to await | Runs it (again). Resolves, and calls `callback`, once for the whole tree with `{ finished }`: whether it finished rather than being stopped. |
| `stop()` | `stop()` | Stops it where it is. |
| `reset()` | `reset()` | Stops it and puts its values back where they were when it started. |

```rust
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" }) });
```

```tsx
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

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

An easing is data, not a function of the app's: the runtime evaluates it natively. In Rust it is the enum `Easing`: `Linear`, `EaseIn`, `EaseOut`, `EaseInOut`, `Bezier(x1, y1, x2, y2)`, `Steps(count, StepPosition)` and `Curve(curve, mode)`, with a `Curve` (`Quad`, `Cubic`, `Poly(n)`, `Sin`, `Circle`, `Exp`, `Elastic(bounciness)`, `Back(s)`, `Bounce`) and an `EaseMode` (`In`, `Out`, `InOut`). To draw one, `Easing.sample(easing, count)` (Rust: `nsh_core::element::sample_easing`) gives its values at `count` evenly spaced points from 0 to 1; `Animated.sampleSpring` and `Animated.sampleDecay` (`sample_spring`, `sample_decay`) give a spring's or decay's values one per frame (at `fps`, 60 by default) from `from` (0) until it ends. All three come from the native code the animations run. Wherever an `Easing` is accepted in TSX you can pass a name (`"easeOut"`), a cubic Bézier as four numbers, or a curve from the `Easing` object.

| Curve | Rust | Shape |
|---|---|---|
| `quad` | `Curve::Quad` | `t²` |
| `cubic` | `Curve::Cubic` | `t³` |
| `poly(n)` | `Curve::Poly(n)` | `tⁿ` (`n` defaults to 2) |
| `sin` | `Curve::Sin` | Sinusoidal |
| `circle` | `Curve::Circle` | Circular |
| `exp` | `Curve::Exp` | Exponential |
| `elastic(bounciness)` | `Curve::Elastic(bounciness)` | Springy overshoot (`bounciness` defaults to 1) |
| `back(s)` | `Curve::Back(s)` | Pulls back before going; `s` is the overshoot (default 1.70158) |
| `bounce` | `Curve::Bounce` | Bounces at the end |

`Easing.steps(count, position)` is CSS `steps()`: the value jumps between `count` levels instead of moving (a frame-by-frame sprite, a ticking hand). `position` says where the jumps fall: `"jump-end"` (the default, also `"end"`), `"jump-start"` (`"start"`), `"jump-none"` or `"jump-both"`; Rust: `Easing::Steps(count, StepPosition::JumpEnd)`, `JumpStart`, `JumpNone`, `JumpBoth`.

The curves are in their "in" form (slow at the start). `Easing.out(curve)` reverses one, `Easing.inOut(curve)` makes it symmetric, `Easing.in(curve)` keeps it as is; in Rust that is the `EaseMode` of `Easing::Curve`.

```rust
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() });
```

```tsx
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

```ts
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)` animates the layout changes of the next commit natively: views that move or resize glide to their new frames, new views appear (fading or scaling in, by `property`) and removed views disappear. Call it right before the state change that changes the layout. Rust: `animate_layout(LayoutAnimation)`, with `nsh_core::element::LayoutAnimation`'s presets or its `create`, `update` and `delete` transitions.

| Member | Rust | Description |
|---|---|---|
| `configureNext(config, onEnd?)` | `animate_layout(config)` | Animates the next commit's changes; `onEnd` runs when done. |
| `create(duration, type?, property?)` | `LayoutAnimation::all(LayoutTransition::new(curve, duration))` | A config using the same curve for all three phases. |
| `Presets.easeInEaseOut` | `LayoutAnimation::EASE_IN_EASE_OUT` | 300 ms, views fading in and out. |
| `Presets.linear` | `LayoutAnimation::LINEAR` | 500 ms at constant speed. |
| `Presets.spring` | `LayoutAnimation::SPRING` | 700 ms; frames spring (damping 0.4), views fade linearly. |
| `easeInEaseOut(onEnd?)`, `linear(onEnd?)`, `spring(onEnd?)` | `animate_layout(LayoutAnimation::…)` | Shorthands for `configureNext(Presets.…)`. |
| `Types`, `Properties` | `LayoutCurve`, `LayoutProperty` | The names, as constants. |

```rust
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.")))
```

```tsx
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

The device API tells the app about the device and its environment. Rust code calls the functions of `nsh_core::prelude` (`window()`, `dark()`, `font_scale()`, `locale()`, `lifecycle()`, `os()`, `idiom()`, `pixel_ratio()`, `set_color_scheme()`, ...); TSX imports them from `nsh`. The window size, the color scheme, the font scale, the pixel ratio, the locale and the app state are reactive: read them in a binding (a closure passed to an element in Rust, JSX in TSX), `computed` or `effect`, and what reads them updates when the platform reports a change (rotation, a window resize, switching to dark mode, changing the text size or the language, moving to a screen of another density, leaving the app and coming back).

```rust
use nsh_core::{
    platform::{Appearance, Idiom, Lifecycle, Os},
    prelude::*, // window, dark, font_scale, locale, lifecycle, os, idiom, pixel_ratio, set_color_scheme, ...
};
```

```tsx
import { colorScheme, fontScale, lifecycle, locale, openUrl, pixelRatio, platform, setColorScheme, windowSize } from "nsh";
```

See [Device and environment](https://nsh.dev/versions/main/docs/device-and-environment.md) for the guide.

### windowSize

```ts
const windowSize: Accessor<Size>;
```

The size of the surface in points: the window, or the embedded `NshAppView` / `NshView`. Reactive. Rust: `window() -> Size<Points>`.

```rust
let wide = move || window().width >= px(600.0);

view().style_when(wide, |s| s.flex_row())
```

```tsx
const wide = () => windowSize().width >= 600;

<View style={{ flexDirection: wide() ? "row" : "column" }}>{/* ... */}</View>
```

### colorScheme

```ts
const colorScheme: Accessor<"light" | "dark">;
```

The appearance shown: the system's, unless the app set its own (`nsh.json` `"appearance"`, [`setColorScheme`](#setcolorscheme)). Reactive. Rust: `dark() -> bool`; theme colors (`AdaptiveColor`) and the `.dark(…)` style variant follow it without reading it. Tailwind's `dark:` variant follows it too (see [Tailwind](https://nsh.dev/versions/main/docs/tailwind.md)).

```rust
view().flex_1().bg(move || if dark() { black() } else { white() })
```

```tsx
const dark = () => colorScheme() === "dark";

<View style={{ flex: 1, backgroundColor: dark() ? "#000" : "#fff" }} />
```

### fontScale

```ts
const fontScale: Accessor<number>;
```

The user's preferred text size relative to the default (`1` is the default size; Dynamic Type on iOS, font size on Android), or the text size the embedding app sets in its place. Reactive. Rust: `font_scale() -> f32`. Text already scales with it unless `allowFontScaling={false}`; read it when other sizes should follow, such as icons next to text.

### locale

```ts
const locale: Accessor<string>;
```

The user's locale as a BCP 47 tag (`"en-US"`, `"zh-Hans-CN"`), or the locale the embedding app sets in its place. Reactive. Rust: `locale() -> Locale` (`locale().as_str()` is the tag). `Intl` formats for it by default; read it to choose the strings of your own translations ([Device and environment](https://nsh.dev/versions/main/docs/device-and-environment.md#language-and-region)).

### lifecycle

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

Whether the app is in use, in React Native's `AppState` terms: `"active"` in the foreground and taking input, `"inactive"` while visible without the focus (another app or window has it, or the system shows something over it, such as the app switcher or an incoming call), `"background"` while not visible (in the background, minimized, a hidden browser tab). An app shown inside a native app follows that app's. Reactive. Rust: `lifecycle() -> Lifecycle` (`Lifecycle::Active`, `Inactive`, `Background`).

Read it in an effect to pause work nobody sees and resume it when the app comes back:

```rust
effect(move || {
    if lifecycle() == Lifecycle::Background {
        feed.pause();
    } else {
        feed.resume();
    }
});
```

```tsx
effect(() => {
  if (lifecycle() === "background") feed.pause();
  else feed.resume();
});
```

### setColorScheme

```ts
function setColorScheme(scheme: "light" | "dark" | "system"): void;
```

Shows the app in `scheme` whatever the system's appearance, at once: `colorScheme()`, `dark:` classes, the components' theme and the platform's controls (alerts, the status bar's default style) follow it; `"system"` follows the system again. `nsh.json` `"appearance"` sets it from the start. Rust: `set_color_scheme(Appearance::Dark)` (`Appearance::Light`, `Appearance::System`).

### platform

```ts
const platform: Platform;

interface Platform {
  readonly os: "ios" | "android" | "macos" | "windows" | "linux" | "web";
  readonly version: string;
  readonly idiom: "phone" | "pad" | "mac" | "tv" | "desktop" | "terminal";
  readonly desktop: boolean;
  readonly catalyst: boolean;
  select<T>(spec: PlatformSelectSpec<T>): T | undefined;
}
```

The platform the app runs on, constant while it runs.

| Member | Rust | Description |
|---|---|---|
| `os` | `os() -> Os` (`os().name()` is the TS string) | The operating system. iOS, the iOS simulator and Mac Catalyst report `"ios"`, browsers `"web"`. |
| `version` | `os_version() -> (u16, u16)` | iOS and desktops: the OS version (`"17.5"`); Android: the API level (`"35"`); the web: `"0.0"`. Rust gives the major and minor version, or the API level and 0 on Android. |
| `idiom` | `idiom() -> Idiom` | The kind of device: `"terminal"` in a terminal (`--target tui`): drawn on a grid of character cells, with desktop behavior (`desktop` is `true`; `os` is still the machine's); elsewhere `"desktop"` exactly where `desktop` is `true`, else `"phone"`, `"pad"` (an iPad, an Android tablet, Mac Catalyst in the iPad idiom), `"mac"` (Mac Catalyst in UIKit's Mac idiom, a mobile idiom) or `"tv"` (Apple TV, Android TV). |
| `desktop` | `is_desktop() -> bool` | Desktop behavior applies: macOS, Windows, Linux, browsers with a mouse and a wide window, and terminals. `desktop={{…}}` props, `select({ desktop })` and `idiom` `"desktop"` (outside a terminal) all follow it. Mac Catalyst runs the iOS backend, so it is mobile: `ios={{…}}` props apply there. [`nsh/desktop`](https://nsh.dev/versions/main/modules/nsh-desktop.md#isavailable)'s `isAvailable` is the narrower check for its window and menu APIs, which macOS, Windows and Linux have. |
| `catalyst` | `is_catalyst() -> bool` | The app runs under Mac Catalyst, in the Mac or the iPad idiom (`os` is `"ios"`). |
| `select(spec)` | `match os() { … }` | The value for this platform (see below). |

```rust
let columns = if is_desktop() { 3 } else { 1 };
```

```tsx
const columns = platform.desktop ? 3 : 1;
```

#### platform.select

```ts
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, terminals
  native?: T;   // every platform but the web
  default?: T;
}
```

Returns the value for the current OS (`ios`, `android`, `web`, ...), else `desktop` or `mobile` (by `platform.desktop`), else `native` (every platform but the web), else `default`, else `undefined`. Rust code matches on `os()` (and `is_desktop()` for `mobile` / `desktop`).

```rust
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,
};
```

```tsx
const shadow = platform.select({
  ios: { boxShadow: "0px 2px 8px rgb(0 0 0 / 0.15)" },
  android: { elevation: 4 },
});
```

> [!TIP]
> For props that only one platform has, prefer the `ios={{…}}` / `android={{…}}` props of TSX elements and components to branching on `platform` (see [Platform-specific code](https://nsh.dev/versions/main/docs/platform-specific.md)).

### pixelRatio

```ts
const pixelRatio: Accessor<number>;
```

Device pixels per point (e.g. `3` on most iPhones). Reactive: it changes when the window moves to a screen of another density (on Mac Catalyst, the desktops, or an external display) and when Android's display size setting changes the density. Rust: `pixel_ratio() -> f32`, and `round_to_nearest_pixel(points)` for a length on whole device pixels; in TSX that length is `Math.round(x * pixelRatio()) / pixelRatio()`.

```rust
let hairline = move || px(1.0 / pixel_ratio());
```

```tsx
const hairline = () => 1 / pixelRatio();
```

### openUrl

```ts
function openUrl(url: string): Promise<OpenUrlResult>;

interface OpenUrlResult {
  opened: boolean;
}
```

Opens `url` outside the app: a web page in the browser, a `mailto:` link in the mail app, a `tel:` link in the phone app, and any scheme another app registered (`maps:`, a host app's own `lb://` links). It resolves with `{ opened }`, whether something opened it: `false` when no app handles the scheme. Rust: `open_url(url)` of `nsh_core::prelude`, an answer to await in a task (or to drop), the same `bool`.

```rust
button()
    .child(text("Contact us"))
    .on_press(|| {
        spawn(async {
            if !open_url("mailto:help@example.com").await {
                log::warn!("no mail app");
            }
        });
    })
```

```tsx
<Button
  onPress={async () => {
    const { opened } = await openUrl("mailto:help@example.com");
    if (!opened) {
      console.warn("no mail app");
    }
  }}
>
  <Text>Contact us</Text>
</Button>
```

- The URL is absolute (it has a scheme). URLs that would run code or reach the app's own data, `javascript:`, `data:`, `blob:`, `file:`, `about:` and `asset:`, reject the promise with a `TypeError`, as do relative addresses. `openUrl` never throws: every failure rejects.
- An app that declares capabilities needs `openUrl`: `"openUrl": true` for every scheme, or `"openUrl": { "schemes": ["https", "mailto"] }` for those listed; other URLs reject with an `Error` whose `code` is `"ERR_ACCESS_DENIED"`, `permission` `"openUrl"` and `resource` the URL (see [Sandbox and capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md)). In Rust, `open_url` answers `false` for them and logs why.
- The embedding app sees the URL first and can route it through its own router instead (Swift `NshAppView.onOpenURL`, Java `NshView.setOpenUrlHandler`, Rust `AppView::host().handle_open_url`; see [iOS](https://nsh.dev/versions/main/docs/ios.md#links-the-app-opens) and [Android](https://nsh.dev/versions/main/docs/android.md#links-the-app-opens)). `opened` is then `true`.
- Each platform opens it with its own opener: `UIApplication.open` on iOS (the host app's application when embedded), an `ACTION_VIEW` intent on Android, `NSWorkspace` on macOS, `ShellExecuteW` on Windows, `GtkUriLauncher` on Linux, GPUI's `open_url`, a new tab on the web. `nsh test` records the URLs instead of opening them.
- A [`TextView`](https://nsh.dev/versions/main/elements/text-view.md) opens its links this way with `links="open"`.

### Layout direction

The layout direction follows the user's language: in a right-to-left language (Arabic, Hebrew, ...) the app lays out right to left, rows run from the right, and `left` / `right` style properties (`marginLeft`, `paddingRight`, ...) mean start and end. Changes apply at once, with no restart.

A view's `direction` style (`"ltr"`, `"rtl"` or `"inherit"`, the default) sets the direction of its own subtree; in Rust, `.direction(LayoutDirection::..)`.

```rust
view().direction(LayoutDirection::Rtl).flex_row().gap_2().child(text("First")).child(text("Second"))
```

```tsx
<View style={{ direction: "rtl", flexDirection: "row", gap: 8 }}>
  <Text>First</Text>
  <Text>Second</Text>
</View>
```

### Related

- Safe area insets (Rust `safe_area()`; TSX `safeArea()`, `safeAreaInsets()`) and the software keyboard (Rust `keyboard_height()`; TSX `keyboardFrame()`) are in [Safe area and keyboard](#safe-area-and-keyboard).
- Screen reader and reduced motion settings are in [Accessibility](#accessibility).

## PanResponder

Pan responders are drag gestures on top of the gesture responder system: the element claims the touches of a gesture, then hears them alone with the gesture state, which tracks the touches' centroid, the distance moved and the velocity for you. Rust code claims them with `.claim_touches(TouchClaim::…)` and hears them with `.on_responder_*` listeners whose `ResponderEvent` carries a `PanGesture`, all in `nsh_core::prelude`; TSX imports `PanResponder` from `nsh`, whose `onPanResponder…` callbacks receive the touch event and the gesture state.

```rust
use nsh_core::prelude::*; // TouchClaim, ClaimRequest, ResponderEvent, PanGesture
```

```tsx
import { PanResponder, type PanResponderGestureState } from "nsh";
```

> [!TIP]
> A pan responder delivers every move to the app's code, so it suits gestures that change app state (reordering, swipe-to-delete decisions). To move a view with the finger, the native gesture values are faster: `.pan_values(x, y)`, `.pinch_value(scale)` and `.rotation_value(angle)` in Rust, the `pan={{ x, y }}`, `pinch` and `rotation` props in TSX. The drag writes [animated values](#animation) on the UI thread and the app only hears when it starts and ends (`on_pan_start` / `on_pan_end`, `onPanStart` / `onPanEnd`). See [Touch and gestures](https://nsh.dev/versions/main/docs/touch-and-gestures.md).

### PanResponder.create

```ts
const PanResponder: { create(config: PanResponderCallbacks): PanResponderInstance };

interface PanResponderInstance {
  panHandlers: TouchProps;
}
```

Creates a pan responder. Spread its `panHandlers` on the view that should receive the gesture. In Rust, the view claims the touches and listens itself:

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

```tsx
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

Every callback receives the touch event (`GestureResponderEvent`, from [`nsh`](#types)) and the gesture state. In Rust, a claim decides with `.ask(|request: &ClaimRequest| …)`, calling `request.claim()` to take the touches (without `ask` it takes them always), and each listener gets a `ResponderEvent` whose `gesture` is the state.

```ts
type PanHandler<R = void> = (e: GestureResponderEvent, gestureState: PanResponderGestureState) => R;
```

| Callback | Rust | Returns | Called when |
|---|---|---|---|
| `onStartShouldSetPanResponder` | `.claim_touches(TouchClaim::on_start())` | `boolean` | A finger goes down: return `true` to become the responder. Asked from the touched view outwards. |
| `onStartShouldSetPanResponderCapture` | `TouchClaim::on_start().capture()` | `boolean` | The same, asked from the outside in before the bubbling one (a parent taking the gesture from its children). |
| `onMoveShouldSetPanResponder` | `TouchClaim::on_move().ask(…)` | `boolean` | A finger moves: return `true` to become the responder (e.g. only once `Math.abs(g.dx) > 10`). |
| `onMoveShouldSetPanResponderCapture` | `TouchClaim::on_move().capture()` | `boolean` | The same, capture phase. |
| `onPanResponderGrant` | `.on_responder_grant(…)` | | This view is the responder now: the gesture starts. |
| `onPanResponderReject` | `.on_responder_reject(…)` | | Another view is the responder and would not let go. |
| `onPanResponderStart` | `.on_responder_start(…)` | | A finger went down while responding. |
| `onPanResponderMove` | `.on_responder_move(…)` | | The fingers moved. |
| `onPanResponderEnd` | `.on_responder_end(…)` | | A finger lifted while responding. |
| `onPanResponderRelease` | `.on_responder_release(…)` | | The last finger lifted: the gesture ended. |
| `onPanResponderTerminate` | `.on_responder_terminate(…)` | | Another view (or a native gesture, like a scroll view) took the touches. |
| `onPanResponderTerminationRequest` | `.keep_touches(true)` keeps them | `boolean` | Another view wants the touches: return `false` to keep them (default `true`). |
| `onShouldBlockNativeResponder` | `TouchClaim::block_native(…)` | `boolean` | Whether to keep native scroll views from taking the touches while responding (default `true`). |

### PanResponderGestureState

```ts
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`, with points as `Point<Points>`.

| Field | Rust | Description |
|---|---|---|
| `stateID` |  | Identifies the gesture. |
| `moveX`, `moveY` | `position` | Latest position of the touches' centroid, in surface points. |
| `x0`, `y0` | `origin` | Where the centroid was when the responder was granted. |
| `dx`, `dy` | `delta` | Distance moved since the grant. |
| `vx`, `vy` | `vx`, `vy` | Velocity in points per second. |
| `numberActiveTouches` | `active_touches` | Fingers down. |

### Inside scroll views

While a pan responder is the responder, native scroll views around it do not scroll (`onShouldBlockNativeResponder` defaults to `true`). To let a horizontal swipe coexist with vertical scrolling, become the responder only on horizontal moves:

```rust
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))
```

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

For a pan the platform recognizes, `TouchClaim::on_pan(PanActivation::horizontal(10.0, 10.0))` decides on the main thread as the fingers move. The underlying responder props (`onStartShouldSetResponder`, `onResponderGrant`, `onTouchStart`, ...) can also be used directly on any element; see [Elements](https://nsh.dev/versions/main/elements.md).

## Clipboard

The clipboard API reads and writes the system clipboard: text everywhere (`UIPasteboard` on iOS, `ClipboardManager` on Android, `NSPasteboard`, GDK and the Win32 clipboard on desktops, `navigator.clipboard` on the web), images on iOS, the desktops and the web, and the files copied in a file manager on the desktops and Mac Catalyst. Rust code calls the functions of `nsh_core::prelude` (`set_clipboard`, `clipboard_string`, ...); TSX imports `Clipboard` from `nsh`.

```rust
use nsh_core::prelude::*; // set_clipboard, clipboard_string, clipboard_image, ...
use nsh_core::element::ClipboardImage;
```

```tsx
import { Clipboard } from "nsh";
```

```ts
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
}
```

| TS | Rust (`nsh_core::prelude`) |
|---|---|
| `await Clipboard.writeText(text)` | `set_clipboard(text)` |
| `await Clipboard.readText()` | `clipboard_string().await -> String` |
| `await Clipboard.hasText()` | `clipboard_has_string().await -> bool` |
| `await Clipboard.writeImage(src)` | `set_clipboard_image(src)` |
| `await Clipboard.readImage()` | `clipboard_image().await -> Option<ClipboardImage>` |
| `await Clipboard.hasImage()` | `clipboard_has_image().await -> bool` |
| `await Clipboard.readFiles()` | `clipboard_files().await -> Vec<String>` |

The Rust reads return answers to await in a task (`spawn`, or an `async` module function); `ClipboardImage` is `nsh_core::element::ClipboardImage`, with `url` and `size` (a `Size<DevicePixels>`).

Images go through the clipboard on iOS, the desktops and the web. On Android the clipboard carries text: `writeImage` and
`readImage` reject with an `Error` whose `code` is `"ERR_FEATURE_UNAVAILABLE_ON_PLATFORM"`, and `hasImage` resolves
`false`. In Rust, `set_clipboard_image` leaves the clipboard as it is there and `clipboard_image` answers `None`.

The user can also copy from a [selectable text](https://nsh.dev/versions/main/elements/text.md) themselves; the clipboard API is for copying from code, such as a Copy button.

### Clipboard.writeText

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

Puts `text` on the clipboard, replacing what was there. Rust: `set_clipboard(text)`.

```rust
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" }))
}
```

```tsx
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

```ts
readText(): Promise<string>;
```

Resolves with the clipboard's text, or `""` when it holds none. Rust: `clipboard_string()`. On iOS, reading the clipboard can show the system's paste notice ("App pasted from …"), and on Android 10 and later only the app in the foreground can read it. Read it when the user asks to paste, not on every screen.

```rust
spawn(async move {
    let pasted = clipboard_string().await;
    if !pasted.is_empty() {
        code.set(pasted.trim().to_string());
    }
});
```

```tsx
const pasted = await Clipboard.readText();
if (pasted) code.set(pasted.trim());
```

### Clipboard.hasText

```ts
hasText(): Promise<boolean>;
```

Resolves with whether the clipboard holds text, without reading it: no paste notice on iOS. Rust: `clipboard_has_string()`. Use it to decide whether to show a Paste button. On the web, browsers only tell by reading, so it may ask the user for permission.

```rust
let can_paste = signal(false);
spawn(async move { can_paste.set(clipboard_has_string().await) });
```

```tsx
const canPaste = signal(false);
Clipboard.hasText().then((has) => canPaste.set(has));
```

### Clipboard.readImage

```ts
readImage(): Promise<ClipboardImage | null>;
```

Resolves with the clipboard's image, or `null` when it holds none: a pasted screenshot, or an image copied in a browser
or an image editor. Rust: `clipboard_image()`, `None` when it holds none. `url` is a URL of the image (PNG, or the
clipboard's own JPEG, GIF, WebP or BMP) that an [`Image`](https://nsh.dev/versions/main/elements/image.md) shows as its `src` and `fetch` reads:
`fetch(url)` gives its bytes, for an upload. `size` (`width` and `height`) is its size in pixels, as decoded. As with
`readText`, read it when the user asks to paste. Images of up to 48 MB (encoded) are read, so the image fits in the
app's memory; a larger one rejects with an `Error` whose `code` is `"ERR_NSH_QUOTA_EXCEEDED"` (its message gives the
image's size and the limit), while `hasImage` resolves `true`. Rust: `clipboard_image()` answers `None` for it.

```rust
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
}
```

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

A chat-style app where users paste screenshots into a composer binds the paste shortcut while its input has the focus
and takes the image when there is one:

```rust
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);
        }
    });
});
```

```tsx
import { keymap } from "nsh";

keymap.bind("mod+v", async () => {
  if (await Clipboard.hasImage()) return paste();
  insertText(await Clipboard.readText());
}, { when: "always" });
```

### Clipboard.hasImage

```ts
hasImage(): Promise<boolean>;
```

Resolves with whether the clipboard holds an image, without reading it: no paste notice on iOS. Rust:
`clipboard_has_image()`. On Android it resolves `false`.

### Clipboard.writeImage

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

Puts the image of `src`, a base64 `data:` URL or the `url` `readImage` gave, on the clipboard, replacing what it holds.
Rust: `set_clipboard_image(src)`. On Windows it takes a PNG, the format browsers, Office and the Snipping Tool read. On
Android it rejects with `"ERR_FEATURE_UNAVAILABLE_ON_PLATFORM"`.

```rust
set_clipboard_image(image.url.clone());
```

```tsx
await Clipboard.writeImage(image.url);
```

### Clipboard.readFiles

```ts
readFiles(): Promise<string[]>;
```

Resolves with the `file:` URLs of the files and folders copied in a file manager (Finder, Explorer, Files), in their
order, or `[]`: the same URLs a [file drop](https://nsh.dev/versions/main/elements/view.md#desktop-file-drops) gives. Rust: `clipboard_files()`.
Parse a URL to get its path.

```rust
let paths: Vec<std::path::PathBuf> = clipboard_files()
    .await
    .iter()
    .filter_map(|file| url::Url::parse(file).ok()?.to_file_path().ok())
    .collect();
```

```tsx
const files = await Clipboard.readFiles();
const names = files.map((url) => decodeURIComponent(new URL(url).pathname.split("/").pop()!));
```

> [!NOTE]
> When your app declares `capabilities` in `nsh.json`, the clipboard must be granted with `"clipboard": true`. Without it every function of `Clipboard` rejects with an `Error` whose `code` is `"ERR_ACCESS_DENIED"`, `permission` `"clipboard"` and `resource` `""`, and nothing reaches the system clipboard. In Rust, the writes leave the clipboard as it is and the reads answer what an empty clipboard does (`""`, `None`, an empty list, `false`), and the refusal is logged. See [Sandbox and capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md).
>
> ```tsx
> try {
>   await Clipboard.writeText(code());
> } catch (error) {
>   if (error.code === "ERR_ACCESS_DENIED") showHint("Copying is turned off for this app");
>   else throw error;
> }
> ```

## Picker

The picker API shows the system's picker for photos and gives the app the images the user picks: the Photos picker on
iOS (`PHPickerViewController`), the Photo Picker on Android, an open panel or file dialog on the desktops and a file
input in a browser. On iOS and Android the picker runs outside the app and hands over only what the user picks, so it
needs no photo library permission. Each picked image arrives as a `File` (TSX) or a `PickedFile` (Rust) whose bytes stay
native: show it with `URL.createObjectURL(file)` in an [`Image`](https://nsh.dev/versions/main/elements/image.md), upload it with `fetch` and
`FormData`. Rust code calls `pick_images` of `nsh_core::prelude`; TSX imports `Picker` from `nsh`.

```rust
use nsh_core::picker::{PickRequest, PickedFile};
use nsh_core::prelude::*; // pick_images
```

```tsx
import { Picker, type PickedImage } from "nsh";
```

```ts
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
}
```

| TS | Rust |
|---|---|
| `await Picker.pickImages(options)` | `pick_images(request).await -> Vec<PickedFile>` |
| `multiple`, `limit` | `PickRequest::new(multiple, limit)` (`limit`: 0 for up to 100) |
| `maxDimension` | `request.max_dimension = Some(DevicePixels(2048))` |
| `quality` | `request.quality = Some(Percentage(0.8))` |
| `format` | `request.format = PickFormat::Current` |
| `image.file.name`, `.type`, `.size` | `file.name`, `file.mime`, `file.data.len()` |
| `image.size` | `file.size` (`Size<DevicePixels>`) |

### Picker.pickImages

```ts
pickImages(options?: PickImagesOptions): Promise<PickedImage[]>;
```

Shows the picker and resolves with the images the user picked, in the order picked, or `[]` when the user cancels.
Rust: `pick_images(request)`, an answer to await in a task (`spawn`, or an `async` module function). `pickImages`
never throws: options out of range (`limit: 0`, a `quality` outside 0 to 1) reject the promise with a `RangeError`, and a
pick the app's capabilities do not grant rejects with `ERR_ACCESS_DENIED` (below). A cancel is the user's answer, not a
failure: it resolves `[]`.

The images come ready to send:

- **Formats every browser and server take.** JPEG, PNG, GIF and WebP come as they are; a photo stored in another
  format (HEIC on iPhones, HEIF, TIFF) comes as a JPEG. `format: "current"` keeps the stored format.
- **Scaled down natively.** With `maxDimension`, an image whose longer side is longer is scaled to fit it, upright, and
  encoded again: a PNG as a PNG, anything else as a JPEG of `quality`. Phone photos are 12 to 48 megapixels; scaling
  them to 2048 pixels before an upload makes them a few hundred kilobytes. A `quality` encodes JPEGs again too.
- **What it shows.** `size` is the image's size in pixels as it shows, its camera orientation applied. An image NSH
  encodes again carries no metadata (no location); one that comes as it is keeps its own.

On Windows, Linux and in GPUI windows, the dialog offers the formats the request takes (with `"compatible"`: JPEG, PNG,
GIF and WebP) and the files come as they are stored, at their own size.

A chat composer attaches a photo, shows it while the message is written, and uploads it when it is sent:

```rust
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
}
```

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

Several photos at once:

```rust
let picked = pick_images(PickRequest::new(true, 9));
spawn(async move {
    let files = picked.await;
    photos.update(|list| list.extend(files));
});
```

```tsx
const images = await Picker.pickImages({ multiple: true, limit: 9, maxDimension: 2048 });
photos.set([...photos(), ...images.map((image) => URL.createObjectURL(image.file))]);
```

### Embedding apps

An app that embeds NSH and has a picker of its own (one with the app's own albums, say) answers the picks itself: in
Rust, a `PickerBackend` (`nsh_core::picker`) given to the engine (`EngineConfig::picker`, or `AppView::set_picker` in
GPUI and GPUI Kit apps) receives every pick's `PickRequest` and returns the files, and the system's picker is not
shown. The files it returns are completed as the platform's are: cut to the request's limit, their sizes, types and
extensions read from their bytes.

### Tests

`nsh test` answers picks in headless runs: `app.onPick(handler)` returns the files the user picks (`{ name, type, data }`),
and without a handler a pick is cancelled. See [Testing](https://nsh.dev/versions/main/docs/testing-and-trace.md).

> [!NOTE]
> When your app declares `capabilities` in `nsh.json`, the picker must be granted with `"picker": true`. Without it
> `pickImages` shows nothing and rejects with an `Error` whose `code` is `"ERR_ACCESS_DENIED"`, `permission`
> `"picker"` and `resource` `""`. In Rust, `pick_images` answers no files and the refusal is logged. See
> [Sandbox and capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md).

## Notifications

`Notifications` shows system notifications and sets the app's icon badge, the Dock's on macOS. Ask for the permission
when the user does something that needs it, then show:

```tsx
import { Notifications } from "nsh";

Notifications.on("press", ({ id }) => openChat(id));

async function notifyMe() {
  if ((await Notifications.requestPermission()) !== "granted") return;
  await Notifications.show({ id: "chat:42", title: "Ada", body: "Are you coming?" });
  Notifications.setBadge(1);
}
```

Rust code calls `request_notification_permission`, `show_notification`, `close_notification`, `set_badge` and
`next_notification_press` of `nsh_core::prelude`.

| Platform | Notifications | Badge |
| --- | --- | --- |
| macOS | The notification center, in a signed app bundle; `unavailable` in `nsh run`'s unbundled host | The Dock, without a permission |
| iOS | The notification center | The home screen, with the permission |
| Android | The system's, with `POST_NOTIFICATIONS` on Android 13 (`nsh package` declares it for apps granted `notifications`) | No count to set: launchers mark an app that has notifications showing, and the count goes with those shown after it |
| Windows | A toast, shown unless the user turned the app's notifications off in Settings, which is `denied`. Windows has no prompt, so `requestPermission` asks nothing. A surface embedded in another app is `unavailable` | The count on the taskbar button, up to `99+`; not shown when the taskbar uses small buttons |
| Linux | The desktop's notification daemon (`org.freedesktop.Notifications`): `granted` while one runs, with no prompt, `unavailable` otherwise | The Unity launcher API, on docks that read it (Plasma, Ubuntu's, Dash to Dock); elsewhere nothing shows |
| Web | `Notification`, where the browser shows them from a page (not on Android) | The Badging API, in an installed app |
| Terminal, GPUI | `unavailable` | None |

### Notifications.show

`show` resolves with whether the system took the notification, which it does not without the permission. A notification
shows while the app is in front as it does behind it. Showing another with the same `id` replaces it, and
`Notifications.close(id)` removes it.

### Notifications.on

`press` reports the `id` of the notification the user pressed. A press can start the app: it waits for the first
listener, so listen when the app starts, and keep what the press opens in the `id`. On Android an embedding app's
activity passes its intents to `NshView.handleNotificationIntent`, in `onCreate` and `onNewIntent`. On Apple platforms an
embedding app that has a notification center delegate keeps it, and its delegate gets the presses. On Linux a press reaches
only the running app: one left on screen after the app exits does nothing.

### Notifications.permission

`permission()` answers without asking, `requestPermission()` shows the system's prompt the first time. Both resolve with
`"default"` (not asked yet), `"granted"`, `"denied"` (only the system's settings change it) or `"unavailable"`.

## Speech

The speech API turns what the user says into text (dictation): the app starts a session, the platform listens to the
microphone, and the transcript arrives as it grows. macOS and iOS recognize with the system's Speech framework; the
system asks the user for the microphone and for speech recognition once. On other platforms a session ends at once
with the error `"unavailable"`, so check `Speech.available()` before showing a microphone button. Rust code calls
`recognize_speech` of `nsh_core::prelude`; TSX imports `Speech` from `nsh`.

```rust
use nsh_core::speech::{SpeechEvent, SpeechRequest};
```

```tsx
import { Speech, type SpeechSession } from "nsh";
```

```ts
const Speech: {
  available(): Promise<boolean>;
  start(options?: SpeechOptions): SpeechSession;
};

interface SpeechOptions {
  /** The language spoken, a BCP 47 tag ("en-US", "zh-CN"); the user's when left out. */
  lang?: string;
  /** Results while the user speaks (true, the default), or only the final one. */
  interim?: boolean;
}

interface SpeechSession {
  on(event: "start", listener: () => void): () => void;
  on(event: "result", listener: (result: SpeechResult) => void): () => void;
  on(event: "end", listener: (end: SpeechEnd) => void): () => void;
  /** The whole transcript so far. */
  readonly text: string;
  readonly ended: boolean;
  stop(): void;
  abort(): void;
}

interface SpeechResult { text: string; isFinal: boolean }
interface SpeechEnd { text: string; error?: SpeechErrorCode }

type SpeechErrorCode =
  | "not-allowed" | "no-speech" | "audio-capture" | "network"
  | "language-not-supported" | "unavailable" | "failed";
```

| TSX | Rust |
|---|---|
| `await Speech.available()` | `speech_available().await -> bool` |
| `Speech.start(options)` | `recognize_speech(request) -> SpeechRecognition` |
| `session.on("result", ...)` | `recognition.next().await -> Option<SpeechEvent>` |
| `session.stop()` / `abort()` | `recognition.stop()` / `abort()` (dropping it aborts) |

### Speech.start

Starts a session and returns it at once. A session reports, in this order: `start` when the microphone is on and the
recognizer listens, `result` each time the transcript changes (`text` is always the whole transcript so far, so the
app shows it as it is), and one `end`, after which nothing comes. `stop()` stops listening and lets the recognizer
finish what it heard: a last result with `isFinal: true`, then `end`. `abort()` ends the session at once, without an
error, and drops what was not reported. One session runs at a time: starting another aborts the one running.

`end` carries the last transcript and, when the session failed, `error`, named as in the Web Speech API:

| `error` | When |
|---|---|
| `"not-allowed"` | The user or the system does not allow the microphone or speech recognition. |
| `"no-speech"` | Nothing was said. |
| `"audio-capture"` | The microphone could not be used. |
| `"network"` | The recognizer needs the network and could not reach it. |
| `"language-not-supported"` | The recognizer does not know `lang`. |
| `"unavailable"` | This platform recognizes no speech, or not now. |
| `"failed"` | The recognizer failed for another reason. |

`start` throws a `TypeError` for options of the wrong types and a `RangeError` for a `lang` that is no language tag.

```tsx
import { signal, Speech, type SpeechSession } from "nsh";

const transcript = signal("");
let session: SpeechSession | null = null;

function toggle() {
  if (session && !session.ended) {
    session.stop();
    return;
  }
  session = Speech.start({ lang: "en-US" });
  session.on("result", ({ text }) => transcript.set(text));
  session.on("end", ({ text, error }) => {
    if (error) console.warn("dictation ended:", error);
    else transcript.set(text);
  });
}
```

```rust
use nsh_core::prelude::*;
use nsh_core::speech::{SpeechEvent, SpeechRequest};

async fn dictate() -> String {
    let mut recognition = recognize_speech(SpeechRequest::default());
    let mut text = String::new();
    while let Some(event) = recognition.next().await {
        match event {
            SpeechEvent::Result { text: heard, .. } => text = heard,
            SpeechEvent::End { .. } => break,
            _ => {}
        }
    }
    text
}
```

### Speech.available

Resolves `true` where a session can run: on macOS and iOS, and wherever the embedding app recognizes speech itself.

### Info.plist

On macOS and iOS the system shows why the app wants the microphone and speech recognition. `nsh package` and
`nsh run` write `NSMicrophoneUsageDescription` and `NSSpeechRecognitionUsageDescription` into the app's Info.plist
when the app may use speech (its `capabilities` grant `speech`, or it declares none).

### Embedding apps

An app that embeds NSH and recognizes speech its own way (its own engine or service) answers the sessions itself: in
Rust, a `SpeechBackend` (`nsh_core::speech`) given to the engine (`EngineConfig::speech`) receives every session's
`SpeechRequest` and a `SpeechSink` it reports to from any thread, and returns the `SpeechControl` the core stops and
aborts the session with. The platform's recognizer is not used then.

### Tests

`nsh test` runs sessions on a fake recognizer in headless runs: a session starts at once, `app.hear(text)` reports
`text` as the transcript so far, `app.endSpeech(error?)` ends it, and `app.speechRequests()` lists the sessions the
app started. See [Testing](https://nsh.dev/versions/main/docs/testing-and-trace.md).

> [!NOTE]
> When your app declares `capabilities` in `nsh.json`, speech must be granted with `"speech": true`. Without it
> `Speech.start` throws an `Error` whose `code` is `"ERR_ACCESS_DENIED"`, `permission` `"speech"` and `resource` `""`.
> In Rust, the session ends with `not-allowed` and the refusal is logged. See
> [Sandbox and capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md).

## Storage

The storage API keeps the app's data on the device: strings by string key, still there the next time the app starts. Use it for settings, drafts, the last tab the user had open, a cache of what the server sent — any state that should outlive the app's process. Rust code uses `nsh_core::storage::Storage`, TSX imports `Storage` from `nsh`; both read and write the same entries, so an app with a Rust entry and a TSX entry sees one set of data.

```rust
use nsh_core::storage::Storage;
```

```tsx
import { Storage } from "nsh";
```

```ts
const Storage: {
  getItem(key: string): Promise<string | null>;
  setItem(key: string, value: string): Promise<void>;
  removeItem(key: string): Promise<void>;
  keys(): Promise<string[]>;
  clear(): Promise<void>;
};
```

| TS | Rust (`nsh_core::storage::Storage`) |
|---|---|
| `await Storage.getItem(key)` | `Storage::get_item(key) -> Option<String>` |
| `await Storage.setItem(key, value)` | `Storage::set_item(key, value) -> Result<(), StorageFull>` |
| `await Storage.removeItem(key)` | `Storage::remove_item(key)` |
| `await Storage.keys()` | `Storage::get_all_keys() -> Vec<String>` |
| `await Storage.clear()` | `Storage::clear()` |

The Rust functions are synchronous, as the entries are in memory: call them where components run (their bodies, handlers and tasks).

Each app has a storage of its own, up to 5 MB of keys and values. Calls run in the order the app makes them, so a `getItem` after a `setItem` sees the new value without waiting for the write. Reads come from memory; writes reach the disk in the background, a few at a time.

| Platform | Where the data is kept |
|---|---|
| iOS | `Library/Application Support/nsh/<app id>/storage.json` in the app's container |
| Android | `files/nsh/<app id>/storage.json` in the app's private directory |
| macOS | `~/Library/Application Support/<app id>/storage.json` |
| Windows | `%APPDATA%\<app id>\storage.json` |
| Linux | `$XDG_DATA_HOME/<app id>/storage.json` (`~/.local/share/…`) |
| Web | The browser's `localStorage`, under keys named after the app id (`nsh:com.example.todo:…`) |

A `storage.json` that is damaged is kept as `storage.json.corrupt` next to it, and the app starts with an empty storage; one that cannot be read leaves the app's changes in memory, so the file is never replaced.

The app id is the `id` in `nsh.json`, and it travels with the app: `nsh build` and `nsh package` write it next to the bundle, the dev server sends it, and a signed package carries the one its release key's certificate vouches for. So every app keeps its own data with no setting, wherever it runs; an app without an id keeps it under `default`. An embedding app can choose another place (see [Embedding on iOS](https://nsh.dev/versions/main/docs/ios.md) and [Embedding on Android](https://nsh.dev/versions/main/docs/android.md)).

### Storage.getItem

```ts
getItem(key: string): Promise<string | null>;
```

Resolves with the value of `key`, or `null` when it has none. Rust: `Storage::get_item(key)`, `None` when it has none.

```rust
let theme = Storage::get_item("theme").unwrap_or_else(|| "system".into());
```

```tsx
const theme = (await Storage.getItem("theme")) ?? "system";
```

### Storage.setItem

```ts
setItem(key: string, value: string): Promise<void>;
```

Sets `key` to `value`, replacing what it held. Rejects with an `Error` whose `code` is `"ERR_NSH_QUOTA_EXCEEDED"` when the storage would grow past 5 MB; the value is not kept then. Rust: `Storage::set_item(key, value)`, which returns `Err(StorageFull)` then. Values are strings: keep structured data as JSON (`serde_json::to_string` in Rust, `JSON.stringify` in TSX) and read it back (`serde_json::from_str`, `JSON.parse`).

```rust
let draft = serde_json::json!({ "title": title.get(), "body": body.get() });
if let Err(full) = Storage::set_item("draft", draft.to_string()) {
    log::warn!("{full}");
}
```

```tsx
Storage.setItem("draft", JSON.stringify({ title: title(), body: body() }));
```

### Storage.removeItem

```ts
removeItem(key: string): Promise<void>;
```

Removes `key` and its value. Removing a key that has no value does nothing. Rust: `Storage::remove_item(key)`.

### Storage.keys

```ts
keys(): Promise<string[]>;
```

Resolves with every key, in order. Rust: `Storage::get_all_keys()`.

### Storage.clear

```ts
clear(): Promise<void>;
```

Removes every key of the app, such as when the user signs out. Rust: `Storage::clear()`.

### Keeping a signal on the device

Read the stored value when the app starts, then write it back whenever the signal changes:

```rust
use nsh_core::{storage::Storage, prelude::*};

#[component]
pub fn App() -> impl IntoElement {
    let saved = Storage::get_item("count").and_then(|n| n.parse().ok());
    let count = signal(saved.unwrap_or(0_u32));
    effect(move || {
        if let Err(full) = Storage::set_item("count", count.get().to_string()) {
            log::warn!("{full}");
        }
    });
    view()
        .on_press(move || count.update(|n| *n += 1))
        .child(text(move || format!("Pressed {} times", count.get())))
}
```

```tsx
import { effect, mount, signal, Text, View } from "nsh";
import { Storage } from "nsh";

const count = signal(0);
const loaded = signal(false);
Storage.getItem("count").then((saved) => {
  count.set(Number(saved ?? 0));
  loaded.set(true);
});
effect(() => {
  if (loaded()) Storage.setItem("count", String(count()));
});

mount(() => (
  <View onPress={() => count.update((n) => n + 1)}>
    <Text>Pressed {count()} times</Text>
  </View>
));
```

## host

`host` reaches the app that embeds NSH: the native app around an `NshAppView` / `NshView`, or on the web the page that runs the player. The app calls the host's functions by name with JSON arguments and listens to the events the host sends.

```ts
import { host } from "nsh";
```

```ts
const host: {
  readonly params: { readonly [key: string]: unknown };
  post(name: string, data?: unknown): void;
  available(): boolean;
  call(name: string, args?: unknown, options?: { timeout?: number }): Promise<unknown>;
  on(event: string, listener: (payload: unknown) => void): () => void;
};
```

### host.available

```ts
available(): boolean;
```

Whether the platform has a host that answers calls. On the web it is `true` when the page gives the player a host ([The host on the web](#the-host-on-the-web)).

```tsx
import { Text } from "nsh";
import { host } from "nsh";

<Text>{host.available() ? "Embedded" : "Standalone"}</Text>;
```

### host.call

```ts
call(name: string, args?: unknown, options?: { timeout?: number }): Promise<unknown>;
```

Calls the host's function `name` with `args` (any JSON value; `null` without one) and resolves with what it returns. `host.call` never throws: every failure rejects the promise, with an `Error` whose `code` says what happened (the message is for people and may change):

| `code` | When |
|---|---|
| `ERR_NSH_HOST_ERROR` | The host's function failed, or the host has no function `name`; the message is the host's |
| `ERR_ACCESS_DENIED` | `name` is not in the app's [`host` capability](#capability); `permission` is `"host"`, `resource` the name |
| `ERR_FEATURE_UNAVAILABLE_ON_PLATFORM` | The platform has no host: `host.available()` is `false` |
| `ETIMEDOUT` | The host did not answer in time |
| `ERR_NSH_QUOTA_EXCEEDED` | 1024 calls already wait for the embedding app's answers |

A name that is no valid name (1 to 128 of `A`–`Z`, `a`–`z`, `0`–`9`, `_`, `.`, `:`, `-`, without `..`) rejects with a `TypeError`.

A call waits 30 seconds for the host's answer, then rejects with `ETIMEDOUT`; an answer that comes later is dropped. `options.timeout` sets the wait in milliseconds, `0` for no limit; a timeout so large the clock never gets there (about 1e22 ms) waits without limit too, and a negative, `NaN` or infinite one rejects the call with a `RangeError`. The time is the app's, as its timers': in `nsh test` with a manual clock it moves with the clock.

```ts
const user = (await host.call("getUserInfo")) as { name: string };
const quote = await host.call("quote.refresh", { symbol: "AAPL" }, { timeout: 5000 }).catch((error) => {
  if (error.code === "ETIMEDOUT" || error.code === "ERR_FEATURE_UNAVAILABLE_ON_PLATFORM") return null;
  throw error;
});
```

### host.on

```ts
on(event: string, listener: (payload: unknown) => void): () => void;
```

Platform events call `listener` with the payload of every `event` the host sends, until the function `host.on` returns is called; a listener added while a component renders stops with the component. Events the host sends before the app starts arrive once it does, so listeners registered at the top level of the app receive them; an event sent before a listener registers is not replayed to it. Read the state the app starts with through `host.call`, and follow its changes with `host.on`.

```ts
const stop = host.on("loginChanged", (payload) => console.log(payload));
// later
stop();
```

### Capability

Every function the app calls must be listed in `nsh.json`'s `capabilities.host`: exact names or prefixes ending in `*`, or `true` for all of them. This holds for every app, also one without other `capabilities`: the host's functions are never granted by default. A call that is not granted rejects with `ERR_ACCESS_DENIED` and is logged, a `host.post` of such a name to an embedding app throws the same error, and building an app that imports `host` from `nsh` without `capabilities.host` warns. Events need no grant. See [Sandbox and capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md#host).

```json
{ "capabilities": { "host": ["getUserInfo", "bridge.*"] } }
```

### The host on the web

On the web the page is the host. `createPlayer`'s `host` option answers the calls, and `player.hostEvent(event, payload)` sends events:

```js
const player = await createPlayer(container, {
  wasm: "./nsh.wasm",
  host: { call: (name, args) => (name === "getUserInfo" ? { name: "Ada" } : Promise.reject(new Error(name))) },
});
player.hostEvent("loginChanged", { signedIn: true });
```

A published app names its host in `nsh.json`: `web.host` is a JS module in the app's directory, relative to `nsh.json`, exporting `createHost(player)`, which returns the object with `call`. `nsh package --target web` ships it with the site, `nsh run --target web` runs it on the development page, and `nsh test` runs it for the apps its tests open. `web.connect` lists the hosts the host's own requests reach, which the page's Content-Security-Policy allows alongside the app's `capabilities.network`. See [Web](https://nsh.dev/versions/main/docs/web.md#the-hosts-functions).

```json
{ "web": { "host": "./host.js", "connect": ["api.example.com"] } }
```

### host.params

The parameters the embedding app set before it started your app, read synchronously from the first line of your code; `{}` when it set none. They stay the same while your app runs: later requests come as events.

```tsx
const conversation = host.params.conversation as string | undefined;
mount(() => (conversation ? <Conversation id={conversation} /> : <Inbox />));
```


### Native SDK channel

The native SDK's `send` keeps events until the app listens, up to 256. When the last listener stops during delivery, remaining events keep waiting in order; events sent during shutdown wait for the next loaded app. `host.post(name, data)` delivers data to the native SDK handler, whose `isPost` distinguishes posts from calls.

### The embedding app's side

Each view keeps one channel for every app it loads. Set parameters before loading, send events at any time from any thread, and register handlers by name. Calls and posts require the app's `capabilities.host` grant. Handlers answer once, now or later; an answer that never comes fails the call.

```rust
// Any platform's AppView (GPUI, macOS, Windows, Linux, iOS): its HostChannel.
use serde_json::json;

let host = view.host();
let mut params = serde_json::Map::new();
params.insert("conversation".into(), json!("42"));
host.set_params(params);
// Runs on the engine thread: answer at once, or move the call and answer later from any thread.
host.handle("user.profile", |call| {
    let id = call.data()["id"].clone();
    call.resolve(json!({ "id": id, "name": "Ada" }));
});
host.send("conversation.open", json!({ "id": "43" })).unwrap();
```

```swift
appView.params = ["conversation": "42"]
try appView.loadBundle(at: bundleURL)

// On the main thread; return the answer, or throw to reject the call.
appView.handle("user.profile") { data in
    let id = (data as? [String: Any])?["id"]
    return ["id": id ?? NSNull(), "name": try await profiles.name(of: id)]
}
appView.handle("analytics") { data, _ in analytics.log(data) }
appView.send("conversation.open", ["id": "43"])
```

```java
nsh.setParams(Map.of("conversation", "42"));
nsh.loadAssetBundle("nsh");

// On the UI thread; answer now or later, from any thread.
nsh.handle("user.profile", (data, reply) -> {
    Object id = ((Map<?, ?>) data).get("id");
    profiles.load(id, profile -> reply.resolve(Map.of("id", id, "name", profile.name)),
            error -> reply.reject(error.getMessage()));
});
nsh.send("conversation.open", Map.of("id", "43"));
```

See [Embedding on iOS](https://nsh.dev/versions/main/docs/ios.md#talking-to-the-app), [Embedding on Android](https://nsh.dev/versions/main/docs/android.md#talking-to-the-app) and [GPUI](https://nsh.dev/versions/main/docs/gpui.md).

> [!NOTE]
> Native SDK calls and posts use the same [`host` capability](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md#host) as platform calls. A Rust app reaches the embedding app's Rust directly, through the functions it registers ([`nativeModule`](#nativemodule) and Rust imports).

## keymap

The keymap binds the app's keyboard shortcuts: a keystroke such as `"mod+k"` and the function it runs. Rust code calls `on_key`, `on_key_with` and `key_label` from `nsh_core::prelude`; TSX imports `keymap` from `nsh`. Both take the same keystrokes and follow the same rules.

```rust
use nsh_core::prelude::*; // on_key, on_key_with, KeyOptions, key_label
```

```tsx
import { keymap } from "nsh";
```

```ts
const keymap: {
  bind(keystroke: string, handler: (e: { keystroke: string }) => void, options?: KeyBindingOptions): () => void;
  bind(bindings: Record<string, (e: { keystroke: string }) => void>, options?: KeyBindingOptions): () => void;
  label(keystroke: string): string;
};

interface KeyBindingOptions {
  when?: "always" | "notEditing";
  repeat?: boolean;
  passThrough?: boolean;
}
```

| TS | Rust |
|---|---|
| `keymap.bind(keystroke, handler)` | `on_key(keystroke, handler)` |
| `keymap.bind(keystroke, handler, { when, repeat, passThrough })` | `on_key_with(keystroke, KeyOptions { when, repeat, pass_through }, handler)`; `when` is `nsh_core::keymap::When` (`Auto`, `Always`, `NotEditing`) |
| `keymap.bind({ … })` | one `on_key` per keystroke |
| `keymap.label(keystroke)` | `key_label(keystroke)` |

A Rust binding lives as long as the component (the owner) that made it; the handler gets the keystroke as written.

Shortcuts work on macOS, Windows, Linux and in browsers (the browser's own keys, such as Ctrl+T or Cmd+W, never reach the page), and on iOS and Android with a hardware keyboard: an iPad's, a Mac's running an iPad app, a tablet's or a Chromebook's, the simulator's and the emulator's. The same code runs everywhere; without a keyboard, no key fires the bindings.

### keymap.bind

```ts
bind(keystroke: string, handler: (e: { keystroke: string }) => void, options?: KeyBindingOptions): () => void;
```

Runs `handler` when `keystroke` is pressed and returns a function that removes the binding. The handler gets `{ keystroke }`: the keystroke as you wrote it, in its case. Rust: `on_key(keystroke, handler)`, whose handler gets the keystroke itself.

```rust
use nsh_core::prelude::*;

#[component]
pub fn App() -> impl IntoElement {
    let open = signal(false);
    on_key("mod+k", move |_| open.set(true));
    on_key("escape", move |_| open.set(false));
    text(move || if open.get() { "Search…" } else { "Press ⌘K" })
}
```

```tsx
import { mount, signal, Text } from "nsh";
import { keymap } from "nsh";

const open = signal(false);
keymap.bind("mod+k", () => open.set(true));
keymap.bind("escape", () => open.set(false));

mount(() => <Text>{open() ? "Search…" : "Press ⌘K"}</Text>);
```

Pass an object to bind several keystrokes at once; the function returned removes them all. In Rust, each keystroke is one `on_key`:

```rust
on_key("mod+s", move |_| save());
on_key("mod+shift+p", move |_| open_palette());
on_key("f5", move |_| refresh());
```

```tsx
const unbind = keymap.bind({
  "mod+s": save,
  "mod+shift+p": openPalette,
  f5: refresh,
});
```

A binding made while a component renders is removed with the component, so a screen's shortcuts live as long as the screen:

```rust
#[component]
fn Editor() -> impl IntoElement {
    on_key("mod+enter", move |_| send());
    input().multiline(true)
}
```

```tsx
function Editor() {
  keymap.bind("mod+enter", send);
  return <Input multiline />;
}
```

With the dev server, editing a module removes the bindings its top-level code made before it runs again, so hot reload never leaves stale shortcuts behind.

### keymap.label

```ts
label(keystroke: string): string;
```

Returns `keystroke` as menus and hints show it where the app runs: `"⇧⌘L"` on macOS and iOS (and in a browser on a Mac, iPhone or iPad), `"Ctrl+Shift+L"` on Windows, Linux and other browsers, for `"mod+shift+l"`. Rust: `key_label(keystroke)`. Use it to show an app's shortcuts with the keys that work:

```rust
text(format!("Search {}", key_label("mod+k")))
```

```tsx
<Text>Search {keymap.label("mod+k")}</Text>
```

It throws a `TypeError` for an invalid keystroke, as `bind` does; `key_label` and `on_key` panic with the same message.

### Keystrokes

A keystroke is modifiers and a key joined by `+`: `"mod+k"`, `"ctrl+shift+p"`, `"alt+enter"`, `"escape"`, `"f5"`, `"cmd+-"` (Command and minus).

| Modifier | macOS | Windows | Linux |
|---|---|---|---|
| `mod` (also `cmdorctrl`) | Command (⌘) | Ctrl | Ctrl |
| `cmd` (also `command`, `meta`, `super`, `win`) | Command (⌘) | Windows key | Super |
| `ctrl` (also `control`) | Control (⌃) | Ctrl | Ctrl |
| `alt` (also `option`, `opt`) | Option (⌥) | Alt | Alt |
| `shift` | Shift (⇧) | Shift | Shift |

iOS follows macOS (`mod` is Command) and Android follows Windows and Linux (`mod` is Ctrl, `cmd` the Meta key). In a browser, keys follow the platform the browser runs on: `mod` is Command on a Mac, iPhone or iPad and Ctrl elsewhere.

Use `mod` for an app's own shortcuts: it is the key each platform's apps use for them (⌘K on macOS, Ctrl+K on Windows and Linux), so one spelling fits everywhere. The Windows key and Super mostly belong to the system, so `cmd` is rarely right outside macOS.

The key is a letter, digit or punctuation key, written as the character it types on a US keyboard without Shift (`k`, `1`, `,`, `/`, `[`; `"shift+/"` for `?`, `"shift+k"` for Shift+K), or a name: `plus` (the `=` / `+` key, also written `=`), `minus` (also `-`), `space`, `enter` (`return`), `escape` (`esc`), `tab`, `backspace`, `delete` (`del`), `insert`, the arrows `up`, `down`, `left`, `right` (`arrowup`, …), `home`, `end`, `pageup`, `pagedown`, `f1` to `f24`. Case does not matter: `"Mod+Shift+K"` is `"mod+shift+k"`, and a capital letter is the same key, not Shift (`"mod+K"` is `"mod+k"`). Lowercase is the recommended style, which these pages use. `"mod-k"` and `"mod++"` are errors whose messages give the right spelling. Menu shortcuts in `nsh/desktop` take the same keystrokes.

Shortcuts work with any keyboard layout: on a Cyrillic or Greek layout, `mod+k` is the key that types K on a US layout, as menu shortcuts are.

`bind` throws a `TypeError` that says what is wrong with an invalid keystroke (`keymap.bind: invalid keystroke "cmd+kk": unknown key "kk"`), and refuses the keystrokes the system keeps for itself, so an app can never break them:

| Platform | Reserved |
|---|---|
| macOS, iOS | Cmd+Q (quit), Cmd+H (hide), Option+Cmd+H (hide others), Cmd+M (minimize), Ctrl+Cmd+F (full screen) |
| Linux, Windows, Android | Ctrl+Q (quit), Alt+F4 (close), F11 (full screen) |
| Web | None (the browser keeps its own keys) |

### While typing

A text input with the keyboard focus needs its keys: typing, moving the caret, deleting, and select all, cut, copy, paste, undo and redo. So by default a binding does not fire while a text input (or a web view) has the focus if its keystroke is one of these: plain keys and keys with only Shift or Option, the arrows, Home, End, Page Up / Down, Return, Tab, Escape, Backspace, Delete, and `mod+a`, `mod+c`, `mod+v`, `mod+x`, `mod+z`. Other keystrokes with Command or Control, and the function keys, fire wherever the focus is.

`when` changes that (Rust: `KeyOptions { when: When::Always, .. }`):

| `when` | Fires |
|---|---|
| (default) | As above |
| `"always"` | Also in text inputs, before the input sees the key |
| `"notEditing"` | Never while a text input has the focus |

```rust
use nsh_core::keymap::When;

// Sends from the message field too.
on_key_with("mod+enter", KeyOptions { when: When::Always, ..KeyOptions::default() }, move |_| send());
// Only when the user is not typing.
on_key_with("mod+e", KeyOptions { when: When::NotEditing, ..KeyOptions::default() }, move |_| archive());
```

```tsx
// Sends from the message field too.
keymap.bind("mod+enter", send, { when: "always" });
// Only when the user is not typing.
keymap.bind("mod+e", archive, { when: "notEditing" });
```

On iOS and Android, a key an input method is composing with (choosing a candidate, committing) stays the input method's. On the GPUI backend, a native component with the keyboard focus counts as a text input, since it may be a text editor. It sees each key first: a key it handles itself never reaches the bindings, and the bindings that fire while text is edited get the keys it lets through.

### Which binding runs

A key that fires a binding is consumed (a binding with `passThrough` lets it go on, below): it is not typed, the system does not beep, and NSH's own keys do not see it (Escape going back, Tab moving the focus, the arrows scrolling). When several bindings have the same keystroke, the newest one that may fire runs, so a dialog can bind Escape over the screen's binding and the screen's comes back when the dialog's goes. Bindings are checked natively the moment the key is pressed; the handler runs right after, on the engine thread (Rust) or the JS thread (TSX).

Holding a key down fires its binding once, until the key is released; with `repeat: true` it fires again on every auto-repeat (to step through a list, say):

```rust
on_key_with("alt+down", KeyOptions { repeat: true, ..KeyOptions::default() }, move |_| next_item());
```

```tsx
keymap.bind("alt+down", nextItem, { repeat: true });
```

With `passThrough: true` the binding runs and the key goes on as if nothing were bound: Tab still moves the focus, a text input still types. A popup that closes when Tab leaves it binds Tab this way, and the focus moves to the next control:

```rust
on_key_with("tab", KeyOptions { pass_through: true, ..KeyOptions::default() }, move |_| close());
```

```tsx
keymap.bind("tab", close, { passThrough: true });
```

Menu shortcuts give way to a binding of the same keystroke: the application menu's ([`nsh/desktop`](./nsh-desktop)) on every desktop, and on macOS the built-in menus' too (Cmd+W, Cmd+C, ...). While you develop with `nsh run`, Cmd+R / Ctrl+R always reloads the app, even if it binds `mod+r`; a packaged app can bind it.

## nativeComponent and nativeModule

`nativeComponent` and `nativeModule` connect your app to what the host app provides, by name, at run time. An iOS or Android app that embeds NSH can register its own views (a map, a chart, a camera preview) by name; `nativeComponent` gives you a typed component for one of them. Because NSH renders with real native views, such a component sits in the view hierarchy like any other view: it is laid out by NSH, clips and scrolls with its parents, and overlaps correctly. An app that embeds NSH from Rust can also register functions, classes and Rust components; `nativeModule` gives you them as one typed object. Your app builds with the stock `nsh build` either way: the host connects what it provides when it runs the app. Rust code places a registered view with `native(name)` from `nsh_core::prelude`, sets its props with `.prop(name, value)` (a JSON value, or a signal or closure of one) or binds one to an animated value with `.bind_prop(name, &value)`, hears its events with `.on_native_event(…)` and calls its commands through an `ElementRef`; TSX imports `nsh`.

```rust
use nsh_core::prelude::*; // native, NativeEvent, element_ref
```

```tsx
import { nativeComponent, nativeModule } from "nsh";
```

See [Native components](https://nsh.dev/versions/main/docs/native-components.md) for registering the native side, and [Embedding on iOS](https://nsh.dev/versions/main/docs/ios.md) / [Embedding on Android](https://nsh.dev/versions/main/docs/android.md).

### nativeComponent

```ts
function nativeComponent<P extends object = {}, E extends object = {}>(
  name: string,
  spec: NativeComponentSpec<P, E>,
): (props: NativeComponentProps<P, E>) => JSX.Element;

interface NativeComponentSpec<P, E> {
  /** Its own props: sent to the component (any JSON value), each when it changes. */
  props: readonly (keyof P & string)[];
  /** The events it emits. */
  events?: readonly (keyof E & string)[];
}
```

Returns a component for the native component the embedding app registered as `name` (Swift `NshAppView.register(component:)`, Java `NshView.registerComponent`). Rust: `native(name)`, a view whose props are JSON values (`.prop("text", json!(…))`) and whose events arrive as `NativeEvent { name, data }`.

- `P` is the type of its own props. Each prop listed in `spec.props` is sent to the native side as JSON when it changes; setting it to `undefined` removes it.
- `E` maps event names to their payloads. An event `regionChange` becomes the handler prop `onRegionChange`.
- The component also takes every [view prop](https://nsh.dev/versions/main/elements/view.md) except `children`: `style`, `class`, layout, accessibility, touch handlers and `ref`.

```ts
type NativeComponentProps<P, E> = Omit<ViewProps, "children"> & P & NativeEventHandlers<E>;
type NativeEventHandlers<E> = { [K in keyof E & string as `on${Capitalize<K>}`]?: (data: E[K]) => void };
```

#### Size

The component is laid out like a view, at the size its style gives it. Where the style leaves a dimension open, it uses the size the native component reports (as an image uses its natural size).

#### Commands

Its `ref` receives a `NativeComponentRef`; `ref.command(name, args)` calls command `name` of the native component with `args` (any JSON value). Rust: `ElementRef::command(name, args)`.

```rust
map.command("zoomTo", json!({ "level": 3 }));
```

```tsx
map.command("zoomTo", { level: 3 });
```

#### When nothing is registered

Where nothing is registered under `name` (a different host app, the dev host, the browser), the component renders an empty view and a warning is logged once. Keep the app usable without it, or check for your host before using it.

### Example

The badge here is a native view of the host app, registered as `embed.badge`. NSH lays it out, sends it `text` and `color`, receives its `tap` events, and calls its `pulse` command:

```rust
use nsh_core::prelude::*;
use serde_json::json;

#[component]
pub fn App() -> impl IntoElement {
    let taps = signal(0_u64);
    let badge = element_ref();
    view()
        .flex_1()
        .p_5()
        .gap_4()
        .child(
            native("embed.badge")
                .prop("text", json!("Tap the native badge"))
                .prop("color", json!("#8250df"))
                .element_ref(&badge)
                .on_native_event(move |e: &NativeEvent| {
                    if &*e.name == "tap" {
                        taps.set(e.data["count"].as_u64().unwrap_or(0));
                        badge.command("pulse", json!(null));
                    }
                })
                .self_start()
                .rounded(px(8.0))
                .overflow_hidden(),
        )
        .child(text(move || format!("Tapped {}×", taps.get())))
}
```

```tsx
import { mount, type NativeComponentRef, signal, View } from "nsh";
import { nativeComponent } from "nsh";

const Badge = nativeComponent<{ text: string; color?: string }, { tap: { count: number } }>("embed.badge", {
  props: ["text", "color"],
  events: ["tap"],
});

function App() {
  const taps = signal(0);
  let badge: NativeComponentRef | undefined;
  return (
    <View style={{ flex: 1, padding: 20, paddingTop: "calc(env(safe-area-inset-top) + 20px)", gap: 16 }}>
      <Badge
        ref={(node) => (badge = node)}
        text={taps() === 0 ? "Tap the native badge" : `Tapped ${taps()}×`}
        color="#8250df"
        onTap={(e) => {
          taps.set(e.count);
          badge?.command("pulse");
        }}
        style={{ alignSelf: "flex-start", borderRadius: 8, overflow: "hidden" }}
      />
    </View>
  );
}

mount(App);
```

### nativeModule

```ts
function nativeModule<T extends object>(specifier: string): T;
```

Returns the exports of the set the embedding app registered as `specifier`: its modules, classes, functions and Rust components, as one object. The app writes the type `T` itself, so nothing about the host is needed when it is built. Rust code built together with the host's crate calls those functions as Rust; `nativeModule` is how TSX reaches them.

```ts
import { nativeModule, signal } from "nsh";

interface TradingApi {
  quote(symbol: string): number;
  placeOrder(symbol: string, quantity: number, side: "Buy" | "Sell"): Promise<Order>;
  on(event: "change", listener: (desk: Desk) => void): () => void;
}

const { Trading } = nativeModule<{ Trading: TradingApi }>("host/trading");

const price = Trading.quote("AAPL");

const desk = signal<Desk | null>(null);
Trading.on("change", (d) => desk.set(d));
```

- Calls work as they do through an import of a set: a plain Rust function returns its value at once, an `async` one returns a promise, and a function you pass is a callback Rust can call later. Rust checks every argument and throws a `TypeError` for a wrong one.
- Each call with the same `specifier` returns the same object.
- Where nothing is registered under `specifier`, `nativeModule` throws a `ReferenceError` naming it. Call it where the app can handle that, or only in the host it is made for.

The host registers the set from Rust, with the platform crate's `set_ui_sets` (next to NSH's own sets) before it starts its views, or `EngineConfig::ui_sets`:

```rust
use std::{cell::RefCell, rc::Rc};

use nsh_core::prelude::*;

pub struct Trading;

#[module]
impl Trading {
    /// A sample price.
    pub fn quote(symbol: String) -> Result<f64, String> { /* ... */ }

    /// Calls `listener` with the desk now and after every change
    /// (`change`, the one event), until the returned function is called
    /// or what called `on` goes.
    pub fn on(event: String, listener: Callback<Desk>, cx: CallCx<'_>) -> Result<Stop, String> {
        if event != "change" {
            return Err(format!("no Trading event `{event}`"));
        }
        let listener = Rc::new(RefCell::new(Some(listener)));
        let held = listener.clone();
        cx.start(async move {
            let mut desk = DESK.subscribe(); // a tokio watch channel the host keeps
            loop {
                let Some(listener) = held.borrow().clone() else { return };
                listener.post(desk.borrow_and_update().clone());
                if desk.changed().await.is_err() {
                    return;
                }
            }
        });
        Ok(Stop::new(move || drop(listener.take())))
    }
}

let mut trading = Registry::ui_set("host/trading");
trading.module::<Trading>();
nsh_platform_gpui::set_ui_sets(vec![nsh_base::registry(), trading]);
```

`on` is how the host keeps every app in step with its own data: the task it starts waits for the host's changes and posts each one to the app, so a change made by the host, or by any app through another function, reaches every app that listens. The `Stop` it returns is the function `Trading.on` returns in TSX: it runs once, when the app calls it or when what called `on` goes (a component, or the module's run under hot reload), and here drops the listener, so the task ends.

> [!NOTE]
> Props, events and command arguments cross to the native side as JSON. Registered components and functions are the host app's own code: NSH's [sandbox limits and capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md) do not apply to what they do.

## Accessibility

The accessibility API reads the user's accessibility settings (is a screen reader running, did they ask for less motion) and talks to the screen reader. Rust code calls `screen_reader()`, `reduce_motion()` and `announce_for_accessibility()` from `nsh_core::prelude` and moves the focus with an `ElementRef`; TSX imports `screenReaderEnabled()`, `reduceMotion()`, `announce()` and `setAccessibilityFocus()` from `nsh`. The settings are reactive: read them in a binding, `computed` or `effect`, and what reads them updates when the user changes them. The accessibility props of elements (`accessibilityLabel`, `role`, ...) are documented under [Elements](https://nsh.dev/versions/main/elements.md); the guide is [Accessibility](https://nsh.dev/versions/main/docs/accessibility.md).

```rust
use nsh_core::prelude::*; // screen_reader, reduce_motion, announce_for_accessibility, element_ref
```

```tsx
import { announce, reduceMotion, screenReaderEnabled, setAccessibilityFocus } from "nsh";
```

### screenReaderEnabled

```ts
const screenReaderEnabled: Accessor<boolean>;
```

Whether a screen reader (VoiceOver, TalkBack) is running. Reactive: what reads it updates when the user turns the screen reader on or off. Rust: `screen_reader() -> bool`, reactive in the same way.

```rust
when(move || !screen_reader(), || text("Swipe for the next photo"))
    .otherwise(move || text("Next photo").on_press(next))
```

```tsx
<If when={!screenReaderEnabled()} else={<Text onPress={next}>Next photo</Text>}>
  <Text>Swipe for the next photo</Text>
</If>
```

### reduceMotion

```ts
const reduceMotion: Accessor<boolean>;
```

Whether the user asked for less motion (Reduce Motion on iOS, Remove animations on Android). Reactive. Rust: `reduce_motion() -> bool`. Tailwind classes follow it too with the `motion-reduce:` variant.

```rust
let open = move || {
    if reduce_motion() {
        panel.set(0.0);
    } else {
        let _ = panel.spring(0.0, Spring::default());
    }
};
```

```tsx
const open = () => {
  if (reduceMotion()) panel.set(0);
  else panel.spring(0);
};
```

### announce

```ts
function announce(message: string): void;
```

The screen reader reads `message` (a VoiceOver announcement, TalkBack). Use it for results that appear without focus moving, such as "Saved". Rust: `announce_for_accessibility(message)`.

### setAccessibilityFocus

```ts
function setAccessibilityFocus(node: ViewRef): void;
```

Moves the screen reader's focus to `node` (an element's `ref`). Rust: `ElementRef::set_accessibility_focus()`.

```rust
use nsh_core::prelude::*;

#[component]
fn Saved() -> impl IntoElement {
    let note = element_ref();
    let save = move || {
        announce_for_accessibility("Saved");
        note.set_accessibility_focus();
    };
    // Runs again when the setting changes, until the component goes.
    effect(|| log::info!("screen reader {}", screen_reader()));
    view()
        .gap_2()
        .child(text("Save").role(AccessibilityRole::Button).on_press(save))
        .child(text("Your changes are kept on this device.").element_ref(&note))
}
```

```tsx
import { effect, Text, View, type ViewRef } from "nsh";
import { announce, screenReaderEnabled, setAccessibilityFocus } from "nsh";

function Saved() {
  let note!: ViewRef;
  const save = () => {
    announce("Saved");
    setAccessibilityFocus(note);
  };
  // Runs again when the setting changes, until the component goes.
  effect(() => console.log("screen reader", screenReaderEnabled()));
  return (
    <View style={{ gap: 8 }}>
      <Text onPress={save} role="button">Save</Text>
      <Text ref={note}>Your changes are kept on this device.</Text>
    </View>
  );
}
```

## Types

`nsh` also exports the types of the reactive API and of the host elements. The most used ones:

| Type | What it is |
|---|---|
| `Accessor<T>` | A readable value: `() => T` |
| `Signal<T>` | An `Accessor<T>` with `set` and `update` |
| `SignalOptions<T>` | Options of `signal` and `computed` (`equals`) |
| `Context<T>` | What `context` returns |
| `Component<P>` | `(props: P) => JSX.Element` |
| `JSX` | The JSX namespace (`JSX.Element`) |
| `ViewRef`, `InputRef`, `ScrollRef`, `ListRef`, `WebViewRef`, `VideoRef`, `NativeComponentRef` | What a `ref` receives, each element's own type (`ViewRef` and the types over it): focus, scroll and other commands. `ViewRef` is also what an element is (`JSX.Element`). See [ref methods](https://nsh.dev/versions/main/elements.md#ref-methods) |
| `ViewProps`, `TextProps`, `ImageProps`, `ScrollProps`, `CommonProps`, `TouchProps` | Props of host elements |
| `ViewStyle`, `TextStyle`, `InputStyle`, `ImageStyle`, `LayoutStyle`, `StyleProp<T>` | Style objects; see the [style reference](https://nsh.dev/versions/main/modules/style-reference.md) |
| `ColorValue`, `DimensionValue`, `LengthValue`, `TransformStep` | Values inside styles |
| `GestureResponderEvent`, `MouseEvent`, `MouseButton`, `ContextMenuEvent`, `PressEvent`, `ScrollEvent`, `PanEvent`, `TouchPoint` | Event payloads |
| `Point`, `Size`, `Bounds`, `Edges`, `Modifiers` | The shapes payloads and props are made of, with GPUI's fields (`nsh_core::geometry`) |
| `PixelSize` | An image's or a video's own size in pixels (`onLoad`, `Image.getSize`, the clipboard's and the picker's images), where `Size` is points |
| `ImageAsset` | What importing an image file gives (`{ url, size: Size, scales? }`; `scales` lists its [pixel-density variants](https://nsh.dev/versions/main/docs/images-and-assets.md#pixel-densities)) |
| `OS` | `"ios" \| "android" \| "macos" \| "windows" \| "linux" \| "web"` |
| `AccessibilityRole`, `AccessibilityState` | Accessibility props |

```tsx
import { type GestureResponderEvent, type InputRef, signal } from "nsh";

let field: InputRef | undefined;
const onPress = (e: GestureResponderEvent) => field?.focus();
```

`StyleProp<T>` accepts one style or a list merged left to right, skipping falsy entries:

```tsx
<View style={[styles.card, selected() && styles.selected]} />
```

Source: https://nsh.dev/versions/main/modules/nsh

---

# List

`nsh` exports `List`: a virtualized list on a native scroll view. Only the rows near the viewport exist, and their cells are reused as you scroll. Which rows exist, where they are, columns, sticky headers and viewability are all computed natively, so scrolling a list of ten thousand items runs no JS except the row bindings that change when a cell is reused.

```ts
import { List, type ListProps, type ViewToken, type ViewabilityConfig } from "nsh";
```

See [Lists](https://nsh.dev/versions/main/docs/lists.md) for the guide and [`<List>`](https://nsh.dev/versions/main/elements/list.md) for the element's props.

## List

```ts
function List<T>(props: ListProps<T>): JSX.Element;
```

```tsx
import { List, mount, Text, View } from "nsh";

const contacts = Array.from({ length: 1000 }, (_, i) => ({ id: String(i), name: `Contact ${i}` }));

function App() {
  return (
    <List each={contacts} estimatedItemSize={48} style={{ flex: 1 }}>
      {(item, index) => (
        <View style={{ height: 48, paddingHorizontal: 16, justifyContent: "center", backgroundColor: index() % 2 ? "#f8fafc" : "#fff" }}>
          <Text>{item().name}</Text>
        </View>
      )}
    </List>
  );
}

mount(App);
```

### Rows are recycled

`children` is a function that renders **one cell**. It runs once per cell, not once per item: when a cell scrolls out of view it is reused for another item, and `item()` and `index()` (both accessors) change. Read them inside JSX expressions (`{item().name}`) so the cell updates when it is reused.

> [!WARNING]
> Do not keep per-item state in signals created inside the row function: the cell is reused for other items and the signal would follow the cell, not the item. Keep it in your data, keyed by id (a signal holding a `Set` of selected ids, for example).

## Props

`ListProps<T>` combines the list's own props with the scrolling props shared with `<Scroll>` and the props every
element takes, which go to the list's scroll view.

### Data and rendering

| Prop | Type | Default | Description |
|---|---|---|---|
| `each` | `readonly T[]` | (required) | The items. Pass a signal's value (`each={items()}`) to follow changes; inserting items above the visible rows keeps those rows in place. |
| `children` | `(item: () => T, index: () => number) => JSX.Element` | (required) | Renders one row (see above). |
| `estimatedItemSize` | `number` | `50` | The size of rows not measured yet, in points, along the list's axis. Close estimates make the scroll indicator and `scrollToIndex` more accurate. |
| `numColumns` | `number` | `1` | Items per row (vertical lists): a grid. |
| `horizontal` | `boolean` | `false` | Scrolls sideways. |
| `inverted` | `boolean` | `false` | Lays out from the end, item 0 last (chat style); starts scrolled to the end and keeps its distance from the end as content changes. |
| `stickyHeaderIndices` | `number[]` | | Items that stick to the start while scrolled past (one column, not inverted). |
| `header` | `ListSlot` | | Rendered before the items. |
| `footer` | `ListSlot` | | Rendered after the items. |
| `empty` | `ListSlot` | | Shown instead of the items while `each` is empty. |
| `separator` | `ListSlot` | | Rendered between items (one column). |
| `keyExtractor` | `(item: T, index: number) => string` | `item.key`, `item.id`, or the index | The key of an item in viewability tokens. |
| `initialScrollIndex` | `number` | | Scrolls to this item before the first frame. |
| `contentStyle` | `ListContentStyle` | | Padding and gaps of the content: `padding`, `paddingHorizontal`, `paddingVertical`, `paddingTop`, `paddingRight`, `paddingBottom`, `paddingLeft`, `gap`, `rowGap`, `columnGap` (numbers). |
| `contentClass` | `string` | | Padding and gaps of the content as classes (`p-*`, `gap-*`); `contentStyle` wins over them. |
| `style` | `StyleProp<ViewStyle>` | | The list's own style (give it a size: `flex: 1` or a height). |
| `testID` | `string` | | The id UI tests find the list's scroll view by (`nsh test`'s `id:`, XCUITest, UI Automator). |
| `ref` | `ListRef \| ((node: ListRef) => void)` | | See [ref methods](#ref-methods). |

`ListSlot` is a component (`Header`) or an element (`<Header />`).

### Loading, refreshing and viewability

| Prop | Type | Default | Description |
|---|---|---|---|
| `onLoadMore` | `() => void` | | Called when the end comes within `loadMoreThreshold` viewports: load more. |
| `loadMoreThreshold` | `number` | `1` | How close to the end (in viewport lengths) `onLoadMore` fires. |
| `onLoadMoreAtStart` | `() => void` | | Called when the start comes within `loadMoreAtStartThreshold` viewports after the user or a scroll command moved the list: load what comes before the first item. |
| `loadMoreAtStartThreshold` | `number` | `1` | How close to the start (in viewport lengths) `onLoadMoreAtStart` fires. |
| `refreshing` | `boolean` | | The pull-to-refresh spinner shows. |
| `onRefresh` | `() => void` | | Enables pull to refresh; set `refreshing` while you load. |
| `refreshIndicator` | `{ height: number }` | | The app draws its own pull-to-refresh indicator, `height` tall, in place of the spinner. |
| `pullValue` | `AnimatedValue` | | Fed with how far the list is pulled past its top, for that indicator. |
| `onViewableItemsChange` | `(info: { viewableItems: ViewToken<T>[]; changed: ViewToken<T>[] }) => void` | | Items that became or stopped being viewable. |
| `viewabilityConfig` | `ViewabilityConfig` | | When an item counts as viewable. |

```ts
interface ViewToken<T> {
  item: T;
  key: string;
  index: number;
  isViewable: boolean;
}

interface ViewabilityConfig {
  /** How much of the viewport an item must cover to count as viewable, from 0 to 1. */
  viewAreaCoverageThreshold?: number;
  /** How much of an item must be visible, from 0 to 1. Without either threshold, any visible pixel counts. */
  itemVisibleThreshold?: number;
  /** Milliseconds items must stay viewable before they are reported. */
  minimumViewTime?: number;
}
```

### Scrolling

| Prop | Type | Default | Description |
|---|---|---|---|
| `scrollbar` | `boolean \| ScrollbarTheme` | `true` | The scroll indicator shows: the platform's, or the app's [built-in bar](https://nsh.dev/versions/main/elements/scrollbar.md#built-in-bars); an object is a theme of the view's own. |
| `scrollable` | `boolean` | `true` | The user can scroll it. |
| `bounces` | `boolean` | `true` | Overscroll past the edges. |
| `pagingEnabled` | `boolean` | `false` | Stops at multiples of the viewport. |
| `snapToInterval` | `number` | `0` | Stops at multiples of this length (0: off). |
| `snapToOffsets` | `number[]` | | Stops at these offsets. |
| `snapToAlignment` | `"start" \| "center" \| "end"` | `"start"` | Which point of an item aligns with the viewport with `snapToInterval`. |
| `disableIntervalMomentum` | `boolean` | `false` | A fling moves one snap point at most. |
| `decelerationRate` | `"normal" \| "fast" \| number` | platform | How fast a fling slows down (`0.998` / `0.99`, or the velocity kept per millisecond). |
| `contentInset` | `Partial<Edges>` | | Room around the content. |
| `contentOffset` | `{ x?, y? }` | | Where it starts. |
| `keyboardShouldPersistTaps` | `"never" \| "always" \| "handled" \| boolean` | `"never"` | Whether a tap dismisses the keyboard (`"never"`: the tap only dismisses it). |
| `keyboardDismissMode` | `"none" \| "on-drag" \| "interactive"` | `"none"` | Whether dragging dismisses the keyboard. |
| `scrollEventThrottle` | `number` | | Minimum milliseconds between `onScroll` events (at most one per frame anyway). |
| `scrollValue` | `AnimatedValue` | | A [animated value](https://nsh.dev/versions/main/modules/nsh.md#animation) fed with the scroll offset (main axis) on the UI thread, for scroll-linked effects. |

### Scroll events

| Event | Payload | When |
|---|---|---|
| `onScroll` | `ScrollEvent`: `{ offset, contentSize, size, zoomScale }` | While scrolling. |
| `onScrollDragStart` | `{ offset }` | A drag starts. |
| `onScrollDragEnd` | `{ offset }` | The finger lifts. |
| `onMomentumStart` | `{ offset }` | A glide starts after the drag. |
| `onMomentumEnd` | `{ offset }` | The glide ends (also when a new drag catches it). |
| `onScrollEnd` | `{ offset }` | Scrolling came to rest. |

Lists also take the props every element takes ([common props](https://nsh.dev/versions/main/elements.md)).

## Ref methods

A list's `ref` receives a `ListRef`, with these methods besides `ViewRef`'s:

| Method | Description |
|---|---|
| `scrollToIndex({ index, animated?, viewPosition?, viewOffset? })` | Scrolls item `index` into view. `viewPosition` places it: `0` at the start of the viewport (default), `0.5` in the middle, `1` at the end; `viewOffset` shifts it further. Resolved natively with the measured (or estimated) row sizes. |
| `scrollToOffset({ offset, animated? })` | Scrolls to a content offset along the list's axis. |
| `scrollToEnd({ animated? })` | Scrolls to the end of the content (the start of an inverted list). |
| `scrollTo({ x?, y?, animated? })` | Scrolls to an offset. |

```tsx
import { List, type ListRef, Text, View } from "nsh";

let list!: ListRef;

<View style={{ flex: 1 }}>
  <Text onPress={() => list.scrollToIndex({ index: 60, viewPosition: 0.5 })}>Jump to 60</Text>
  <List ref={list} each={items} numColumns={3} estimatedItemSize={90} style={{ flex: 1 }}
        contentStyle={{ padding: 12, gap: 8 }}>
    {(item) => <View style={{ height: 90, backgroundColor: "#e0e7ff" }}><Text>{item().title}</Text></View>}
  </List>
</View>
```

## Examples

A chat: newest message at the bottom, older messages loaded as you scroll up.

```tsx
<List
  each={messages()}
  inverted
  estimatedItemSize={44}
  style={{ flex: 1 }}
  contentStyle={{ padding: 12, gap: 6 }}
  keyboardDismissMode="interactive"
  onLoadMore={loadOlder}
  loadMoreThreshold={0.5}
>
  {(m) => (
    <View style={{ alignSelf: m().mine ? "flex-end" : "flex-start", maxWidth: "75%", padding: 10, borderRadius: 14, backgroundColor: m().mine ? "#6366f1" : "#e2e8f0" }}>
      <Text style={{ color: m().mine ? "#fff" : "#0f172a" }}>{m().text}</Text>
    </View>
  )}
</List>
```

Pull to refresh:

```tsx
const refreshing = signal(false);
const refresh = async () => {
  refreshing.set(true);
  items.set(await load());
  refreshing.set(false);
};

<List each={items()} refreshing={refreshing()} onRefresh={refresh} style={{ flex: 1 }}>
  {(item) => <Text style={{ padding: 16 }}>{item().title}</Text>}
</List>
```

## ListItemsProps

```ts
type ListItemsProps<T> = Pick<ListProps<T>,
  "each" | "children" | "keyExtractor" | "stickyHeaderIndices" | "initialScrollIndex"
  | "onViewableItemsChange" | "viewabilityConfig" | "refreshing" | "onRefresh"
  | "onLoadMore" | "loadMoreThreshold"
  | "header" | "footer" | "empty">;
```

The data-and-rows half of `ListProps`: what you pass to a component of your own that lays out a list itself, such as a settings list that wraps `List` with its own padding and dividers.

Source: https://nsh.dev/versions/main/modules/nsh-list

---

# Image

`nsh` exports `Image`, the [`<Image>`](https://nsh.dev/versions/main/elements/image.md) element that shows images. The same `Image` also asks the native image loader about images without showing them: their size, and loading them before they are shown.

```ts
import { Image, type PixelSize } from "nsh";
```

`Image` is a component carrying two functions: `<Image src=…>` renders the native image view (the compiler makes it in place, as it does `<View>`), and `Image.getSize` / `Image.prefetch` are called on it directly.

```ts
const Image: ((props: ImageProps) => JSX.Element) & {
  getSize(src: string | ImageAsset): Promise<PixelSize>;
  prefetch(src: string | ImageAsset): Promise<void>;
};
```

See [Images and assets](https://nsh.dev/versions/main/docs/images-and-assets.md) for the guide.

## Image.getSize

```ts
getSize(src: string | ImageAsset): Promise<PixelSize>;

interface PixelSize {
  width: number;   // pixels (an SVG's: points)
  height: number;
}
```

Loads the image and resolves with its size in pixels (of the source image, not a downsampled copy; an SVG's intrinsic size in points, [on the web as the browser measures it](https://nsh.dev/versions/main/docs/images-and-assets.md#svg-images)). An imported image with [pixel-density variants](https://nsh.dev/versions/main/docs/images-and-assets.md#pixel-densities) loads the variant the views load on this screen and resolves with the imported file's size, whichever variant it loaded (an `<Image>` showing it reports the loaded variant's pixels in `onLoad`). The loaded bytes stay in memory, so the `<Image>` that shows it next does not download it again. The promise rejects if the image cannot be loaded.

```tsx
import { Image, signal } from "nsh";

const url = "https://picsum.photos/seed/nsh/1200/800";
const ratio = signal(1);

Image.getSize(url).then(({ width, height }) => ratio.set(width / height));

<Image src={url} style={{ width: "100%", aspectRatio: ratio() }} />;
```

## Image.prefetch

```ts
prefetch(src: string | ImageAsset): Promise<void>;
```

Loads an image ahead of showing it. Resolves once its bytes are in memory, and rejects with the error when the image cannot be loaded. For an imported image with pixel-density variants, it loads the variant the views load on this screen. Use it for the next page of a gallery or the image behind a tap.

```ts
const next = photos.slice(index + 1, index + 4);
next.forEach((p) => Image.prefetch(p.url).catch(() => {})); // the <Image> reports its own error later
```

## Related

- [`<Image>`](https://nsh.dev/versions/main/elements/image.md): `src`, `placeholder`, the `objectFit` style, `onLoad`, `onProgress`, `onError` and the other props.
- Importing an image file (`import logo from "./logo.png"`) gives an `ImageAsset` (`{ url, size, scales? }`, sized in points) that `<Image src>` and canvas `drawImage` accept.

> [!NOTE]
> When your app declares `capabilities` in `nsh.json`, `getSize` and `prefetch` of remote URLs must be allowed under `network`, like `fetch`. A URL outside them is never requested: the promise rejects with an `Error` whose `code` is `"ERR_ACCESS_DENIED"`, `permission` `"network"` and `resource` the URL. See [Sandbox and capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md).

> [!NOTE]
> A terminal shows text, so in a terminal app `getSize` and `prefetch` settle at once: the promise rejects with an `Error` whose `code` is `"ERR_FEATURE_UNAVAILABLE_ON_PLATFORM"`.

Source: https://nsh.dev/versions/main/modules/nsh-image

---

# Canvas

`Canvas` draws with an HTML Canvas 2D–style context. Your `draw` function **records** the drawing; the platform replays it natively (Core Graphics on iOS, `android.graphics.Canvas` on Android) at the screen's resolution. Numbers and colors in a drawing may be [animated values](https://nsh.dev/versions/main/modules/nsh.md#animation): when they animate, the platform redraws on its own, without running `draw` again.

```ts
import { Canvas, CanvasGradient, CanvasRenderingContext2D, Path2D } from "nsh";
```

See [Canvas](https://nsh.dev/versions/main/docs/canvas.md) for the guide and [`<Canvas>`](https://nsh.dev/versions/main/elements/canvas.md) for its props.

## Canvas

```ts
function Canvas(props: CanvasProps): JSX.Element;

interface CanvasProps extends ViewProps {
  draw: (cx: CanvasRenderingContext2D, size: CanvasSize) => void;
}

interface CanvasSize {
  width: number;   // points
  height: number;
}
```

A view drawn with a 2D context. It takes every [view prop](https://nsh.dev/versions/main/elements/view.md) (style, classes, touch handlers, accessibility, `ref`), plus:

| Prop | Type | Description |
|---|---|---|
| `draw` | `(cx, { width, height }) => void` | Draws the canvas. Runs once the size is known, again when the signals it reads change, and again when the canvas resizes. Animated values passed as numbers or colors animate without running it. |

Give the canvas a size through its style (`width` / `height`, `flex: 1`, `aspectRatio`, ...). Coordinates are in points, the origin at the top left.

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

function App() {
  const values = signal([12, 30, 22, 48, 36, 60, 52, 75]);
  return (
    <View style={{ flex: 1, padding: 24 }}>
      <Canvas
        style={{ height: 160 }}
        draw={(cx, { width, height }) => {
          const v = values();
          const step = width / (v.length - 1);
          cx.strokeStyle = "#6366f1";
          cx.lineWidth = 3;
          cx.lineJoin = "round";
          cx.beginPath();
          v.forEach((n, i) => (i ? cx.lineTo(i * step, height - n * 2) : cx.moveTo(0, height - n * 2)));
          cx.stroke();
        }}
      />
      <Text onPress={() => values.update((v) => [...v.slice(1), Math.random() * 80])}>Next</Text>
    </View>
  );
}

mount(App);
```

## Animating without redrawing

Any argument typed `CanvasNumber` and any paint (`fillStyle`, `strokeStyle`) accepts a `AnimatedNode`. The canvas then reads the node while it draws, and redraws natively on every frame of its animation:

```tsx
import { createAnimatedValue, Easing } from "nsh";
import { Canvas } from "nsh";

const progress = createAnimatedValue(0);

<Canvas
  style={{ width: 120, height: 120 }}
  draw={(cx, { width }) => {
    const c = width / 2;
    cx.lineWidth = 12;
    cx.lineCap = "round";
    cx.strokeStyle = "#6366f1";
    cx.beginPath();
    // The end angle is an animated node: animating `progress` redraws natively.
    cx.arc(c, c, c - 10, -Math.PI / 2, progress.mul(Math.PI * 2).sub(Math.PI / 2));
    cx.stroke();
  }}
/>;

progress.timing(0.75, { duration: 900, easing: Easing.inOut(Easing.cubic) });
```

```ts
type CanvasNumber = number | AnimatedNode;
type CanvasPaint = string | CanvasGradient | AnimatedNode;
```

## CanvasRenderingContext2D

The context `draw` receives. Calls only record operations; the platform draws them after `draw` returns.

### State and transforms

```ts
readonly canvas: { readonly width: number; readonly height: number };
save(): void;
restore(): void;
translate(x: CanvasNumber, y: CanvasNumber): void;
scale(x: CanvasNumber, y: CanvasNumber): void;
rotate(angle: CanvasNumber): void;
transform(a: CanvasNumber, b: CanvasNumber, c: CanvasNumber, d: CanvasNumber, e: CanvasNumber, f: CanvasNumber): void;
setTransform(a: CanvasNumber, b: CanvasNumber, c: CanvasNumber, d: CanvasNumber, e: CanvasNumber, f: CanvasNumber): void;
resetTransform(): void;
```

| Member | Description |
|---|---|
| `canvas` | The canvas's size in points. |
| `save()` / `restore()` | Pushes / pops the drawing state (transform, clip, styles). |
| `translate(x, y)` | Moves the origin. |
| `scale(x, y)` | Scales the axes. |
| `rotate(angle)` | Rotates the axes; radians, clockwise. |
| `transform(a, b, c, d, e, f)` | Multiplies the transform by the matrix `[a c e; b d f]`. |
| `setTransform(a, b, c, d, e, f)` | Replaces the transform. |
| `resetTransform()` | Back to the identity. |

### Properties

| Property | Type | Description |
|---|---|---|
| `fillStyle` | `CanvasPaint` | Color, gradient or native color node used by `fill`, `fillRect`, `fillText`. |
| `strokeStyle` | `CanvasPaint` | The same for strokes. |
| `lineWidth` | `CanvasNumber` | Stroke width in points. |
| `lineCap` | `"butt" \| "round" \| "square"` | How strokes end. |
| `lineJoin` | `"miter" \| "round" \| "bevel"` | How stroke segments join. |
| `miterLimit` | `number` | Miter joins longer than this (in line widths) are beveled. |
| `lineDashOffset` | `CanvasNumber` | Where the dash pattern starts. |
| `globalAlpha` | `CanvasNumber` | Opacity of what is drawn next, 0..1. |
| `globalCompositeOperation` | `string` | How what is drawn next combines with the canvas (`"source-over"`, `"multiply"`, ...). |
| `shadowColor` | `string` | The color of shadows (transparent: none). |
| `shadowBlur` | `number` | Shadow blur in points. |
| `shadowOffsetX`, `shadowOffsetY` | `number` | Shadow offset in points. |
| `font` | `string` | CSS `font` shorthand, e.g. `"600 14px Inter"` (sizes in `px`, `pt` or `rem`). |
| `textAlign` | `"start" \| "end" \| "left" \| "right" \| "center"` | Where text sits horizontally relative to its x. |
| `textBaseline` | `"alphabetic" \| "top" \| "hanging" \| "middle" \| "ideographic" \| "bottom"` | Where text sits vertically relative to its y. |

Dashes: `setLineDash(segments: number[])` and `getLineDash(): number[]`.

### Paths

The context has a current path, built with the same methods as [`Path2D`](#path2d):

```ts
beginPath(): void;
moveTo(x, y): void;
lineTo(x, y): void;
quadraticCurveTo(cpx, cpy, x, y): void;
bezierCurveTo(cp1x, cp1y, cp2x, cp2y, x, y): void;
arc(x, y, radius, startAngle, endAngle, counterclockwise?: boolean): void;
arcTo(x1, y1, x2, y2, radius): void;
ellipse(x, y, radiusX, radiusY, rotation, startAngle, endAngle, counterclockwise?: boolean): void;
rect(x, y, w, h): void;
roundRect(x, y, w, h, radii?: CanvasNumber | CanvasNumber[]): void;
closePath(): void;
```

All coordinates are `CanvasNumber`s. Angles are in radians, clockwise from the x axis. `roundRect`'s `radii` is one radius or 2–4 as in CSS `border-radius` (top left first).

### Drawing

```ts
fill(path?: Path2D | "nonzero" | "evenodd", rule?: "nonzero" | "evenodd"): void;
stroke(path?: Path2D): void;
clip(path?: Path2D | "nonzero" | "evenodd", rule?: "nonzero" | "evenodd"): void;
fillRect(x, y, w, h): void;
strokeRect(x, y, w, h): void;
clearRect(x, y, w, h): void;
```

| Method | Description |
|---|---|
| `fill(path?, rule?)` | Fills the current path (or `path`) with `fillStyle`, by the nonzero (default) or even-odd rule. |
| `stroke(path?)` | Strokes the current path (or `path`) with `strokeStyle`. |
| `clip(path?, rule?)` | Restricts what is drawn next to the path. |
| `fillRect`, `strokeRect` | A rectangle, without touching the current path. |
| `clearRect` | Makes a rectangle transparent. |

### Text

```ts
fillText(text: string, x: CanvasNumber, y: CanvasNumber, maxWidth?: number): void;
strokeText(text: string, x: CanvasNumber, y: CanvasNumber, maxWidth?: number): void;
measureText(text: string): TextMetrics; // { width: number }
```

`measureText` is synchronous: it measures with the platform's text engine and the current `font`. Only `width` is reported.

```ts
cx.font = "11px system-ui";
const label = "100";
cx.fillText(label, 40 - cx.measureText(label).width, 20);
```

### Gradients

```ts
createLinearGradient(x0: number, y0: number, x1: number, y1: number): CanvasGradient;
createRadialGradient(x0: number, y0: number, r0: number, x1: number, y1: number, r1: number): CanvasGradient;
createConicGradient(startAngle: number, x: number, y: number): CanvasGradient;

class CanvasGradient {
  addColorStop(offset: number, color: string): void; // offset 0..1, any CSS color
}
```

```ts
const g = cx.createLinearGradient(0, 0, 0, height);
g.addColorStop(0, "rgba(99, 102, 241, 0.4)");
g.addColorStop(1, "rgba(99, 102, 241, 0)");
cx.fillStyle = g;
cx.fillRect(0, 0, width, height);
```

### Images

```ts
drawImage(image: string | ImageAsset, ...args: CanvasNumber[]): void;
```

Draws an image given as a URL or an imported asset (`import logo from "./logo.png"`). It is loaded natively; the canvas draws again once it has loaded. An imported asset draws the imported file itself; import the `@3x` file to draw sharp on every screen. Three forms, as in HTML:

- `drawImage(image, dx, dy)`: at its natural size.
- `drawImage(image, dx, dy, dw, dh)`: scaled into a rectangle.
- `drawImage(image, sx, sy, sw, sh, dx, dy, dw, dh)`: part of it (source in image pixels).

## Path2D

```ts
class Path2D {
  constructor(path?: Path2D | string);
  addPath(path: Path2D): void;
  // and every path method: moveTo, lineTo, quadraticCurveTo, bezierCurveTo,
  // arc, arcTo, ellipse, rect, roundRect, closePath
}
```

A reusable path to fill, stroke or clip. The constructor copies another `Path2D` or parses SVG path data natively:

```ts
const heart = new Path2D("M12 21s-7-4.5-9.5-9A5.5 5.5 0 0 1 12 6a5.5 5.5 0 0 1 9.5 6c-2.5 4.5-9.5 9-9.5 9z");
cx.save();
cx.scale(4, 4);
cx.fillStyle = "#ef4444";
cx.fill(heart);
cx.restore();
```

## Not supported

Pixel access (`getImageData`, `putImageData`), `filter`, `isPointInPath` and SVG images are not available. An invalid color or font drops that one operation, as in HTML Canvas.

Source: https://nsh.dev/versions/main/modules/nsh-canvas

---

# WebView

`nsh` exports `WebView`: a web page shown by the platform's own browser engine (`WKWebView` on iOS and Mac Catalyst, `android.webkit.WebView` on Android). It is a native view laid out like any other, so it scrolls, clips and overlaps other views correctly.

```ts
import { WebView, type WebViewNavigation, type WebViewProps } from "nsh";
```

See [Web view and video](https://nsh.dev/versions/main/docs/web-view-and-video.md) for the guide and [`<WebView>`](https://nsh.dev/versions/main/elements/web-view.md) for its props.

## WebView

```ts
const WebView: (props: WebViewProps) => JSX.Element;

interface WebViewProps extends Omit<ViewProps, "children" | "ios" | "desktop">, WebViewHostProps {
  ios?: IOSWebViewHostProps;
  desktop?: DesktopWebViewHostProps;
}
```

```tsx
import { mount, signal, Text, View, WebView, type WebViewNavigation, type WebViewRef } from "nsh";

function Browser() {
  const nav = signal<WebViewNavigation | null>(null);
  let web!: WebViewRef;
  return (
    <View style={{ flex: 1 }}>
      <View style={{ flexDirection: "row", gap: 16, padding: 12 }}>
        <Text onPress={() => web.goBack()} style={{ opacity: nav()?.canGoBack ? 1 : 0.4 }}>Back</Text>
        <Text onPress={() => web.reload()}>Reload</Text>
        <Text style={{ numberOfLines: 1, flex: 1 }}>{nav()?.title ?? ""}</Text>
      </View>
      <WebView ref={web} src="https://example.com" style={{ flex: 1 }} onNavigationStateChange={(n) => nav.set(n)} />
    </View>
  );
}

mount(Browser);
```

## Props

`WebView` takes the [view props](https://nsh.dev/versions/main/elements/view.md) (style, classes, layout, accessibility, `ref`; no children), plus:

| Prop | Type | Default | Description |
|---|---|---|---|
| `src` | `string` | | The URL of the page to show. |
| `html` | `string` | | Inline HTML, shown instead of `src`. |
| `baseUrl` | `string` | | What `html`'s relative links resolve against. |
| `injectedJavaScript` | `string` | | Runs after each page loads. |
| `injectedJavaScriptBeforeContentLoaded` | `string` | | Runs before each page's own scripts. |
| `userAgent` | `string` | platform's | The user agent string. |
| `scrollable` | `boolean` | `true` | The user can scroll the page. |
| `javaScriptEnabled` | `boolean` | `true` | Pages run scripts. |
| `ios` | `{ allowsBackForwardNavigationGestures?: boolean }` | | iOS only: swipe from the edges to go back and forward. |
| `desktop` | `{ allowsBackForwardNavigationGestures?: boolean }` | | macOS: two-finger trackpad swipes go back and forward; Windows: touchscreen swipes; Linux: touchpad swipes. |

## Events

| Event | Payload | When |
|---|---|---|
| `onLoadStart` | `WebViewNavigation` | A page starts loading. |
| `onLoad` | `WebViewNavigation` | A page finished loading. |
| `onError` | `{ message: string }` | A page failed to load. |
| `onNavigationStateChange` | `WebViewNavigation` | The URL, title, loading state or history changed. |
| `onMessage` | `{ data: string }` | The page called `window.nsh.postMessage(data)`. |

```ts
interface WebViewNavigation {
  url: string;
  title: string;
  loading: boolean;
  canGoBack: boolean;
  canGoForward: boolean;
}
```

## Ref methods

| Method | Description |
|---|---|
| `reload()` | Reloads the page. |
| `goBack()` | Goes back in its history. |
| `goForward()` | Goes forward in its history. |
| `stopLoading()` | Stops loading. |
| `injectJavaScript(script)` | Runs `script` in the page. |
| `postMessage(data)` | Sends `data` (a string) to the page: a `message` event on `window`, with `data` as `event.data`. |

## Talking to the page

The page sends strings to the app with `window.nsh.postMessage(…)`; the app sends strings to the page with `ref.postMessage(…)`. Send JSON for structured data.

```tsx
const page = `<!doctype html><html><head><meta name="viewport" content="width=device-width"></head>
<body>
  <button onclick="window.nsh.postMessage('hello from the page')">Post to the app</button>
  <p id="got"></p>
  <script>
    window.addEventListener('message', (e) => { document.getElementById('got').textContent = e.data; });
  </script>
</body></html>`;

let web!: WebViewRef;
const message = signal("");

<WebView ref={web} html={page} style={{ height: 200 }} onMessage={(e) => message.set(e.data)} />
<Text onPress={() => web.postMessage("hi from the app")}>Post to the page</Text>
```

## Capabilities

When your app declares `capabilities` in `nsh.json`, a web view may only show and navigate to the hosts listed under `webview`; other top-level navigations are refused natively. An app without a `capabilities` key may show anything. See [Sandbox and capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md).

```json
{
  "capabilities": {
    "webview": { "hosts": ["example.com", "*.example.com"] }
  }
}
```

Source: https://nsh.dev/versions/main/modules/nsh-webview

---

# Video

`nsh` exports `Video`: a video player built on the platform's player (`AVPlayer` on iOS and Mac Catalyst, `MediaPlayer` on Android). Playback is controlled with props, so pausing is a signal away.

```ts
import { Video, type VideoProps } from "nsh";
```

See [Web view and video](https://nsh.dev/versions/main/docs/web-view-and-video.md) for the guide and [`<Video>`](https://nsh.dev/versions/main/elements/video.md) for its props.

## Video

```ts
const Video: (props: VideoProps) => JSX.Element;

interface VideoProps extends Omit<ViewProps, "children">, VideoHostProps {
  src: string;
}
```

```tsx
import { mount, signal, Text, Video, type VideoRef, View } from "nsh";

function Player() {
  const paused = signal(true);
  const time = signal("");
  let video!: VideoRef;
  return (
    <View style={{ flex: 1, padding: 16, gap: 12 }}>
      <Video
        ref={video}
        src="https://example.com/clip.mp4"
        paused={paused()}
        muted
        repeat
        class="object-cover"
        style={{ height: 220, borderRadius: 8, overflow: "hidden", backgroundColor: "#000" }}
        onProgress={(e) => time.set(`${e.currentTime.toFixed(1)} / ${e.duration.toFixed(1)} s`)}
      />
      <View style={{ flexDirection: "row", gap: 16 }}>
        <Text onPress={() => paused.update((p) => !p)}>{paused() ? "Play" : "Pause"}</Text>
        <Text onPress={() => video.seek(0)}>Restart</Text>
        <Text>{time()}</Text>
      </View>
    </View>
  );
}

mount(Player);
```

## Props

`Video` takes the [view props](https://nsh.dev/versions/main/elements/view.md) (style, classes, layout, accessibility, `ref`; no children), plus:

| Prop | Type | Default | Description |
|---|---|---|---|
| `src` | `string` | (required) | The video's URL. |
| `paused` | `boolean` | `false` | Playback is paused. |
| `muted` | `boolean` | `false` | No sound. |
| `volume` | `number` | `1` | 0..1. |
| `rate` | `number` | `1` | The playback speed. |
| `repeat` | `boolean` | `false` | Plays again from the start at the end. |
| `controls` | `boolean` | `false` | Shows the platform's playback controls. |
| `objectFit` (style), `object-*` classes | `"cover" \| "contain" \| "fill" \| "none" \| "scale-down"` | `"contain"` | How the video fits its box, as CSS's `object-fit` (`class="object-cover"`). |
| `progressUpdateInterval` | `number` | `250` | Milliseconds between `onProgress` events. |
| `audioSession` | `"default" \| "playback" \| "mixWithOthers"` | `"default"` | What the sound does to the rest of the device's audio: see [Sound and other apps](#sound-and-other-apps). |

### Sound and other apps

A video's sound follows the app's audio settings, which by default are the platform's for video: on iOS the device's silent mode silences it. An app that plays speech, as an audiobook or a language course does, sets `audioSession`:

| `audioSession` | In silent mode | Other apps' audio while it plays |
|---|---|---|
| `"default"` | the app's audio settings decide | the app's audio settings decide |
| `"playback"` | sound plays | pauses, and plays again once the video pauses, ends or goes |
| `"mixWithOthers"` | sound plays | keeps playing |

The setting takes effect while the video plays. On iOS, the first such video to play sets `AVAudioSession` to the `playback` category in the `spokenAudio` mode (mixing with other apps' audio for `"mixWithOthers"`), and once none plays the session returns to what it was and the apps it paused may play again; `"default"` leaves the session as the app, or the app embedding NSH, set it. On Android the player's sound is marked as speech, and a `"playback"` video holds audio focus while it plays: it pauses when another app takes the focus (a call, a navigation prompt) and plays on when it comes back. Changing `audioSession` on Android opens the source again. The desktops and the web play the sound as they play any video.

```tsx
<Video src="asset:/greeting.m4a" audioSession="playback" />
```

## Events

| Event | Payload | When |
|---|---|---|
| `onLoadStart` | | The video starts loading. |
| `onLoad` | `{ duration: number; size: PixelSize }` | It is ready to play: its length in seconds and its size in pixels. |
| `onProgress` | `{ currentTime: number; duration: number }` | While playing, every `progressUpdateInterval` ms. Seconds. |
| `onBuffer` | `{ isBuffering: boolean }` | Playback waits for data, or resumes. |
| `onEnd` | | Playback reached the end. |
| `onError` | `{ message: string }` | The video could not be loaded or played. |

## Ref methods

| Method | Description |
|---|---|
| `seek(seconds)` | Jumps to `seconds`. |

```ts
const aspect = signal(16 / 9);

<Video src={url} onLoad={(e) => aspect.set(e.size.width / e.size.height)} style={{ width: "100%", aspectRatio: aspect() }} />;
```

## Capabilities

When your app declares `capabilities` in `nsh.json`, remote video sources must be allowed under `network`, like `fetch`; a refused source shows nothing. See [Sandbox and capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md).

Source: https://nsh.dev/versions/main/modules/nsh-video

---

# nsh/base

`nsh/base` is the base component layer of an app's UI: unstyled components that own behavior, state, focus and
accessibility, on every platform. It sits between the primitives (`nsh`, `nsh/mobile` and `nsh/desktop`) and the
app's own component library, as `gpui-base` sits between `gpui` and a styled library in GPUI Kit (see
[Modules](https://nsh.dev/versions/main/modules.md#three-layers)). It provides controls (`Button`, `Link`, `Checkbox`, `ColorPicker` with its `ColorArea`, `ColorSlider`, `ColorField`, `ColorSwatch` and `ColorEyeDropper`, `NumberInput`, `Radio` in a `RadioGroup`, `Slider`, `Switch`, `Tab` in `Tabs`, `Toggle` in a `ToggleGroup`, `Select`, `Combobox`, `Calendar`, `TimeField`, `DatePicker`), command palettes (`Command`), bars of controls (`Toolbar` with its `ToolbarGroup` and `ToolbarSeparator`), scroll bars of the app's own look (`Scrollbar`), regions that expand and collapse (`Collapsible`, and `Accordion` with its `AccordionItem`, `AccordionHeader`, `AccordionTrigger` and `AccordionPanel`), a progress bar (`Progress`), one-time codes (`OtpInput`), the pages of a set (`Pagination`), items that hold items (`Tree`), the parts charts are built from (`Plot` with `Line`, `Area`, `Bar`, `Rule`, `Dot`, `Cell`, `Grid`, `Pie` and `Arc`, in `nsh/base/plot`), workspaces the user arranges (`ResizablePanel`s in a
`ResizablePanelGroup`, and `DockArea`'s splits, tab groups and docks), carousels (`Carousel` and its parts), documents of Markdown or HTML (`TextView`), a code editor (`Editor`) the changes between texts (`DiffView`) and tables of rows and columns (`Table` and its parts, `DataTable`), text inputs
(`Input`), popups shown on top of everything (`Popover`, `Menu` and `ContextMenu` with their `MenuItem`,
`MenuSeparator` and `Submenu`, `Tooltip`, `Sheet`), toasts (`Toast` in a `ToastStack`, their lifecycle in a `ToastManager`), navigation (a `NavStack` of `NavPage`s driven
by the state you create with `createNavStack`, and `Dialog` for content presented over everything else) and the system's
alert dialogs (`AlertDialog`). Pages and dialogs also decide the status bar
(`statusBar`).

The base set also includes `Avatar` and `AvatarGroup`: pictures with native
image-loading state and a row that places its first `limit` avatars.

The look is the app's: what goes inside a page, a dialog or a header is your own JSX, drawn from the primitives with
styles, [Tailwind](https://nsh.dev/versions/main/docs/tailwind.md) classes and your theme, Rust components from [your own crate](https://nsh.dev/versions/main/docs/rust.md),
or a component library the community builds on `nsh/base`. Every host serves `nsh/base`; Rust apps use the same API
from the `nsh-base` crate (`nsh_base::{button, dialog, …}`).

```rust
use nsh_base::{
    MarkdownExtension, MarkdownOptions, accordion, accordion_header, accordion_item, accordion_panel, accordion_trigger,
    alert_dialog, button, carousel, carousel_content, carousel_item, carousel_next,
    carousel_pagination, carousel_pagination_item, carousel_previous, checkbox, color_area, color_field, color_picker,
    color_slider, color_swatch, dialog, diff_view, dock_area, editor, hover_card, link,
    calendar, combobox, command, date_picker, h_resizable, nav_page, nav_stack, radio, radio_group, resizable_panel, select, switch, tab, tabs, text_view, theme, time_field, toast, toast_stack, toggle, toggle_group, toolbar, toolbar_group, toolbar_separator, tree, v_resizable,
};
```

```tsx
import {
  Accordion,
  AccordionHeader,
  AccordionItem,
  AccordionPanel,
  AccordionTrigger,
  AlertDialog,
  Avatar,
  AvatarGroup,
  Button,
  Carousel,
  CarouselContent,
  CarouselItem,
  CarouselNext,
  CarouselPagination,
  CarouselPaginationItem,
  CarouselPrevious,
  Checkbox,
  Collapsible,
  ColorArea,
  ColorEyeDropper,
  ColorField,
  ColorPicker,
  ColorSlider,
  ColorSwatch,
  ContextMenu,
  createNavStack,
  DataTable,
  Dialog,
  DiffView,
  DockArea,
  Editor,
  HoverCard,
  Link,
  Menu,
  OtpInput,
  Pagination,
  Progress,
  MenuItem,
  MenuSeparator,
  NavPage,
  NavStack,
  Popover,
  Radio,
  RadioGroup,
  ResizablePanel,
  ResizablePanelGroup,
  Scrollbar,
  Select,
  Combobox,
  Command,
  Calendar,
  TimeField,
  DatePicker,
  Sheet,
  NumberInput,
  Slider,
  Submenu,
  Switch,
  Tab,
  Table,
  TableBody,
  TableCaption,
  TableCell,
  TableFooter,
  TableHead,
  TableHeader,
  TableRow,
  Tabs,
  TextView,
  Toast,
  ToastManager,
  ToastStack,
  Toggle,
  ToggleGroup,
  Toolbar,
  ToolbarGroup,
  ToolbarSeparator,
  Tree,
  Tooltip,
} from "nsh/base";
import type {
  AccordionHeaderProps,
  AccordionItemProps,
  AccordionPanelProps,
  AccordionProps,
  AccordionTriggerProps,
  AlertDialogAction,
  AlertDialogOptions,
  AlertDialogPresentation,
  AlertDialogResult,
  AlertDialogRole,
  AvatarGroupProps,
  AvatarProps,
  AvatarStatus,
  ButtonProps,
  CarouselContentProps,
  CarouselControlProps,
  CarouselItemProps,
  CarouselPaginationItemProps,
  CarouselPaginationProps,
  CarouselProps,
  CheckboxProps,
  CollapsibleProps,
  ColorAreaProps,
  ColorChannel,
  ColorFieldProps,
  ColorFormat,
  ColorPickerProps,
  ColorSliderProps,
  ColorSpace,
  ColorSwatchProps,
  DialogChangeReason,
  DataTableColumn,
  DataTableProps,
  DataTableRef,
  DataTableSelection,
  DataTableSort,
  DialogProps,
  DiffAnnotation,
  DiffFile,
  DiffHunk,
  DiffLineRange,
  DiffSeparator,
  DiffStats,
  DiffViewProps,
  DiffViewRef,
  DockAreaLayout,
  DockNode,
  DockRegion,
  EditorDecoration,
  EditorDiagnostic,
  EditorProps,
  EditorRef,
  EditorReplaceAll,
  EditorSearch,
  EditorSearchResult,
  EditorSelection,
  Edges,
  HeaderStyle,
  LinkOpenWith,
  LinkProps,
  NavPageProps,
  NavStackProps,
  NavStackState,
  OtpInputProps,
  PaginationItemState,
  PaginationProps,
  ProgressProps,
  StatusBar,
  RadioGroupProps,
  RadioProps,
  NumberInputProps,
  SelectEntry,
  SelectGroup,
  SelectItem,
  SelectProps,
  ComboboxProps,
  CommandEntry,
  CommandGroup,
  CommandItem,
  CommandProps,
  CalendarProps,
  TimeFieldProps,
  DatePickerProps,
  ScrollbarEntrance,
  ScrollbarLook,
  ScrollbarMode,
  ScrollbarMotion,
  ScrollbarProps,
  ScrollbarTheme,
  SliderProps,
  SliderScale,
  SliderValue,
  StatusBarForeground,
  SwitchProps,
  TabProps,
  TabsProps,
  TextViewProps,
  TextViewDocument,
  MarkdownExtension,
  MarkdownOptions,
  ToastEntry,
  ToastMotion,
  ToastOptions,
  ToastProps,
  ToastStackProps,
  ToastTransitionStatus,
  ToggleGroupProps,
  ToggleProps,
  ToolbarProps,
  TreeEntry,
  TreeItem,
  TreeProps,
} from "nsh/base";
```

This page is the module's index: each component has an element page with its examples, props and platform notes. For
walkthroughs, see the [Navigation guide](https://nsh.dev/versions/main/docs/navigation.md) and [Forms and keyboard](https://nsh.dev/versions/main/docs/forms-and-keyboard.md).

| TSX | Rust | What it is |
|---|---|---|
| [`Button`](https://nsh.dev/versions/main/elements/button.md) | `button()` | A press target with the disabled and selected states and a role for screen readers. |
| [`Link`](https://nsh.dev/versions/main/elements/link.md) | `link()` | A press target that goes somewhere: it opens its `href` through the system, or the app opens it (`openWith="app"`, `onOpen`). |
| [`Avatar`](https://nsh.dev/versions/main/elements/avatar.md), [`AvatarGroup`](https://nsh.dev/versions/main/elements/avatar.md) | `avatar()`, `avatar_group()` | A person's picture, or a fallback (the initials, the app's icon) while it loads, when it fails and without one; and a row that shows the first `limit` and an overflow. The loading state is native. |
| [`Checkbox`](https://nsh.dev/versions/main/elements/checkbox.md) | `checkbox()` | A checked, unchecked or indeterminate control with an indicator the app styles and marks. |
| [`Radio`](https://nsh.dev/versions/main/elements/radio.md), [`RadioGroup`](https://nsh.dev/versions/main/elements/radio.md) | `radio()`, `radio_group()` | One option of a set the user picks one of, and the set; the app owns which one is checked. |
| [`Switch`](https://nsh.dev/versions/main/elements/switch.md) | `switch()` | An on / off control with a track and a thumb the app styles. |
| [`Tab`](https://nsh.dev/versions/main/elements/tabs.md), [`Tabs`](https://nsh.dev/versions/main/elements/tabs.md) | `tab()`, `tabs()` | One tab of a tab list, and the list; the app owns which one is selected and shows its content. |
| [`Toggle`](https://nsh.dev/versions/main/elements/toggle.md), [`ToggleGroup`](https://nsh.dev/versions/main/elements/toggle.md) | `toggle()`, `toggle_group()` | A button that is on or off, and a toolbar of them; the app owns which ones are pressed. |
| [`Toolbar`](https://nsh.dev/versions/main/elements/toolbar.md), [`ToolbarGroup`](https://nsh.dev/versions/main/elements/toolbar.md), [`ToolbarSeparator`](https://nsh.dev/versions/main/elements/toolbar.md) | `toolbar()`, `toolbar_group()`, `toolbar_separator()` | A bar of buttons, toggles and links: one stop of the keyboard focus whose arrow keys move along it; groups of related items and lines between them. |
| [`Carousel`](https://nsh.dev/versions/main/elements/carousel.md) and its parts | `carousel()`, `carousel_content()`, `carousel_item()`, `carousel_previous()`, `carousel_next()`, `carousel_pagination()`, `carousel_pagination_item()` | Slides shown one place at a time on the platform's own scrolling, with previous / next, a pagination, the keys and a seamless loop; the app owns `index`. |
| [`Select`](https://nsh.dev/versions/main/elements/select.md) | `select()` | One value from a list of items: a popup at the trigger on desktops, a sheet on phones; the app owns `value` and draws the trigger. |
| [`Combobox`](https://nsh.dev/versions/main/elements/combobox.md) | `combobox()` | One value or several (`multiple`) from a list of items filtered by typing into its input; the app owns `value` and styles the field. |
| [`Calendar`](https://nsh.dev/versions/main/elements/calendar.md) | `calendar()` | A date or a range of dates picked from months of days, with month and year views and the keyboard; the app owns `value` and draws the items. |
| [`TimeField`](https://nsh.dev/versions/main/elements/time-field.md) | `time_field()` | A time of day edited segment by segment (hour, minute, second, AM/PM); the app owns `value`. |
| [`DatePicker`](https://nsh.dev/versions/main/elements/date-picker.md) | `date_picker()` | A date, a range or a date and time from a calendar in a popup at the trigger on desktops, a sheet on phones; the app owns `value` and draws the trigger. |
| [`Collapsible`](https://nsh.dev/versions/main/elements/collapsible.md) | `collapsible()` | A region whose content expands and collapses; the app owns `open` and its trigger. |
| [`Accordion`](https://nsh.dev/versions/main/elements/accordion.md), [`AccordionItem`](https://nsh.dev/versions/main/elements/accordion.md), [`AccordionHeader`](https://nsh.dev/versions/main/elements/accordion.md), [`AccordionTrigger`](https://nsh.dev/versions/main/elements/accordion.md), [`AccordionPanel`](https://nsh.dev/versions/main/elements/accordion.md) | `accordion()`, `accordion_item()`, `accordion_header()`, `accordion_trigger()`, `accordion_panel()` | Stacked sections that expand and collapse under their headings, one at a time or several (`multiple`); the app owns `value`, the open items. |
| [`OtpInput`](https://nsh.dev/versions/main/elements/otp-input.md) | `otp_input()` | A one-time code in cells the app styles; the app owns `value`, `onComplete` tells when it is full. |
| [`Pagination`](https://nsh.dev/versions/main/elements/pagination.md) | `pagination()` | The pages of a set: Previous, the pages around the current one with ellipses, the app's children and Next; the app owns `page`. |
| [`Command`](https://nsh.dev/versions/main/elements/command.md) | `command()` | A command palette: a search field over the app's commands, filtered natively by label and keywords, in a virtualized list; Return or a press chooses (`onSelect`), in a `Dialog` for a Cmd+K palette. |
| [`Tree`](https://nsh.dev/versions/main/elements/tree.md) | `tree()` | Items that hold items, virtualized: expanded and collapsed, one selected, one stop of the keyboard focus; the app owns `expanded` and `selected` or the tree keeps its own. |
| [`Progress`](https://nsh.dev/versions/main/elements/progress.md) | `progress()` | A progress bar; the app owns `value` (0 to 100) and `indeterminate`. |
| [`NumberInput`](https://nsh.dev/versions/main/elements/number-input.md) | `number_input()` | A number typed in a field or stepped with buttons and keys; the app owns `value` (or the input keeps its own from `defaultValue`). |
| [`Scrollbar`](https://nsh.dev/versions/main/elements/scrollbar.md) | `scrollbar()` | A scroll bar of the app's own look for the scroll view or list it names (`scroll`); its thumb follows the content and its drags and presses scroll it. |
| [`Slider`](https://nsh.dev/versions/main/elements/slider.md) | `slider()` | A value, or a range of two, picked along a track; the app owns `value` (or the slider keeps its own from `defaultValue`). |
| [`ColorPicker`, `ColorArea`, `ColorSlider`, `ColorField`, `ColorSwatch`, `ColorEyeDropper`](https://nsh.dev/versions/main/elements/color-picker.md) | `color_picker()`, `color_area()`, `color_slider()`, `color_field()`, `color_swatch()`, `color_eye_dropper()` | A color picker and its parts: a saturation and brightness area, sliders of any channel of RGB, HSL, HSB or OKLCH and of the alpha, fields of the color or a channel, swatches, an eyedropper; the app owns `value` (or the picker keeps its own from `defaultValue`). |
| [`ResizablePanelGroup`, `ResizablePanel`](https://nsh.dev/versions/main/elements/resizable.md) | `h_resizable()`, `v_resizable()`, `resizable_panel()` | Panels side by side or stacked, with handles the user drags to resize them. |
| [`DockArea`](https://nsh.dev/versions/main/elements/dock.md) | `dock_area()` | A workspace of splits, tab groups and edge docks the user arranges; its layout is the app's data. |
| [`NavStack`, `NavPage`, `createNavStack`](https://nsh.dev/versions/main/elements/nav-stack.md) | `nav_stack()`, `nav_page()` | A native navigation stack and its pages. |
| [`Dialog`](https://nsh.dev/versions/main/elements/dialog.md) | `dialog()` | Content presented over everything else: sheets, full-screen flows, dialogs. |
| [`AlertDialog`](https://nsh.dev/versions/main/elements/alert-dialog.md) | `alert_dialog()` | The platform's alert or action sheet. |
| [`TextView`](https://nsh.dev/versions/main/elements/text-view.md) | `text_view()` | A document of Markdown, HTML or blocks, drawn with texts and views, for streamed AI replies. |
| [`Editor`](https://nsh.dev/versions/main/elements/editor.md) | `editor()` | A code editor: syntax highlighting, several carets, folding, find and replace, diagnostics. |
| [`DiffView`](https://nsh.dev/versions/main/elements/diff-view.md) | `diff_view()` | The changes between two texts or of a patch, side by side or unified, with per-change actions. |
| [`Table`, `TableHeader`, `TableBody`, `TableFooter`, `TableRow`, `TableHead`, `TableCell`, `TableCaption`](https://nsh.dev/versions/main/elements/table.md) | `table()`, `table_row()`, ... | A table of the app's own rows and cells, with a table's roles for screen readers. |
| [`DataTable`](https://nsh.dev/versions/main/elements/data-table.md) | `data_table()` | A table of any number of rows and columns: selection, sorting, fixed, resizable and movable columns, rows served a page at a time. |
| [`Input`](https://nsh.dev/versions/main/elements/input.md) | `nsh_base::input()` | The platform's native text input, one line or several. |
| [`Popover`](https://nsh.dev/versions/main/elements/popover.md) | `popover()` | Content anchored to a trigger, on top of everything. |
| [`HoverCard`](https://nsh.dev/versions/main/elements/hover-card.md) | `hover_card()` | A preview of what its trigger points at, while the pointer rests on it (a press on touch screens). |
| [`Menu`, `ContextMenu`, `MenuItem`, `MenuSeparator`, `Submenu`](https://nsh.dev/versions/main/elements/menu.md) | `menu()`, ... | Menus: popups with cascading submenus on desktops, sheets on phones; checkable items and choices of one. |
| [`Tooltip`](https://nsh.dev/versions/main/elements/tooltip.md) | `tooltip()` | A hint next to its trigger. |
| [`Sheet`](https://nsh.dev/versions/main/elements/sheet.md) | `sheet()` | A panel at an edge of the screen over a backdrop. |
| [`Toast`, `ToastStack`, `ToastManager`](https://nsh.dev/versions/main/elements/toast.md) | `toast()`, `toast_stack()`, `ToastManager` | Unstyled toasts: a semantic root, a stack of layers, their lifecycle. |
| `statusBar` on pages and dialogs | `.status_bar(..)` | The status bar while a page or dialog is up. See [Status bar](#status-bar). |

In Rust, `theme()` reads the app's theme as design tokens (`theme().primary`, `theme().radius`), the same tokens
TSX's [theme classes](https://nsh.dev/versions/main/docs/tailwind.md#theme-tokens) use.

## Controls

### Button

A press target that owns its behavior and has no look: presses, the disabled and selected states and its role for
screen readers. Its look is the app's `class` and `style` with state variants, its content is its children. See
[Button](https://nsh.dev/versions/main/elements/button.md).

### Link

A press target that goes somewhere and has no look: presses, Return and Space while it has the keyboard focus, the
disabled state, the link role for screen readers and the current page of a navigation (`current`). `href` is where it
goes, never shown: a press reports it (`onOpen`), then opens a web page or another app's link outside the app, or,
with `openWith="app"`, leaves the opening to the app's own routes. See [Link](https://nsh.dev/versions/main/elements/link.md).

### Checkbox

A checked, unchecked or indeterminate control that owns its behavior and has no look: presses, keyboard activation,
the disabled state and the checkbox role and value for screen readers (mixed while indeterminate), with the value
owned by the app (`checked`, `indeterminate`, `onChange`). The app styles the checkbox and its indicator, whose
`checked:`, `indeterminate:` and `disabled:` classes follow the checkbox, and puts its own mark in the indicator
(`indicator`). See [Checkbox](https://nsh.dev/versions/main/elements/checkbox.md).

### Radio and RadioGroup

One option of a set the user picks exactly one of, and the set around them. A radio owns its behavior and has no
look: presses, keyboard activation, the disabled state and the radio role and checked state for screen readers. The
group is the radio group screen readers announce and holds no value: the app tells each radio whether it is checked
(`checked`), and a press on an unchecked one asks for it (`onChange`). The app's indicator and label are the radio's
children, whose `group-checked:` classes follow it. See [Radio](https://nsh.dev/versions/main/elements/radio.md).

### Switch

An on / off control that owns its behavior and has no look: presses, keyboard activation, the disabled state and the
switch role and value for screen readers, with the value owned by the app (`checked`, `onChange`). The app styles the
switch, its track and its thumb, whose `checked:` and `disabled:` classes follow the switch. See
[Switch](https://nsh.dev/versions/main/elements/switch.md).

### Tab and Tabs

The tabs of a tab list and the list around them. A tab owns its behavior and has no look: presses, keyboard
activation, the disabled state and the tab role and selected state for screen readers. The list is the tab list
screen readers announce and holds no value: the app tells each tab whether it is selected (`selected`), hears
presses (`onPress`) and shows the selected section's content itself. The app's label is the tab's children, whose
`group-selected:` classes follow it. The list's indicator (`indicatorClass`, `indicatorStyle`), an underline or a
pill the app styles, sits on the selected tab and springs to the next one natively. See [Tabs](https://nsh.dev/versions/main/elements/tabs.md).

### Carousel

Slides shown one place at a time (a product's photos, an onboarding, a banner, a row of cards). The content is a
native scroll view that snaps to the slides' starts, so a finger, the wheel and the touchpad move them in the same
frame as the pointer; when it rests the carousel reports the slide with `onChange`. Previous and next
(`CarouselPrevious`, `CarouselNext`), the pagination (`CarouselPaginationItem`s in a `CarouselPagination`, with an
indicator that springs to the slide shown) and the arrow keys move it natively, around the ends seamlessly with
`looping`. The slide shown is the app's `index`, which the app's own timer advances for slides that move on by
themselves (`onDragStart` / `onDragEnd`, `onFocus` / `onBlur` say when to wait); the look and every label are the
app's. See
[Carousel](https://nsh.dev/versions/main/elements/carousel.md).

### Toggle and ToggleGroup

A button that is on or off (bold, a favorite, a view option), and a toolbar of them. A toggle owns its behavior and
has no look: presses, keyboard activation, the disabled state and the button role with its pressed state for screen
readers. The group is the toolbar screen readers announce, one stop of the keyboard focus whose arrow keys move
between its toggles without pressing them, and holds no value: the app tells each toggle whether it is pressed
(`pressed`), hears the value it asks for (`onChange`), and keeps any number pressed or exactly one. `disabled` on the
group disables every toggle in it. The app's icon or label is the toggle's children, whose `group-aria-pressed:`
classes follow it. See [Toggle](https://nsh.dev/versions/main/elements/toggle.md).

### Toolbar, ToolbarGroup and ToolbarSeparator

A bar of controls: a text editor's formatting, a media player's transport, a vertical palette of tools. The toolbar
is the one screen readers announce (named by `accessibilityLabel`), and one stop of the keyboard focus over the
`Button`s, `Toggle`s and `Link`s inside it: Tab enters at the item it last left, the arrow keys of its `axis` move
along it and Home and End jump to its ends, pressing nothing. A `ToolbarGroup` is a named run of related items (undo
and redo, an alignment), and a `ToggleGroup` inside a toolbar is one of its groups, its toggles the toolbar's items. A
`ToolbarSeparator` is a line the app draws between runs. `disabled` on the toolbar or a group disables every item in
it. The toolbar holds no value and has no look: each control keeps its own state, and the app styles the bar, its
groups and separators. See [Toolbar](https://nsh.dev/versions/main/elements/toolbar.md).

### Select

One value chosen from a list of items given as data (`items`: a value and a title each, optionally disabled or in a
section), with no look. The app's trigger opens the list: a popup at the trigger on the desktops, a sheet at the
bottom on phones and tablets. The select owns the keyboard (Up, Down, Home, End, Page Up and Down, typeahead, Return
and Escape), search (`searchable`), the highlighted row (`focus:` on `itemClass`; `renderItem` gets what an item is, never its state) and
the combobox, listbox and option roles for screen readers. The app owns the value (`value`, `onChange`) or leaves it
to the select (`defaultValue`), and styles each part or draws the rows. See [Select](https://nsh.dev/versions/main/elements/select.md).

### Combobox

Values chosen from a list of items, as a select's list, filtered by typing into the combobox's input, with no look:
one, or with `multiple` several, a choice then
toggling the item while the list stays open. The value is an array the app owns (`value`, `onChange`) or leaves to
the combobox (`defaultValue`); `onConfirm` tells it as the list closes. The query can be the app's (`query`,
`onQueryChange`), a footer shows below the rows and a clear button empties the value. See
[Combobox](https://nsh.dev/versions/main/elements/combobox.md).

### Calendar

A date, or with `range` a range of dates, picked from months of days, with no look. One month or several
(`numberOfMonths`) show side by side; the header turns them and opens a view of the months or a page of years. The
value is an ISO date (`"2026-10-28"`) or `[start, end]` the app owns (`value`, `onChange`) or leaves to the calendar
(`defaultValue`); `disabledMatcher` keeps days from being picked, and the days take the keyboard as one stop of Tab.
The app styles the parts and draws the items (`renderItem`, given what an item is; its states are its classes, a
range's days `selected:` with `data-range-start:`, `data-range-middle:` and `data-range-end:`). See
[Calendar](https://nsh.dev/versions/main/elements/calendar.md).

### TimeField

A time of day edited a segment at a time, with no look: the hour, the minute, the second (`precision`) and AM/PM
(`hourCycle="h12"`), by stepping, typing or a phone's number pad. The value is `"HH:MM"` (`"HH:MM:SS"`) on a
24-hour clock, the app's (`value`, `onChange`) or the field's own (`defaultValue`). See
[TimeField](https://nsh.dev/versions/main/elements/time-field.md).

### DatePicker

A date picked from a calendar that opens from the app's trigger, as a select's list does: a popup on desktops, a
sheet on phones. The value is in the forms of the HTML inputs, an ISO date, `[start, end]` with `range` or a date and
time with `timePrecision` (a time field under the calendar), the app's (`value`, `onChange`) or the picker's own
(`defaultValue`). Presets set it, a clear button clears it, and every prop of `Calendar` passes on. See
[DatePicker](https://nsh.dev/versions/main/elements/date-picker.md).

### Collapsible

A region whose content expands and collapses, with no look: its children show always (a summary, the trigger), its
`content` after them while `open`. The app owns `open` and the trigger that flips it, and says the expanded state to
screen readers there. The content is made once and kept while collapsed, so what is inside keeps its state. With
`reveal` it opens and closes with a springing height, natively. See [Collapsible](https://nsh.dev/versions/main/elements/collapsible.md).

### Accordion

Stacked sections that expand and collapse under their headings, with no look: an `Accordion` of `AccordionItem`s, each
an `AccordionHeader` around its `AccordionTrigger` and an `AccordionPanel`. The app owns `value`, the open items'
values, and sets the one `onChange` reports when a trigger is pressed: one item at a time, or several with `multiple`.
Screen readers hear a group of headings whose buttons say whether their item is expanded, and each open panel as a
region. With `reveal` a panel opens and closes with a springing height, natively; with `keepMounted` its content stays
in the tree while closed. See [Accordion](https://nsh.dev/versions/main/elements/accordion.md).

### Avatar

A person's picture, with no look: the fallback (the initials of `name`, or the app's `fallback`) and the picture over
it, transparent until it has loaded, both as large as the avatar, then the app's children (a presence dot). The image's
own load and error events change its status natively (`onStatusChange`), and `fallbackDelay` keeps the fallback back
while a picture loads. Screen readers hear an image labelled with the name. An `AvatarGroup` shows its first `limit`
avatars, makes no views for the others, and shows its `overflow` while `total` is more. See
[Avatar](https://nsh.dev/versions/main/elements/avatar.md).

### Progress

A linear progress bar, with no look: a track with an indicator inside it, the indicator `value` percent of the track's
width. The app owns `value` (0 to 100) and `indeterminate`; screen readers get the progress bar role, the range and the
value, and no value while indeterminate, when the indicator's width and motion are the app's. See
[Progress](https://nsh.dev/versions/main/elements/progress.md).

### NumberInput

A number typed in a field or stepped, with no look: the field (`Input`), the decrement before it and the increment
after it (or both in a column on the right, `controlsRight`). The app owns `value` (a number or `null`; or the input
keeps its own from `defaultValue`) and hears `onChange` with the number the field reads as. The field takes a number or
the text on the way to one, digits and signs of other keyboards included; the buttons, Up / Down and Page Up / Page
Down step it by `step`, keeping the decimals, up to `min` and `max`, and leaving the field holds a typed value to them.
The field is a spin button for screen readers, whose increment and decrement step it. See
[NumberInput](https://nsh.dev/versions/main/elements/number-input.md).

### Slider

A value, or a range of two, picked along a track, with no look: a track that takes presses and drags, the indicator
inside it that the values map onto, the range and one thumb per value on it. The app owns `value` (a number or
`[start, end]`; or the slider keeps its own from `defaultValue`) and hears `onChange` for each new value, snapped to
`step` from `min`, and `onChangeEnd` once per change; `scale` spreads the values linearly or by orders of magnitude,
`axis` lays the track out horizontally or vertically. Each thumb is an adjustable element for screen readers with its
own value, a stop of the keyboard focus, and moves with WAI-ARIA's slider keys. See [Slider](https://nsh.dev/versions/main/elements/slider.md).

### Scrollbar

A scroll bar of the app's own look for a scroll view or a list, placed where the app wants it, with no look: a track
(the bar's `class`) and a thumb in it (`thumbClass`). It names its scroll view (`scroll`, its `ref`) and follows its
offset, content and viewport; a drag of the thumb scrolls the content, a press on the track brings the thumb's middle
there. `mode` shows it while the content scrolls (until `motion.idle` after), while the pointer is over the bar,
or always; `axis` makes it horizontal. `Scrollbar.setTheme` gives every scroll view and list a bar of the app's look
over its viewport, with none to place, and a view takes a theme of its own as its `scrollbar` prop. See
[Scrollbar](https://nsh.dev/versions/main/elements/scrollbar.md).
### ColorPicker

A color picker with no look: the root holds the color and the parts inside it show and change it, laid out by the app.
`ColorArea` is HSB's saturation and brightness, `ColorSlider` any channel of RGB, HSL, HSB or OKLCH or the alpha
(horizontal or vertical), `ColorField` the color in any CSS form or a channel's number, `ColorSwatch` a preset a press
picks or a preview of the color, `ColorEyeDropper` a button picking a color on the screen (macOS, the web). The app owns `value` (or the picker keeps its own from `defaultValue`) and hears
`onChange` and `onChangeEnd` with the color and its text as `format` writes it; the picker keeps each space's
channels as the user set them. The thumbs are adjustable elements for screen readers and stops of the keyboard focus.
See [ColorPicker](https://nsh.dev/versions/main/elements/color-picker.md).

### OtpInput

A fixed-length numeric one-time code, with no look: one native text field over the cells takes the keyboard, so
typing, paste, the number pad and the system's code autofill are the platform's, and screen readers find one text
field. Digits only go in, up to `length`; Backspace removes the last. The app owns `value` (or gives `defaultValue`)
and hears `onChange` and `onComplete`; it styles the cells (`focus:` on the one that takes the next digit, `data-filled:`
on those that hold a digit), their groups and the caret. See [OtpInput](https://nsh.dev/versions/main/elements/otp-input.md).

### Pagination

The pages of a set to move among, a navigation landmark with no look: Previous, the first and the last page, the
current one with its neighbours (`visiblePages`), an ellipsis for each run left out, the app's children and Next;
`compact` keeps Previous, the children and Next. The app owns `page` and hears `onChange({ page })`; the current page
is `selected:` and the current page for screen readers. The app styles the items (`itemClass`) or draws them
(`renderItem`). See [Pagination](https://nsh.dev/versions/main/elements/pagination.md).

### Command

A command palette: a search field over the app's commands (`items`: an `id`, a `label`, `keywords`, a `group`, a
`shortcut` to show, `disabled`, `checked`), filtered natively as the user types (the label or a keyword holds the
query, ignoring case; sections with no match go), in a virtualized list that makes only the rows in view. Up and
Down move the highlight, Return or a press chooses (`onSelect({ id })`), Escape clears the query and then reports
`onCancel`, where the app closes a `Dialog` around it. The query is the app's (`query`, `onQueryChange`) or the
field's own; with `filterable={false}` and `loading` the app answers it from a server. The app styles every part
(`itemClass` with `focus:` for the highlight, `checked:`, `disabled:`) and draws the rows (`renderItem`, given the
shortcut as shown here). See [Command](https://nsh.dev/versions/main/elements/command.md).

### Tree

Items that hold items: a project's files, a settings sidebar, an outline. `items` is data (`TreeItem`: an `id`, a
`label`, `children`, `disabled`), and the rows are virtualized: only those in view are made, and a collapsed item's
children never are, so a tree of thousands of items stays fast. The app owns the expanded ids and the selected one
(`expanded`, `selected`, with `onExpandedChange` and `onSelectedChange`) or the tree keeps its own (`defaultExpanded`,
`defaultSelected`). A press selects a row and expands or collapses a folder; the tree is one stop of the keyboard
focus whose arrow keys move the selection (Right and Left expand, collapse, enter and leave a folder), with Home,
End, Return, Space and typeahead. The app styles the rows (`itemClass` with `selected:`, `aria-expanded:`, `focus:`)
and draws them (`renderItem`, given each item's `depth`). See [Tree](https://nsh.dev/versions/main/elements/tree.md).

### Plot (`nsh/base/plot`)

The parts charts are built from, as `gpui-base`'s `plot`, in a module of their own: `import { Plot, Line, Area, Bar,
Grid, Pie, Arc, Sankey, Treemap } from "nsh/base/plot"`. A `Plot` holds the app's rows (`data`, generic over their type, so `x` and `y`
are checked keys or functions of a row), the `point`, `linear` or `band` scales of its axes, the row under the pointer
(`onHoverChange`) and its motion (`motion`: the appear, the hover's fade and glide); its marks draw natively from the
rows, with no JS per point, and paint with the SVG paint properties (`stroke-*`, `fill-*`), `currentColor` where none
is set; an `Area` or a `Bar` shows a background (a gradient, `bg-linear-*`) inside its shapes. Bars stand in the
bands of a `band` scale, side by side or piled in a `stack`, grow in as the plot appears and fade away from the row
under the pointer, with a `label` part at each bar's end. The hover's cross line, dots (each mark's own
with `hoverDotClass`) and tooltip (`tooltipPlacement`, kept inside the plot) are parts the app styles and fills, moved
natively; axis labels are the app's own elements. A `Pie` splits the turn into a slice per row (a donut with an
`innerRadius`), each painted with its own classes (`sliceClass`, a function of its row), and an `Arc` draws one sector
between two angles (a gauge's track and value); over a pie the plot reports the slice under the pointer, which lifts
(`hoverLift`) while the others fade (`hoverDim`). A `Sankey` draws flows between the rows (`links`), laid out as
d3-sankey lays them out, each node and ribbon painted with its own classes, its nodes labelled, hovered and moving to new flows. A `Treemap` tiles the rows as a hierarchy of nested
rectangles (`id`, `parent`), each leaf's area its `value`, colored by category or along a ramp of the plot's
`colorScale`, its labels shown where they fit. See [Plot](https://nsh.dev/versions/main/elements/plot.md).

## Workspaces

### ResizablePanelGroup and ResizablePanel

Panels side by side or stacked, with a handle between each two that the user drags to share the room. The group owns
the drag, which runs natively, each panel's limits (`minSize`, `maxSize`) and the resize cursor; the sizes are the
app's (`size`, reported with `onResize`), and so are the handles' look and the panels' content. See
[Resizable](https://nsh.dev/versions/main/elements/resizable.md).

### DockArea

A dockable workspace: panels in tab groups, groups split side by side or stacked, and docks on the left, right and
bottom edges. The layout is data the app owns (`layout`, reported with `onLayoutChange`); the area owns tab drags and
drops, resizing, docks, zoom and the lock, keeps each panel's content as it moves, and presents the same layout with
drawers and a bottom sheet when it is narrow. The tabs, handles, drop indicator and the panels' content are the
app's. See [Dock](https://nsh.dev/versions/main/elements/dock.md).

## Documents

### TextView

`TextView` shows a document of Markdown, HTML or blocks the app builds, drawn with [`Text`](https://nsh.dev/versions/main/elements/text.md)
elements and views: headings, lists, code, tables, images, formulas, footnotes and the app's own syntax. It is made for
AI chat replies that stream in, with a reading typography in the theme's colors that the app restyles part by part,
and render functions that put the app's content in place. See [TextView](https://nsh.dev/versions/main/elements/text-view.md).

## Code

### Editor

`Editor` is a code editor for more than fifty languages: syntax highlighting, line numbers, several carets, folding,
soft wrap, find and replace, diagnostics and decorations, with the keys of code editors. The text is the app's
(`value` and `onChange`), and so is the find bar, which drives the editor's `search`. It comes with a look built from
the theme's tokens that the app restyles part by part. See [Editor](https://nsh.dev/versions/main/elements/editor.md).

### DiffView

`DiffView` shows the changes between two texts, or of the files of a patch, as code review tools do: side by side or
unified, the words changed within lines highlighted, unchanged lines collapsed into separators that expand, in the
`Editor`'s syntax colors. The app's actions keep or revert each change. See [DiffView](https://nsh.dev/versions/main/elements/diff-view.md).

### Table

`Table` and its parts lay out a few rows the app writes as children, and give screen readers a table: groups of rows,
rows, column headers and cells. Every part takes the app's look. See [Table](https://nsh.dev/versions/main/elements/table.md).

### DataTable

`DataTable` shows rows and columns and scrolls both ways over any number of either, making only the cells in view. Rows,
columns or cells select; columns resize, move, stay fixed and sort (the app sorts); the app serves rows a page at a time
and can draw cells and titles. See [DataTable](https://nsh.dev/versions/main/elements/data-table.md).

## Navigation

A `NavStack` of `NavPage`s is `UINavigationController` on iOS and a stack with a toolbar and predictive back on
Android; on the desktops and the web each page shows the app's own `header`. See
[NavStack](https://nsh.dev/versions/main/elements/nav-stack.md), which also covers `createNavStack` and leaving a page.

### Dialog

`Dialog` presents content over everything else, including the stack's header, in its own native window layer. Its
popup and backdrop are styled by the app. See [Dialog](https://nsh.dev/versions/main/elements/dialog.md).

## Alert dialogs

### AlertDialog

`AlertDialog.show(options)` shows the platform's own alert or action sheet and resolves with `{ action }`, the `id`
of the action the user chose. See [AlertDialog](https://nsh.dev/versions/main/elements/alert-dialog.md).

## Input

`Input` is the platform's native text input: a single-line or multiline field whose typing, caret, selection,
autocorrection and autofill the platform handles. The app owns its value and its look. Its props are the type `InputProps` (with `IOSInputProps` for `ios={{…}}`), exported beside it. See [Input](https://nsh.dev/versions/main/elements/input.md).

## Status bar

The status bar belongs to what is on screen, as in UIKit, where each view controller declares its
`preferredStatusBarStyle` and the topmost one decides. In NSH the pages and dialogs are those view controllers: a
`NavPage` or a `Dialog` declares the status bar it wants with `statusBar`, and the app declares its default in
`nsh.json`.

```rust
use nsh_base::nav_page;
use nsh_core::prelude::*;

fn photo_viewer() -> Screen {
    nav_page().header_visible(false).status_bar(
        StatusBarSetting::default()
            .foreground(StatusBarStyle::Light)
            .hidden(true)
            .animated(true),
    )
}
```

```tsx
import { NavPage } from "nsh/base";

function PhotoViewer() {
  return (
    <NavPage headerVisible={false} statusBar={{ foreground: "light", hidden: true, animated: true }}>
      …
    </NavPage>
  );
}
```

`statusBar` takes these fields, each optional (in Rust, a `StatusBarStyle` alone, or `StatusBarSetting`'s builder
methods of the same names):

| Field | Type | Description |
|---|---|---|
| `foreground` | `"auto" \| "light" \| "dark"` (Rust: `StatusBarStyle::Default`, `Light`, `Dark`) | The color of the content (time, battery, signal): `"light"` for dark backgrounds, `"dark"` for light ones, `"auto"` the platform's for the current appearance. |
| `hidden` | `boolean` | Hides the status bar. |
| `animated` | `boolean` | Animates the change when the page or dialog comes and goes. |

The value is reactive: `statusBar={{ foreground: dark() ? "light" : "dark" }}` follows the signal, as does a Rust
closure that reads one.

### Which one applies

The page or dialog shown **most recently** decides, **field by field**: a page pushed onto a stack is over the pages
below it, and an open dialog is over the pages. A field it leaves out comes from the one below it, and in the end
from the app's default. When the page is popped or the dialog closes, the one below it applies again.

```rust
nav_page()
    .title("Inbox")
    .status_bar(StatusBarStyle::Dark);

// Pushed over it: hidden, with the inbox's dark content when it shows again.
nav_page()
    .title("Photo")
    .status_bar(StatusBarSetting::default().hidden(true));
```

```tsx
<NavPage title="Inbox" statusBar={{ foreground: "dark" }}>…</NavPage>

// Pushed over it: hidden, with the inbox's dark content when it shows again.
<NavPage title="Photo" statusBar={{ hidden: true }}>…</NavPage>
```

### The app's default

`nsh.json`'s `"statusBar"` is the setting under every page and dialog, as Info.plist's `UIStatusBarStyle` and
`UIStatusBarHidden` are in a UIKit app:

```json
{
  "statusBar": { "foreground": "light", "hidden": false }
}
```

Both fields are optional. Without it the content is `"auto"` and the bar shows. Packaged iOS apps also show it on the
launch screen.

### The status bar on each platform

- **iOS**: hiding and showing animate with a fade. In an app [embedded](https://nsh.dev/versions/main/docs/ios.md) in a native one,
  the host app's view controller decides how the status bar looks. The host applies NSH's setting by returning
  `NshAppView.preferredStatusBarStyle`, `NshAppView.prefersStatusBarHidden` and
  `NshAppView.preferredStatusBarUpdateAnimation` from its view controller.
- **Android**: apps draw edge to edge, behind the status bar (Android 15, API 35): the app's own background is the
  bar's, and `foreground` keeps its content readable on it.
- **Desktops and the web**: the window's title bar and the browser's bars are the system's and the browser's;
  `statusBar` and `nsh.json`'s `"statusBar"` are for the phones.

> [!IMPORTANT]
> When your `nsh.json` declares `"capabilities"`, the status bar changes only when they include
> `"statusBar": true`; other changes are refused and logged. See
> [Sandbox and capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md).

```json
{
  "capabilities": {
    "statusBar": true
  }
}
```

## Related

- [Navigation guide](https://nsh.dev/versions/main/docs/navigation.md).
- [Forms and keyboard](https://nsh.dev/versions/main/docs/forms-and-keyboard.md).
- [Avatar](https://nsh.dev/versions/main/elements/avatar.md), [Button](https://nsh.dev/versions/main/elements/button.md), [Carousel](https://nsh.dev/versions/main/elements/carousel.md), [Link](https://nsh.dev/versions/main/elements/link.md), [Checkbox](https://nsh.dev/versions/main/elements/checkbox.md), [Radio](https://nsh.dev/versions/main/elements/radio.md), [Switch](https://nsh.dev/versions/main/elements/switch.md), [Tabs](https://nsh.dev/versions/main/elements/tabs.md), [Toggle](https://nsh.dev/versions/main/elements/toggle.md), [Toolbar](https://nsh.dev/versions/main/elements/toolbar.md), [Select](https://nsh.dev/versions/main/elements/select.md), [Combobox](https://nsh.dev/versions/main/elements/combobox.md), [Command](https://nsh.dev/versions/main/elements/command.md), [Calendar](https://nsh.dev/versions/main/elements/calendar.md), [TimeField](https://nsh.dev/versions/main/elements/time-field.md), [DatePicker](https://nsh.dev/versions/main/elements/date-picker.md), [Collapsible](https://nsh.dev/versions/main/elements/collapsible.md), [HoverCard](https://nsh.dev/versions/main/elements/hover-card.md), [Accordion](https://nsh.dev/versions/main/elements/accordion.md), [Progress](https://nsh.dev/versions/main/elements/progress.md), [Slider](https://nsh.dev/versions/main/elements/slider.md), [ColorPicker](https://nsh.dev/versions/main/elements/color-picker.md), [Scrollbar](https://nsh.dev/versions/main/elements/scrollbar.md), [NumberInput](https://nsh.dev/versions/main/elements/number-input.md), [OtpInput](https://nsh.dev/versions/main/elements/otp-input.md), [Pagination](https://nsh.dev/versions/main/elements/pagination.md), [Tree](https://nsh.dev/versions/main/elements/tree.md), [Plot](https://nsh.dev/versions/main/elements/plot.md), [NavStack](https://nsh.dev/versions/main/elements/nav-stack.md), [Dialog](https://nsh.dev/versions/main/elements/dialog.md), [AlertDialog](https://nsh.dev/versions/main/elements/alert-dialog.md), [TextView](https://nsh.dev/versions/main/elements/text-view.md), [Editor](https://nsh.dev/versions/main/elements/editor.md), [DiffView](https://nsh.dev/versions/main/elements/diff-view.md), [Table](https://nsh.dev/versions/main/elements/table.md), [DataTable](https://nsh.dev/versions/main/elements/data-table.md), [Text](https://nsh.dev/versions/main/elements/text.md) and [Input](https://nsh.dev/versions/main/elements/input.md).
  [AlertDialog](https://nsh.dev/versions/main/elements/alert-dialog.md), [TextView](https://nsh.dev/versions/main/elements/text-view.md), [Editor](https://nsh.dev/versions/main/elements/editor.md), [DiffView](https://nsh.dev/versions/main/elements/diff-view.md), [Table](https://nsh.dev/versions/main/elements/table.md), [DataTable](https://nsh.dev/versions/main/elements/data-table.md),
  [Text](https://nsh.dev/versions/main/elements/text.md) and
  [Input](https://nsh.dev/versions/main/elements/input.md).
- [Device and environment](https://nsh.dev/versions/main/docs/device-and-environment.md).
- [`BackHandler`](https://nsh.dev/versions/main/modules/nsh-mobile.md#backhandler): `BackHandler` and other Android-only APIs.

Source: https://nsh.dev/versions/main/modules/nsh-base

---

# nsh/mobile

`nsh/mobile` holds the capabilities specific to iOS and Android: the system's tab bar, `TabBar`, on both;
[`InputAccessoryView`](#inputaccessoryview), a bar over the keyboard, on iOS; and [`BackHandler`](#backhandler), the
back button, on Android. Rust code uses `nsh_core::mobile` and `nsh_core::prelude`; TSX imports `nsh/mobile`. The
module can be imported on every platform, so one bundle runs everywhere: on the other platforms its components take no
room and its calls return at once, and `isAvailable` tells you whether you are on iOS or Android (`platform.os` from
`nsh` tells which). What desktops have is in [nsh/desktop](https://nsh.dev/versions/main/modules/nsh-desktop.md).

```rust
use nsh_core::mobile::{TabBarItem, tab_bar};
```

```tsx
import { BackHandler, InputAccessoryView, isAvailable, TabBar } from "nsh/mobile";
import type { TabBarItem, TabBarProps } from "nsh/mobile";
```

## Scope

This module exposes capabilities specific to mobile platforms, such as the system tab bar for top-level app navigation. Common controls belong to [`nsh/base`](https://nsh.dev/versions/main/modules/nsh-base.md): its [Switch](https://nsh.dev/versions/main/elements/switch.md), for example, shares behavior and API across phones, desktops and the web, with the track, thumb and state styles supplied by the app. `TabBar` serves mobile app navigation; `Tabs` serves tabbed content across platforms. Only capabilities with mobile-specific interaction semantics belong here. A system appearance, size or animation alone does not change a common control’s shared role. This distinction guides which capabilities belong here ([Goals and design principles](https://nsh.dev/versions/main/docs/goals.md)).

## isAvailable

```ts
const isAvailable: boolean;
```

`true` on iOS, the iOS simulator, Mac Catalyst and Android; `false` elsewhere. Rust:
`matches!(os(), Os::Ios | Os::Android)`.

## TabBar

A tab bar switches between the top-level sections of an app: records and stats, inbox and settings. `TabBar` is the
system's own bar, so it looks and behaves as the system's apps do: `UITabBar` on iOS and iPadOS (Liquid Glass and its
selection on iOS 26), Material 3's navigation bar on Android, in the system's colors, light and dark. The app gives the
tabs (`items`), says which one is selected (`selectedIndex`), hears the user's choice (`onChange`), places the bar with
its `class` and `style`, and shows the selected section's content itself. For tabs inside a page, and on every
platform, use `nsh/base`'s [Tabs](https://nsh.dev/versions/main/elements/tabs.md).

```rust
use nsh_core::{
    mobile::{TabBarItem, tab_bar},
    prelude::*,
};

fn sections() -> impl IntoElement {
    let section = signal(0u32);
    view()
        .flex_1()
        .child(text(move || match section.get() {
            0 => "Records",
            _ => "Stats",
        }))
        .child(
            tab_bar()
                .items(vec![
                    TabBarItem::new("Records").icon("list.bullet"),
                    TabBarItem::new("Stats").icon("chart.bar"),
                ])
                .selected_index(section)
                .on_change(move |index: &u32| section.set(*index))
                .absolute()
                .left_0()
                .right_0()
                .bottom_0(),
        )
}
```

```tsx
import { mount, signal, Text, View } from "nsh";
import { TabBar } from "nsh/mobile";
import { platform } from "nsh";

function App() {
  const section = signal(0);
  return (
    <View class="flex-1">
      <Text>{section() === 0 ? "Records" : "Stats"}</Text>
      <TabBar
        items={[
          { title: "Records", icon: platform.select({ ios: "list.bullet", android: "ic_records" }) },
          { title: "Stats", icon: platform.select({ ios: "chart.bar", android: "ic_stats" }) },
        ]}
        selectedIndex={section()}
        onChange={({ index }) => section.set(index)}
        class="absolute inset-x-0 bottom-0"
      />
    </View>
  );
}

mount(App);
```

`TabBar` comes from `nsh/mobile`, `nsh_core::mobile` in Rust. The selection is the app's: a
tap reports `onChange` with the tab's index (`{ index }`), the bar shows the choice at once, as the system's does, and the app shows
that section and passes the index back as `selectedIndex`. Its height is the system's where the style leaves it open.
In Rust, `tab_bar()` makes one, with a setter per prop (`.items(..)`, `.selected_index(..)`), a listener per event
(`.on_change(..)`) and the typed style methods; `TabBarItem::new(title).icon(name)` makes a tab.

### Props

| Prop | Rust | Type | Default | Description |
|---|---|---|---|---|
| `items` | `.items(..)` | `TabBarItem[]` | `[]` | The tabs, in order. |
| `selectedIndex` | `.selected_index(..)` | `number` | `0` | The selected tab, by index; an index past the tabs selects none. |
| `hidden` | `.hidden(..)` | `boolean` | `false` | iOS: hides the bar without a transition. The app owns this value across pushes and pops. The bar shows when both this prop and the visible stack’s `hidesBottomBarWhenPushed` request are false. |
| `class`, `style` | style methods | `string`, `StyleProp<ViewStyle>` | none | Where the bar is: its position and size. Its look is the system's, with the selected tab in the theme's `primary`. |
| `testID` | `.test_id(..)` | `string` | none | Finds the bar in tests and `nsh test --trace`. |

#### TabBarItem

| Field | Rust | Type | Description |
|---|---|---|---|
| `title` | `TabBarItem::new(title)` | `string` | The tab's title, which screen readers say. |
| `icon` | `.icon(name)` | `string` | The tab's icon, by the platform's name for it: an [SF Symbol](https://developer.apple.com/sf-symbols/) on iOS (`"house"`), a drawable of the app on Android (`res/drawable/home.xml` is `"home"`, `"android:ic_menu_search"` the system's). `platform.select` picks one per platform. |

### Events

| Event | Rust | Description |
|---|---|---|
| `onChange` | `.on_change(\|index: &u32\| ..)` | The user chose a tab: `{ index }`, its index. The bar shows the choice at once; the app shows the tab's content and sets `selectedIndex`. |

### Platform notes

- **iOS and Mac Catalyst**: `UITabBar`, with the system's appearance for the iOS version: the floating Liquid Glass
  bar and its selection on iOS 26. Icons are SF Symbols. The theme's `primary` is the bar's `tintColor`, the selected
  tab's color; the other tabs keep the system's.
- **Android**: Material 3's navigation bar, made of the platform's views: an icon in its active indicator over each
  label, a ripple on press, the system's dynamic colors on Android 12 and later and Material's baseline colors before,
  light or dark as the app's appearance. At the bottom of the window it reaches under the navigation bar, taller by
  its inset, as Material's does. Icons are drawables of the app (tinted by the bar). The selected tab's icon and label
  take the theme's `primary`, over an active indicator of it at 12% opacity; the other tabs keep the system's.
- **Desktops (macOS, Windows, Linux, GPUI) and the web**: the sections show with [Tabs](https://nsh.dev/versions/main/elements/tabs.md), in the app's
  look. `TabBar` takes no room there, so one layout holds both, picked by `platform.os`
  ([`nsh`'s device API](https://nsh.dev/versions/main/modules/nsh.md#device)).

## InputAccessoryView

On iOS and Mac Catalyst; on Android it is an empty hidden view.

```ts
function InputAccessoryView(props: InputAccessoryViewProps): JSX.Element;

interface InputAccessoryViewProps {
  nativeID: string;
  style?: StyleProp<ViewStyle>;
  class?: string;
  children?: JSX.Element;
}
```

A bar over the keyboard (UIKit's `inputAccessoryView`), shown while an input whose `ios={{ inputAccessoryViewID }}` matches its `nativeID` has focus. Rust: `input_accessory_view(native_id)`, shown for the inputs whose `.input_accessory(native_id)` matches. It is as wide as the window and as tall as its content, and moves with the keyboard natively.

| Prop | Type | Rust | Description |
|---|---|---|---|
| `nativeID` | `string` | `input_accessory_view(native_id)` | Inputs with this `inputAccessoryViewID` show the bar. |
| `style` | `StyleProp<ViewStyle>` | `Styled` methods (`.bg(…)`) | The bar's style (its background, for example). |
| `class` | `string` | | Tailwind classes. |
| `children` | `JSX.Element` | `.child(…)` | The bar's content. |

It renders nothing where it is placed in the tree, and nothing at all on Android, so you can place it next to the input it belongs to.

```rust
use nsh_core::prelude::*;

#[component]
fn Note() -> impl IntoElement {
    let note = signal(String::new());
    let field = element_ref();
    view()
        .child(
            input()
                .element_ref(&field)
                .value(note)
                .on_change(move |value: &str| note.set(value.to_string()))
                .placeholder("Write a note")
                .input_accessory("note-bar"),
        )
        .child(
            input_accessory_view("note-bar").bg(rgb(0xf1f5f9)).child(
                view()
                    .flex_row()
                    .items_center()
                    .p(px(10.0))
                    .child(
                        text(move || format!("{} characters", note.with(|n| n.chars().count())))
                            .flex_1()
                            .text_color(rgb(0x64748b)),
                    )
                    .child(text("Done").font_weight(FontWeight::SEMIBOLD).on_press(move || field.blur())),
            ),
        )
}
```

```tsx
import { type InputRef, signal, Text, View } from "nsh";
import { Input } from "nsh/base";
import { InputAccessoryView } from "nsh/mobile";

function Note() {
  const text = signal("");
  let input: InputRef | undefined;
  return (
    <View>
      <Input
        ref={(n) => (input = n)}
        value={text()}
        onChange={({ value }) => text.set(value)}
        placeholder="Write a note"
        ios={{ inputAccessoryViewID: "note-bar" }}
      />
      <InputAccessoryView nativeID="note-bar" style={{ backgroundColor: "#f1f5f9" }}>
        <View style={{ flexDirection: "row", alignItems: "center", padding: 10 }}>
          <Text style={{ flex: 1, color: "#64748b" }}>{text().length} characters</Text>
          <Text onPress={() => input?.blur()} style={{ fontWeight: "600" }}>Done</Text>
        </View>
      </InputAccessoryView>
    </View>
  );
}
```

See also [Forms and keyboard](https://nsh.dev/versions/main/docs/forms-and-keyboard.md).

## BackHandler

On Android; on iOS its listeners are kept and never called, and `exitApp()` returns at once.

```ts
const BackHandler: {
  on(event: "press", listener: () => boolean | void): () => void;
  exitApp(): void;
};
```

The system back button and back gesture. Dialogs handle the back press first (a dialog closes); then `BackHandler`'s listeners run, the most recently added first; when none of them handles it, the top navigation stack pops, and with no page to go back to the app exits.

| Member | Rust | Description |
|---|---|---|
| `on("press", listener)` | `on_back_press(listener)` | `listener` returns `true` when it handled the press. Returns a function that stops listening; a listener added while a component renders (or an effect runs) stops with it, in Rust and TSX alike. |
| `exitApp()` | the listener returns `false` | Leaves the app. A Rust listener that returns `false` lets the press go on, so the stack goes back or the app exits. |

```rust
use nsh_base::alert_dialog;
use nsh_core::prelude::*;

#[component]
fn Editor() -> impl IntoElement {
    let dirty = signal(false);
    on_back_press(move || {
        if !dirty.get_untracked() {
            return false; // let the app go back or exit
        }
        spawn(async move {
            let answer = alert_dialog().title("Discard changes?").cancel("keep", "Keep").destructive("discard", "Discard").show().await;
            if answer.is_ok_and(|r| r.action.as_deref() == Some("discard")) {
                dirty.set(false); // the next back press leaves
            }
        });
        true
    });
    // ...
}
```

```tsx
import { signal } from "nsh";
import { BackHandler } from "nsh/mobile";
import { AlertDialog } from "nsh/base";

function Editor() {
  const dirty = signal(false);
  // Stops listening when Editor goes.
  BackHandler.on("press", () => {
    if (!dirty()) return false; // let the app go back or exit
    AlertDialog.show({
      title: "Discard changes?",
      actions: [{ label: "Keep", role: "cancel", id: "keep" }, { label: "Discard", role: "destructive", id: "discard" }],
    }).then(({ action }) => action === "discard" && BackHandler.exitApp());
    return true;
  });
  // ...
}
```

> [!NOTE]
> The listener runs after the system has delivered the press: the main thread never waits for the app's code. While at least one listener is registered, NSH takes back presses that dialogs leave, and goes back in the top stack or exits the app itself when no listener returns `true`.

The status bar is set by the `statusBar` of [pages and dialogs](https://nsh.dev/versions/main/modules/nsh-base.md#status-bar) from `nsh/base`, on iOS and Android alike.

Source: https://nsh.dev/versions/main/modules/nsh-mobile

---

# nsh/desktop

`nsh/desktop` holds what only desktops have: the window and its title bar, the application menu and context menus. It works on macOS, Windows and Linux. Rust code finds the same in `nsh_core::element::desktop`: the window's functions (`set_title`, `set_title_bar`, `title_bar`, `minimize`, … `close_window`), the application menu and context menus (`set_application_menu`, `popup_menu`, made of `MenuItem`s), and marks draggable views with `.window_drag(true)`; TSX imports `nsh/desktop`. The module can be imported on every platform, so one bundle runs everywhere: on iOS and Android its functions do nothing, and `isAvailable` tells you whether its window and menus are there.

```rust
use nsh_core::{
    desktop::{MenuRole, TitleBarStyle},
    element::desktop::{
        MenuItem, close_window, popup_menu, set_application_menu, set_title, set_title_bar, title_bar,
    },
    prelude::*,
};
```

```tsx
import { isAvailable, Menu, titleBar, Window } from "nsh/desktop";
```

## isAvailable

```ts
const isAvailable: boolean;
```

`true` where this module's window and menu APIs work: macOS, Windows and Linux; `false` elsewhere. Rust: `os().is_desktop()`.

[`platform.desktop`](https://nsh.dev/versions/main/modules/nsh.md#platform) is the broader check for desktop behavior (`desktop={{…}}` props, `platform.select({ desktop })`): it also holds in browsers in the desktop idiom, which run in the browser's own window. Gate desktop layout, density and input on `platform.desktop`, and calls of `Window` and `Menu` on `isAvailable`.

## Window

```ts
const Window: {
  setTitle(title: string): void;
  setTitleBar(options: { style: "default" | "hidden"; height?: number }): void;
  setMenuBar(mode: "shown" | "autoHide"): void;
  minimize(): void;
  toggleMaximize(): void;
  toggleFullScreen(): void;
  setFrame(frame: {
    origin?: Partial<Point>;
    size?: Partial<Size>;
    animated?: boolean;
  }): void;
  setLevel(level: "normal" | "floating" | "desktopIcon"): void;
  orderFront(): void;
  close(): void;
};
```

The Rust column names the functions of `nsh_core::element::desktop`.

| Member | Rust | Description |
|---|---|---|
| `setTitle(title)` | `set_title(title)` | The window's title: the title bar, the taskbar or Dock, the window switcher. |
| `setTitleBar({ style, height? })` | `set_title_bar(TitleBarStyle::Hidden, Some(px(height)))` | `style: "hidden"` removes the system's title bar: the app fills the window up to its top edge and draws a title bar of its own. The system's window controls stay (macOS's traffic lights, Windows' minimize / maximize / close buttons, GTK's window buttons). `height` is your bar's height in points: the controls are centered in it (Windows' caption buttons fill it; on macOS `height` selects compact chrome up to 44 points and regular chrome above; size your bar using the actual height from `titleBar().height`, and AppKit places the traffic lights during live resizing. An embedding app's existing toolbar keeps its own style and height); without it they take the platform's height. `style: "default"` brings the system's title bar back (Rust: `set_title_bar(TitleBarStyle::Default, None)`). |
| `setMenuBar(mode)` | `set_menu_bar_visibility(mode)` | On Windows and Linux in GPUI apps, where the window draws the application menu as a bar above the app: `"shown"` (the default) shows it always; `"autoHide"` shows it after Alt is pressed and released alone, until Alt alone hides it again, as in Windows and GNOME apps. F10 and Alt with a menu's initial open a menu either way, and the bar shows while it is open. macOS's menu bar is the system's. |
| `minimize()` | `minimize()` | Minimizes the window. |
| `toggleMaximize()` | `toggle_maximize()` | Maximizes the window, or restores it when it is maximized. |
| `toggleFullScreen()` | `toggle_full_screen()` | Enters or leaves full screen. |
| `setFrame(frame)` | `set_frame(WindowFrame { .. })` | Moves and sizes the window in points; omitted fields keep their values. On macOS and Windows, `size` (`width`, `height`) includes window decorations; on Linux it sets GTK's default window size. `origin` (`x`, `y`) is the window's top left corner, measured from the top left of the primary screen (on macOS the one with the menu bar) with `y` growing down, the same on every platform; a `height` without a `y` keeps the top edge where it is, so the window grows and shrinks at its bottom edge. `animated: true` enables macOS's resize animation (default: false). |
| `setLevel(level)` | `set_level(level)` | On macOS and Windows, `"floating"` keeps the window above normal windows and `"normal"` restores the normal level. `"desktopIcon"` selects macOS's desktop icon level (the window also sits on every space, out of Mission Control and Cmd+`); on Windows it moves the window to the bottom of the current z-order, where later activation can raise it. |
| `orderFront()` | `order_front()` | Brings the window to the front of its level and focuses it (the app activates; macOS deminiaturizes, Windows restores minimized windows and sets foreground, GTK presents). The window keeps its level. On macOS, desktop-level surfaces stay behind other windows. GPUI activates its window; the window manager controls foreground requests on Linux. |
| `close()` | `close_window()` | Closes the window; the app ends with it. |

Window sizing is supported on macOS, Windows and Linux; positioning and levels on macOS and Windows. Linux's window manager controls placement and stacking. In GPUI apps, `setFrame` sets the window's size and the platform places it; GPUI's host chooses its position and level when opening the window.

When sizing a window from content measured with `onLayout`, allow room for window decorations on macOS and Windows. `width` and `height` accept positive finite numbers; `x` and `y` accept finite numbers. Invalid fields keep their previous values.

## A title bar of your own

With the title bar hidden, the app draws its own bar and says which parts of it move the window, with `.window_drag(true)` in Rust and `desktop={{ windowDrag: true }}` in TSX:

```rust
use nsh_core::{
    desktop::TitleBarStyle,
    element::{desktop::{set_title_bar, title_bar}}, prelude::*,
};

#[component]
fn TitleBar() -> impl IntoElement {
    set_title_bar(TitleBarStyle::Hidden, Some(px(40.0))); // a bar 40 points tall
    view()
        .window_drag(true)
        .h(move || match title_bar().top {
            top if top > px(0.0) => top,
            _ => px(40.0),
        })
        .pl(move || title_bar().left + px(8.0)) // macOS's traffic lights
        .pr(move || title_bar().right + px(8.0)) // the caption buttons on Windows, GTK's buttons
        .flex_row()
        .items_center()
        .child(text("My App"))
        .child(view().flex_1())
        .child(input().placeholder("Search").w(px(180.0)))
}
```

```tsx
import { Text, View } from "nsh";
import { Input } from "nsh/base";
import { titleBar, Window } from "nsh/desktop";

Window.setTitleBar({ style: "hidden", height: 40 }); // a bar 40 points tall

function TitleBar() {
  return (
    <View
      desktop={{ windowDrag: true }}
      style={{
        height: titleBar().height || 40,
        paddingLeft: titleBar().left + 8, // macOS's traffic lights
        paddingRight: titleBar().right + 8, // the caption buttons on Windows, GTK's buttons
        flexDirection: "row",
        alignItems: "center",
      }}
    >
      <Text>My App</Text>
      <View style={{ flex: 1 }} />
      <Input placeholder="Search" style={{ width: 180 }} />
    </View>
  );
}
```

Pressing a view with `windowDrag` drags the window as the system's title bar would: a double click maximizes it (or does what the user set: on macOS, "Double-click a window's title bar to"), and on Windows and Linux a right click opens the window menu. In GPUI apps on Linux, a right click goes to the app instead when the draggable view under it, or a view inside that one, listens to `onContextMenu`; listeners on views around it, the root included, do not take the window menu away.

- The nearest view that sets `windowDrag` decides: `.window_drag(false)` (`desktop={{ windowDrag: false }}`) keeps a part of a draggable view clickable.
- Text fields and views with press or touch handlers (`onPress`, `onTouch*`, responders) inside a draggable view stay clickable without it: the search field and any buttons in the example above work as usual.
- `windowDrag` also works with the system's title bar: a sidebar or toolbar can move the window too.

### titleBar

```ts
const titleBar: Accessor<{ height: number; left: number; right: number }>;
```

The hidden title bar's area, in points (reactive): its `height`, and the widths the system's window controls take at its `left` and `right` ends. Lay your bar out with it so that nothing goes under the controls. All three are 0 while the system shows its title bar (and in full screen, and off desktops). Rust: `title_bar() -> Edges<Points>`, whose `top` is the height and `left` and `right` the controls' widths; reading it subscribes to changes.

| | `height` | `left` | `right` |
|---|---|---|---|
| macOS | `height`, else the title bar's (28 or 32, by macOS version) | The traffic lights' width | 0 |
| Windows | `height`, else 32 | 0 | The three caption buttons (138) |
| Linux | `height`, else the header bar's | The window buttons at the start (the desktop's button layout) | The window buttons at the end |

On Windows the caption buttons are drawn by NSH in Windows 11's style and follow the app's appearance; hovering the maximize button shows Windows 11's snap layouts. The window keeps its resize borders, shadow and rounded corners on every platform.

## Menu

```ts
const Menu: {
  setApplicationMenu(items: MenuItem[] | null): void;
  popup(items: MenuItem[], at?: Point): Promise<void>;
};
```

| Member | Description |
|---|---|
| `setApplicationMenu(items)` | Sets the application menu: one submenu per top-level item (`File`, `Edit`, ...). On macOS it is the menu bar, whose first menu is the app menu (AppKit titles it with the app's name). On Windows and Linux it is the window's menu bar, which is not shown while the title bar is hidden; its shortcuts still work, and a title bar of the app's own can open its menus with `Menu.popup`. `null` restores the platform's default menu. |
| `popup(items, at?)` | Shows a context menu with its top left corner at `at` (the window's coordinates, in points: an `onContextMenu`'s `e.pagePosition`), or at the pointer. The promise resolves once the menu closes, whether an item was chosen or not: a button that opened it can stay pressed until then. |

In Rust, `set_application_menu(items)` takes a `Vec<MenuItem>` (`None` restores the platform's default menu), and `popup_menu(items)` (at the pointer) and `popup_menu_at(items, at)` return an `Answer<()>` that comes once the menu closes (awaiting it is optional). An item's handler runs under the owner that set the menu, while that owner lives.

Call `setApplicationMenu` again to change the menu. Inside an `effect` it follows the signals it reads: a check mark or a disabled state that depends on app state stays current.

### Menu items

```ts
type MenuItem =
  | { type: "separator" }
  | {
      label?: string;
      role?: MenuRole;
      shortcut?: string;
      when?: "always" | "auto" | "notEditing";
      disabled?: boolean;
      checked?: boolean;
      onSelect?: () => void;
      submenu?: MenuItem[];
    };
```

| Field | Description |
|---|---|
| `label` | What the item shows. A role's item has a label of its own without it. |
| `onSelect` | Called when the item is chosen, by a click or its shortcut. |
| `shortcut` | Its keyboard shortcut: modifiers and one key joined by `+`, such as `"mod+n"`, `"mod+shift+z"`, `"alt+f4"` or `"f11"`. The modifiers are in the table below. Keys are letters, digits and punctuation, written as the character the key types on a US keyboard without Shift (`,`, `/`; `"shift+/"` for `?`), or a name: `plus` (the `=` / `+` key, also `=`), `minus` (also `-`), `space`, `enter` (`return`), `escape` (`esc`), `tab`, `backspace`, `delete` (`del`), `insert`, the arrows `up`, `down`, `left`, `right` (`arrowup`, …), `home`, `end`, `pageup`, `pagedown`, `f1`–`f24`. Case does not matter (`"Mod+Shift+N"` is `"mod+shift+n"`; a capital letter is the same key, not Shift), and lowercase is the recommended style. An invalid shortcut (`"mod-n"`, `"mod++"`, `"mod+?"`) throws an error that gives the right spelling. `keymap` takes the same keystrokes. Menus show it in the platform's own style (`⇧⌘N` on macOS, `Ctrl+Shift+N` on Windows). |
| `when` | When the shortcut chooses the item while a text field has the keyboard focus, on the GPUI backend: `"always"` (the default), `"auto"` (unless the field uses the key itself: keys that type, move the caret or delete, and the editing shortcuts, as with [`keymap`](https://nsh.dev/versions/main/modules/nsh.md#keymap)'s bindings) or `"notEditing"`. A key the item leaves goes to the field. |
| `disabled` | `true` grays the item out (default `false`). |
| `checked` | Set (to `true` or `false`) for an item with a check mark. |
| `submenu` | Makes the item a submenu (it needs a `label`). |
| `role` | A standard item the platform carries out (below). |

`null`, `undefined` and `false` items are left out, so `cond && { … }` works in a list.

In Rust, an item is `MenuItem::new(label)`, `MenuItem::role(role)`, `MenuItem::separator()` or `MenuItem::submenu(label, items)`, with the fields as methods: `.shortcut("mod+n")` (it panics on an invalid shortcut, with the right spelling), `.shortcut_when(When::Auto)`, `.disabled(true)`, `.checked(on)`, `.on_select(f)`, and `.label(..)` for a role's item.

Modifiers:

| Modifier | macOS | Windows | Linux |
|---|---|---|---|
| `mod` (also `cmdorctrl`) | Command (⌘) | Ctrl | Ctrl |
| `cmd` (also `command`, `meta`, `super`, `win`) | Command (⌘) | Windows key | Super |
| `ctrl` (also `control`) | Control (⌃) | Ctrl | Ctrl |
| `alt` (also `option`, `opt`) | Option (⌥) | Alt | Alt |
| `shift` | Shift (⇧) | Shift | Shift |

Use `mod` for an app's own shortcuts: it is the key each platform's apps use for them (⌘N on macOS, Ctrl+N on Windows and Linux), so one spelling fits everywhere. The Windows key and Super mostly belong to the system (Win+E, the GNOME overview), so `cmd` is rarely right outside macOS.

Roles:

| Role | Does | Platforms |
|---|---|---|
| `about`, `hide`, `hideOthers`, `showAll` | The app menu's standard items | macOS (left out elsewhere) |
| `quit` | Quits the app | All |
| `undo`, `redo`, `cut`, `copy`, `paste`, `selectAll` | Edit the focused text field (its own shortcuts stay its own) | All |
| `minimize`, `zoom`, `toggleFullScreen`, `close` | The window | All |

A role's item has the platform's label and shortcut unless it sets its own (macOS adds the app's name to `about`, `hide` and `quit`).

Menu shortcuts come first, as in native apps: a key an item takes never reaches the focused text field or NSH's own keys. Only a binding of [`keymap`](https://nsh.dev/versions/main/modules/nsh.md#keymap) of the same keystroke comes before them. So give the editing shortcuts (`mod+c`, `mod+v`, `mod+x`, `mod+a`, `mod+z`) only to the edit roles, which pass them to the text field, and avoid keys without a modifier (`escape`, the arrows, letters), which would take them from text fields and from back navigation. On the GPUI backend, `when: "auto"` lets an item share a key with text fields: `delete` or `mod+z` choose the item while no field has the focus and edit the text while one has it.

On the GPUI backend, a native component with the keyboard focus sees each key first. A key it handles itself never reaches the keymap or the menu. A key it lets through reaches the keymap as if a text field were focused, then the menu.

```rust
use nsh_core::{
    desktop::MenuRole,
    element::desktop::{MenuItem, set_application_menu},
    platform::Os,
    prelude::*,
};

#[component]
fn AppMenu() -> impl IntoElement {
    let mac = os() == Os::MacOs;
    let wrap = signal(true);
    effect(move || {
        let mut menus = Vec::new();
        if mac {
            menus.push(MenuItem::submenu("My App", [
                MenuItem::role(MenuRole::About),
                MenuItem::separator(),
                MenuItem::role(MenuRole::Hide),
                MenuItem::role(MenuRole::HideOthers),
                MenuItem::separator(),
                MenuItem::role(MenuRole::Quit),
            ]));
        }
        let mut file = vec![
            MenuItem::new("New").shortcut("mod+n").on_select(create_document),
            MenuItem::new("Open…").shortcut("mod+o").on_select(open_document),
        ];
        if !mac {
            file.push(MenuItem::separator());
            file.push(MenuItem::role(MenuRole::Quit).label("Exit"));
        }
        menus.push(MenuItem::submenu("File", file));
        menus.push(MenuItem::submenu("Edit", [
            MenuItem::role(MenuRole::Undo),
            MenuItem::role(MenuRole::Redo),
            MenuItem::separator(),
            MenuItem::role(MenuRole::Cut),
            MenuItem::role(MenuRole::Copy),
            MenuItem::role(MenuRole::Paste),
        ]));
        menus.push(MenuItem::submenu("View", [
            MenuItem::new("Word Wrap")
                .checked(wrap.get())
                .on_select(move || wrap.update(|w| *w = !*w)),
            MenuItem::role(MenuRole::ToggleFullScreen),
        ]));
        set_application_menu(menus);
    });
    view()
}
```

```tsx
import { effect, signal } from "nsh";
import { platform } from "nsh";
import { Menu } from "nsh/desktop";

const mac = platform.os === "macos";
const wrap = signal(true);

effect(() => {
  Menu.setApplicationMenu([
    mac && {
      label: "My App",
      submenu: [{ role: "about" }, { type: "separator" }, { role: "hide" }, { role: "hideOthers" }, { type: "separator" }, { role: "quit" }],
    },
    {
      label: "File",
      submenu: [
        { label: "New", shortcut: "mod+n", onSelect: () => createDocument() },
        { label: "Open…", shortcut: "mod+o", onSelect: () => openDocument() },
        !mac && { type: "separator" },
        !mac && { role: "quit", label: "Exit" },
      ],
    },
    {
      label: "Edit",
      submenu: [{ role: "undo" }, { role: "redo" }, { type: "separator" }, { role: "cut" }, { role: "copy" }, { role: "paste" }],
    },
    {
      label: "View",
      submenu: [
        { label: "Word Wrap", checked: wrap(), onSelect: () => wrap.update((w) => !w) },
        { role: "toggleFullScreen" },
      ],
    },
  ]);
});
```

A context menu, from a button's press:

```rust
text("More").on_press(|| {
    let _ = popup_menu(vec![
        MenuItem::new("Rename").on_select(rename),
        MenuItem::new("Duplicate").on_select(duplicate),
        MenuItem::separator(),
        MenuItem::new("Delete").on_select(remove),
    ]);
})
```

```tsx
<View
  onPress={() =>
    Menu.popup([
      { label: "Rename", onSelect: rename },
      { label: "Duplicate", onSelect: duplicate },
      { type: "separator" },
      { label: "Delete", onSelect: remove },
    ])
  }
>
  <Text>More</Text>
</View>
```

> [!NOTE]
> Menus are the system's (NSMenu, Win32 menus, GTK popover menus): they look and behave like every other app's, follow the system's (or the app's) appearance and are keyboard accessible. `examples/desktop` is an app with a title bar of its own, an application menu and context menus.

Source: https://nsh.dev/versions/main/modules/nsh-desktop

---

# Standard modules

Native Shell provides eleven standard modules for TSX, imported by their bare names (Rust code uses Rust's own libraries: [From Rust](#from-rust)): Node-shaped APIs compatible with gpui-shell's, running in the app's VM on NSH's native runtime, with their capabilities checked in Rust. Their TypeScript declarations in `.nsh/types` are generated from the same specs as the modules, so what the types show is what the runtime exports.

| Module | Exports |
|---|---|
| `buffer` | `Buffer`, `atob`, `btoa`, `constants`, default (LLRT); `Buffer` is also a global |
| `crypto` | `createHash`, `createHmac`, `randomBytes`, `randomFill`, `randomFillSync`, `randomInt`, `randomUUID`, `getRandomValues`, `webcrypto`, `crypto`, `Crc32`, `Crc32c`, `Md5`, `Sha1`, `Sha256`, `Sha384`, `Sha512`, default (LLRT); `crypto` is also a global |
| `path` | `basename`, `delimiter`, `dirname`, `extname`, `format`, `isAbsolute`, `join`, `normalize`, `parse`, `relative`, `resolve`, `sep`, default (LLRT) |
| `url` | `URL`, `URLSearchParams`, `domainToASCII`, `domainToUnicode`, `fileURLToPath`, `format`, `pathToFileURL`, `urlToHttpOptions`, default; `URL` and `URLSearchParams` are NSH's global classes |
| `zlib` | `deflate`, `deflateRaw`, `inflate`, `inflateRaw`, `gzip`, `gunzip`, `brotliCompress`, `brotliDecompress`, `zstdCompress`, `zstdDecompress`, each with its `Sync` form, default (LLRT) |
| `os` | `platform()`, `arch()`, `homedir()`, `EOL`, default |
| `console` | default: the VM's `console` (`log`, `info`, `debug`, `warn`, `error`) |
| `fs/promises` | `readFile`, `writeFile`, `readdir`, `exists`, `mkdir`, `rename`, `unlink`, `rmdir`, `stat`, `lstat`, `readlink`, default |
| `process` | `run`, `spawn`, `exit`, `platform`, `arch`, `nextTick`, `ChildProcess`, default; the default object also has `env` and `dataDir` and is the global `process` |
| `net` | `connect`, `Socket`, default |
| `websocket` | `connect(url, options?)` resolving a `WebSocketConnection` (`read`, `write`, `close(code?, reason?)`, `closeCode`, `closeReason`), `WebSocketConnection`, default; the global `WebSocket` constructor on native hosts |

## From Rust

Rust code does the same work with Rust's standard library and crates.io, in the app's own native code: blocking calls run on the runtime's threads with `blocking(…)` and async ones with `background(…)` (`nsh_core::prelude`), and their results come back to the component in a task. The `capabilities` of `nsh.json` govern the app's TSX and NSH's services (`fetch`, the clipboard); the app's own Rust code runs with the permissions of the app's process. In browser apps, Rust code reaches the network with `fetch` and keeps data with `nsh_core::storage::Storage`.

| Module | Rust |
|---|---|
| `buffer` | `Vec<u8>`, `&[u8]`, the `base64` crate |
| `crypto` | crates such as `sha2`, `hmac`, `rand` and `uuid` |
| `path` | `std::path` |
| `url` | the `url` crate |
| `zlib` | crates such as `flate2`, `brotli` and `zstd` |
| `os` | `std::env::consts`, `os()` |
| `console` | the `log` crate |
| `fs/promises` | `std::fs` in `blocking(…)`; `Storage` for key-value data |
| `process` | `std::process::Command` in `blocking(…)` |
| `net` | `std::net::TcpStream` in `blocking(…)`, or `tokio::net` in `background(…)` |
| `websocket` | a crate such as `tokio-tungstenite` in `background(…)` |

## Imports and generated types

Each module is imported by exactly the name in the table: `import { join } from "path"`, `import fs from "fs/promises"`. The bundler keeps these imports, and the runtime serves them natively; the catalog is these eleven names. `buffer`, `crypto`, `path`, `url` and `zlib` are LLRT's implementations, pinned to `d9fd873e793c6551c5d92b2e31480f3279e3cd8d`, with declarations projected from that revision onto the exports the runtime has. The others are NSH's own. NSH keeps the identity of its URL, Blob, stream and event classes.

All eleven modules load on native hosts and in browser apps. `Buffer`, hashing, crypto and compression use the same portable Rust implementation in WebAssembly, including synchronous APIs; random values use browser cryptographic entropy. Browser `path` operations use POSIX paths and a virtual `/` working directory. Browser files use persistent app-private storage, and WebSockets use the browser transport. Process execution and raw TCP calls fail with `code` `ERR_FEATURE_UNAVAILABLE_ON_PLATFORM` in browsers.

## How they compare with Node.js and gpui-shell

The modules follow Node's names and shapes for the subset they export, and gpui-shell's behavior where it defines one. NSH's own choices:

- `fs/promises`' `exists` is `true` for a symlink whose target is missing, and `unlink`, `rename`, `rmdir`, `lstat` and `readlink` act on a symlink itself.
- `Stats` and `Dirent` have their fields (`size`, `mtimeMs`, `name`, ...) as own properties, as Node's do, and `isFile()`, `isDirectory()` and `isSymbolicLink()` on their prototype.
- A `ChildProcess` listener receives the event's payload: the output text, or the exit's `{ code, signal }` (with `error` and `errorCode` when the runtime ended the child). `on` returns the child. `run` resolves `{ code, signal, stdout, stderr }`: gpui-shell's output with the signal that ended the child.
- A child's environment is a small set from the host plus the names the app is granted, and it runs in the app's data directory or a `cwd` within an `fs.write` root ([Processes](#processes)).
- `process.platform`, `process.arch`, `os.platform()` and `os.arch()` give Rust's `std::env::consts` names, as gpui-shell's do: `"macos"`, `"windows"`, `"linux"`, `"ios"`, `"android"`; `"aarch64"`, `"x86_64"` ([OS metadata](#os-metadata-and-logging)).
- `process.dataDir` is `null` when the host has no data directory; `process.exit` asks the host to close the app surface.
- Limits are part of each API: sizes, counts and timeouts are listed with each module below.

## Failures

A function that returns a promise reports every failure by rejecting it, as Node's `fs/promises` does: a wrong argument, a path or host the app is not granted, a used-up limit and an I/O error alike, so one `catch` (or `.catch`) handles them all. A synchronous function (`process.spawn`, `process.exit`, `os.homedir`, `ChildProcess.write`, the global `WebSocket`'s constructor and `send`) throws. A wrong use (an argument of the wrong type, an option out of its range) is a `TypeError` or `RangeError`. Every failure an app can handle carries a `code`, which stays the same from release to release; the message is written for people and may change, so apps branch on `code`:

| `code` | What it means |
|---|---|
| `ERR_ACCESS_DENIED` | The app's `capabilities` do not grant the call. The error has `permission`, the capability's key in `nsh.json` (`"fs"`, `"process"`, `"network"`), and `resource`, what was asked for: the path, the command (`"exit"` for `process.exit`), the `"host:port"` of a socket or the WebSocket's URL |
| `ERR_FEATURE_UNAVAILABLE_ON_PLATFORM` | The call belongs to other platforms: files run on desktops and in browsers, processes on desktops, TCP sockets on native hosts, `os.homedir()` on hosts that configure a home directory |
| `ERR_NSH_QUOTA_EXCEEDED` | A limit of the runtime is used up: operations or data in flight, children, sockets, WebSockets, bytes waiting to be sent, listeners |
| `ETIMEDOUT` | The call ran out of time: `run`'s `timeoutMs`, a connection, a WebSocket handshake, write or close |
| `ENOENT`, `EEXIST`, `EACCES`, `ECONNREFUSED`, ... | The operating system's answer, with Node's codes; `EACCES` and `EPERM` are the OS refusing a file, apart from the app's capabilities |
| `ERR_OUT_OF_RANGE`, `ERR_FS_FILE_TOO_LARGE`, `ERR_SOCKET_CLOSED`, `ERR_CHILD_PROCESS_STDIO_MAXBUFFER` | Node's codes for a size past a limit, a closed connection and output past `run`'s capture |

```tsx
import fs from "fs/promises";

async function loadSettings(): Promise<string> {
  try {
    return await fs.readFile("${dataDir}/settings.json", "utf8");
  } catch (error) {
    if (error.code === "ENOENT") return "{}";
    if (error.code === "ERR_ACCESS_DENIED") console.warn(`not granted: ${error.permission} ${error.resource}`);
    throw error;
  }
}
```

A host app may grant less than the app declares ([Sandbox and Capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md)), so an app handles `ERR_ACCESS_DENIED` as it handles a failed request.

## OS metadata and logging

`os.platform(): string` and `os.arch(): string` report the actual native host OS and architecture, and `process.platform` and `process.arch` hold the same values. They are the names of Rust's `std::env::consts::OS` and `ARCH`, as gpui-shell's are: `"macos"`, `"windows"`, `"linux"`, `"ios"`, `"android"` for the OS, `"aarch64"`, `"x86_64"` for the architecture, so apps compare against them directly (`process.platform === "macos"`). `os.EOL: string` is the host's line separator. `os.homedir(): string` returns a configured absolute host home path; where none is configured it throws an error with `code` `ERR_FEATURE_UNAVAILABLE_ON_PLATFORM`. Directory paths are metadata: file operations still require `fs.read` / `fs.write` grants.

Browser apps read an empty `process.env` object, and `os.homedir()` throws `ERR_FEATURE_UNAVAILABLE_ON_PLATFORM` there, since home paths and environment variables belong to native hosts.

`import console from "console"` shares the VM's global `console` object. The module has a default export only, supporting `log`, `info`, `debug`, `warn`, `error`, each with signature `(...values: unknown[]): void`. It uses NSH's logger formatting.

## Compression

`zlib` is LLRT's, with one bound NSH adds: each decompression (`inflate`, `inflateRaw`, `gunzip`, `brotliDecompress`, `zstdDecompress` and their `Sync` forms) produces at most 64 MiB, or the VM's heap limit when that is smaller. Longer output throws a `RangeError`, as Node.js does for `maxOutputLength`; an app's own `maxOutputLength` sets a lower bound for one call. `Buffer.alloc`, `Buffer.allocUnsafe`, `Buffer.allocUnsafeSlow` and `crypto.randomBytes` throw a `RangeError` (`code` `ERR_OUT_OF_RANGE`) for a size past the VM's heap limit, or 1 GiB without one; `allocUnsafe` returns zeroed memory.

## Files

`fs/promises` reads and writes native files on desktop hosts (macOS, Windows and Linux), and app-private browser files through the Origin Private File System (OPFS). Every path is checked against `capabilities.fs` before the operation starts: `read` roots for `readFile`, `readdir`, `stat`, `lstat`, `readlink` and `exists`, `write` roots for `writeFile`, `mkdir`, `rename`, `unlink` and `rmdir`. Every failure rejects the promise: a path outside the grants with `code` `ERR_ACCESS_DENIED` (`permission` `"fs"`, `resource` the path as the app wrote it), before any disk work.

```json
{
  "capabilities": {
    "fs": { "read": ["${dataDir}"], "write": ["${dataDir}"] }
  }
}
```

Roots are absolute paths, `${dataDir}` (this app's data directory, chosen by the host), `${pluginDir}` (the app's directory), `${homeDir}`, or paths relative to the app's directory. A relative path in a call is resolved in each granted root in turn. An embedding host may narrow the grants further. Every operation stays inside its granted root, symlinks included; an absolute path is checked as written, so a root is reached by its own path (or its resolved one), not through a link outside it. `lstat`, `readlink`, `exists`, `unlink`, `rename` and `rmdir` act on a symlink itself: `exists` is `true` for a symlink whose target is missing, and `unlink` removes the link and keeps its target.

Failures carry Node's error properties: `code` (`ENOENT`, `EEXIST`, `ENOTDIR`, `EISDIR`, `ENOTEMPTY`, `ELOOP`, `EACCES`, `EPERM`, ...; `EILSEQ` for text that is not UTF-8, `ERR_FS_FILE_TOO_LARGE` past the read limit), `syscall` and `path`, so `error.code === "ENOENT"` tells a missing file apart. A path outside the grants rejects with `ERR_ACCESS_DENIED`, a call on iOS or Android (whose apps keep data with [`Storage`](https://nsh.dev/versions/main/modules/nsh.md#storage)) with `ERR_FEATURE_UNAVAILABLE_ON_PLATFORM`, and a wrong argument (an unknown encoding or option) with a `TypeError`.

`readFile` returns a `Uint8Array`, or a string with `"utf8"`, and reads files up to 64 MiB. `writeFile` writes a string or `Uint8Array` of up to 8 MiB, creating or replacing a regular file. `readdir` lists up to 10 000 names (1 MiB of them; a larger directory rejects with a `RangeError`, `code` `ERR_OUT_OF_RANGE`), sorted, or `Dirent`s (`name`, `isDirectory()`) with `{ withFileTypes: true }`. `stat` and `lstat` resolve a `Stats` with `size`, `mode`, `mtimeMs` / `atimeMs` / `birthtimeMs`, `mtime` / `atime` / `birthtime` as `Date`s, and `isFile()`, `isDirectory()` and `isSymbolicLink()`. `rmdir` removes one empty directory. One VM runs up to 1024 operations at a time and holds up to 64 MiB of file data in flight (data handed to `writeFile` until it is written, data read until its promise settles); a call past these limits rejects with `ERR_NSH_QUOTA_EXCEEDED`, and a `writeFile` past 8 MiB with a `RangeError` (`code` `ERR_OUT_OF_RANGE`).

Browser storage is scoped to the page's origin and the app's own namespace, with the same file grants and size limits checked in Rust. OPFS requires a secure context, such as HTTPS or localhost. File modification times come from browser metadata; unknown access/birth times and modes are zero. `rename` uses an atomic browser handle move and reports `ENOTSUP` when the browser does not provide it. Browser entries are regular files or directories, and `readlink` reports `EINVAL`.

## Processes

`process.spawn` and `process.run` launch commands on desktop hosts (macOS, Windows and Linux). The runtime executes the program directly with an argument array, with no shell, and owns its pipes; stdout and stderr arrive as incremental UTF-8.

```json
{
  "capabilities": {
    "process": { "execute": ["git"], "env": ["GIT_AUTHOR_NAME"] },
    "fs": { "write": ["${dataDir}"] }
  }
}
```

Commands match `process.execute` exactly: `git` and `/usr/bin/git` are separate grants. Bare commands resolve through the absolute directories of the host's `PATH`; on Windows a bare command also finds `<name>.com` and `<name>.exe` there. A batch file (`.cmd`, `.bat`) runs through `cmd.exe`: grant its absolute path (`C:\Windows\System32\cmd.exe`) and pass `/d`, `/c` and the script as arguments. A child's environment is `PATH`, `HOME`, `USERPROFILE`, `SystemRoot`, `TEMP`, `TMP`, `TMPDIR`, `LANG` and `LC_*` from the host, plus the names `process.env` grants (matched exactly, ignoring case only on Windows, whose environment does). A child runs in the app's data directory (created when missing), or in `cwd`, an existing directory within an `fs.write` root, since the child may write where it runs. An embedding host can narrow the grants.

```rust
use std::{
    io::{BufRead, BufReader},
    process::{Command, Stdio},
};

spawn(async move {
    // `run`: the whole output once the command exits.
    if let Ok(Ok(output)) = blocking(|| Command::new("git").args(["status", "--short"]).output()).await {
        log::info!("{} {}", output.status, String::from_utf8_lossy(&output.stdout));
    }
    // `spawn` with `lines: true`: each line as it comes.
    let _ = blocking(|| -> std::io::Result<()> {
        let mut child = Command::new("git").args(["log", "--oneline"]).stdout(Stdio::piped()).spawn()?;
        if let Some(stdout) = child.stdout.take() {
            for line in BufReader::new(stdout).lines() {
                log::info!("{}", line?);
            }
        }
        log::info!("done {}", child.wait()?);
        Ok(())
    })
    .await;
});
```

```tsx
import process from "process";

const { code, stdout } = await process.run("git", ["status", "--short"]);
const child = process.spawn("git", ["log", "--oneline"], { lines: true });
child.on("stdout", (line) => console.log(line));
child.on("exit", ({ code, signal }) => console.log("done", code, signal));
```

`run` resolves `{ code, signal, stdout, stderr }` for any exit status: `code` is the exit status and `signal` `null`, or, when a signal ended the child, `code` is `null` and `signal` its name (`"SIGTERM"`). It rejects on every failure. `spawn` returns a child at once; `stdin: "pipe"` enables `write` and `end`, and `lines: true` delivers complete lines. `on(event, handler)` returns the child, and a handler gets the event's payload: the text, or `{ code, signal }` once, after the final output (with `error` when the runtime ended the child: a timeout, an over-long line) (at once for a listener added later). `pid` is the child's process id. `spawn` throws what `run` rejects with, before the child starts: a command `process.execute` does not grant fails with `ERR_ACCESS_DENIED` (`permission` `"process"`, `resource` the command), a `cwd` outside the `fs.write` grants with `ERR_ACCESS_DENIED` (`permission` `"fs"`, `resource` the `cwd`), a call off the desktops with `ERR_FEATURE_UNAVAILABLE_ON_PLATFORM`, and a call past the children limit with `ERR_NSH_QUOTA_EXCEEDED`; a launch failure carries `code` (`ENOENT` for a missing executable, `EACCES` for one the OS cannot run), `syscall` (`spawn <command>`) and `path`. `run` rejects with `ETIMEDOUT` at its deadline and with a `RangeError` (`code` `ERR_CHILD_PROCESS_STDIO_MAXBUFFER`) for output past its capture; a spawned child's exit carries the same message in `error` and its code in `errorCode`. `process.dataDir` is `null` when the host has no data directory. `kill`, a timeout, the reactive owner's cleanup and the VM's teardown end the whole process tree: on Unix its process group gets SIGTERM and then SIGKILL after 250 ms (at teardown, SIGKILL at once).

| Limit | Value |
|---|---|
| `timeoutMs` | Up to 4,294,967,295 ms; `run` defaults to 30 seconds, `spawn` runs until exit |
| `run`'s capture | 8 MiB per stream |
| One line with `lines: true` | 8 MiB |
| Children per VM | 32 |
| Output in flight per VM | 8 MiB; readers wait for JS to take it |
| Pending stdin per child | 1 MiB; `write` throws `ERR_NSH_QUOTA_EXCEEDED` past it |
| Listeners | 64 per event per child |

`process.exit(code?)` requests that the host close this app surface. Grant it with `"exit": true` in `capabilities.process`; the engine forwards the request through the platform's app-exit command. A call the grant does not cover throws `ERR_ACCESS_DENIED` (`permission` `"process"`, `resource` `"exit"`). Hosts take exit requests through an exit handler they install; elsewhere the call throws `ERR_FEATURE_UNAVAILABLE_ON_PLATFORM`. On macOS, this closes the surface window. In a browser, it stops the app and clears its surface while keeping the host page open. An embedding host controls how its surface handles the request. Gallery denies this capability so its **Request host exit** action demonstrates permission handling and keeps the demo open.

## Network permissions and boundaries

Global `fetch` retains NSH's streaming HTTP implementation, checking `network.hosts` or `network.http` for requests and redirect hops. WebSocket supports `ws:` / `wss:`, text and binary messages, event listeners and closing handshakes. A WebSocket handshake is an HTTP GET, so both the global `WebSocket` and the `websocket` module's `connect` use the HTTP grants: `ws` is checked as `http` and `wss` as `https`, using GET (a rule may also list `ws` / `wss` in `schemes`). NSH checks the initial normalized URL before starting the connection. The native handshake connects to that URL and rejects redirects; browser WebSocket redirects and connection policy are controlled by the browser. Both APIs refuse a URL with credentials or a fragment. Each VM holds at most 32 WebSockets across both APIs, and messages are at most 8 MiB in both.

A URL the app is not granted is refused before any connection starts. The global `WebSocket` reports it as a browser reports a connection that fails: the constructor returns the socket, which then fires `error` and `close` (code 1006, `wasClean` `false`), so the handlers the app sets right after the constructor hear them. The module's `connect` rejects with `ERR_ACCESS_DENIED` (`permission` `"network"`, `resource` the URL). The 33rd WebSocket throws (the constructor) or rejects (`connect`) with `ERR_NSH_QUOTA_EXCEEDED`, and a malformed URL is a `SyntaxError` (the constructor) or a `TypeError` (`connect`).

The global `WebSocket` queues at most eight messages to send, with at most 8 MiB buffered (`bufferedAmount`); `send()` past either throws `ERR_NSH_QUOTA_EXCEEDED`, and once the socket is closing, `send()` discards its data, as a browser's does. Its handshake and each write time out after 30 seconds, and closing waits up to 5 seconds for the peer's close frame. Messages are delivered as `message` events as they arrive.

The `websocket` module's `WebSocketConnection` holds at most eight pending operations (reads, writes, close) and at most 8 MiB of writes not sent yet; a `write()` past either rejects with `ERR_NSH_QUOTA_EXCEEDED`, and a message past 8 MiB with a `RangeError` (`code` `ERR_OUT_OF_RANGE`). One `read()` may wait at a time; a second rejects with a `TypeError`. Messages that arrive before they are read wait for the app, and their flow follows its reads: while eight messages or 8 MiB wait unread, the connection stops reading from the network, so the peer's sending waits too, and reading resumes as the app reads. Resolving, connecting and the handshake together, each write and closing time out after 30 seconds.

`read()` resolves the messages in arrival order. Once the connection has closed cleanly (the peer closed it, or the app called `close()`) and every message that came before is read, `read()` resolves `null`, as a `net` socket's does at EOF; `closeCode` and `closeReason` then hold the close frame's code and reason (`null` while the connection is open; 1005 for a close frame without a code, 1006 for a connection that ended without a closing handshake). `read()` rejects only for a failure, after the messages that came before it, with its `code`: `ERR_SOCKET_CLOSED` for a connection that ended without a closing handshake, `ETIMEDOUT`, the OS's code for a socket error, or `EPROTO` for a protocol error (with the HTTP `status` of a refused handshake). `close(code?, reason?)` sends its code (1000, the default, or 3000 to 4999) and reason (at most 123 UTF-8 bytes) in the close frame, as the global `WebSocket`'s `close()` does; a code or reason outside these rejects with a `RangeError` (`code` `ERR_OUT_OF_RANGE`). It discards the messages not read yet and resolves once the peer answers the closing handshake.

```tsx
import { connect } from "websocket";

const socket = await connect("wss://chat.example.com/socket");
await socket.write("hello");
for (let message; (message = await socket.read()) !== null; ) {
  console.log(message);
}
console.log(`closed: ${socket.closeCode} ${socket.closeReason}`);
```

`net.connect({ host, port })` uses only `network.sockets`, a list of exact `"host:port"` destinations (`"[::1]:9000"` for IPv6), checked before DNS lookup. Each entry grants one port on one host; host patterns, `network.hosts` and HTTP grants cover HTTP traffic only, and an app without `"capabilities"` lists its sockets too. The returned `Socket` provides `read(size?)`, `write(text)` and `close()`; reads return `Uint8Array`, or `null` at EOF. Every failure rejects: a destination not granted with `ERR_ACCESS_DENIED` (`permission` `"network"`, `resource` `"host:port"`), the 33rd socket and writes past the 4 MiB that may wait with `ERR_NSH_QUOTA_EXCEEDED`, a read or write past 1 MiB with a `RangeError` (`code` `ERR_OUT_OF_RANGE`); connection and I/O failures reject with Node's `code` (`ECONNREFUSED`, `ENOTFOUND`, `ETIMEDOUT`, `ECONNRESET`, ...) and `syscall`, a connection's also with `address` and `port`, and a write on a closed socket with `ERR_SOCKET_CLOSED` (a read there returns `null`). Connections and I/O have 30-second timeouts, each read/write is limited to 1 MiB, at most 4 MiB of writes may wait to be sent, and `close()` ends pending reads and writes at once. Each VM keeps at most 32 sockets open or connecting. This is a promise-based client socket interface.

Raw TCP uses native hosts. Both WebSocket interfaces use the browser transport in web apps, retaining Rust capability checks and the limits above. Custom browser handshake headers report an explicit unsupported-option error. Browser connection policies also apply. Embedding grants intersect the app's capability declaration.

## WebSocket grant example

This `nsh.json` fragment permits the GET handshake for this `wss` URL, keeping its path and HTTPS scope:

```json
{
  "capabilities": {
    "network": {
      "http": [{
        "host": "chat.example.com",
        "methods": ["GET"],
        "schemes": ["https"],
        "pathPrefix": "/socket"
      }]
    }
  }
}
```

```rust
use futures_util::{SinkExt, StreamExt};
use tokio_tungstenite::{connect_async, tungstenite::Message};

spawn(async move {
    let _ = background(async {
        let (mut socket, _) = connect_async("wss://chat.example.com/socket").await?;
        socket.send(Message::text("hello")).await?;
        while let Some(message) = socket.next().await {
            log::info!("{}", message?);
        }
        Ok::<_, tokio_tungstenite::tungstenite::Error>(())
    })
    .await;
});
```

```tsx
const socket = new WebSocket("wss://chat.example.com/socket");
socket.addEventListener("open", () => socket.send("hello"));
socket.addEventListener("message", (event) => console.log(event.data));
```

## TCP grant example

TCP uses a socket grant: the exact host and port the app connects to.

```json
{
  "capabilities": {
    "network": { "sockets": ["tcp.example.com:9000"] }
  }
}
```

```rust
use std::{
    io::{Read, Write},
    net::TcpStream,
};

spawn(async move {
    let reply = blocking(|| -> std::io::Result<String> {
        let mut socket = TcpStream::connect(("tcp.example.com", 9000))?;
        socket.write_all(b"hello\n")?;
        let mut bytes = [0; 1024];
        let n = socket.read(&mut bytes)?;
        Ok(String::from_utf8_lossy(&bytes[..n]).into_owned())
    })
    .await;
    if let Ok(Ok(reply)) = reply {
        log::info!("{reply}");
    }
});
```

```tsx
import { connect } from "net";

const socket = await connect({ host: "tcp.example.com", port: 9000 });
try {
  await socket.write("hello\n");
  const bytes = await socket.read(1024);
  if (bytes) console.log(new TextDecoder().decode(bytes));
} finally {
  socket.close();
}
```

## Gallery

Open **Standard APIs** in `examples/gallery` to run file operations, child processes, TCP and both WebSocket interfaces, and inspect host metadata and queued jobs. The utilities action demonstrates buffers, hashing, compression and file URLs. Each action displays its result or error. Files stay in a temporary directory under the gallery's own data directory and are removed after the action. The TCP and WebSocket actions connect to local echo servers on ports 9876 and 9877. On web, file actions exercise OPFS, utilities run in WebAssembly, and both WebSocket actions use browser connections; process and TCP actions display the host's typed platform errors.

Gallery's **AI Chat** uses `process.spawn` to chat through a locally installed Claude or Codex CLI on desktop. Sign in through the CLI in a terminal, then choose the provider in the composer. Replies use the conversation as context; Stop and leaving the screen end the child process. Web and mobile run scripted streaming conversations, including reasoning, tool cards and error recovery.

Source: https://nsh.dev/versions/main/modules/standard-modules

---

# Global APIs

Besides the ECMAScript standard library, an NSH app's JS environment has a set of standard globals: `fetch` with `Headers`, `Request` and `Response`; the Streams Standard; `URL` and `URLSearchParams`; `TextEncoder` / `TextDecoder`; `Blob`, `File` and `FormData`; `EventTarget`, `Event` and `AbortController`; timers, `requestAnimationFrame` and `console`; and `Intl` for number and date formatting. They are implemented natively in Rust, follow the WHATWG standards, and need no import, so the many JavaScript libraries built on these standards (HTTP clients, URL and encoding helpers, stream utilities) work unchanged.

This page lists every global an app has. These are the TSX environment's: Rust code uses Rust's standard library, crates.io and NSH's services of `nsh_core::prelude` instead (`fetch`, timers, tasks; see [Building with Rust](https://nsh.dev/versions/main/docs/rust.md)), named in the table's Rust column. UI is built with [elements](https://nsh.dev/versions/main/elements.md) and the app's own components, and everything else an app uses comes from the [modules](https://nsh.dev/versions/main/modules.md) it imports.

The TypeScript declarations of all of these are generated into `.nsh/types/nsh/globals.d.ts` (see [Project structure](https://nsh.dev/versions/main/docs/project-structure.md)).

| Group | Globals | Rust |
|---|---|---|
| [Console and timing](#console-and-timing) | `console`, `performance` | the `log` crate (`log::info!`, ...), `nsh_core::time::now()` |
| [Timers and frames](#timers-and-frames) | `setTimeout`, `setInterval`, `clearTimeout`, `clearInterval`, `queueMicrotask`, `requestAnimationFrame`, `cancelAnimationFrame` | `set_timeout`, `set_interval`, `timer(delay).await`, `request_animation_frame`, `next_frame().await`, `Spawned::cancel()` |
| [Base64 and errors](#base64-and-errors) | `atob`, `btoa`, `DOMException` | the `base64` crate, `Result` |
| [Events and abort signals](#events-and-abort-signals) | `EventTarget`, `Event`, `CustomEvent`, `AbortController`, `AbortSignal` | signals and closures; `Spawned::cancel()` ends a task |
| [URLs](#urls) | `URL`, `URLSearchParams` | the `url` crate |
| [Text encoding](#text-encoding) | `TextEncoder`, `TextDecoder` | `str::as_bytes`, `String::from_utf8` |
| [Blobs and form data](#blobs-and-form-data) | `Blob`, `File`, `FormData` | `Vec<u8>` bodies of `HttpRequest` |
| [Fetch](#fetch) | `fetch`, `Headers`, `Request`, `Response` | `fetch`, `HttpRequest`, `HttpResponse` |
| [Number and date formatting](#number-and-date-formatting) | `Intl.NumberFormat`, `Intl.DateTimeFormat`, `toLocaleString` | `format!` and crates.io's formatting crates, with `locale()` |
| [Streams](#streams) | `ReadableStream`, `WritableStream`, `TransformStream`, readers, writers, controllers, `ByteLengthQueuingStrategy`, `CountQueuingStrategy`, `TextEncoderStream`, `TextDecoderStream` | `fetch` gives the whole body; `background` tasks run long-lived connections on native targets |

Native hosts also provide `Buffer`, `crypto`, `process` and `WebSocket`; see [Standard modules](https://nsh.dev/versions/main/modules/standard-modules.md) for their modules, permissions and resource limits.

## Console and timing

```ts
declare var console: {
  log(...data: unknown[]): void;
  info(...data: unknown[]): void;
  debug(...data: unknown[]): void;
  warn(...data: unknown[]): void;
  error(...data: unknown[]): void;
};

declare var performance: {
  /** Milliseconds since the JS context started, with sub-millisecond precision. */
  now(): number;
};
```

In Rust, the `log` crate's macros (`log::info!`, `log::warn!`, ...) write to the same log, and appear in the terminal of `nsh run` too. `console` writes one line per call to the runtime's log (target `js`): `log` and `info` at info level, `debug`, `warn` and `error` at their levels. Arguments are joined with spaces; strings print verbatim, errors with their stack, functions as `[Function name]`, and objects and arrays as JSON (falling back to `String(value)` for cycles).

While a device is connected to the dev server, its log lines appear in the terminal running `nsh run` / `nsh dev`, prefixed with the device name; see [Dev server and debugging](https://nsh.dev/versions/main/docs/dev-server-and-debugging.md).

> [!NOTE]
> Only the five methods above exist. There is no `console.table`, `console.group`, `console.time` or `console.assert`, and no `%s` / `%o` format substitutions.

`performance.now()` is the clock `requestAnimationFrame` passes to its callbacks; in Rust, `nsh_core::time::now()` and the `Instant`s that `request_animation_frame` and `next_frame()` give are that clock. `performance` has no other members.

## Timers and frames

```ts
function setTimeout(handler: (...args: any[]) => void, timeout?: number, ...args: any[]): number;
function setInterval(handler: (...args: any[]) => void, timeout?: number, ...args: any[]): number;
function clearTimeout(id: number | undefined): void;
function clearInterval(id: number | undefined): void;
function queueMicrotask(callback: () => void): void;
/** Runs `callback` at the next display frame with its time in milliseconds. */
function requestAnimationFrame(callback: (time: number) => void): number;
function cancelAnimationFrame(id: number): void;
```

Rust: `set_timeout(delay, f)` and `set_interval(period, f)` return a `Spawned` handle whose `cancel()` clears them, `timer(delay).await` waits in a task, and `request_animation_frame(f)` / `next_frame().await` give the next frame's time; all of them end with the component that made them. Timers behave as in browsers: a missing, negative or non-finite delay is 0, the returned id is a positive integer, and clearing an unknown id does nothing. `handler` must be a function (string handlers are not evaluated). Timers do not clamp nested delays to 4 ms.

> [!WARNING]
> The extra `...args` of `setTimeout` / `setInterval` are declared but currently not passed to the handler. Use a closure instead: `setTimeout(() => save(id), 100)`.

`requestAnimationFrame` callbacks run once, at the next frame the engine produces, all with the same `performance.now()` time. A callback that requests another frame is called at the following frame, so the usual loop works:

```rust
spawn(async move {
    let start = next_frame().await;
    loop {
        let time = next_frame().await;
        let elapsed = time.duration_since(start).as_secs_f32() * 1000.0;
        progress.set((elapsed / 300.0).min(1.0));
        if elapsed >= 300.0 {
            break;
        }
    }
});
```

```tsx
let start = 0;
function tick(time: number) {
  if (!start) start = time;
  progress.set(Math.min(1, (time - start) / 300));
  if (time - start < 300) requestAnimationFrame(tick);
}
requestAnimationFrame(tick);
```

> [!TIP]
> Driving an animation from JS frame by frame runs your code on every frame in QuickJS. For animations of styles and transforms, prefer [`nsh`'s animation API](https://nsh.dev/versions/main/modules/nsh.md#animation), whose drivers run natively without calling back into JS (see [Animation](https://nsh.dev/versions/main/docs/animation.md)).

## Base64 and errors

```ts
function atob(data: string): string;
function btoa(data: string): string;

class DOMException extends Error {
  constructor(message?: string, name?: string);
  readonly name: string;
  readonly message: string;
  readonly code: number;
}
```

`atob` / `btoa` convert between binary strings and Base64 as in browsers. `DOMException` is what aborted operations reject with: an `AbortController.abort()` without a reason gives a `DOMException` named `"AbortError"`, and `AbortSignal.timeout` one named `"TimeoutError"`.

## Events and abort signals

```ts
class EventTarget {
  constructor();
  addEventListener(type: string, listener: EventListenerOrEventListenerObject | null,
    options?: AddEventListenerOptions | boolean): void;
  removeEventListener(type: string, listener: EventListenerOrEventListenerObject | null,
    options?: { capture?: boolean } | boolean): void;
  dispatchEvent(event: Event): boolean;
}

interface AddEventListenerOptions {
  capture?: boolean;
  once?: boolean;
  passive?: boolean;
  signal?: AbortSignal;
}

class Event {
  constructor(type: string, init?: { bubbles?: boolean; cancelable?: boolean; composed?: boolean });
  readonly type: string;
  readonly target: EventTarget | null;
  readonly currentTarget: EventTarget | null;
  readonly eventPhase: number; // NONE 0, CAPTURING_PHASE 1, AT_TARGET 2, BUBBLING_PHASE 3
  readonly bubbles: boolean;
  readonly cancelable: boolean;
  readonly defaultPrevented: boolean;
  readonly composed: boolean;
  readonly isTrusted: boolean;
  readonly timeStamp: number;
  returnValue: boolean;
  cancelBubble: boolean;
  readonly srcElement: EventTarget | null; // legacy: `target`
  initEvent(type: string, bubbles?: boolean, cancelable?: boolean): void; // legacy
  composedPath(): EventTarget[];
  preventDefault(): void;
  stopPropagation(): void;
  stopImmediatePropagation(): void;
}

class CustomEvent<T = any> extends Event {
  constructor(type: string, init?: EventInit & { detail?: T });
  readonly detail: T;
}

class AbortController {
  readonly signal: AbortSignal;
  abort(reason?: any): void;
}

class AbortSignal extends EventTarget {
  readonly aborted: boolean;
  readonly reason: any;
  onabort: ((event: Event) => void) | null;
  throwIfAborted(): void;
  static abort(reason?: any): AbortSignal;
  static timeout(milliseconds: number): AbortSignal;
  static any(signals: Iterable<AbortSignal>): AbortSignal;
}
```

These are the DOM Standard's classes with one difference: there is no tree, so an event is dispatched to its target only. Capture listeners run first, then the others, as the DOM does at the target; `bubbles` has no effect. The classes can be subclassed, which makes `EventTarget` a small event emitter:

```ts
class Channel extends EventTarget {
  send(message: string) {
    this.dispatchEvent(new CustomEvent("message", { detail: message }));
  }
}

const channel = new Channel();
channel.addEventListener("message", (e) => console.log((e as CustomEvent<string>).detail));
channel.send("hello");
```

These events are unrelated to the events of elements (`onPress`, `onChange`, ...), which are props; see [Touch and gestures](https://nsh.dev/versions/main/docs/touch-and-gestures.md).

`AbortSignal` cancels `fetch` requests and stream pipes, and removes listeners added with `{ signal }`. In Rust, a request runs in a task, and cancelling the task cancels it:

```rust
let search = spawn(async move {
    let _ = fetch("https://api.example.com/search?q=nsh").await;
});
// later, for example when the screen closes (a task also ends with its component):
search.cancel();
```

```tsx
const controller = new AbortController();
const signal = AbortSignal.any([controller.signal, AbortSignal.timeout(10_000)]);
fetch("https://api.example.com/search?q=nsh", { signal }).catch((e) => {
  if (e.name === "AbortError" || e.name === "TimeoutError") return;
  throw e;
});
// later, for example when the screen closes:
controller.abort();
```

## URLs

```ts
class URL {
  constructor(url: string | URL, base?: string | URL);
  static canParse(url: string | URL, base?: string | URL): boolean;
  static parse(url: string | URL, base?: string | URL): URL | null;
  /** A `blob:` URL `fetch` reads `blob` from, until revoked. */
  static createObjectURL(blob: Blob): string;
  static revokeObjectURL(url: string): void;
  href: string;
  readonly origin: string;
  protocol: string;
  username: string;
  password: string;
  host: string;
  hostname: string;
  port: string;
  pathname: string;
  search: string;
  hash: string;
  readonly searchParams: URLSearchParams;
  toString(): string;
  toJSON(): string;
}

class URLSearchParams {
  constructor(init?: string | Record<string, string> | Iterable<[string, string]> | URLSearchParams);
  readonly size: number;
  append(name: string, value: string): void;
  delete(name: string, value?: string): void;
  get(name: string): string | null;
  getAll(name: string): string[];
  has(name: string, value?: string): boolean;
  set(name: string, value: string): void;
  sort(): void;
  forEach(callback: (value: string, key: string, parent: URLSearchParams) => void, thisArg?: unknown): void;
  entries(): IterableIterator<[string, string]>;
  keys(): IterableIterator<string>;
  values(): IterableIterator<string>;
  [Symbol.iterator](): IterableIterator<[string, string]>;
  toString(): string;
}
```

URLs are parsed per the URL Standard. A URL's `searchParams` is live in both directions: changing the parameters rewrites the query, and setting `search` or `href` parses it again. Rust code uses the `url` crate, which follows the same standard:

```rust
let mut url = url::Url::parse("https://api.example.com")?.join("/v1/items")?;
url.query_pairs_mut().append_pair("page", "2").append_pair("tag", "new");
url.as_str(); // "https://api.example.com/v1/items?page=2&tag=new"
```

```tsx
const url = new URL("/v1/items", "https://api.example.com");
url.searchParams.set("page", "2");
url.searchParams.append("tag", "new");
url.href; // "https://api.example.com/v1/items?page=2&tag=new"
```

The iterators of `URLSearchParams` (and of `Headers` and `FormData`) iterate over a snapshot taken when the iterator was created, and have the iterator helpers (`map`, `filter`, `toArray`, ...).

`URL.createObjectURL(blob)` returns a `blob:` URL that `fetch` (with `GET`) can read until `revokeObjectURL` is called. `<Image>` shows one as its `src` or `placeholder` ([Image](https://nsh.dev/versions/main/elements/image.md)).

## Text encoding

```ts
class TextEncoder {
  readonly encoding: "utf-8";
  encode(input?: string): Uint8Array;
  encodeInto(source: string, destination: Uint8Array): { read: number; written: number };
}

/** UTF-8, UTF-16LE / BE and windows-1252 (with the labels of latin1 and ASCII). */
class TextDecoder {
  constructor(label?: string, options?: { fatal?: boolean; ignoreBOM?: boolean });
  readonly encoding: string;
  readonly fatal: boolean;
  readonly ignoreBOM: boolean;
  decode(input?: BufferSource, options?: { stream?: boolean }): string;
}
```

`TextDecoder` knows fewer encodings than a browser: UTF-8, UTF-16LE, UTF-16BE and windows-1252 (which the labels `latin1`, `iso-8859-1`, `ascii` and the like also name, as the Encoding Standard specifies). Other labels throw a `RangeError`. With `{ stream: true }`, a multi-byte sequence cut between two chunks is kept for the next call.

## Blobs and form data

```ts
class Blob {
  constructor(blobParts?: Iterable<BlobPart>, options?: { type?: string; endings?: "transparent" | "native" });
  readonly size: number;
  readonly type: string;
  slice(start?: number, end?: number, contentType?: string): Blob;
  arrayBuffer(): Promise<ArrayBuffer>;
  bytes(): Promise<Uint8Array>;
  text(): Promise<string>;
  stream(): ReadableStream<Uint8Array>;
}

class File extends Blob {
  constructor(fileBits: Iterable<BlobPart>, fileName: string,
    options?: { type?: string; endings?: "transparent" | "native"; lastModified?: number });
  readonly name: string;
  readonly lastModified: number;
  readonly webkitRelativePath: string;
}

class FormData {
  constructor();
  append(name: string, value: string | Blob, fileName?: string): void;
  delete(name: string): void;
  get(name: string): File | string | null;
  getAll(name: string): (File | string)[];
  has(name: string): boolean;
  set(name: string, value: string | Blob, fileName?: string): void;
  forEach(callback: (value: File | string, key: string, parent: FormData) => void, thisArg?: unknown): void;
  entries(): IterableIterator<[string, File | string]>;
  keys(): IterableIterator<string>;
  values(): IterableIterator<File | string>;
  [Symbol.iterator](): IterableIterator<[string, File | string]>;
}

type BlobPart = ArrayBuffer | ArrayBufferView | Blob | string;
```

A blob holds its bytes in memory, and `slice` shares them instead of copying. Blobs are in-memory values only: there is no file system access behind `File`, and `FormData` has no constructor from a form element.

A `FormData` body is sent as `multipart/form-data`, and `Response.formData()` / `Request.formData()` parse both `multipart/form-data` and `application/x-www-form-urlencoded`.

```ts
const form = new FormData();
form.append("title", "Holiday");
form.append("photo", new Blob([bytes], { type: "image/jpeg" }), "photo.jpg");
await fetch("https://api.example.com/upload", { method: "POST", body: form });
```

## Fetch

```ts
/**
 * HTTP through the platform's network stack (NSURLSession,
 * HttpURLConnection), streaming both ways; `data:` and `blob:` URLs are
 * answered locally, and `asset:/` URLs with the app's bundled files.
 */
function fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;

interface RequestInit {
  method?: string;
  headers?: HeadersInit;
  /** A ReadableStream is sent as it is read (chunked), with `duplex: "half"`. */
  body?: BodyInit | null;
  duplex?: "half";
  signal?: AbortSignal | null;
  /** "manual" gives the 3xx response itself. */
  redirect?: "follow" | "manual" | "error";
  credentials?: "omit" | "same-origin" | "include";
  cache?: "default" | "no-store" | "reload" | "no-cache" | "force-cache" | "only-if-cached";
  mode?: "same-origin" | "no-cors" | "cors";
  referrer?: string;
  referrerPolicy?: string;
  integrity?: string;
  keepalive?: boolean;
  priority?: "high" | "low" | "auto";
}

type HeadersInit = Headers | Record<string, string> | Iterable<[string, string]>;
type BodyInit = ReadableStream<Uint8Array> | Blob | BufferSource | FormData | URLSearchParams | string;
```

`fetch` sends HTTP and HTTPS requests through the platform's own network stack: `NSURLSession` on iOS and Mac Catalyst, `HttpURLConnection` on Android. So the system's proxy settings, TLS configuration and certificate trust apply. `data:` URLs and `blob:` URLs (from `URL.createObjectURL`) are answered locally without touching the network; any other scheme rejects. Rust's `fetch(request)` goes through the same stack and the same capabilities, takes a URL or an `HttpRequest`, and resolves with an `HttpResponse` holding the whole body ([Networking](https://nsh.dev/versions/main/docs/networking.md#from-rust-components)):

```rust
#[derive(serde::Deserialize)]
struct Todo {
    id: u32,
    title: String,
    done: bool,
}

async fn load_todos(token: &str) -> Result<Vec<Todo>, String> {
    let request = HttpRequest::get("https://api.example.com/todos").header("Authorization", format!("Bearer {token}"));
    let response = fetch(request).await?;
    if !response.ok() {
        return Err(format!("HTTP {}", response.status()));
    }
    serde_json::from_slice(&response.body).map_err(|e| e.to_string())
}
```

```tsx
type Todo = { id: number; title: string; done: boolean };

async function loadTodos(): Promise<Todo[]> {
  const res = await fetch("https://api.example.com/todos", {
    headers: { Authorization: `Bearer ${token}` },
  });
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return res.json();
}
```

### Headers, Request and Response

```ts
class Headers {
  constructor(init?: HeadersInit);
  append(name: string, value: string): void;
  delete(name: string): void;
  get(name: string): string | null;
  getSetCookie(): string[];
  has(name: string): boolean;
  set(name: string, value: string): void;
  forEach(callback: (value: string, key: string, parent: Headers) => void, thisArg?: unknown): void;
  entries(): IterableIterator<[string, string]>;
  keys(): IterableIterator<string>;
  values(): IterableIterator<string>;
  [Symbol.iterator](): IterableIterator<[string, string]>;
}

interface Body {
  /** The body as it arrives (a byte stream), or null. */
  readonly body: ReadableStream<Uint8Array> | null;
  readonly bodyUsed: boolean;
  arrayBuffer(): Promise<ArrayBuffer>;
  blob(): Promise<Blob>;
  bytes(): Promise<Uint8Array>;
  formData(): Promise<FormData>;
  json(): Promise<any>;
  text(): Promise<string>;
}

class Request implements Body {
  constructor(input: string | URL | Request, init?: RequestInit);
  readonly method: string;
  readonly url: string;
  readonly headers: Headers;
  readonly destination: string;
  readonly referrer: string;
  readonly referrerPolicy: string;
  readonly mode: string;
  readonly credentials: string;
  readonly cache: string;
  readonly redirect: "follow" | "manual" | "error";
  readonly integrity: string;
  readonly keepalive: boolean;
  readonly isReloadNavigation: boolean;
  readonly isHistoryNavigation: boolean;
  readonly signal: AbortSignal;
  readonly duplex: "half";
  clone(): Request;
  // ...and the Body members
}

class Response implements Body {
  constructor(body?: BodyInit | null, init?: { status?: number; statusText?: string; headers?: HeadersInit });
  static json(data: unknown, init?: ResponseInit): Response;
  static error(): Response;
  static redirect(url: string | URL, status?: number): Response;
  readonly type: "basic" | "default" | "error";
  readonly url: string;
  readonly redirected: boolean;
  readonly status: number;
  readonly ok: boolean;
  readonly statusText: string;
  readonly headers: Headers;
  clone(): Response;
  // ...and the Body members
}
```

### Streaming

A response's `body` is a byte stream filled as the network delivers data, so large or long-lived responses (downloads, server-sent events, streamed model output) can be processed while they arrive. When more than 1 MiB is waiting unread, the request is paused until the app reads again.

```ts
const res = await fetch("https://api.example.com/events");
const lines = res.body!.pipeThrough(new TextDecoderStream());
for await (const chunk of lines) {
  console.log(chunk);
}
```

A `ReadableStream` request body is uploaded chunk by chunk as the network asks for it; pass `duplex: "half"` as the Fetch Standard requires:

```ts
await fetch("https://api.example.com/upload", {
  method: "PUT",
  body: blob.stream(),
  duplex: "half",
});
```

### Differences from browsers

- **No CORS and no origin.** An app is not a web page: it may talk to any host its [capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md) allow. `mode` is accepted and ignored.
- **No forbidden headers.** An app may set `Cookie`, `User-Agent`, `Origin` and any other header. When no `Accept` header is given, `Accept: */*` is sent.
- **`redirect: "manual"` delivers the 3xx response itself**, with its status and `Location` header, instead of an opaque filtered response. `"follow"` follows redirects (each hop is checked against the capabilities); `"error"` rejects when the response is a redirect.
- **A `FormData` body always gets `Content-Type: multipart/form-data; boundary=…`**, even when a `Content-Type` header was set. HTTP libraries often set a default content type and clear it only where they detect a browser; without the boundary the server cannot parse the body.
- **`credentials`, `cache`, `referrer`, `referrerPolicy`, `integrity`, `keepalive` and `priority`** are validated and kept on the `Request` object, but are not passed to the network stack: caching and cookie handling are those of the platform's stack.
- **Capabilities.** When the app declares `network` capabilities in `nsh.json` (or the embedding app grants fewer), a request to a host that is not allowed never reaches the network and `fetch` rejects with a `TypeError` whose `code` is `"ERR_ACCESS_DENIED"`, `permission` `"network"` and `resource` the URL refused. See [Sandbox and capabilities](https://nsh.dev/versions/main/docs/sandbox-and-capabilities.md).
- **Errors.** Network failures reject with a `TypeError` whose message starts with `Network request failed:`; aborts reject with the signal's `reason`.

See [Networking](https://nsh.dev/versions/main/docs/networking.md) for a guide to loading data in components.

## Streams

The full WHATWG Streams Standard: readable streams (default and byte streams, BYOB readers, `tee`, `pipeTo` / `pipeThrough`, `ReadableStream.from`, async iteration), writable streams, transform streams, the two queuing strategies and the text encoding streams.

```ts
class ReadableStream<R = any> {
  constructor(underlyingSource: UnderlyingByteSource, strategy?: { highWaterMark?: number });
  constructor(underlyingSource?: UnderlyingDefaultSource<R>, strategy?: QueuingStrategy<R>);
  static from<R>(iterable: Iterable<R | PromiseLike<R>> | AsyncIterable<R>): ReadableStream<R>;
  readonly locked: boolean;
  cancel(reason?: any): Promise<void>;
  getReader(options: { mode: "byob" }): ReadableStreamBYOBReader;
  getReader(): ReadableStreamDefaultReader<R>;
  pipeThrough<T>(transform: { writable: WritableStream<R>; readable: ReadableStream<T> },
    options?: StreamPipeOptions): ReadableStream<T>;
  pipeTo(destination: WritableStream<R>, options?: StreamPipeOptions): Promise<void>;
  tee(): [ReadableStream<R>, ReadableStream<R>];
  values(options?: { preventCancel?: boolean }): AsyncIterableIterator<R>;
  [Symbol.asyncIterator](options?: { preventCancel?: boolean }): AsyncIterableIterator<R>;
}

class ReadableStreamDefaultReader<R = any> {
  constructor(stream: ReadableStream<R>);
  readonly closed: Promise<void>;
  read(): Promise<{ done: false; value: R } | { done: true; value?: R }>;
  releaseLock(): void;
  cancel(reason?: any): Promise<void>;
}

class ReadableStreamBYOBReader {
  constructor(stream: ReadableStream<Uint8Array>);
  readonly closed: Promise<void>;
  read<T extends ArrayBufferView>(view: T, options?: { min?: number }): Promise<ReadableStreamReadResult<T>>;
  releaseLock(): void;
  cancel(reason?: any): Promise<void>;
}

class ReadableStreamDefaultController<R = any> {
  readonly desiredSize: number | null;
  close(): void;
  enqueue(chunk?: R): void;
  error(e?: any): void;
}

class ReadableByteStreamController {
  readonly byobRequest: ReadableStreamBYOBRequest | null;
  readonly desiredSize: number | null;
  close(): void;
  enqueue(chunk: ArrayBufferView): void;
  error(e?: any): void;
}

class ReadableStreamBYOBRequest {
  readonly view: ArrayBufferView | null;
  respond(bytesWritten: number): void;
  respondWithNewView(view: ArrayBufferView): void;
}

class WritableStream<W = any> {
  constructor(underlyingSink?: UnderlyingSink<W>, strategy?: QueuingStrategy<W>);
  readonly locked: boolean;
  abort(reason?: any): Promise<void>;
  close(): Promise<void>;
  getWriter(): WritableStreamDefaultWriter<W>;
}

class WritableStreamDefaultWriter<W = any> {
  constructor(stream: WritableStream<W>);
  readonly closed: Promise<void>;
  readonly desiredSize: number | null;
  readonly ready: Promise<void>;
  abort(reason?: any): Promise<void>;
  close(): Promise<void>;
  releaseLock(): void;
  write(chunk?: W): Promise<void>;
}

class WritableStreamDefaultController {
  readonly signal: AbortSignal;
  error(e?: any): void;
}

class TransformStream<I = any, O = any> {
  constructor(transformer?: Transformer<I, O>, writableStrategy?: QueuingStrategy<I>,
    readableStrategy?: QueuingStrategy<O>);
  readonly readable: ReadableStream<O>;
  readonly writable: WritableStream<I>;
}

class TransformStreamDefaultController<O = any> {
  readonly desiredSize: number | null;
  enqueue(chunk?: O): void;
  error(reason?: any): void;
  terminate(): void;
}

class ByteLengthQueuingStrategy {
  constructor(init: { highWaterMark: number });
  readonly highWaterMark: number;
  readonly size: (chunk: ArrayBufferView) => number;
}

class CountQueuingStrategy {
  constructor(init: { highWaterMark: number });
  readonly highWaterMark: number;
  readonly size: (chunk: any) => 1;
}

class TextEncoderStream {
  readonly encoding: "utf-8";
  readonly readable: ReadableStream<Uint8Array>;
  readonly writable: WritableStream<string>;
}

class TextDecoderStream {
  constructor(label?: string, options?: { fatal?: boolean; ignoreBOM?: boolean });
  readonly encoding: string;
  readonly fatal: boolean;
  readonly ignoreBOM: boolean;
  readonly readable: ReadableStream<string>;
  readonly writable: WritableStream<BufferSource>;
}
```

The underlying source, sink and transformer objects (`UnderlyingDefaultSource`, `UnderlyingByteSource`, `UnderlyingSink`, `Transformer`) and `StreamPipeOptions` (`preventAbort`, `preventCancel`, `preventClose`, `signal`) have the standard shapes; their full declarations are in `globals.d.ts`.

`TextEncoderStream` keeps a surrogate pair cut between two string chunks together, and `TextDecoderStream` a multi-byte sequence cut between two byte chunks.

A transform stream that splits text into lines:

```ts
function lines(): TransformStream<string, string> {
  let rest = "";
  return new TransformStream({
    transform(chunk, controller) {
      const parts = (rest + chunk).split("\n");
      rest = parts.pop()!;
      for (const line of parts) controller.enqueue(line);
    },
    flush(controller) {
      if (rest) controller.enqueue(rest);
    },
  });
}

const res = await fetch("https://api.example.com/log");
for await (const line of res.body!.pipeThrough(new TextDecoderStream()).pipeThrough(lines())) {
  console.log(line);
}
```

## Number and date formatting

QuickJS has no `Intl` of its own; NSH adds one, formatting in Rust: `Intl.NumberFormat`, `Intl.DateTimeFormat` and `Intl.getCanonicalLocales`, and the `toLocaleString` of numbers and BigInts and `toLocaleString` / `toLocaleDateString` / `toLocaleTimeString` of dates, which take the same `locales` and `options`. Their declarations are TypeScript's own (the `ES2023` library), so they are not in `globals.d.ts`.

```ts
(1234567.891).toLocaleString();                                              // "1,234,567.891" (en-US)
(1234.5).toLocaleString("de-DE", { style: "currency", currency: "EUR" });  // "1.234,50 €"
new Intl.NumberFormat("en", { notation: "compact" }).format(1_500_000);      // "1.5M"
new Intl.NumberFormat("en", { style: "percent", signDisplay: "exceptZero" }).format(0.042); // "+4%"
new Date().toLocaleTimeString([], { hour: "2-digit", minute: "2-digit", hour12: false });   // "09:05"
new Intl.DateTimeFormat("en-US", { dateStyle: "medium", timeStyle: "short" }).format(date); // "Oct 16, 2026, 3:04 PM"
```

Without `locales`, the device's locale is used: its region format (iOS `NSLocale.currentLocale`, Android `Locale.getDefault()`), `en-US` in `nsh test` and on the web.

- **Numbers**: the `decimal`, `percent`, `currency` (`currencyDisplay` `symbol`, `narrowSymbol`, `code`) and `unit` (common units: lengths, masses, durations, data sizes, temperatures, speeds) styles; `minimumIntegerDigits`, `minimum` / `maximumFractionDigits`, `minimum` / `maximumSignificantDigits`, `roundingPriority`, `trailingZeroDisplay`, `useGrouping`, `signDisplay`; `standard`, `scientific`, `engineering` and `compact` notation (`compactDisplay` `short` / `long`). Rounding is half away from zero, on the number as written (`1.005` rounds to `1.01`, as in browsers). `format` also takes BigInts and decimal strings, exactly. `formatToParts` and `resolvedOptions` work as in browsers.
- **Dates**: `weekday`, `year`, `month` (`numeric`, `2-digit`, `short`, `long`, `narrow`), `day`, `hour`, `minute`, `second`, `fractionalSecondDigits`, `hour12` / `hourCycle`, `timeZoneName` and `dateStyle` / `timeStyle`, in the Gregorian calendar. `timeZone` takes the device's zone (in a browser, the browser's), `UTC` or an offset (`"+08:00"`); other zone names throw a `RangeError` (there is no time zone database).
- **Locales**: the locale data is a table of common languages (English, German, French, Spanish, Italian, Portuguese, Dutch, Russian, Swedish, Polish, Turkish, Indonesian, Vietnamese, Thai, Hindi, Chinese, Japanese, Korean) with their regional variants (`en-GB`, `en-IN`, `de-CH`, `es-MX`, `pt-PT`, `zh-TW`, ...), not the whole of CLDR, so details can differ from a browser's output. A locale without data falls back to the next one asked for, then the device's, then `en-US`; Russian, Swedish, Polish, Turkish, Indonesian, Vietnamese, Thai and Hindi dates have no month names (their months are written as numbers, their weekdays in English). Digits are always Latin.
- **Not there**: `Intl.Collator` (`String.prototype.localeCompare` is QuickJS's, which ignores the locale), `PluralRules`, `RelativeTimeFormat`, `ListFormat`, `DisplayNames`, `Segmenter` and `Intl.Locale`; `currencySign: "accounting"` and `currencyDisplay: "name"` format as `standard` and `code`.

## Performance

All of these classes are native: parsing URLs, encoding and decoding text, building multipart bodies and moving stream chunks happen in Rust, not in QuickJS. Still, every call from JS crosses into the runtime, so prefer whole-buffer operations (`res.json()`, `res.text()`, `encoder.encode(s)`) over byte-by-byte loops in JS. See [Performance](https://nsh.dev/versions/main/docs/performance.md).

Source: https://nsh.dev/versions/main/modules/globals

---

# Style reference

This page lists every key of the `style` prop, and the method of `Styled` that sets it in Rust. Rust components style elements with typed methods named after Tailwind's utilities (`.p_4()`, `.rounded(px(12.0))`, `.bg(color)`, from `nsh_core::prelude`), which lower to the same keys; TSX passes `style` objects (and classes). The Rust column names the method; a value, a signal or a closure goes to most of them, and `.style_when(…)` / `.style_with(…)` make any of them conditional. The keys and their types come from the generated declarations in `.nsh/types/nsh/types.d.ts`, so your editor checks them as you type. A style key means the CSS property of its name, the same as the class that sets it: `paddingLeft` is CSS's `padding-left` and `pl-4`, `boxShadow` is `box-shadow` and `shadow-md`; a few keys take plainer names apps write (`paddingHorizontal` for `padding-inline`, `marginStart` for `margin-inline-start`, `numberOfLines` for `line-clamp`). Numbers are points, and the CSS features are there too: grid, gradients, box shadows, filters, blend modes, outlines, transforms, transitions and keyframe animations.

For how to apply styles, combine them with classes and inherit text styles, see [Styling](https://nsh.dev/versions/main/docs/styling.md). For the class syntax, see the [Tailwind reference](https://nsh.dev/versions/main/modules/tailwind-reference.md).

## The five interfaces

Each interface extends the one before it:

| Interface | Extends | Used by |
|---|---|---|
| `LayoutStyle` | | Layout of every element (flexbox, grid, sizes, spacing, position) |
| `ViewStyle` | `LayoutStyle` | `<View>`, `<Scroll>`, `<List>`, controls and every other element |
| `TextStyle` | `ViewStyle` | `<Text>` and `<Input>` (and views, whose text styles pass to the text inside them) |
| `InputStyle` | `TextStyle` | `<Input>`: adds `placeholderColor` and `caretColor` |
| `ImageStyle` | `ViewStyle` | `<Image>` |

```rust
use nsh_core::prelude::*;

fn card() -> View {
    view().p_4().rounded(px(12.0)).bg(white()).shadow([BoxShadow {
        offset_y: px(4.0),
        blur: px(12.0),
        color: rgba(0x00000014).into(),
        ..BoxShadow::default()
    }])
}

fn title(label: &str) -> Text {
    text(label.to_string()).text_size(px(17.0)).font_weight(FontWeight::SEMIBOLD).text_color(rgb(0x111111))
}

card().child(title("Hello"))
```

```tsx
import type { ViewStyle, TextStyle } from "nsh";
import { Text, View } from "nsh";

const card: ViewStyle = {
  padding: 16,
  borderRadius: 12,
  backgroundColor: "#fff",
  boxShadow: "0 4px 12px rgb(0 0 0 / 0.08)",
};

const title: TextStyle = { fontSize: 17, fontWeight: "600", color: "#111" };

<View style={card}>
  <Text style={title}>Hello</Text>
</View>;
```

`style` also takes an array; entries merge left to right and falsy entries are skipped, so conditional styles need no spreading. In Rust, `.style_when(condition, …)` adds styles while the condition holds:

```rust
card().style_when(selected, |s| s.border_color(rgb(0x2563eb)).border(px(2.0)))
```

```tsx
<View style={[card, selected() && { borderColor: "#2563eb", borderWidth: 2 }]} />
```

> [!NOTE]
> The inline `style` always wins over `class`. Setting a key to `null` or `undefined` resets it to its default.

## How style keys read

Style keys follow CSS, so a style and a class that name one property do the same thing:

- **Layout direction.** A view that sets no `display` lays its children out in a column. `display: "flex"` is a row unless `flexDirection` is set, as in CSS and the `flex` class. `flexShrink` is `0` unless set.
- **Physical and logical sides.** `left`, `right`, `marginLeft`, `paddingRight`, `borderLeftWidth`, `borderTopLeftRadius` and `textAlign: "left"` keep their side in right-to-left layouts. The start and end keys (`marginStart`, `paddingEnd`, `start`, `end`, `borderStartWidth`, ...), the `borderTopStartRadius` family and `textAlign: "start" | "end"` follow the direction: inline start is the left in left-to-right layouts and the right in right-to-left ones.
- **Border colors.** A border or an outline whose width is set and whose color is not is drawn in the text color (CSS's `currentColor`).
- **Transforms.** `translate`, `rotate` and `scale` are properties of their own, and `transform` takes CSS's string of functions or a list of steps whose amounts may be animated values. They compose in that order: `translate`, `rotate`, `scale`, then `transform`.

## Value types

| Type | Accepts | Rust |
|---|---|---|
| `number` | Points (density-independent). `1` is one point on iOS and one dp on Android. | `Points`: `px(16.0)` |
| `DimensionValue` | `number` (points), `` `${number}%` `` (of the parent), or `"auto"`. | `Length`: `px(…)`, `relative(0.5)`, `auto()` |
| `LengthValue` | `number` (points) or `` `${number}%` ``. No `"auto"`. | `DefiniteLength`: `px(…)`, `relative(0.5)` |
| `ColorValue` | A CSS color string: `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`, `rgb()`, `rgba()`, `hsl()`, `hsla()`, `oklch()`, `oklab()`, or a named CSS color (`black`, `white`, `transparent`, `rebeccapurple`, ...). | `Hsla` / `AdaptiveColor`: `rgb(0x2563eb)`, `hsla(…)`, theme colors (`theme().primary`) |
| `EnvValue` | An environment variable in a padding or margin: `env(name)`, `env(name, <length>)` (the length stands in for an unknown name), `calc(env(name) + <length>)` or `calc(<length> + env(name))`. The names are `safe-area-inset-top`, `-right`, `-bottom`, `-left` ([Safe area](https://nsh.dev/versions/main/elements/safe-area.md)) and `keyboard-inset-height` ([Keyboard](https://nsh.dev/versions/main/elements/keyboard.md)). Accepted by the physical padding and margin keys and their shorthands. | `.p_safe_area()`, `.pt_safe_area_plus(px(8.0))`, `.pb_keyboard()`, `.mb_keyboard_plus(…)`, ... |
| `AnimatedNode` | A native animated value or a node derived from it (see [`nsh`'s animation API](https://nsh.dev/versions/main/modules/nsh.md#animation)). Accepted by `opacity`, `backgroundColor`, `borderColor`, `color`, `translate`, `rotate`, `scale`, the steps of a `transform` list, and a sticky view's `top` / `left`; the value then animates on the UI thread without JS. | `AnimatedValue` / `AnimatedNode`, bound with `.bind_opacity(&v)`, `.bind_background(&v)`, `.bind_border_color(&v)`, `.bind_color(&v)`, `.bind_translate_x(&v)`, ... |

Strings with CSS syntax (`boxShadow`, `textShadow`, `backgroundImage`, `filter`, `gridTemplateColumns`, ...) take lengths in `px` and bare numbers (both points), `pt` (4/3 of a point, as in CSS), or `rem` (16 points).

## LayoutStyle

Layout is computed in Rust (flexbox and CSS grid). A view that sets no `display` is a flex container whose children stack in a column; `display: "flex"` makes it a row unless `flexDirection` is set, as in CSS. Elements default to `flexShrink: 0`, `alignContent: "flex-start"` (grids: CSS's `"normal"`), `alignItems: "stretch"`, and no automatic minimum size. See [Layout](https://nsh.dev/versions/main/docs/layout.md).

### Display and position

| Key | Type | Rust | Description |
|---|---|---|---|
| `display` | `"flex" \| "grid" \| "block" \| "flow-root" \| "none"` | `.flex()`, `.grid()`, `.hidden()` | The layout of the children. `"flex"` lays them out in a row unless `flexDirection` sets a direction, as in CSS; a view that sets no display lays them out in a column. `"none"` removes the element from layout and hides it. `"block"` stacks children as CSS block layout does. |
| `boxSizing` | `"border-box" \| "content-box"` | | Dimensions include borders and padding, or content alone. Default `"border-box"`. |
| `position` | `"relative" \| "absolute" \| "static" \| "fixed" \| "sticky"` | `.relative()`, `.absolute()` | `"absolute"` takes the element out of the flow and places it by `top` / `right` / `bottom` / `left` relative to its nearest positioned ancestor (its parent unless that is `"static"`). `"static"` stays in flow and ignores insets. `"fixed"` preserves the element type and lays out and mounts it in its surface or modal root, keeping it in place while surrounding content scrolls. `"sticky"` stays in the flow and, while its parent is in view, sticks `top` (`left` in a horizontal scroll view) from the start of the viewport of the scroll view around it, until its end meets its parent's content box's; it draws above its siblings of the same `zIndex`. Default `"relative"`. |
| `top` | `DimensionValue \| AnimatedNode` | `.top(…)`, `.inset(…)`, `.bind_sticky_top(&node)` | Offset from the parent's top edge (absolute) or from the element's own position (relative). On a sticky view, where it sticks, which an animated value moves every frame. |
| `right` | `DimensionValue` | `.right(…)` | Offset from the right edge, in either direction. |
| `bottom` | `DimensionValue` | `.bottom(…)` | Offset from the bottom edge. |
| `left` | `DimensionValue \| AnimatedNode` | `.left(…)`, `.bind_sticky_left(&node)` | Offset from the left edge, in either direction. On a sticky view in a horizontal scroll view, where it sticks, which an animated value moves every frame. |
| `start` | `DimensionValue` | | Offset from the inline start edge: left in left-to-right layouts, right in right-to-left ones. |
| `end` | `DimensionValue` | | Offset from the inline end edge: right in left-to-right layouts, left in right-to-left ones. |
| `zIndex` | `number` | `.z_index(z)` | Order among siblings (stable for equal values); also the native stacking order. |
| `direction` | `"inherit" \| "ltr" \| "rtl"` | | Layout direction, inherited by default. As in CSS, `left` and `right` properties keep their sides right to left, while the inline start / end ones (`marginStart`, `end`, ...) take the sides the direction gives them. |

### Flexbox

| Key | Type | Rust | Description |
|---|---|---|---|
| `flexDirection` | `"row" \| "column" \| "row-reverse" \| "column-reverse"` | `.flex_row()`, `.flex_col()`, `.flex_row_reverse()`, `.flex_col_reverse()` | The main axis. Default `"column"` for a view that sets no `display`, `"row"` once `display: "flex"` is set. |
| `flexWrap` | `"wrap" \| "nowrap" \| "wrap-reverse"` | `.flex_wrap()` | Whether children wrap onto several lines. Default `"nowrap"`. |
| `flex` | `number` | `.flex_1()`, `.flex_auto()`, `.flex_none()` | One number, not the CSS shorthand: a positive number sets `flexGrow` to it, `flexShrink: 1` and `flexBasis: 0`; `0` makes the element inflexible; a negative number shrinks it down to its minimum size. |
| `flexGrow` | `number` | `.flex_grow(f)` | How much of the free space the element takes. Default `0`. |
| `flexShrink` | `number` | `.flex_shrink(f)`, `.flex_shrink_0()` | How much the element shrinks when space runs out. Default `0`, not `1` as in CSS. |
| `flexBasis` | `DimensionValue` | `.basis(…)` | The main-axis size before free space is distributed. |
| `justifyContent` | `"flex-start" \| "flex-end" \| "start" \| "end" \| "center" \| "space-between" \| "space-around" \| "space-evenly" \| "stretch" \| "normal"` | `.justify_start()`, `.justify_center()`, `.justify_end()`, `.justify_between()`, `.justify_around()`, `.justify_evenly()` | Distribution of children along the main axis. Default `"normal"`: `"flex-start"` in flex containers; in grids, tracks sized `auto` stretch. |
| `alignItems` | `"flex-start" \| "flex-end" \| "start" \| "end" \| "self-start" \| "self-end" \| "center" \| "stretch" \| "baseline" \| "normal"` | `.items_start()`, `.items_center()`, `.items_end()`, `.items_stretch()`, `.items_baseline()` | Alignment of children on the cross axis. Default `"stretch"`. |
| `alignSelf` | `"auto" \| "flex-start" \| "flex-end" \| "start" \| "end" \| "self-start" \| "self-end" \| "center" \| "stretch" \| "baseline" \| "normal"` | `.self_start()`, `.self_center()`, `.self_end()`, `.self_stretch()` | Overrides the parent's `alignItems` for this element. |
| `alignContent` | `"flex-start" \| "flex-end" \| "start" \| "end" \| "center" \| "stretch" \| "space-between" \| "space-around" \| "space-evenly" \| "normal"` | `.content_start()`, `.content_center()`, `.content_between()`, … | Distribution of wrapped lines (and grid tracks) on the cross axis. Default `"flex-start"` in flex containers and `"normal"` in grids, where tracks sized `auto` stretch. `"start"` / `"end"` follow the writing direction. |
| `gap` | `LengthValue` | `.gap(…)`, `.gap_4()` | Space between rows and columns of children. |
| `rowGap` | `LengthValue` | `.gap_y(…)` | Space between rows. |
| `columnGap` | `LengthValue` | `.gap_x(…)` | Space between columns. |

### Grid

Set `display: "grid"` to lay out children in a CSS grid. Track lists use CSS syntax.

| Key | Type | Rust | Description |
|---|---|---|---|
| `gridTemplateColumns` | `string` | `.grid_template_columns(…)`, `.grid_cols(n)` | Column tracks: `"repeat(3, 1fr)"`, `"200px 1fr"`, `minmax()`, `auto-fill` / `auto-fit`, line names (`"[a] 40px [b c] 1fr [d]"`). |
| `gridTemplateRows` | `string` | `.grid_template_rows(…)`, `.grid_rows(n)` | Row tracks, same syntax. |
| `gridAutoColumns` | `string` | | Size of implicitly created columns. |
| `gridAutoRows` | `string` | | Size of implicitly created rows. |
| `gridAutoFlow` | `"row" \| "column" \| "dense" \| "row dense" \| "column dense"` | `.grid_flow_col()`, `.grid_flow_dense()` | How items without a placement fill the grid. |
| `gridColumn` | `number \| string` | `.col_span(n)`, `.col_span_full()` | Column placement: `"1 / 3"`, `"span 2"`, a line number or a line name (`"content-start / content-end"`, `"2 col"`, `"span col"`). |
| `gridColumnStart` | `number \| string` | `.col_start(…)` | Start column line. |
| `gridColumnEnd` | `number \| string` | `.col_end(…)` | End column line. |
| `gridRow` | `number \| string` | `.row_span(n)`, `.row_span_full()` | Row placement, same syntax as `gridColumn`. |
| `gridRowStart` | `number \| string` | `.row_start(…)` | Start row line. |
| `gridRowEnd` | `number \| string` | `.row_end(…)` | End row line. |
| `justifyItems` | `"flex-start" \| "flex-end" \| "start" \| "end" \| "self-start" \| "self-end" \| "center" \| "stretch" \| "baseline" \| "normal"` | | How grid items sit in their areas along the row. |
| `justifySelf` | `"auto" \| "flex-start" \| "flex-end" \| "start" \| "end" \| "self-start" \| "self-end" \| "center" \| "stretch" \| "baseline" \| "normal"` | | Overrides `justifyItems` for this item. |

```rust
view()
    .grid()
    .grid_template_columns("repeat(3, 1fr)")
    .gap_2()
    .child(view().col_span(2).h(px(60.0)).bg(rgb(0xc7d2fe)))
    .child(view().h(px(60.0)).bg(rgb(0xa5b4fc)))
```

```tsx
<View style={{ display: "grid", gridTemplateColumns: "repeat(3, 1fr)", gap: 8 }}>
  <View style={{ gridColumn: "span 2", height: 60, backgroundColor: "#c7d2fe" }} />
  <View style={{ height: 60, backgroundColor: "#a5b4fc" }} />
</View>
```

### Size

| Key | Type | Rust | Description |
|---|---|---|---|
| `width` | `DimensionValue` | `.w(…)`, `.w_full()`, `.size(…)` | Width. |
| `height` | `DimensionValue` | `.h(…)`, `.h_full()` | Height. |
| `minWidth` | `LengthValue` | `.min_w(…)` | Minimum width. |
| `minHeight` | `LengthValue` | `.min_h(…)` | Minimum height. |
| `maxWidth` | `LengthValue` | `.max_w(…)` | Maximum width. |
| `maxHeight` | `LengthValue` | `.max_h(…)` | Maximum height. |
| `aspectRatio` | `number \| "auto" \| "16 / 9"` | `.aspect_ratio(r)`, `.aspect_square()` | Width divided by height, a number (`1.5`) or CSS's ratio (`"16 / 9"`); the missing dimension is computed from the other one. `"auto"` sets none. |

### Margin

Margins accept `"auto"` (absorbs free space, as in flexbox) and negative values. The physical keys (all but `marginStart` / `marginEnd`) also take an `EnvValue`: `marginBottom: "env(keyboard-inset-height)"` (Rust `.mb_keyboard()`, `.mt_safe_area()`, ...).

| Key | Type | Rust | Description |
|---|---|---|---|
| `margin` | `DimensionValue \| EnvValue` | `.m(…)`, `.m_4()` | All four sides. |
| `marginHorizontal` | `DimensionValue \| EnvValue` | `.mx(…)` | Left and right. |
| `marginVertical` | `DimensionValue \| EnvValue` | `.my(…)` | Top and bottom. |
| `marginTop` | `DimensionValue \| EnvValue` | `.mt(…)` | Top. |
| `marginRight` | `DimensionValue \| EnvValue` | `.mr(…)` | Right. |
| `marginBottom` | `DimensionValue \| EnvValue` | `.mb(…)` | Bottom. |
| `marginLeft` | `DimensionValue \| EnvValue` | `.ml(…)` | Left. |
| `marginStart` | `DimensionValue` | `.ms(…)` | Inline start: left in left-to-right layouts, right in right-to-left ones. |
| `marginEnd` | `DimensionValue` | `.me(…)` | Inline end: the opposite side of `marginStart`. |

### Padding

The physical keys (all but `paddingStart` / `paddingEnd`) also take an `EnvValue`: `paddingTop: "env(safe-area-inset-top)"`, `paddingBottom: "calc(env(safe-area-inset-bottom) + 16px)"` (Rust `.pt_safe_area()`, `.pb_safe_area_plus(px(16.0))`, `.pb_keyboard()`, ...). A padding is at least 0.

| Key | Type | Rust | Description |
|---|---|---|---|
| `padding` | `LengthValue \| EnvValue` | `.p(…)`, `.p_4()` | All four sides. |
| `paddingHorizontal` | `LengthValue \| EnvValue` | `.px(…)` | Left and right. |
| `paddingVertical` | `LengthValue \| EnvValue` | `.py(…)` | Top and bottom. |
| `paddingTop` | `LengthValue \| EnvValue` | `.pt(…)` | Top. |
| `paddingRight` | `LengthValue \| EnvValue` | `.pr(…)` | Right. |
| `paddingBottom` | `LengthValue \| EnvValue` | `.pb(…)` | Bottom. |
| `paddingLeft` | `LengthValue \| EnvValue` | `.pl(…)` | Left. |
| `paddingStart` | `LengthValue` | `.ps(…)` | Inline start: left in left-to-right layouts, right in right-to-left ones. |
| `paddingEnd` | `LengthValue` | `.pe(…)` | Inline end: the opposite side of `paddingStart`. |

## ViewStyle

Everything drawn by a view. All keys of `LayoutStyle` apply too.

### Background

| Key | Type | Rust | Description |
|---|---|---|---|
| `backgroundColor` | `ColorValue \| AnimatedNode` | `.bg(color)`, `.bind_background(&node)` | The fill color. Takes a native animated color. |
| `backgroundImage` | `string` | `.bg_linear(angle)`, `.bg_radial()`, `.bg_conic()` with `.gradient_from` / `_via` / `_to` | CSS gradients drawn over the background color: `linear-gradient(...)`, `radial-gradient(...)`, `conic-gradient(...)`, several separated by commas. |

```rust
view().h(px(120.0)).rounded(px(16.0)).bg_linear(deg(135.0)).gradient_from(rgb(0x6366f1)).gradient_to(rgb(0xec4899))
```

```tsx
<View style={{ height: 120, borderRadius: 16, backgroundImage: "linear-gradient(135deg, #6366f1, #ec4899)" }} />
```

### Borders

| Key | Type | Rust | Description |
|---|---|---|---|
| `borderWidth` | `number` | `.border(w)`, `.border_1()`, `.border_2()` | Width of all four sides. |
| `borderTopWidth` | `number` | `.border_t(w)` | Top side. |
| `borderRightWidth` | `number` | `.border_r(w)` | Right side. |
| `borderBottomWidth` | `number` | `.border_b(w)` | Bottom side. |
| `borderLeftWidth` | `number` | `.border_l(w)` | Left side. |
| `borderStartWidth` | `number` | `.border_s(w)` | Inline start side (left in left-to-right layouts, right in right-to-left ones). |
| `borderEndWidth` | `number` | `.border_e(w)` | Inline end side. |
| `borderColor` | `ColorValue \| AnimatedNode` | `.border_color(c)`, `.bind_border_color(&node)` | Color of all four sides. Takes a native animated color. |
| `borderTopColor` | `ColorValue` | `.border_t_color(c)` | Top side. |
| `borderRightColor` | `ColorValue` | `.border_r_color(c)` | Right side. |
| `borderBottomColor` | `ColorValue` | `.border_b_color(c)` | Bottom side. |
| `borderLeftColor` | `ColorValue` | `.border_l_color(c)` | Left side. |
| `borderStartColor` | `ColorValue` | `.border_s_color(c)` | Inline start side. |
| `borderEndColor` | `ColorValue` | `.border_e_color(c)` | Inline end side. |
| `borderStyle` | `"solid" \| "dashed" \| "dotted" \| "none" \| "hidden"` | `.border_solid()`, `.border_dashed()`, `.border_dotted()`, `.border_none()` | Line style. Default `"solid"`. `"none"` and `"hidden"` draw and lay out no border whatever the widths, set before or after, as in CSS. |

A side whose width is set and whose color nothing sets is drawn in the text color, CSS's `currentColor`: `{ borderWidth: 1, color: "#2563eb" }` draws a blue border. Outlines take the text color the same way.

### Corners

| Key | Type | Rust | Description |
|---|---|---|---|
| `borderRadius` | `number` | `.rounded(r)`, `.rounded_lg()` | Radius of all four corners. |
| `borderTopLeftRadius` | `number` | `.rounded_tl(r)` | Top-left corner. |
| `borderTopRightRadius` | `number` | `.rounded_tr(r)` | Top-right corner. |
| `borderBottomRightRadius` | `number` | `.rounded_br(r)` | Bottom-right corner. |
| `borderBottomLeftRadius` | `number` | `.rounded_bl(r)` | Bottom-left corner. |
| `borderTopStartRadius` | `number` | `.rounded_ss(r)` | Top corner on the inline start side. |
| `borderTopEndRadius` | `number` | `.rounded_se(r)` | Top corner on the inline end side. |
| `borderBottomStartRadius` | `number` | `.rounded_es(r)` | Bottom corner on the inline start side. |
| `borderBottomEndRadius` | `number` | `.rounded_ee(r)` | Bottom corner on the inline end side. |
| `borderCurve` | `"circular" \| "continuous"` | `.border_curve(curve)` | `"continuous"`: corners whose curvature eases into the edges, like iOS app icons. Where the box is too small the curve falls back to circular, so pills stay pills. Works on both platforms. |

### Outline

An outline is drawn outside the border and takes no space in layout.

| Key | Type | Rust | Description |
|---|---|---|---|
| `outlineWidth` | `number` | `.outline(w)` | Line width. |
| `outlineColor` | `ColorValue` | `.outline_color(c)` | Line color. Default the text color. |
| `outlineStyle` | `"solid" \| "dashed" \| "dotted" \| "none" \| "hidden"` | `.outline_dashed()`, `.outline_dotted()`, `.outline_none()` | Line style. |
| `outlineOffset` | `number` | `.outline_offset(o)` | Distance from the border edge; negative values move it inside. |

### Shadows

A view casts shadows with CSS's `boxShadow`: several layers, spread and inset shadows. Transitions animate it (`transitionProperty: "boxShadow"`).

| Key | Type | Rust | Description |
|---|---|---|---|
| `boxShadow` | `string \| BoxShadowLayer[]` | `.shadow([BoxShadow { … }])`, `.shadow_md()`, `.shadow_color(c)` | CSS `box-shadow`: offsets, blur, spread and color, several layers separated by commas, `inset` for inner shadows; or its layers as numbers, `[{ x, y, blur, spread, color, inset }]` (only `x` and `y` required); a layer without a color is drawn in the text color, as CSS's `currentColor`. `.shadow_color(c)` recolors the layers of a preset or of `.shadow(…)`. |

```rust
view().p_4().rounded(px(12.0)).bg(white()).shadow([
    BoxShadow { offset_y: px(1.0), blur: px(2.0), color: rgba(0x0000000f).into(), ..BoxShadow::default() },
    BoxShadow { offset_y: px(8.0), blur: px(24.0), spread: px(-4.0), color: rgba(0x0000001f).into(), ..BoxShadow::default() },
])
```

```tsx
<View style={{ padding: 16, borderRadius: 12, backgroundColor: "#fff",
  boxShadow: "0 1px 2px rgb(0 0 0 / 0.06), 0 8px 24px -4px rgb(0 0 0 / 0.12)" }} />
```

> [!NOTE]
> On Android, shadows need a background: a view with a transparent background (text on nothing, for example) casts no shadow. For Android's material shadow use the `android={{ elevation }}` prop instead of a style.

### Opacity, visibility and overflow

| Key | Type | Rust | Description |
|---|---|---|---|
| `opacity` | `number \| AnimatedNode` | `.opacity(o)`, `.bind_opacity(&value)` | 0 (invisible) to 1. Takes a native animated value. |
| `visibility` | `"visible" \| "hidden" \| "collapse"` | | Hidden views keep their space in layout (unlike `display: "none"`). |
| `overflow` | `"visible" \| "hidden"` | `.overflow_hidden()` | `"hidden"` clips children to the view's bounds (and corners). |
| `backfaceVisibility` | `"visible" \| "hidden"` | `.backface_hidden()`, `.backface_visible()` | `"hidden"`: invisible while a 3D rotation turns it away. |
| `verticalAlign` | `"baseline" \| "text-top" \| "text-bottom" \| "middle"` | `.align_baseline()`, `.align_text_top()`, `.align_text_bottom()`, `.align_middle()` | Where a view or image inside a `<Text>` sits in its line, as CSS's `vertical-align`: its bottom on the baseline (default), its top or bottom at the text font's top or bottom, or its middle half the x height above the baseline. The line grows to hold it. |

### Transforms

Transforms are CSS's: the `translate`, `rotate` and `scale` properties and `transform`, composed in that order. Each is a property of its own, so a style's `scale` replaces a class's `scale-*` and keeps its `rotate-*`, and a style's `transform` replaces a class's transform functions (`rotate-x-*`, `skew-*`).

| Key | Type | Rust | Description |
|---|---|---|---|
| `translate` | `string \| number \| AnimatedNode \| [x, y]` | `.translate_x(…)`, `.translate_y(…)`; `.bind_translate_x(&v)`, `.bind_translate_y(&v)` | CSS's `translate`: x, then y (`"10px 20px"`; percentages of the view's own size, `"-50% 0"`). A number is points along x. `[x, y]` takes a number, a string (`"50%"`, `"10px"`) or an animated value per axis; an animated value alone moves it along x. |
| `rotate` | `string \| number \| AnimatedNode` | `.rotate(deg(…))`; `.bind_rotate(&v)` | CSS's `rotate`: `"45deg"`, `"0.5turn"`, or about an axis, `"x 90deg"`. A number, and an animated value, is degrees about z, clockwise. |
| `scale` | `string \| number \| AnimatedNode \| [x, y]` | `.scale(f)`, `.scale_x(f)`, `.scale_y(f)`; `.bind_scale(&v)` | CSS's `scale`: `1.5`, `"150%"`, x and y (`"1 2"`). An animated value scales both axes; `[x, y]` takes a number or an animated value per axis. |
| `transform` | `string \| TransformStep[]` | `.rotate_x(…)`, `.rotate_y(…)`, `.skew_x(…)`, `.skew_y(…)`, `.transform_none()`; animated steps: `.bind_transform(kind, &v)`, `.bind_motion(&m)` (after every style transform) | CSS's `transform`: `"translateX(10px) rotate(45deg) scale(1.5)"`, or `"none"`. Functions: `translate()`, `translateX()`, `translateY()`, `scale()`, `scaleX()`, `scaleY()`, `rotate()` / `rotateZ()`, `rotateX()`, `rotateY()`, `skew()`, `skewX()`, `skewY()`, `perspective()`. Lengths take `px` (translations also `%`, of the view's own size), angles `deg`, `rad` or `turn`. Or a list of steps whose amounts may be animated values: what the string cannot hold, such as an animated 3D rotation (`[{ perspective: 800 }, { rotateY: angle }]`), and a motion's channels (`m.transform`). A style's `transform` is one form or the other, so a perspective before animated steps is a step of the list. Applied after `translate`, `rotate` and `scale`. |
| `transformOrigin` | `string \| (number \| string)[]` | `.transform_origin(…)`, `.origin_top_left()`, ... | The point the transforms act around: keywords, percentages and lengths (`"top left"`, `"50% 0"`, `[10, 20]`). Default the center. |

A `TransformStep` is an object with one key, applied in the order of the list:

| Step | Value | Native animated |
|---|---|---|
| `translateX`, `translateY` | `number` (points) | yes |
| `scale`, `scaleX`, `scaleY` | `number` (factor) | yes |
| `rotate`, `rotateZ`, `rotateX`, `rotateY` | `number` (degrees) or `string` (`"45deg"`, `"0.5rad"`) | yes |
| `skewX`, `skewY` | `number` (degrees) or `string` | no |
| `perspective` | `number` (points) | no |

```rust
view().perspective(px(600.0)).child(view().rotate_y(deg(20.0)).scale(0.95))
```

```tsx
<View style={{ transform: "perspective(600px) rotateY(20deg) scale(0.95)" }} />
```

An animated value drives `translate`, `rotate` and `scale` directly, and the steps of a `transform` list:

```tsx
const x = createAnimatedValue(0);
const angle = createAnimatedValue(0);

<View style={{ translate: [x, 0], rotate: angle }} />
<View style={{ transform: [{ perspective: 800 }, { rotateY: angle }] }} />
```

> [!NOTE]
> Android draws no skew: `skew()`, `skewX()` and `skewY()` leave the view unskewed there.

### Filters and blending

| Key | Type | Rust | Description |
|---|---|---|---|
| `filter` | `string` | `.blur(r)`, `.brightness(…)`, `.contrast(…)`, `.grayscale(…)`, `.hue_rotate(…)`, `.invert(…)`, `.saturate(…)`, `.sepia(…)` | CSS filters of the view and its content: `brightness()`, `contrast()`, `grayscale()`, `hue-rotate()`, `invert()`, `saturate()`, `sepia()`, `opacity()`, `blur()`, `drop-shadow()`. |
| `backdropFilter` | `string` | `.backdrop_blur(r)`, `.backdrop_brightness(…)`, ... | CSS filters of what is behind the view, such as `"blur(10px)"` for frosted glass. |
| `maskImage` | `string` | | A CSS gradient whose alpha decides how much of the view is drawn, fully where opaque and not at all where transparent: `linear-gradient(...)`, `radial-gradient(...)`, `conic-gradient(...)`. Masks everything the view draws, its backdrop filter included, whose blur then draws without the system material's tint. Not drawn on Windows and GPUI. |
| `glassEffect` | `"none" \| "regular" \| "clear"` | `.glass_effect(GlassEffect::Regular)` | Liquid Glass behind the view's content on iOS 26 and macOS 26 and later. `"regular"` uses the standard material; `"clear"` takes less color from the background. `"none"` is the default. Pair with `backdropFilter` for the blur shown on earlier iOS versions and other platforms. |
| `mixBlendMode` | `"normal" \| "multiply" \| "screen" \| "overlay" \| "darken" \| "lighten" \| "color-dodge" \| "color-burn" \| "hard-light" \| "soft-light" \| "difference" \| "exclusion" \| "hue" \| "saturation" \| "color" \| "luminosity" \| "plus-darker" \| "plus-lighter"` | `.mix_blend_mode(mode)` | How the view blends with what is behind it. |

> [!WARNING]
> Platform limits:
> - iOS applies only `opacity()`, `brightness()` up to 1 and `drop-shadow()` to views. `<Image>` takes every color filter and `blur()`, applied while the image is decoded.
> - iOS `backdropFilter` blur uses a system material at a fraction, an approximation of the exact radius.
> - Android needs API 31 for `blur()`, `drop-shadow()` and `backdropFilter`; below that only color filters apply. Blend modes need API 29.

### Transitions

When a transitioned property changes (from a new style, a class or a variant such as `active:`), the platform animates it natively. No JS runs during the animation.

| Key | Type | Rust | Description |
|---|---|---|---|
| `transitionProperty` | `string` | `.transition()`, `.transition_all()`, `.transition_colors()`, `.transition_opacity()`, `.transition_shadow()`, `.transition_transform()`, `.transition_none()` | Comma-separated properties that animate: `"all"`, `"colors"` (`color`, `backgroundColor`, `borderColor`, ...), `"opacity"`, `"transform"` (every transform property), `"boxShadow"`, `"borderRadius"`, `"borderWidth"`, or `"none"`. |
| `transitionDuration` | `number \| "${number}ms" \| "${number}s"` | `.duration(ms)` | Milliseconds as a number, or `"150ms"` / `"0.2s"`. |
| `transitionDelay` | `number \| "${number}ms" \| "${number}s"` | `.delay(ms)` | Delay before the transition starts. |
| `transitionTimingFunction` | `"linear" \| "ease" \| "ease-in" \| "ease-out" \| "ease-in-out" \| "cubic-bezier(...)"` | `.ease_linear()`, `.ease_in()`, `.ease_out()`, `.ease_in_out()`, `.ease_bezier(…)` | The easing curve. |

```rust
view()
    .on_press(move || open.update(|o| *o = !*o))
    .h(move || px(if open.get() { 160.0 } else { 56.0 }))
    .opacity(move || if open.get() { 1.0 } else { 0.8 })
    .transition()
    .duration(200.0)
```

```tsx
<View
  onPress={() => open.set(!open())}
  style={{ height: open() ? 160 : 56, opacity: open() ? 1 : 0.8,
    transitionProperty: "opacity, transform", transitionDuration: 200 }}
/>
```

### Keyframe animations

Built-in keyframe animations, run natively (Tailwind's `animate-*`).

| Key | Type | Rust | Description |
|---|---|---|---|
| `animationName` | `"none" \| "spin" \| "ping" \| "pulse" \| "bounce"` | `.animate_spin()`, `.animate_ping()`, `.animate_pulse()`, `.animate_bounce()`, `.animate_none()` | The animation. |
| `animationDuration` | `number \| "${number}ms" \| "${number}s"` | `.animation(KeyframeAnimation { … })` | Length of one iteration. |
| `animationDelay` | `number \| "${number}ms" \| "${number}s"` | `.animation(KeyframeAnimation { … })` | Delay before the first iteration. |
| `animationTimingFunction` | `"linear" \| "ease" \| "ease-in" \| "ease-out" \| "ease-in-out" \| "cubic-bezier(...)"` | `.animation(KeyframeAnimation { … })` | The easing curve. |
| `animationIterationCount` | `number \| "infinite"` | `.animation(KeyframeAnimation { … })` | How many times it runs. |

For animations driven by values, gestures or springs, use [`nsh`'s animation API](https://nsh.dev/versions/main/modules/nsh.md#animation) instead.

### Pointer and selection

| Key | Type | Rust | Description |
|---|---|---|---|
| `cursor` | `"auto" \| "default" \| "pointer" \| "text" \| "grab" \| "grabbing" \| "not-allowed" \| ...` (every CSS cursor keyword, and `"none"`) | `.cursor(Cursor)`, `.cursor_pointer()` | The pointer shape over the view, for pointers (iPad trackpads, Mac Catalyst, desktops). Diagonal resize keywords keep their axis: `nwse-resize` / `nw-resize` / `se-resize` (`Cursor::NwseResize`) and `nesw-resize` / `ne-resize` / `sw-resize` (`Cursor::NeswResize`). Windows, Linux, Android, the web and GPUI show diagonal cursors; AppKit uses them on macOS 15+, with an open hand on macOS 14. UIKit uses pointer effects on iPad and Mac Catalyst. |
| `pointerEvents` | `"auto" \| "none" \| "box-none" \| "box-only"` | `.pointer_events(PointerEvents::BoxNone)` | Which touches the view and the views in it take (`pointer-events-none`, `pointer-events-auto`). `"none"`: none, for the views in it too unless one sets `"auto"`, inherited as in CSS. `"box-none"`: none on the view itself, the views in it take theirs; `"box-only"`: the view itself takes them, the views in it none (both React Native's, for the view only). Default `"auto"`. See [touch and gestures](https://nsh.dev/versions/main/docs/touch-and-gestures.md#pointerevents). |
| `userSelect` | `"auto" \| "none" \| "text"` | `.select_text()`, `.select_none()` | Whether a `<Text>` can be selected and copied (`"text"`, `select-text`) or not (`"none"`, `select-none`); a view's reaches the texts in it that set none. `"auto"` (`select-auto`), the default, leaves it to the view around it, else to the platform. See [text](https://nsh.dev/versions/main/elements/text.md). |

### SVG paint

CSS's paint properties of SVG shapes, which any element takes and the elements inside it inherit, as in a browser.
They paint what Rust components draw on canvases.

| Key | Type | Rust | Description |
|---|---|---|---|
| `fill` | `"none" \| "currentColor" \| ColorValue` | `.fill_color(c)`, `.fill_none()`, `.fill_current()` | What shapes are filled with; `currentColor` is the element's text color. |
| `stroke` | `"none" \| "currentColor" \| ColorValue` | `.stroke_color(c)`, `.stroke_none()`, `.stroke_current()` | What the outlines of shapes are painted with. |
| `strokeWidth` | `number \| string` | `.stroke_width(w)` | The width of those outlines, a length (1 by default). |
| `strokeDasharray` | `number \| string` | — | Dashes and gaps along those outlines: lengths separated by spaces or commas (`"4 2"`), an odd list repeated, or `"none"`. |

## TextStyle

Text styles apply to `<Text>` and `<Input>`. They are also inherited, as in CSS: text properties set on a view pass to the texts and inputs inside it, and nested `<Text>` spans inherit from their parent text. All keys of `ViewStyle` apply too. See [Text](https://nsh.dev/versions/main/docs/text.md).

### Font

| Key | Type | Rust | Description |
|---|---|---|---|
| `color` | `ColorValue \| AnimatedNode` | `.text_color(c)`, `.bind_color(&node)` | Text color. Takes a native animated color. Also the color of borders and outlines that set none. |
| `fontSize` | `number` | `.text_size(s)`, `.text_sm()`, `.text_lg()`, ... | Size in points. |
| `fontWeight` | `"normal" \| "bold" \| number \| "${number}"` | `.font_weight(FontWeight::SEMIBOLD)` | `"normal"` (400), `"bold"` (700) or 100–900. |
| `fontFamily` | `string` | `.font_family(name)` | A system family, or the name an imported font evaluates to (`import Inter from "./Inter.ttf"`), or a list of them, most preferred first (`"Brand, 'Noto Sans SC', sans-serif"`). See [Fonts](https://nsh.dev/versions/main/docs/fonts.md#fallback-lists). |
| `fontStyle` | `"normal" \| "italic"` | `.italic()` | Italic. |
| `fontVariant` | `FontVariantName[] \| string` | `.small_caps()`, `.oldstyle_nums()`, `.lining_nums()`, `.tabular_nums()`, `.proportional_nums()` | OpenType number and letter forms, a list (`["tabular-nums"]`) or CSS's names separated by spaces (`"tabular-nums small-caps"`). `tabular-nums` keeps digits the same width, useful for counters and timers. |

### Spacing and alignment

| Key | Type | Rust | Description |
|---|---|---|---|
| `lineHeight` | `number` | `.line_height(h)` | Line height in points. |
| `letterSpacing` | `number` | `.letter_spacing(s)` | Extra space between characters, in points. |
| `textAlign` | `"auto" \| "left" \| "center" \| "right" \| "justify" \| "start" \| "end"` | `.text_left()`, `.text_center()`, `.text_right()`, `.text_justify()` | Horizontal alignment. `"left"` and `"right"` keep their sides in right-to-left layouts; `"start"` and `"end"` follow the direction. |
| `writingDirection` | `"auto" \| "ltr" \| "rtl"` | `.writing_direction(d)` | Base direction of the text; `"auto"` takes it from the content. |
| `textTransform` | `"none" \| "uppercase" \| "lowercase" \| "capitalize"` | `.uppercase()`, `.lowercase()`, `.capitalize()`, `.normal_case()` | Case transformation. |

> [!TIP]
> Tailwind's `leading-*` and `tracking-*` classes set line heights as multiples of the font size and letter spacing in `em`, so they scale with `text-*` sizes.

### Lines and overflow

| Key | Type | Rust | Description |
|---|---|---|---|
| `numberOfLines` | `number` | `.number_of_lines(n)`, `.truncate()` | The most lines a `<Text>` shows (CSS's `line-clamp`, `line-clamp-*`); `0` (`line-clamp-none`), the default, shows them all. `truncate` is one line cut with an ellipsis. |
| `textOverflow` | `"ellipsis" \| "clip" \| "ellipsis-start" \| "ellipsis-middle"` | `.text_overflow(EllipsizeMode::Middle)` | How a clamped `<Text>` is cut: an ellipsis at its end (`"ellipsis"`, `text-ellipsis`, the default), clipped (`"clip"`, `text-clip`), or the ellipsis at its start or in its middle (file paths). |

### Decoration

| Key | Type | Rust | Description |
|---|---|---|---|
| `textDecorationLine` | `"none" \| "underline" \| "line-through" \| "underline line-through"` | `.underline()`, `.line_through()`, `.no_underline()` | Lines drawn with the text. |
| `textDecorationColor` | `ColorValue` | `.text_decoration_color(c)` | Color of the lines (default the text color). |
| `textDecorationStyle` | `"solid" \| "double" \| "dotted" \| "dashed" \| "wavy"` | `.text_decoration_solid()`, `_double()`, `_dotted()`, `_dashed()`, `_wavy()` | Line style. |
| `textDecorationThickness` | `number \| "auto" \| "from-font"` | `.text_decoration_thickness(t)` | Line thickness. |
| `textUnderlineOffset` | `number \| "auto"` | `.underline_offset(o)` | Distance of the underline from the baseline. |

### Placeholder, caret and selection

`placeholderColor` and `caretColor` belong to `InputStyle`, the style of `<Input>`; `selectionColor` to `TextStyle`, as
selectable texts take it too.

| Key | Type | Rust | Description |
|---|---|---|---|
| `placeholderColor` | `ColorValue` | `.placeholder_color(c)` of an input | The color of an `<Input>`'s placeholder (`placeholder:text-*`). |
| `textAlignVertical` | `"auto" \| "top" \| "center" \| "bottom"` | | Where text shorter than its box sits (a `<Text>` with a height). |
| `selectionColor` | `ColorValue` | `.selection_color(c)` of an input or a text | An `<Input>`'s or a selectable `<Text>`'s selection highlight and handles (`selection:bg-*`); the platform's accent by default. On iOS also an input's caret, unless `caretColor` is set (UIKit tints both with one color). |
| `caretColor` | `ColorValue` | `.caret_color(c)` of an input | An `<Input>`'s caret (`caret-*`); the platform's default when unset. |

### Text shadow

| Key | Type | Rust | Description |
|---|---|---|---|
| `textShadow` | `string \| TextShadowLayer[]` | `.text_shadow([TextShadow { … }])`, `.text_shadow_sm()`, `.text_shadow_color(c)` | CSS's `text-shadow`: offsets, blur and color (`"0 1px 2px rgb(0 0 0 / 0.3)"`), or its layers as numbers, `[{ x, y, blur, color }]`; several layers drawn as the widest one; a layer without a color is drawn in the text color; `"none"`. |

```rust
text("Title").text_shadow([TextShadow {
    offset_y: px(1.0),
    radius: px(2.0),
    color: rgba(0x0000004d).into(),
    ..TextShadow::default()
}])
```

```tsx
<Text style={{ textShadow: "0 1px 2px rgb(0 0 0 / 0.3)" }}>Title</Text>
```

> [!NOTE]
> iOS draws no gradients (`backgroundImage`) or inset box shadows on `<Text>`.

## ImageStyle

All keys of `ViewStyle`, plus:

| Key | Type | Rust | Description |
|---|---|---|---|
| `tintColor` | `ColorValue` | `.tint_color(c)` of an image | Recolors a template image (every opaque pixel takes this color), for monochrome icons. |
| `objectFit` | `"fill" \| "contain" \| "cover" \| "none" \| "scale-down"` | `.object_fit(ResizeMode::Contain)` | CSS's `object-fit`: how an image or a video fits its box. `"cover"` fills it and crops, `"contain"` fits inside it, `"fill"` stretches, `"none"` keeps the natural size, `"scale-down"` is `"none"` or `"contain"`, whichever is smaller. Images cover their box by default, videos are contained in it. |
| `objectPosition` | `string` | `.object_position(p)`, `.object_top()`, ... of an image | Where the image sits in its box once `objectFit` has sized it, as CSS's `object-position`: keywords, percentages and lengths (`"top"`, `"left bottom"`, `"25% 75%"`, `"right 10px bottom 20%"`). A covering image is cropped around it. Default the center. |

`objectFit` applies to `<Video>` too; see [image](https://nsh.dev/versions/main/elements/image.md) and [video](https://nsh.dev/versions/main/elements/video.md).

## Props that look like styles

Android's material shadow is a platform prop, set beside the style:

| Setting | Prop | Rust | Class |
|---|---|---|---|
| Material shadow (Android) | `android={{ elevation }}` | `.elevation(e)` | |

## Related

- [Styling](https://nsh.dev/versions/main/docs/styling.md): `style`, `class`, inheritance and precedence.
- [Tailwind reference](https://nsh.dev/versions/main/modules/tailwind-reference.md): every supported utility and variant.
- [Layout](https://nsh.dev/versions/main/docs/layout.md): flexbox and grid in practice.
- [view](https://nsh.dev/versions/main/elements/view.md), [text](https://nsh.dev/versions/main/elements/text.md), [image](https://nsh.dev/versions/main/elements/image.md): the elements these styles apply to.

`width`, `height` and `flexBasis` also accept `"min-content"`, `"max-content"` and `"fit-content"`, computed by Taffy.

Source: https://nsh.dev/versions/main/modules/style-reference

---

# Tailwind reference

Every element takes Tailwind CSS classes in its `class` prop (and conditional ones in `classList`). NSH resolves them in Rust against Tailwind 4's default theme: JS passes only the string, each distinct string is parsed once and cached, and variants such as `dark:` or `active:` are re-evaluated natively when the appearance, window size or press state changes, without running any JS.

Each utility sets exactly what Tailwind CSS 4 generates for it, with the same meaning as in a browser. This page lists what is supported. For an introduction see [Tailwind](https://nsh.dev/versions/main/docs/tailwind.md); for the style keys the utilities set, see the [Style reference](https://nsh.dev/versions/main/modules/style-reference.md).

Rust components take no class strings: they style elements with the typed methods of `Styled` (`nsh_core::prelude`), named after these utilities and resolving to the same values, Tailwind's default scales included (`px-4` is `.px_4()`, `rounded-2xl` `.rounded_2xl()`, `shadow-md` `.shadow_md()`, `bg-linear-to-br` `.bg_linear_to_br()`). Colors are values: theme colors, or Tailwind's palette as `nsh_core::element::palette` (`ZINC.shade(800)` is `zinc-800`). Variants are methods taking a closure of styles: `.active(|s| …)`, `.hover(…)`, `.focus(…)`, `.disabled_style(…)`, `.dark(…)`, `.group_active(…)`, and `.style_when(condition, …)` for the rest. The [Style reference](https://nsh.dev/versions/main/modules/style-reference.md) names the method of each style key.

```rust
use nsh_core::{element::palette::{RED, ZINC}, prelude::*};

view()
    .flex_row()
    .items_center()
    .gap_3()
    .rounded_2xl()
    .bg(white())
    .p_4()
    .shadow_md()
    .active(|s| s.scale(0.98))
    .transition()
    .dark(|s| s.bg(ZINC.shade(800)))
    .child(
        text("Inbox")
            .text_base()
            .font_weight(FontWeight::SEMIBOLD)
            .text_color(ZINC.shade(900))
            .dark(|s| s.text_color(white())),
    )
    .child(
        text(move || unread.get().to_string())
            .text_color(move || if unread.get() > 0 { RED.shade(500) } else { ZINC.shade(400) }),
    )
```

```tsx
<View class="flex-row items-center gap-3 rounded-2xl bg-white p-4 shadow-md active:scale-[0.98] transition dark:bg-zinc-800">
  <Text class="text-base font-semibold text-zinc-900 dark:text-white">Inbox</Text>
  <Text classList={{ "text-red-500": unread() > 0, "text-zinc-400": unread() === 0 }}>{unread()}</Text>
</View>
```

## How classes combine

- **Later wins.** Among utilities of the same variant level, the one later in the string wins: `"p-4 p-2"` is `p-2`. A component can take a `class` prop and append it to its own classes without `tailwind-merge`.
- **Variants apply after plain utilities**, in Tailwind's variant order: `group-*:` (by their state, then by group name), `selection:`, `placeholder:`, position (`first:` ...), `checked:`, `indeterminate:`, `selected:`, `focus-within:`, `hover:`, `focus:`, `focus-visible:`, `active:`, `enabled:`, `disabled:`, `aria-busy:`, `aria-checked:`, `aria-expanded:`, `aria-pressed:`, `aria-selected:`, `data-*:` (by name), motion, `max-*:` breakpoints widest first, then breakpoints ascending, orientation, direction, `dark:`, then platform. A class's highest variant decides, then its next highest, and one more variant comes later (`dark:hover:` after `dark:`), as Tailwind sorts them. So `"active:bg-red-500 bg-blue-500"` is red while pressed.
- **`style` wins over classes.** The inline `style` is applied on top of the resolved classes. A style key is the CSS property of its name, the one the utilities set, so it replaces that property and nothing else: `style={{ paddingLeft: 8 }}` beats `pl-4` and keeps `pr-4`. An important utility (`!p-4` or `p-4!`) wins over the inline style too.
- **Text styles inherit.** Text utilities on a view (`text-white`, `font-bold`, `text-center`, ...) pass to the `<Text>` and `<Input>` elements inside it, as in CSS.
- **Display is CSS's.** `flex` and `inline-flex` make a row unless a direction utility says otherwise, wherever it is in the string (`flex-col flex` is a column). A style's `display: "flex"` is a row in the same way; views that set no display keep NSH's column default.

## Units and the theme

Lengths are points (`1` = one point on iOS, one dp on Android). Tailwind's `1rem` is 16 points, so the theme matches the web at the same density: one spacing step is 4 points (`p-4` = 16 points), `text-base` is 16 points.

### Spacing values

Utilities that take a spacing value (padding, margin, gap, inset, width, height, `basis`, `translate`, `leading`) accept:

| Value | Example | Result |
|---|---|---|
| Steps (quarter steps allowed) | `p-4`, `gap-1.5`, `m-0.25` | step × 4 points |
| `px` | `p-px`, `-mt-px` | 1 point |
| `0` | `m-0` | 0 |
| Fraction (inset, width, height, `basis`, `translate`) | `w-1/2`, `left-1/3` | percentage of the parent |
| `full` (the same) | `w-full`, `inset-full` | 100% |
| `auto` (margin, inset, width, height, basis) | `mx-auto`, `w-auto` | `"auto"` |
| Arbitrary | `p-[13px]`, `w-[42%]`, `mt-[1.5rem]` | the given length |

Margins, insets, `translate`, `rotate`, `skew`, `scale`, `z`, `hue-rotate`, `tracking`, `underline-offset`, `outline-offset`, grid lines and gradient angles take a leading `-` for negative values: `-mt-2`, `-translate-x-1/2`, `-rotate-6`. Tailwind has no negative form of the others (`-p-4`, `-gap-2`, `-w-4`), and neither has NSH.

### Colors

The full Tailwind 4 palette is built in: `red`, `orange`, `amber`, `yellow`, `lime`, `green`, `emerald`, `teal`, `cyan`, `sky`, `blue`, `indigo`, `violet`, `purple`, `fuchsia`, `pink`, `rose`, `slate`, `gray`, `zinc`, `neutral`, `stone`, `mauve`, `olive`, `mist`, `taupe`, each in shades `50`, `100`–`900`, `950`; plus `black`, `white` and `transparent`. Your own colors come from `nsh.json` (see [Theme customization](#theme-customization)).

Every color utility takes:

| Form | Example |
|---|---|
| A theme color | `bg-sky-500`, `text-brand` |
| An opacity modifier (percent) | `bg-black/50`, `ring-black/5` |
| An arbitrary opacity | `text-black/[0.35]` |
| An arbitrary color | `bg-[#0ea5e9]`, `border-[rgb(0_0_0_/_0.1)]`, `text-[oklch(70%_0.2_50)]` |
| An arbitrary color with a modifier | `bg-[rgb(0_0_255)]/25` |

`currentColor` and `inherit` are not color values. As in a browser, a border, an outline or a ring without a color class is drawn in the element's text color, its own or the one it inherits (`<View class="text-white"><View class="border ring-2" /></View>` draws both white), and so is a border whose width the `style` prop sets without a color.

## Arbitrary values

Square brackets pass a value the theme does not have: `w-[37px]`, `grid-cols-[200px_1fr]`, `bg-[linear-gradient(45deg,red,blue)]`.

- `_` stands for a space (`grid-cols-[1fr_2fr]`); write `\_` for a literal underscore.
- Lengths: a bare number or `px` (points), `pt` (4/3 of a point, as in CSS), `rem` (16 points), and `%` where percentages make sense.
- Angles (`rotate-[...]`, `hue-rotate-[...]`, `bg-linear-[...]`): `deg`, `rad`, `grad`, `turn`.
- Times (`duration-[...]`, `delay-[...]`): `ms` or `s`; a bare number is milliseconds.
- Type hints settle ambiguous values: `text-[length:22px]` is a size, `text-[color:#333]` a color; `border-[length:3px]` likewise.

Arbitrary CSS properties (`[mask-type:luminance]`) are not supported.

## Layout

| Class | Sets |
|---|---|
| `flex`, `inline-flex` | `display: "flex"`, and a row unless a direction utility is present |
| `grid`, `inline-grid` | `display: "grid"` |
| `block`, `flow-root` | block layout or an independent block formatting context |
| `box-border`, `box-content` | dimensions include borders and padding, or content alone |
| `w/h/size-min`, `w/h/size-max`, `w/h/size-fit` | Taffy intrinsic sizes: `min-content`, `max-content`, `fit-content` |
| `inline`, `inline-block` | `display: "block"`: what a browser computes for them in a flex or grid parent |
| `hidden` | `display: "none"` |
| `relative`, `absolute` | `position` |
| `static` | `position: "static"`: in the flow, its insets ignored ; absolute descendants use their nearest positioned ancestor |
| `sticky` | `position: "sticky"`: in the flow, it sticks `top` (`left` in a horizontal scroll view) within the scroll view around it while its parent is in view |
| `fixed` | `position: "fixed"`: an element laid out in its root view's box (the window or its modal) above that root view's children, in place while what is around it scrolls |
| `inset-<n>`, `inset-x-<n>`, `inset-y-<n>` | `top` / `right` / `bottom` / `left` |
| `top-<n>`, `right-<n>`, `bottom-<n>`, `left-<n>` | the matching offset |
| `start-<n>`, `end-<n>` | `start` / `end` (direction-aware) |
| `z-<n>`, `z-auto`, `z-[<n>]` | `zIndex` (`z-auto` is 0) |
| `visible` | `visibility: "visible"` |
| `invisible`, `collapse` | `visibility: "hidden"` (keeps its space) |
| `overflow-hidden`, `overflow-clip`, `overflow-x-hidden`, `overflow-y-hidden` | `overflow: "hidden"` |
| `overflow-visible` | `overflow: "visible"` |
| `aspect-square`, `aspect-video`, `aspect-<a>/<b>`, `aspect-[<a>/<b>]`, `aspect-auto` | `aspectRatio` (1, 16/9, a/b, none) |

Scrolling is an element, not a class: `overflow-auto` and `overflow-scroll` are not supported; use [scroll](https://nsh.dev/versions/main/elements/scroll.md).

## Flexbox and grid

| Class | Sets |
|---|---|
| `flex-row`, `flex-row-reverse`, `flex-col`, `flex-col-reverse` | `flexDirection` |
| `flex-wrap`, `flex-wrap-reverse`, `flex-nowrap` | `flexWrap` |
| `flex-1` | grow 1, shrink 1, basis 0 |
| `flex-<n>` | grow n, shrink 1, basis 0 |
| `flex-auto` | grow 1, shrink 1, basis auto |
| `flex-initial` | grow 0, shrink 1, basis auto |
| `flex-none` | grow 0, shrink 0, basis auto |
| `flex-[<grow>]`, `flex-[<grow>_<shrink>_<basis>]` | the CSS shorthand: `flex-[2]`, `flex-[3_0_50%]` |
| `grow`, `grow-<n>`, `grow-[<n>]` | `flexGrow` (bare: 1) |
| `shrink`, `shrink-<n>`, `shrink-[<n>]` | `flexShrink` (bare: 1) |
| `basis-<n>` | `flexBasis` (spacing, fraction, `full`, `auto`, arbitrary) |
| `justify-start`, `justify-end`, `justify-center`, `justify-between`, `justify-around`, `justify-evenly`, `justify-stretch`, `justify-normal` | `justifyContent` |
| `items-start`, `items-end`, `items-center`, `items-baseline`, `items-stretch` | `alignItems` |
| `self-auto`, `self-start`, `self-end`, `self-center`, `self-stretch`, `self-baseline` | `alignSelf` |
| `content-start`, `content-end`, `content-center`, `content-between`, `content-around`, `content-evenly`, `content-stretch`, `content-normal` | `alignContent` |
| `justify-items-start`, `-end`, `-center`, `-stretch`, `-normal` | `justifyItems` |
| `justify-self-auto`, `-start`, `-end`, `-center`, `-stretch` | `justifySelf` |
| `place-content-center`, `-start`, `-end`, `-between`, `-stretch` | `alignContent` and `justifyContent` |
| `place-items-center`, `-start`, `-end`, `-stretch` | `alignItems` and `justifyItems` |
| `place-self-auto`, `-center`, `-start`, `-end`, `-stretch` | `alignSelf` and `justifySelf` |
| `gap-<n>`, `gap-x-<n>`, `gap-y-<n>` | `gap`, `columnGap`, `rowGap` |
| `space-x-<n>`, `space-y-<n>` (and negative) | a margin on each child but the last: the end margin (`space-x`) or the bottom one (`space-y`), under the child's own margins, as in Tailwind CSS; it adds to a `gap` |
| `space-x-reverse`, `space-y-reverse` | the margin on the start / top side instead (children in reverse order) |
| `grid-cols-<n>` | `gridTemplateColumns: "repeat(n, minmax(0, 1fr))"` |
| `grid-cols-[<tracks>]`, `grid-cols-none` | `gridTemplateColumns` (`grid-cols-[200px_1fr]`) |
| `grid-rows-<n>`, `grid-rows-[<tracks>]`, `grid-rows-none` | `gridTemplateRows` |
| `col-span-<n>`, `col-span-full`, `col-auto`, `col-<n>`, `col-[<value>]` | `gridColumn` |
| `col-start-<n>`, `col-end-<n>` (and `-auto`) | `gridColumnStart`, `gridColumnEnd` |
| `row-span-<n>`, `row-span-full`, `row-auto`, `row-<n>`, `row-[<value>]` | `gridRow` |
| `row-start-<n>`, `row-end-<n>` (and `-auto`) | `gridRowStart`, `gridRowEnd` |
| `grid-flow-row`, `grid-flow-col`, `grid-flow-dense`, `grid-flow-row-dense`, `grid-flow-col-dense` | `gridAutoFlow` |
| `auto-cols-auto`, `-min`, `-max`, `-fr`, `auto-cols-[<track>]` | `gridAutoColumns` |
| `auto-rows-auto`, `-min`, `-max`, `-fr`, `auto-rows-[<track>]` | `gridAutoRows` |

## Spacing

| Class | Sets |
|---|---|
| `p-<n>`, `px-<n>`, `py-<n>` | `padding`, `paddingHorizontal`, `paddingVertical` |
| `pt-<n>`, `pr-<n>`, `pb-<n>`, `pl-<n>` | `paddingTop` / `Right` / `Bottom` / `Left` |
| `ps-<n>`, `pe-<n>` | `paddingStart`, `paddingEnd` (direction-aware) |
| `m-<n>`, `mx-<n>`, `my-<n>` | `margin`, `marginHorizontal`, `marginVertical` |
| `mt-<n>`, `mr-<n>`, `mb-<n>`, `ml-<n>` | `marginTop` / `Right` / `Bottom` / `Left` |
| `ms-<n>`, `me-<n>` | `marginStart`, `marginEnd` (direction-aware) |

## Sizing

| Class | Sets |
|---|---|
| `w-<n>`, `h-<n>` | `width`, `height` (spacing, fraction, `full`, `auto`, arbitrary) |
| `size-<n>` | `width` and `height` |
| `min-w-<n>`, `max-w-<n>`, `min-h-<n>`, `max-h-<n>` | the matching limit |
| `w-screen`, `w-dvw`, `w-svw`, `w-lvw` | the window width (also on `min-w-` / `max-w-`) |
| `h-screen`, `h-dvh`, `h-svh`, `h-lvh` | the window height (also on `min-h-` / `max-h-`) |
| `w-auto`, `h-auto` | `auto` (sized by content) |
| `max-w-none`, `max-h-none` | no limit |
| `w-<container>`, `min-w-<container>`, `max-w-<container>` | a container width (below) |

Container widths (points): `3xs` 256, `2xs` 288, `xs` 320, `sm` 384, `md` 448, `lg` 512, `xl` 576, `2xl` 672, `3xl` 768, `4xl` 896, `5xl` 1024, `6xl` 1152, `7xl` 1280; `prose` is 65 times the width of the element's font's `0` (CSS's `65ch`), as in Tailwind CSS.

## Typography

### Font

| Class | Sets |
|---|---|
| `font-sans` | the system font |
| `font-serif`, `font-mono` | `fontFamily: "serif"` / `"monospace"` |
| `font-thin` (100), `font-extralight` (200), `font-light` (300), `font-normal` (400), `font-medium` (500), `font-semibold` (600), `font-bold` (700), `font-extrabold` (800), `font-black` (900) | `fontWeight` |
| `font-[<weight>]`, `font-[<family>]` | a numeric weight, otherwise a family: `font-[650]`, `font-[Inter]` |
| `italic`, `not-italic` | `fontStyle` |
| `normal-nums`, `small-caps`, `oldstyle-nums`, `lining-nums`, `tabular-nums`, `proportional-nums` | `fontVariant` (they combine; `normal-nums` resets the number forms) |

### Size, color and line height

`text-<size>` sets the font size and Tailwind's matching line height, which a `leading-*` class replaces wherever it is in the string and whatever its variant (`leading-tight md:text-lg` keeps the tight leading):

| Class | Size | Line height |
|---|---|---|
| `text-xs` | 12 | 16 |
| `text-sm` | 14 | 20 |
| `text-base` | 16 | 24 |
| `text-lg` | 18 | 28 |
| `text-xl` | 20 | 28 |
| `text-2xl` | 24 | 32 |
| `text-3xl` | 30 | 36 |
| `text-4xl` | 36 | 40 |
| `text-5xl` | 48 | 1× |
| `text-6xl` | 60 | 1× |
| `text-7xl` | 72 | 1× |
| `text-8xl` | 96 | 1× |
| `text-9xl` | 128 | 1× |

| Class | Sets |
|---|---|
| `text-<size>/<leading>` | size and line height: `text-sm/6` (24 points), `text-lg/tight` |
| `text-[<length>]` | `fontSize`: `text-[22px]`, `text-[length:22px]` |
| `text-<color>` | `color` |
| `leading-none` (1), `leading-tight` (1.25), `leading-snug` (1.375), `leading-normal` (1.5), `leading-relaxed` (1.625), `leading-loose` (2) | `lineHeight` as a multiple of the font size |
| `leading-<n>`, `leading-[<length>]` | `lineHeight` in points (`leading-6` = 24) |
| `leading-[<number>]` | `lineHeight` as a multiple of the font size (`leading-[1.5]`), inherited as that multiplier; `em` and `%` compute a length at the element's font size before inheritance |
| `tracking-tighter` (-0.05em), `tracking-tight` (-0.025em), `tracking-normal` (0), `tracking-wide` (0.025em), `tracking-wider` (0.05em), `tracking-widest` (0.1em) | `letterSpacing` relative to the font size |
| `tracking-[<value>]` | `letterSpacing`: `tracking-[0.2em]`, `tracking-[1px]` |

### Alignment, case and wrapping

| Class | Sets |
|---|---|
| `text-left`, `text-center`, `text-right`, `text-justify` | `textAlign` |
| `text-start`, `text-end` | `textAlign: "start"` / `"end"`: the start or end of the line in the layout direction |
| `align-baseline`, `align-text-top`, `align-text-bottom`, `align-middle` | `verticalAlign` (views and images inside a text) |
| `uppercase`, `lowercase`, `capitalize`, `normal-case` | `textTransform` |
| `truncate` | one line, tail ellipsis, no wrapping, `overflow: hidden` (on a view: its texts do not wrap) |
| `line-clamp-<n>`, `line-clamp-none` | `numberOfLines` (`none` shows every line) |
| `text-ellipsis`, `text-clip` | `textOverflow: "ellipsis"` / `"clip"` |
| `whitespace-nowrap`, `text-nowrap` | lines never wrap; on a view, the lines of the texts in it (inherited, as CSS's `white-space`) |
| `whitespace-normal`, `text-wrap`, `text-balance`, `text-pretty` | lines wrap (balancing is not done) |
| `select-text`, `select-none` | `userSelect: "text"` / `"none"`; on a view, of the texts in it that set none |
| `select-auto` | `userSelect: "auto"`: the view around it decides, as CSS's `user-select: auto` (`select-none md:select-auto`) |

### Decoration and shadow

| Class | Sets |
|---|---|
| `underline`, `line-through`, `no-underline` | `textDecorationLine` |
| `decoration-solid`, `decoration-double`, `decoration-dotted`, `decoration-dashed`, `decoration-wavy` | `textDecorationStyle` |
| `decoration-<n>`, `decoration-[<length>]` | `textDecorationThickness` |
| `decoration-auto`, `decoration-from-font` | `textDecorationThickness: "auto"` |
| `decoration-<color>` | `textDecorationColor` |
| `underline-offset-<n>`, `underline-offset-[<length>]`, `underline-offset-auto` | `textUnderlineOffset` |
| `text-shadow-2xs`, `-xs`, `-sm`, `-md`, `-lg`; `/<alpha>` | a text shadow from the theme (one layer: the widest of the theme's); the modifier is the layers' alpha: `text-shadow-md/20` |
| `text-shadow-<color>`, `text-shadow-current` | its color, at the size's alpha |
| `text-shadow-none` | removes it |

Tailwind's text shadows have several layers; natively one shadow is drawn, the widest layer.

### Inputs

| Class | Sets |
|---|---|
| `placeholder:text-<color>` | `placeholderColor` |
| `selection:bg-<color>` | `selectionColor` (the highlight of an input's or a selectable text's selection, and of those inside the element) |
| `caret-<color>` | the cursor color |

## Backgrounds

| Class | Sets |
|---|---|
| `bg-<color>` | `backgroundColor` |
| `bg-[<gradient>]` | `backgroundImage`: `bg-[linear-gradient(45deg,red,blue)]`, `bg-[radial-gradient(...)]` |
| `bg-linear-to-t`, `-tr`, `-r`, `-br`, `-b`, `-bl`, `-l`, `-tl` | a linear gradient toward a side or corner (`bg-gradient-to-*` is the v3 name) |
| `bg-linear-<angle>`, `bg-linear-[<angle>]` | a linear gradient at an angle: `bg-linear-45`, `-bg-linear-12`, `bg-linear-[0.25turn]` |
| `bg-radial` | a radial gradient from the center |
| `bg-conic`, `bg-conic-<angle>` | a conic gradient, optionally starting at an angle |
| `from-<color>`, `via-<color>`, `to-<color>` | the gradient's stops (default transparent at the ends) |
| `from-<p>%`, `via-<p>%`, `to-<p>%` | stop positions: `via-40%`, `from-[15%]` |
| `bg-none` | removes the gradient |

Gradient utilities mix their colors in Oklab, as Tailwind CSS writes them (`in oklab`); at an arbitrary position (`bg-linear-[25deg]`, `bg-conic-[0.25turn]`) they follow CSS's default, Oklab with the palette's colors and sRGB when every stop is a hex, `rgb()`, `hsl()` or named color.

```rust
view()
    .h_32()
    .rounded_2xl()
    .bg_linear_to_br()
    .gradient_from(INDIGO.shade(500))
    .gradient_via(PURPLE.shade(500))
    .gradient_via_position(percentage(0.4))
    .gradient_to(PINK.shade(500))
```

```tsx
<View class="h-32 rounded-2xl bg-linear-to-br from-indigo-500 via-purple-500 via-40% to-pink-500" />
```

## Borders

| Class | Sets |
|---|---|
| `border`, `border-<n>`, `border-[<length>]` | `borderWidth` (bare: 1) |
| `border-x`, `border-y`, `border-t`, `border-r`, `border-b`, `border-l`, `border-s`, `border-e` (with `-<n>` or bare) | the matching sides' widths |
| `border-<color>`, `border-t-<color>`, ... | `borderColor` and the per-side colors |
| `border-solid`, `border-dashed`, `border-dotted` | `borderStyle` |
| `border-none`, `border-hidden` | `borderStyle: "none"` / `"hidden"`: no border whatever the width classes, in any order (`md:border-solid` shows it again) |
| `rounded`, `rounded-<size>`, `rounded-none`, `rounded-full`, `rounded-[<length>]` | `borderRadius` (bare: `sm`) |
| `corner-squircle`, `corner-round` | `borderCurve`: `"continuous"`, `"circular"` |
| `rounded-t-`, `-r-`, `-b-`, `-l-`, `-tl-`, `-tr-`, `-br-`, `-bl-` | the matching corners |
| `rounded-s-`, `-e-`, `-ss-`, `-se-`, `-es-`, `-ee-` | start / end corners (direction-aware): `borderTopStartRadius`, `borderTopEndRadius`, `borderBottomStartRadius`, `borderBottomEndRadius` |
| `outline`, `outline-<n>`, `outline-[<length>]` | `outlineWidth` (bare: 1), solid unless a style class is anywhere in the string (`outline-dashed outline-2` is dashed, `outline-none outline-2` draws nothing) |
| `outline-<color>` | `outlineColor` |
| `outline-solid`, `outline-dashed`, `outline-dotted`, `outline-none`, `outline-hidden` | `outlineStyle`; a style alone is CSS's medium width, 3 points |
| `outline-offset-<n>`, `outline-offset-[<length>]` | `outlineOffset` |

Radius sizes (points): `xs` 2, `sm` 4, `md` 6, `lg` 8, `xl` 12, `2xl` 16, `3xl` 24, `4xl` 32, `full` 9999.

### Rings

Rings are box shadows with a spread, drawn outside the border without taking space.

| Class | Sets |
|---|---|
| `ring`, `ring-<n>`, `ring-[<length>]` | a ring of that width (bare: 1) |
| `ring-<color>` | its color (default the element's text color) |
| `ring-inset` | draws the ring inside |
| `ring-offset-<n>`, `ring-offset-<color>` | a gap between element and ring (default white) |
| `inset-ring`, `inset-ring-<n>`, `inset-ring-<color>` | an inner ring |

## Effects

| Class | Sets |
|---|---|
| `shadow-2xs`, `shadow-xs`, `shadow-sm`, `shadow`, `shadow-md`, `shadow-lg`, `shadow-xl`, `shadow-2xl`; `/<alpha>` | `boxShadow` from the theme; the modifier is the layers' alpha: `shadow-xl/20` |
| `shadow-[<box-shadow>]` | an arbitrary shadow: `shadow-[0_8px_24px_rgb(0_0_0_/_0.12)]` |
| `shadow-<color>`, `shadow-current` | recolors the shadow layers, at the size's alpha: `shadow-indigo-500/40` |
| `shadow-none` | no shadow |
| `inset-shadow-2xs`, `-xs`, `-sm`, `inset-shadow`, `inset-shadow-[...]`, `inset-shadow-<color>`, `inset-shadow-none` | an inner shadow |
| `opacity-<n>`, `opacity-[<value>]` | `opacity`: `opacity-50` = 0.5 |
| `mix-blend-<mode>` | `mixBlendMode`: `normal`, `multiply`, `screen`, `overlay`, `darken`, `lighten`, `color-dodge`, `color-burn`, `hard-light`, `soft-light`, `difference`, `exclusion`, `hue`, `saturation`, `color`, `luminosity`, `plus-darker`, `plus-lighter` |

Shadows, rings and inset shadows combine into one `boxShadow` list, as in CSS. A shadow color replaces each layer's color, alpha too, as Tailwind's `--tw-shadow-color`: `shadow-md shadow-red-500` is an opaque red shadow, `shadow-md/20 shadow-red-500` one at 20%.

## Filters

| Class | Sets |
|---|---|
| `blur`, `blur-xs` (4), `-sm` (8), `-md` (12), `-lg` (16), `-xl` (24), `-2xl` (40), `-3xl` (64), `blur-none`, `blur-[<length>]` | `blur()` |
| `brightness-<n>`, `contrast-<n>`, `saturate-<n>` | percentage factors: `brightness-125` = 1.25 |
| `grayscale`, `grayscale-<n>`, `invert`, `invert-<n>`, `sepia`, `sepia-<n>` | bare: 100% |
| `hue-rotate-<deg>`, `-hue-rotate-<deg>` | `hue-rotate()` |
| `drop-shadow`, `drop-shadow-xs`, `-sm`, `-md`, `-lg`, `-xl`, `-2xl`, `drop-shadow-[...]`, `drop-shadow-none`; `drop-shadow-<color>`, `drop-shadow-current`; `/<alpha>` on either | a `drop-shadow()` per layer, after the other filters; a color replaces the layers', at the size's alpha; the web, Linux, Windows and GPUI draw every layer, iOS, macOS and Android the widest |
| `drop-shadow-none` | removes it |
| `filter-none` | removes all filters |
| `backdrop-blur`, `backdrop-blur-<size>`, `backdrop-blur-[<length>]` | blurs what is behind the view |
| `backdrop-brightness-<n>`, `backdrop-contrast-<n>`, `backdrop-grayscale`, `backdrop-hue-rotate-<deg>`, `backdrop-invert`, `backdrop-opacity-<n>`, `backdrop-saturate-<n>`, `backdrop-sepia` | backdrop filters |
| `backdrop-filter-none` | removes them |

> [!WARNING]
> iOS applies only `opacity`, `brightness` up to 1 and `drop-shadow` to views; `<Image>` takes every color filter and `blur`. Android needs API 31 for `blur`, `drop-shadow` and backdrop blur. See the [Style reference](https://nsh.dev/versions/main/modules/style-reference.md#filters-and-blending).

## Transforms

| Class | Sets |
|---|---|
| `translate-x-<n>`, `translate-y-<n>`, `translate-<n>` | `translate` (spacing, `full`, fractions of the element's own size: `-translate-x-1/2`, arbitrary) |
| `rotate-<deg>`, `rotate-[<angle>]` | `rotate` |
| `rotate-x-<deg>`, `rotate-y-<deg>`, `rotate-z-<deg>` | 3D rotation (in `transform`, after the translation, the rotation and the scale) |
| `scale-<pct>`, `scale-x-<pct>`, `scale-y-<pct>`, `scale-[<factor>]` | `scale`: `scale-95` = 0.95, `-scale-x-100` mirrors |
| `skew-<deg>`, `skew-x-<deg>`, `skew-y-<deg>` | skew, in `transform` (not on Android) |
| `perspective-dramatic` (100), `-near` (300), `-normal` (500), `-midrange` (800), `-distant` (1200), `perspective-[<length>]`, `perspective-none` | depth for the 3D rotations of the element's children, seen from its center (CSS's `perspective`: `<View class="perspective-near"><View class="rotate-y-45" /></View>`) |
| `origin-center`, `-top`, `-top-right`, `-right`, `-bottom-right`, `-bottom`, `-bottom-left`, `-left`, `-top-left`, `origin-[<value>]` | `transformOrigin` |
| `backface-hidden`, `backface-visible` | `backfaceVisibility` |
| `transform-none` | clears the 3D rotations and the skews (CSS's `transform: none`) |
| `translate-none`, `rotate-none`, `scale-none` | clears the translation, the rotation, the scale |

Transform utilities compose like CSS: `translate-*`, `rotate-*` and `scale-*` set the `translate`, `rotate` and `scale` properties and combine regardless of order, then `transform` applies (`rotate-x-*`, `skew-*`). The `style` prop's keys of the same names replace only their own property: `style={{ scale: 1.1 }}` replaces `scale-95` and keeps `rotate-3`. `transform`, `transform-gpu`, `transform-cpu` and `transform-flat` are accepted and do nothing: NSH composes every transform alike, flat. Translations by a fraction of the size are resolved against the element's frame and follow it when it resizes.

## Transitions and animation

| Class | Sets |
|---|---|
| `transition` | colors, opacity, shadow and transform; 150 ms, `cubic-bezier(0.4, 0, 0.2, 1)` |
| `transition-all`, `transition-colors`, `transition-opacity`, `transition-shadow`, `transition-transform` | the animated properties |
| `transition-none` | no transition |
| `duration-<ms>`, `duration-[<time>]` | `transitionDuration`: `duration-300`, `duration-[0.4s]` |
| `delay-<ms>`, `delay-[<time>]` | `transitionDelay` |
| `ease-linear`, `ease-in`, `ease-out`, `ease-in-out`, `ease-initial`, `ease-[cubic-bezier(...)]` | `transitionTimingFunction` |
| `animate-spin`, `animate-ping`, `animate-pulse`, `animate-bounce` | a native keyframe animation, repeated forever |
| `animate-none` | stops it |

Transitions run on the UI thread when a value changes, including when a variant starts or stops matching, so `transition active:scale-95` animates the press without JS. Wrap animations in `motion-safe:` to respect the reduce-motion setting.

## Interactivity

| Class | Sets |
|---|---|
| `pointer-events-none`, `pointer-events-auto` | `pointerEvents: "none"` / `"auto"`: whether the view is a target for touches and the pointer, inherited as in CSS: inside a `pointer-events-none` view, a `pointer-events-auto` one is a target again |
| `cursor-<name>`, `cursor-[<name>]` | `cursor`: `cursor-pointer`, `cursor-grab`, `cursor-not-allowed`, ... (every CSS cursor keyword) |
| `select-none`, `select-text`, `select-auto` | text selection (see Typography) |

## SVG

| Class | Sets |
|---|---|
| `fill-<color>`, `fill-none`, `fill-current`, `fill-inherit` | `fill` (`fill-current` is `currentColor`) |
| `stroke-<color>`, `stroke-none`, `stroke-current`, `stroke-inherit` | `stroke` |
| `stroke-<number>`, `stroke-[<length>]` | `strokeWidth` |

## Images

| Class | Sets |
|---|---|
| `object-cover`, `object-contain`, `object-fill`, `object-none`, `object-scale-down` | `objectFit` (`fill` stretches, `none` keeps the natural size, placed at `objectPosition`, `scale-down` is the same, shrunk to fit where larger); images and videos |
| `object-top`, `object-bottom`, `object-left`, `object-right`, `object-center`, `object-top-left`, `object-top-right`, `object-bottom-left`, `object-bottom-right`, `object-[<position>]` | `objectPosition` (`object-left-top`, ... are the same as `object-top-left`, ...) |
| `tint-<color>` | `tintColor` (recolors template images) |

## Accepted without effect

These utilities are rendering hints, or what every native view already is; they parse without a warning and change nothing: `antialiased`, `subpixel-antialiased`, `isolation-auto`, `box-border`, `appearance-none`, `appearance-auto`, `will-change-auto`, `will-change-scroll`, `will-change-contents`, `will-change-transform`, `will-change-[<value>]`, `transform`, `transform-gpu`, `transform-cpu`, `transform-flat`. Scrolling, snapping and overscroll are props of [scroll](https://nsh.dev/versions/main/elements/scroll.md).

## Not supported

`peer-*` variants, pseudo-elements (`before:`, `after:`), arbitrary properties (`[prop:value]`), `overflow-auto` / `overflow-scroll`, `divide-*`, `columns-*`, `float-*`, `container`, container queries, `order-*`, `transform-3d`, `select-all`, `border-double` / `outline-double`, intrinsic min/max constraints (such as `max-w-max`), `snap-*`, `scroll-*`, `overscroll-*`, `touch-*` and `isolate` are unknown classes. `nsh build` and `nsh dev` warn about unknown classes they find in your source (`file:line:col: unknown class '...'`), and the runtime logs each unknown class once.

## Variants

Variants make a utility conditional: `dark:bg-zinc-900`, `md:flex-row`, `active:opacity-70`. They stack (`dark:active:bg-zinc-700`) and are evaluated natively whenever what they depend on changes.

### Appearance and environment

| Variant | Applies when | Rust |
|---|---|---|
| `dark:` | the appearance is dark | `.dark(\|s\| …)` |
| `ios:` | running on iOS or Mac Catalyst | `.when(os() == Os::Ios, …)` |
| `android:` | running on Android | `.when(os() == Os::Android, …)` |
| `portrait:`, `landscape:` | the window is taller than wide / wider than tall | `.style_when(move \|\| window().height > window().width, …)` |
| `ltr:`, `rtl:` | the layout direction | `.style_when(rtl, …)` |
| `motion-safe:`, `motion-reduce:` | the user has not / has asked for reduced motion | `.style_when(reduce_motion, …)` |

### Breakpoints

Breakpoints compare the window width in points.

| Variant | Min width |
|---|---|
| `sm:` | 640 |
| `md:` | 768 |
| `lg:` | 1024 |
| `xl:` | 1280 |
| `2xl:` | 1536 |

| Form | Example | Applies when |
|---|---|---|
| `<bp>:` | `md:p-8` | width ≥ breakpoint |
| `max-<bp>:` | `max-md:p-1` | width < breakpoint |
| `min-[<length>]:` | `min-[600px]:grid-cols-3` | width ≥ the length |
| `max-[<length>]:` | `max-[400px]:text-sm` | width < the length |

A phone in portrait (390 points wide) matches none of the default breakpoints; a tablet or a phone in landscape matches several. In Rust, a breakpoint is a condition on the window: `.style_when(move || window().width >= px(768.0), |s| s.p_8())` is `md:p-8`.

### Interaction states

States are tracked by the platform only for elements whose classes use them, and changes apply natively, with no JS round trip.

| Variant | Applies when | Rust |
|---|---|---|
| `active:` | the element is pressed | `.active(\|s\| …)` |
| `hover:` | a pointer is over it (iPad pointer, Mac Catalyst, Android mouse) | `.hover(\|s\| …)` |
| `focus:`, `focus-visible:` | the input has focus | `.focus(\|s\| …)` |
| `focus-within:` | the element or a descendant has focus (an `Overlay`'s content is a descendant of the element it is in) | `.focus_within(…)` |
| `disabled:` | the element has the `disabled` prop | `.disabled_style(\|s\| …)` |
| `enabled:` | the element does not have the `disabled` prop |  |
| `selected:` | the element is selected: a `Button`'s `selected`, or `accessibilityState.selected` |  |
| `checked:` | the element is checked: `accessibilityState.checked` is `true` (`"mixed"` is not checked) |  |
| `indeterminate:` | the element is indeterminate: `accessibilityState.checked` is `"mixed"` |  |
| `aria-expanded:` | the element is expanded: `accessibilityState.expanded` is `true` (a `Popover`'s or `Menu`'s trigger while its popup is open) |  |
| `aria-pressed:` | the element is a toggle button that is on: `accessibilityState.pressed` is `true` (`"mixed"` is not pressed; not `active:`, a press in progress) | `.aria_pressed(\|s\| …)` |
| `aria-busy:` | the element is busy: `accessibilityState.busy` is `true` |  |
| `aria-checked:` | the element is checked: `accessibilityState.checked` is `true`, as `checked:` |  |
| `aria-selected:` | the element is selected: `accessibilityState.selected` is `true`, as `selected:` |  |
| `data-<name>:` | the element has the boolean `data-*` attribute `name` (Tailwind's `&[data-<name>]`; names of lower case letters, digits and `-`): what a component's part shows beyond its states, a calendar's day at the start of a range `data-range-start` | `Interactive::project_data(name, …)` sets one |

The same states as style objects are the `activeStyle`, `hoverStyle`, `focusStyle`, `disabledStyle`, `checkedStyle`, `indeterminateStyle`, `expandedStyle` and `pressedStyle` props of every element (and a `Button`'s `selectedStyle`); they go over the element's style and classes.

`disabled` works on any element: it applies `disabled:` and removes the element's press handlers, so it shows no press feedback either.

```rust
view()
    .on_press(save)
    .disabled(saving)
    .rounded_lg()
    .bg(BLUE.shade(600))
    .px_4()
    .py_2()
    .transition()
    .active(|s| s.scale(0.95).bg(BLUE.shade(700)))
    .disabled_style(|s| s.opacity(0.4))
    .child(text("Save").font_weight(FontWeight::MEDIUM).text_color(white()))
```

```tsx
<View
  onPress={save}
  disabled={saving()}
  class="rounded-lg bg-blue-600 px-4 py-2 transition active:scale-95 active:bg-blue-700 disabled:opacity-40"
>
  <Text class="font-medium text-white">Save</Text>
</View>
```

### Groups

Mark an ancestor with `group` and style descendants by its state with `group-<state>:`. Name groups to nest them: `group/card` and `group-hover/card:`.

| Variant | Applies when the group is | Rust |
|---|---|---|
| `group-active:` | pressed | `.group_active(…)`, `.group_active_named(name, …)` |
| `group-hover:` | hovered | `.group_hover(…)`, `.group_hover_named(name, …)` |
| `group-focus:`, `group-focus-visible:` | focused |  |
| `group-focus-within:` | focused or containing focus | `.group_focus_within(…)`, `.group_focus_within_named(name, …)` |
| `group-disabled:` | disabled |  |
| `group-selected:` | selected |  |
| `group-checked:` | checked |  |
| `group-indeterminate:` | indeterminate |  |
| `group-aria-expanded:` | expanded |  |
| `group-aria-pressed:` | a toggle button that is on |  |
| `group-aria-busy:`, `group-aria-checked:`, `group-aria-selected:` | busy, checked, selected |  |
| `group-data-<name>:` | showing the `data-*` attribute `name` |  |

```rust
view()
    .on_press(open)
    .group_named("row")
    .flex_row()
    .items_center()
    .gap_3()
    .p_3()
    .active(|s| s.bg(ZINC.shade(100)))
    .child(
        text("Settings")
            .flex_1()
            .text_color(ZINC.shade(900))
            .group_active_named("row", |s| s.text_color(BLUE.shade(600))),
    )
    .child(
        text("›")
            .text_color(ZINC.shade(400))
            .group_active_named("row", |s| s.translate_x(px(4.0)))
            .transition_transform(),
    )
```

```tsx
<View onPress={open} class="group/row flex-row items-center gap-3 p-3 active:bg-zinc-100">
  <Text class="flex-1 text-zinc-900 group-active/row:text-blue-600">Settings</Text>
  <Text class="text-zinc-400 group-active/row:translate-x-1 transition-transform">›</Text>
</View>
```

### Position among siblings

| Variant | Applies to |
|---|---|
| `first:` | the first child |
| `last:` | the last child |
| `only:` | the only child |
| `odd:` | the 1st, 3rd, ... child |
| `even:` | the 2nd, 4th, ... child |

```rust
each(items, |item: &Item| item.id, move |item, index| {
    text(move || item.with(|i| i.name.clone()))
        .border_b(px(1.0))
        .border_color(ZINC.shade(200))
        .py_3()
        .style_when(move || index.get() + 1 == items.with(Vec::len), |s| s.border_b(px(0.0)))
})
```

```tsx
<Each of={items()}>{(item) => <Text class="border-b border-zinc-200 py-3 last:border-b-0">{item().name}</Text>}</Each>
```

### Placeholder and selection

`placeholder:` applies to an `<Input>`'s placeholder and only takes a text color: `placeholder:text-zinc-400` (the style key `placeholderColor`). `selection:` applies to the selection of an `<Input>` or a selectable `<Text>`, and on any element to those inside it (Tailwind's `& *::selection`; the nearest element's wins), and takes its background, the highlight: `selection:bg-violet-200` (the style key `selectionColor`, which also tints an input's caret where the platform draws them in one color).

### Important

`!` before or after a utility (`!p-4`, `p-4!`) makes it win over every other class and over the inline `style`.

## Theme customization

Extend the theme in the `"tailwind"` object of your app's `nsh.json`. Entries with a new name are added; entries with an existing name replace the default. Lengths are points. The theme is checked when the app is bundled: an unknown key or an invalid value is a build error.

```json
{
  "name": "My App",
  "id": "com.example.myapp",
  "tailwind": {
    "colors": {
      "brand": { "50": "#f5f3ff", "500": "#7c3aed", "600": "#6d28d9", "DEFAULT": "#7c3aed" },
      "accent": "#f59e0b"
    },
    "spacing": 4,
    "breakpoints": { "tablet": 600 },
    "fontFamily": { "display": "Inter" },
    "fontSize": { "huge": [48, 1.1] },
    "fontWeight": { "heavy": 850 },
    "radius": { "card": 14 },
    "shadow": { "card": "0 2px 8px rgb(0 0 0 / 0.12)" },
    "insetShadow": { "well": "inset 0 2px 6px rgb(0 0 0 / 0.1)" },
    "dropShadow": { "icon": "0 2px 4px rgb(0 0 0 / 0.2)" },
    "tracking": { "label": 0.08 },
    "leading": { "dense": 1.15 },
    "blur": { "glass": 20 },
    "perspective": { "card": 700 },
    "aspect": { "photo": 1.5 },
    "ease": { "snappy": [0.2, 0, 0, 1] },
    "container": { "content": 680 }
  }
}
```

With this theme, `bg-brand-500`, `bg-brand` (the `DEFAULT` shade), `text-accent`, `tablet:flex-row`, `font-display`, `text-huge`, `font-heavy`, `rounded-card`, `shadow-card`, `inset-shadow-well`, `drop-shadow-icon`, `tracking-label`, `leading-dense`, `blur-glass`, `perspective-card`, `aspect-photo`, `ease-snappy` and `max-w-content` all work.

| Key | Value | Used by |
|---|---|---|
| `colors` | `{ name: color }` or `{ name: { shade: color } }`; `DEFAULT` names the bare color. Any CSS color syntax. | every color utility |
| `spacing` | points per step (default 4) | `p-*`, `m-*`, `gap-*`, `w-*`, ... |
| `rem` | points per `rem` (default 16) | |
| `breakpoints` | `{ name: width }` | breakpoint variants (sorted by width) |
| `container` | `{ name: width }` | `w-*`, `min-w-*`, `max-w-*` |
| `fontFamily` | `{ name: family }` (a system family or the name of a bundled font) | `font-*` |
| `fontSize` | `{ name: size }` or `{ name: [size, lineHeightMultiple] }` | `text-*` |
| `fontWeight` | `{ name: 1–1000 }` | `font-*` |
| `tracking` | `{ name: em }` | `tracking-*` |
| `leading` | `{ name: multiple }` | `leading-*` |
| `radius` | `{ name: points }` | `rounded-*` |
| `shadow`, `insetShadow`, `dropShadow` | `{ name: "CSS box-shadow" }` | `shadow-*`, `inset-shadow-*`, `drop-shadow-*` |
| `blur` | `{ name: points }` | `blur-*`, `backdrop-blur-*` |
| `perspective` | `{ name: points }` | `perspective-*` |
| `aspect` | `{ name: ratio }` | `aspect-*` |
| `ease` | `{ name: [x1, y1, x2, y2] }` | `ease-*` |

> [!NOTE]
> The Tailwind theme shapes only your app's classes. The app's design tokens (shadcn/ui's colors, `radius`, the fonts and the app's own) are its theme, the `"theme"` key of `nsh.json`, which Rust components draw with; see [Rust](https://nsh.dev/versions/main/docs/rust.md#theme). Classes name those tokens as Tailwind names `@theme` variables (`bg-primary`, `bg-up/30`, `rounded-(--radius)`): see [Theme tokens](https://nsh.dev/versions/main/docs/tailwind.md#theme-tokens).

## Related

- [Tailwind](https://nsh.dev/versions/main/docs/tailwind.md): the guide.
- [Styling](https://nsh.dev/versions/main/docs/styling.md): `class`, `classList`, `style` and how they combine.
- [Style reference](https://nsh.dev/versions/main/modules/style-reference.md): the style keys utilities set.

Source: https://nsh.dev/versions/main/modules/tailwind-reference