myphp-runtime 0.0.0-stage → 1.28.0

package/src/index.test.ts

@@ -0,0 +1,161 @@
+import { afterEach, expect, test } from "bun:test";
+import {
+  Channel,
+  call,
+  currentWindow,
+  direction,
+  event,
+  isCallError,
+  isMyPHP,
+  locale,
+  on,
+  onDocumentReload,
+  onDocumentState,
+  onFileDrop,
+  onLocaleChange,
+  onPreferences,
+  preferences,
+  runtime,
+  type DocumentState,
+  type FileDrop,
+  type Runtime,
+  type ThemePreferences,
+} from "./index";
+
+const calls: [string, unknown[]][] = [];
+const listeners = new Map<string, (payload: unknown) => void>();
+
+const fake: Runtime = {
+  call: async <T>(method: string, ...args: unknown[]) => {
+    calls.push([method, args]);
+    if (method === "Svc.fail") {
+      const err = new Error("boom") as Error & { method: string };
+      err.name = "CallError";
+      err.method = method;
+      throw err;
+    }
+    return method as T;
+  },
+  channel: <T>(onmessage?: (value: T) => void) =>
+    ({ onmessage, onclose: null, closed: false, close() {}, [Symbol.asyncIterator]: () => ({}) }) as unknown as Channel<T>,
+  on: (name, listener) => {
+    listeners.set(name, listener as (payload: unknown) => void);
+    return () => listeners.delete(name);
+  },
+  once: (name, listener) => {
+    listeners.set(name, listener as (payload: unknown) => void);
+    return () => listeners.delete(name);
+  },
+  platform: "darwin",
+  windowId: 1,
+  version: "0.1.0",
+  preferences: { accent: null, reduceMotion: false, reduceTransparency: true, highContrast: false, textScale: 1 },
+  locale: "en",
+  dir: "ltr",
+  window: {
+    minimize: () => fake.call("myphp:window.Minimize"),
+    maximize: () => fake.call("myphp:window.Maximize"),
+    unmaximize: () => fake.call("myphp:window.Unmaximize"),
+    toggleMaximize: () => fake.call("myphp:window.ToggleMaximize"),
+    isMaximized: () => fake.call("myphp:window.IsMaximized"),
+    toggleFullScreen: () => fake.call("myphp:window.ToggleFullScreen"),
+    close: () => fake.call("myphp:window.Close"),
+    setTitle: (title) => fake.call("myphp:window.SetTitle", title),
+  },
+};
+
+afterEach(() => {
+  delete (globalThis as { myphp?: Runtime }).myphp;
+  calls.length = 0;
+  listeners.clear();
+});
+
+test("outside MyPHP", async () => {
+  expect(isMyPHP()).toBe(false);
+  expect(() => runtime()).toThrow("runtime not found");
+  await expect(call("Svc.method")).rejects.toThrow("runtime not found");
+});
+
+test("delegates to window.myphp", async () => {
+  (globalThis as { myphp?: Runtime }).myphp = fake;
+  expect(isMyPHP()).toBe(true);
+  expect(await call<string>("Svc.method", 1, "a")).toBe("Svc.method");
+  expect(calls).toEqual([["Svc.method", [1, "a"]]]);
+
+  const got: unknown[] = [];
+  const off = event<{ n: number }>("tick").on((p) => got.push(p.n));
+  listeners.get("tick")?.({ n: 7 });
+  off();
+  expect(got).toEqual([7]);
+  expect(listeners.has("tick")).toBe(false);
+
+  on("other", () => {});
+  expect(listeners.has("other")).toBe(true);
+
+  await currentWindow.setTitle("Hi");
+  expect(calls.at(-1)).toEqual(["myphp:window.SetTitle", ["Hi"]]);
+
+  const err = await call("Svc.fail").catch((e: unknown) => e);
+  expect(isCallError(err)).toBe(true);
+  expect(isCallError(new Error("other"))).toBe(false);
+});
+
+test("Channel", () => {
+  expect(() => new Channel()).toThrow("runtime not found");
+  (globalThis as { myphp?: Runtime }).myphp = fake;
+  const fn = (n: number) => n;
+  const ch = new Channel<number>(fn);
+  expect(ch.onmessage).toBe(fn);
+  expect(ch.closed).toBe(false);
+});
+
+test("onFileDrop", () => {
+  (globalThis as { myphp?: Runtime }).myphp = fake;
+  const got: FileDrop[] = [];
+  const off = onFileDrop((d) => got.push(d));
+  listeners.get("myphp:file-drop")?.({ paths: ["/tmp/a.txt"], x: 10, y: 20 });
+  expect(got).toEqual([{ paths: ["/tmp/a.txt"], x: 10, y: 20 }]);
+  off();
+  expect(listeners.has("myphp:file-drop")).toBe(false);
+});
+
+test("onDocumentState and onDocumentReload", () => {
+  (globalThis as { myphp?: Runtime }).myphp = fake;
+  const states: DocumentState[] = [];
+  let reloads = 0;
+  const off = onDocumentState((s) => states.push(s));
+  const offReload = onDocumentReload(() => reloads++);
+  const state = { name: "a.md", path: "/tmp/a.md", edited: true, readOnly: false, conflict: false, deleted: false };
+  listeners.get("myphp:document-state")?.(state);
+  listeners.get("myphp:document-reload")?.({});
+  expect(states).toEqual([state]);
+  expect(reloads).toBe(1);
+  off();
+  offReload();
+  expect(listeners.has("myphp:document-state")).toBe(false);
+  expect(listeners.has("myphp:document-reload")).toBe(false);
+});
+
+test("preferences and onPreferences", () => {
+  (globalThis as { myphp?: Runtime }).myphp = fake;
+  expect(preferences()).toEqual(fake.preferences);
+  const got: ThemePreferences[] = [];
+  const off = onPreferences((p) => got.push(p));
+  const changed = { accent: "#ff8000", reduceMotion: true, reduceTransparency: false, highContrast: false, textScale: 1.25 };
+  listeners.get("myphp:preferences")?.(changed);
+  expect(got).toEqual([changed]);
+  off();
+  expect(listeners.has("myphp:preferences")).toBe(false);
+});
+
+test("locale, direction and onLocaleChange", () => {
+  (globalThis as { myphp?: Runtime }).myphp = fake;
+  expect(locale()).toBe("en");
+  expect(direction()).toBe("ltr");
+  const got: [string, string][] = [];
+  const off = onLocaleChange((tag, dir) => got.push([tag, dir]));
+  listeners.get("myphp:locale")?.({ locale: "ar", dir: "rtl" });
+  expect(got).toEqual([["ar", "rtl"]]);
+  off();
+  expect(listeners.has("myphp:locale")).toBe(false);
+});

