@raycast/api 1.30.1 → 1.31.0

package/README.md

@@ -1,6 +1,6 @@
 <p align="center">
   <img src="https://raw.githubusercontent.com/raycast/extensions/main/images/store-logo.png" height="128">
-  <h1 align="center">Raycast Extensions (Beta)</h1>
+  <h1 align="center">Raycast Extensions</h1>
 </p>
 
 <p align="center">

package/package.json

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

package/types/api/components/Detail.d.ts

@@ -1,6 +1,7 @@
-import { ReactElement } from "react";
+import React, { ReactElement, ReactNode } from "react";
 import { ActionsInterface, NavigationChildInterface } from "./types";
 import PropTypes from "prop-types";
+import { Color, Image } from "../ui";
 /**
  * Renders a markdown (CommonMark) string.
  *
@@ -22,6 +23,108 @@ export declare namespace Detail {
         navigationTitle: PropTypes.Requireable<string>;
         isLoading: PropTypes.Requireable<boolean>;
         markdown: PropTypes.Requireable<string>;
+        metadata: PropTypes.Requireable<PropTypes.ReactNodeLike>;
+    };
+    var displayName: string;
+}
+/**
+ * See {@link Detail.Metadata}
+ */
+declare function DetailMetadata(props: Detail.Metadata.Props): ReactElement<Detail.Metadata.Props>;
+declare namespace DetailMetadata {
+    var propTypes: {};
+    var displayName: string;
+}
+/**
+ * See {@link Detail.Metadata.Label}
+ */
+declare function DetailMetadataLabel(props: Detail.Metadata.Label.Props): ReactElement<Detail.Metadata.Label.Props> | null;
+declare namespace DetailMetadataLabel {
+    var propTypes: {
+        title: PropTypes.Validator<string>;
+        icon: PropTypes.Requireable<string | Required<PropTypes.InferProps<{
+            fileIcon: PropTypes.Validator<string>;
+        }>> | PropTypes.InferProps<{
+            source: PropTypes.Requireable<string | PropTypes.InferProps<{
+                light: PropTypes.Validator<string>;
+                dark: PropTypes.Validator<string>;
+            }>>;
+            fallback: PropTypes.Requireable<string | PropTypes.InferProps<{
+                light: PropTypes.Validator<string>;
+                dark: PropTypes.Validator<string>;
+            }>>;
+            mask: PropTypes.Requireable<Image.Mask>;
+            tintColor: PropTypes.Requireable<string | PropTypes.InferProps<{
+                light: PropTypes.Validator<string>;
+                dark: PropTypes.Validator<string>;
+                adjustContrast: PropTypes.Requireable<boolean>;
+            }>>;
+        }>>;
+        text: PropTypes.Requireable<string>;
+    };
+    var displayName: string;
+}
+/**
+ * See {@link Detail.Metadata.Separator}
+ */
+declare function DetailMetadataSeparator(props: Detail.Metadata.Separator.Props): ReactElement<Detail.Metadata.Separator.Props>;
+declare namespace DetailMetadataSeparator {
+    var propTypes: {};
+    var displayName: string;
+}
+/**
+ * See {@link Detail.Metadata.Link}
+ */
+declare function DetailMetadataLink(props: Detail.Metadata.Link.Props): ReactElement<Detail.Metadata.Link.Props>;
+declare namespace DetailMetadataLink {
+    var propTypes: {
+        title: PropTypes.Validator<string>;
+        target: PropTypes.Validator<string>;
+        text: PropTypes.Validator<string>;
+    };
+    var displayName: string;
+}
+/**
+ * See {@link Detail.Metadata.TagList}
+ */
+declare function DetailMetadataTagList(props: Detail.Metadata.TagList.Props): ReactElement<Detail.Metadata.TagList.Props>;
+declare namespace DetailMetadataTagList {
+    var propTypes: {
+        title: PropTypes.Validator<string>;
+        children: PropTypes.Requireable<PropTypes.ReactNodeLike>;
+    };
+    var displayName: string;
+}
+/**
+ * See {@link Detail.Metadata.TagList.Item}
+ */
+declare function DetailMetadataTagListItem(props: Detail.Metadata.TagList.Item.Props): ReactElement<Detail.Metadata.TagList.Item.Props>;
+declare namespace DetailMetadataTagListItem {
+    var propTypes: {
+        text: PropTypes.Validator<string>;
+        icon: PropTypes.Requireable<string | Required<PropTypes.InferProps<{
+            fileIcon: PropTypes.Validator<string>;
+        }>> | PropTypes.InferProps<{
+            source: PropTypes.Requireable<string | PropTypes.InferProps<{
+                light: PropTypes.Validator<string>;
+                dark: PropTypes.Validator<string>;
+            }>>;
+            fallback: PropTypes.Requireable<string | PropTypes.InferProps<{
+                light: PropTypes.Validator<string>;
+                dark: PropTypes.Validator<string>;
+            }>>;
+            mask: PropTypes.Requireable<Image.Mask>;
+            tintColor: PropTypes.Requireable<string | PropTypes.InferProps<{
+                light: PropTypes.Validator<string>;
+                dark: PropTypes.Validator<string>;
+                adjustContrast: PropTypes.Requireable<boolean>;
+            }>>;
+        }>>;
+        color: PropTypes.Requireable<string | PropTypes.InferProps<{
+            light: PropTypes.Validator<string>;
+            dark: PropTypes.Validator<string>;
+            adjustContrast: PropTypes.Requireable<boolean>;
+        }>>;
     };
     var displayName: string;
 }
