react-x11 2.9.0 → 2.9.2

package/src/desktopcalendarhooks.js

@@ -0,0 +1,259 @@
+// `useDesktopCalendarEvents()` — the desktop's calendar as rendering state:
+// the occurrences in a range, grouped the way a calendar grid asks for them,
+// re-read when the store moves.
+//
+// The imperative half in `desktopcalendar.js` is complete; what a component
+// wants on top is binding — the tree's connection, a handle that is closed
+// when the view goes away, the grant asked for on the first read rather than
+// at start-up — not another rung.
+//
+// ```jsx
+// const { byDay } = useDesktopCalendarEvents({ from, to, watch: true });
+//
+// <Calendar
+//   dayContent={(day) =>
+//     byDay.get(day)?.slice(0, 3).map((ev) => (
+//       <box key={ev.uid} style={{ width: 4, height: 4, borderRadius: 2,
+//                                  backgroundColor: ev.calendar.color ?? '$accent' }} />
+//     ))
+//   }
+// />
+// ```
+//
+// `<Calendar>` is `@react-x11/components`; the `'YYYY-MM-DD'` keys are the
+// one contract between the two packages, which is why `byDay` is here and
+// the grid is there.
+
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import { useAppOrNull } from './appcontext.js';
+import {
+  CalendarAccessError,
+  byDay as groupByDay,
+  desktopCalendar,
+} from './desktopcalendar.js';
+import { openPrivacySettings } from './permissions.js';
+
+const NO_EVENTS = [];
+const NO_CALENDARS = [];
+const NO_ERRORS = [];
+
+/** 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 effects are keyed on it. */
+function pickCalendars(all, onlyKey) {
+  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.
+ *
+ * **`from` and `to` are read by their timestamps, not their identity**, so
+ * `new Date(...)` inline in the render body is fine and will not re-query on
+ * every paint. That is the mistake this hook would otherwise invite, and it
+ * costs a round trip per frame.
+ *
+ * `status` is the whole answer:
+ *
+ * - `'idle'` — `enabled: false`, nothing asked yet.
+ * - `'loading'` — a read is in flight. The first one may be showing the
+ *   system's permission prompt: the first read is what asks, so that a
+ *   picker the user never opens never prompts.
+ * - `'ready'` — `events` is this range.
+ * - `'denied'` — the **user's** answer. `openSettings()` puts them in front
+ *   of the switch; do not show that button on any other status.
+ * - `'unavailable'` — the **machine's** answer: no bridge, not a Mac, no
+ *   Evolution Data Server on the bus. An ordinary state, not a failure —
+ *   hide the feature rather than reporting it.
+ *
+ * `errors` is different from all of them: calendars that would not answer
+ * while others did, which is one unreachable CalDAV server rather than a
+ * failed read.
+ */
+export function useDesktopCalendarEvents(options) {
+  const { from, to, calendars: only, watch = false, enabled = true } = options;
+  const app = useAppOrNull();
+
+  const [cal, setCal] = useState(null);
+  const [backend, setBackend] = useState(null);
+  const [events, setEvents] = useState(NO_EVENTS);
+  const [found, setFound] = useState(NO_CALENDARS);
+  const [errors, setErrors] = useState(NO_ERRORS);
+  const [status, setStatus] = useState('idle');
+  const [error, setError] = useState(null);
+  const [nonce, setNonce] = useState(0);
+  const live = useRef(true);
+
+  const refresh = useCallback(() => setNonce((n) => n + 1), []);
+  const openSettings = useCallback(() => openPrivacySettings('calendars'), []);
+
+  // 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 every frame.
+  const fromMs = from.getTime();
+  const toMs = to.getTime();
+  const onlyKey = only ? only.join(',') : '';
+
+  useEffect(() => {
+    live.current = true;
+    return () => {
+      live.current = false;
+    };
+  }, []);
+
+  // The handle, opened once per connection: the `osascript` child and the
+  // bus reference behind it are shared, and one hook must not open a second
+  // of either every time the month changes.
+  useEffect(() => {
+    if (!enabled) {
+      setCal(null);
+      setBackend(null);
+      setStatus('idle');
+      return undefined;
+    }
+
+    let alive = true;
+    let handle = null;
+    setStatus('loading');
+    desktopCalendar({ app }).then(
+      (opened) => {
+        if (!alive) {
+          void opened?.close();
+          return;
+        }
+        handle = opened;
+        setCal(opened);
+        setBackend(opened ? opened.backend : null);
+        if (!opened) {
+          setEvents(NO_EVENTS);
+          setStatus('unavailable');
+        }
+      },
+      (err) => {
+        if (!alive) return;
+        setError(err instanceof Error ? err : new Error(String(err)));
+        setStatus('unavailable');
+      },
+    );
+
+    return () => {
+      alive = false;
+      setCal(null);
+      void handle?.close();
+    };
+  }, [app, enabled]);
+
+  // The query.
+  useEffect(() => {
+    if (!cal) return undefined;
+
+    let alive = true;
+    void (async () => {
+      setStatus('loading');
+      setError(null);
+      try {
+        const all = await cal.listCalendars();
+        if (!alive) return;
+        setFound(all);
+
+        const result = await cal.eventsBetween(
+          new Date(fromMs),
+          new Date(toMs),
+          {
+            calendars: pickCalendars(all, onlyKey),
+          },
+        );
+        if (!alive) return;
+        setEvents(result.events);
+        setErrors(result.errors);
+        setStatus('ready');
+      } catch (err) {
+        if (!alive) return;
+        setError(err instanceof Error ? err : new Error(String(err)));
+        setEvents(NO_EVENTS);
+        // The user's refusal and the machine's silence are different words:
+        // one has a Settings switch behind it and the other does not. A
+        // request that came back still undecided is the machine's — TCC
+        // would not even ask — so it is 'unavailable', not a refusal the
+        // user could take back.
+        const refused =
+          err instanceof CalendarAccessError && err.status !== 'prompt';
+        setStatus(refused ? 'denied' : 'unavailable');
+      }
+    })();
+
+    return () => {
+      alive = false;
+    };
+    // `refresh` is stable; `nonce` is what a manual refresh moves.
+  }, [cal, fromMs, toMs, onlyKey, nonce]);
+
+  // 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 EDS's
+  // `Start()` reported the range's existing contents as a change.
+  useEffect(() => {
+    if (!cal || !watch) return undefined;
+
+    let alive = true;
+    let stopWatching = null;
+    void (async () => {
+      try {
+        const all = await cal.listCalendars();
+        if (!alive) return;
+        stopWatching = await cal.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 (alive && live.current) refresh();
+          },
+          { calendars: pickCalendars(all, onlyKey) },
+        );
+        if (!alive) await stopWatching();
+      } catch {
+        // No grant, no service, nothing to watch. The query effect above is
+        // what reports that to the caller; a second copy would only race.
+      }
+    })();
+
+    return () => {
+      alive = false;
+      void (async () => {
+        if (stopWatching) await stopWatching();
+      })();
+    };
+  }, [cal, watch, fromMs, toMs, onlyKey, refresh]);
+
+  const grouped = useMemo(() => groupByDay(events), [events]);
+
+  return useMemo(
+    () => ({
+      events,
+      byDay: grouped,
+      calendars: found,
+      errors,
+      status,
+      backend,
+      error,
+      refresh,
+      openSettings,
+    }),
+    [
+      events,
+      grouped,
+      found,
+      errors,
+      status,
+      backend,
+      error,
+      refresh,
+      openSettings,
+    ],
+  );
+}

