@domicile-desktop/react 0.0.0-alpha-2edc3c14d846 → 0.0.0-alpha-b85d9bb6d4af

package/README.md

@@ -31,6 +31,17 @@ export const Shell = mount(Focused);
   - `./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.
@@ -38,6 +49,7 @@ export const Shell = mount(Focused);
 ## 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.
 
 ## Test

package/dist/appearance.d.ts

@@ -0,0 +1,3 @@
+import type { Appearance } from "@domicile-desktop/sdk/desktop/appearance";
+/** The accent, contrast and motion the config asks for, as they change. */
+export declare const useAppearance: () => Appearance;

package/dist/appearance.js

@@ -0,0 +1,11 @@
+import { useMemo } from "react";
+import { useDomicile } from "./domicile-provider";
+import { useWatch } from "./use-watch";
+/** The accent, contrast and motion the config asks for, as they change. */
+export const useAppearance = () => {
+    const { appearance } = useDomicile();
+    const accentColor = useWatch(appearance, "change", () => appearance.accentColor);
+    const highContrast = useWatch(appearance, "change", () => appearance.highContrast);
+    const reducedMotion = useWatch(appearance, "change", () => appearance.reducedMotion);
+    return useMemo(() => ({ accentColor, highContrast, reducedMotion }), [accentColor, highContrast, reducedMotion]);
+};

package/dist/displays.d.ts

@@ -0,0 +1,3 @@
+import type { Display } from "@domicile-desktop/sdk/desktop/displays";
+/** The screens, or `undefined` until the compositor describes the desktop. */
+export declare const useDisplays: () => readonly Display[] | undefined;

package/dist/displays.js

@@ -0,0 +1,7 @@
+import { useDomicile } from "./domicile-provider";
+import { useWatch } from "./use-watch";
+/** The screens, or `undefined` until the compositor describes the desktop. */
+export const useDisplays = () => {
+    const { displays } = useDomicile();
+    return useWatch(displays, "change", () => displays.list);
+};

package/dist/domicile-provider.d.ts

@@ -0,0 +1,12 @@
+import type { AppDomicile } from "@domicile-desktop/sdk/desktop/app-desktop";
+import type { Domicile } from "@domicile-desktop/sdk/desktop/desktop";
+import type { ReactNode } from "react";
+/** Hands `domicile` to every hook below. `mount` renders one for you. */
+export declare const DomicileProvider: ({ children, domicile, }: {
+    children: ReactNode;
+    domicile: Domicile | AppDomicile;
+}) => import("react").JSX.Element;
+/** A shell's desktop, from the provider above. Throws under an app's. */
+export declare const useDomicile: () => Domicile;
+/** The desktop above as an app has it: a shell's has all of it too. */
+export declare const useAppDomicile: () => AppDomicile;

package/dist/domicile-provider.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+const DomicileContext = createContext(undefined);
+/** Hands `domicile` to every hook below. `mount` renders one for you. */
+export const DomicileProvider = ({ children, domicile, }) => _jsx(DomicileContext, { value: domicile, children: children });
+/** A shell's desktop, from the provider above. Throws under an app's. */
+export const useDomicile = () => {
+    const domicile = useProvided("useDomicile");
+    if (isShells(domicile)) {
+        return domicile;
+    }
+    else {
+        throw new Error("useDomicile: the desktop above is an app's; use useAppDomicile");
+    }
+};
+/** The desktop above as an app has it: a shell's has all of it too. */
+export const useAppDomicile = () => useProvided("useAppDomicile");
+const useProvided = (hook) => {
+    const domicile = useContext(DomicileContext);
+    if (domicile === undefined) {
+        throw new Error(`${hook}: no <DomicileProvider> above`);
+    }
+    else {
+        return domicile;
+    }
+};
+// Only a shell's desktop manages windows.
+const isShells = (domicile) => "windows" in domicile;

package/dist/failure-boundary.d.ts

@@ -0,0 +1,15 @@
+import type { ReactNode } from "react";
+import { Component } from "react";
+type Props = {
+    children: ReactNode;
+};
+type State = {
+    error: unknown;
+};
+/** Shows the error a child throws while drawing, in place of the children. */
+export declare class FailureBoundary extends Component<Props, State> {
+    state: State;
+    static getDerivedStateFromError(error: unknown): State;
+    render(): ReactNode;
+}
+export {};

package/dist/failure-boundary.js

@@ -0,0 +1,13 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Component } from "react";
+/** Shows the error a child throws while drawing, in place of the children. */
+export class FailureBoundary extends Component {
+    state = { error: undefined };
+    static getDerivedStateFromError(error) {
+        return { error };
+    }
+    render() {
+        const { error } = this.state;
+        return error === undefined ? (this.props.children) : (_jsxs("div", { role: "alert", children: [_jsx("p", { children: "Something went wrong, and this can't be shown." }), _jsx("pre", { children: error instanceof Error ? error.message : String(error) })] }));
+    }
+}

package/dist/fake-domicile.d.ts

@@ -0,0 +1,10 @@
+import { FakeDomicileHost } from "@domicile-desktop/sdk/fake-host";
+import type { ReactNode } from "react";
+/**
+ * Hands the components below `fake`'s desktop, which the test sets state on
+ * and reads calls from. Without `fake`, a desktop no test drives.
+ */
+export declare const FakeDomicile: ({ children, fake, }: {
+    children: ReactNode;
+    fake?: FakeDomicileHost | undefined;
+}) => import("react").JSX.Element;

package/dist/fake-domicile.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// The desktop for a component's tests.
+//
+// ```tsx
+// const fake = new FakeDomicileHost();
+// render(<FakeDomicile fake={fake}><Taskbar /></FakeDomicile>);
+// act(() => fake.appear("term", { title: "Terminal" }));
+// ```
+import { FakeDomicileHost } from "@domicile-desktop/sdk/fake-host";
+import { useState } from "react";
+import { DomicileProvider } from "./domicile-provider";
+/**
+ * Hands the components below `fake`'s desktop, which the test sets state on
+ * and reads calls from. Without `fake`, a desktop no test drives.
+ */
+export const FakeDomicile = ({ children, fake, }) => {
+    const [own] = useState(() => new FakeDomicileHost());
+    return (_jsx(DomicileProvider, { domicile: (fake ?? own).domicile, children: children }));
+};

