react-x11 2.9.0 → 2.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-x11",
-  "version": "2.9.0",
+  "version": "2.9.1",
   "description": "react renderer with X11 as a target",
   "main": "./src/index.js",
   "files": [
@@ -32,6 +32,7 @@
     "examples:tooltips": "tsx examples/tooltips.jsx",
     "examples:chat": "tsx examples/chat.jsx",
     "examples:clipboard": "tsx examples/clipboard.jsx",
+    "examples:calendar": "tsx examples/calendar.jsx",
     "labs:urischeme": "tsx examples/labs/urischeme.jsx",
     "filedialog:probe": "node scripts/filedialog-probe.mjs",
     "a11y:probe": "node scripts/a11y-probe.mjs",
@@ -92,13 +93,14 @@
     "node": ">=20.19"
   },
   "dependencies": {
+    "ical.js": "^2.2.1",
     "linebreak": "^1.1.0",
     "ntk": "^8.7.0",
     "react-reconciler": "^0.33.0",
     "yoga-layout": "^3.2.1"
   },
   "optionalDependencies": {
-    "@windowkit/appkit": "^0.7.0",
+    "@windowkit/appkit": "^0.8.0",
     "dbus-native": "^0.15.1",
     "x11-dri": "^0.7.0"
   },

package/src/cocoa/app.js

@@ -25,6 +25,7 @@ import { CocoaGLArea, cocoaGLConfig, resolveCocoaGLRuntime } from './glarea.js';
 import { CocoaDockMenu } from './dock.js';
 import { CocoaGlobalMenuExport } from './globalmenu.js';
 import { CocoaStatusItem } from './statusitem.js';
+import { CocoaCalendars } from './calendar.js';
 import { CocoaNotifications } from './notifications.js';
 import { CocoaPaneHost } from './panehost.js';
 import { CocoaPermissions } from './permissions.js';
