electrobun 0.0.2 → 0.0.4

package/documentation/docs/apis/browser/Electroview Class.md

@@ -0,0 +1,158 @@
+---
+sidebar_position: 1
+---
+
+> Instantiate Electrobun apis in the browser.
+
+```
+import {Electroview} from "electrobun/view";
+
+const electrobun = new Electroview({ ...options })
+
+```
+
+## Constructor Options
+
+### rpc
+
+This is the browser side of creating typed RPC between the main bun process and a given BrowserView's context.
+
+```typescript title="src/shared/types.ts"
+export type MyWebviewRPCType = {
+  // functions that execute in the main process
+  bun: RPCSchema<{
+    requests: {
+      someBunFunction: {
+        params: {
+          a: number;
+          b: number;
+        };
+        response: number;
+      };
+    };
+    messages: {
+      logToBun: {
+        msg: string;
+      };
+    };
+  }>;
+  // functions that execute in the browser context
+  webview: RPCSchema<{
+    requests: {
+      someWebviewFunction: {
+        params: {
+          a: number;
+          b: number;
+        };
+        response: number;
+      };
+    };
+    messages: {
+      logToWebview: {
+        msg: string;
+      };
+    };
+  }>;
+};
+```
+
+```typescript title="/src/myview/index.ts"
+import { Electroview } from "electrobun/view";
+import { type MyWebviewRPCType } from "../shared/types";
+
+const rpc = Electroview.defineRPC<MyWebviewRPC>({
+  handlers: {
+    requests: {
+      someWebviewFunction: ({ a, b }) => {
+        document.body.innerHTML += `bun asked me to do math with ${a} and ${b}\n`;
+        return a + b;
+      },
+    },
+    messages: {
+      logToWebview: ({ msg }) => {
+        // this will appear in the inspect element devtools console
+        console.log(`bun asked me to logToWebview: ${msg}`);
+      },
+    },
+  },
+});
+const electroview = new ElectrobunView.Electroview({ rpc });
+```
+
+Assuming you've wired up rpc on the bun side when creating the [BrowserWindow](/docs/apis/bun/BrowserWindow) you'll be able to call those bun functions from the browser.
+
+```typescript title="/src/myview/index.ts"
+electroview.rpc.request.someBunFunction({ a: 9, b: 8 }).then((result) => {
+  console.log("result: ", result);
+});
+
+// or
+electroview.rpc.send.logToBun({ msg: "hi from browser" });
+```
+
+## Static Methods
+
+### defineRPC
+
+Pass `Electroview.defineRPC` the shared rpc type to generate the typed rpc and message functions you can call from the browser and to set up types for the browser handlers for functions handled in the browser.
+
+## Methods
+
+### syncRPC
+
+Regular Electrobun rpc between the bun and browser process is async and non-blocking. There may be times when you want the BrowserView process to halt while the bun process asynchronously responds as a way to simulate a synchronous api. This will also halt the zig and objc processes while waiting for a response.
+
+Internally Electrobun uses this mechanism for things that require synchronous response like when waiting for the bun process to make a `will-navigate` decision for a BrowserView to allow or block the navigation.
+
+You may want to use the synchronous api when migrating from Electron to Electrobun if you made heavy use of Electron's nodeIntegration as a way to break up the migration and simplify the steps to refactor to an asynchronous architecture.
+
+:::warning
+Since the syncRPC is blocking we currently don't provide automatic typing for functions and strongly discourage usage unless you really know what you're doing.
+:::
+
+Assuming you've defined syncRPC bun handlers
+
+```typescript title="/src/bun/index.ts"
+const win = new BrowserWindow({
+  title: "my url window",
+  url: "views://mainview/index.html",
+  frame: {
+    width: 1800,
+    height: 600,
+    x: 2000,
+    y: 2000,
+  },
+  rpc: myWebviewRPC,
+  // define syncRPC handlers
+  syncRpc: {
+    doSyncMathInBun: ({ a, b }) => {
+      console.log("doing sync math in bun", a, b);
+      return a + b;
+    },
+  },
+});
+```
+
+:::note
+You'll notice when using the syncRPC api you don't need to use async/await since the entire browser thread will freeze while waiting for bun to return the result.
+:::
+
+```typescript title="/src/mainview/index.ts"
+const electrobun = new Electroview();
+
+// The entire thread will halt while waiting for bun to respond
+const syncMathResult = electrobun.syncRpc({
+  // These method signatures are not currently typed to discourage usage
+  // of the syncRPC api
+  method: "doSyncMath",
+  params: { a: 5, b: 9 },
+});
+
+document.body.innerHTML += `<br> \nsync result: ${syncMathResult}\n`;
+```
+
+### Browser to Browser RPC
+
+Electrobun doesn't provide browser to browser RPC out of the box as we favour isolation between browser contexts for greater security.
+
+There's nothing stopping you from creating bun to browser rpc for two different BrowserViews and passing messages between them via bun. You can also establish any number of other web-based mechanisms to communicated between browser contexts from localstorage to webRTC or via a server.

package/documentation/docs/apis/browser/GlobalProperties.md

