npm - electrobun - Versions diffs - 0.0.1 → 0.0.3 - Mend

electrobun 0.0.1 → 0.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (729) hide show

package/documentation/docs/apis/bun/BrowserWindow.md ADDED Viewed

@@ -0,0 +1,423 @@
+> Create and control browser windows
+```typescript
+// in the main process
+import { BrowserWindow } from "electrobun/bun";
+const win = new BrowserWindow({
+  title: "my url window",
+  frame: {
+    width: 1800,
+    height: 600,
+    x: 2000,
+    y: 2000,
+  },
+  url: "views://mainview/index.html",
+});
+```
+## Constructor Options
+### title
+Set the title of the window.
+```
+const win = new BrowserWindow({
+  title: "my url window",
+});
+```
+### frame
+Set the window dimensions
+```
+const win = new BrowserWindow({
+   frame: {
+    width: 1800,
+    height: 600,
+    x: 2000,
+    y: 2000,
+  },
+});
+```
+### styleMask
+This controls the OSX window appearance and functionality. You can set the following:
+```
+const win = new BrowserWindow({
+  title: "my url window",
+  url: "views://mainview/index.html",
+  frame: {
+    width: 1800,
+    height: 600,
+    x: 2000,
+    y: 2000,
+  },
+  styleMask: {
+    // These are the current defaults
+    Borderless: false,
+    Titled: true,
+    Closable: true,
+    Miniaturizable: true,
+    Resizable: true,
+    UnifiedTitleAndToolbar: false,
+    FullScreen: false,
+    FullSizeContentView: false,
+    UtilityWindow: false,
+    DocModalWindow: false,
+    NonactivatingPanel: false,
+    HUDWindow: false,
+  }
+});
+```
+### titleBarStyle
+This is an additional window configuration for OSX. This can be set to either `hiddenInset` or `default`. When setting it to `hiddenInset` it will also override `Titled` and `FullSizeContentView` to be `true`
+```
+const win = new BrowserWindow({
+  title: "my url window",
+  url: "views://mainview/index.html",
+  frame: {
+    width: 1800,
+    height: 600,
+    x: 2000,
+    y: 2000,
+  },
+  titleBarStyle: 'hiddenInset',
+  styleMask: {
+    // In addition to the defaults, these will be forced to true when titleBarStyle
+    // is set to hiddenInset
+    Titled: true,
+    FullSizeContentView: true,
+  }
+});
+```
+:::info
+The following options are used to instantiate the default BrowserView
+:::
+### url
+Set the initial url for the window's default BrowserView to navigate to when it opens.
+```
+// Use any url on the internet
+const win = new BrowserWindow({
+   url: "https://electrobun.dev",
+});
+// or use the views:// url scheme to load local
+// content that you've bundled with your app.
+const win = new BrowserWindow({
+   url: "views://mainview/index.html",
+});
+```
+### html
+Set an html string for the window's default BrowserView to load when it opens. Anything that would be valid in an html file including javascript and css can be used.
+Use this instead of setting the `url` property.
+```
+const htmlString = "<html><head></head><body><h1>hello world</h1></body></html>";
+const win = new BrowserWindow({
+   html: htmlString,
+});
+```
+### partition
+Partitions allow you to separate the browser session. Things like cookies and so on. For example if you have two BrowserViews with the same partition and log into gmail in one, the other will also be logged into gmail. If you use two different partitions then you could log into a different gmail account in each BrowserView.
+```
+// ephemeral partition. If you close and reopen your app
+// even if you use the same partition name it will not
+// have persisted.
+const win = new BrowserWindow({
+   partition: "partition1",
+});
+// To make partitions persistent just prefix it with `persist:`
+const win = new BrowserWindow({
+   partition: "persist:partition1",
+});
+```
+### preload
+Set a preload script for the window's default BrowserView to render after html is parsed but before any other javascript is executed. The preload script will be run after any navigation before the page's scripts are run.
+You can use either inline javascript or a url.
+```
+// Use any url on the internet
+const win = new BrowserWindow({
+   preload: "https://electrobun.dev/some/remote/file.js",
+});
+// or use the views:// preload scheme to load local
+// content that you've bundled with your app.
+const win = new BrowserWindow({
+   preload: "views://somebundledview/preloadscript.js",
+});
+// or use inline javascript
+const win = new BrowserWindow({
+   preload: "document.body.innerHTML = 'Hello world'; console.log('hello console')",
+});
+```
+### rpc
+The RPC property allows you to establish RPC (remote procedure calls) between the bun process and this window's default BrowserView. In other words it lets you define functions that execute in the bun process that are callable and return a value back to the browser process and visa versa.
+These RPC functions are asynchronous.
+```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/bun/index.ts"
+import { BrowserWindow, BrowserView } from "electrobun/bun";
+import { type MyWebviewRPCType } from "../shared/types";
+// Create an RPC object for the bun handlers with the shared type
+const myWebviewRPC = BrowserView.defineRPC<MyWebviewRPC>({
+  maxRequestTime: 5000,
+  handlers: {
+    requests: {
+      someBunFunction: ({ a, b }) => {
+        console.log(`browser asked me to do math with: ${a} and ${b}`);
+        return a + b;
+      },
+    },
+    // When the browser sends a message we can handle it
+    // in the main bun process
+    messages: {
+      "*": (messageName, payload) => {
+        console.log("global message handler", messageName, payload);
+      },
+      logToBun: ({ msg }) => {
+        console.log("Log to bun: ", msg);
+      },
+    },
+  },
+});
+// Pass the RPC object to the BrowserWindow, which will set it
+// on the window's default BrowserView
+const win = new BrowserWindow({
+  title: "my window",
+  url: "views://mainview/index.html",
+  frame: {
+    width: 1800,
+    height: 600,
+    x: 2000,
+    y: 2000,
+  },
+  rpc: myWebviewRPC,
+});
+// ... later on
+// Note: These RPC methods will inherit types from the shared type
+// Call a browser function from bun
+const answer = await win.webview.rpc.someWebviewFunction(4, 6);
+// Send a message to the BrowserView from bun
+win.webview.rpc.logToBrowser("my message");
+```
+:::info
+The above code snippet shows defining the bun process rpc handlers and calling the browser process handlers from bun. To see how to handle the Browser context code take a look at the [Browser API](/docs/apis/browser/Electroview%20Class)
+:::
+### syncRpc
+:::warning
+The `SyncRpc` api is blocking. Calling `syncRpc` methods from the browser will completely block the browser thread and halt javascript while waiting for the bun process to respond.
+:::
+:::info
+Really the only time you may want to use the `syncRpc` api instead of the regular async `rpc` api is when you're migrating from Electron to Electrobun and you had a lot of browser code with the node integration enabled. Using the `syncRpc` api can save you lots of time on the initial refactor/migration.
+It's strongly advised to later follow up and migrate `syncRpc` methods to async `rpc` later on.
+:::
+```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,
+  },
+  syncRpc: {
+    someSyncBunMethod: ({ a, b }) => {
+      console.log("doing sync math in bun", a, b);
+      return a + b;
+    },
+  },
+});
+```
+To see how to call syncRpc methods from the browser take a look at the [Browser API](/docs/apis/browser/Electroview%20Class)
+## Properties
+### webview
+This is a getter for the window's default [BrowserView](/docs/apis/bun/BrowserView)
+```
+const win = new BrowserWindow({
+   ...
+});
+const defaultWebview = win.webview;
+```
+## Methods
+### setTitle
+Change the window title:
+```
+win.setTitle('new title')
+```
+### close
+Close a window
+```
+win.close();
+```
+### on(name, handler)
+Subscribe to BrowserWindow events (see below)
+## Events
+### close
+When a window closes.
+```
+// listen to a specific window's close event
+win.on('close', (event) => {
+  const {id} = event.data;
+  console.log('window closed')
+});
+// listen globally to window close events
+import Electrobun from 'electrobun/bun';
+Electrobun.events.on('close', (event) => {
+  const {id} = event.data;
+  if (win.id === id) {
+    console.log('my window closed');
+  } else {
+    console.log(`some other window with id ${id}` closed);
+  }
+});
+```
+### resize
+When a window's width or height changes. This events sends the x and y as part of the data because a window may be resized by dragging the top-left corner which would also reposition it.
+```
+// listen to a specific window's resize event
+win.on("resize", (event) => {
+  const { id, x, y, width, height } = event.data;
+  console.log("window resized", id, x, y, width, height);
+});
+// listen globally to window resize events
+import Electrobun from 'electrobun/bun';
+Electrobun.events.on("resize", (event) => {
+  const { id, x, y, width, height } = event.data;
+  console.log("window resized", id, x, y, width, height);
+});
+```
+### move
+When a window's width or height changes
+```
+// listen to a specific window's move event
+win.on("move", (event) => {
+  const { id, x, y } = event.data;
+  console.log("window moved", id, x, y);
+});
+// listen globally to window move events
+import Electrobun from 'electrobun/bun';
+Electrobun.eventson("move", (event) => {
+  const { id, x, y } = event.data;
+  console.log("window moved", id, x, y);
+});
+```