@@ -34,5 +137,127 @@ export declare namespace Detail {
          * The CommonMark string to be rendered.
          */
         markdown?: string | null;
+        /**
+         * The `Detail.Metadata` to be rendered in the right side area
+         */
+        metadata?: React.ReactNode;
+    }
+    /**
+     * A Metadata view that will be shown in the right-hand-side of the `Detail`.
+     *
+     * Use it to display additional structured data about the main content shown in the `Detail` view.
+     */
+    const Metadata: typeof DetailMetadata;
+    namespace Metadata {
+        /**
+         * Props of the {@link Detail.Metadata} React component.
+         */
+        interface Props {
+            /**
+             * The Detail.Metadata.Item elements of the Metadata view.
+             */
+            children: React.ReactNode;
+        }
+        /**
+         * Props of the Detail.Metadata.Item React component.
+         */
+        interface ItemProps {
+            /**
+             * The title shown above the item.
+             */
+            title: string;
+        }
+        namespace Label {
+            /**
+             * Props of the {@link Detail.Metadata.Label} React component.
+             */
+            interface Props extends ItemProps {
+                /**
+                 * An icon to illustrate the value of the item.
+                 */
+                icon?: Image.ImageLike;
+                /**
+                 * The text value of the item.
+                 */
+                text?: string;
+            }
+        }
+        namespace Separator {
+            /**
+             * Props of the {@link Detail.Metadata.Separator} React component.
+             */
+            interface Props {
+            }
+        }
+        namespace Link {
+            /**
+             * Props of the {@link Detail.Metadata.Link} React component.
+             */
+            interface Props extends ItemProps {
+                /**
+                 * The target of the link.
+                 */
+                target: string;
+                /**
+                 * The text value of the item.
+                 */
+                text: string;
+            }
+        }
+        namespace TagList {
+            /**
+             * Props of the {@link Detail.Metadata.TagList} React component.
+             */
+            interface Props extends ItemProps {
+                /**
+                 * The tags contained in the TagList.
+                 */
+                children: ReactNode;
+            }
+            namespace Item {
+                /**
+                 * Props of the {@link Detail.Metadata.TagList.Item} React component.
+                 */
+                interface Props {
+                    /**
+                     * An optional icon in front of the text of the tag.
+                     */
+                    icon?: Image.ImageLike;
+                    /**
+                     * The text of the tag.
+                     */
+                    text: string;
+                    /**
+                     * Changes the text color to the provided color and sets a transparent background with the same color.
+                     */
+                    color?: Color.ColorLike;
+                }
+            }
+        }
     }
 }
+declare namespace DetailMetadataTagList {
+    /**
+     * A Tag in a {@link Detail.Metadata.TagList}.
+     */
+    const Item: typeof DetailMetadataTagListItem;
+}
+declare namespace DetailMetadata {
+    /**
+     * A single value with an optional icon.
+     */
+    const Label: typeof DetailMetadataLabel;
+    /**
+     * A metadata item that shows a separator line. Use it for grouping and visually separating metadata items.
+     */
+    const Separator: typeof DetailMetadataSeparator;
+    /**
+     * An item to display a link.
+     */
+    const Link: typeof DetailMetadataLink;
+    /**
+     * A list of {@link Detail.Metadata.TagList.Item} displayed in a row.
+     */
+    const TagList: typeof DetailMetadataTagList;
+}
+export {};

package/types/api/components/Form.d.ts