package/src/index.ts

@@ -0,0 +1,268 @@
+/**
+ * Typed access to the MyPHP runtime, which MyPHP injects into every page of
+ * an app as `window.myphp`. The client that `myphp generate` writes for your PHP
+ * services is built on it; use it directly for window controls and the
+ * platform:
+ *
+ * ```ts
+ * import { currentWindow, runtime } from "myphp-runtime";
+ *
+ * if (runtime().platform === "darwin") document.body.classList.add("mac");
+ * await currentWindow.toggleMaximize();
+ * ```
+ *
+ * @module
+ */
+import type {
+  Channel as ChannelType,
+  Direction,
+  LocaleChange,
+  Runtime,
+  ThemePreferences,
+  WindowControls,
+} from "./types";
+
+export type { Direction, LocaleChange, Platform, Runtime, ThemePreferences, WindowControls } from "./types";
+
+declare global {
+  interface Window {
+    /** The MyPHP runtime; missing outside MyPHP windows. */
+    myphp?: Runtime;
+  }
+}
+
+/** Reports whether the page runs inside a MyPHP window. */
+export function isMyPHP(): boolean {
+  return typeof globalThis === "object" && (globalThis as { myphp?: Runtime }).myphp !== undefined;
+}
+
+/**
+ * Returns the MyPHP runtime. Throws when the page is not running inside a
+ * MyPHP window, e.g. when the dev server is opened in a regular browser.
+ */
+export function runtime(): Runtime {
+  const rt = (globalThis as { myphp?: Runtime }).myphp;
+  if (!rt) throw new Error("myphp: runtime not found; is this page running inside a MyPHP window?");
+  return rt;
+}
+
+/**
+ * Calls a bound PHP method by name, e.g. `call("Greeter.greet", "Ada")`.
+ * Prefer the typed client generated by `myphp generate`. A PHP exception rejects
+ * with a {@link CallError}.
+ */
+export function call<T = unknown>(method: string, ...args: unknown[]): Promise<T> {
+  try {
+    return runtime().call<T>(method, ...args);
+  } catch (err) {
+    return Promise.reject(err);
+  }
+}
+
+/**
+ * A stream of values from a PHP method that takes a `MyPHP\Channel`.
+ * Create one, pass it to the call in place of that parameter, and iterate
+ * it or handle its values with `onmessage`:
+ *
+ * ```ts
+ * const lines = new Channel<string>();
+ * const done = Shell.tail("ping -c 3 example.com", lines);
+ * for await (const line of lines) output.append(line + "\n");
+ * await done;
+ * ```
+ *
+ * It closes when the method returns; `close()`, or breaking out of the
+ * loop, stops the method. A channel serves one call.
+ */
+export type Channel<T = unknown> = ChannelType<T>;
+
+/** Creates a {@link Channel}, optionally with its `onmessage` handler. */
+export const Channel = function <T>(onmessage?: (value: T) => void): Channel<T> {
+  return runtime().channel<T>(onmessage);
+} as unknown as new <T = unknown>(onmessage?: (value: T) => void) => Channel<T>;
+
+/** Subscribes to a PHP event by name. Returns a function that unsubscribes. */
+export function on<T = unknown>(name: string, listener: (payload: T) => void): () => void {
+  return runtime().on<T>(name, listener);
+}
+
+/** Like {@link on}, but unsubscribes after the first event. */
+export function once<T = unknown>(name: string, listener: (payload: T) => void): () => void {
+  return runtime().once<T>(name, listener);
+}
+
+/**
+ * The language the app shows, a BCP 47 tag such as "en" or "zh-Hans"
+ * (`App::locale()`): the page has it from document start, so its first paint
+ * can be in it.
+ *
+ * ```ts
+ * document.documentElement.lang = locale();
+ * document.documentElement.dir = direction();
+ * ```
+ */
+export function locale(): string {
+  return runtime().locale;
+}
+
+/** The direction the language the app shows is written in: "ltr" or "rtl". */
+export function direction(): Direction {
+  return runtime().dir;
+}
+
+/**
+ * Subscribes to changes of the language the app shows, as `App::setLocale()`
+ * makes them, or the user's languages while the app follows them. The
+ * listener hears only of a language the page did not have: a page loaded
+ * after a change starts with the new one. Returns a function that
+ * unsubscribes.
+ *
+ * ```ts
+ * onLocaleChange((tag, dir) => {
+ *   document.documentElement.lang = tag;
+ *   document.documentElement.dir = dir;
+ * });
+ * ```
+ */
+export function onLocaleChange(listener: (locale: string, dir: Direction) => void): () => void {
+  return on<LocaleChange>("myphp:locale", (p) => listener(p.locale, p.dir));
+}
+
+/** A typed event sent by the PHP side, declared with `new Event(...)`. */
+export interface PhpEvent<T> {
+  readonly name: string;
+  /** Subscribes to the event and returns a function that unsubscribes. */
+  on(listener: (payload: T) => void): () => void;
+  /** Like on, but unsubscribes after the first event. */
+  once(listener: (payload: T) => void): () => void;
+}
+
+/** Returns the typed event `name`; the generated client declares them. */
+export function event<T>(name: string): PhpEvent<T> {
+  return {
+    name,
+    on: (listener) => on<T>(name, listener),
+    once: (listener) => once<T>(name, listener),
+  };
+}
+
+/** The error of a call whose PHP method threw. */
+export interface CallError extends Error {
+  readonly name: "CallError";
+  /** The method that failed, e.g. "Greeter.greet". */
+  readonly method: string;
+}
+
+/** Reports whether err comes from a PHP method that threw. */
+export function isCallError(err: unknown): err is CallError {
+  return err instanceof Error && err.name === "CallError";
+}
+
+/** Files dropped on the window, e.g. from Finder or Explorer. */
+export interface FileDrop {
+  /** Absolute paths of the dropped files and directories. */
+  paths: string[];
+  /** Where they were dropped, in CSS pixels, like `clientX`. */
+  x: number;
+  /** Where they were dropped, in CSS pixels, like `clientY`. */
+  y: number;
+}
+
+/**
+ * Subscribes to files dropped on the window, with their paths, which DOM
+ * drop events do not tell. Only the app's own pages get them. Returns a
+ * function that unsubscribes.
+ *
+ * ```ts
+ * onFileDrop(({ paths, x, y }) => {
+ *   const target = document.elementFromPoint(x, y);
+ * });
+ * ```
+ */
+export function onFileDrop(listener: (drop: FileDrop) => void): () => void {
+  return on<FileDrop>("myphp:file-drop", listener);
+}
+
+/** The document a window shows (`new Documents(...)`), as PHP describes it. */
+export interface DocumentState {
+  /** The file name, or a name such as "Untitled 2" while untitled. */
+  name: string;
+  /** The file, "" while the document is untitled. */
+  path: string;
+  /** Whether the document has unsaved changes. */
+  edited: boolean;
+  /** Whether its file can't be written: saving asks for another. */
+  readOnly: boolean;
+  /** Whether another app changed its file while it had unsaved changes. */
+  conflict: boolean;
+  /** Whether its file was deleted: saving writes it again. */
+  deleted: boolean;
+}
+
+/**
+ * Subscribes to the state of the window's document: edited, saved,
+ * renamed, moved, changed by another app. Only the app's own pages get it.
+ * Returns a function that unsubscribes.
+ *
+ * ```ts
+ * onDocumentState(({ name, edited }) => {
+ *   heading.textContent = edited ? `${name} (edited)` : name;
+ * });
+ * ```
+ */
+export function onDocumentState(listener: (state: DocumentState) => void): () => void {
+  return on<DocumentState>("myphp:document-state", listener);
+}
+
+/**
+ * Subscribes to the window's document being read from its file again:
+ * reverted, or changed by another app while it had no unsaved changes.
+ * Fetch its content again, with the service bound to
+ * `$documents->service()`. Returns a function that unsubscribes.
+ */
+export function onDocumentReload(listener: () => void): () => void {
+  return on<unknown>("myphp:document-reload", () => listener());
+}
+
+/**
+ * Returns the accent color and the accessibility settings of the desktop
+ * (`Theme::preferences()` in PHP), current from document start on.
+ * Throws outside MyPHP, as {@link runtime} does.
+ *
+ * ```ts
+ * const { accent, reduceTransparency } = preferences();
+ * ```
+ *
+ * CSS gets the accent and the text scale from the `--myphp-accent` and
+ * `--myphp-text-scale` variables of `:root`.
+ */
+export function preferences(): ThemePreferences {
+  return runtime().preferences;
+}
+
+/**
+ * Subscribes to changes of the desktop's preferences, which
+ * {@link preferences} returns; the listener gets the new ones. Returns a
+ * function that unsubscribes.
+ *
+ * ```ts
+ * const apply = (p: ThemePreferences) => root.classList.toggle("opaque", p.reduceTransparency);
+ * apply(preferences());
+ * onPreferences(apply);
+ * ```
+ */
+export function onPreferences(listener: (preferences: ThemePreferences) => void): () => void {
+  return on<ThemePreferences>("myphp:preferences", listener);
+}
+
+/** The window hosting the page, e.g. for a custom title bar. */
+export const currentWindow: WindowControls = {
+  minimize: async () => runtime().window.minimize(),
+  maximize: async () => runtime().window.maximize(),
+  unmaximize: async () => runtime().window.unmaximize(),
+  toggleMaximize: async () => runtime().window.toggleMaximize(),
+  isMaximized: async () => runtime().window.isMaximized(),
+  toggleFullScreen: async () => runtime().window.toggleFullScreen(),
+  close: async () => runtime().window.close(),
+  setTitle: async (title) => runtime().window.setTitle(title),
+};