package/documentation/docs/apis/bun/ContextMenu.md ADDED Viewed

@@ -0,0 +1,50 @@
+> Show a context menu
+Typically you'd wire up a rightclick event with preventDefault in the browser context, rpc to bun, then create a native context menu from the bun context. But you can also create and show a context menu entirely from bun which will show at the mouse cursor's position globally positioned on screen even outside of your application window. Even if you have no windows open and another app is focused.
+```
+import {ContextMenu} from "electrobun/bun";
+// Show a context menu wherever the mouse cursor is on screen
+// after 5 seconds.
+setTimeout(() => {
+  ContextMenu.showContextMenu([
+    { 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",
+    },
+    {
+      label: "Custom menu disabled",
+      enabled: false,
+      action: "custom-action-2",
+      // todo: support a data property on all menus (app, tray, context)
+      data: {
+        some: "data",
+        that: "is serialized",
+        nested: { thing: 23 },
+      },
+    },
+    { type: "separator" },
+    { role: "cut" },
+    { role: "copy" },
+    { role: "paste" },
+    { role: "pasteAndMatchStyle" },
+    { role: "delete" },
+    { role: "selectAll" },
+  ]);
+}, 5000);
+Electrobun.events.on("context-menu-clicked", (e) => {
+  console.log("context event", e.data.action);
+});
+```