package/dist/mount.d.ts

@@ -0,0 +1,12 @@
+import type { AppDomicile } from "@domicile-desktop/sdk/desktop/app-desktop";
+import type { Domicile } from "@domicile-desktop/sdk/desktop/desktop";
+import type { ComponentType } from "react";
+/**
+ * A `Shell` or `main` that draws `App` with the desktop it is handed, in
+ * strict mode, showing an error in its place if it throws.
+ *
+ * ```ts
+ * export const Shell: ShellModule = mount(Desktop);
+ * ```
+ */
+export declare const mount: (App: ComponentType) => (root: HTMLElement, domicile: Domicile | AppDomicile) => void;

package/dist/mount.js

@@ -0,0 +1,27 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { StrictMode } from "react";
+import { flushSync } from "react-dom";
+import { createRoot } from "react-dom/client";
+import { DomicileProvider } from "./domicile-provider";
+import { FailureBoundary } from "./failure-boundary";
+/**
+ * A `Shell` or `main` that draws `App` with the desktop it is handed, in
+ * strict mode, showing an error in its place if it throws.
+ *
+ * ```ts
+ * export const Shell: ShellModule = mount(Desktop);
+ * ```
+ */
+export const mount = (App) => (root, domicile) => {
+    // An element of its own: the page reports failures by appending to
+    // `root`, and a React root there would erase them. It draws no box, so
+    // the app sizes against `root` and nothing is positioned against it.
+    const element = root.ownerDocument.createElement("div");
+    element.style.display = "contents";
+    root.append(element);
+    const reactRoot = createRoot(element);
+    // Synchronously: the page draws nothing until `Shell` returns.
+    flushSync(() => {
+        reactRoot.render(_jsx(StrictMode, { children: _jsx(FailureBoundary, { children: _jsx(DomicileProvider, { domicile: domicile, children: _jsx(App, {}) }) }) }));
+    });
+};

package/dist/per-desktop.d.ts

@@ -0,0 +1,7 @@
+import type { Domicile } from "@domicile-desktop/sdk/desktop/desktop";
+/**
+ * `make`, run once per desktop: every caller with the same `domicile` gets the
+ * same value. For watches and stores that every bar, panel and the lock
+ * screen share without a provider passing them down.
+ */
+export declare const perDesktop: <T>(make: (domicile: Domicile) => T) => ((domicile: Domicile) => T);

