@raycast/api 1.44.0 → 1.45.0

package/api.d.ts

@@ -550,13 +550,8 @@ declare interface Arguments {
     [item: string]: any;
 }
 
-/**
- * An interface describing top-level props for arguments
- */
+/** @deprecated Use {@Link LaunchProps} directly */
 export declare interface ArgumentsLaunchProps {
-    /**
-     * Use these values to populate the initial state for your command.
-     */
     arguments?: Arguments;
 }
 
@@ -857,7 +852,6 @@ export declare function closeMainWindow(options?: {
  *  <List>
  *    <List.Item title="Blue" icon={{ source: Icon.Circle, tintColor: Color.Blue }} />
  *    <List.Item title="Green" icon={{ source: Icon.Circle, tintColor: Color.Green }} />
- *    <List.Item title="Brown" icon={{ source: Icon.Circle, tintColor: Color.Brown }} />
  *    <List.Item title="Magenta" icon={{ source: Icon.Circle, tintColor: Color.Magenta }} />
  *    <List.Item title="Orange" icon={{ source: Icon.Circle, tintColor: Color.Orange }} />
  *    <List.Item title="Purple" icon={{ source: Icon.Circle, tintColor: Color.Purple }} />
@@ -872,7 +866,6 @@ export declare function closeMainWindow(options?: {
  */
 export declare enum Color {
     Blue = "raycast-blue",
-    Brown = "raycast-brown",
     Green = "raycast-green",
     Magenta = "raycast-magenta",
     Orange = "raycast-orange",
@@ -957,6 +950,12 @@ export declare namespace Color {
      * - Keywords, e.g. `red`
      */
     export type Raw = string;
+    /** The standard colors. Use those colors for consistency.
+     *
+     * @remarks
+     * The colors automatically adapt to the Raycast theme (light or dark).
+     */
+    const Brown: Color.Dynamic;
 }
 
 /**
@@ -1887,6 +1886,12 @@ declare interface DropdownMembers_2 {
  * See {@link Form.Dropdown.Props}
  */
 declare interface DropdownProps extends FormItemProps_2<string>, SearchBarInterface {
+    /**
+     * Placeholder text that will be shown in the dropdown search field.
+     *
+     * @defaultValue `"Search..."`
+     */
+    placeholder?: string;
     /**
      * Sections or items. If {@link Form.Dropdown.Item} elements are specified, a default section is automatically created.
      */
@@ -2049,7 +2054,7 @@ export declare interface Environment {
      */
     launchType: LaunchType;
     /**
-     * Any custom context values passed from a programmatic command launch via `launchCommand`.
+     * @deprecated Use the top-level prop `launchContext` instead.
      */
     launchContext?: LaunchContext;
 }
@@ -3060,14 +3065,8 @@ declare interface FormItemRef {
     reset: () => void;
 }
 
-/**
- * An interface describing top-level props for Form drafts
- */
+/** @deprecated Use {@Link LaunchProps} directly */
 export declare interface FormLaunchProps {
-    /**
-     * When a user enters the command via a draft, this object will contain the user inputs that were saved as a draft.
-     * Use its values to populate the initial state for your Form.
-     */
     draftValues?: Form.Values;
 }
 
@@ -3760,7 +3759,7 @@ export declare function getApplications(path?: PathLike): Promise<Application[]>
  * Returns the default application that the file would be opened with.
  *
  * @param path - The path of the file or folder to get the default application for.
- * @returns The default {@link Application} that would open the file. Throws an error if no application was found.
+ * @returns A Promise that resolves with the default {@link Application} that would open the file. If no application was found, the promise will be rejected.
  *
  * @example
  * ```typescript
@@ -3777,7 +3776,7 @@ export declare function getDefaultApplication(path: PathLike): Promise<Applicati
 /**
  * Returns the frontmost application.
  *
- * @returns The frontmost {@link Application}. Throws an error if no application was found.
+ * @returns A Promise that resolves with the frontmost {@link Application}. If no application was found, the promise will be rejected.
  *
  * @example
  * ```typescript
@@ -3825,8 +3824,7 @@ export declare function getPreferenceValues<Values extends PreferenceValues = Pr
 /**
  * Gets the selected items from Finder.
  *
- * @throws An error when Finder is not the frontmost application.
- * @returns A Promise that resolves with the selected file system items.
+ * @returns A Promise that resolves with the selected file system items. If Finder is not the frontmost application, the promise will be rejected.
  *
  * @example
  * ```typescript
@@ -3853,8 +3851,7 @@ export declare function getSelectedFinderItems(): Promise<FileSystemItem[]>;
 /**
  * Gets the selected text of the frontmost application.
  *
- * @throws An error when no text is selected in the frontmost application.
- * @returns A Promise that resolves with the selected text.
+ * @returns A Promise that resolves with the selected text. If no text is selected in the frontmost application, the promise will be rejected.
  *
  * @example
  * ```typescript
@@ -4886,14 +4883,34 @@ declare const Item_3: FunctionComponent<ItemProps_3>;
 
 declare type ItemAccessory = ({
     /**
-     * An optional text that will be used as the label.
+     * An optional text that will be used as the label, optionally colored.
+     * Color changes the text color to the provided color.
+     * Defaults to {@link Color.SecondaryText}.
      */
-    text?: string | undefined | null;
+    text?: string | undefined | null | {
+        value: string | undefined | null;
+        color?: Color;
+    };
+} | {
+    /**
+     * An optional Date that will be used as the label, optionally colored. The date is formatted relatively to the current time (for example `new Date()` will be displayed as `"now"`, yesterday's Date will be displayed as "1d", etc.).
+     * Color changes the text color to the provided color.
+     * Defaults to {@link Color.SecondaryText}.
+     */
+    date?: Date | undefined | null | {
+        value: Date | undefined | null;
+        color?: Color;
+    };
 } | {
     /**
-     * An optional Date that will be used as the label. The date is formatted relatively to the current time (for example `new Date()` will be displayed as `"now"`, yesterday's Date will be displayed as "1d", etc.).
+     * A string or Date that will be used as the label, optionally colored. The date is formatted relatively to the current time (for example `new Date()` will be displayed as `"now"`, yesterday's Date will be displayed as "1d", etc.).
+     * Color changes the text color to the provided color and sets a transparent background with the same color.
+     * Defaults to {@link Color.SecondaryText}.
      */
-    date?: Date | undefined | null;
+    tag: string | Date | undefined | null | {
+        value: string | Date | undefined | null;
+        color?: Color;
+    };
 }) & {
     /**
      * An optional {@link Image.ImageLike} that will be used as the icon.
@@ -4970,14 +4987,14 @@ declare interface ItemProps extends ActionsInterface {
      */
     title: string | {
         value: string;
-        tooltip: string;
+        tooltip?: string | null;
     };
     /**
      * An optional subtitle displayed next to the main title, optionally with a tooltip.
      */
     subtitle?: string | {
-        value: string | undefined | null;
-        tooltip: string;
+        value?: string | null;
+        tooltip?: string | null;
     };
     /**
      * An optional property used for providing additional indexable strings for search.
@@ -5075,7 +5092,7 @@ declare interface ItemProps_3 {
      */
     title: string;
     /**
-     * The subtitle displayed for this item in a slightly dimmed text color.
+     * The subtitle displayed for this item.
      */
     subtitle?: string;
     /**
@@ -5187,8 +5204,12 @@ declare interface LabelProps {
     icon?: Image.ImageLike | undefined | null;
     /**
      * The text value of the item.
+     * Specifying `color` will display the text in the provided color. Defaults to {@link Color.SecondaryText}.
      */
-    text?: string;
+    text?: string | {
+        value: string;
+        color?: Color | null;
+    };
 }
 
 /**
@@ -5229,7 +5250,37 @@ declare interface LaunchContext {
 /**
  * The top-level props that a Command receives on launch
  */
-export declare type LaunchProps = ArgumentsLaunchProps | FormLaunchProps;
+export declare type LaunchProps<T extends {
+    arguments?: Arguments;
+    draftValues?: Form.Values;
+    launchContext?: LaunchContext;
+} = {
+    arguments: Arguments;
+    draftValues: Form.Values;
+    launchContext?: LaunchContext;
+}> = {
+    /**
+     * The type of launch for the command (user initiated or background).
+     */
+    launchType: LaunchType;
+    /**
+     * Use these values to populate the initial state for your command.
+     */
+    arguments: T["arguments"];
+    /**
+     * When a user enters the command via a draft, this object will contain the user inputs that were saved as a draft.
+     * Use its values to populate the initial state for your Form.
+     */
+    draftValues?: T["draftValues"];
+    /**
+     * When the command is launched programmatically via `launchCommand`, this object contains the value passed to `context`.
+     */
+    launchContext?: T["launchContext"];
+    /**
+     * When the command is launched as a fallback command, this string contains the text of the root search.
+     */
+    fallbackText?: string;
+};
 
 export declare enum LaunchType {
     /**
@@ -7189,7 +7240,7 @@ export declare const SubmitFormAction: {
 /**
  * @deprecated Use {@link Action.SunmitForm.Props} instead.
  */
-export declare interface SubmitFormActionProps<T> extends Action.SubmitForm.Props<T> {
+export declare interface SubmitFormActionProps<T extends Form.Values> extends Action.SubmitForm.Props<T> {
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raycast/api",
-  "version": "1.44.0",
+  "version": "1.45.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

@@ -550,13 +550,8 @@ declare interface Arguments {
     [item: string]: any;
 }
 
-/**
- * An interface describing top-level props for arguments
- */
+/** @deprecated Use {@Link LaunchProps} directly */
 export declare interface ArgumentsLaunchProps {
-    /**
-     * Use these values to populate the initial state for your command.
-     */
     arguments?: Arguments;
 }
 
@@ -857,7 +852,6 @@ export declare function closeMainWindow(options?: {
  *  <List>
  *    <List.Item title="Blue" icon={{ source: Icon.Circle, tintColor: Color.Blue }} />
  *    <List.Item title="Green" icon={{ source: Icon.Circle, tintColor: Color.Green }} />
- *    <List.Item title="Brown" icon={{ source: Icon.Circle, tintColor: Color.Brown }} />
  *    <List.Item title="Magenta" icon={{ source: Icon.Circle, tintColor: Color.Magenta }} />
  *    <List.Item title="Orange" icon={{ source: Icon.Circle, tintColor: Color.Orange }} />
  *    <List.Item title="Purple" icon={{ source: Icon.Circle, tintColor: Color.Purple }} />
@@ -872,7 +866,6 @@ export declare function closeMainWindow(options?: {
  */
 export declare enum Color {
     Blue = "raycast-blue",
-    Brown = "raycast-brown",
     Green = "raycast-green",
     Magenta = "raycast-magenta",
     Orange = "raycast-orange",
@@ -957,6 +950,12 @@ export declare namespace Color {
      * - Keywords, e.g. `red`
      */
     export type Raw = string;
+    /** The standard colors. Use those colors for consistency.
+     *
+     * @remarks
+     * The colors automatically adapt to the Raycast theme (light or dark).
+     */
+    const Brown: Color.Dynamic;
 }
 
 /**
@@ -1887,6 +1886,12 @@ declare interface DropdownMembers_2 {
  * See {@link Form.Dropdown.Props}
  */
 declare interface DropdownProps extends FormItemProps_2<string>, SearchBarInterface {
+    /**
+     * Placeholder text that will be shown in the dropdown search field.
+     *
+     * @defaultValue `"Search..."`
+     */
+    placeholder?: string;
     /**
      * Sections or items. If {@link Form.Dropdown.Item} elements are specified, a default section is automatically created.
      */
@@ -2049,7 +2054,7 @@ export declare interface Environment {
      */
     launchType: LaunchType;
     /**
-     * Any custom context values passed from a programmatic command launch via `launchCommand`.
+     * @deprecated Use the top-level prop `launchContext` instead.
      */
     launchContext?: LaunchContext;
 }
@@ -3060,14 +3065,8 @@ declare interface FormItemRef {
     reset: () => void;
 }
 
-/**
- * An interface describing top-level props for Form drafts
- */
+/** @deprecated Use {@Link LaunchProps} directly */
 export declare interface FormLaunchProps {
-    /**
-     * When a user enters the command via a draft, this object will contain the user inputs that were saved as a draft.
-     * Use its values to populate the initial state for your Form.
-     */
     draftValues?: Form.Values;
 }
 
@@ -3760,7 +3759,7 @@ export declare function getApplications(path?: PathLike): Promise<Application[]>
  * Returns the default application that the file would be opened with.
  *
  * @param path - The path of the file or folder to get the default application for.
- * @returns The default {@link Application} that would open the file. Throws an error if no application was found.
+ * @returns A Promise that resolves with the default {@link Application} that would open the file. If no application was found, the promise will be rejected.
  *
  * @example
  * ```typescript
@@ -3777,7 +3776,7 @@ export declare function getDefaultApplication(path: PathLike): Promise<Applicati
 /**
  * Returns the frontmost application.
  *
- * @returns The frontmost {@link Application}. Throws an error if no application was found.
+ * @returns A Promise that resolves with the frontmost {@link Application}. If no application was found, the promise will be rejected.
  *
  * @example
  * ```typescript
@@ -3825,8 +3824,7 @@ export declare function getPreferenceValues<Values extends PreferenceValues = Pr
 /**
  * Gets the selected items from Finder.
  *
- * @throws An error when Finder is not the frontmost application.
- * @returns A Promise that resolves with the selected file system items.
+ * @returns A Promise that resolves with the selected file system items. If Finder is not the frontmost application, the promise will be rejected.
  *
  * @example
  * ```typescript
@@ -3853,8 +3851,7 @@ export declare function getSelectedFinderItems(): Promise<FileSystemItem[]>;
 /**
  * Gets the selected text of the frontmost application.
  *
- * @throws An error when no text is selected in the frontmost application.
- * @returns A Promise that resolves with the selected text.
+ * @returns A Promise that resolves with the selected text. If no text is selected in the frontmost application, the promise will be rejected.
  *
  * @example
  * ```typescript
@@ -4886,14 +4883,34 @@ declare const Item_3: FunctionComponent<ItemProps_3>;
 
 declare type ItemAccessory = ({
     /**
-     * An optional text that will be used as the label.
+     * An optional text that will be used as the label, optionally colored.
+     * Color changes the text color to the provided color.
+     * Defaults to {@link Color.SecondaryText}.
      */
-    text?: string | undefined | null;
+    text?: string | undefined | null | {
+        value: string | undefined | null;
+        color?: Color;
+    };
+} | {
+    /**
+     * An optional Date that will be used as the label, optionally colored. The date is formatted relatively to the current time (for example `new Date()` will be displayed as `"now"`, yesterday's Date will be displayed as "1d", etc.).
+     * Color changes the text color to the provided color.
+     * Defaults to {@link Color.SecondaryText}.
+     */
+    date?: Date | undefined | null | {
+        value: Date | undefined | null;
+        color?: Color;
+    };
 } | {
     /**
-     * An optional Date that will be used as the label. The date is formatted relatively to the current time (for example `new Date()` will be displayed as `"now"`, yesterday's Date will be displayed as "1d", etc.).
+     * A string or Date that will be used as the label, optionally colored. The date is formatted relatively to the current time (for example `new Date()` will be displayed as `"now"`, yesterday's Date will be displayed as "1d", etc.).
+     * Color changes the text color to the provided color and sets a transparent background with the same color.
+     * Defaults to {@link Color.SecondaryText}.
      */
-    date?: Date | undefined | null;
+    tag: string | Date | undefined | null | {
+        value: string | Date | undefined | null;
+        color?: Color;
+    };
 }) & {
     /**
      * An optional {@link Image.ImageLike} that will be used as the icon.
@@ -4970,14 +4987,14 @@ declare interface ItemProps extends ActionsInterface {
      */
     title: string | {
         value: string;
-        tooltip: string;
+        tooltip?: string | null;
     };
     /**
      * An optional subtitle displayed next to the main title, optionally with a tooltip.
      */
     subtitle?: string | {
-        value: string | undefined | null;
-        tooltip: string;
+        value?: string | null;
+        tooltip?: string | null;
     };
     /**
      * An optional property used for providing additional indexable strings for search.
@@ -5075,7 +5092,7 @@ declare interface ItemProps_3 {
      */
     title: string;
     /**
-     * The subtitle displayed for this item in a slightly dimmed text color.
+     * The subtitle displayed for this item.
      */
     subtitle?: string;
     /**
@@ -5187,8 +5204,12 @@ declare interface LabelProps {
     icon?: Image.ImageLike | undefined | null;
     /**
      * The text value of the item.
+     * Specifying `color` will display the text in the provided color. Defaults to {@link Color.SecondaryText}.
      */
-    text?: string;
+    text?: string | {
+        value: string;
+        color?: Color | null;
+    };
 }
 
 /**
@@ -5229,7 +5250,37 @@ declare interface LaunchContext {
 /**
  * The top-level props that a Command receives on launch
  */
-export declare type LaunchProps = ArgumentsLaunchProps | FormLaunchProps;
+export declare type LaunchProps<T extends {
+    arguments?: Arguments;
+    draftValues?: Form.Values;
+    launchContext?: LaunchContext;
+} = {
+    arguments: Arguments;
+    draftValues: Form.Values;
+    launchContext?: LaunchContext;
+}> = {
+    /**
+     * The type of launch for the command (user initiated or background).
+     */
+    launchType: LaunchType;
+    /**
+     * Use these values to populate the initial state for your command.
+     */
+    arguments: T["arguments"];
+    /**
+     * When a user enters the command via a draft, this object will contain the user inputs that were saved as a draft.
+     * Use its values to populate the initial state for your Form.
+     */
+    draftValues?: T["draftValues"];
+    /**
+     * When the command is launched programmatically via `launchCommand`, this object contains the value passed to `context`.
+     */
+    launchContext?: T["launchContext"];
+    /**
+     * When the command is launched as a fallback command, this string contains the text of the root search.
+     */
+    fallbackText?: string;
+};
 
 export declare enum LaunchType {
     /**
@@ -7189,7 +7240,7 @@ export declare const SubmitFormAction: {
 /**
  * @deprecated Use {@link Action.SunmitForm.Props} instead.
  */
-export declare interface SubmitFormActionProps<T> extends Action.SubmitForm.Props<T> {
+export declare interface SubmitFormActionProps<T extends Form.Values> extends Action.SubmitForm.Props<T> {
 }
 
 /**