@@ -735,7 +735,7 @@ export declare namespace Form {
     /**
      * A form item with a simple text label.
      *
-     * @remark Do *not* use this component to show validation messages for other form fields.
+     * @remarks Do *not* use this component to show validation messages for other form fields.
      *
      * @example
      * Label
@@ -957,7 +957,7 @@ export declare namespace Form {
          */
         interface Props extends Form.ItemProps<string[]> {
             /**
-             * The list of tag picker's items.
+             * The list of tags.
              */
             children?: ReactNode;
             /**
@@ -971,16 +971,16 @@ export declare namespace Form {
              */
             interface Props {
                 /**
-                 * Value of the tag picker item.
+                 * Value of the tag.
                  * Make sure to assign unique value for each item.
                  */
                 value: string;
                 /**
-                 * The display title of the token.
+                 * The display title of the tag.
                  */
                 title: string;
                 /**
-                 * An icon to show in the token.
+                 * An icon to show in the tag.
                  */
                 icon?: Image.ImageLike;
             }

package/types/api/components/List.d.ts

@@ -64,6 +64,35 @@ export declare namespace List {
         onSearchTextChange: PropTypes.Requireable<(...args: any[]) => any>;
         isLoading: PropTypes.Requireable<boolean>;
         navigationTitle: PropTypes.Requireable<string>;
+        actions: PropTypes.Requireable<PropTypes.ReactNodeLike>;
+    };
+    var displayName: string;
+}
+declare function ListEmptyView(props: List.EmptyView.Props): ReactElement<List.EmptyView.Props>;
+declare namespace ListEmptyView {
+    var propTypes: {
+        id: PropTypes.Requireable<string>;
+        icon: PropTypes.Requireable<string | Required<PropTypes.InferProps<{
+            fileIcon: PropTypes.Validator<string>;
+        }>> | PropTypes.InferProps<{
+            source: PropTypes.Requireable<string | PropTypes.InferProps<{
+                light: PropTypes.Validator<string>;
+                dark: PropTypes.Validator<string>;
+            }>>;
+            fallback: PropTypes.Requireable<string | PropTypes.InferProps<{
+                light: PropTypes.Validator<string>;
+                dark: PropTypes.Validator<string>;
+            }>>;
+            mask: PropTypes.Requireable<Image.Mask>;
+            tintColor: PropTypes.Requireable<string | PropTypes.InferProps<{
+                light: PropTypes.Validator<string>;
+                dark: PropTypes.Validator<string>;
+                adjustContrast: PropTypes.Requireable<boolean>;
+            }>>;
+        }>>;
+        title: PropTypes.Requireable<string>;
+        description: PropTypes.Requireable<string>;
+        actions: PropTypes.Requireable<PropTypes.ReactNodeLike>;
     };
     var displayName: string;
 }
@@ -88,7 +117,6 @@ declare namespace ListItem {
         id: PropTypes.Requireable<string>;
         title: PropTypes.Validator<string>;
         subtitle: PropTypes.Requireable<string>;
-        accessoryTitle: PropTypes.Requireable<string>;
         keywords: PropTypes.Requireable<string[]>;
         icon: PropTypes.Requireable<string | Required<PropTypes.InferProps<{
             fileIcon: PropTypes.Validator<string>;
@@ -108,6 +136,46 @@ declare namespace ListItem {
                 adjustContrast: PropTypes.Requireable<boolean>;
             }>>;
         }>>;
+        accessoryTitle: PropTypes.Requireable<string>;
+        accessoryIcon: PropTypes.Requireable<string | Required<PropTypes.InferProps<{
+            fileIcon: PropTypes.Validator<string>;
+        }>> | PropTypes.InferProps<{
+            source: PropTypes.Requireable<string | PropTypes.InferProps<{
+                light: PropTypes.Validator<string>;
+                dark: PropTypes.Validator<string>;
+            }>>;
+            fallback: PropTypes.Requireable<string | PropTypes.InferProps<{
+                light: PropTypes.Validator<string>;
+                dark: PropTypes.Validator<string>;
+            }>>;
+            mask: PropTypes.Requireable<Image.Mask>;
+            tintColor: PropTypes.Requireable<string | PropTypes.InferProps<{
+                light: PropTypes.Validator<string>;
+                dark: PropTypes.Validator<string>;
+                adjustContrast: PropTypes.Requireable<boolean>;
+            }>>;
+        }>>;
+        accessories: PropTypes.Requireable<Required<PropTypes.InferProps<{
+            text: PropTypes.Requireable<string>;
+            icon: PropTypes.Requireable<string | Required<PropTypes.InferProps<{
+                fileIcon: PropTypes.Validator<string>;
+            }>> | PropTypes.InferProps<{
+                source: PropTypes.Requireable<string | PropTypes.InferProps<{
+                    light: PropTypes.Validator<string>;
+                    dark: PropTypes.Validator<string>;
+                }>>;
+                fallback: PropTypes.Requireable<string | PropTypes.InferProps<{
+                    light: PropTypes.Validator<string>;
+                    dark: PropTypes.Validator<string>;
+                }>>;
+                mask: PropTypes.Requireable<Image.Mask>;
+                tintColor: PropTypes.Requireable<string | PropTypes.InferProps<{
+                    light: PropTypes.Validator<string>;
+                    dark: PropTypes.Validator<string>;
+                    adjustContrast: PropTypes.Requireable<boolean>;
+                }>>;
+            }>>;
+        }>>[]>;
     };
     var displayName: string;
 }
