janela 0.18.1 → 0.19.0

package/bin/lib.mjs

@@ -239,6 +239,9 @@ export function ffiManifest(shimLib, { platform = process.platform, macSdkPath =
       ],
       returns: "i32",
     },
+    // No handle: the responder chain and the key window are process state,
+    // not per-window, so this is the one call that takes only its argument.
+    { name: "wvPerformAction", symbol: "wv_perform_action", params: ["string"], returns: "i32" },
     { name: "wvMenuSetEnabled", symbol: "wv_menu_set_enabled", params: ["i32", "i32", "i32"], returns: "i32" },
     { name: "wvMenuSetChecked", symbol: "wv_menu_set_checked", params: ["i32", "i32", "i32"], returns: "i32" },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "janela",
-  "version": "0.18.1",
+  "version": "0.19.0",
   "description": "Desktop, iOS and Android apps in pure TypeScript, compiled to native. No Rust, no Node, no Electron.",
   "type": "module",
   "bin": {

package/runtime/ios.ts

@@ -102,6 +102,121 @@ function pending(api: string, why: string): string {
  * scheduled by the shell, the library re-entered when they fire) is the whole
  * of that change on this side.
  */
+// ---- menus ---------------------------------------------------------------
+//
+// A mirror of the desktop lane's menu builders, so a project's src-host can
+// declare a menu and still compile for a phone. Nothing renders here — iOS
+// has no menu bar — but the objects are real, so handlers, `setEnabled` and
+// the rest are ordinary no-ops rather than missing symbols.
+//
+// Duplicated rather than shared because the CLI copies ONE of these two files
+// in as `./janela`: a shared module would have to inject the FFI the desktop
+// setters call, which is more machinery than the forty lines it would save.
+
+/** Submenus and separators have nothing to run. */
+function menuNoop(): void {}
+
+/** An entry in the application menu. See the desktop lane for what it does. */
+export class MenuItem {
+  label: string;
+  accel: string;
+  separator: boolean;
+  items: MenuItem[];
+  onClick: () => void;
+  enabled = true;
+  checkable = false;
+  checked = false;
+  tag = -1;
+  ownerHandle = -1;
+
+  constructor(
+    label: string,
+    accel: string,
+    separator: boolean,
+    items: MenuItem[],
+    onClick: () => void,
+  ) {
+    this.label = label;
+    this.accel = accel;
+    this.separator = separator;
+    this.items = items;
+    this.onClick = onClick;
+  }
+
+  /** Records the state. False: there is no live menu here to change. */
+  setEnabled(on: boolean): boolean {
+    this.enabled = on;
+    return false;
+  }
+
+  /** Records the state. False: there is no live menu here to change. */
+  setLabel(label: string): boolean {
+    this.label = label;
+    return false;
+  }
+}
+
+/** An item that can carry a tick. */
+export class CheckMenuItem extends MenuItem {
+  constructor(label: string, accel: string, onClick: () => void) {
+    super(label, accel, false, [], onClick);
+    this.checkable = true;
+  }
+
+  /** Records the state. False: there is no live menu here to change. */
+  setChecked(on: boolean): boolean {
+    this.checked = on;
+    return false;
+  }
+}
+
+/** A clickable entry. `accel` is "" for no shortcut. */
+export function menuItem(label: string, accel: string, onClick: () => void): MenuItem {
+  return new MenuItem(label, accel, false, [], onClick);
+}
+
+/** A clickable entry that carries a tick. */
+export function menuCheckItem(label: string, accel: string, onClick: () => void): CheckMenuItem {
+  return new CheckMenuItem(label, accel, onClick);
+}
+
+/** A divider. */
+export function menuSeparator(): MenuItem {
+  return new MenuItem("", "", true, [], menuNoop);
+}
+
+/** A submenu holding other entries. Nestable. */
+export function submenu(label: string, items: MenuItem[]): MenuItem {
+  return new MenuItem(label, "", false, items, menuNoop);
+}
+
+/**
+ * The platform's own actions.
+ *
+ * Every one returns false here. On desktop these are AppKit selectors, Win32
+ * messages and WebKitGTK editing commands; a phone has none of them, and the
+ * editing gestures it does have belong to UIKit and need no menu to reach.
+ */
+export const predefined = {
+  about: (): boolean => false,
+  hide: (): boolean => false,
+  hideOthers: (): boolean => false,
+  showAll: (): boolean => false,
+  quit: (): boolean => false,
+  close: (): boolean => false,
+
+  undo: (): boolean => false,
+  redo: (): boolean => false,
+  cut: (): boolean => false,
+  copy: (): boolean => false,
+  paste: (): boolean => false,
+  selectAll: (): boolean => false,
+
+  minimize: (): boolean => false,
+  zoom: (): boolean => false,
+  fullscreen: (): boolean => false,
+};
+
 /**
  * A running janela app on iOS, typed by the contract it serves.
  *
@@ -462,6 +577,19 @@ export class JanelaAppImpl<
     console.error(pending("quit", "iOS apps are dismissed by the user"));
   }
 
+  /**
+   * @remarks Returns false on iOS: a phone has no menu bar to put this in.
+   *
+   * Present so a project's `src-host/main.ts` compiles on both lanes — the
+   * whole reason this file mirrors the desktop one. The items are still built,
+   * so their handlers and any later `setEnabled` are ordinary no-ops rather
+   * than crashes; what is absent is somewhere to render them.
+   */
+  setMenu(_entries: MenuItem[]): boolean {
+    console.error(pending("setMenu", "a phone has no menu bar"));
+    return false;
+  }
+
   /**
    * Present for source compatibility with the desktop lane; UIKit owns the run
    * loop here, so the shell shows the page rather than this.

package/runtime/janela.ts

@@ -44,6 +44,7 @@ declare function wvDialog(
 declare function wvSetFullscreen(h: number, on: number): number;
 declare function wvSetMenu(h: number, spec: string): number;
 declare function wvOnMenu(h: number, cb: (tag: number) => number): number;
+declare function wvPerformAction(action: string): number;
 declare function wvMenuSetEnabled(h: number, tag: number, on: number): number;
 declare function wvMenuSetChecked(h: number, tag: number, on: number): number;
 declare function wvMenuSetLabel(h: number, tag: number, label: string): number;
@@ -174,31 +175,35 @@ const TIMER_JOBS = -1;
 // handler registry here, is written into the wire format, comes back on a
 // click, and is what setEnabled/setChecked/setLabel address.
 
-// NSEventModifierFlags.
-const MENU_SHIFT = 131072;
-const MENU_CONTROL = 262144;
-const MENU_OPTION = 524288;
-const MENU_COMMAND = 1048576;
-
-/** "CmdOrCtrl+Shift+O" -> "o<US>1179648". Unknown words are taken as the key. */
+// Modifiers travel SYMBOLICALLY, not as one platform's constants.
+//
+// They used to be NSEventModifierFlags integers, which only worked because
+// macOS was the only renderer. Naming the intent instead lets each platform
+// map it — and it is the only way "CmdOrCtrl" can mean what it says, since the
+// runtime does not know which platform it was built for.
+const MOD_PRIMARY = 1; // CmdOrCtrl: Command on macOS, Control elsewhere
+const MOD_SHIFT = 2;
+const MOD_ALT = 4; // Option on macOS
+const MOD_CTRL = 8; // Control, explicitly, on every platform
+const MOD_CMD = 16; // Command, explicitly; ignored where there is none
+
+/** "CmdOrCtrl+Shift+O" -> "o<US>3". Unknown words are taken as the key. */
 function parseAccel(accel: string): string {
   const parts = accel.split("+");
   let mods = 0;
   let key = "";
   for (let i = 0; i < parts.length; i++) {
     const p = parts[i].toLowerCase();
-    if (p === "cmd" || p === "command" || p === "meta" || p === "super") {
-      mods = mods | MENU_COMMAND;
-    } else if (p === "cmdorctrl" || p === "commandorcontrol") {
-      // macOS is the only platform with custom menus so far, so this is
-      // Command here; the Windows and Linux renderers will read it as Control.
-      mods = mods | MENU_COMMAND;
+    if (p === "cmdorctrl" || p === "commandorcontrol") {
+      mods = mods | MOD_PRIMARY;
+    } else if (p === "cmd" || p === "command" || p === "meta" || p === "super") {
+      mods = mods | MOD_CMD;
     } else if (p === "ctrl" || p === "control") {
-      mods = mods | MENU_CONTROL;
+      mods = mods | MOD_CTRL;
     } else if (p === "alt" || p === "option") {
-      mods = mods | MENU_OPTION;
+      mods = mods | MOD_ALT;
     } else if (p === "shift") {
-      mods = mods | MENU_SHIFT;
+      mods = mods | MOD_SHIFT;
     } else if (p !== "") {
       key = p;
     }
@@ -258,21 +263,20 @@ export class MenuItem {
    *
    * Applied immediately when the item is already in a menu, and remembered
    * for the next `setMenu` when it is not — so state set before mounting is
-   * not lost.
+   * not lost. The return says which of the two happened: true when the live
+   * menu was changed, false when the value was only recorded.
    */
-  setEnabled(on: boolean): void {
+  setEnabled(on: boolean): boolean {
     this.enabled = on;
-    if (this.ownerHandle >= 0 && this.tag >= 0) {
-      wvMenuSetEnabled(this.ownerHandle, this.tag, on ? 1 : 0);
-    }
+    if (this.ownerHandle < 0 || this.tag < 0) return false;
+    return wvMenuSetEnabled(this.ownerHandle, this.tag, on ? 1 : 0) === 0;
   }
 
   /** Change the text without rebuilding the menu. */
-  setLabel(label: string): void {
+  setLabel(label: string): boolean {
     this.label = label;
-    if (this.ownerHandle >= 0 && this.tag >= 0) {
-      wvMenuSetLabel(this.ownerHandle, this.tag, label);
-    }
+    if (this.ownerHandle < 0 || this.tag < 0) return false;
+    return wvMenuSetLabel(this.ownerHandle, this.tag, label) === 0;
   }
 }
 
@@ -292,12 +296,11 @@ export class CheckMenuItem extends MenuItem {
     this.checkable = true;
   }
 
-  /** Tick or untick the item. */
-  setChecked(on: boolean): void {
+  /** Tick or untick the item. Returns as `setEnabled` does. */
+  setChecked(on: boolean): boolean {
     this.checked = on;
-    if (this.ownerHandle >= 0 && this.tag >= 0) {
-      wvMenuSetChecked(this.ownerHandle, this.tag, on ? 1 : 0);
-    }
+    if (this.ownerHandle < 0 || this.tag < 0) return false;
+    return wvMenuSetChecked(this.ownerHandle, this.tag, on ? 1 : 0) === 0;
   }
 }
 
@@ -306,6 +309,70 @@ export function menuItem(label: string, accel: string, onClick: () => void): Men
   return new MenuItem(label, accel, false, [], onClick);
 }
 
+/**
+ * The platform's own actions, callable from anywhere.
+ *
+ * ```ts
+ * const close = menuItem("Close", "CmdOrCtrl+W", () => predefined.close());
+ * const copy  = menuItem("Copy",  "CmdOrCtrl+C", () => predefined.copy());
+ *
+ * // and they compose, which a fixed "predefined item" never could:
+ * menuItem("Save and close", "", () => { write(); predefined.close(); });
+ * ```
+ *
+ * Copy, paste and undo are the interesting ones: they are not "do this" but a
+ * selector sent up the responder chain, and by the time a handler here runs
+ * the menu click has already been delivered to us. So these ask the platform
+ * to send the action up the chain at that moment, which is what lets it reach
+ * the webview's editing context. `document.execCommand("paste")` cannot —
+ * webviews block it.
+ *
+ * An action with no equivalent on a platform returns false rather than
+ * pretending. What exists where:
+ *
+ * - everywhere: `quit`, `close`, `minimize`, `zoom`, `fullscreen`, `about`,
+ *   `undo`, `redo`, `cut`, `copy`, `paste`, `selectAll`
+ * - macOS only: `hide`, `hideOthers`, `showAll`
+ *
+ * The three that stop at macOS are not a missing API but a missing concept.
+ * `hide` is application state there — windows vanish, the app stays in the
+ * Dock, one click brings it back. Hiding a window on Windows or Linux instead
+ * takes it out of the taskbar with no way back short of a tray icon, and
+ * `hideOthers` / `showAll` reach into other applications: the nearest Windows
+ * call minimizes you too, and on Wayland there is nothing at all.
+ *
+ * `about` shows each platform's own About box — NSApplication's panel,
+ * `ShellAboutW`, `gtk_show_about_dialog` — named after the process, which is
+ * what the macOS application menu shows. A richer one is your app's to build.
+ *
+ * Each platform reaches the editing commands by its own route: AppKit
+ * selectors up the responder chain, WebKitGTK's
+ * `webkit_web_view_execute_editing_command`, and on Windows the DevTools
+ * protocol, since WebView2 runs the page out of process and exposes no
+ * copy/paste entry point of its own. On Windows and Linux the call is
+ * dispatched rather than awaited, so a `true` there means the browser was
+ * asked, not that it has finished.
+ */
+export const predefined = {
+  about: (): boolean => wvPerformAction("about") === 0,
+  hide: (): boolean => wvPerformAction("hide") === 0,
+  hideOthers: (): boolean => wvPerformAction("hideOthers") === 0,
+  showAll: (): boolean => wvPerformAction("showAll") === 0,
+  quit: (): boolean => wvPerformAction("quit") === 0,
+  close: (): boolean => wvPerformAction("closeWindow") === 0,
+
+  undo: (): boolean => wvPerformAction("undo") === 0,
+  redo: (): boolean => wvPerformAction("redo") === 0,
+  cut: (): boolean => wvPerformAction("cut") === 0,
+  copy: (): boolean => wvPerformAction("copy") === 0,
+  paste: (): boolean => wvPerformAction("paste") === 0,
+  selectAll: (): boolean => wvPerformAction("selectAll") === 0,
+
+  minimize: (): boolean => wvPerformAction("minimize") === 0,
+  zoom: (): boolean => wvPerformAction("zoom") === 0,
+  fullscreen: (): boolean => wvPerformAction("fullscreen") === 0,
+};
+
 /** A clickable entry that carries a tick. `accel` is "" for no shortcut. */
 export function menuCheckItem(label: string, accel: string, onClick: () => void): CheckMenuItem {
   return new CheckMenuItem(label, accel, onClick);
@@ -704,8 +771,17 @@ export class JanelaAppImpl<
    * save.setEnabled(false);   // later, without rebuilding
    * ```
    *
-   * Returns false where custom menus are not supported yet — everything but
-   * macOS. The standard menu is unaffected either way.
+   * Renders on all three desktop platforms: an NSMenu bar, a Win32 menu, or a
+   * GtkMenuBar above the webview. Returns false if the platform refused —
+   * GTK 4, where GtkMenuBar no longer exists, is the one case that does.
+   *
+   * What differs is the FLOOR beneath it. macOS gets a standard bar whether
+   * you set one or not, because there a Command shortcut is a menu key
+   * equivalent and an app with no menu has no Cmd+Q or Cmd+V. Windows and
+   * Linux need no such floor: Alt+F4 is the window manager's, and the editing
+   * keys belong to WebView2 and WebKitGTK. So an app that never calls this
+   * has a full menu bar on macOS and none elsewhere — which is what an app
+   * with nothing in its menus should look like on each.
    */
   setMenu(entries: MenuItem[]): boolean {
     // A rebuild invalidates every tag from the previous call, so the registry