@@ -0,0 +1,11 @@
+## Global Properties
+
+These global properties are injected into the browser context regardless of whether you've instantiated the `Electroview`.
+
+### window.\_\_electrobunWebviewId
+
+The id of the webview
+
+### window.\_\_electrobunWindowId
+
+The id of the window

package/documentation/docs/apis/browser/index.md

@@ -0,0 +1,25 @@
+---
+sidebar_position: 2
+title: "Browser API"
+---
+
+These are apis you can use in the BrowserView browser context. If you're just starting to look around take a look at the [Getting Started Guide](/docs/guides/Getting%20Started/) first to learn how to set up your first project.
+
+The Electrobun Browser api is not injected into browser contexts automatically. Instead you'll configure your `electrobun.config` file to use bun to build browser typescript code where you can write typescript. The cli will bundle the transpiled code with your app, and then you can use the `views://` scheme to load html and that bundled javascript or load it as `preload` script in a BrowserView.
+
+While there's no need to use the Browser API at all in your BrowserViews if you want to establish rpc between browserview and bun or use other Electrobun apis in the browser you'll need to use it.
+
+You should explicitly import the `electrobun/view` api in browser processes:
+
+```typescript
+import Electrobun from "electrobun/view";
+
+// or
+
+import {
+  Electroview,
+  // other specified imports
+} from "electrobun/view";
+
+const electrobun = new Electroview(/*...*/);
+```

package/documentation/docs/apis/bun/ApplicationMenu.md

@@ -0,0 +1,141 @@
+> Create and control an application menu. In MacOS this is the menu in the top-left with File, Edit, and so on.
+
+```
+import {ApplicationMenu} from "electrobun/bun";
+
+
+ApplicationMenu.setApplicationMenu([
+  {
+    submenu: [{ label: "Quit", role: "quit" }],
+  },
+  {
+    label: "Edit",
+    submenu: [
+      { role: "undo" },
+      { role: "redo" },
+      { type: "separator" },
+      {
+        label: "Custom Menu Item  🚀",
+        action: "custom-action-1",
+        tooltip: "I'm a tooltip",
+      },
+      {
+        label: "Custom menu disabled",
+        enabled: false,
+        action: "custom-action-2",
+      },
+      { type: "separator" },
+      { role: "cut" },
+      { role: "copy" },
+      { role: "paste" },
+      { role: "pasteAndMatchStyle" },
+      { role: "delete" },
+      { role: "selectAll" },
+    ],
+  },
+]);
+
+Electrobun.events.on("application-menu-clicked", (e) => {
+  console.log("application menu clicked", e.data.action); // custom-actino
+});
+
+```
+
+### setApplicationMenu
+
+This function takes an array of menu items. Here are some example menu items:
+
+### Menu dividers
+
+```
+// menu dividers
+{type: "divider"}
+// or
+{type: "separator"}
+
+```
+
+### Default Roles
+
+Menu items can specify a role instead of an action. Use menu item roles to access built-in OS functionality and enable their corresponding keyboard shortcuts.
+
+If you want to enable keyboard shortcuts like `cmd+q` to quit your application, `cmd+c` and `cmd+v` for copy and paste then you need to specify menu items with the corresponding roles.
+
+```
+// example Edit menu
+ {
+    label: "Edit",
+    submenu: [
+      // Corresponding keyboard shotcuts will automatically
+      // be bound when a valid role is set.
+      { role: "undo" },
+      { role: "redo" },
+      { type: "separator" },
+      { role: "cut" },
+      { role: "copy" },
+      { role: "paste" },
+      { role: "pasteAndMatchStyle" },
+      { role: "delete" },
+      { role: "selectAll" },
+    ],
+  },
+```
+
+List of supported roles
+
+```
+  quit: "Quit",
+  hide: "Hide",
+  hideOthers: "Hide Others",
+  showAll: "Show All",
+  undo: "Undo",
+  redo: "Redo",
+  cut: "Cut",
+  copy: "Copy",
+  paste: "Paste",
+  pasteAndMatchStyle: "Paste And Match Style",
+  delete: "Delete",
+  selectAll: "Select All",
+  startSpeaking: "Start Speaking",
+  stopSpeaking: "Stop Speaking",
+  enterFullScreen: "Enter FullScreen",
+  exitFullScreen: "Exit FullScreen",
+  toggleFullScreen: "Toggle Full Screen",
+  minimize: "Minimize",
+  zoom: "Zoom",
+  bringAllToFront: "Bring All To Front",
+  close: "Close",
+  cycleThroughWindows: "Cycle Through Windows",
+  showHelp: "Show Help",
+```
+
+### Custom Menu Items
+
+Instead of a role you can specify and action, you can then listen for that action in the 'application-menu-clicked' event.
+
+```
+// basic menu item
+{label: "I am a menu item", action: 'some-action'}
+```
+
+## Optionaly properties
+
+### enabled
+
+Set to false to show the menu item as disabled
+
+### checked
+
+Set to true to show a checkbox next to the menu item.
+
+### hidden
+
+Set to true to hide
+
+### tooltip
+
+Will show this tooltip when hovering over the menu item
+
+### submenu
+
+The top-level menu corresponds to the menu items you see when the app is focused, eg: File, Edit, View, etc. You can add actions to those if you want and treat them like buttons, but you can also add nested submenus.