@raycast/api 1.25.6 → 1.26.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raycast/api",
-  "version": "1.25.6",
+  "version": "1.26.3",
   "description": "Build extensions for Raycast with React and Node.js.",
   "author": "Raycast Technologies Ltd.",
   "homepage": "https://developers.raycast.com",
@@ -13,4 +13,4 @@
   "bin": {
     "ray": "./bin/ray"
   }
-}
+}

package/types/index.d.ts

@@ -225,30 +225,6 @@ export function clearClipboard(): Promise<void>;
  * @category Clipboard
  */
 export function pasteText(text: string): Promise<void>;
-/**
- * Gets the selected text of the frontmost application.
- *
- * @throws An error when no text is selected in the frontmost application.
- * @returns Returns a promise that resolves with the selected text.
- *
- * @example
- * ```typescript
- * 
- *
- * export default async () => {
- *   try {
- *     const selectedText = await getSelectedText();
- *     const transformedText = selectedText.toUpperCase();
- *     await pasteText(transformedText);
- *   } catch (error) {
- *     await showToast(ToastStyle.Failure, "Cannot transform text", String(error));
- *   }
- * };
- * ```
- *
- * @category Clipboard
- */
-export function getSelectedText(): Promise<string>;
 /**
  * A keyboard shortcut is defined by one or more modifier keys (command, control, etc.) and a single key equivalent (a character or special key).
  * See {@link KeyModifier} and {@link KeyEquivalent} for supported values.
@@ -2756,6 +2732,66 @@ export interface PreferenceValues {
  * @category Preferences
  */
 export function getPreferenceValues<Values extends PreferenceValues = PreferenceValues>(): Values;
+/**
+ * Gets the selected text of the frontmost application.
+ *
+ * @throws An error when no text is selected in the frontmost application.
+ * @returns Returns a promise that resolves with the selected text.
+ *
+ * @example
+ * ```typescript
+ * 
+ *
+ * export default async () => {
+ *   try {
+ *     const selectedText = await getSelectedText();
+ *     const transformedText = selectedText.toUpperCase();
+ *     await pasteText(transformedText);
+ *   } catch (error) {
+ *     await showToast(ToastStyle.Failure, "Cannot transform text", String(error));
+ *   }
+ * };
+ * ```
+ *
+ * @category Environment
+ */
+export function getSelectedText(): Promise<string>;
+/**
+ * Holds data about a File System item. Use the {@link getSelectedFinderItems} method to retrieve values.
+ *
+ * @category Environment
+ */
+export interface FileSystemItem {
+    /**
+     * The path to the item
+     */
+    path: string;
+}
+/**
+ * Gets the selected items from Finder.
+ *
+ * @throws An error when Finder is not the frontmost application.
+ * @returns Returns a promise that resolves with the selected file system items.
+ *
+ * @example
+ * ```typescript
+ * 
+ *
+ * export default async () => {
+ *   try {
+ *     const selectedItems = await getSelectedFinderItems();
+ *     if (selectedItems.length) {
+ *       await pasteText(selectedItems[0].path);
+ *     }
+ *   } catch (error) {
+ *     await showToast(ToastStyle.Failure, "Cannot copy file path", String(error));
+ *   }
+ * };
+ * ```
+ *
+ * @category Environment
+ */
+export function getSelectedFinderItems(): Promise<FileSystemItem[]>;
 
 
 /**
@@ -2897,6 +2933,149 @@ export function useNavigation(): Navigation;
  * @subcategory Rendering
  */
 export function render(nodeToRender: ReactNode): void;
