@tauri-apps/plugin-dialog 2.0.0-alpha.5 → 2.0.0-beta.0

package/README.md

@@ -18,7 +18,7 @@ Install the Core plugin by adding the following to your `Cargo.toml` file:
 
 ```toml
 [dependencies]
-tauri-plugin-dialog = "2.0.0-alpha"
+tauri-plugin-dialog = "2.0.0-beta"
 # alternatively with Git:
 tauri-plugin-dialog = { git = "https://github.com/tauri-apps/plugins-workspace", branch = "v2" }
 ```

package/dist-js/index.d.ts

@@ -86,22 +86,60 @@ interface ConfirmDialogOptions {
     /** The label of the cancel button. */
     cancelLabel?: string;
 }
-declare function open(options?: OpenDialogOptions & {
-    multiple?: false;
-    directory?: false;
-}): Promise<null | FileResponse>;
-declare function open(options?: OpenDialogOptions & {
-    multiple?: true;
-    directory?: false;
-}): Promise<null | FileResponse[]>;
-declare function open(options?: OpenDialogOptions & {
-    multiple?: false;
-    directory?: true;
-}): Promise<null | string>;
-declare function open(options?: OpenDialogOptions & {
-    multiple?: true;
-    directory?: true;
-}): Promise<null | string[]>;
+type OpenDialogReturn<T extends OpenDialogOptions> = T["directory"] extends true ? T["multiple"] extends true ? string[] | null : string | null : T["multiple"] extends true ? FileResponse[] | null : FileResponse | null;
+/**
+ * Open a file/directory selection dialog.
+ *
+ * The selected paths are added to the filesystem and asset protocol scopes.
+ * When security is more important than the easy of use of this API,
+ * prefer writing a dedicated command instead.
+ *
+ * Note that the scope change is not persisted, so the values are cleared when the application is restarted.
+ * You can save it to the filesystem using [tauri-plugin-persisted-scope](https://github.com/tauri-apps/tauri-plugin-persisted-scope).
+ * @example
+ * ```typescript
+ * import { open } from '@tauri-apps/plugin-dialog';
+ * // Open a selection dialog for image files
+ * const selected = await open({
+ *   multiple: true,
+ *   filters: [{
+ *     name: 'Image',
+ *     extensions: ['png', 'jpeg']
+ *   }]
+ * });
+ * if (Array.isArray(selected)) {
+ *   // user selected multiple files
+ * } else if (selected === null) {
+ *   // user cancelled the selection
+ * } else {
+ *   // user selected a single file
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { open } from '@tauri-apps/plugin-dialog';
+ * import { appDir } from '@tauri-apps/api/path';
+ * // Open a selection dialog for directories
+ * const selected = await open({
+ *   directory: true,
+ *   multiple: true,
+ *   defaultPath: await appDir(),
+ * });
+ * if (Array.isArray(selected)) {
+ *   // user selected multiple directories
+ * } else if (selected === null) {
+ *   // user cancelled the selection
+ * } else {
+ *   // user selected a single directory
+ * }
+ * ```
+ *
+ * @returns A promise resolving to the selected path(s)
+ *
+ * @since 2.0.0
+ */
+declare function open<T extends OpenDialogOptions>(options?: T): Promise<OpenDialogReturn<T>>;
 /**
  * Open a file/directory save dialog.
  *
@@ -179,5 +217,5 @@ declare function ask(message: string, options?: string | ConfirmDialogOptions):
  * @since 2.0.0
  */
 declare function confirm(message: string, options?: string | ConfirmDialogOptions): Promise<boolean>;
-export type { DialogFilter, FileResponse, OpenDialogOptions, SaveDialogOptions, MessageDialogOptions, ConfirmDialogOptions, };
+export type { DialogFilter, FileResponse, OpenDialogOptions, OpenDialogReturn, SaveDialogOptions, MessageDialogOptions, ConfirmDialogOptions, };
 export { open, save, message, ask, confirm };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tauri-apps/plugin-dialog",
-  "version": "2.0.0-alpha.5",
+  "version": "2.0.0-beta.0",
   "license": "MIT or APACHE-2.0",
   "authors": [
     "Tauri Programme within The Commons Conservancy"
@@ -20,7 +20,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@tauri-apps/api": "2.0.0-alpha.13"
+    "@tauri-apps/api": "2.0.0-beta.0"
   },
   "scripts": {
     "build": "rollup -c"