@tauri-apps/plugin-dialog 2.4.2 → 2.6.0

package/README.md

@@ -31,6 +31,24 @@ tauri-plugin-dialog = "2.0.0"
 tauri-plugin-dialog = { git = "https://github.com/tauri-apps/plugins-workspace", branch = "v2" }
 ```
 
+### Linux XDG Desktop Portal Support
+
+By default, this plugin uses gtk to show dialogs, however since `v2.5.0` you can switch to using [XDG Desktop Portal](https://flatpak.github.io/xdg-desktop-portal/) by adding the following to your `Cargo.toml` file:
+
+```toml
+[dependencies]
+tauri-plugin-dialog = { version = "2.5.0", default-features = false, features = ["xdg-portal"] }
+# alternatively with Git:
+tauri-plugin-dialog = { git = "https://github.com/tauri-apps/plugins-workspace", branch = "v2", default-features = false, features = ["xdg-portal"] }
+
+```
+
+Do note if you use the `xdg-portal` feature, you need to ensure that [`zenity`](https://gitlab.gnome.org/GNOME/zenity) and an [XDG Desktop Portal backend](https://flatpak.github.io/xdg-desktop-portal#using-portals) is installed with your program.
+
+For more information, see [XDG Desktop Portal documentation](https://flatpak.github.io/xdg-desktop-portal/) and [`rfd` documentation](https://docs.rs/rfd/latest/rfd#xdg-desktop-portal-backend).
+
+### JavaScript
+
 You can install the JavaScript Guest bindings using your preferred JavaScript package manager:
 
 ```sh

package/dist-js/index.d.ts

@@ -8,6 +8,16 @@ interface DialogFilter {
     name: string;
     /**
      * Extensions to filter, without a `.` prefix.
+     *
+     * **Note:** Mobile platforms have different APIs for filtering that may not support extensions.
+     * iOS: Extensions are supported in the document picker, but not in the media picker.
+     * Android: Extensions are not supported.
+     *
+     * For these platforms, MIME types are the primary way to filter files, as opposed to extensions.
+     * This means the string values here labeled as `extensions` may also be a MIME type.
+     * This property name of `extensions` is being kept for backwards compatibility, but this may be revisited to
+     * specify the difference between extension or MIME type filtering.
+     *
      * @example
      * ```typescript
      * extensions: ['svg', 'png']
@@ -23,7 +33,14 @@ interface DialogFilter {
 interface OpenDialogOptions {
     /** The title of the dialog window (desktop only). */
     title?: string;
-    /** The filters of the dialog. */
+    /**
+     * The filters of the dialog.
+     * On mobile platforms, if either:
+     * A) the {@linkcode pickerMode} is set to `media`, `image`, or `video`
+     * -- or --
+     * B) the filters include **only** either image or video mime types, the media picker will be displayed.
+     * Otherwise, the document picker will be displayed.
+     */
     filters?: DialogFilter[];
     /**
      * Initial directory or file path.
@@ -45,6 +62,38 @@ interface OpenDialogOptions {
     recursive?: boolean;
     /** Whether to allow creating directories in the dialog. Enabled by default. **macOS Only** */
     canCreateDirectories?: boolean;
+    /**
+     * The preferred mode of the dialog.
+     * This is meant for mobile platforms (iOS and Android) which have distinct file and media pickers.
+     * If not provided, the dialog will automatically choose the best mode based on the MIME types or extensions of the {@linkcode filters}.
+     * On desktop, this option is ignored.
+     */
+    pickerMode?: PickerMode;
+    /**
+     * The file access mode of the dialog.
+     * If not provided, `copy` is used, which matches the behavior of the {@linkcode open} method before the introduction of this option.
+     *
+     * **Usage**
+     * If a file is opened with {@linkcode fileAccessMode: 'copy'}, it will be copied to the app's sandbox.
+     * This means the file can be read, edited, deleted, copied, or any other operation without any issues, since the file
+     * now belongs to the app.
+     * This also means that the caller has responsibility of deleting the file if this file is not meant to be retained
+     * in the app sandbox.
+     *
+     * If a file is opened with {@linkcode fileAccessMode: 'scoped'}, the file will remain in its original location
+     * and security-scoped access will be automatically managed by the system.
+     *
+     * **Note**
+     * This is specifically meant for document pickers on iOS or MacOS, in conjunction with [security scoped resources](https://developer.apple.com/documentation/foundation/nsurl/startaccessingsecurityscopedresource()).
+     *
+     * Why only document pickers, and not image or video pickers?
+     * The image and video pickers on iOS behave differently from the document pickers, and return [NSItemProvider](https://developer.apple.com/documentation/foundation/nsitemprovider) objects instead of file URLs.
+     * These are meant to be ephemeral (only available within the callback of the picker), and are not accessible outside of the callback.
+     * So for image and video pickers, the only way to access the file is to copy it to the app's sandbox, and this is the URL that is returned from this API.
+     * This means there is no provision for using `scoped` mode with image or video pickers.
+     * If an image or video picker is used, `copy` is always used.
+     */
+    fileAccessMode?: FileAccessMode;
 }
 /**
  * Options for the save dialog.
@@ -68,6 +117,24 @@ interface SaveDialogOptions {
     /** Whether to allow creating directories in the dialog. Enabled by default. **macOS Only** */
     canCreateDirectories?: boolean;
 }
+/**
+ * The preferred mode of the dialog.
+ * This is meant for mobile platforms (iOS and Android) which have distinct file and media pickers.
+ * On desktop, this option is ignored.
+ * If not provided, the dialog will automatically choose the best mode based on the MIME types or extensions of the {@linkcode filters}.
+ *
+ * **Note:** This option is only supported on iOS 14 and above. This parameter is ignored on iOS 13 and below.
+ */
+export type PickerMode = 'document' | 'media' | 'image' | 'video';
+/**
+ * The file access mode of the dialog.
+ *
+ * - `copy`: copy/move the picked file to the app sandbox; no scoped access required.
+ * - `scoped`: keep file in place; security-scoped access is automatically managed.
+ *
+ * **Note:** This option is only supported on iOS 14 and above. This parameter is ignored on iOS 13 and below.
+ */
+export type FileAccessMode = 'copy' | 'scoped';
 /**
  * Default buttons for a message dialog.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tauri-apps/plugin-dialog",
-  "version": "2.4.2",
+  "version": "2.6.0",
   "license": "MIT OR Apache-2.0",
   "authors": [
     "Tauri Programme within The Commons Conservancy"