package/documentation/docs/apis/bun/Events.md ADDED Viewed

@@ -0,0 +1,50 @@
+> Event system in the main bun process
+## Event Propagation
+### Global Events
+Most events can be listened to directly on the thing firing them or globally.
+Global Event handlers fire first. Then handlers are fired in the sequence that they were registered in.
+```
+// listen to global event
+Electrobun.events.on("will-navigate", (e) => {
+    // handle
+});
+// listen to event on object
+win.webview.on('will-navigate', (e) => {
+    // handle
+})
+```
+### Event.response
+You can set a response on some events. Typically these are events initiated from zig which freeze the zig process while waiting for a reply from bun. An example of this is the BrowserView `will-navigate` where objc requires a synchronous response. By freezing the zig process and waiting for bun we allow bun to remain async while the events propagate.
+```
+Electrobun.events.on("will-navigate", (e) => {
+  console.log(
+    "example global will-navigate handler",
+    e.data.url,
+    e.data.webviewId
+  );
+  e.response = { allow: true };
+});
+```
+As the event propagates through different handlers you can both read and write from the e.response value.
+### Event.responseWasSet
+A property that indicates the response has been set to something which can be useful when an event propagates through multiple handlers instead of trying to infer from the response value whether it was set or not.
+### Event.clearResponse
+If a previous handler has set the e.response to something and you want to clear it, you can simply call `e.clearResponse()`
+### Event.data
+Each event will set different event data

