@raycast/api - npm Package Compare versions

Comparing version 1.30.3 to 1.31.0

package.json

 {
   "name": "@raycast/api",
-  "version": "1.30.3",
+  "version": "1.31.0",
   "description": "Build extensions for Raycast with React and Node.js.",
@@ -5,0 +5,0 @@ "author": "Raycast Technologies Ltd.",

types/api/components/Detail.d.ts

@@ -1,4 +0,5 @@
-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";
 /**
@@ -25,5 +26,107 @@ * Renders a markdown (CommonMark) string.
         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;
+}
 export declare namespace Detail {
@@ -38,3 +141,125 @@ /**
         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 {};

types/api/components/Form.d.ts

@@ -738,3 +738,3 @@ import { ReactElement, ReactNode } from "react";
      *
-     * @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.
      *
@@ -961,3 +961,3 @@ * @example
             /**
-             * The list of tag picker's items.
+             * The list of tags.
              */
@@ -976,3 +976,3 @@ children?: ReactNode;
                 /**
-                 * Value of the tag picker item.
+                 * Value of the tag.
                  * Make sure to assign unique value for each item.
@@ -982,7 +982,7 @@ */
                 /**
-                 * 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.
                  */
@@ -989,0 +989,0 @@ icon?: Image.ImageLike;

types/api/components/List.d.ts

@@ -67,5 +67,34 @@ import { ReactElement, ReactNode } from "react";
         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;
+}
 /**
@@ -92,3 +121,2 @@ * See {@link List.Section}
         subtitle: PropTypes.Requireable<string>;
-        accessoryTitle: PropTypes.Requireable<string>;
         keywords: PropTypes.Requireable<string[]>;
@@ -113,2 +141,42 @@ icon: PropTypes.Requireable<string | Required<PropTypes.InferProps<{
         }>>;
+        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>;
+                }>>;
+            }>>;
+        }>>[]>;
     };
@@ -184,2 +252,41 @@ var displayName: string;
     /**
+     * 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}.
@@ -199,3 +306,3 @@ *
      *     <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>
@@ -341,4 +448,52 @@ *   );
     }
+    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.
@@ -366,14 +521,18 @@ */
             /**
-             * 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.
@@ -502,3 +661,3 @@ */
                 /**
-                 * A optional icon displayed for the item.
+                 * An optional icon displayed for the item.
                  */
@@ -505,0 +664,0 @@ icon?: Image.ImageLike;

types/api/environment/environment.d.ts

@@ -32,2 +32,6 @@ /**
     isDevelopment: boolean;
+    /**
+     * The theme used by the Raycast application.
+     */
+    theme: "light" | "dark";
 }
@@ -47,4 +51,5 @@ /**
  * console.log(`Is development mode: ${environment.isDevelopment}`);
+ * console.log(`Raycast theme: ${environment.theme}`);
  * ```
  */
 export declare const environment: Environment;

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

 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;

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

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

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

 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;

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

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

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

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

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

 export * from "./ids";
 export * from "./internal-children";
 export * from "./propTypes";
+export * from "./invariant";

types/api/ui/icon.d.ts

@@ -19,2 +19,3 @@ /**
     ArrowClockwise = "arrow-clockwise-16",
+    TwoArrowsClockwise = "arrow-2-clockwise-16",
     ArrowRight = "arrow-right-16",
@@ -21,0 +22,0 @@ Binoculars = "binoculars-16",

No alert changes

Improved metrics

Number of package files

82

increased by1.23%

Worsened metrics

Total package byte prevSize

26092755

decreased by-0.38%

Lines of code

5169

decreased by-41.15%

No dependency changes