react-x11 2.8.3 → 2.9.1

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/elements.d.ts

@@ -278,6 +278,47 @@ export type WindowType =
   | 'desktop'
   | (string & {});
 
+/**
+ * How a window paces its frames when its content changes faster than the
+ * display refreshes — a terminal under a flood, a chart on a socket, a
+ * simulation. Priced in CPU time, not counted in updates: a frame costs
+ * what the flush (and on macOS the present) took of this thread, and a
+ * claim waits only while recent frames have spent more than their share.
+ * A scroll that is mostly blits keeps the display's rate; only a stream of
+ * expensive frames earns a wait (docs/elements.md "frameRate").
+ *
+ * - `'display'` — every frame the clock gives, after React's own
+ *   batching. **The default.**
+ * - `'adaptive'` — paints stay under a quarter of the time while busy, and
+ *   the screen is never more than 50ms behind (a 20fps floor). Idle claims
+ *   and cheap frames never wait.
+ * - `'throughput'` — a tenth, a 10fps floor and a 30fps ceiling: fewer,
+ *   later frames for a window whose output matters more than its display.
+ * - a number — a ceiling in frames per second, nothing else.
+ * - `{ budget, minFps, maxFps }` — the three numbers the presets are made
+ *   of, any subset; the rest are `'display'`'s (so name a `minFps` with a
+ *   `budget` below 1).
+ *
+ * `createRoot({ frameRate })` sets the default for every window of a root,
+ * and `REACT_X11_FRAME_RATE` overrides both from the environment.
+ */
+export type FrameRate =
+  | 'display'
+  | 'adaptive'
+  | 'throughput'
+  | number
+  | {
+      /** Share of wall time paints may take while busy, above 0 and at
+       * most 1. */
+      budget?: number;
+      /** The floor: the screen is never more than `1000 / minFps` ms behind
+       * the last paint. 0 for none. */
+      minFps?: number;
+      /** A ceiling in frames per second, cheap frames included. 0 for
+       * none. */
+      maxFps?: number;
+    };
+
 export interface WindowProps
   extends
     CommonProps,
@@ -289,6 +330,10 @@ export interface WindowProps
   ref?: Ref<NtkWindow>;
   /** Window title (UTF-8, via `WM_NAME` + `_NET_WM_NAME`). */
   title?: string;
+  /** How this window paces its frames under a stream of changes — see
+   * {@link FrameRate}. `'display'` unless the root or the environment says
+   * otherwise. A `<popup>` paces itself the same way. */
+  frameRate?: FrameRate;
   /**
    * Created but never self-mapped: this window is waiting to be embedded
    * (XEmbed / `<foreign>` on the other side), and from the reparent on,
@@ -865,6 +910,15 @@ export interface GlAreaProps extends DrawnProps<DrawnNode> {
   clearColor?: Color | [number, number, number, number];
   /** `'demand'` (default) redraws on change; `'always'` runs continuously. */
   frameLoop?: FrameLoop;
+  /**
+   * How the surface's frames are paced when they are expensive — the same
+   * vocabulary as {@link WindowProps.frameRate}, priced by what `onDraw`
+   * and the swap cost this thread. Defaults to the owning window's, so a
+   * `<window frameRate="adaptive">` paces the scene inside it too; set it
+   * here for a scene that wants every frame (`'display'`) while the window
+   * around it streams, or the other way round.
+   */
+  frameRate?: FrameRate;
   /** Visual spec for ntk's `chooseGLXConfig`, e.g. `{ DEPTH_SIZE: 24 }`. */
   glx?: Record<string, unknown>;
   /** Runs once, with the context current: one-time state, uploads, lists. */

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;