package/dist/per-desktop.js

@@ -0,0 +1,19 @@
+/**
+ * `make`, run once per desktop: every caller with the same `domicile` gets the
+ * same value. For watches and stores that every bar, panel and the lock
+ * screen share without a provider passing them down.
+ */
+export const perDesktop = (make) => {
+    const made = new WeakMap();
+    return (domicile) => {
+        const known = made.get(domicile);
+        if (known === undefined) {
+            const value = make(domicile);
+            made.set(domicile, value);
+            return value;
+        }
+        else {
+            return known;
+        }
+    };
+};

package/dist/portals.d.ts

@@ -0,0 +1,9 @@
+import type { BoundShortcut, Capturing, PortalRequest, PortalWallpaper } from "@domicile-desktop/sdk/portal";
+/** Every unanswered portal request, oldest first. */
+export declare const usePortalRequests: () => readonly PortalRequest[] | undefined;
+/** Every session that controls or captures input. */
+export declare const useCapturing: () => readonly Capturing[] | undefined;
+/** Every chord applications hold through the GlobalShortcuts portal. */
+export declare const useBoundShortcuts: () => readonly BoundShortcut[] | undefined;
+/** The pictures applications set through the Wallpaper portal. */
+export declare const usePortalWallpaper: () => PortalWallpaper | undefined;

package/dist/portals.js

@@ -0,0 +1,23 @@
+import { useDomicile } from "./domicile-provider";
+import { useWatch } from "./use-watch";
+// Each is `undefined` until the compositor's first push.
+/** Every unanswered portal request, oldest first. */
+export const usePortalRequests = () => {
+    const { portals } = useDomicile();
+    return useWatch(portals, "change", () => portals.requests);
+};
+/** Every session that controls or captures input. */
+export const useCapturing = () => {
+    const { portals } = useDomicile();
+    return useWatch(portals, "change", () => portals.capturing);
+};
+/** Every chord applications hold through the GlobalShortcuts portal. */
+export const useBoundShortcuts = () => {
+    const { portals } = useDomicile();
+    return useWatch(portals, "change", () => portals.boundShortcuts);
+};
+/** The pictures applications set through the Wallpaper portal. */
+export const usePortalWallpaper = () => {
+    const { portals } = useDomicile();
+    return useWatch(portals, "change", () => portals.wallpaper);
+};

package/dist/session.d.ts

@@ -0,0 +1,4 @@
+/** Whether the user stepped away, or `undefined` until the compositor says. */
+export declare const useIdle: () => boolean | undefined;
+/** Whether the desk is locked, or `undefined` until the compositor says. */
+export declare const useLocked: () => boolean | undefined;

package/dist/session.js

@@ -0,0 +1,12 @@
+import { useDomicile } from "./domicile-provider";
+import { useWatch } from "./use-watch";
+/** Whether the user stepped away, or `undefined` until the compositor says. */
+export const useIdle = () => {
+    const { session } = useDomicile();
+    return useWatch(session, "idlechange", () => session.idle);
+};
+/** Whether the desk is locked, or `undefined` until the compositor says. */
+export const useLocked = () => {
+    const { session } = useDomicile();
+    return useWatch(session, "lockchange", () => session.locked);
+};

package/dist/shared-watch.d.ts

@@ -0,0 +1,15 @@
+/** One watch that many components read, for `useSyncExternalStore`. */
+export type SharedWatch<T> = {
+    /** Starts the watch for the first subscriber and stops it after the last. */
+    subscribe: (onChange: () => void) => () => void;
+    /** The latest value, or `undefined` before the first and while stopped. */
+    current: () => T | undefined;
+};
+/**
+ * Shares the watch `start` begins among every subscriber, so a library's
+ * watch runs once however many bars show it.
+ *
+ * `start` calls `onValue` with each value and returns what stops it. Failures
+ * stay `start`'s to handle, as values or logs.
+ */
+export declare const sharedWatch: <T>(start: (onValue: (value: T) => void) => () => void) => SharedWatch<T>;

package/dist/shared-watch.js

