refactor(clipboard): refactor clipboard function arguments for better clarity about the needed type (#1218)

.changes/clipboard-refactor.md

@@ -0,0 +1,11 @@
+---
+"clipboard-manager": "patch"
+---
+
+Refactored the clipboard Rust APIs for more clarity and consistency:
+
+- Changed `Clipboard::write_text` to take a string type instead of an enum.
+- Changed `Clipboard::read_text` to return a string type instead of an enum.
+- Changed `Clipboard::write_html` to take 2 string arguments instead of an enum.
+- Changed `Clipboard::write_image` to take a reference to a `tauri::Image` instead of an enum.
+- Removed `ClipKind` and `ClipboardContents` enums.

plugins/clipboard-manager/api-iife.js

@@ -1 +1 @@
-if("__TAURI__"in window){var __TAURI_PLUGIN_CLIPBOARDMANAGER__=function(e){"use strict";var r;async function t(e,r={},t){return window.__TAURI_INTERNALS__.invoke(e,r,t)}"function"==typeof SuppressedError&&SuppressedError;class a{get rid(){return function(e,r,t,a){if("a"===t&&!a)throw new TypeError("Private accessor was defined without a getter");if("function"==typeof r?e!==r||!a:!r.has(e))throw new TypeError("Cannot read private member from an object whose class did not declare it");return"m"===t?a:"a"===t?a.call(e):a?a.value:r.get(e)}(this,r,"f")}constructor(e){r.set(this,void 0),function(e,r,t,a,n){if("m"===a)throw new TypeError("Private method is not writable");if("a"===a&&!n)throw new TypeError("Private accessor was defined without a setter");if("function"==typeof r?e!==r||!n:!r.has(e))throw new TypeError("Cannot write private member to an object whose class did not declare it");"a"===a?n.call(e,t):n?n.value=t:r.set(e,t)}(this,r,e,"f")}async close(){return t("plugin:resources|close",{rid:this.rid})}}r=new WeakMap;class n extends a{constructor(e){super(e)}static async new(e,r,a){return t("plugin:image|new",{rgba:i(e),width:r,height:a}).then((e=>new n(e)))}static async fromBytes(e){return t("plugin:image|from_bytes",{bytes:i(e)}).then((e=>new n(e)))}static async fromPath(e){return t("plugin:image|from_path",{path:e}).then((e=>new n(e)))}async rgba(){return t("plugin:image|rgba",{rid:this.rid}).then((e=>new Uint8Array(e)))}async size(){return t("plugin:image|size",{rid:this.rid})}}function i(e){return null==e?null:"string"==typeof e?e:e instanceof Uint8Array?Array.from(e):e instanceof ArrayBuffer?Array.from(new Uint8Array(e)):e instanceof n?e.rid:e}return e.clear=async function(){await t("plugin:clipboard-manager|clear")},e.readImage=async function(){return await t("plugin:clipboard-manager|read_image").then((e=>new n(e)))},e.readText=async function(){return(await t("plugin:clipboard-manager|read_text")).plainText.text},e.writeHtml=async function(e,r){await t("plugin:clipboard-manager|write_html",{data:{html:{html:e,altHtml:r}}})},e.writeImage=async function(e){await t("plugin:clipboard-manager|write_image",{data:{image:{image:i(e)}}})},e.writeText=async function(e,r){await t("plugin:clipboard-manager|write_text",{data:{plainText:{label:r?.label,text:e}}})},e}({});Object.defineProperty(window.__TAURI__,"clipboardManager",{value:__TAURI_PLUGIN_CLIPBOARDMANAGER__})}
+if("__TAURI__"in window){var __TAURI_PLUGIN_CLIPBOARDMANAGER__=function(e){"use strict";var r;async function t(e,r={},t){return window.__TAURI_INTERNALS__.invoke(e,r,t)}"function"==typeof SuppressedError&&SuppressedError;class n{get rid(){return function(e,r,t,n){if("a"===t&&!n)throw new TypeError("Private accessor was defined without a getter");if("function"==typeof r?e!==r||!n:!r.has(e))throw new TypeError("Cannot read private member from an object whose class did not declare it");return"m"===t?n:"a"===t?n.call(e):n?n.value:r.get(e)}(this,r,"f")}constructor(e){r.set(this,void 0),function(e,r,t,n,a){if("m"===n)throw new TypeError("Private method is not writable");if("a"===n&&!a)throw new TypeError("Private accessor was defined without a setter");if("function"==typeof r?e!==r||!a:!r.has(e))throw new TypeError("Cannot write private member to an object whose class did not declare it");"a"===n?a.call(e,t):a?a.value=t:r.set(e,t)}(this,r,e,"f")}async close(){return t("plugin:resources|close",{rid:this.rid})}}r=new WeakMap;class a extends n{constructor(e){super(e)}static async new(e,r,n){return t("plugin:image|new",{rgba:i(e),width:r,height:n}).then((e=>new a(e)))}static async fromBytes(e){return t("plugin:image|from_bytes",{bytes:i(e)}).then((e=>new a(e)))}static async fromPath(e){return t("plugin:image|from_path",{path:e}).then((e=>new a(e)))}async rgba(){return t("plugin:image|rgba",{rid:this.rid}).then((e=>new Uint8Array(e)))}async size(){return t("plugin:image|size",{rid:this.rid})}}function i(e){return null==e?null:"string"==typeof e?e:e instanceof Uint8Array?Array.from(e):e instanceof ArrayBuffer?Array.from(new Uint8Array(e)):e instanceof a?e.rid:e}return e.clear=async function(){await t("plugin:clipboard-manager|clear")},e.readImage=async function(){return await t("plugin:clipboard-manager|read_image").then((e=>new a(e)))},e.readText=async function(){return await t("plugin:clipboard-manager|read_text")},e.writeHtml=async function(e,r){await t("plugin:clipboard-manager|write_html",{html:e,altHtml:r})},e.writeImage=async function(e){await t("plugin:clipboard-manager|write_image",{image:i(e)})},e.writeText=async function(e,r){await t("plugin:clipboard-manager|write_text",{label:r?.label,text:e})},e}({});Object.defineProperty(window.__TAURI__,"clipboardManager",{value:__TAURI_PLUGIN_CLIPBOARDMANAGER__})}

plugins/clipboard-manager/guest-js/index.ts

@@ -11,8 +11,6 @@
 import { invoke } from "@tauri-apps/api/core";
 import { Image, transformImage } from "@tauri-apps/api/image";
 
-type ClipResponse = Record<"plainText", { text: string }>;
-
 /**
  * Writes plain text to the clipboard.
  * @example
@@ -31,12 +29,8 @@ async function writeText(
   opts?: { label?: string },
 ): Promise<void> {
   await invoke("plugin:clipboard-manager|write_text", {
-    data: {
-      plainText: {
-        label: opts?.label,
-        text,
-      },
-    },
+    label: opts?.label,
+    text,
   });
 }
 
@@ -50,26 +44,7 @@ async function writeText(
  * @since 2.0.0
  */
 async function readText(): Promise<string> {
-  const kind: ClipResponse = await invoke("plugin:clipboard-manager|read_text");
-  return kind.plainText.text;
-}
-
-/**
- * Gets the clipboard content as Uint8Array image.
- * @example
- * ```typescript
- * import { readImage } from '@tauri-apps/plugin-clipboard-manager';
- *
- * const clipboardImage = await readImage();
- * const blob = new Blob([clipboardImage.bytes], { type: 'image' })
- * const url = URL.createObjectURL(blob)
- * ```
- * @since 2.0.0
- */
-async function readImage(): Promise<Image> {
-  return await invoke<number>("plugin:clipboard-manager|read_image").then(
-    (rid) => new Image(rid),
-  );
+  return await invoke("plugin:clipboard-manager|read_text");
 }
 
 /**
@@ -94,14 +69,28 @@ async function writeImage(
   image: string | Image | Uint8Array | ArrayBuffer | number[],
 ): Promise<void> {
   await invoke("plugin:clipboard-manager|write_image", {
-    data: {
-      image: {
-        image: transformImage(image),
-      },
-    },
+    image: transformImage(image),
   });
 }
 
+/**
+ * Gets the clipboard content as Uint8Array image.
+ * @example
+ * ```typescript
+ * import { readImage } from '@tauri-apps/plugin-clipboard-manager';
+ *
+ * const clipboardImage = await readImage();
+ * const blob = new Blob([clipboardImage.bytes], { type: 'image' })
+ * const url = URL.createObjectURL(blob)
+ * ```
+ * @since 2.0.0
+ */
+async function readImage(): Promise<Image> {
+  return await invoke<number>("plugin:clipboard-manager|read_image").then(
+    (rid) => new Image(rid),
+  );
+}
+
 /**
  * * Writes HTML or fallbacks to write provided plain text to the clipboard.
  * @example
@@ -118,12 +107,8 @@ async function writeImage(
  */
 async function writeHtml(html: string, altHtml?: string): Promise<void> {
   await invoke("plugin:clipboard-manager|write_html", {
-    data: {
-      html: {
-        html,
-        altHtml,
-      },
-    },
+    html,
+    altHtml,
   });
 }
 

plugins/clipboard-manager/src/commands.rs

@@ -2,37 +2,54 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
 
-use tauri::{command, AppHandle, Manager, ResourceId, Runtime, State, Webview};
+use tauri::{command, image::JsImage, AppHandle, Manager, ResourceId, Runtime, State, Webview};
 
-use crate::{ClipKind, Clipboard, ClipboardContents, Result};
+use crate::{Clipboard, Result};
 
 #[command]
+#[cfg(desktop)]
 pub(crate) async fn write_text<R: Runtime>(
     _app: AppHandle<R>,
     clipboard: State<'_, Clipboard<R>>,
-    data: ClipKind,
+    text: &str,
+    #[allow(unused)] label: Option<String>,
 ) -> Result<()> {
-    clipboard.write_text(data)
+    clipboard.write_text(text)
 }
 
 #[command]
-pub(crate) async fn write_image<R: Runtime>(
-    webview: Webview<R>,
+#[cfg(not(desktop))]
+pub(crate) async fn write_text<R: Runtime>(
+    _app: AppHandle<R>,
     clipboard: State<'_, Clipboard<R>>,
-    data: ClipKind,
+    text: &str,
+    #[allow(unused)] label: Option<&str>,
 ) -> Result<()> {
-    let resources_table = webview.resources_table();
-    clipboard.write_image_inner(data, &resources_table)
+    match label {
+        Some(label) => clipboard.write_text_with_label(text, label),
+        None => clipboard.write_text(text),
+    }
 }
 
 #[command]
 pub(crate) async fn read_text<R: Runtime>(
     _app: AppHandle<R>,
     clipboard: State<'_, Clipboard<R>>,
-) -> Result<ClipboardContents> {
+) -> Result<String> {
     clipboard.read_text()
 }
 
+#[command]
+pub(crate) async fn write_image<R: Runtime>(
+    webview: Webview<R>,
+    clipboard: State<'_, Clipboard<R>>,
+    image: JsImage,
+) -> Result<()> {
+    let resources_table = webview.resources_table();
+    let image = image.into_img(&resources_table)?;
+    clipboard.write_image(&image)
+}
+
 #[command]
 pub(crate) async fn read_image<R: Runtime>(
     webview: Webview<R>,
@@ -48,9 +65,10 @@ pub(crate) async fn read_image<R: Runtime>(
 pub(crate) async fn write_html<R: Runtime>(
     _app: AppHandle<R>,
     clipboard: State<'_, Clipboard<R>>,
-    data: ClipKind,
+    html: &str,
+    alt_text: Option<&str>,
 ) -> Result<()> {
-    clipboard.write_html(data)
+    clipboard.write_html(html, alt_text)
 }
 
 #[command]

plugins/clipboard-manager/src/desktop.rs

@@ -5,9 +5,7 @@
 use arboard::ImageData;
 use image::ImageEncoder;
 use serde::de::DeserializeOwned;
-use tauri::{image::Image, plugin::PluginApi, AppHandle, Manager, ResourceTable, Runtime};
-
-use crate::models::*;
+use tauri::{image::Image, plugin::PluginApi, AppHandle, Runtime};
 
 use std::{borrow::Cow, sync::Mutex};
 
@@ -29,67 +27,50 @@ pub struct Clipboard<R: Runtime> {
 }
 
 impl<R: Runtime> Clipboard<R> {
-    pub fn write_text(&self, kind: ClipKind) -> crate::Result<()> {
-        match kind {
-            ClipKind::PlainText { text, .. } => match &self.clipboard {
-                Ok(clipboard) => clipboard.lock().unwrap().set_text(text).map_err(Into::into),
-                Err(e) => Err(crate::Error::Clipboard(e.to_string())),
-            },
-            _ => Err(crate::Error::Clipboard("Invalid clip kind".to_string())),
+    pub fn write_text<'a, T: Into<Cow<'a, str>>>(&self, text: T) -> crate::Result<()> {
+        match &self.clipboard {
+            Ok(clipboard) => clipboard.lock().unwrap().set_text(text).map_err(Into::into),
+            Err(e) => Err(crate::Error::Clipboard(e.to_string())),
         }
     }
 
-    pub(crate) fn write_image_inner(
-        &self,
-        kind: ClipKind,
-        resources_table: &ResourceTable,
-    ) -> crate::Result<()> {
-        match kind {
-            ClipKind::Image { image, .. } => match &self.clipboard {
-                Ok(clipboard) => {
-                    let image = image.into_img(resources_table)?;
-                    clipboard
-                        .lock()
-                        .unwrap()
-                        .set_image(ImageData {
-                            bytes: Cow::Borrowed(image.rgba()),
-                            width: image.width() as usize,
-                            height: image.height() as usize,
-                        })
-                        .map_err(Into::into)
-                }
-                Err(e) => Err(crate::Error::Clipboard(e.to_string())),
-            },
-            _ => Err(crate::Error::Clipboard("Invalid clip kind".to_string())),
+    pub fn write_image(&self, image: &Image<'_>) -> crate::Result<()> {
+        match &self.clipboard {
+            Ok(clipboard) => clipboard
+                .lock()
+                .unwrap()
+                .set_image(ImageData {
+                    bytes: Cow::Borrowed(image.rgba()),
+                    width: image.width() as usize,
+                    height: image.height() as usize,
+                })
+                .map_err(Into::into),
+            Err(e) => Err(crate::Error::Clipboard(e.to_string())),
         }
     }
 
-    pub fn write_image(&self, kind: ClipKind) -> crate::Result<()> {
-        let resources_table = self.app.resources_table();
-        self.write_image_inner(kind, &resources_table)
-    }
-
-    pub fn read_text(&self) -> crate::Result<ClipboardContents> {
+    pub fn read_text(&self) -> crate::Result<String> {
         match &self.clipboard {
             Ok(clipboard) => {
                 let text = clipboard.lock().unwrap().get_text()?;
-                Ok(ClipboardContents::PlainText { text })
+                Ok(text)
             }
             Err(e) => Err(crate::Error::Clipboard(e.to_string())),
         }
     }
 
-    pub fn write_html(&self, kind: ClipKind) -> crate::Result<()> {
-        match kind {
-            ClipKind::Html { html, alt_html, .. } => match &self.clipboard {
-                Ok(clipboard) => clipboard
-                    .lock()
-                    .unwrap()
-                    .set_html(html, alt_html)
-                    .map_err(Into::into),
-                Err(e) => Err(crate::Error::Clipboard(e.to_string())),
-            },
-            _ => Err(crate::Error::Clipboard("Invalid clip kind!".to_string())),
+    pub fn write_html<'a, T: Into<Cow<'a, str>>>(
+        &self,
+        html: T,
+        alt_text: Option<T>,
+    ) -> crate::Result<()> {
+        match &self.clipboard {
+            Ok(clipboard) => clipboard
+                .lock()
+                .unwrap()
+                .set_html(html, alt_text)
+                .map_err(Into::into),
+            Err(e) => Err(crate::Error::Clipboard(e.to_string())),
         }
     }
 

plugins/clipboard-manager/src/error.rs

@@ -13,7 +13,6 @@ pub enum Error {
     PluginInvoke(#[from] tauri::plugin::mobile::PluginInvokeError),
     #[error("{0}")]
     Clipboard(String),
-    #[cfg(desktop)]
     #[error(transparent)]
     Tauri(#[from] tauri::Error),
     #[cfg(desktop)]

plugins/clipboard-manager/src/lib.rs

@@ -16,8 +16,6 @@ use tauri::{
     Manager, Runtime,
 };
 
-pub use models::*;
-
 #[cfg(desktop)]
 mod desktop;
 #[cfg(mobile)]
@@ -25,7 +23,6 @@ mod mobile;
 
 mod commands;
 mod error;
-mod models;
 
 pub use error::{Error, Result};
 

plugins/clipboard-manager/src/mobile.rs

@@ -3,13 +3,14 @@
 // SPDX-License-Identifier: MIT
 
 use serde::de::DeserializeOwned;
+use serde::{Deserialize, Serialize};
 use tauri::{
     image::Image,
     plugin::{PluginApi, PluginHandle},
     AppHandle, Runtime,
 };
 
-use crate::models::*;
+use std::borrow::Cow;
 
 #[cfg(target_os = "android")]
 const PLUGIN_IDENTIFIER: &str = "app.tauri.clipboard";
@@ -33,28 +34,44 @@ pub fn init<R: Runtime, C: DeserializeOwned>(
 pub struct Clipboard<R: Runtime>(PluginHandle<R>);
 
 impl<R: Runtime> Clipboard<R> {
-    pub fn write_text(&self, kind: ClipKind) -> crate::Result<()> {
-        self.0.run_mobile_plugin("write", kind).map_err(Into::into)
+    pub fn write_text<'a, T: Into<Cow<'a, str>>>(&self, text: T) -> crate::Result<()> {
+        let text = text.into().to_string();
+        self.0
+            .run_mobile_plugin("write", ClipKind::PlainText { text, label: None })
+            .map_err(Into::into)
     }
 
-    pub(crate) fn write_image_inner(
+    pub fn write_text_with_label<'a, T: Into<Cow<'a, str>>>(
         &self,
-        kind: ClipKind,
-        resources_table: &tauri::ResourceTable,
+        text: T,
+        label: T,
     ) -> crate::Result<()> {
-        Err(crate::Error::Clipboard(
-            "Unsupported on this platform".to_string(),
-        ))
+        let text = text.into().to_string();
+        let label = label.into().to_string();
+        self.0
+            .run_mobile_plugin(
+                "write",
+                ClipKind::PlainText {
+                    text,
+                    label: Some(label),
+                },
+            )
+            .map_err(Into::into)
     }
 
-    pub fn write_image(&self, kind: ClipKind) -> crate::Result<()> {
+    pub fn write_image(&self, _image: &Image<'_>) -> crate::Result<()> {
         Err(crate::Error::Clipboard(
             "Unsupported on this platform".to_string(),
         ))
     }
 
-    pub fn read_text(&self) -> crate::Result<ClipboardContents> {
-        self.0.run_mobile_plugin("read", ()).map_err(Into::into)
+    pub fn read_text(&self) -> crate::Result<String> {
+        self.0
+            .run_mobile_plugin("read", ())
+            .map(|c| match c {
+                ClipboardContents::PlainText { text } => text,
+            })
+            .map_err(Into::into)
     }
 
     pub fn read_image(&self) -> crate::Result<Image<'_>> {
@@ -64,7 +81,11 @@ impl<R: Runtime> Clipboard<R> {
     }
 
     // Treat HTML as unsupported on mobile until tested
-    pub fn write_html(&self, _kind: ClipKind) -> crate::Result<()> {
+    pub fn write_html<'a, T: Into<Cow<'a, str>>>(
+        &self,
+        _html: T,
+        _alt_text: Option<T>,
+    ) -> crate::Result<()> {
         Err(crate::Error::Clipboard(
             "Unsupported on this platform".to_string(),
         ))
@@ -76,3 +97,15 @@ impl<R: Runtime> Clipboard<R> {
         ))
     }
 }
+
+#[derive(Debug, Deserialize, Serialize)]
+#[serde(rename_all = "camelCase")]
+enum ClipKind {
+    PlainText { label: Option<String>, text: String },
+}
+
+#[derive(Debug, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+enum ClipboardContents {
+    PlainText { text: String },
+}

plugins/clipboard-manager/src/models.rs

@@ -1,36 +0,0 @@
-// Copyright 2019-2023 Tauri Programme within The Commons Conservancy
-// SPDX-License-Identifier: Apache-2.0
-// SPDX-License-Identifier: MIT
-
-use serde::{Deserialize, Serialize};
-
-#[derive(Deserialize)]
-#[cfg_attr(mobile, derive(Serialize))]
-#[serde(rename_all = "camelCase")]
-pub enum ClipKind {
-    PlainText {
-        label: Option<String>,
-        text: String,
-    },
-    #[cfg(desktop)]
-    Image {
-        image: tauri::image::JsImage,
-    },
-    Html {
-        html: String,
-        alt_html: Option<String>,
-    },
-}
-
-#[derive(Debug, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub enum ClipboardContents {
-    PlainText {
-        text: String,
-    },
-    Image {
-        bytes: Vec<u8>,
-        width: usize,
-        height: usize,
-    },
-}