+
+/**
+ * Creates and shows a confirmation Alert with the given options.
+ *
+ * @param options - The options used to create the Alert.
+ * @returns A promise that resolves to a boolean when the user takes an action.
+ * It will be `true` for the primary Action, `false` for the dismiss Action.
+ *
+ * @example
+ * ```typescript
+ * 
+ *
+ * export default async () => {
+ *   if (await confirmAlert({ title: "Are you sure?" })) {
+ *     // do something
+ *   }
+ * };
+ * ```
+ *
+ * @category User Interface
+ * @subcategory Alert
+ */
+export function confirmAlert(options: AlertOptions): Promise<boolean>;
+/**
+ * The options to create an {@link Alert}.
+ *
+ * @example
+ * ```typescript
+ * 
+ *
+ * export default async () => {
+ *   const options: AlertOptions = {
+ *     title: "Finished cooking",
+ *     message: "Delicious pasta for lunch",
+ *     primaryAction: {
+ *       title: 'Do something',
+ *       onAction: () => {
+ *         console.log("The alert action has been triggered")
+ *       }
+ *     }
+ *   };
+ *   const alert = new Alert(options);
+ *   await alert.show();
+ * };
+ * ```
+ *
+ * @category User Interface
+ * @subcategory Alert
+ */
+export interface AlertOptions {
+    /**
+     * The icon of an alert to illustrate the action. Displayed on the top.
+     */
+    icon?: ImageLike;
+    /**
+     * The title of an alert. Displayed below the icon.
+     */
+    title: string;
+    /**
+     * An additional message for an Alert. Useful to show more information, e.g. a confirmation message for a destructive action.
+     */
+    message?: string;
+    /**
+     * The primary Action the user can take.
+     */
+    primaryAction?: AlertActionOptions;
+    /**
+     * The Action to dismiss the alert. There usually shouldn't be any side effects when the user takes this action.
+     */
+    dismissAction?: AlertActionOptions;
+}
+/**
+ * The options to create an {@link Alert} Action.
+ *
+ * @category User Interface
+ * @subcategory Alert
+ */
+export interface AlertActionOptions {
+    /**
+     * The title of the action.
+     */
+    title: string;
+    /**
+     * The style of the action.
+     */
+    style?: AlertActionStyle;
+    /**
+     * A callback called when the action is triggered.
+     */
+    onAction?: () => void;
+}
+/**
+ * Defines the visual style of an Action of the Alert.
+ *
+ * @remarks
+ * Use {@link AlertActionStyle.Default} for confirmations of a positive action.
+ * Use {@link AlertActionStyle.Destructive} for confirmations of a destructive action (eg. deleting a file).
+ *
+ * @category User Interface
+ * @subcategory Alert
+ */
+export enum AlertActionStyle {
+    Default = "DEFAULT",
+    Cancel = "CANCEL",
+    Destructive = "DESTRUCTIVE"
+}
+/**
+ * Union type for the supported color types.
+ *
+ * @remark
+ * Besides the {@link Color}, you can use any of the following color formats:
+ * - HEX, e.g `#FF0000`
+ * - Short HEX, e.g. `#F00`
+ * - RGBA, e.g. `rgb(255, 0, 0)`
+ * - RGBA Percentage, e.g. `rgb(255, 0, 0, 1.0)`
+ * - HSL, e.g. `hsla(200, 20%, 33%, 0.2)`
+ * - Keywords, e.g. `red`
+ *
+ * Colors different to the built-in ones (see {@link Color}) will be dynamically adjusted to fit the contrast.
+ *
+ * @example
+ * ```typescript
+ * 
+ *
+ * export default function Command() {
+ *   return (
+ *     <List>
+ *       <List.Item title="Built-in color" icon={{ source: Icon.Circle, tintColor: Color.Red }} />
+ *       <List.Item title="HEX" icon={{ source: Icon.Circle, tintColor: "#FF0000" }} />
+ *       <List.Item title="Short HEX" icon={{ source: Icon.Circle, tintColor: "#F00" }} />
+ *       <List.Item title="RGBA" icon={{ source: Icon.Circle, tintColor: "rgb(255, 0, 0)" }} />
+ *       <List.Item title="RGBA Percentage" icon={{ source: Icon.Circle, tintColor: "rgb(255, 0, 0, 1.0)" }} />
+ *       <List.Item title="HSL" icon={{ source: Icon.Circle, tintColor: "hsla(200, 20%, 33%, 0.2)" }} />
+ *       <List.Item title="Keywords" icon={{ source: Icon.Circle, tintColor: "red" }} />
+ *     </List>
+ *   );
+ * };
+ * ```
+ *
+ * @category User Interface
+ * @subcategory Colors
+ */
+export type ColorLike = Color | DynamicColor | string;
 /**
  * The standard colors. Use this colors for consistency.
  *
@@ -2960,7 +3139,7 @@ export enum Color {
  * @category User Interface
  * @subcategory Colors
  */
