@raycast/api 1.34.1 → 1.35.0

package/package.json

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

@@ -730,7 +730,7 @@ export declare namespace Color {
          * Raycast user interface. This makes it easy to guarantee a good look and feel when you aren't in control of the
          * color, e.g. get it via a network request.
          *
-         * @defaultValue false
+         * @defaultValue `false`
          */
         adjustContrast?: boolean | undefined | null;
     }
@@ -1088,7 +1088,7 @@ declare interface CopyToClipboardProps {
     content: string | number;
     /**
      * An optional title for the action.
-     * @defaultValue Copy to Clipboard
+     * @defaultValue `"Copy to Clipboard"`
      */
     title?: string;
     /**
@@ -1165,16 +1165,16 @@ declare interface DatePickerMembers {
      * * `Date` - only year, month, and day can be picked
      * * `DateTime` - hour and second can be picked in addition to year, month and day
      */
-    Type: typeof FormDatePickerType;
+    Type: typeof DatePickerType;
 }
 
 declare interface DatePickerProps extends FormItemProps_2<Date> {
     /**
      * Indicates what types of date components can be picked
      *
-     * Defaults to {@link FormDatePickerType.DateTime}
+     * Defaults to {@link Form.DatePicker.Type.DateTime}
      */
-    type?: FormDatePickerType;
+    type?: DatePickerType;
 }
 
 /**
@@ -1182,6 +1182,20 @@ declare interface DatePickerProps extends FormItemProps_2<Date> {
  */
 declare type DatePickerRef = FormItemRef;
 