@@ -0,0 +1,37 @@
+/**
+ * Shares the watch `start` begins among every subscriber, so a library's
+ * watch runs once however many bars show it.
+ *
+ * `start` calls `onValue` with each value and returns what stops it. Failures
+ * stay `start`'s to handle, as values or logs.
+ */
+export const sharedWatch = (start) => {
+    const listeners = new Set();
+    const state = { running: undefined };
+    return {
+        current: () => state.running?.value,
+        subscribe: (onChange) => {
+            listeners.add(onChange);
+            if (state.running === undefined) {
+                state.running = run(start, listeners);
+            }
+            return () => {
+                listeners.delete(onChange);
+                if (listeners.size === 0) {
+                    state.running?.stop();
+                    state.running = undefined;
+                }
+            };
+        },
+    };
+};
+const run = (start, listeners) => {
+    const running = { value: undefined };
+    const stop = start((value) => {
+        running.value = value;
+        for (const onChange of listeners) {
+            onChange();
+        }
+    });
+    return Object.assign(running, { stop });
+};

package/dist/use-shared-watch.d.ts

@@ -0,0 +1,9 @@
+import type { Domicile } from "@domicile-desktop/sdk/desktop/desktop";
+import type { SharedWatch } from "./shared-watch";
+/** The latest value of `watch`, or `undefined` before the first. */
+export declare const useSharedWatch: <T>(watch: SharedWatch<T>) => T | undefined;
+/**
+ * The latest value of the desktop's `desk` watch, or `undefined` before the
+ * first. `desk` is a `perDesktop`, so every caller shares one watch.
+ */
+export declare const useDeskWatch: <T>(desk: (domicile: Domicile) => SharedWatch<T>) => T | undefined;

package/dist/use-shared-watch.js

@@ -0,0 +1,9 @@
+import { useSyncExternalStore } from "react";
+import { useDomicile } from "./domicile-provider";
+/** The latest value of `watch`, or `undefined` before the first. */
+export const useSharedWatch = (watch) => useSyncExternalStore(watch.subscribe, watch.current);
+/**
+ * The latest value of the desktop's `desk` watch, or `undefined` before the
+ * first. `desk` is a `perDesktop`, so every caller shares one watch.
+ */
+export const useDeskWatch = (desk) => useSharedWatch(desk(useDomicile()));

package/dist/use-watch.d.ts

@@ -0,0 +1,12 @@
+import type { Unsubscribe } from "@domicile-desktop/sdk/desktop/subscribe";
+/** A namespace of the desktop, or anything with its `on`. */
+export type Watchable<K extends string> = {
+    on: (type: K, listener: () => void) => Unsubscribe;
+};
+/**
+ * What `read` answers, read again on each `type` event of `source`.
+ *
+ * `read` must answer the same value until the event: the desktop's lists keep
+ * their identity between changes, so reading an attribute does.
+ */
+export declare const useWatch: <K extends string, T>(source: Watchable<K>, type: NoInfer<K>, read: () => T) => T;

package/dist/use-watch.js

@@ -0,0 +1,13 @@
+// The one way a hook here follows the desktop: read an attribute again each
+// time its namespace says it changed.
+import { useCallback, useSyncExternalStore } from "react";
+/**
+ * What `read` answers, read again on each `type` event of `source`.
+ *
+ * `read` must answer the same value until the event: the desktop's lists keep
+ * their identity between changes, so reading an attribute does.
+ */
+export const useWatch = (source, type, read) => {
+    const subscribe = useCallback((onChange) => source.on(type, onChange), [source, type]);
+    return useSyncExternalStore(subscribe, read);
+};

package/dist/watch-presence.d.ts

@@ -0,0 +1,15 @@
+import type { Result } from "@cprussin/option-result";
+import type { SystemError } from "@domicile-desktop/sdk/system";
+/**
+ * Calls `onPresent` with `read` now and whenever it changes, and returns a
+ * function that stops watching. For whether hardware exists, read
+ * from `/sys`, which works while the desktop is locked.
+ */
+export declare const watchPresence: (read: () => Promise<Result<boolean, SystemError>>, onPresent: (present: Result<boolean, SystemError>) => void, every?: typeof everyInterval) => (() => void);
+/**
+ * Whether hardware is absent: not looked for yet, or
+ * not there. A failed look shows the item, since the hardware may be there.
+ */
+export declare const isAbsent: (present: Result<boolean, SystemError> | undefined) => boolean;
+declare const everyInterval: (ms: number, tick: () => void) => (() => void);
+export {};

package/dist/watch-presence.js