package/documentation/docs/apis/bun/PATHS.md ADDED Viewed

@@ -0,0 +1,17 @@
+> Global paths exposed by Electrobun
+```
+import {PATHS} from "electrobun/bun";
+// in a macOS bundle this is where static bundled resources are kept.
+// Note: You shouldn't modify or write to the bundle at runtime as it will affect code signing
+// integrity.
+PATHS.RESOURCES_FOLDER
+// Typically you would use the views:// url scheme which maps to
+// RESOURCES_FOLDER + '/app/views/'
+// But there may be cases in bun where you want to read a file directly.
+PATHS.VIEWS_FOLDER
+```

package/documentation/docs/apis/bun/Tray.md ADDED Viewed

@@ -0,0 +1,115 @@
+> Create and manage system tray icon and menu.
+```
+import {Tray} from "electrobun/bun";
+const tray = new Tray({
+  title: "Example Tray Item (click to create menu)",
+  // This can be a views url or an absolute file path
+  image: `views://assets/electrobun-logo-32-template.png`,
+  template: true,
+  width: 32,
+  height: 32,
+});
+// map action names to clicked state
+// Note: This is just used for this example
+const menuState = {
+  "item-1": false,
+  "sub-item-1": false,
+  "sub-item-2": true,
+};
+const updateTrayMenu = () => {
+  tray.setMenu([
+    {
+      type: "normal",
+      label: `Toggle me`,
+      action: "item-1",
+      checked: menuState["item-1"],
+      tooltip: `I'm a tooltip`,
+      submenu: [
+        {
+          type: "normal",
+          label: "Click me to toggle sub-item 2",
+          tooltip: "i will also unhide sub-item-3",
+          action: "sub-item-1",
+        },
+        {
+          type: "divider",
+        },
+        {
+          type: "normal",
+          label: "Toggle sub-item-3's visibility",
+          action: "sub-item-2",
+          enabled: menuState["sub-item-1"],
+        },
+        {
+          type: "normal",
+          label: "I was hidden",
+          action: "sub-item-3",
+          hidden: menuState["sub-item-2"],
+        },
+      ],
+    },
+  ]);
+};
+// TODO: events should be typed
+tray.on("tray-clicked", (e) => {
+  const { id, action } = e.data as { id: number; action: string };
+  if (action === "") {
+    // main menu was clicked before we create a system tray menu for it.
+    updateTrayMenu();
+    tray.setTitle("Example Tray Item (click to open menu)");
+  } else {
+    // once there's a menu, we can toggle the state of the menu items
+    menuState[action] = !menuState[action];
+    updateTrayMenu();
+  }
+  // respond to left and right clicks on the tray icon/name
+  console.log("event listener for tray clicked", e.data.action);
+});
+```
+## Constructor Options
+### title
+This is the text that will appear in your system tray
+### image
+This is an optional url to an image to load. You can use the `views://` schema to access local bundled images.
+### template
+You can use a full-color image like a png but that image will just be shown as is. On MacOS you can create a template image and set the `template` property to true. A template image uses opacity to define a black and white image that adapts to your systems light/dark mode.
+### width and height
+Set the dimensions of the image used in the system tray
+## Methods
+### setMenu
+Call setMenu whenever you want to show the menu. Typically you would listen for the `tray-clicked` event, then show the menu and listen for the `tray-item-clicked`. Your app could also listen for keyboard shortcuts or show the system tray menu in response to something else.
+A common pattern is to create a function that dynamically generates the menu from some kind of state to implement things like checkbox toggles.
+### Menu Items
+See [Application Menu](/docs/apis/bun/ApplicationMenu) for more info on available properties for menu items.
+## Events
+### tray-clicked
+This is fired when the system tray item itself is clicked
+### tray-item-clicked
+This is fired when a system tray menu item or submenu item is clicked.