+/**
+ * See {@link Form.DatePicker.Type}
+ */
+declare enum DatePickerType {
+    /**
+     * Only year, month, and day can be picked
+     */
+    Date = "date",
+    /**
+     * hour and second can be picked in addition to year, month and day
+     */
+    DateTime = "date_time"
+}
+
 declare interface DeprecatedActionPanelMembers {
     /**
      * @deprecated Use {@link Action} instead.
@@ -1309,7 +1323,7 @@ export declare namespace Detail {
 /**
  * See {@link List.Item.Detail}
  */
-declare const Detail_2: FunctionComponent<DetailProps_3>;
+declare const Detail_2: FunctionComponent<DetailProps_3> & DetailMembers_2;
 
 declare interface DetailMembers {
     /**
@@ -1320,6 +1334,96 @@ declare interface DetailMembers {
     Metadata: typeof Metadata;
 }
 
+declare interface DetailMembers_2 {
+    /**
+     * A Metadata view that will be shown in the bottom side of the `List.Item.Detail`.
+     *
+     * Use it to display additional structured data about the content of the `List.Item`.
+     *
+     * @example
+     * ```typescript
+     * import { List } from "@raycast/api";
+     *
+     * export default function Metadata() {
+     *   const markdown = `
+     * ![Illustration](https://assets.pokemon.com/assets/cms2/img/pokedex/full/001.png)
+     * There is a plant seed on its back right from the day this Pokémon is born. The seed slowly grows larger.
+     * `;
+     *   return (
+     *     <List isShowingDetail>
+     *       <List.Item
+     *         title="Bulbasaur"
+     *         detail={
+     *           <List.Item.Detail
+     *             markdown={markdown}
+     *             metadata={
+     *               <List.Item.Detail.Metadata>
+     *                 <List.Item.Detail.Metadata.Label title="Types" />
+     *                 <List.Item.Detail.Metadata.Label title="Grass" icon="pokemon_types/grass.svg" />
+     *                 <List.Item.Detail.Metadata.Separator />
+     *                 <List.Item.Detail.Metadata.Label title="Poison" icon="pokemon_types/poison.svg" />
+     *                 <List.Item.Detail.Metadata.Separator />
+     *                 <List.Item.Detail.Metadata.Label title="Chracteristics" />
+     *                 <List.Item.Detail.Metadata.Label title="Height" text="70cm" />
+     *                 <List.Item.Detail.Metadata.Separator />
+     *                 <List.Item.Detail.Metadata.Label title="Weight" text="6.9 kg" />
+     *                 <List.Item.Detail.Metadata.Separator />
+     *                 <List.Item.Detail.Metadata.Label title="Abilities" />
+     *                 <List.Item.Detail.Metadata.Label title="Chlorophyll" text="Main Series" />
+     *                 <List.Item.Detail.Metadata.Separator />
+     *                 <List.Item.Detail.Metadata.Label title="Overgrow" text="Main Series" />
+     *                 <List.Item.Detail.Metadata.Separator />
+     *               </List.Item.Detail.Metadata>
+     *             }
+     *           />
+     *         }
+     *       />
+     *     </List>
+     *   );
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * import { List } from "@raycast/api";
+     *
+     * export default function Metadata() {
+     *   return (
+     *     <List isShowingDetail>
+     *       <List.Item
+     *         title="Bulbasaur"
+     *         detail={
+     *           <List.Item.Detail
+     *             metadata={
+     *               <List.Item.Detail.Metadata>
+     *                 <List.Item.Detail.Metadata.Label title="Types" />
+     *                 <List.Item.Detail.Metadata.Label title="Grass" icon="pokemon_types/grass.svg" />
+     *                 <List.Item.Detail.Metadata.Separator />
+     *                 <List.Item.Detail.Metadata.Label title="Poison" icon="pokemon_types/poison.svg" />
+     *                 <List.Item.Detail.Metadata.Separator />
+     *                 <List.Item.Detail.Metadata.Label title="Chracteristics" />
+     *                 <List.Item.Detail.Metadata.Label title="Height" text="70cm" />
+     *                 <List.Item.Detail.Metadata.Separator />
+     *                 <List.Item.Detail.Metadata.Label title="Weight" text="6.9 kg" />
+     *                 <List.Item.Detail.Metadata.Separator />
+     *                 <List.Item.Detail.Metadata.Label title="Abilities" />
+     *                 <List.Item.Detail.Metadata.Label title="Chlorophyll" text="Main Series" />
+     *                 <List.Item.Detail.Metadata.Separator />
+     *                 <List.Item.Detail.Metadata.Label title="Overgrow" text="Main Series" />
+     *                 <List.Item.Detail.Metadata.Separator />
+     *               </List.Item.Detail.Metadata>
+     *             }
+     *           />
+     *         }
+     *       />
+     *     </List>
+     *   );
+     * }
+     * ```
+     */
+    Metadata: typeof Metadata_2;
+}
+
 /**
  * @deprecated Use {@link Detail.Props} instead.
  */
@@ -1341,13 +1445,17 @@ declare interface DetailProps_3 {
     /**
      * Indicates whether a loading bar should be shown or hidden above the detail
      *
-     * @defaultValue false
+     * @defaultValue `false`
      */
     isLoading?: boolean;
     /**
      * The CommonMark string to be rendered in the right side area when the parent List is showing details and the item is selected.
      */
     markdown?: string | null;
+    /**
+     * The `List.Item.Detail.Metadata` to be rendered in the bottom side of the `List.Item.Detail`
+     */
+    metadata?: ReactNode;
 }
 
 /**
@@ -1528,7 +1636,7 @@ declare interface DropdownMembers_2 {
  */
 declare interface DropdownProps extends FormItemProps_2<string> {
     /**
-     * Sections or items. If {@link DropdownItem} elements are specified, a default section is automatically created.
+     * Sections or items. If {@link Form.Dropdown.Item} elements are specified, a default section is automatically created.
      */
     children?: ReactNode;
 }
@@ -1545,7 +1653,7 @@ declare interface DropdownProps_2 {
     /**
      * Placeholder text that will be shown in the dropdown search field.
      *
-     * @defaultValue Search...
+     * @defaultValue `"Search..."`
      */
     placeholder?: string;
     /**
@@ -2119,6 +2227,12 @@ export declare namespace Form {
          * Props of the {@link Form.DatePicker} React component.
          */
         export type Props = DatePickerProps;
+        /**
+         * The types of date components the user can pick
+         * * `Date` - only year, month, and day can be picked
+         * * `DateTime` - hour and second can be picked in addition to year, month and day
+         */
+        export type Type = DatePickerType;
     }
     /**
      * A Ref Type for the {@link Form.Dropdown}.
@@ -2328,20 +2442,6 @@ export declare const FormDatePicker: typeof Form.DatePicker;
 export declare interface FormDatePickerProps extends Form.DatePicker.Props {
 }
 
-/**
- * See {@link Form.DatePicker.Type}
- */
-declare enum FormDatePickerType {
-    /**
-     * Only year, month, and day can be picked
-     */
-    Date = "date",
-    /**
-     * hour and second can be picked in addition to year, month and day
-     */
-    DateTime = "date_time"
-}
-
 /**
  * @deprecated Use {@link Form.Dropdown} instead.
  */
@@ -2409,20 +2509,20 @@ declare interface FormItemProps_2<T extends FormValue_2> {
     /**
      * The current value of the item.
      */
-    value?: T & FormValue_2;
+    value?: T;
     /**
      * The default value of the item.
      * Keep in mind that `defaultValue` will be configured once per component lifecycle. This means that if a user changes the value, `defaultValue` won't be configured on re-rendering.
      *
-     * If you're using {@link FormItemProps.storeValue} and configured it as `true` then the stored value will be set.
+     * If you're using `storeValue` and configured it as `true` then the stored value will be set.
      *
-     * If you configure {@link FormItemProps.value} at the same time with {@link FormItemProps.defaultValue}, the `value` will be set instead of `defaultValue`.
+     * If you configure `value` at the same time with `defaultValue`, the `value` will be set instead of `defaultValue`.
      */
-    defaultValue?: T & FormValue_2;
+    defaultValue?: T;
     /**
-     * The callback which will be triggered on the {@link Form.Item.Props.value} change for the item.
+     * The callback which will be triggered when the `value` of the item changes.
      */
-    onChange?: (newValue: T & FormValue_2) => void;
+    onChange?: (newValue: T) => void;
 }
 
 /**
@@ -2430,7 +2530,7 @@ declare interface FormItemProps_2<T extends FormValue_2> {
  */
 declare interface FormItemRef {
     /**
-     * Makes the item focused
+     * Focuses the item.
      *
      * @example
      * ```typescript
@@ -2464,8 +2564,9 @@ declare interface FormItemRef {
     focus: () => void;
     /**
      * Resets value of the item
+     *
      * @remarks
-     * In case if {@link FormItemProps.defaultValue} is defined, calling the `.reset()` function will drop the value to the provided one.
+     * If `defaultValue` is defined, calling the `.reset()` function will set `value` to the `defaultValue`.
      *
      * @example
      * ```typescript
@@ -3612,6 +3713,11 @@ export declare type KeyModifier = Keyboard.KeyModifier;
  */
 declare const Label: FunctionComponent<LabelProps>;
 
+/**
+ * See {@link List.Item.Detail.Metadata.Label}
+ */
+declare const Label_2: FunctionComponent<LabelProps_2>;
+
 declare interface LabelProps {
     /**
      * The title shown above the item.
@@ -3627,6 +3733,21 @@ declare interface LabelProps {
     text?: string;
 }
 
+declare interface LabelProps_2 {
+    /**
+     * The title of the item.
+     */
+    title: string;
+    /**
+     * An icon to illustrate the value of the item.
+     */
+    icon?: Image.ImageLike | undefined | null;
+    /**
+     * The text value of the item.
+     */
+    text?: string;
+}
+
 /**
  * See {@link Detail.Metadata.Link}
  */
@@ -3944,13 +4065,13 @@ declare interface ListProps_2 extends ActionsInterface, NavigationChildInterface
      * @remarks
      * Having this enabled when filtering items in the extension is unspecified behaviour.
      *
-     * @defaultValue false when `onSearchTextChange` is specified, true otherwise.
+     * @defaultValue `false` when `onSearchTextChange` is specified, `true` otherwise.
      */
     enableFiltering?: boolean;
     /**
      * Placeholder text that will be shown in the search bar.
      *
-     * @defaultValue Search value...
+     * @defaultValue `"Search value..."`
      */
     searchBarPlaceholder?: string;
     /**
@@ -3960,7 +4081,7 @@ declare interface ListProps_2 extends ActionsInterface, NavigationChildInterface
     /**
      * Defines whether the {@link List.Props.onSearchTextChange} will be triggered on every keyboard press or with a delay for throttling the events.
      * Recommended to set to `true` when using custom filtering logic with asynchronous operations (e.g. network requests).
-     * @defaultValue false
+     * @defaultValue `false`
      */
     throttle?: boolean;
     /**
@@ -4125,6 +4246,11 @@ export declare interface LocalStorageValues extends LocalStorage.Values {
  */
 declare const Metadata: FunctionComponent<MetadataProps> & MetadataMembers;
 
+/**
+ * See {@link List.Item.Detail.Metadata}
+ */
+declare const Metadata_2: FunctionComponent<MetadataProps_2> & MetadataMembers_2;
+
 declare interface MetadataMembers {
     /**
      * A single value with an optional icon.
@@ -4144,6 +4270,67 @@ declare interface MetadataMembers {
     TagList: typeof TagList;
 }
 
+declare interface MetadataMembers_2 {
+    /**
+     * A title with, optionally, an icon and/or text to its right.
+     *
+     * @example
+     * ```typescript
+     * import { List } from "@raycast/api";
+     *
+     * export default function Metadata() {
+     *   return (
+     *     <List isShowingDetail>
+     *       <List.Item
+     *         title="Bulbasaur"
+     *         detail={
+     *           <List.Item.Detail
+     *             metadata={
+     *               <List.Item.Detail.Metadata>
+     *                 <List.Item.Detail.Metadata.Label title="Type" icon="pokemon_types/grass.svg" text="Grass"/>
+     *               </List.Item.Detail.Metadata>
+     *             }
+     *           />
+     *         }
+     *       />
+     *     </List>
+     *   );
+     * }
+     * ```
+     */
+    Label: typeof Label_2;
+    /**
+     * A metadata item that shows a separator line. Use it for grouping and visually separating metadata items.
+     *
+     * @example
+     * ```typescript
+     * import { List } from "@raycast/api";
+     *
+     * export default function Metadata() {
+     *   return (
+     *     <List isShowingDetail>
+     *       <List.Item
+     *         title="Bulbasaur"
+     *         detail={
+     *           <List.Item.Detail
+     *             metadata={
+     *               <List.Item.Detail.Metadata>
+     *                 <List.Item.Detail.Metadata.Label title="Type" icon="pokemon_types/grass.svg" text="Grass"/>
+     *                 <List.Item.Detail.Metadata.Separator />
+     *                 <List.Item.Detail.Metadata.Label title="Type" icon="pokemon_types/poison.svg" text="Poison"/>
+     *               </List.Item.Detail.Metadata>
+     *             }
+     *           />
+     *         }
+     *       />
+     *     </List>
+     *   );
+     * }
+     * ```
+     */
+    Separator: typeof Separator_3;
+}
+
 declare interface MetadataProps {
     /**
      * The Detail.Metadata.Item elements of the Metadata view.
@@ -4151,6 +4338,13 @@ declare interface MetadataProps {
     children: ReactNode;
 }
 
+declare interface MetadataProps_2 {
+    /**
+     * The {@link Detail.Metadata.Item}s of the Metadata view.
+     */
+    children: ReactNode;
+}
+
 /**
  * Return type of the {@link useNavigation} hook to perform push and pop actions.
  */
@@ -4181,7 +4375,7 @@ declare interface NavigationChildInterface {
     /**
      * Indicates whether a loading bar should be shown or hidden below the search bar
      *
-     * @defaultValue false
+     * @defaultValue `false`
      */
     isLoading?: boolean;
 }
@@ -4518,6 +4712,16 @@ export declare const OpenAction: FunctionComponent<OpenProps>;
 export declare interface OpenActionProps extends Action.Open.Props {
 }
 
+/**
+ * Opens Raycast's preference window and selects the current command.
+ */
+export declare function openCommandPreferences(): Promise<void>;
+
+/**
+ * Opens Raycast's preference window and selects the current extension.
+ */
+export declare function openExtensionPreferences(): Promise<void>;
+
 /**
  * See {@link Action.OpenInBrowser}
  */
@@ -4544,7 +4748,7 @@ declare interface OpenInBrowserProps {
     url: string;
     /**
      * An optional title for the action.
-     * @defaultValue Open in Browser
+     * @defaultValue `"Open in Browser"`
      */
     title?: string;
     /**
@@ -4629,7 +4833,7 @@ declare interface OpenWithProps {
     path: string;
     /**
      * The title for the action.
-     * @defaultValue Open With
+     * @defaultValue `"Open With"`
      */
     title?: string;
     /**
@@ -4696,7 +4900,7 @@ declare interface PasteProps {
     content: string | number;
     /**
      * An optional title for the action.
-     * @defaultValue Paste in Active app
+     * @defaultValue `"Paste in Active app"`
      */
     title?: string;
     /**
@@ -4777,7 +4981,7 @@ declare interface Preference_2 {
      * If the preference is required, an onboarding view is shown when the
      * extension is opened for the first time.
      *
-     * @defaultValue false
+     * @defaultValue `false`
      */
     required: boolean;
     /**
@@ -4974,6 +5178,11 @@ declare const Separator: FunctionComponent<SeparatorProps>;
  */
 declare const Separator_2: FunctionComponent<SeparatorProps_2>;
 
+/**
+ * See {@link List.Item.Detail.Metadata.Label}
+ */
+declare const Separator_3: FunctionComponent<SeparatorProps_3>;
+
 /**
  * See {@link Form.Separator.Props}
  */
@@ -4983,6 +5192,9 @@ declare interface SeparatorProps {
 declare interface SeparatorProps_2 {
 }
 
+declare interface SeparatorProps_3 {
+}
+
 /**
  * @deprecated Use {@link LocalStorage.setItem} instead
  */
@@ -5050,7 +5262,7 @@ declare interface ShowInFinderProps {
     path: PathLike;
     /**
      * An optional title for the action.
-     * @defaultValue Show in Finder
+     * @defaultValue `"Show in Finder"`
      */
     title?: string;
     /**
@@ -5212,7 +5424,7 @@ export declare interface SubmitFormActionProps<T> extends Action.SubmitForm.Prop
 declare interface SubmitFormProps<T extends Form.Values> {
     /**
      * The title displayed for the item.
-     * @defaultValue Submit Form
+     * @defaultValue `"Submit Form"`
      */
     title?: string;
     /**
@@ -5415,14 +5627,29 @@ export declare class Toast {
      * Deprecated - Use `showToast` instead
      */
     constructor(props: Toast.Options);
+    /**
+     * The style of a Toast.
+     */
     get style(): Toast.Style;
     set style(style: Toast.Style);
+    /**
+     * The title of a Toast. Displayed on the top.
+     */
     get title(): string;
     set title(title: string);
+    /**
+     * An additional message for the Toast. Useful to show more information, e.g. an identifier of a newly created asset.
+     */
     get message(): string | undefined;
     set message(message: string | undefined);
+    /**
+     * The primary Action the user can take when hovering on the Toast.
+     */
     get primaryAction(): Toast.ActionOptions | undefined;
     set primaryAction(action: Toast.ActionOptions | undefined);
+    /**
+     * The secondary Action the user can take when hovering on the Toast.
+     */
     get secondaryAction(): Toast.ActionOptions | undefined;
     set secondaryAction(action: Toast.ActionOptions | undefined);
     /**
@@ -5582,7 +5809,7 @@ declare interface TrashProps {
     paths: PathLike | PathLike[];
     /**
      * An optional title for the action.
-     * @defaultValue Move to Trash
+     * @defaultValue `"Move to Trash"`
      */
     title?: string;
     /**