package/src/types.ts

@@ -0,0 +1,105 @@
+/** The operating system, using Node.js' `process.platform` names. */
+export type Platform = "darwin" | "linux" | "win32";
+
+/** The direction a language is written in: left to right, or right to left. */
+export type Direction = "ltr" | "rtl";
+
+/** The payload of the `myphp:locale` event. */
+export interface LocaleChange {
+  /** The language the app shows now, e.g. "zh-Hans". */
+  locale: string;
+  /** The direction it is written in. */
+  dir: Direction;
+}
+
+/** Controls for the window hosting the page, handy for custom title bars. */
+export interface WindowControls {
+  minimize(): Promise<void>;
+  maximize(): Promise<void>;
+  unmaximize(): Promise<void>;
+  toggleMaximize(): Promise<void>;
+  isMaximized(): Promise<boolean>;
+  toggleFullScreen(): Promise<void>;
+  close(): Promise<void>;
+  setTitle(title: string): Promise<void>;
+}
+
+/**
+ * A stream of values from a PHP method that takes a `MyPHP\Channel`,
+ * passed to the call in its place. Iterate it, or handle the values with
+ * `onmessage`: values that arrive before either wait for it. The channel
+ * closes when the method returns, or calls `Close`, once its values are
+ * taken; `close()` stops the method.
+ */
+export interface Channel<T = unknown> extends AsyncIterable<T> {
+  /** Called with each value, instead of iterating. */
+  onmessage: ((value: T) => void) | null;
+  /** Called when the channel closes. */
+  onclose: (() => void) | null;
+  /** Whether the channel is closed. */
+  readonly closed: boolean;
+  /**
+   * Closes the channel, dropping values not taken yet: the PHP method's
+   * `send()` fails and it stops. Breaking out of a
+   * `for await` loop over the channel closes it too.
+   */
+  close(): void;
+}
+
+/**
+ * The accent color and the accessibility settings of the desktop, as
+ * `MyPHP\ThemePreferences` encodes them.
+ */
+export interface ThemePreferences {
+  /** The accent color of the desktop's controls as "#rrggbb", or null where the desktop has none. */
+  accent: string | null;
+  /** Whether the desktop asks for less motion; `prefers-reduced-motion` tells it too. */
+  reduceMotion: boolean;
+  /**
+   * Whether the desktop asks for opaque surfaces in place of translucent
+   * ones: macOS's Reduce Transparency, Windows's transparency effects
+   * turned off. Linux desktops have no such setting.
+   */
+  reduceTransparency: boolean;
+  /** Whether the desktop asks for more contrast; `prefers-contrast` tells it too. */
+  highContrast: boolean;
+  /** How many times larger than usual text should be; 1 is usual. */
+  textScale: number;
+}
+
+/** The runtime MyPHP injects into every page as `window.myphp`. */
+export interface Runtime {
+  /** Calls a bound PHP method, e.g. `call("Greeter.greet", "Ada")`. */
+  call<T = unknown>(method: string, ...args: unknown[]): Promise<T>;
+  /**
+   * Creates a channel to pass to a call of a PHP method that streams values
+   * through a `MyPHP\Channel` parameter. A channel serves one call.
+   */
+  channel<T = unknown>(onmessage?: (value: T) => void): Channel<T>;
+  /** Subscribes to a PHP event. Returns a function that unsubscribes. */
+  on<T = unknown>(event: string, listener: (payload: T) => void): () => void;
+  /** Like `on`, but unsubscribes after the first event. */
+  once<T = unknown>(event: string, listener: (payload: T) => void): () => void;
+  /** The operating system. */
+  readonly platform: Platform;
+  /** The id of the `MyPHP\Window` hosting this page. */
+  readonly windowId: number;
+  /** MyPHP version. */
+  readonly version: string;
+  /**
+   * The desktop's preferences, current from document start on; the
+   * `myphp:preferences` event tells their changes.
+   */
+  readonly preferences: ThemePreferences;
+  /**
+   * The language the app shows, a BCP 47 tag such as "en" or "zh-Hans"
+   * (`App::locale()`): of the languages the app is written in, the one the
+   * user reads best, or the one `App::setLocale()` chose. A page has it from
+   * document start, and the `myphp:locale` event tells of changes.
+   */
+  readonly locale: string;
+  /** The direction `locale` is written in, for `<html dir>`. */
+  readonly dir: Direction;
+  /** The window hosting this page. */
+  readonly window: WindowControls;
+}