-interface DynamicColor {
+export interface DynamicColor {
     /**
      * The color which is used in light theme.
      *
@@ -2988,44 +3167,6 @@ interface DynamicColor {
      */
     adjustContrast?: boolean;
 }
-/**
- * Union type for the supported color types.
- *
- * @remark
- * Besides the {@link Color}, you can use any of the following color formats:
- * - HEX, e.g `#FF0000`
- * - Short HEX, e.g. `#F00`
- * - RGBA, e.g. `rgb(255, 0, 0)`
- * - RGBA Percentage, e.g. `rgb(255, 0, 0, 1.0)`
- * - HSL, e.g. `hsla(200, 20%, 33%, 0.2)`
- * - Keywords, e.g. `red`
- *
- * Colors different to the built-in ones (see {@link Color}) will be dynamically adjusted to fit the contrast.
- *
- * @example
- * ```typescript
- * 
- *
- * export default function Command() {
- *   return (
- *     <List>
- *       <List.Item title="Built-in color" icon={{ source: Icon.Circle, tintColor: Color.Red }} />
- *       <List.Item title="HEX" icon={{ source: Icon.Circle, tintColor: "#FF0000" }} />
- *       <List.Item title="Short HEX" icon={{ source: Icon.Circle, tintColor: "#F00" }} />
- *       <List.Item title="RGBA" icon={{ source: Icon.Circle, tintColor: "rgb(255, 0, 0)" }} />
- *       <List.Item title="RGBA Percentage" icon={{ source: Icon.Circle, tintColor: "rgb(255, 0, 0, 1.0)" }} />
- *       <List.Item title="HSL" icon={{ source: Icon.Circle, tintColor: "hsla(200, 20%, 33%, 0.2)" }} />
- *       <List.Item title="Keywords" icon={{ source: Icon.Circle, tintColor: "red" }} />
- *     </List>
- *   );
- * };
- * ```
- *
- * @category User Interface
- * @subcategory Colors
- */
-export type ColorLike = DynamicColor | Color | string;
-export {};
 /**
  * List of built-in icons that can be used for actions or list items.
  *
@@ -3116,7 +3257,7 @@ export enum Icon {
  */
 export interface FileIcon {
     /**
-     * The path to a file or folder to get it's icon from.
+     * The path to a file or folder to get its icon from.
      */
     fileIcon: string;
 }
@@ -3252,6 +3393,7 @@ export enum ImageMask {
      */
     RoundedRectangle = "roundedRectangle"
 }
+
 /**
  * A Toast with a certain style, title, and message.
  *
@@ -3279,17 +3421,23 @@ export enum ImageMask {
  */
 export class Toast {
     private options;
-    constructor(options: ToastOptions);
+    private id;
+    private callbacks;
+    constructor(props: ToastOptions);
     get style(): ToastStyle;
     set style(style: ToastStyle);
     get title(): string;
     set title(title: string);
     get message(): string | undefined;
     set message(message: string | undefined);
+    get primaryAction(): ToastActionOptions | undefined;
+    set primaryAction(action: ToastActionOptions | undefined);
+    get secondaryAction(): ToastActionOptions | undefined;
+    set secondaryAction(action: ToastActionOptions | undefined);
     /**
      * Shows the Toast.
      *
-     * @returns A promise that resolves when toast is shown.
+     * @returns A promise that resolves when the toast is shown.
      */
     show(): Promise<void>;
     /**
@@ -3312,6 +3460,12 @@ export class Toast {
  *     style: ToastStyle.Success,
  *     title: "Finished cooking",
  *     message: "Delicious pasta for lunch",
+ *     primaryAction: {
+ *       title: 'Do something',
+ *       onAction: () => {
+ *         console.log("The toast action has been triggered")
+ *       }
+ *     }
  *   };
  *   const toast = new Toast(options);
  *   await toast.show();
@@ -3331,9 +3485,37 @@ export interface ToastOptions {
      */
     title: string;
     /**
-     * An additional message for the toast. Useful to show more information, e.g. an identifier of a newly create asset
+     * An additional message for the toast. Useful to show more information, e.g. an identifier of a newly created asset.
      */
     message?: string;
+    /**
+     * The primary Action the user can take when hovering on the Toast.
+     */
+    primaryAction?: ToastActionOptions;
+    /**
+     * The secondary Action the user can take when hovering on the Toast.
+     */
+    secondaryAction?: ToastActionOptions;
+}
+/**
+ * The options to create a {@link Toast} Action.
+ *
+ * @category User Interface
+ * @subcategory Toast
+ */
+export interface ToastActionOptions {
+    /**
+     * The title of the action.
+     */
+    title: string;
+    /**
+     * The keyboard shortcut for the action.
+     */
+    shortcut?: KeyboardShortcut;
+    /**
+     * A callback called when the action is triggered.
+     */
+    onAction: () => void;
 }
 /**
  * Defines the visual style of the Toast.
@@ -3352,7 +3534,7 @@ export enum ToastStyle {
     Animated = "ANIMATED"
 }
 /**
- * Creates and shows a Toast with the the given style, title, and message.
+ * Creates and shows a Toast with the given style, title, and message.
  *
  * @param style - The visual style of the Toast.
  * @param title - The title that will be displayed in the Toast.