@raycast/api 1.55.1 → 1.56.0

package/api.d.ts

@@ -455,8 +455,6 @@ declare enum ActionStyle {
     Destructive = "destructive"
 }
 
-export declare function addBreadcrumb(breadcrumb: Breadcrumb): void;
-
 export declare namespace AI {
     /**
      * Returns a prompt completion.
@@ -651,15 +649,6 @@ export declare interface ArgumentsLaunchProps {
     arguments?: Arguments;
 }
 
-declare type Breadcrumb = {
-    level?: BreadcrumbLevel;
-    category?: string;
-    message?: string;
-    data?: Data;
-};
-
-declare type BreadcrumbLevel = "fatal" | "error" | "warning" | "log" | "info" | "debug";
-
 /**
  * Caching abstraction that stores data on disk and supports LRU (least recently used) access.
  * Since extensions can only consume up to a max. heap memory size, the cache only maintains a lightweight index in memory
@@ -796,11 +785,14 @@ export declare const clearLocalStorage: typeof LocalStorage.clear;
 /**
  * Clear the text in the search bar.
  *
- * @param options - Can be used to force scrolling to the top. Defaults to scrolling to the top after the
- * the search bar was cleared.
+ * @param options - Can be used to control the behaviour after the search bar is cleared.
  * @returns A Promise that resolves when the search bar is cleared.
  */
 export declare function clearSearchBar(options?: {
+    /**
+     * Can be used to force scrolling to the top. Defaults to scrolling to the top after the
+     * the search bar was cleared.
+     */
     forceScrollToTop?: boolean;
 }): Promise<void>;
 
@@ -870,6 +862,7 @@ export declare namespace Clipboard {
     /**
      * Reads the clipboard content as plain text, file name, or HTML.
      *
+     * @param options - Options for the read operation.
      * @returns A Promise that resolves when the clipboard content was read.
      *
      * @example
@@ -884,10 +877,18 @@ export declare namespace Clipboard {
      * };
      * ```
      */
-    export function read(): Promise<ReadContent>;
+    export function read(options?: {
+        /**
+         * Specify an offset to access the Clipboard History. Minimum value is 0, maximum value is 5.
+         *
+         * @defaultValue `0`
+         */
+        offset?: number;
+    }): Promise<ReadContent>;
     /**
      * Reads the clipboard as plain text.
      *
+     * @param options - Options for the readText operation.
      * @returns A promise that resolves when the clipboard content was read as plain text.
      *
      * @example
@@ -900,7 +901,14 @@ export declare namespace Clipboard {
      * };
      * ```
      */
-    export function readText(): Promise<string | undefined>;
+    export function readText(options?: {
+        /**
+         * Specify an offset to access the Clipboard History. Minimum value is 0, maximum value is 5.
+         *
+         * @defaultValue `0`
+         */
+        offset?: number;
+    }): Promise<string | undefined>;
     /**
      * Type of the content read from the {@link Clipboard}.
      *
@@ -967,9 +975,7 @@ export declare namespace Clipboard {
 /**
  * Closes the main Raycast window.
  *
- * @param options - A parameter object with the properties:
- * `clearRootSearch`: clears the text in the root search bar and scrolls to the top; default is `false`
- * `popToRootType`: defines the pop to root behavior ({@link PopToRootType}); the default is to to respect the user's "Pop to Root Search" preference in Raycast
+ * @param options - Can be used to control the behaviour after closing the main window.
  * @returns A Promise that resolves when the main window is closed.
  *
  * @example
@@ -984,7 +990,15 @@ export declare namespace Clipboard {
  * ```
  */
 export declare function closeMainWindow(options?: {
+    /**
+     * Clears the text in the root search bar and scrolls to the top
+     *
+     * @defaultValue `false`
+     */
     clearRootSearch?: boolean;
+    /**
+     * Defines the pop to root behavior ({@link PopToRootType}); the default is to to respect the user's "Pop to Root Search" preference in Raycast
+     */
     popToRootType?: PopToRootType;
 }): Promise<void>;
 
@@ -1509,7 +1523,7 @@ declare interface CopyToClipboardProps {
     icon?: Image.ImageLike;
     /**
      * Indicates whether the content should be copied to the clipboard temporarily or not.
-     * @defaultValue false
+     * @defaultValue `false`
      */
     transient?: boolean;
     /**
@@ -1570,12 +1584,6 @@ declare interface CreateSnippetProps {
     shortcut?: Keyboard.Shortcut;
 }
 
-declare type Data = {
-    function: string;
-} | {
-    title: string;
-} | Record<string, string>;
-
 /**
  * See {@link Form.DatePicker}
  */
@@ -4216,6 +4224,23 @@ export declare namespace Grid {
         }
     }
     export namespace Item {
+        /**
+         * An interface describing an accessory item in a {@link Grid.Item}
+         *
+         * @example
+         * ```typescript
+         * import { Grid } from "@raycast/api";
+         *
+         * export default function Command() {
+         *   return (
+         *     <Grid>
+         *       <Grid.Item title="Item" accessory={{ icon: Icon.Hammer }} />
+         *     </Grid>
+         *   );
+         * }
+         * ```
+         */
+        export type Accessory = ItemAccessory_2;
         /**
          * Props of the {@link Grid.Item} React component.
          */
@@ -4422,7 +4447,7 @@ declare interface GridProps extends ActionsInterface, NavigationChildInterface,
     /**
      * Column count for the grid's sections. Minimum value is 1, maximum value is 8.
      *
-     * @defaultValue 5
+     * @defaultValue `5`
      */
     columns?: number;
     /**
@@ -5205,6 +5230,19 @@ declare type ItemAccessory = ({
     tooltip?: string | undefined | null;
 };
 
+declare type ItemAccessory_2 = {
+    /**
+     * An optional {@link Image.ImageLike} that will be used as the icon.
+     * @remarks
+     * An image will be shown in front of the text if {@link List.Item.Accessory.text} is specified.
+     */
+    icon?: Image.ImageLike | undefined | null;
+    /**
+     * An optional tooltip shown when the accessory is hovered.
+     */
+    tooltip?: string | undefined | null;
+};
+
 /**
  * An interface describing Action events in callbacks
  *
@@ -5351,6 +5389,10 @@ declare interface ItemProps_2 extends ActionsInterface {
      * When filtering the list in Raycast through the search bar, the keywords will be searched in addition to the title.
      */
     keywords?: string[];
+    /**
+     * An optional {@link Grid.Item.Accessory} item displayed underneath a {@link Grid.Item}.
+     */
+    accessory?: ItemAccessory_2;
     /**
      * Optional information to preview files with Quick Look. Toggle the preview ith {@link Action.ToggleQuickLook}.
      *
@@ -5443,6 +5485,100 @@ export declare namespace Keyboard {
          */
         key: KeyEquivalent;
     }
+    export namespace Shortcut {
+        /**
+         * Shortcuts that are commonly used throughout Raycast. Use them to provide a consistent experience.
+         *
+         * @example
+         * ```typescript
+         * import { List, Action, ActionPanel, Keyboard } from "@raycast/api";
+         * import { useState } from "react";
+         *
+         * type Item = { id: string; title: string; done: boolean };
+         *
+         * let currentId = 0;
+         * function generateId() {
+         *   currentId++;
+         *   return `${currentId}`;
+         * }
+         *
+         * export default function Reminders() {
+         *   const [items, setItems] = useState<Item[]>([{ id: generateId(), title: "Do the laudry", done: false }]);
+         *
+         *   return (
+         *     <List>
+         *       {items.map((item) => (
+         *         <List.Item
+         *           key={item.id}
+         *           icon={item.done ? "checked.png" : "unchecked.png"}
+         *           title={item.title}
+         *           actions={
+         *             <ActionPanel>
+         *               <Action
+         *                 title={item.done ? "Uncheck" : "Check"}
+         *                 onAction={() =>
+         *                   setItems((previousState) =>
+         *                     previousState.map((previousStateItem) =>
+         *                       previousStateItem.id === item.id ? { ...item, done: !previousStateItem.done } : item
+         *                     )
+         *                   )
+         *                 }
+         *               />
+         *               <Action
+         *                 title="New Item"
+         *                 shortcut={Keyboard.Shortcut.Common.New}
+         *                 onAction={() =>
+         *                   setItems((previousState) => [{ id: generateId(), title: "New Item", done: false }, ...previousState])
+         *                 }
+         *               />
+         *             </ActionPanel>
+         *           }
+         *         />
+         *       ))}
+         *     </List>
+         *   );
+         * }
+         * ```
+         */
+        const Common: {
+            Copy: Shortcut;
+            CopyDeeplink: Shortcut;
+            CopyName: Shortcut;
+            CopyPath: Shortcut;
+            Duplicate: Shortcut;
+            Edit: Shortcut;
+            MoveDown: Shortcut;
+            MoveUp: Shortcut;
+            New: Shortcut;
+            Open: Shortcut;
+            OpenWith: Shortcut;
+            Pin: Shortcut;
+            Refresh: Shortcut;
+            Remove: Shortcut;
+            RemoveAll: Shortcut;
+            ToggleQuickLook: Shortcut;
+        };
+        /**
+         * @internal
+         */
+        const Reserved: {
+            CloseWindow: Shortcut;
+            Delete: Shortcut;
+            DeleteForward: Shortcut;
+            DeleteLineBackward: Shortcut;
+            DeleteWordBackward: Shortcut;
+            GoBack: Shortcut;
+            OpenActionPanel: Shortcut;
+            OpenPreferences: Shortcut;
+            OpenSearchBarDropdown: Shortcut;
+            OpenSearchBarLink: Shortcut;
+            PrimaryAction: Shortcut;
+            Quit: Shortcut;
+            ReturnToRoot: Shortcut;
+            SecondaryAction: Shortcut;
+            SelectAll: Shortcut;
+        };
+    }
     /**
      * Modifier of a {@link Keyboard.Shortcut}
      */
@@ -6937,7 +7073,7 @@ declare interface PickDateProps {
 /**
  * Pops the navigation stack back to root search.
  *
- * @param options - Can be used to clear the search bar. Defaults to clearing the search bar after popped to root.
+ * @param options - Can be used to control the behaviour after going back to the root search.
  * @returns A Promise that resolves when Raycast popped to root.
  *
  * @example
@@ -7258,7 +7394,7 @@ declare interface SectionProps_3 {
     /**
      * Column count for the section. Minimum value is 1, maximum value is 8.
      *
-     * @defaultValue 5
+     * @defaultValue `5`
      */
     columns?: number;
     /**
@@ -7322,6 +7458,7 @@ export declare const setLocalStorageItem: typeof LocalStorage.setItem;
  * A HUD will automatically hide the main window and show a compact message at the bottom of the screen.
  *
  * @param title - The title that will be displayed in the HUD.
+ * @param options - Can be used to control the behaviour after closing the main window.
  * @returns A Promise that resolves when the HUD is shown.
  *
  * @example
@@ -7333,7 +7470,18 @@ export declare const setLocalStorageItem: typeof LocalStorage.setItem;
  * };
  * ```
  */
-export declare function showHUD(title: string): Promise<void>;
+export declare function showHUD(title: string, options?: {
+    /**
+     * Clears the text in the root search bar and scrolls to the top
+     *
+     * @defaultValue `false`
+     */
+    clearRootSearch?: boolean;
+    /**
+     * Defines the pop to root behavior ({@link PopToRootType}); the default is to to respect the user's "Pop to Root Search" preference in Raycast
+     */
+    popToRootType?: PopToRootType;
+}): Promise<void>;
 
 /**
  * See {@link Action.ShowInFinder.Props}
@@ -7617,13 +7765,13 @@ declare const TagListItem: FunctionComponent<TagListItemProps>;
 
 declare interface TagListItemProps {
     /**
-     * An optional icon in front of the text of the tag.
+     * The optional icon tag icon. Required if the tag has no text.
      */
     icon?: Image.ImageLike | undefined | null;
     /**
-     * The text of the tag.
+     * The optional tag text. Required if the tag has no icon.
      */
-    text: string;
+    text?: string;
     /**
      * Changes the text color to the provided color and sets a transparent background with the same color.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raycast/api",
-  "version": "1.55.1",
+  "version": "1.56.0",
   "description": "Build extensions for Raycast with React and Node.js.",
   "author": "Raycast Technologies Ltd.",
   "homepage": "https://developers.raycast.com",

package/types/index.d.ts

@@ -433,8 +433,6 @@ declare enum ActionStyle {
     Destructive = "destructive"
 }
 
-export declare function addBreadcrumb(breadcrumb: Breadcrumb): void;
-
 export declare namespace AI {
     /**
      * Returns a prompt completion.
@@ -629,15 +627,6 @@ export declare interface ArgumentsLaunchProps {
     arguments?: Arguments;
 }
 
-declare type Breadcrumb = {
-    level?: BreadcrumbLevel;
-    category?: string;
-    message?: string;
-    data?: Data;
-};
-
-declare type BreadcrumbLevel = "fatal" | "error" | "warning" | "log" | "info" | "debug";
-
 /**
  * Caching abstraction that stores data on disk and supports LRU (least recently used) access.
  * Since extensions can only consume up to a max. heap memory size, the cache only maintains a lightweight index in memory
@@ -774,11 +763,14 @@ export declare const clearLocalStorage: typeof LocalStorage.clear;
 /**
  * Clear the text in the search bar.
  *
- * @param options - Can be used to force scrolling to the top. Defaults to scrolling to the top after the
- * the search bar was cleared.
+ * @param options - Can be used to control the behaviour after the search bar is cleared.
  * @returns A Promise that resolves when the search bar is cleared.
  */
 export declare function clearSearchBar(options?: {
+    /**
+     * Can be used to force scrolling to the top. Defaults to scrolling to the top after the
+     * the search bar was cleared.
+     */
     forceScrollToTop?: boolean;
 }): Promise<void>;
 
@@ -848,6 +840,7 @@ export declare namespace Clipboard {
     /**
      * Reads the clipboard content as plain text, file name, or HTML.
      *
+     * @param options - Options for the read operation.
      * @returns A Promise that resolves when the clipboard content was read.
      *
      * @example
@@ -862,10 +855,18 @@ export declare namespace Clipboard {
      * };
      * ```
      */
-    export function read(): Promise<ReadContent>;
+    export function read(options?: {
+        /**
+         * Specify an offset to access the Clipboard History. Minimum value is 0, maximum value is 5.
+         *
+         * @defaultValue `0`
+         */
+        offset?: number;
+    }): Promise<ReadContent>;
     /**
      * Reads the clipboard as plain text.
      *
+     * @param options - Options for the readText operation.
      * @returns A promise that resolves when the clipboard content was read as plain text.
      *
      * @example
@@ -878,7 +879,14 @@ export declare namespace Clipboard {
      * };
      * ```
      */
-    export function readText(): Promise<string | undefined>;
+    export function readText(options?: {
+        /**
+         * Specify an offset to access the Clipboard History. Minimum value is 0, maximum value is 5.
+         *
+         * @defaultValue `0`
+         */
+        offset?: number;
+    }): Promise<string | undefined>;
     /**
      * Type of the content read from the {@link Clipboard}.
      *
@@ -945,9 +953,7 @@ export declare namespace Clipboard {
 /**
  * Closes the main Raycast window.
  *
- * @param options - A parameter object with the properties:
- * `clearRootSearch`: clears the text in the root search bar and scrolls to the top; default is `false`
- * `popToRootType`: defines the pop to root behavior ({@link PopToRootType}); the default is to to respect the user's "Pop to Root Search" preference in Raycast
+ * @param options - Can be used to control the behaviour after closing the main window.
  * @returns A Promise that resolves when the main window is closed.
  *
  * @example
@@ -962,7 +968,15 @@ export declare namespace Clipboard {
  * ```
  */
 export declare function closeMainWindow(options?: {
+    /**
+     * Clears the text in the root search bar and scrolls to the top
+     *
+     * @defaultValue `false`
+     */
     clearRootSearch?: boolean;
+    /**
+     * Defines the pop to root behavior ({@link PopToRootType}); the default is to to respect the user's "Pop to Root Search" preference in Raycast
+     */
     popToRootType?: PopToRootType;
 }): Promise<void>;
 
@@ -1487,7 +1501,7 @@ declare interface CopyToClipboardProps {
     icon?: Image.ImageLike;
     /**
      * Indicates whether the content should be copied to the clipboard temporarily or not.
-     * @defaultValue false
+     * @defaultValue `false`
      */
     transient?: boolean;
     /**
@@ -1548,12 +1562,6 @@ declare interface CreateSnippetProps {
     shortcut?: Keyboard.Shortcut;
 }
 
-declare type Data = {
-    function: string;
-} | {
-    title: string;
-} | Record<string, string>;
-
 /**
  * See {@link Form.DatePicker}
  */
@@ -4194,6 +4202,23 @@ export declare namespace Grid {
         }
     }
     export namespace Item {
+        /**
+         * An interface describing an accessory item in a {@link Grid.Item}
+         *
+         * @example
+         * ```typescript
+         * import { Grid } from "@raycast/api";
+         *
+         * export default function Command() {
+         *   return (
+         *     <Grid>
+         *       <Grid.Item title="Item" accessory={{ icon: Icon.Hammer }} />
+         *     </Grid>
+         *   );
+         * }
+         * ```
+         */
+        export type Accessory = ItemAccessory_2;
         /**
          * Props of the {@link Grid.Item} React component.
          */
@@ -4400,7 +4425,7 @@ declare interface GridProps extends ActionsInterface, NavigationChildInterface,
     /**
      * Column count for the grid's sections. Minimum value is 1, maximum value is 8.
      *
-     * @defaultValue 5
+     * @defaultValue `5`
      */
     columns?: number;
     /**
@@ -5183,6 +5208,19 @@ declare type ItemAccessory = ({
     tooltip?: string | undefined | null;
 };
 
+declare type ItemAccessory_2 = {
+    /**
+     * An optional {@link Image.ImageLike} that will be used as the icon.
+     * @remarks
+     * An image will be shown in front of the text if {@link List.Item.Accessory.text} is specified.
+     */
+    icon?: Image.ImageLike | undefined | null;
+    /**
+     * An optional tooltip shown when the accessory is hovered.
+     */
+    tooltip?: string | undefined | null;
+};
+
 /**
  * An interface describing Action events in callbacks
  *
@@ -5329,6 +5367,10 @@ declare interface ItemProps_2 extends ActionsInterface {
      * When filtering the list in Raycast through the search bar, the keywords will be searched in addition to the title.
      */
     keywords?: string[];
+    /**
+     * An optional {@link Grid.Item.Accessory} item displayed underneath a {@link Grid.Item}.
+     */
+    accessory?: ItemAccessory_2;
     /**
      * Optional information to preview files with Quick Look. Toggle the preview ith {@link Action.ToggleQuickLook}.
      *
@@ -5421,6 +5463,81 @@ export declare namespace Keyboard {
          */
         key: KeyEquivalent;
     }
+    export namespace Shortcut {
+        /**
+         * Shortcuts that are commonly used throughout Raycast. Use them to provide a consistent experience.
+         *
+         * @example
+         * ```typescript
+         * import { List, Action, ActionPanel, Keyboard } from "@raycast/api";
+         * import { useState } from "react";
+         *
+         * type Item = { id: string; title: string; done: boolean };
+         *
+         * let currentId = 0;
+         * function generateId() {
+         *   currentId++;
+         *   return `${currentId}`;
+         * }
+         *
+         * export default function Reminders() {
+         *   const [items, setItems] = useState<Item[]>([{ id: generateId(), title: "Do the laudry", done: false }]);
+         *
+         *   return (
+         *     <List>
+         *       {items.map((item) => (
+         *         <List.Item
+         *           key={item.id}
+         *           icon={item.done ? "checked.png" : "unchecked.png"}
+         *           title={item.title}
+         *           actions={
+         *             <ActionPanel>
+         *               <Action
+         *                 title={item.done ? "Uncheck" : "Check"}
+         *                 onAction={() =>
+         *                   setItems((previousState) =>
+         *                     previousState.map((previousStateItem) =>
+         *                       previousStateItem.id === item.id ? { ...item, done: !previousStateItem.done } : item
+         *                     )
+         *                   )
+         *                 }
+         *               />
+         *               <Action
+         *                 title="New Item"
+         *                 shortcut={Keyboard.Shortcut.Common.New}
+         *                 onAction={() =>
+         *                   setItems((previousState) => [{ id: generateId(), title: "New Item", done: false }, ...previousState])
+         *                 }
+         *               />
+         *             </ActionPanel>
+         *           }
+         *         />
+         *       ))}
+         *     </List>
+         *   );
+         * }
+         * ```
+         */
+        const Common: {
+            Copy: Shortcut;
+            CopyDeeplink: Shortcut;
+            CopyName: Shortcut;
+            CopyPath: Shortcut;
+            Duplicate: Shortcut;
+            Edit: Shortcut;
+            MoveDown: Shortcut;
+            MoveUp: Shortcut;
+            New: Shortcut;
+            Open: Shortcut;
+            OpenWith: Shortcut;
+            Pin: Shortcut;
+            Refresh: Shortcut;
+            Remove: Shortcut;
+            RemoveAll: Shortcut;
+            ToggleQuickLook: Shortcut;
+        };
+
+    }
     /**
      * Modifier of a {@link Keyboard.Shortcut}
      */
@@ -6915,7 +7032,7 @@ declare interface PickDateProps {
 /**
  * Pops the navigation stack back to root search.
  *
- * @param options - Can be used to clear the search bar. Defaults to clearing the search bar after popped to root.
+ * @param options - Can be used to control the behaviour after going back to the root search.
  * @returns A Promise that resolves when Raycast popped to root.
  *
  * @example
@@ -7236,7 +7353,7 @@ declare interface SectionProps_3 {
     /**
      * Column count for the section. Minimum value is 1, maximum value is 8.
      *
-     * @defaultValue 5
+     * @defaultValue `5`
      */
     columns?: number;
     /**
@@ -7300,6 +7417,7 @@ export declare const setLocalStorageItem: typeof LocalStorage.setItem;
  * A HUD will automatically hide the main window and show a compact message at the bottom of the screen.
  *
  * @param title - The title that will be displayed in the HUD.
+ * @param options - Can be used to control the behaviour after closing the main window.
  * @returns A Promise that resolves when the HUD is shown.
  *
  * @example
@@ -7311,7 +7429,18 @@ export declare const setLocalStorageItem: typeof LocalStorage.setItem;
  * };
  * ```
  */
-export declare function showHUD(title: string): Promise<void>;
+export declare function showHUD(title: string, options?: {
+    /**
+     * Clears the text in the root search bar and scrolls to the top
+     *
+     * @defaultValue `false`
+     */
+    clearRootSearch?: boolean;
+    /**
+     * Defines the pop to root behavior ({@link PopToRootType}); the default is to to respect the user's "Pop to Root Search" preference in Raycast
+     */
+    popToRootType?: PopToRootType;
+}): Promise<void>;
 
 /**
  * See {@link Action.ShowInFinder.Props}
@@ -7595,13 +7724,13 @@ declare const TagListItem: FunctionComponent<TagListItemProps>;
 
 declare interface TagListItemProps {
     /**
-     * An optional icon in front of the text of the tag.
+     * The optional icon tag icon. Required if the tag has no text.
      */
     icon?: Image.ImageLike | undefined | null;
     /**
-     * The text of the tag.
+     * The optional tag text. Required if the tag has no icon.
      */
-    text: string;
+    text?: string;
     /**
      * Changes the text color to the provided color and sets a transparent background with the same color.
      */