@@ -177,6 +178,17 @@ export class CocoaApp {
         ? new CocoaNotifications(this)
         : null;
 
+    // EventKit (src/cocoa/calendar.js). Present exactly when the bridge has
+    // it (>= 0.8), and its presence is the top rung of
+    // src/desktopcalendar.js's ladder for this app — an older bridge leaves
+    // the ladder to find `osascript` instead, which answers the same
+    // questions out of the same framework.
+    this.calendars =
+      typeof native.calendars === 'function' &&
+      typeof native.eventsBetween === 'function'
+        ? new CocoaCalendars(this)
+        : null;
+
     // The GL policy, glbackend.js's shape. No GLX exists here, so the
     // default is 'auto' (the direct backend where the runtime loads);
     // useSupports('shaders') stays false until the first <glarea> resolves
@@ -767,6 +779,12 @@ export class CocoaApp {
       case 'notification-dismissed':
         this.notifications?.route(ev);
         return this._afterInput();
+      case 'calendar-store-changed':
+        // EventKit's own notification, which names nothing that changed. A
+        // watcher's answer is to query again, and that query's result is a
+        // render, so the frame goes out the way an input's does.
+        this.calendars?.route(ev);
+        return this._afterInput();
       case 'animation-end':
         // the presenter that added the animation registered for its id; an
         // id nobody knows is an animation already forgotten (cancelled, or

package/src/cocoa/calendar.js

@@ -0,0 +1,186 @@
+// The user's calendars on the cocoa backend — EventKit (`EKEventStore`)
+// through @windowkit/appkit (>= 0.8), the top rung of
+// src/desktopcalendar.js's ladder. `CocoaApp.calendars` is this object and
+// its *presence* is the capability, the rule `filePanels`, `permissions` and
+// `notifications` follow, so the ladder never names a backend.
+//
+// EventKit is the macOS counterpart of Evolution Data Server plus GNOME
+// Online Accounts in one framework: every account the user added in System
+// Settings > Internet Accounts — iCloud, Google, Exchange, CalDAV, a
+// subscribed feed — is served by one store, the desktop did the OAuth, and
+// the app never sees a credential.
+//
+// Three things about the framework shape the code here:
+//
+// - **It expands recurrences itself.** `predicateForEventsWithStartDate…`
+//   answers occurrences, so there is no `ical.js` on this rung and no
+//   recurrence arithmetic to get wrong. The EDS rung pays for that
+//   client-side; this one does not.
+// - **The predicate spans at most four years** (the framework's own limit),
+//   so a longer range is asked for in chunks and the pieces are merged —
+//   `chunkSpan` in ../desktopcalendar.js, shared with the `osascript` rung
+//   because it is the same framework underneath.
+// - **An all-day event ends at the last second of its last day.** Every
+//   other rung, and `byDay`, read `end` as exclusive, so it is normalised
+//   here — at the edge, once, rather than in every consumer.
+//
+// A change to anything in the store arrives as one `calendar-store-changed`
+// backend event that names nothing, so `watch` reports `kind: 'changed'`
+// with a null calendar and no count. Re-query; do not try to patch.
+
+import {
+  calendarBackendName,
+  chunkSpan,
+  hexFromComponents,
+  sortEvents,
+  withExclusiveEnd,
+} from '../desktopcalendar.js';
+
+/** `EKCalendar` as the shape every rung answers with. */
+export function calendarInfo(cal) {
+  return {
+    uid: String(cal.id),
+    name: cal.title ?? '',
+    // EventKit has no "unchecked in the sidebar" state to report — a
+    // calendar hidden in Calendar.app is still in the store — so every
+    // calendar here is enabled, which is what `enabled` means to a caller
+    // filtering the list.
+    enabled: true,
+    color: hexFromComponents(cal.color),
+    backend: calendarBackendName(cal.type),
+    readOnly: cal.allowsModifications === false || cal.immutable === true,
+    // The account the calendar came from, which is what the EDS rung's
+    // `account` is too: an `EKSource` is the Internet Accounts entry.
+    account: cal.source?.title ?? undefined,
+  };
+}
+
+/** One occurrence from the bridge as the shape every rung answers with. */
+export function desktopEvent(ev, byId) {
+  const meta = byId.get(String(ev.calendar));
+  const start = new Date(ev.start);
+  return {
+    uid: String(ev.id ?? ev.itemId ?? `${ev.calendar}:${ev.start}`),
+    summary: ev.title ?? '',
+    location: ev.location ?? undefined,
+    description: ev.notes ?? undefined,
+    start,
+    end: withExclusiveEnd(new Date(ev.end), Boolean(ev.allDay)),
+    allDay: Boolean(ev.allDay),
+    recurring: Boolean(ev.recurring),
+    calendar: meta
+      ? { uid: meta.uid, name: meta.name, color: meta.color }
+      : { uid: String(ev.calendar), name: '' },
+  };
+}
+
+export class CocoaCalendars {
+  constructor(app) {
+    this.app = app;
+    this._native = app._native;
+    this.backend = 'cocoa';
+    this._watchers = new Set();
+  }
+
+  /**
+   * The TCC grant, read without prompting. `'write-only'` is macOS 14's
+   * partial grant, which is a refusal to a reader — but its own word, so a
+   * caller that only saves events can tell it from a denial.
+   */
+  async access() {
+    return this.app.permissions
+      ? this.app.permissions.status('calendars')
+      : 'unknown';
+  }
+
+  /** The system prompt, once per app; the status after the user answered. */
+  async requestAccess() {
+    return this.app.permissions
+      ? this.app.permissions.request('calendars')
+      : 'unknown';
+  }
+
+  listCalendars() {
+    return new Promise((resolve, reject) => {
+      this._native.calendars((err, list) =>
+        err ? reject(err) : resolve((list ?? []).map(calendarInfo)),
+      );
+    });
+  }
+
+  _events(range) {
+    return new Promise((resolve, reject) => {
+      this._native.eventsBetween(range, (err, events) =>
+        err ? reject(err) : resolve(events ?? []),
+      );
+    });
+  }
+
+  /**
+   * The occurrences in a range, already expanded by the framework.
+   *
+   * `errors` is always empty here: there is one store, and a failure in it
+   * is a failure of the whole read rather than of one account. The EDS rung
+   * is the one where a single unreachable CalDAV server must not blank the
+   * month.
+   */
+  async eventsBetween(from, to, options = {}) {
+    const metas = options.calendars ?? (await this.listCalendars());
+    // "These calendars, of which there are none" is not "every calendar",
+    // which is what an empty filter means to the predicate underneath. A
+    // caller whose filter matched nothing must get nothing.
+    if (options.calendars && metas.length === 0) {
+      return { events: [], errors: [] };
+    }
+    const byId = new Map(metas.map((meta) => [meta.uid, meta]));
+    const ids = options.calendars ? metas.map((meta) => meta.uid) : undefined;
+
+    const events = [];
+    const seen = new Set();
+    for (const [start, end] of chunkSpan(from, to)) {
+      const raw = await this._events({ start, end, calendars: ids });
+      for (const one of raw) {
+        // An occurrence that straddles a chunk boundary is reported by both
+        // predicates; the caller must not see it twice.
+        const key = `${one.id} ${one.start}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        events.push(desktopEvent(one, byId));
+      }
+    }
+    return { events: sortEvents(events), errors: [] };
+  }
+
+  /**
+   * `EKEventStoreChangedNotification`, as the ladder's change signal.
+   *
+   * The notification names neither the calendar nor what happened — a
+   * detail EventKit does not have — so the change carries a null calendar
+   * and no count, and re-querying is the only correct answer. Every watcher
+   * hears every change, whatever range it asked for, because a change
+   * outside a range can still move what is inside it (a recurrence master
+   * edited months away).
+   */
+  async watch(from, to, onChange) {
+    const entry = { onChange };
+    this._watchers.add(entry);
+    return async () => {
+      this._watchers.delete(entry);
+    };
+  }
+
+  /** `calendar-store-changed`, routed from the app's backend callback. */
+  route() {
+    for (const entry of [...this._watchers]) {
+      try {
+        entry.onChange({ calendar: null, kind: 'changed', count: null });
+      } catch {
+        // a watcher that throws is not the other watchers' problem
+      }
+    }
+  }
+
+  /** Nothing to release: the store belongs to the process, and a handle's
+   *  own watchers are dropped by the stop function `watch` returned. */
+  async close() {}
+}

package/src/cocoa/native.js

@@ -11,10 +11,27 @@
 // is CommonJS + a .node binary, so `createRequire` is the honest loader.
 import { createRequire } from 'node:module';
 
-const require = createRequire(import.meta.url);
-
 const PACKAGE = '@windowkit/appkit';
 
+// The loader is made on first use, and from the executable when there is
+// no module URL to make it from. A bundle built for Node's single-executable
+// format (docs/packaging.md, tier 3) is CommonJS, and esbuild leaves
+// `import.meta` an empty object in that output — so a module-scope
+// `createRequire(import.meta.url)` threw ERR_INVALID_ARG_VALUE the moment
+// the backend loaded, in every cocoa app shipped as a SEA, before this
+// could say what it was trying to load. `createRequire(process.execPath)`
+// is the loader Node's SEA docs prescribe (the embedded main's `__filename`
+// *is* the executable), and it answers both specs below: an absolute
+// REACT_X11_CALAYERS_PATH resolves from anywhere, and the bare package name
+// resolves through a `node_modules` beside the binary. Made lazily, a
+// loader that cannot be made at all is reported by the error at the bottom
+// rather than by a throw at import.
+let require = null;
+function load(spec) {
+  require ??= createRequire(import.meta.url ?? process.execPath);
+  return require(spec);
+}
+
 let cached = null;
 
 export function loadNative() {
@@ -30,7 +47,7 @@ export function loadNative() {
   const path = process.env.REACT_X11_CALAYERS_PATH;
   for (const spec of [path, PACKAGE].filter(Boolean)) {
     try {
-      const mod = require(spec);
+      const mod = load(spec);
       // the package's index.js exports the raw addon as `native`; a direct
       // path to a built checkout may be the addon itself
       cached = mod.native ?? mod;

package/src/cocoa/permissions.js

@@ -13,23 +13,32 @@
 // bundled app must carry the usage-description keys
 // (`NSCameraUsageDescription` and friends) or a request never prompts.
 
-/** Apple's four words as the ladder's. */
+/** Apple's words as the ladder's. `writeOnly` is macOS 14's partial grant
+ *  for EventKit — a grant to a writer, a refusal to a reader — and stays its
+ *  own word for exactly that reason. */
 const STATUS = Object.freeze({
   authorized: 'granted',
   denied: 'denied',
   restricted: 'restricted',
   notDetermined: 'prompt',
+  writeOnly: 'write-only',
 });
 
 export function statusFromBridge(status) {
   return STATUS[status] ?? 'unknown';
 }
 
-/** The bridge's options for a kind: `automation` carries its target. */
+/** The bridge's options for a kind: `automation` carries its target, and
+ *  `calendars` the level being asked for (`reminders` has no write-only
+ *  grant, and the bridge refuses one with a TypeError). */
 function bridgeOptions(kind, options = {}) {
-  return kind === 'automation' && options.target != null
-    ? { target: String(options.target) }
-    : undefined;
+  if (kind === 'automation' && options.target != null) {
+    return { target: String(options.target) };
+  }
+  if (kind === 'calendars' && options.access != null) {
+    return { access: String(options.access) };
+  }
+  return undefined;
 }
 
 export class CocoaPermissions {