@react-x11/components 0.1.0 → 0.2.1

package/src/desktop-calendar/eds.ts

@@ -0,0 +1,484 @@
+// The user's desktop calendars, over D-Bus, through Evolution Data Server.
+//
+// EDS is the store every GNOME calendar UI reads from, and GNOME Online
+// Accounts feeds Google/Microsoft/CalDAV into it — so anything the user
+// connected in Settings shows up here with no OAuth work on our side, and no
+// credentials ever touching this package.
+//
+// Two services are involved:
+//   Sources5   — the registry: which calendars exist, their names and colours
+//   Calendar8  — the store: open a calendar, query a time range, watch changes
+//
+// Recurring events come back as unexpanded masters, so occurrences are
+// generated client-side with `ical.js` (an optional dependency — see
+// `./ical.js`).
+//
+// **The connection is not ours.** It arrives from react-x11's shared bus, so
+// the app's exported service, its tray, its menus and this all speak on one
+// socket under one unique name. Dialling a second one would make the app look
+// like two applications on the bus, and would leak a connection per mount.
+import type { MessageBus } from 'react-x11';
+
+import { loadIcal } from './ical.js';
+import type { IcalComponent, IcalModule, IcalTime } from './ical.js';
+
+const SOURCES_NAME = 'org.gnome.evolution.dataserver.Sources5';
+const SOURCES_PATH = '/org/gnome/evolution/dataserver/SourceManager';
+const OBJECT_MANAGER = 'org.freedesktop.DBus.ObjectManager';
+const FACTORY_NAME = 'org.gnome.evolution.dataserver.Calendar8';
+const FACTORY_PATH = '/org/gnome/evolution/dataserver/CalendarFactory';
+const FACTORY_IFACE = 'org.gnome.evolution.dataserver.CalendarFactory';
+const CAL_IFACE = 'org.gnome.evolution.dataserver.Calendar';
+const VIEW_IFACE = 'org.gnome.evolution.dataserver.CalendarView';
+
+/**
+ * `E_CAL_CLIENT_VIEW_FLAGS_NONE`. A view is created with
+ * `NOTIFY_INITIAL` instead, which makes `Start()` replay everything already
+ * matching the query as `ObjectsAdded` — the current contents, announced as
+ * if they had just changed.
+ *
+ * That is the wrong signal for a watcher whose answer to a change is to run
+ * the query again: the re-query tears the view down, starts a new one, and is
+ * told the same thing again, for as long as the app is open. Flags of NONE is
+ * the whole of "only tell me what changes from here".
+ */
+const VIEW_FLAGS_NONE = 0;
+
+/** One calendar the desktop knows about. */
+export interface DesktopCalendarInfo {
+  uid: string;
+  /** The name shown in the desktop's own calendar UI. */
+  name: string;
+  enabled: boolean;
+  /** The colour that UI draws it in — worth carrying into a day marker. */
+  color?: string;
+  /** `caldav`, `google`, `local`, `webcal`… */
+  backend?: string;
+  readOnly: boolean;
+  /** Set when the calendar came from an Online Accounts login. */
+  account?: string;
+}
+
+/** One occurrence, already expanded out of any recurrence rule. */
+export interface DesktopEvent {
+  uid: string;
+  summary: string;
+  location?: string;
+  description?: string;
+  start: Date;
+  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[];
+  errors: DesktopCalendarError[];
+}
+
+/** What `watch` reports. Deliberately thin: re-query rather than patch. */
+export interface CalendarChange {
+  calendar: DesktopCalendarInfo;
+  kind: 'ObjectsAdded' | 'ObjectsModified' | 'ObjectsRemoved';
+  count: number;
+}
+
+const pad = (n: number): string => String(n).padStart(2, '0');
+
+/** `20260807T113000Z` — what the S-expression query wants. */
+function icalStamp(d: Date): string {
+  return (
+    `${d.getUTCFullYear()}${pad(d.getUTCMonth() + 1)}${pad(d.getUTCDate())}T` +
+    `${pad(d.getUTCHours())}${pad(d.getUTCMinutes())}${pad(d.getUTCSeconds())}Z`
+  );
+}
+
+/** The query EDS understands for "anything happening between these two". */
+function rangeQuery(from: Date, to: Date): string {
+  return `(occur-in-time-range? (make-time "${icalStamp(from)}") (make-time "${icalStamp(to)}"))`;
+}
+
+/**
+ * A source's whole configuration is an ini-style keyfile carried in one D-Bus
+ * property, so it has to be parsed to find out whether a source is even a
+ * calendar (as opposed to an address book, a mail account or a task list).
+ */
+export function parseKeyFile(
+  text: string,
+): Record<string, Record<string, string>> {
+  const out: Record<string, Record<string, string>> = {};
+  let section: string | null = null;
+  for (const raw of text.split('\n')) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) continue;
+    if (line.startsWith('[') && line.endsWith(']')) {
+      section = line.slice(1, -1);
+      out[section] = out[section] ?? {};
+      continue;
+    }
+    if (!section) continue;
+    const eq = line.indexOf('=');
+    if (eq === -1) continue;
+    const key = line.slice(0, eq).trim();
+    if (key.includes('[')) continue; // a DisplayName[ru] translation
+    out[section][key] = line.slice(eq + 1).trim();
+  }
+  return out;
+}
+
+/** `dbus-native`'s proxies are built by introspection, so they are `any`
+ *  shaped. These name only what is called. */
+interface CalendarIface {
+  Open(): Promise<void>;
+  GetObjectList(query: string): Promise<string[]>;
+  GetTimezone(tzid: string): Promise<string>;
+  GetView(query: string): Promise<string>;
+}
+interface ViewIface {
+  $subscribe(signal: string, fn: (...args: unknown[]) => void): Promise<void>;
+  SetFlags(flags: number): Promise<void>;
+  Start(): Promise<void>;
+  Stop(): Promise<void>;
+  Dispose(): Promise<void>;
+}
+
+/**
+ * The desktop's calendars, read over a bus someone else owns.
+ *
+ * ```ts
+ * const ref = await sessionBus();
+ * if (!ref) return;                       // no bus here; no calendars
+ * const desktop = new DesktopCalendar(ref.bus);
+ * const { events } = await desktop.eventsBetween(from, to);
+ * ```
+ *
+ * Nothing here closes the connection, because nothing here opened it. Call
+ * `dispose()` to drop the views this instance started, then release your own
+ * reference to the bus.
+ */
+export class DesktopCalendar {
+  #bus: MessageBus;
+  #open = new Map<string, { cal: CalendarIface; busName: string }>();
+  #views: ViewIface[] = [];
+  #timezones = new Set<string>();
+
+  constructor(bus: MessageBus) {
+    this.#bus = bus;
+  }
+
+  /** Every calendar the desktop knows about, colour included. */
+  async listCalendars(): Promise<DesktopCalendarInfo[]> {
+    const om = (await this.#bus
+      .getService(SOURCES_NAME)
+      .getInterface(SOURCES_PATH, OBJECT_MANAGER)) as {
+      GetManagedObjects(): Promise<
+        Record<string, Record<string, Record<string, unknown>>>
+      >;
+    };
+    const managed = await om.GetManagedObjects();
+
+    const calendars: DesktopCalendarInfo[] = [];
+    for (const interfaces of Object.values(managed)) {
+      const src = interfaces['org.gnome.evolution.dataserver.Source'];
+      if (!src) continue;
+      const cfg = parseKeyFile(String(src.Data ?? ''));
+      // no [Calendar] section means an address book, a task list or mail
+      if (!cfg.Calendar) continue;
+      const ds = cfg['Data Source'] ?? {};
+      calendars.push({
+        uid: String(src.UID ?? ''),
+        name: ds.DisplayName ?? '',
+        enabled: ds.Enabled !== 'false',
+        color: cfg.Calendar.Color,
+        backend: cfg.Calendar.BackendName,
+        readOnly: !interfaces['org.gnome.evolution.dataserver.Source.Writable'],
+        account: cfg['GNOME Online Accounts']?.Account,
+      });
+    }
+    return calendars;
+  }
+
+  async #openCalendar(
+    uid: string,
+  ): Promise<{ cal: CalendarIface; busName: string }> {
+    const existing = this.#open.get(uid);
+    if (existing) return existing;
+
+    const factory = (await this.#bus
+      .getService(FACTORY_NAME)
+      .getInterface(FACTORY_PATH, FACTORY_IFACE)) as {
+      OpenCalendar(uid: string): Promise<[string, string]>;
+    };
+    const [path, busName] = await factory.OpenCalendar(uid);
+    const cal = (await this.#bus
+      .getService(busName)
+      .getInterface(path, CAL_IFACE)) as CalendarIface;
+    await cal.Open();
+
+    const entry = { cal, busName };
+    this.#open.set(uid, entry);
+    return entry;
+  }
+
+  /**
+   * Events reference timezones by id, but the payload rarely carries the
+   * matching VTIMEZONE — so definitions are fetched on demand and registered
+   * with ical.js. A backend that has none leaves the time floating, which is
+   * ical.js's own fallback and better than refusing the event.
+   */
+  async #ensureTimezone(
+    ICAL: IcalModule,
+    cal: CalendarIface,
+    tzid: string | undefined,
+  ): Promise<void> {
+    if (!tzid || this.#timezones.has(tzid) || ICAL.TimezoneService.has(tzid)) {
+      return;
+    }
+    this.#timezones.add(tzid);
+    try {
+      const vtz = await cal.GetTimezone(tzid);
+      const comp = new ICAL.Component(ICAL.parse(vtz));
+      const sub =
+        comp.name === 'vtimezone'
+          ? comp
+          : comp.getFirstSubcomponent('vtimezone');
+      if (sub) ICAL.TimezoneService.register(tzid, new ICAL.Timezone(sub));
+    } catch {
+      /* no definition for it; ical.js falls back to floating time */
+    }
+  }
+
+  /**
+   * Expanded occurrences between two `Date`s, across the calendars given (or
+   * every enabled one). Sorted by start.
+   *
+   * A backend that is offline or broken contributes an entry in `errors`
+   * rather than throwing: one unreachable CalDAV server must not blank a
+   * whole month of the user's own local calendar.
+   */
+  async eventsBetween(
+    from: Date,
+    to: Date,
+    options: { calendars?: DesktopCalendarInfo[] } = {},
+  ): Promise<EventsResult> {
+    const ICAL = await loadIcal();
+    const list =
+      options.calendars ??
+      (await this.listCalendars()).filter((c) => c.enabled);
+    const query = rangeQuery(from, to);
+
+    const perCalendar = await Promise.all(
+      list.map(async (meta) => {
+        try {
+          const { cal } = await this.#openCalendar(meta.uid);
+          const objects = await cal.GetObjectList(query);
+          return {
+            events: await this.#expand(ICAL, cal, objects, from, to, meta),
+            error: null,
+          };
+        } catch (err) {
+          return {
+            events: [],
+            error: {
+              calendar: meta,
+              message: err instanceof Error ? err.message : String(err),
+            },
+          };
+        }
+      }),
+    );
+
+    const events: DesktopEvent[] = [];
+    const errors: DesktopCalendarError[] = [];
+    for (const chunk of perCalendar) {
+      events.push(...chunk.events);
+      if (chunk.error) errors.push(chunk.error);
+    }
+    events.sort((a, b) => a.start.getTime() - b.start.getTime());
+    return { events, errors };
+  }
+
+  async #expand(
+    ICAL: IcalModule,
+    cal: CalendarIface,
+    objects: string[],
+    from: Date,
+    to: Date,
+    meta: DesktopCalendarInfo,
+  ): Promise<DesktopEvent[]> {
+    const out: DesktopEvent[] = [];
+    for (const ics of objects) {
+      let comp: IcalComponent;
+      try {
+        comp = new ICAL.Component(ICAL.parse(ics));
+      } catch {
+        continue; // one unparseable object is not the range's problem
+      }
+
+      // Register any VTIMEZONE shipped inline, then any referenced by id.
+      for (const vtz of comp.getAllSubcomponents('vtimezone')) {
+        const tz = new ICAL.Timezone(vtz);
+        if (!ICAL.TimezoneService.has(tz.tzid)) {
+          ICAL.TimezoneService.register(tz.tzid, tz);
+        }
+      }
+
+      const vevents =
+        comp.name === 'vevent' ? [comp] : comp.getAllSubcomponents('vevent');
+      for (const ve of vevents) {
+        for (const prop of ['dtstart', 'dtend']) {
+          const p = ve.getFirstProperty(prop);
+          if (p) await this.#ensureTimezone(ICAL, cal, p.getParameter('tzid'));
+        }
+        const event = new ICAL.Event(ve);
+        // folded in by the recurrence iterator below
+        if (event.isRecurrenceException()) continue;
+
+        const push = (startTime: IcalTime, endTime: IcalTime | null): void => {
+          const start = startTime.toJSDate();
+          const end = endTime ? endTime.toJSDate() : start;
+          if (end < from || start >= to) return;
+          out.push({
+            uid: event.uid,
+            summary: event.summary || '',
+            location: event.location || undefined,
+            description: event.description || undefined,
+            start,
+            end,
+            allDay: event.startDate.isDate,
+            recurring: event.isRecurring(),
+            calendar: { uid: meta.uid, name: meta.name, color: meta.color },
+          });
+        };
+
+        if (!event.isRecurring()) {
+          push(event.startDate, event.endDate);
+          continue;
+        }
+
+        const duration = event.duration;
+        const it = event.iterator();
+        let next: IcalTime | null;
+        // A malformed RRULE with no UNTIL and a tiny interval can iterate
+        // forever; the range check below normally ends it, and this is the
+        // backstop for the case where it cannot.
+        let guard = 0;
+        while ((next = it.next()) && guard++ < 2000) {
+          if (next.toJSDate() >= to) break;
+          const end = next.clone();
+          end.addDuration(duration);
+          if (end.toJSDate() < from) continue;
+          const details = event.getOccurrenceDetails(next);
+          push(details.startDate, details.endDate);
+        }
+      }
+    }
+    return out;
+  }
+
+  /**
+   * Live updates: `onChange` fires whenever anything in the range moves, so
+   * the caller can re-query. Returns an unsubscribe function.
+   *
+   * Deliberately a "something changed" signal rather than a patch — a
+   * recurrence master edited three months away can change what today looks
+   * like, and re-running the query is both simpler and correct.
+   *
+   * **Changes only.** What is in the range already is what `eventsBetween`
+   * answered; `onChange` fires for what happens after that. See
+   * {@link VIEW_FLAGS_NONE} for the loop that reporting the initial contents
+   * as a change costs a caller who re-queries on one.
+   */
+  async watch(
+    from: Date,
+    to: Date,
+    onChange: (change: CalendarChange) => void,
+    options: { calendars?: DesktopCalendarInfo[] } = {},
+  ): Promise<() => Promise<void>> {
+    const list =
+      options.calendars ??
+      (await this.listCalendars()).filter((c) => c.enabled);
+    const query = rangeQuery(from, to);
+    const started: ViewIface[] = [];
+
+    for (const meta of list) {
+      try {
+        const { cal, busName } = await this.#openCalendar(meta.uid);
+        const viewPath = await cal.GetView(query);
+        const view = (await this.#bus
+          .getService(busName)
+          .getInterface(viewPath, VIEW_IFACE)) as ViewIface;
+
+        // Belt to `VIEW_FLAGS_NONE`'s braces, for a backend that would not
+        // take the flags: `Complete` closes the initial delivery, so anything
+        // before it is the replay rather than a change. Only armed when
+        // `SetFlags` failed — a view that never reports `Complete` would
+        // otherwise be watched in silence, and losing live updates is the
+        // worse half of the trade.
+        let replaying = false;
+        try {
+          await view.SetFlags(VIEW_FLAGS_NONE);
+        } catch {
+          replaying = true;
+        }
+        await view.$subscribe('Complete', () => {
+          replaying = false;
+        });
+
+        for (const signal of [
+          'ObjectsAdded',
+          'ObjectsModified',
+          'ObjectsRemoved',
+        ] as const) {
+          await view.$subscribe(signal, (objects) => {
+            if (replaying) return;
+            onChange({
+              calendar: meta,
+              kind: signal,
+              count: Array.isArray(objects) ? objects.length : 0,
+            });
+          });
+        }
+        await view.Start();
+        started.push(view);
+        this.#views.push(view);
+      } catch {
+        /* skip a calendar that will not open; the others still update */
+      }
+    }
+
+    return async () => {
+      for (const view of started) {
+        this.#views = this.#views.filter((v) => v !== view);
+        try {
+          await view.Stop();
+          await view.Dispose();
+        } catch {
+          /* already gone */
+        }
+      }
+    };
+  }
+
+  /** Stop every view this instance started. Does **not** touch the bus. */
+  async dispose(): Promise<void> {
+    const views = this.#views;
+    this.#views = [];
+    for (const view of views) {
+      try {
+        await view.Stop();
+        await view.Dispose();
+      } catch {
+        /* already gone */
+      }
+    }
+    this.#open.clear();
+  }
+}

