[positioner] handleIconState in JS (#1822)

* [positioner] handleIconState in JS

* update readme

* fix change file version

* fixes

---------

Co-authored-by: Lucas Nogueira <lucas@tauri.app>

Author: jbolda

.changes/positioner-v2-handleIconState.md

@@ -0,0 +1,6 @@
+---
+"positioner": patch
+"positioner-js": patch
+---
+
+`handleIconState` function for use in JavaScript event handlers. This allows one to update the TrayIcon state through JavaScript and fully create and handle the TrayIcon without requiring Rust (and the side-effect of creating a TrayIcon).

plugins/barcode-scanner/api-iife.js

@@ -58,6 +58,7 @@ fn main() {
         .plugin(tauri_plugin_positioner::init())
         // This is required to get tray-relative positions to work
         .setup(|app| {
+            // note that this will create a new TrayIcon
             TrayIconBuilder::new()
                 .on_tray_icon_event(|app, event| {
                     tauri_plugin_positioner::on_tray_event(app.app_handle(), &event);
@@ -70,6 +71,40 @@ fn main() {
 }
 ```
 
+Alternatively, you may handle the tray events through JavaScript. Register the plugin as previously noted.
+
+```rust
+fn main() {
+    tauri::Builder::default()
+        .plugin(tauri_plugin_positioner::init())
+        .run(tauri::generate_context!())
+        .expect("error while running tauri application");
+}
+```
+
+And in JavaScript, the `action` passed to the TrayIcon should include the handler.
+
+```javascript
+import {
+  moveWindow,
+  Position,
+  handleIconState,
+} from "@tauri-apps/plugin-positioner";
+
+const action = async (event: TrayIconEvent) => {
+  // add the handle in the action to update the state
+  await handleIconState(event);
+  if ("click" in event) {
+    const { click } = event;
+    // note this option requires enabling the `tray-icon`
+    //   feature in the Cargo.toml
+    await moveWindow(Position.TrayLeft);
+  }
+};
+
+const tray = await TrayIcon.new({ id: "main", action });
+```
+
 Afterwards all the plugin's APIs are available through the JavaScript guest bindings:
 
 ```javascript

plugins/positioner/README.md

@@ -4,6 +4,7 @@
 // SPDX-License-Identifier: MIT
 
 import { invoke } from '@tauri-apps/api/core'
+import type { TrayIconEvent } from '@tauri-apps/api/tray'
 
 /**
  * Well known window positions.
@@ -37,3 +38,14 @@ export async function moveWindow(to: Position): Promise<void> {
     position: to
   })
 }
+
+export async function handleIconState(event: TrayIconEvent): Promise<void> {
+  await invokeSetTrayIconState(event.rect)
+}
+
+async function invokeSetTrayIconState(rect: TrayIconEvent['rect']) {
+  await invoke('plugin:positioner|set_tray_icon_state', {
+    position: rect.position,
+    size: rect.size
+  })
+}

plugins/positioner/api-iife.js

@@ -0,0 +1,8 @@
+# Automatically generated - DO NOT EDIT!
+
+"$schema" = "../../schemas/schema.json"
+
+[[permission]]
+identifier = "allow-set-tray-icon-state"
+description = "Enables the set_tray_icon_state to handle events and set the TrayIcon state."
+commands.allow = ["set_tray_icon_state"]

plugins/positioner/guest-js/index.ts

@@ -3,6 +3,7 @@
 Allows the move_window command
 
 - `allow-move-window`
+- `set-tray-icon-state`
 
 ## Permission Table
 
@@ -36,6 +37,19 @@ Enables the move_window command without any pre-configured scope.
 
 Denies the move_window command without any pre-configured scope.
 
+</td>
+</tr>
+
+<tr>
+<td>
+
+`positioner:allow-set-tray-icon-state`
+
+</td>
+<td>
+
+Enables the set_tray_icon_state to handle events and set the TrayIcon state.
+
 </td>
 </tr>
 </table>

plugins/positioner/permissions/autogenerated/commands/set_tray_icon_state.toml

@@ -1,4 +1,4 @@
 "$schema" = "schemas/schema.json"
 [default]
 description = "Allows the move_window command"
-permissions = ["allow-move-window"]
+permissions = ["allow-move-window", "set-tray-icon-state"]

plugins/positioner/permissions/autogenerated/reference.md

@@ -304,6 +304,11 @@
           "type": "string",
           "const": "deny-move-window"
         },
+        {
+          "description": "Enables the set_tray_icon_state to handle events and set the TrayIcon state.",
+          "type": "string",
+          "const": "allow-set-tray-icon-state"
+        },
         {
           "description": "Allows the move_window command",
           "type": "string",

plugins/positioner/permissions/default.toml

@@ -63,10 +63,27 @@ async fn move_window<R: Runtime>(window: tauri::Window<R>, position: Position) -
     window.move_window(position)
 }
 
+#[cfg(feature = "tray-icon")]
+#[tauri::command]
+fn set_tray_icon_state<R: Runtime>(
+    app: AppHandle<R>,
+    position: PhysicalPosition<f64>,
+    size: PhysicalSize<f64>,
+) {
+    app.state::<Tray>()
+        .0
+        .lock()
+        .unwrap()
+        .replace((position, size));
+}
+
 /// The Tauri plugin that exposes [`WindowExt::move_window`] to the webview.
 pub fn init<R: Runtime>() -> TauriPlugin<R> {
-    let plugin =
-        plugin::Builder::new("positioner").invoke_handler(tauri::generate_handler![move_window]);
+    let plugin = plugin::Builder::new("positioner").invoke_handler(tauri::generate_handler![
+        move_window,
+        #[cfg(feature = "tray-icon")]
+        set_tray_icon_state
+    ]);
 
     #[cfg(feature = "tray-icon")]
     let plugin = plugin.setup(|app_handle, _api| {