react-x11 2.8.3 → 2.9.1

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/glnodes.js

@@ -11,6 +11,7 @@ import { cssColorStraight } from 'ntk';
 export { directGLFailure, hasDirectGL } from './glbackend.js';
 
 import { Node } from './nodes.js';
+import { FramePacer, resolveFrameRate } from './pacing.js';
 
 // One visual query per (app, spec): GetFBConfigs is a round trip and every
 // <glarea> in an app wants the same answer.
@@ -99,6 +100,9 @@ const px = (v) => Math.max(1, Math.round(v || 0));
  * - `clearColor` — CSS colour or `[r, g, b, a]` floats (default black).
  * - `frameLoop` — `'demand'` (default: redraw on prop/size/expose changes)
  *   or `'always'` (drive ntk's frame clock continuously).
+ * - `frameRate` — how the frames are paced when they are expensive
+ *   (src/pacing.js): a preset, a cap, or the three numbers, the same
+ *   vocabulary as `<window frameRate>`. Defaults to the owning window's.
  * - `glx` — a `chooseGLXConfig` spec, e.g. `{ DEPTH_SIZE: 24 }`.
  *
  * The X child window is stacked above everything drawn in the parent, so 2D
@@ -114,12 +118,36 @@ export class GlAreaNode extends Node {
     this._frameScheduled = false;
     this._created = false;
     this._pointerDirty = true;
+    // The frame pacer (src/pacing.js), the surface's own: a scene's frames
+    // are drawn on a clock of their own, and what one costs — `onDraw` and
+    // the swap, on this thread — is what decides whether the next may
+    // start at once. The policy is this element's `frameRate`, else the
+    // owning window's, read at each request so a change on either follows.
+    this._pacer = new FramePacer();
+    this._ownPolicy = null;
+    this._syncFramePolicy();
   }
 
   get isGlArea() {
     return true;
   }
 
+  /** The policy this surface paces by: its own prop, else the window's. */
+  _framePolicy() {
+    if (this.props.frameRate !== undefined && this.props.frameRate !== null) {
+      return this._ownPolicy;
+    }
+    return this.root?._framePolicy ?? this._pacer.policy;
+  }
+
+  _syncFramePolicy() {
+    const value = this.props.frameRate;
+    this._ownPolicy =
+      value === undefined || value === null
+        ? null
+        : resolveFrameRate(value, '<glarea frameRate>');
+  }
+
   _setRoot(root) {
     super._setRoot(root);
     // the owning window may already exist (a <glarea> mounted into a live
@@ -275,8 +303,21 @@ export class GlAreaNode extends Node {
     this.requestFrame();
   }
 
-  /** Draw one frame on the child window's next frame tick. */
+  /**
+   * Draw one frame on the child window's next frame tick — after whatever
+   * wait the pacer asks for (src/pacing.js). Off by default it answers
+   * "now"; under an adaptive policy a scene whose frames cost more than
+   * their share of the thread is held between them, and a `frameLoop` of
+   * `'always'` becomes a loop at the budget rather than at the display.
+   */
   requestFrame() {
+    if (!this.window || this.destroyed || this._frameScheduled) return;
+    this._pacer.configure(this._framePolicy());
+    if (this._pacer.defer(() => this._requestFrameNow())) return;
+    this._requestFrameNow();
+  }
+
+  _requestFrameNow() {
     if (!this.window || this.destroyed || this._frameScheduled) return;
     this._frameScheduled = true;
     const schedule =
@@ -290,13 +331,28 @@ export class GlAreaNode extends Node {
   }
 
   _drawFrame() {
+    const pacer = this._pacer;
+    pacer.began();
+    let drawn = false;
+    try {
+      drawn = this._drawFrameNow();
+    } finally {
+      pacer.ended(undefined, drawn);
+    }
+    // after the frame is priced, so the loop's next frame is judged by
+    // this one rather than by the one before
+    if (drawn && this.props.frameLoop === 'always') this.requestFrame();
+  }
+
+  /** The frame itself; true when it drew. */
+  _drawFrameNow() {
     const gl = this.gl;
-    if (!gl || this.destroyed) return;
+    if (!gl || this.destroyed) return false;
     const direct = gl.backend === 'direct';
     // On the direct backend every buffer may still be held by the display,
     // and drawing into one before it comes back would paint what is on
     // screen. `onFrameAvailable` asks for this frame again when one frees.
-    if (direct && gl.canRender && !gl.canRender()) return;
+    if (direct && gl.canRender && !gl.canRender()) return false;
     // binds this surface — the GPU context is shared between every <glarea>
     // on the connection — and picks up a resize
     gl.makeCurrent?.();
@@ -325,7 +381,7 @@ export class GlAreaNode extends Node {
     }
     this.props.onDraw?.(gl, info);
     gl.SwapBuffers();
-    if (this.props.frameLoop === 'always') this.requestFrame();
+    return true;
   }
 
   /**
@@ -357,7 +413,9 @@ export class GlAreaNode extends Node {
   }
 
   applyProps(newProps, oldProps) {
+    const before = oldProps ?? this.props;
     super.applyProps(newProps, oldProps);
+    if (newProps.frameRate !== before.frameRate) this._syncFramePolicy();
     // onDraw/clearColor are read at frame time, so any update is a new frame
     this.requestFrame();
   }
@@ -375,6 +433,7 @@ export class GlAreaNode extends Node {
   destroySubtree() {
     if (this.destroyed) return;
     super.destroySubtree();
+    this._pacer.cancel();
     this.gl?.destroy?.();
     this.gl = null;
     this.window?.destroy?.();

package/src/index.d.ts

@@ -9,7 +9,7 @@
 
 import type { ReactNode, RefObject } from 'react';
 import type { DrawnNode, NtkApp, NtkWindow } from './types/nodes.js';
-import type { ReactX11Elements } from './types/elements.js';
+import type { FrameRate, ReactX11Elements } from './types/elements.js';
 
 export * from './types/style.js';
 export * from './types/events.js';
@@ -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
@@ -232,6 +233,15 @@ export interface RootOptions {
    * run each. 6 by default; 0 paints glyphs at every size.
    */
   textStripBelow?: number;
+  /**
+   * How this root's windows pace their frames when their content changes
+   * faster than the display refreshes — the default for every `<window>`
+   * and `<glarea>` that names no `frameRate` of its own. `'display'` (every
+   * frame the clock gives) unless said otherwise; `'adaptive'` holds paints
+   * to a quarter of the time under a flood. `REACT_X11_FRAME_RATE` overrides
+   * it, and the props, from the environment. See {@link FrameRate}.
+   */
+  frameRate?: FrameRate;
   /** `':1'`, `'host:0.0'`, or a unix socket path. Defaults to `$DISPLAY`. */
   display?: string;
   /**

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

@@ -25,8 +25,178 @@ import type {
   WheelEvent,
 } from './types/events.js';
 
-/** ntk's 2d context. Typed loosely — it is ntk's API, not ours. */
-export type Context2D = unknown;
+/** A gradient, as `createLinearGradient` answers with. */
+export interface CanvasGradientLike {
+  addColorStop(offset: number, color: string): void;
+}
+
+/** An RGBA pixel block, as `createImageData` answers with. */
+export interface ImageDataLike {
+  readonly data: Uint8ClampedArray;
+  readonly width: number;
+  readonly height: number;
+}
+
+/**
+ * The 2d context a node paints into — the canvas-shaped subset **both**
+ * backends implement: ntk's `RenderingContext2D` over XRender on X11, and
+ * `CocoaContext2D` over CoreGraphics on macOS. Declared as the contract an
+ * element may rely on rather than as either class: what is here is on
+ * both, and a member one backend has and the other does not is optional
+ * here or absent. Coordinates are device pixels in the owning window's
+ * space — `abs`, `contentBox()` — unless a transform says otherwise.
+ * Anything ntk documents beyond this is reachable at runtime and is
+ * ntk's to change.
+ */
+export interface Context2D {
+  fillStyle: string | CanvasGradientLike;
+  strokeStyle: string | CanvasGradientLike;
+  lineWidth: number;
+  lineCap: 'butt' | 'round' | 'square';
+  lineJoin: 'miter' | 'round' | 'bevel';
+  globalAlpha: number;
+  /** A CSS font shorthand, `'13px sans-serif'`. */
+  font: string;
+  shadowBlur: number;
+  shadowOffsetX: number;
+  shadowOffsetY: number;
+  shadowColor: string;
+  /**
+   * X11 only: XRender's compositing operator — `'source-over'` (the
+   * default), `'copy'`, and the rest ntk documents. Absent on the cocoa
+   * backend, whose bridge has no blend-mode verb yet; test for it with
+   * `'globalCompositeOperation' in ctx`.
+   */
+  globalCompositeOperation?: string;
+  save(): void;
+  restore(): void;
+  translate(x: number, y: number): void;
+  scale(x: number, y: number): void;
+  rotate(angle: number): void;
+  transform(
+    a: number,
+    b: number,
+    c: number,
+    d: number,
+    e: number,
+    f: number,
+  ): void;
+  setTransform(
+    a: number,
+    b: number,
+    c: number,
+    d: number,
+    e: number,
+    f: number,
+  ): void;
+  resetTransform(): void;
+  getTransform(): {
+    a: number;
+    b: number;
+    c: number;
+    d: number;
+    e: number;
+    f: number;
+  };
+  setLineDash(segments: number[]): void;
+  getLineDash(): number[];
+  beginPath(): void;
+  closePath(): void;
+  moveTo(x: number, y: number): void;
+  lineTo(x: number, y: number): void;
+  bezierCurveTo(
+    cp1x: number,
+    cp1y: number,
+    cp2x: number,
+    cp2y: number,
+    x: number,
+    y: number,
+  ): void;
+  quadraticCurveTo(cpx: number, cpy: number, x: number, y: number): void;
+  arc(
+    x: number,
+    y: number,
+    radius: number,
+    startAngle: number,
+    endAngle: number,
+    anticlockwise?: boolean,
+  ): void;
+  rect(x: number, y: number, width: number, height: number): void;
+  roundRect(
+    x: number,
+    y: number,
+    width: number,
+    height: number,
+    radii: number | number[],
+  ): void;
+  fill(fillRule?: 'nonzero' | 'evenodd'): void;
+  stroke(): void;
+  clip(fillRule?: 'nonzero' | 'evenodd'): void;
+  fillRect(x: number, y: number, width: number, height: number): void;
+  /** Many rectangles in one operation — one request on X11, one
+   * CoreGraphics call on macOS. `[x, y, w, h]` quadruples, flat or nested. */
+  fillRects(rects: number[] | number[][]): void;
+  strokeRect(x: number, y: number, width: number, height: number): void;
+  clearRect(x: number, y: number, width: number, height: number): void;
+  fillText(text: string, x: number, y: number): void;
+  measureText(text: string): { width: number; [key: string]: unknown };
+  /**
+   * Composite an offscreen `Surface` (`react-x11/ntk`) — whole at a point,
+   * whole into a rect, or a source rect of it into a destination rect: the
+   * canvas overloads. One composite either way.
+   */
+  drawImage(image: unknown, dx: number, dy: number): void;
+  drawImage(
+    image: unknown,
+    dx: number,
+    dy: number,
+    dw: number,
+    dh: number,
+  ): void;
+  drawImage(
+    image: unknown,
+    sx: number,
+    sy: number,
+    sw: number,
+    sh: number,
+    dx: number,
+    dy: number,
+    dw: number,
+    dh: number,
+  ): void;
+  createLinearGradient(
+    x0: number,
+    y0: number,
+    x1: number,
+    y1: number,
+  ): CanvasGradientLike;
+  createImageData(width: number, height: number): ImageDataLike;
+  /** Raw pixels, straight RGBA, written transform- and clip-free — the
+   * canvas contract (docs/elements.md "<canvas>"). */
+  putImageData(data: ImageDataLike, x: number, y: number): void;
+}
+
+/**
+ * What `paintCachePlan` answers with: draw this node's content once into a
+ * surface under `key`, and composite that until the key changes
+ * (docs/extending.md "Drawing once instead of every frame").
+ */
+export interface PaintCachePlan {
+  /** Identity: the same key must mean the same pixels. Name every input
+   * `paintCached` reads. */
+  key: string;
+  /** Where the surface goes, in device pixels — window coordinates. */
+  x: number;
+  y: number;
+  /** Its size, in device pixels. */
+  width: number;
+  height: number;
+  /** `'argb32'` (the default), or `'a8'` for coverage tinted at composite
+   * time — one rendered copy per key serves every ink. */
+  format?: 'argb32' | 'a8';
+  /** The colour an `'a8'` surface is painted through. */
+  tint?: string;
+}
 
 /** How an axis is bounded when layout asks an element for its size.
  * `'exactly'` — the style decided this axis; `'at-most'` — that many pixels
@@ -284,6 +454,48 @@ export declare class Node {
   /** Draw. A subclass calls `super.paint(ctx)` first, for the background,
    * border and clip, then draws inside `this.abs`. */
   paint(ctx: Context2D): void;
+  /**
+   * Draw between the background and the children — where every built-in
+   * draws, and the seam to override rather than `paint`: `paint` draws the
+   * background, then this, then the children, the border and the focus
+   * ring, and a scroller's bars, and an element that overrides `paint`
+   * has to keep all of that in the right order itself. Draws inside
+   * `contentBox()`; the clip is already set. The default draws nothing.
+   */
+  paintContent(ctx: Context2D): void;
+  /**
+   * The paint-cache protocol, with `paintCached`: implement both or
+   * neither. Answer a plan to have this frame's content drawn once into a
+   * surface under `plan.key` and composited from it until the key changes,
+   * or `null` to opt out this frame — the right answer whenever the paint
+   * depends on something the key cannot see (a caret, a hover, anything
+   * animating). The key is the whole correctness surface.
+   */
+  paintCachePlan?(ctx: Context2D): PaintCachePlan | null;
+  /**
+   * Draw the content the plan named, at the **origin of `box`** — surface
+   * coordinates, not `this.abs`. `ink` is the colour a mono drawing (one
+   * that asked for `'a8'`) must paint in: white where the surface is
+   * coverage and the tint arrives at composite time, the tint itself on a
+   * backend without coverage surfaces. A multi-colour drawing ignores it.
+   * `paintDamage()` is null in here: a cached copy is drawn whole.
+   */
+  paintCached?(ctx: Context2D, box: Rect, ink?: string): void;
+  /**
+   * The rect this element writes opaque pixels over on every paint — in
+   * window coordinates like `abs`, whole pixels — or `null`, the default,
+   * which promises nothing.
+   *
+   * A pass that lies inside it is painted without the fills that would be
+   * under it: the window's background, this node's own and every
+   * ancestor's. That is what an element with a retained surface it draws
+   * whole — a terminal, a media frame, a chart — answers with, and it then
+   * claims its damage as a **rect inside the answer** rather than as the
+   * node, which is inflated by a pixel of slop and so never covered. The
+   * promise is the element's to keep: every pixel, alpha one, on every
+   * paint, whatever the props. A translucent element answers `null`.
+   */
+  opaqueRect(): Rect | null;
   /**
    * The rect this paint pass is repainting, or null when it is repainting
    * the whole window — and null outside a paint, which means the same