@@ -177,6 +245,45 @@ declare namespace ListDropdownItem {
     var displayName: string;
 }
 export declare namespace List {
+    /**
+     * A view to display when there aren't any items available. Use to greet users with a friendly message if the
+     * extension requires user input before it can show any list items e.g. when searching for a package, an article etc.
+     *
+     * @remarks
+     * Raycast provides a default `EmptyView` that will be displayed if the {@link List} component either has no children,
+     * or if it has children, but none of them match the query in the search bar. This too can be overridden by passing
+     * an empty view alongside the other `List.Item`s.
+     *
+     * @example
+     * import { useState } from "react";
+     * import { List } from "@raycast/api";
+     *
+     * export default function CommandWithCustomEmptyState() {
+     *   const [state, setState] = useState({ searchText: "", items: [] });
+     *
+     *   useEffect(() => {
+     *     // perform an API call that eventually populates `items`.
+     *   }, [state.searchText])
+     *
+     *   return (
+     *     <List
+     *       onSearchTextChange={(newValue) =>
+     *         setState((previous) => ({ ...previous, searchText: newValue }))
+     *       }
+     *     >
+     *       {state.searchText === "" && state.items.length === 0 ? (
+     *         <List.EmptyView
+     *           icon={{ source: "https://placekitten.com/500/500" }}
+     *           title="Type something to get started"
+     *         />
+     *       ) : (
+     *         state.items.map((item) => <List.Item key={item} title={item} />)
+     *       )}
+     *     </List>
+     *   );
+     * }
+     */
+    const EmptyView: typeof ListEmptyView;
     /**
      * A item in the {@link List}.
      *
@@ -192,7 +299,7 @@ export declare namespace List {
      * export default function Command() {
      *   return (
      *     <List>
-     *       <List.Item icon={Icon.Star} title="Augustiner Helles" subtitle="0,5 Liter" accessoryTitle="Germany" />
+     *       <List.Item icon={Icon.Star} title="Augustiner Helles" subtitle="0,5 Liter" accessories={[{ text: "Germany" }]} />
      *     </List>
      *   );
      * }
@@ -333,7 +440,55 @@ export declare namespace List {
          */
         isShowingDetail?: boolean;
     }