package/src/index.d.ts

@@ -29,6 +29,7 @@ export * from './types/launcher.js';
 export * from './types/tray.js';
 export * from './types/permissions.js';
 export * from './types/notifications.js';
+export * from './types/desktopcalendar.js';
 
 /**
  * The XID of the X11 window a ref points at, or `null` if there is not one

package/src/index.js

@@ -27,6 +27,15 @@ export {
   notify,
 } from './notifications.js';
 export { useNotifier } from './notificationhooks.js';
+export {
+  CalendarAccessError,
+  NoCalendarServiceError,
+  byDay,
+  calendarBackend,
+  dayKey,
+  desktopCalendar,
+} from './desktopcalendar.js';
+export { useDesktopCalendarEvents } from './desktopcalendarhooks.js';
 export { parseUriList } from './transfer.js';
 export { useApp, useClipboard, useSupports } from './appcontext.js';
 export { BusUnavailableError, closeBus, sessionBus, systemBus } from './bus.js';

package/src/permissionhooks.js

@@ -42,30 +42,33 @@ import {
 export function usePermission(kind, options = {}) {
   const app = useAppOrNull();
   const target = options.target;
+  // `calendars` only: which level to ask for. Part of the effect keys
+  // because asking for a narrower grant is asking a different question.
+  const access = options.access;
   const available = permissionBackend({ app }) !== null;
   const [status, setStatus] = useState('unknown');
   const inflight = useRef(null);
 
   const refresh = useCallback(async () => {
-    const next = await permissionStatus(kind, { app, target });
+    const next = await permissionStatus(kind, { app, target, access });
     setStatus(next);
     return next;
-  }, [kind, app, target]);
+  }, [kind, app, target, access]);
 
   useEffect(() => {
     let alive = true;
-    permissionStatus(kind, { app, target }).then(
+    permissionStatus(kind, { app, target, access }).then(
       (next) => alive && setStatus(next),
       () => alive && setStatus('unknown'),
     );
     return () => {
       alive = false;
     };
-  }, [kind, app, target]);
+  }, [kind, app, target, access]);
 
   const request = useCallback(() => {
     if (inflight.current) return inflight.current;
-    const run = requestPermission(kind, { app, target })
+    const run = requestPermission(kind, { app, target, access })
       .then((next) => {
         setStatus(next);
         return next;
@@ -75,7 +78,7 @@ export function usePermission(kind, options = {}) {
       });
     inflight.current = run;
     return run;
-  }, [kind, app, target]);
+  }, [kind, app, target, access]);
 
   const openSettings = useCallback(
     () => openPrivacySettings(kind, { app }),

package/src/permissions.js

@@ -23,18 +23,24 @@
 //
 // ## Two things the vocabulary decides
 //
-// - A status is one of five words. `'granted'`, `'denied'` and
+// - A status is one of six words. `'granted'`, `'denied'` and
 //   `'restricted'` (MDM or parental controls: the user cannot grant it) are
 //   the platform's; `'prompt'` is "not decided yet — a request would ask";
 //   `'unknown'` is "nothing here can say", which is a fact about the machine
 //   rather than about the permission, and the reason a query never throws.
+//   `'write-only'` is the sixth and the odd one: macOS 14's partial grant
+//   for `calendars` and `reminders`, where the app may save an item it
+//   cannot read. It crosses as its own word rather than being flattened
+//   into one of the other two, because it is a grant to a writer and a
+//   refusal to a reader and only the caller knows which it is.
 // - A request answers with the status **after** the user has, never with a
 //   bare boolean, because `'restricted'` and `'denied'` want different UI —
 //   one is a Settings switch the user can flip, the other is not.
 
 import { liveApps } from './trace-registry.js';
 
-/** The kinds a status can be asked for. `automation` wants `{ target }`. */
+/** The kinds a status can be asked for. `automation` wants `{ target }`;
+ *  `calendars` takes `{ access: 'write-only' }` for the narrower grant. */
 export const PERMISSION_KINDS = Object.freeze([
   'camera',
   'microphone',
@@ -43,6 +49,8 @@ export const PERMISSION_KINDS = Object.freeze([
   'input-monitoring',
   'automation',
   'location',
+  'calendars',
+  'reminders',
 ]);
 
 /** The Settings panes, the kinds above plus the two that have no API at all
@@ -55,6 +63,8 @@ const SETTINGS_PANES = Object.freeze({
   'input-monitoring': 'Privacy_ListenEvent',
   automation: 'Privacy_Automation',
   location: 'Privacy_LocationServices',
+  calendars: 'Privacy_Calendars',
+  reminders: 'Privacy_Reminders',
   'files-and-folders': 'Privacy_FilesAndFolders',
   'full-disk-access': 'Privacy_AllFiles',
 });

package/src/types/desktopcalendar.d.ts

@@ -0,0 +1,207 @@
+/**
+ * The calendars the user's desktop already has — EventKit on macOS,
+ * Evolution Data Server on a freedesktop session. See
+ * docs/desktop-calendar.md.
+ */
+
+import type { NtkApp } from './nodes.js';
+import type { PermissionStatus } from './permissions.js';
+
+/** Which rung answered: the EventKit bridge, an `osascript` child holding
+ *  an `EKEventStore`, or Evolution Data Server over the session bus. */
+export type CalendarBackend = 'cocoa' | 'osascript' | 'eds';
+
+/** One calendar the desktop knows about. */
+export interface DesktopCalendarInfo {
+  uid: string;
+  /** The name shown in the desktop's own calendar UI. */
+  name: string;
+  /** Whether the desktop has it switched on. Always true on macOS, which
+   *  has no such state to report. */
+  enabled: boolean;
+  /** `'#3584e4'` — the colour that UI draws it in, worth carrying into a
+   *  day marker. */
+  color?: string;
+  /** `caldav`, `google`, `local`, `exchange`, `subscription`, `birthday`…
+   *  the store's own word, lower-cased. */
+  backend?: string;
+  readOnly: boolean;
+  /** The account it came from, where one is named — a GNOME Online Accounts
+   *  entry, or an `EKSource` (`'iCloud'`, `'Google'`). */
+  account?: string;
+}
+
+/** One occurrence, with any recurrence already expanded. */
+export interface DesktopEvent {
+  uid: string;
+  summary: string;
+  location?: string;
+  description?: string;
+  start: Date;
+  /** **Exclusive**, on every rung: an all-day event on the 10th ends at
+   *  midnight on the 11th. The macOS rungs normalise what EventKit reports
+   *  (the last second of the last day) so a caller never has to ask. */
+  end: Date;
+  allDay: boolean;
+  recurring: boolean;
+  calendar: { uid: string; name: string; color?: string };
+}
+
+/** A calendar that would not answer. One broken backend is not a failure. */
+export interface DesktopCalendarError {
+  calendar: DesktopCalendarInfo;
+  message: string;
+}
+
+export interface EventsResult {
+  events: DesktopEvent[];
+  /** Empty on the macOS rungs, where there is one store. */
+  errors: DesktopCalendarError[];
+}
+
+/**
+ * What `watch` reports. Deliberately thin: re-query rather than patch.
+ *
+ * `'changed'` with a null calendar and no count is EventKit's — its
+ * notification names nothing, and a rung must not invent a count.
+ */
+export interface CalendarChange {
+  calendar: DesktopCalendarInfo | null;
+  kind: 'ObjectsAdded' | 'ObjectsModified' | 'ObjectsRemoved' | 'changed';
+  count: number | null;
+}
+
+export interface EventsOptions {
+  /** Restrict to these calendars. Default: every enabled one. */
+  calendars?: DesktopCalendarInfo[];
+}
+
+/**
+ * Nothing on this machine can read a calendar. Raised only by
+ * `desktopCalendar({ required: true })`; the default answer is `null`,
+ * because a machine with no calendar service is an ordinary machine.
+ */
+export declare class NoCalendarServiceError extends Error {
+  readonly name: 'NoCalendarServiceError';
+  readonly cause?: unknown;
+}
+
+/**
+ * The app may not read the calendars. `status` says why: `'denied'` and
+ * `'restricted'` and `'write-only'` are decisions, and `'prompt'` is a
+ * request that came back with nothing — TCC declining to ask, which the
+ * hook reports as `'unavailable'` rather than as a refusal.
+ */
+export declare class CalendarAccessError extends Error {
+  readonly name: 'CalendarAccessError';
+  readonly status: PermissionStatus;
+  readonly cause?: unknown;
+}
+
+/** A handle on the desktop's calendars. `close()` it. */
+export interface DesktopCalendar {
+  readonly backend: CalendarBackend;
+  /** The grant, without prompting; `'granted'` on a rung with no such gate. */
+  access(): Promise<PermissionStatus>;
+  /** Raise the system's prompt where there is one. Reads do this on the
+   *  first one, so a picker the user never opens never prompts. */
+  requestAccess(): Promise<PermissionStatus>;
+  /** System Settings › Privacy & Security › Calendars. `false` off macOS. */
+  openSettings(): Promise<boolean>;
+  listCalendars(): Promise<DesktopCalendarInfo[]>;
+  /** Occurrences in `[from, to)`, sorted by start. Rejects with
+   *  {@link CalendarAccessError} where the user said no. */
+  eventsBetween(
+    from: Date,
+    to: Date,
+    options?: EventsOptions,
+  ): Promise<EventsResult>;
+  /** Call `onChange` when something moves; the returned function stops. */
+  watch(
+    from: Date,
+    to: Date,
+    onChange: (change: CalendarChange) => void,
+    options?: EventsOptions,
+  ): Promise<() => Promise<void>>;
+  close(): Promise<void>;
+}
+
+export interface DesktopCalendarOptions {
+  /** The connection whose backend to ask, when there are several. */
+  app?: NtkApp;
+  /** Pin one rung and fail rather than fall through it. */
+  backend?: CalendarBackend;
+  /** Reject with {@link NoCalendarServiceError} instead of answering null. */
+  required?: boolean;
+}
+
+/**
+ * The desktop's calendars, on the best rung this machine has — or `null`,
+ * which is an ordinary answer about a machine.
+ */
+export declare function desktopCalendar(
+  options?: DesktopCalendarOptions,
+): Promise<DesktopCalendar | null>;
+
+/** Which rung this machine lands on, without reading anything, spawning
+ *  anything or prompting. */
+export declare function calendarBackend(
+  options?: Pick<DesktopCalendarOptions, 'app'>,
+): Promise<CalendarBackend | null>;
+
+/** The local calendar day a `Date` falls on, as `'YYYY-MM-DD'` — the key
+ *  `byDay` uses and `<Calendar dayContent>` is handed. */
+export declare function dayKey(date: Date): string;
+
+/** Occurrences grouped by the local day they appear on. An event lands
+ *  under every day it touches, not only under its start. */
+export declare function byDay(
+  events: DesktopEvent[],
+): Map<string, DesktopEvent[]>;
+
+/**
+ * `'idle'` before anything is asked, `'denied'` for the user's refusal and
+ * `'unavailable'` for the machine's silence — separate words, because only
+ * one of them has a Settings switch behind it.
+ */
+export type DesktopCalendarStatus =
+  'idle' | 'loading' | 'ready' | 'denied' | '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 changed. */
+  watch?: boolean;
+  /** Set false to hold off entirely — and to not prompt: a picker that is
+   *  not open yet has no business asking for the user's calendar. */
+  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[];
+  /** Calendars that would not answer while others did. Not fatal. */
+  errors: DesktopCalendarError[];
+  status: DesktopCalendarStatus;
+  /** Which rung answered, once one has. */
+  backend: CalendarBackend | null;
+  /** Why there are no events, when there is a reason worth showing. */
+  error: Error | null;
+  /** Re-query now. */
+  refresh: () => void;
+  /** System Settings › Privacy & Security › Calendars — for `'denied'`, and
+   *  for no other status. */
+  openSettings: () => Promise<boolean>;
+}
+
+/** The user's desktop calendar events, as rendering state. */
+export declare function useDesktopCalendarEvents(
+  options: UseDesktopCalendarEventsOptions,
+): UseDesktopCalendarEventsResult;

package/src/types/permissions.d.ts

@@ -12,7 +12,9 @@ export type PermissionKind =
   | 'accessibility'
   | 'input-monitoring'
   | 'automation'
-  | 'location';
+  | 'location'
+  | 'calendars'
+  | 'reminders';
 
 /** The panes `openPrivacySettings` reaches: every kind, plus the two with no
  * API because reading the folder is the prompt. */
@@ -23,10 +25,12 @@ export type PrivacyPane =
  * `'granted'`, `'denied'` and `'restricted'` (MDM or parental controls — the
  * user cannot grant it) are the platform's; `'prompt'` is not decided yet, a
  * request would ask; `'unknown'` is "nothing here can say", a fact about the
- * machine rather than the permission.
+ * machine rather than the permission. `'write-only'` is macOS 14's partial
+ * grant for `calendars`/`reminders`: a grant to a writer, a refusal to a
+ * reader, and only the caller knows which it is.
  */
 export type PermissionStatus =
-  'granted' | 'denied' | 'restricted' | 'prompt' | 'unknown';
+  'granted' | 'denied' | 'restricted' | 'prompt' | 'write-only' | 'unknown';
 
 export interface PermissionOptions {
   /** The connection whose backend to ask, when there are several. */
@@ -34,6 +38,10 @@ export interface PermissionOptions {
   /** `automation` only: the bundle id of the app to send Apple Events to.
    * Only a running target has an answer. */
   target?: string;
+  /** `calendars` only: which grant to ask for. `'write-only'` is macOS 14's
+   * narrower prompt — the app may save events it cannot read. `reminders`
+   * has no such grant and refuses one. */
+  access?: 'full' | 'write-only';
 }
 
 /**
@@ -96,5 +104,5 @@ export interface Permission {
 /** A permission for a component: the status as render state. */
 export declare function usePermission(
   kind: PermissionKind,
-  options?: Pick<PermissionOptions, 'target'>,
+  options?: Pick<PermissionOptions, 'target' | 'access'>,
 ): Permission;