@domicile-desktop/react

React for a Domicile shell or app: mount it on the desktop, read the desktop from context, and follow its state with hooks. See With React. Every hook's full signature and docs ship in the package's .d.ts, so your editor shows them.

Usage

import { mount } from "@domicile-desktop/react/mount";import { useFocusedWindow } from "@domicile-desktop/react/windows";const Focused = () => <p>{useFocusedWindow() ?? "the shell"}</p>;export const Shell = mount(Focused);

• ./elements: JSX types for the engine's <app> and <webview>. Load them once with /// <reference types="@domicile-desktop/react/elements" />.
• ./mount: mount(App) is a shell's Shell or an app's main. Draws App synchronously (the page draws nothing until Shell returns) in an element of its own with display: contents, under StrictMode, an error boundary that shows what threw, and <DomicileProvider>.
• ./nested-shell: <NestedShell shell> runs another shell, such as an npm package's Shell or runManganese(), inside this one, on the same desktop. It sizes against the element it is placed in. Both shells see every window and bind keys, so draw windows and bind keys in only one of them.
• ./domicile-provider: <DomicileProvider domicile>, useDomicile() (a shell's Domicile; throws under an app's) and useAppDomicile().
• ./use-watch: useWatch(namespace, type, read), read again on each type event, via useSyncExternalStore. read must answer the same value until the event; the desktop's lists keep their identity between changes.
• Hooks over the desktop's core state, each rerendering on change:
  • ./windows: useWindows, useFocusedWindow
  • ./displays: useDisplays
  • ./appearance: useAppearance
  • ./session: useIdle, useLocked
  • ./portals: usePortalRequests, useCapturing, useBoundShortcuts, usePortalWallpaper
• Shared watches, for state a library watches (UPower, BlueZ, pactl):
  • ./shared-watch: sharedWatch(start) runs one watch for every subscriber, from the first to the last.
  • ./per-desktop: perDesktop(make), one value per desktop.
  • ./use-shared-watch: useSharedWatch(watch), and useDeskWatch(desk) for a perDesktop watch of the desktop above.
  • ./watch-presence: watchPresence(read, onPresent) looks for hardware in /sys every 10 seconds; isAbsent says whether to hide for want of it.
  • The system-* packages' /react use these: useBattery, useBluetooth, useNetwork, useAudio and more.
• ./fake-domicile: <FakeDomicile fake> for tests. fake is a FakeDomicileHost (@domicile-desktop/sdk/fake-host) the test drives; without it, a desktop no test drives.

Dependencies

• @domicile-desktop/sdk for the desktop's types and FakeDomicileHost.
• @cprussin/option-result for watchPresence's Result.
• react and react-dom are peers: the shell's own copies.

Working on this package

For contributors to this repository. Shell authors don't need it.

bun run turbo test --filter @domicile-desktop/react