+    namespace EmptyView {
+        interface Props extends ActionsInterface {
+            /**
+             * An icon displayed in the center of the EmptyView.
+             *
+             * @remarks
+             * If an SVG is used, its longest side will be 128 pixels. Other images will be up/downscaled proportionally so that the longest side is between 64 and 256 pixels.
+             * If not specified, Raycast's default `EmptyView` icon will be used.
+             */
+            icon?: Image.ImageLike;
+            /**
+             * The main title displayed for the Empty View.
+             */
+            title?: string;
+            /**
+             * An optional description for why the empty view is shown.
+             */
+            description?: string;
+        }
+    }
     namespace Item {
+        /**
+         * An interface describing an accessory item in a {@link List.Item}
+         *
+         * @example
+         * ```typescript
+         * import { List } from "@raycast/api";
+         *
+         * export default function Command() {
+         *   return (
+         *     <List>
+         *       <List.Item title="An Item with Accessories" accessories={[{ text: `An Accessory Text`, icon: Icon.Hammer }, { icon: Icon.Person }, { text: "Just Do It!" }]} />
+         *     </List>
+         *   );
+         * }
+         * ```
+         */
+        interface Accessory {
+            /**
+             * An optional text that will be used as the label.
+             */
+            text?: string;
+            /**
+             * 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;
+        }
         /**
          * Props of the {@link List.Item} React component.
          */
@@ -357,17 +512,21 @@ export declare namespace List {
              */
             keywords?: string[];
             /**
-             * A optional icon displayed for the list item.
+             * An optional icon displayed for the list item.
              */
             icon?: Image.ImageLike;
             /**
-             * A optional icon displayed as accessory for the list item.
+             * @deprecated Use "accessories={[ { icon: ... } ]}" instead.
              */
             accessoryIcon?: Image.ImageLike;
             /**
-             * An additional title displayed for the item.
+             * @deprecated Use "accessories={[ { text: ... } ]}" instead.
              */
             accessoryTitle?: string;
+            /**
+             * An optional array of {@link List.Item.Accessory} items displayed on the right side in a List.Item.
+             */
+            accessories?: Accessory[];
             /**
              * An {@link ActionPanel} that will be updated for the selected list item.
              */
@@ -492,7 +651,7 @@ export declare namespace List {
                  */
                 title: string;
                 /**
-                 * A optional icon displayed for the item.
+                 * An optional icon displayed for the item.
                  */
                 icon?: Image.ImageLike;
             }

package/types/api/environment/environment.d.ts

@@ -29,6 +29,10 @@ export interface Environment {
      * Indicates whether the command is a development command (vs. an installed command from the Store).
      */
     isDevelopment: boolean;
+    /**
+     * The theme used by the Raycast application.
+     */
+    theme: "light" | "dark";
 }
 /**
  * Contains environment values such as the Raycast version, extension info, and paths.
@@ -43,6 +47,7 @@ export interface Environment {
  * console.log(`Assets path: ${environment.assetsPath}`);
  * console.log(`Support path: ${environment.supportPath}`);
  * console.log(`Is development mode: ${environment.isDevelopment}`);
+ * console.log(`Raycast theme: ${environment.theme}`);
  * ```
  */
 export declare const environment: Environment;

package/types/api/internal/rendering/node-builders/detail.d.ts

@@ -1,2 +1,4 @@
 import { RaycastElement } from "./types";
 export declare function appendDetailChildElement(detailElement: RaycastElement, childElement: RaycastElement): void;
+export declare function appendDetailMetadataChildElement(detailMetadataElement: RaycastElement, childElement: RaycastElement): void;
+export declare function appendDetailMetadataTagListChildElement(detailMetadataTagListElement: RaycastElement, childElement: RaycastElement): void;

package/types/api/internal/rendering/node-builders/forms.d.ts

@@ -1,2 +1,3 @@
 import { RaycastElement } from "./types";
 export declare function appendFormChildElement(formElement: RaycastElement, childElement: RaycastElement): void;
+export declare function appendFormDropdownChildElement(formDropdownElement: RaycastElement, childElement: RaycastElement): void;

package/types/api/internal/rendering/node-builders/list.d.ts

@@ -1,4 +1,5 @@
 import { RaycastElement } from "./types";
 export declare function appendListChildElement(listElement: RaycastElement, childElement: RaycastElement): void;
+export declare function appendListEmptyViewChildElement(listEmptyViewElement: RaycastElement, childElement: RaycastElement): void;
 export declare function appendListDropdownChildElement(listElement: RaycastElement, childElement: RaycastElement): void;
 export declare function appendListItemChildElement(listItemElement: RaycastElement, childElement: RaycastElement): void;

package/types/api/internal/rendering/node-builders/types.d.ts

@@ -1 +1 @@
-export declare const AllPropsFromChildren: PropsFromChildren[];
+export {};

package/types/api/internal/rendering/reconciler/index.d.ts

@@ -1 +1,2 @@
-export {};
+import { createInstance } from "./instance";
+export { createInstance };

package/types/api/internal/rendering/reconciler/instance.d.ts

@@ -0,0 +1,3 @@
+import { ElementNames, RaycastElement, RenderNode } from "../node-builders/types";
+export declare function createInstance(nodeName: ElementNames, props: RenderNode): RaycastElement;
+export declare function cloneInstance(instance: RaycastElement, _updatePayload: unknown, type: ElementNames, _oldProps: RenderNode, newProps: RenderNode, _workInProgress: unknown, childrenUnchanged: boolean): RaycastElement;

package/types/api/internal/utils/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./ids";
 export * from "./internal-children";
 export * from "./propTypes";
+export * from "./invariant";

package/types/api/internal/utils/invariant.d.ts

@@ -0,0 +1,4 @@
+/**
+ * If the condition is falsy, print a warning in dev mode
+ */
+export declare function invariant(condition: boolean, warning: string): boolean;

package/types/api/ui/icon.d.ts

@@ -16,6 +16,7 @@
  */
 export declare enum Icon {
     ArrowClockwise = "arrow-clockwise-16",
+    TwoArrowsClockwise = "arrow-2-clockwise-16",
     ArrowRight = "arrow-right-16",
     Binoculars = "binoculars-16",
     Bubble = "bubble-left-16",