package/src/desktop-calendar/ical.ts

@@ -0,0 +1,119 @@
+// The slice of `ical.js` this package uses, and the loader that finds it.
+//
+// **`ical.js` is an `optionalDependency`, and these types are deliberately
+// ours rather than the package's.** `import type … from 'ical.js'` would put
+// the module in the type graph, and then an app that did not install it could
+// not type-check against this package at all — which is the opposite of what
+// "optional" means. So the surface is written out structurally, and the value
+// arrives through a dynamic `import()` that is allowed to fail.
+//
+// react-x11 makes the same call with `dbus-native`, for the same reason.
+
+/** An `ICAL.Time`. */
+export interface IcalTime {
+  toJSDate(): Date;
+  clone(): IcalTime;
+  addDuration(duration: unknown): void;
+  /** True for a date without a time — an all-day event's start. */
+  isDate: boolean;
+}
+
+export interface IcalProperty {
+  getParameter(name: string): string | undefined;
+}
+
+export interface IcalComponent {
+  name: string;
+  getFirstSubcomponent(name: string): IcalComponent | null;
+  getAllSubcomponents(name: string): IcalComponent[];
+  getFirstProperty(name: string): IcalProperty | null;
+}
+
+export interface IcalRecurExpansion {
+  next(): IcalTime | null;
+}
+
+export interface IcalEvent {
+  uid: string;
+  summary: string;
+  location: string;
+  description: string;
+  startDate: IcalTime;
+  endDate: IcalTime;
+  duration: unknown;
+  isRecurring(): boolean;
+  isRecurrenceException(): boolean;
+  iterator(): IcalRecurExpansion;
+  getOccurrenceDetails(time: IcalTime): {
+    startDate: IcalTime;
+    endDate: IcalTime;
+  };
+}
+
+export interface IcalTimezone {
+  tzid: string;
+}
+
+/** What `import('ical.js')` gives back, as far as this package is concerned. */
+export interface IcalModule {
+  parse(input: string): unknown;
+  Component: new (jcal: unknown) => IcalComponent;
+  Event: new (component: IcalComponent) => IcalEvent;
+  Timezone: new (component: IcalComponent) => IcalTimezone;
+  TimezoneService: {
+    has(tzid: string): boolean;
+    register(tzid: string, zone: IcalTimezone): void;
+  };
+}
+
+/** Thrown when the calendar is asked for events and `ical.js` is not there. */
+export class IcalUnavailableError extends Error {
+  constructor(cause?: unknown) {
+    super(
+      "@react-x11/components: reading desktop calendar events needs 'ical.js', " +
+        'which is an optional dependency and is not installed. ' +
+        'Run `npm install ical.js`. Listing calendars does not need it.',
+      { cause },
+    );
+    this.name = 'IcalUnavailableError';
+  }
+}
+
+let cached: Promise<IcalModule> | null = null;
+
+/**
+ * Load `ical.js`, once.
+ *
+ * Deliberately **not** cached as a rejection: a failed load is almost always
+ * "not installed", but retrying costs nothing and a cached rejection would
+ * outlive an app that installed it and re-rendered.
+ */
+export async function loadIcal(): Promise<IcalModule> {
+  if (cached) return cached;
+  const attempt = (async (): Promise<IcalModule> => {
+    try {
+      // The specifier is built at run time so a bundler treats this as a
+      // genuinely optional import and does not fail the build resolving a
+      // package the app may well not have.
+      const name = 'ical.js';
+      const mod = (await import(/* @vite-ignore */ name)) as {
+        default?: IcalModule;
+      } & IcalModule;
+      // ical.js is CJS-with-a-default under some resolutions and a namespace
+      // under others; `parse` is on whichever one is real.
+      const resolved = typeof mod.parse === 'function' ? mod : mod.default;
+      if (!resolved || typeof resolved.parse !== 'function') {
+        throw new TypeError('ical.js did not export what was expected');
+      }
+      return resolved;
+    } catch (err) {
+      throw new IcalUnavailableError(err);
+    }
+  })();
+  // Only a successful load is remembered.
+  cached = attempt.catch((err: unknown) => {
+    cached = null;
+    throw err;
+  });
+  return cached;
+}