@react-x11/components 0.1.0 → 0.2.1

package/src/desktop-calendar/index.ts

@@ -0,0 +1,287 @@
+// Read the calendars the user's desktop already has, and hand them to a
+// `<Calendar dayContent>`.
+//
+// The point of this module is that an app gets the user's real events —
+// Google, Microsoft, CalDAV, local — without asking for a single credential
+// and without an OAuth flow, because the desktop already did all of that. See
+// `./eds.js` for how, and `../calendar/` for what to draw them on.
+//
+// Nothing here opens a D-Bus connection. `useSessionBus()` (or `sessionBus()`
+// for the imperative path) hands over react-x11's shared one, so an app is one
+// name on the bus however many features it turns on.
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useSessionBus } from 'react-x11';
+
+import { DesktopCalendar } from './eds.js';
+import type {
+  CalendarChange,
+  DesktopCalendarError,
+  DesktopCalendarInfo,
+  DesktopEvent,
+} from './eds.js';
+
+export { DesktopCalendar, parseKeyFile } from './eds.js';
+export type {
+  CalendarChange,
+  DesktopCalendarError,
+  DesktopCalendarInfo,
+  DesktopEvent,
+  EventsResult,
+} from './eds.js';
+export { IcalUnavailableError } from './ical.js';
+
+const pad = (n: number): string => String(n).padStart(2, '0');
+
+/**
+ * The local calendar day a `Date` falls on, as `'YYYY-MM-DD'`.
+ *
+ * Deliberately a local three-liner rather than an import from `../calendar/`:
+ * no component in this package imports another, because a lateral import
+ * makes the two one unit in a bundler's eyes and an app that wanted only the
+ * events would start paying for the grid. The **format** is the contract they
+ * share, not the function — these keys index straight into a `<Calendar>`'s
+ * `dayContent`.
+ */
+function dayKeyOf(date: Date): string {
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+
+/**
+ * Occurrences grouped by the local day they appear on — which is what a
+ * calendar grid actually renders.
+ *
+ * An all-day event spans `[start, end)` across possibly several days, and a
+ * timed one can cross midnight, so an event lands under **every** day it
+ * touches rather than only under its start.
+ */
+export function byDay(events: DesktopEvent[]): Map<string, DesktopEvent[]> {
+  const days = new Map<string, DesktopEvent[]>();
+  for (const event of events) {
+    // `end` is exclusive, so a one-day all-day event ending at the next
+    // midnight must not also mark the next day.
+    const lastMs = Math.max(event.start.getTime(), event.end.getTime() - 1);
+    const last = new Date(lastMs);
+    const cursor = new Date(
+      event.start.getFullYear(),
+      event.start.getMonth(),
+      event.start.getDate(),
+    );
+    while (cursor <= last) {
+      const key = dayKeyOf(cursor);
+      const list = days.get(key);
+      if (list) list.push(event);
+      else days.set(key, [event]);
+      cursor.setDate(cursor.getDate() + 1);
+    }
+  }
+  return days;
+}
+
+export type DesktopCalendarStatus =
+  'idle' | 'loading' | 'ready' | 'unavailable';
+
+export interface UseDesktopCalendarEventsOptions {
+  /** Start of the window to read, inclusive. */
+  from: Date;
+  /** End of the window, exclusive. */
+  to: Date;
+  /** Restrict to these calendar UIDs. Default: every enabled calendar. */
+  calendars?: string[];
+  /** Re-query when the desktop says something in the range changed. */
+  watch?: boolean;
+  /** Set false to hold off entirely — a picker that is not open yet. */
+  enabled?: boolean;
+}
+
+export interface UseDesktopCalendarEventsResult {
+  events: DesktopEvent[];
+  /** The same events, keyed by `'YYYY-MM-DD'`, ready for `dayContent`. */
+  byDay: Map<string, DesktopEvent[]>;
+  /** Every calendar found, for a legend or a filter. */
+  calendars: DesktopCalendarInfo[];
+  /** Backends that would not answer. Not fatal; the rest still loaded. */
+  errors: DesktopCalendarError[];
+  status: DesktopCalendarStatus;
+  /** Why there are no events: no bus, or no `ical.js`. */
+  error: Error | null;
+  /** Re-query now. */
+  refresh: () => void;
+}
+
+const NO_EVENTS: DesktopEvent[] = [];
+const NO_CALENDARS: DesktopCalendarInfo[] = [];
+const NO_ERRORS: DesktopCalendarError[] = [];
+
+/** The calendars a caller asked for by uid, or every enabled one. `onlyKey`
+ *  is the comma-joined list, because an array prop is a new identity every
+ *  render and these two effects are keyed on it. */
+function pickCalendars(
+  all: DesktopCalendarInfo[],
+  onlyKey: string,
+): DesktopCalendarInfo[] {
+  if (!onlyKey) return all.filter((c) => c.enabled);
+  const wanted = new Set(onlyKey.split(','));
+  return all.filter((c) => wanted.has(c.uid));
+}
+
+/**
+ * The user's desktop calendar events, as rendering state.
+ *
+ * ```tsx
+ * const { byDay } = useDesktopCalendarEvents({ from, to });
+ *
+ * <Calendar
+ *   dayContent={(day, state) =>
+ *     byDay.get(day)?.slice(0, 3).map((ev) => (
+ *       <box key={ev.uid} style={{ width: 4, height: 4, borderRadius: 2,
+ *                                  backgroundColor: state.selected
+ *                                    ? state.color
+ *                                    : (ev.calendar.color ?? '$accent') }} />
+ *     ))
+ *   }
+ * />
+ * ```
+ *
+ * **`from` and `to` are read by their timestamps, not their identity**, so
+ * `new Date(...)` inline in the render is fine and will not re-query on every
+ * paint. That is the mistake this hook would otherwise invite, and it costs a
+ * D-Bus round trip per frame.
+ *
+ * `status` is `'unavailable'` when there is no session bus or `ical.js` is not
+ * installed — both are ordinary on a machine that simply does not have them,
+ * so neither throws, and `error` says which it was. Treat it as "no calendar
+ * integration here", not as a failure to report.
+ */
+export function useDesktopCalendarEvents(
+  options: UseDesktopCalendarEventsOptions,
+): UseDesktopCalendarEventsResult {
+  const { from, to, calendars: only, watch = false, enabled = true } = options;
+  const { bus } = useSessionBus();
+
+  const [events, setEvents] = useState<DesktopEvent[]>(NO_EVENTS);
+  const [found, setFound] = useState<DesktopCalendarInfo[]>(NO_CALENDARS);
+  const [errors, setErrors] = useState<DesktopCalendarError[]>(NO_ERRORS);
+  const [status, setStatus] = useState<DesktopCalendarStatus>('idle');
+  const [error, setError] = useState<Error | null>(null);
+  const [nonce, setNonce] = useState(0);
+
+  const refresh = useCallback(() => setNonce((n) => n + 1), []);
+
+  // Timestamps, not the Date objects: a caller writing `from={new Date(y, m, 1)}`
+  // in the render body hands us a new identity every paint, and an effect keyed
+  // on that would re-query the bus on every frame.
+  const fromMs = from.getTime();
+  const toMs = to.getTime();
+  const onlyKey = only ? only.join(',') : '';
+
+  useEffect(() => {
+    if (!enabled) {
+      setStatus('idle');
+      return undefined;
+    }
+    if (!bus) {
+      // `useSessionBus` is still connecting, or there is no bus at all. Its
+      // own `status` distinguishes them; from here both mean "nothing yet".
+      setStatus('unavailable');
+      setEvents(NO_EVENTS);
+      return undefined;
+    }
+
+    let live = true;
+    const desktop = new DesktopCalendar(bus);
+
+    const run = async (): Promise<void> => {
+      setStatus('loading');
+      setError(null);
+      try {
+        const all = await desktop.listCalendars();
+        if (!live) return;
+        setFound(all);
+
+        const result = await desktop.eventsBetween(
+          new Date(fromMs),
+          new Date(toMs),
+          { calendars: pickCalendars(all, onlyKey) },
+        );
+        if (!live) return;
+        setEvents(result.events);
+        setErrors(result.errors);
+        setStatus('ready');
+      } catch (err) {
+        if (!live) return;
+        // No bus, no ical.js, no EDS on this desktop — all ordinary.
+        setError(err instanceof Error ? err : new Error(String(err)));
+        setEvents(NO_EVENTS);
+        setStatus('unavailable');
+      }
+    };
+
+    void run();
+
+    return () => {
+      live = false;
+      void desktop.dispose();
+    };
+    // `refresh` is stable; `nonce` is what a manual refresh moves.
+  }, [bus, enabled, fromMs, toMs, onlyKey, nonce, refresh]);
+
+  // The subscription is a **separate** effect, and deliberately not keyed on
+  // `nonce`: a change has to re-run the query, and only the query. Watching
+  // from inside the effect the change re-runs means every notification tears
+  // the views down and starts new ones — which is a loop as soon as anything
+  // is delivered while a view is starting, and was one for as long as
+  // `Start()` reported the range's existing contents as a change.
+  //
+  // The cost is one extra `listCalendars()` per range, not per refresh.
+  useEffect(() => {
+    if (!enabled || !watch || !bus) return undefined;
+
+    let live = true;
+    let stopWatching: (() => Promise<void>) | null = null;
+    const desktop = new DesktopCalendar(bus);
+
+    void (async () => {
+      try {
+        const all = await desktop.listCalendars();
+        if (!live) return;
+        stopWatching = await desktop.watch(
+          new Date(fromMs),
+          new Date(toMs),
+          () => {
+            // Re-query rather than patch: a recurrence master edited months
+            // away changes what this range looks like.
+            if (live) refresh();
+          },
+          { calendars: pickCalendars(all, onlyKey) },
+        );
+        if (!live) await stopWatching();
+      } catch {
+        // No bus, no EDS, nothing to watch. The query effect above is what
+        // reports that to the caller; a second copy of it would only race.
+      }
+    })();
+
+    return () => {
+      live = false;
+      void (async () => {
+        if (stopWatching) await stopWatching();
+        await desktop.dispose();
+      })();
+    };
+  }, [bus, enabled, watch, fromMs, toMs, onlyKey, refresh]);
+
+  const grouped = useMemo(() => byDay(events), [events]);
+
+  return {
+    events,
+    byDay: grouped,
+    calendars: found,
+    errors,
+    status,
+    error,
+    refresh,
+  };
+}
+
+/** A subscription that only reports *when* something changed. */
+export type { CalendarChange as DesktopCalendarChange };

package/src/embed/client.ts

@@ -0,0 +1,311 @@
+// The lifecycle both XEmbed wrappers have, with none of the vocabulary
+// either of them has.
+//
+// `<Terminal>` and `<MediaPlayer>` are the same component twice: render a
+// `<foreign>` with no `windowId` so it *adopts* whatever turns up inside it,
+// take the container id `onReady` hands over, spawn a program that draws into
+// that id, and hand the program back when the tree changes. Only the argv and
+// the control channel differ, and those are what the two `backends.ts` files
+// are for.
+//
+// Everything here is ordinary React state. The X part is one prop —
+// `onReady` — because core's `<foreign>` already owns the protocol
+// (react-x11#269, ntk#246): the reparent, the save set, `_XEMBED_INFO`, the
+// synthetic ConfigureNotify, and handing the client back on unmount without
+// ever destroying it.
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import { nodeProcessHost } from './host.js';
+import type { ExitInfo, ProcessHost, SpawnedProcess } from './host.js';
+
+/**
+ * Where the child is in its life.
+ *
+ * `'unavailable'` is not an error state to report as a failure: a machine
+ * with no terminal emulator installed, or no mpv, is an ordinary machine.
+ * Both components render their `fallback` on it, the way
+ * `useDesktopCalendarEvents` reports "no bus, no ical.js" rather than
+ * throwing.
+ */
+export type EmbedStatus =
+  'idle' | 'starting' | 'running' | 'exited' | 'unavailable';
+
+/**
+ * No backend for this component is installed.
+ *
+ * Thrown by a `PlanFactory`, caught by the hook, and turned into
+ * `status: 'unavailable'`. `tried` is what was looked for, so the message an
+ * app shows can name the install line rather than saying "not found".
+ */
+export class BackendUnavailableError extends Error {
+  readonly tried: readonly string[];
+
+  constructor(what: string, tried: readonly string[]) {
+    super(
+      `@react-x11/components: no ${what} backend is installed — looked for ` +
+        `${tried.join(', ')}. Install one, or pass \`fallback\` to render ` +
+        'something else.',
+    );
+    this.name = 'BackendUnavailableError';
+    this.tried = tried;
+  }
+}
+
+/** What to run, and what to do with it once it is running. */
+export interface LaunchPlan {
+  /** Absolute path or a name on `PATH`. */
+  command: string;
+  args: readonly string[];
+  cwd?: string;
+  env?: Record<string, string | undefined>;
+  /** Which backend this plan chose, for `onBackend` and the handle. */
+  backend?: string;
+  /**
+   * Attach a control channel now that the process exists. Its return value is
+   * called at teardown, before the process is signalled.
+   */
+  attach?(
+    process: SpawnedProcess,
+  ): void | (() => void) | Promise<void | (() => void)>;
+  /** Always run at teardown — temporary directories, sockets. */
+  dispose?(): void | Promise<void>;
+}
+
+export interface PlanContext {
+  /** The `<foreign>` container the program must draw into. */
+  windowId: number;
+  host: ProcessHost;
+}
+
+/** Builds the command line, once the window to draw into exists. */
+export type PlanFactory = (context: PlanContext) => Promise<LaunchPlan>;
+
+export interface UseEmbeddedClientOptions {
+  /**
+   * **Must be referentially stable for as long as the child should keep
+   * running.** A new identity is the restart signal — that is how "the
+   * command changed" reaches a program that cannot be reconfigured in place —
+   * so a factory rebuilt every render restarts the child every render.
+   *
+   * Both components build theirs with `useMemo` over a *string* key rather
+   * than over the props themselves, because `command={['bash']}` is a new
+   * array on every paint and an effect keyed on that never settles. Same
+   * reason `useDesktopCalendarEvents` keys on `from.getTime()`.
+   */
+  plan: PlanFactory;
+  /** Defaults to `nodeProcessHost()`. */
+  host?: ProcessHost;
+  /** False holds off entirely — a pane that is not visible yet. */
+  enabled?: boolean;
+  /** Sent on unmount and on restart. Default `SIGTERM`. */
+  stopSignal?: string;
+  onStart?: (info: { process: SpawnedProcess; backend?: string }) => void;
+  onExit?: (info: ExitInfo) => void;
+  /** Spawn failures and missing backends alike. */
+  onError?: (err: Error) => void;
+}
+
+export interface EmbeddedClient {
+  status: EmbedStatus;
+  /** The last failure, including a `BackendUnavailableError`. */
+  error: Error | null;
+  pid: number | null;
+  /** The container window, once `<foreign>` has one. */
+  windowId: number | null;
+  /** Which backend the plan picked. */
+  backend: string | null;
+  /** Wire straight to `<foreign onReady>`. */
+  handleReady: (info: { windowId: number }) => void;
+  /** Stop the child and start it again with a freshly built plan. */
+  restart: () => void;
+  /** Signal the child. `false` if there is not one. */
+  signal: (signal?: string) => boolean;
+}
+
+/**
+ * Run a program inside a `<foreign>`.
+ *
+ * ```jsx
+ * const client = useEmbeddedClient({ plan });
+ * return <foreign onReady={client.handleReady} style={{ flexGrow: 1 }} />;
+ * ```
+ *
+ * The `<foreign>` is rendered by the caller rather than here, because the
+ * element's props — style, focus, the `onEmbedded`/`onClientGone` handlers a
+ * component may want to compose with — belong to the component, not to the
+ * lifecycle.
+ */
+export function useEmbeddedClient(
+  options: UseEmbeddedClientOptions,
+): EmbeddedClient {
+  const { plan, enabled = true, stopSignal = 'SIGTERM' } = options;
+  const host = useMemo(() => options.host ?? nodeProcessHost(), [options.host]);
+
+  const [windowId, setWindowId] = useState<number | null>(null);
+  const [status, setStatus] = useState<EmbedStatus>('idle');
+  const [error, setError] = useState<Error | null>(null);
+  const [pid, setPid] = useState<number | null>(null);
+  const [backend, setBackend] = useState<string | null>(null);
+  const [generation, setGeneration] = useState(0);
+
+  // The live child, for `signal()`. A ref rather than state because a caller
+  // reaching for it through a handle is not rendering, and re-rendering the
+  // tree because a pid arrived would be work for nothing.
+  const processRef = useRef<SpawnedProcess | null>(null);
+
+  // Handlers are read at the moment they fire, so a component that passes a
+  // fresh arrow function every render does not restart its child.
+  const handlers = useRef(options);
+  handlers.current = options;
+
+  const handleReady = useCallback((info: { windowId: number }) => {
+    setWindowId(info.windowId);
+  }, []);
+
+  const restart = useCallback(() => setGeneration((n) => n + 1), []);
+
+  const signal = useCallback((sig = 'SIGTERM') => {
+    const child = processRef.current;
+    return child ? child.kill(sig) : false;
+  }, []);
+
+  useEffect(() => {
+    if (!enabled || windowId === null) {
+      setStatus('idle');
+      return undefined;
+    }
+
+    let live = true;
+    let child: SpawnedProcess | null = null;
+    let detach: (() => void) | void;
+    let planned: LaunchPlan | null = null;
+
+    const fail = (err: unknown, next: EmbedStatus): void => {
+      const wrapped = err instanceof Error ? err : new Error(String(err));
+      if (!live) return;
+      setError(wrapped);
+      setStatus(next);
+      handlers.current.onError?.(wrapped);
+    };
+
+    void (async () => {
+      setStatus('starting');
+      setError(null);
+      try {
+        planned = await plan({ windowId, host });
+      } catch (err) {
+        // "no xterm on this machine" is not the same kind of news as "spawn
+        // failed", and only one of the two is worth a fallback.
+        fail(
+          err,
+          err instanceof BackendUnavailableError ? 'unavailable' : 'exited',
+        );
+        return;
+      }
+      if (!live) {
+        await planned.dispose?.();
+        return;
+      }
+
+      try {
+        child = await host.spawn(planned.command, planned.args, {
+          cwd: planned.cwd,
+          env: planned.env,
+        });
+      } catch (err) {
+        await planned.dispose?.();
+        fail(err, 'exited');
+        return;
+      }
+
+      // Unmounted while `spawn` was in flight: nothing rendered it, so
+      // nothing should outlive it.
+      if (!live) {
+        child.kill(stopSignal);
+        await planned.dispose?.();
+        return;
+      }
+
+      processRef.current = child;
+      setPid(child.pid);
+      setBackend(planned.backend ?? null);
+      setStatus('running');
+
+      child.onExit((info) => {
+        if (!live) return;
+        processRef.current = null;
+        setStatus('exited');
+        setPid(null);
+        handlers.current.onExit?.(info);
+      });
+      child.onError((err) => fail(err, 'exited'));
+
+      handlers.current.onStart?.({ process: child, backend: planned.backend });
+
+      try {
+        const opened = await planned.attach?.(child);
+        // Opening a control channel can take seconds — the socket does not
+        // exist until the player creates it — so the teardown below may
+        // already have run with nothing to tear down. Closing it here is the
+        // only chance there will be.
+        if (live) detach = opened;
+        else opened?.();
+      } catch (err) {
+        // A control channel that would not open is a degraded player, not a
+        // dead one: the video is already on screen.
+        fail(err, 'running');
+      }
+    })();
+
+    return () => {
+      live = false;
+      processRef.current = null;
+      // Order matters: drop the control channel first, so a socket close
+      // triggered by the signal is not reported as the player failing.
+      try {
+        detach?.();
+      } catch {
+        // a channel that is already gone
+      }
+      child?.kill(stopSignal);
+      void planned?.dispose?.();
+    };
+    // `plan` is the restart signal — see the note on the option.
+  }, [enabled, windowId, plan, host, stopSignal, generation]);
+
+  return {
+    status,
+    error,
+    pid,
+    windowId,
+    backend,
+    handleReady,
+    restart,
+    signal,
+  };
+}
+
+/**
+ * The first of `candidates` that is installed, or a `BackendUnavailableError`
+ * naming all of them.
+ *
+ * Auto-detection rather than a hard dependency is the whole reason both
+ * components take a `backend` prop that defaults to `'auto'`: this package
+ * cannot depend on a binary, and most machines have exactly one of the ones
+ * it can drive.
+ */
+export async function resolveBackend<T extends { binaries: readonly string[] }>(
+  host: ProcessHost,
+  what: string,
+  candidates: readonly T[],
+): Promise<{ backend: T; path: string }> {
+  const tried: string[] = [];
+  for (const backend of candidates) {
+    for (const binary of backend.binaries) {
+      tried.push(binary);
+      const path = await host.which(binary);
+      if (path) return { backend, path };
+    }
+  }
+  throw new BackendUnavailableError(what, tried);
+}