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 draws a title bar of its own and closes the window with nsh_core::ui::desktop (set_title_bar, title_bar, close_window) and marks draggable views with .window_drag(true); TSX imports nsh/desktop, which holds the window’s other functions and the menus too. 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 you are on a desktop.

use nsh_core::{
    desktop::TitleBarStyle,
    ui::{
        desktop::{close_window, set_title_bar, title_bar},
        prelude::*,
    },
};

import { isAvailable, Menu, titleBar, Window } from "nsh/desktop";

#isAvailable

const isAvailable: boolean;

true on macOS, Windows and Linux; false elsewhere. Rust: os().is_desktop().

#Window

const Window: {
  setTitle(title: string): void;
  setTitleBar(style: "default" | "hidden", height?: number): void;
  minimize(): void;
  toggleMaximize(): void;
  toggleFullScreen(): void;
  setFrame(frame: {
    origin?: Partial<Point>;
    size?: Partial<Size>;
    animated?: boolean;
    anchorTop?: boolean;
  }): void;
  setLevel(level: "normal" | "floating" | "desktopIcon"): void;
  orderFront(): void;
  close(): void;
};

The Rust column names the functions of nsh_core::ui::desktop.

Window sizing is supported on macOS, Windows and Linux; positioning and levels on macOS and Windows. Linux’s window manager controls placement and stacking. GPUI’s host configures window bounds 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:

use nsh_core::{
    desktop::TitleBarStyle,
    ui::{
        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)))
}

import { Input, Text, View } from "nsh";
import { titleBar, Window } from "nsh/desktop";

Window.setTitleBar("hidden", 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.

• 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

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.

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

const Menu: {
  setApplicationMenu(items: MenuItem[] | null): void;
  popup(items: MenuItem[], at?: Point): Promise<void>;
};

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

type MenuItem =
  | { type: "separator" }
  | {
      label?: string;
      role?: MenuRole;
      shortcut?: string;
      disabled?: boolean;
      checked?: boolean;
      onSelect?: () => void;
      submenu?: MenuItem[];
    };

null, undefined and false items are left out, so cond && { … } works in a list.

Modifiers:

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:

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

import { effect, signal } from "nsh";
import { platform } from "nsh/device";
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:

<View
  onPress={() =>
    Menu.popup([
      { label: "Rename", onSelect: rename },
      { label: "Duplicate", onSelect: duplicate },
      { type: "separator" },
      { label: "Delete", onSelect: remove },
    ])
  }
>
  <Text>More</Text>
</View>