@@ -0,0 +1,48 @@
+/** How often to look again: a device plugged in or out. */
+const EVERY_MS = 10_000;
+/**
+ * Calls `onPresent` with `read` now and whenever it changes, and returns a
+ * function that stops watching. For whether hardware exists, read
+ * from `/sys`, which works while the desktop is locked.
+ */
+export const watchPresence = (read, onPresent, every = everyInterval) => {
+    const watch = {
+        shown: undefined,
+        stopped: false,
+    };
+    const look = () => {
+        read()
+            .then((present) => {
+            const shown = JSON.stringify(present.match({
+                Err: (error) => error,
+                Ok: (found) => found,
+            }));
+            if (!watch.stopped && shown !== watch.shown) {
+                watch.shown = shown;
+                onPresent(present);
+            }
+        })
+            .catch((error) => {
+            // biome-ignore lint/suspicious/noConsole: surfacing a background failure; the next look reads again
+            console.error("Failed to look for hardware", error);
+        });
+    };
+    look();
+    const stopClock = every(EVERY_MS, look);
+    return () => {
+        watch.stopped = true;
+        stopClock();
+    };
+};
+/**
+ * Whether hardware is absent: not looked for yet, or
+ * not there. A failed look shows the item, since the hardware may be there.
+ */
+export const isAbsent = (present) => present === undefined ||
+    present.match({ Err: () => false, Ok: (has) => !has });
+const everyInterval = (ms, tick) => {
+    const id = setInterval(tick, ms);
+    return () => {
+        clearInterval(id);
+    };
+};

package/dist/windows.d.ts

@@ -0,0 +1,5 @@
+import type { ClientWindow } from "@domicile-desktop/sdk/desktop/windows";
+/** Every client window, in the order they appeared. */
+export declare const useWindows: () => readonly ClientWindow[];
+/** The window holding the keyboard, or `undefined` while the shell holds it. */
+export declare const useFocusedWindow: () => string | undefined;

package/dist/windows.js

@@ -0,0 +1,12 @@
+import { useDomicile } from "./domicile-provider";
+import { useWatch } from "./use-watch";
+/** Every client window, in the order they appeared. */
+export const useWindows = () => {
+    const { windows } = useDomicile();
+    return useWatch(windows, "change", () => windows.list);
+};
+/** The window holding the keyboard, or `undefined` while the shell holds it. */
+export const useFocusedWindow = () => {
+    const { windows } = useDomicile();
+    return useWatch(windows, "focuschange", () => windows.focused);
+};

package/package.json

@@ -1,6 +1,7 @@
 {
   "dependencies": {
-    "@domicile-desktop/sdk": "0.0.0-alpha-2edc3c14d846"
+    "@cprussin/option-result": "^2.0.1",
+    "@domicile-desktop/sdk": "0.0.0-alpha-b85d9bb6d4af"
   },
   "description": "React for a Domicile shell or app: mount it on the desktop, read the desktop from context, and follow its state with hooks.",
   "devDependencies": {
@@ -39,6 +40,10 @@
       "types": "./dist/mount.d.ts",
       "default": "./dist/mount.js"
     },
+    "./per-desktop": {
+      "types": "./dist/per-desktop.d.ts",
+      "default": "./dist/per-desktop.js"
+    },
     "./portals": {
       "types": "./dist/portals.d.ts",
       "default": "./dist/portals.js"
@@ -47,10 +52,22 @@
       "types": "./dist/session.d.ts",
       "default": "./dist/session.js"
     },
+    "./shared-watch": {
+      "types": "./dist/shared-watch.d.ts",
+      "default": "./dist/shared-watch.js"
+    },
+    "./use-shared-watch": {
+      "types": "./dist/use-shared-watch.d.ts",
+      "default": "./dist/use-shared-watch.js"
+    },
     "./use-watch": {
       "types": "./dist/use-watch.d.ts",
       "default": "./dist/use-watch.js"
     },
+    "./watch-presence": {
+      "types": "./dist/watch-presence.d.ts",
+      "default": "./dist/watch-presence.js"
+    },
     "./windows": {
       "types": "./dist/windows.d.ts",
       "default": "./dist/windows.js"
@@ -75,7 +92,7 @@
     "test:unit": "bun test"
   },
   "type": "module",
-  "version": "0.0.0-alpha-2edc3c14d846",
+  "version": "0.0.0-alpha-b85d9bb6d4af",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/cprussin/domicile.git",