Basalt
Reference

Windows

React Native has no API for any of this: on a phone there is one window, it is the screen, and nothing an app says would change it. On a desktop the window is the first thing an app wants after it has drawn something.

import {
  useWindow,
  windowControl,
  useCloseRequest,
  useQuitRequest,
  quit,
  Window,
  useDisplays,
} from 'basalt-core';

useWindow()

const window = useWindow();

window.setSize(900, 700);
window.center();
window.setFullScreen(true);
window.toggleMaximize();

const {width, height, x, y, fullScreen, maximized} = window.bounds;
setSize(width, height)a request; a tiling window manager may ignore it
setPosition(x, y)
center()
setFullScreen(on?)defaults to true
minimize()
toggleMaximize()
close()asks, so a close handler still gets to refuse
setMinimumSize(width, height)the app's own window's; see the note below
setMaximumSize(width, height)0 in either direction clears that limit
setResizable(on?)defaults to true
setAlwaysOnTop(on?)defaults to false
boundslive; see below
capabilitieswhat this desktop will actually do

bounds is live

It re-renders when the window moves, is resized, or changes state, because the alternative, a getBounds() an app calls and caches, is an app whose layout is right until somebody drags a corner.

Reading it before there is a window gives zeroes rather than null, so const {width} = window.bounds never throws during a first render. And because setSize is a request rather than an instruction, bounds is what reports what happened rather than what was asked for.

capabilities

const {position, minimumSize, maximumSize, resizable, alwaysOnTop} =
  useWindow().capabilities;

All five are true on macOS and Windows. On Linux, minimumSize and resizable are, and the other three are not: GTK4 removed gtk_window_move, gtk_window_set_geometry_hints and gtk_window_set_keep_above because Wayland has no protocol a client can use for any of them. A client has no idea where its window is and no say in it.

So this is settled rather than pending, and it is a value rather than a paragraph: an app can put its "always on top" switch away on the desktop that has no such thing, which is better than a switch that lies. bounds.x and bounds.y are always zero on Linux for the same reason, and both display servers centre an unplaced window by default, so an app that never moves its window already gets what center() would have asked for.

The five are read once. They are booleans a platform knows at compile time, not a question for the window manager.

windowControl

The same calls, usable outside a component: windowControl.setSize(...), windowControl.close(), windowControl.getBounds(), windowControl.getCapabilities(). useWindow() is this object plus the live bounds, so the two cannot disagree.

useCloseRequest()

useCloseRequest(close => (unsaved ? setAsking(true) : close()));

A window with a close handler stops closing on its own. Every attempt, its close button, Cmd-W, Alt+F4, the window manager, is refused and reported, and the window goes when the app says so by calling the close it was handed. Which is the point: there is nowhere else to put "are you sure".

Pass null or nothing to stop being asked, which is also what unmounting does.

The decision has to exist before the attempt, which is why this is a registration rather than a handler that returns false: the system wants a synchronous yes or no and the handler is JavaScript on another thread.

On macOS this covers closing the window and not Cmd-Q, which terminates the application without asking any window whether it minds. That is useQuitRequest.

useQuitRequest()

useQuitRequest(allow => (unsaved ? setAsking(true) : allow()));

// later, when the person said yes
quit();

The same mechanism one level up, and it exists because the window half is not enough: an app can guard every window it owns and still lose the person's work to Cmd-Q.

Quitting is one event no matter how many windows are open, so the handler takes no window id. Register it once, near the top of the app. An app that registers from two components gets asked twice, which is harmless and is not the intended shape.

What each desktop means by quitting differs, and usefully so. On macOS this is Cmd-Q, the Quit menu item, and logging out. On Windows and Linux there is no application-level quit gesture to intercept, because an app ends when its last window closes, which is useCloseRequest's business. What this catches there is the session ending: logout, shutdown, reboot.

<Window>, a second window

<Window title="Preview" width={600} height={400} onClose={hide}>
  <Preview id={id} />
</Window>

Mount it and a window opens; unmount it and the window closes.

prop
title
width, height
onClosethe person closed it; see below
onCloseRequestthe person is trying to; refuses and reports, like useCloseRequest

A window is a React root

That is Fabric's grain rather than a decision Basalt made. A surface is what has a size, a layout context and a root shadow node, and two windows sharing one would be two windows sharing a layout. So a second window runs a second React tree, and <Window>'s children are rendered there rather than where they were written.

Which has a consequence worth stating plainly, because it is the one thing that surprises people: the children do not see React context from the tree they were written in. A theme provider, a navigation container or a Redux store wrapping the <Window> is not wrapping its children.

What does cross is props. The elements themselves are passed through, so anything captured in a closure or given as a prop arrives intact, including state and callbacks:

const [count, setCount] = useState(0);
<Window>
  <Text onPress={() => setCount(count + 1)}>{count}</Text>
</Window>

works, and re-renders the window when count changes. A useContext inside <Preview> does not. An app that needs context in a window should pass the value as a prop and re-provide it inside.

onClose and onCloseRequest

onClose means the person closed the window, through its own close button or the window manager, and not that the app unmounted the <Window>. An app that unmounted it already knows. It is the half that keeps the two sides agreeing: without it an app's open flag would stay true after the window had gone, the next render would try to close a window that closed itself, and the window could never be reopened.

onCloseRequest is the earlier half. Somebody is trying to close the window and it has not closed:

<Window onCloseRequest={close => (dirty ? ask() : close())}>

There are two ways to then say yes, and they are not the same one written twice. Unmounting the <Window> is the React-shaped one and usually right: the window is a render of some state, and agreeing to close it is that state changing. The close the handler is handed is the other, for when the app has no such state to change, and it closes the window without calling onClose, because an app that just said yes is not waiting to be told.

useWindow() inside a <Window> means that window. Its bounds are that window's, setSize resizes it, and it does not re-render when another window moves. Outside any <Window>, and from windowControl, it means the window the app started in.

Two calls are still the app's own window's whoever asks: minimize() and toggleMaximize(), and the size limits. close() is not: a second window closes itself.

useDisplays()

What screens the desktop has, where they are, and how dense they are. React Native's Dimensions reports the window, which is the right answer to a different question: an app placing a window, or deciding how much it can show, is asking about the screen it is on and the ones beside it.

const screens = useDisplays();
// or, outside a component
import {displays, primaryDisplay, pointerPosition} from 'basalt-core';
field
x, y, width, heightthe screen, in layout units
workX, workY, workWidth, workHeightwhat is left after a menu bar, taskbar or dock
scaleFactor
primary

primaryDisplay() is the one with primary set, or null. pointerPosition() resolves to {x, y, known}.

Bounds and scale factor come from all three desktops. The work area comes from macOS and Windows, and GTK4 reports the full bounds instead; the pointer's position comes from macOS and Windows and never from GTK.

None of those are gaps waiting to be filled. gdk_monitor_get_workarea, gdk_display_get_primary_monitor and reading the pointer were all in GTK 3 and were removed, because Wayland has no protocol a client can use for any of them. So an app that needs the work area should treat "equal to bounds" as the answer rather than as a failure, and one that needs the pointer should check known.

On this page