@ayonli/jsext/types/dialog.d.ts

A JavaScript extension package for building strong and modern applications.

/**
 * Asynchronous dialog functions for both browsers and terminals.
 *
 * This includes `alert`, `confirm`, `prompt` and other non-standard dialogs.
 * @experimental
 * @module
 */
import progress from "./dialog/progress.ts";
import type { ProgressState, ProgressFunc, ProgressAbortHandler } from "./dialog/progress.ts";
import { type FileDialogOptions, type PickFileOptions, type SaveFileOptions, type DownloadFileOptions, openFile, openFiles, openDirectory, pickFile, pickFiles, pickDirectory, saveFile, downloadFile } from "./dialog/file.ts";
export type { FileDialogOptions, PickFileOptions, SaveFileOptions, DownloadFileOptions };
export { openFile, openFiles, openDirectory, pickFile, pickFiles, pickDirectory, saveFile, downloadFile, };
export { progress, ProgressState, ProgressFunc, ProgressAbortHandler };
/**
 * Options for dialog functions such as {@link alert}, {@link confirm} and
 * {@link prompt}.
 */
export interface DialogOptions {
    /**
     * By default, a GUI dialog is displayed in the browser, and text mode is
     * used in the terminal. Set this option to `true` will force the program
     * to always display a GUI dialog, even in the terminal.
     *
     * When in the terminal, the GUI dialog is rendered with the OS's native
     * dialog. If the dialog is failed to display, an error will be thrown.
     *
     * This option is only functional in `Windows`, `macOS` and `Linux`, it is
     * ignored in other platforms and the browser.
     */
    gui?: boolean;
}
/**
 * Displays a dialog with a message, and to wait until the user dismisses the
 * dialog.
 *
 * @example
 * ```ts
 * import { alert } from "@ayonli/jsext/dialog";
 *
 * await alert("Hello, world!");
 * ```
 */
export declare function alert(message: string, options?: DialogOptions): Promise<void>;
/**
 * Displays a dialog with a message, and to wait until the user either confirms
 * or cancels the dialog.
 *
 * @example
 * ```ts
 * import { confirm } from "@ayonli/jsext/dialog";
 *
 * if (await confirm("Are you sure?")) {
 *     console.log("Confirmed");
 * } else {
 *     console.log("Canceled");
 * }
 * ```
 */
export declare function confirm(message: string, options?: DialogOptions): Promise<boolean>;
/**
 * Options for the {@link prompt} function.
 */
export interface PromptOptions extends DialogOptions {
    /**
     * The default value of the input box.
     */
    defaultValue?: string | undefined;
    /**
     * The type of the input box. The default value is `text`, when `password`
     * is specified, the input will be masked.
     */
    type?: "text" | "password";
    /**
     * Terminal only, used when `type` is `password`. The default value is
     * `*`, use an empty string if you don't want to show any character.
     *
     * This option is ignored when `gui` is `true`.
     */
    mask?: string;
}
/**
 * Displays a dialog with a message prompting the user to input some text, and to
 * wait until the user either submits the text or cancels the dialog.
 *
 * @example
 * ```ts
 * import { prompt } from "@ayonli/jsext/dialog";
 *
 * const name = await prompt("What's your name?");
 *
 * if (name) {
 *     console.log(`Hello, ${name}!`);
 * }
 * ```
 *
 * @example
 * ```ts
 * // with default value
 * import { prompt } from "@ayonli/jsext/dialog";
 *
 * const name = await prompt("What's your name?", "John Doe");
 *
 * if (name) {
 *     console.log(`Hello, ${name}!`);
 * }
 * ```
 */
export declare function prompt(message: string, defaultValue?: string | undefined): Promise<string | null>;
/**
 * @example
 * ```ts
 * // input password
 * import { prompt } from "@ayonli/jsext/dialog";
 *
 * const password = await prompt("Enter your password:", { type: "password" });
 *
 * if (password) {
 *     console.log("Your password is:", password);
 * }
 * ```
 */
export declare function prompt(message: string, options?: PromptOptions): Promise<string | null>;