@raycast/api 1.27.1 → 1.28.0

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

@@ -0,0 +1,275 @@
+import { ReactElement, ReactNode } from "react";
+import { Image } from "../ui";
+import { ActionsInterface, NavigationChildInterface } from "./types";
+import PropTypes from "prop-types";
+/**
+ * Displays {@link List.Section} or {@link List.Item}.
+ *
+ * @remarks
+ * The list uses built-in filtering by indexing the title of list items and additionally keywords.
+ *
+ * @example
+ * ```typescript
+ * import { List } from "@raycast/api";
+ *
+ * export default function Command() {
+ *   return (
+ *     <List navigationTitle="Search Beers" searchBarPlaceholder="Search your favorite beer">
+ *       <List.Item title="Augustiner Helles" />
+ *       <List.Item title="Camden Hells" />
+ *       <List.Item title="Leffe Blonde" />
+ *       <List.Item title="Sierra Nevada IPA" />
+ *     </List>
+ *   );
+ * }
+ * ```
+ */
+export declare function List(props: List.Props): ReactElement<List.Props>;
+export declare namespace List {
+    var propTypes: {
+        selectedItemId: PropTypes.Requireable<string>;
+        searchBarPlaceholder: PropTypes.Requireable<string>;
+        throttle: PropTypes.Requireable<boolean>;
+        onSearchTextChange: PropTypes.Requireable<(...args: any[]) => any>;
+        onSelectionChange: PropTypes.Requireable<(...args: any[]) => any>;
+    };
+    var displayName: string;
+}
+/**
+ * See {@link List.Section}
+ */
+declare function ListSection(props: List.Section.Props): ReactElement<List.Section.Props>;
+declare namespace ListSection {
+    var propTypes: {
+        id: PropTypes.Requireable<string>;
+        title: PropTypes.Requireable<string>;
+        subtitle: PropTypes.Requireable<string>;
+    };
+    var displayName: string;
+}
+/**
+ * See {@link List.Item}
+ */
+declare function ListItem(props: List.Item.Props): ReactElement<List.Item.Props>;
+declare namespace ListItem {
+    var propTypes: {
+        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>;
+        }>> | PropTypes.InferProps<{
+            source: PropTypes.Requireable<string | PropTypes.InferProps<{
+                light: PropTypes.Validator<string>;
+                dark: PropTypes.Validator<string>;
+            }>>;
+            fallback: PropTypes.Requireable<string | PropTypes.InferProps<{
+                /**
+                 * Displays {@link List.Section} or {@link List.Item}.
+                 *
+                 * @remarks
+                 * The list uses built-in filtering by indexing the title of list items and additionally keywords.
+                 *
+                 * @example
+                 * ```typescript
+                 * import { List } from "@raycast/api";
+                 *
+                 * export default function Command() {
+                 *   return (
+                 *     <List navigationTitle="Search Beers" searchBarPlaceholder="Search your favorite beer">
+                 *       <List.Item title="Augustiner Helles" />
+                 *       <List.Item title="Camden Hells" />
+                 *       <List.Item title="Leffe Blonde" />
+                 *       <List.Item title="Sierra Nevada IPA" />
+                 *     </List>
+                 *   );
+                 * }
+                 * ```
+                 */
+                light: PropTypes.Validator<string>;
+                dark: PropTypes.Validator<string>;
+            }>>;
+            /**
+             * Displays {@link List.Section} or {@link List.Item}.
+             *
+             * @remarks
+             * The list uses built-in filtering by indexing the title of list items and additionally keywords.
+             *
+             * @example
+             * ```typescript
+             * import { List } from "@raycast/api";
+             *
+             * export default function Command() {
+             *   return (
+             *     <List navigationTitle="Search Beers" searchBarPlaceholder="Search your favorite beer">
+             *       <List.Item title="Augustiner Helles" />
+             *       <List.Item title="Camden Hells" />
+             *       <List.Item title="Leffe Blonde" />
+             *       <List.Item title="Sierra Nevada IPA" />
+             *     </List>
+             *   );
+             * }
+             * ```
+             */
+            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;
+}
+export declare namespace List {
+    /**
+     * A item in the {@link List}.
+     *
+     * @remarks
+     * This is one of the foundational UI components of Raycast. A list item represents a single entity. It can be a
+     * GitHub pull request, a file, or anything else. You most likely want to perform actions on this item, so make it clear
+     * to the user what this list item is about.
+     *
+     * @example
+     * ```typescript
+     * import { Icon, List } from "@raycast/api";
+     *
+     * export default function Command() {
+     *   return (
+     *     <List>
+     *       <List.Item icon={Icon.Star} title="Augustiner Helles" subtitle="0,5 Liter" accessoryTitle="Germany" />
+     *     </List>
+     *   );
+     * }
+     * ```
+     */
+    const Item: typeof ListItem;
+    /**
+     * A group of related {@link List.Item}.
+     *
+     * @remarks
+     * Sections are a great way to structure your list. For example, group GitHub issues with the same status and order them by priority.
+     * This way, users can quickly access what is most relevant.
+     *
+     * @example
+     * ```typescript
+     * import { List } from "@raycast/api";
+     *
+     * export default function Command() {
+     *   return (
+     *     <List>
+     *       <List.Section title="Lager">
+     *         <List.Item title="Camden Hells" />
+     *       </List.Section>
+     *       <List.Section title="IPA">
+     *         <List.Item title="Sierra Nevada IPA" />
+     *       </List.Section>
+     *     </List>
+     *   );
+     * }
+     * ```
+     */
+    const Section: typeof ListSection;
+    /**
+     * Props of the {@link List} React component.
+     */
+    interface Props extends ActionsInterface, NavigationChildInterface {
+        /**
+         * List sections or items. If {@link List.Item} elements are specified, a default section is automatically created.
+         */
+        children?: ReactNode;
+        /**
+         * Callback triggered when the item selection in the list changes.
+         */
+        onSelectionChange?: (id?: string) => void;
+        /**
+         * Placeholder text that will be shown in the search bar.
+         *
+         * @defaultValue Search value...
+         */
+        searchBarPlaceholder?: string;
+        /**
+         * Selects the item with the specified id.
+         */
+        selectedItemId?: string;
+        /**
+         * Defines whether the {@link ListProps.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
+         */
+        throttle?: boolean;
+        /**
+         * Callback triggered when the search bar text changes.
+         * Note that built-in list filtering will be disabled when this callback is set.
+         */
+        onSearchTextChange?: (text: string) => void;
+    }
+    namespace Item {
+        /**
+         * Props of the {@link List.Item} React component.
+         */
+        interface Props extends ActionsInterface {
+            /**
+             * ID of the item.
+             * Make sure to assign each item a unique ID or a UUID will be auto generated.
+             */
+            id?: string;
+            /**
+             * The main title displayed for that item.
+             */
+            title: string;
+            /**
+             * An optional subtitle displayed next to the main title.
+             */
+            subtitle?: string;
+            /**
+             * An additional title displayed for the item.
+             */
+            accessoryTitle?: string;
+            /**
+             * An optional property used for providing additional indexable strings for search.
+             * When filtering the list in Raycast through the search bar, the keywords will be searched in addition to the title.
+             */
+            keywords?: string[];
+            /**
+             * A optional icon displayed for the list item.
+             */
+            icon?: Image.ImageLike;
+            /**
+             * A optional icon displayed as accessory for the list item.
+             */
+            accessoryIcon?: Image.ImageLike;
+            /**
+             * An {@link ActionPanel} that will be updated for the selected list item.
+             */
+            actions?: ReactNode | null;
+        }
+    }
+    namespace Section {
+        /**
+         * Props of the {@link List.Section} React component.
+         */
+        interface Props {
+            /**
+             * The {@link List.Item} elements of the section.
+             */
+            children?: ReactNode;
+            /**
+             * ID of the section.
+             * Make sure to assign each section a unique ID or a UUID will be auto generated.
+             */
+            id?: string;
+            /**
+             * Title displayed above the section.
+             */
+            title?: string;
+            /**
+             * An optional subtitle displayed next to the title of the section.
+             */
+            subtitle?: string;
+        }
+    }
+}
+export {};

package/types/api/components/actions/Action.d.ts

@@ -0,0 +1,396 @@
+import { ReactElement } from "react";
+import PropTypes from "prop-types";
+import { Keyboard } from "../../app";
+import { Image } from "../../ui";
+import { CopyToClipboardAction, CopyToClipboardActionProps } from "./CopyToClipboardAction";
+import { OpenAction, OpenActionProps } from "./OpenAction";
+import { OpenInBrowserAction, OpenInBrowserActionProps } from "./OpenInBrowserAction";
+import { OpenWithAction, OpenWithActionProps } from "./OpenWithAction";
+import { PasteAction, PasteActionProps } from "./PasteAction";
+import { PushAction, PushActionProps } from "./PushAction";
+import { ShowInFinderAction, ShowInFinderActionProps } from "./ShowInFinderAction";
+import { SubmitFormAction, SubmitFormActionProps } from "./SubmitFormAction";
+import { TrashAction, TrashActionProps } from "./TrashAction";
+/**
+ * A context-specific action that can be performed by the user.
+ *
+ * @remarks
+ * Assign keyboard shortcuts to items to make it easier for users to perform frequently used actions.
+ *
+ * @example
+ * ```typescript
+ * import { ActionPanel, Action, List } from "@raycast/api";
+ *
+ * export default function Command() {
+ *   return (
+ *     <List navigationTitle="Open Pull Requests">
+ *       <List.Item
+ *         title="Docs: Update API Reference"
+ *         subtitle="#1"
+ *         actions={
+ *           <ActionPanel title="#1 in raycast/extensions">
+ *             <Action.OpenInBrowser url="https://github.com/raycast/extensions/pull/1" />
+ *             <Action.CopyToClipboard title="Copy Pull Request Number" content="#1" />
+ *             <Action title="Close Pull Request" onAction={() => console.log("Close PR #1")} />
+ *           </ActionPanel>
+ *         }
+ *       />
+ *     </List>
+ *   );
+ * }
+ * ```
+ */
+export declare function Action(props: Action.Props): ReactElement<Action.Props>;
+export declare namespace Action {
+    var propTypes: {
+        id: PropTypes.Requireable<string>;
+        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>;
+            }>>;
+        }>>;
+        shortcut: PropTypes.Requireable<Required<PropTypes.InferProps<{
+            modifiers: PropTypes.Validator<string[]>;
+            key: PropTypes.Validator<string>;
+        }>>>;
+        onAction: PropTypes.Requireable<(...args: any[]) => any>;
+    };
+    var displayName: string;
+}
+export declare namespace Action {
+    /**
+     * Action that copies the content to the clipboard.
+     *
+     * @remarks
+     * The main window is closed, and a HUD is shown after the content was copied to the clipboard.
+     *
+     * @example
+     * ```typescript
+     * import { ActionPanel, Action, Detail } from "@raycast/api";
+     *
+     * export default function Command() {
+     *   return (
+     *     <Detail
+     *       markdown="Press `⌘ + .` and share some love."
+     *       actions={
+     *         <ActionPanel>
+     *           <Action.CopyToClipboard content="I ❤️ Raycast" shortcut={{ modifiers: ["cmd"], key: "." }} />
+     *         </ActionPanel>
+     *       }
+     *     />
+     *   );
+     * }
+     * ```
+     */
+    const CopyToClipboard: typeof CopyToClipboardAction;
+    /**
+     * An action to open a file or folder with a specific application, just as if you had double-clicked the
+     * file's icon.
+     *
+     * @remarks
+     * The main window is closed after the file is opened.
+     *
+     * @example
+     * ```typescript
+     * import { ActionPanel, Detail, Action } from "@raycast/api";
+     *
+     * export default function Command() {
+     *   return (
+     *     <Detail
+     *       markdown="Check out your extension code."
+     *       actions={
+     *         <ActionPanel>
+     *           <Action.Open title="Open Folder" target={__dirname} />
+     *         </ActionPanel>
+     *       }
+     *     />
+     *   );
+     * }
+     * ```
+     */
+    const Open: typeof OpenAction;
+    /**
+     * Action that opens a URL in the default browser.
+     *
+     * @remarks
+     * The main window is closed after the URL is opened in the browser.
+     *
+     * @example
+     * ```typescript
+     * import { ActionPanel, Detail, Action } from "@raycast/api";
+     *
+     * export default function Command() {
+     *   return (
+     *     <Detail
+     *       markdown="Join the gang!"
+     *       actions={
+     *         <ActionPanel>
+     *           <Action.OpenInBrowser url="https://raycast.com/jobs" />
+     *         </ActionPanel>
+     *       }
+     *     />
+     *   );
+     * }
+     * ```
+     */
+    const OpenInBrowser: typeof OpenInBrowserAction;
+    /**
+     * Action that opens a file or folder with a specific application.
+     *
+     * @remarks
+     * The action opens a sub-menu with all applications that can open the file or folder.
+     * The main window is closed after the file is opened in the specified application.
+     *
+     * @example
+     * ```typescript
+     * import { ActionPanel, Detail, Action } from "@raycast/api";
+     * import { homedir } from "os";
+     *
+     * const DESKTOP_DIR = `${homedir()}/Desktop`;
+     *
+     * export default function Command() {
+     *   return (
+     *     <Detail
+     *       markdown="What do you want to use to open your desktop with?"
+     *       actions={
+     *         <ActionPanel>
+     *           <Action.OpenWith path={DESKTOP_DIR} />
+     *         </ActionPanel>
+     *       }
+     *     />
+     *   );
+     * }
+     * ```
+     */
+    const OpenWith: typeof OpenWithAction;
+    /**
+     * Action that pastes the content to the front-most applications.
+     *
+     * @remarks
+     * The main window is closed after the content is pasted to the front-most application.
+     *
+     * @example
+     * ```typescript
+     * import { ActionPanel, Detail, Action } from "@raycast/api";
+     *
+     * export default function Command() {
+     *   return (
+     *     <Detail
+     *       markdown="Let us know what you think about the Raycast API?"
+     *       actions={
+     *         <ActionPanel>
+     *           <Action.Paste content="api@raycast.com" />
+     *         </ActionPanel>
+     *       }
+     *     />
+     *   );
+     * }
+     * ```
+     */
+    const Paste: typeof PasteAction;
+    /**
+     * Action that pushes a new view to the navigation stack.
+     *
+     * @example
+     * ```typescript
+     * import { ActionPanel, Detail, Action } from "@raycast/api";
+     *
+     * function Ping() {
+     *   return (
+     *     <Detail
+     *       markdown="Ping"
+     *       actions={
+     *         <ActionPanel>
+     *           <Action.Push title="Push Pong" target={<Pong />} />
+     *         </ActionPanel>
+     *       }
+     *     />
+     *   );
+     * }
+     *
+     * function Pong() {
+     *   return <Detail markdown="Pong" />;
+     * }
+     *
+     * export default function Command() {
+     *   return <Ping />;
+     * }
+     * ```
+     */
+    const Push: typeof PushAction;
+    /**
+     * Action that shows a file or folder in the Finder.
+     *
+     * @remarks
+     * The main window is closed after the file or folder is revealed in the Finder.
+     *
+     * @example
+     * ```typescript
+     * import { ActionPanel, Detail, Action } from "@raycast/api";
+     * import { homedir } from "os";
+     *
+     * const DOWNLOADS_DIR = `${homedir()}/Downloads`;
+     *
+     * export default function Command() {
+     *   return (
+     *     <Detail
+     *       markdown="Are your downloads pilling up again?"
+     *       actions={
+     *         <ActionPanel>
+     *           <Action.ShowInFinder path={DOWNLOADS_DIR} />
+     *         </ActionPanel>
+     *       }
+     *     />
+     *   );
+     * }
+     * ```
+     */
+    const ShowInFinder: typeof ShowInFinderAction;
+    /**
+     * Action that adds a submit handler for capturing form values.
+     *
+     * @example
+     * ```typescript
+     * import { ActionPanel, Form, Action } from "@raycast/api";
+     * import { useState } from "react";
+     *
+     * export default function Command() {
+     *   const [name, setName] = useState<string>();
+     *
+     *   return (
+     *     <Form
+     *       actions={
+     *         <ActionPanel>
+     *           <Action.SubmitForm title="Submit Name" onSubmit={(values) => console.log(values)} />
+     *         </ActionPanel>
+     *       }
+     *     >
+     *       <Form.TextField id="name" value={name} onChange={setName} />
+     *     </Form>
+     *   );
+     * }
+     * ```
+     */
+    const SubmitForm: typeof SubmitFormAction;
+    /**
+     * Action that moves a file or folder to the Trash.
+     *
+     * @example
+     * ```typescript
+     * import { ActionPanel, Detail, Action } from "@raycast/api";
+     * import { homedir } from "os";
+     *
+     * const FILE = `${homedir()}/Downloads/get-rid-of-me.txt`;
+     *
+     * export default function Command() {
+     *   return (
+     *     <Detail
+     *       markdown="Some spring cleaning?"
+     *       actions={
+     *         <ActionPanel>
+     *           <Action.Trash paths={FILE} />
+     *         </ActionPanel>
+     *       }
+     *     />
+     *   );
+     * }
+     * ```
+     */
+    const Trash: typeof TrashAction;
+    /**
+     * Props of the {@link Action} React component.
+     */
+    interface Props {
+        /**
+         * ID of the item.
+         *
+         * @remarks
+         * Make sure to assign each section or item a unique ID. If no ID is specified, a memoized auto-generated is used.
+         */
+        id?: string;
+        /**
+         * The title displayed for the item.
+         */
+        title: string;
+        /**
+         * The icon displayed for the action.
+         */
+        icon?: Image.ImageLike;
+        /**
+         * The keyboard shortcut for the item.
+         */
+        shortcut?: Keyboard.Shortcut;
+        /**
+         * Callback that is triggered when the item is selected.
+         */
+        onAction?: () => void;
+    }
+    namespace CopyToClipboard {
+        /**
+         * Props of the {@link Action.CopyToClipboard} React component.
+         */
+        type Props = CopyToClipboardActionProps;
+    }
+    namespace Open {
+        /**
+         * Props of the {@link Action.Open} React component.
+         */
+        type Props = OpenActionProps;
+    }
+    namespace OpenInBrowser {
+        /**
+         * Props of the {@link Action.OpenInBrowser} React component.
+         */
+        type Props = OpenInBrowserActionProps;
+    }
+    namespace OpenWith {
+        /**
+         * Props of the {@link Action.OpenWith} React component.
+         */
+        type Props = OpenWithActionProps;
+    }
+    namespace Paste {
+        /**
+         * Props of the {@link Action.Paste} React component.
+         */
+        type Props = PasteActionProps;
+    }
+    namespace Push {
+        /**
+         * Props of the {@link Action.Push} React component.
+         */
+        type Props = PushActionProps;
+    }
+    namespace ShowInFinder {
+        /**
+         * Props of the {@link Action.ShowInFinder} React component.
+         */
+        type Props = ShowInFinderActionProps;
+    }
+    namespace SubmitForm {
+        /**
+         * Props of the {@link Action.SubmitForm} React component.
+         */
+        type Props<T> = SubmitFormActionProps<T>;
+    }
+    namespace Trash {
+        /**
+         * Props of the {@link Action.Trash} React component.
+         */
+        type Props = TrashActionProps;
+    }
+}

package/types/api/components/actions/CopyToClipboardAction.d.ts

@@ -0,0 +1,39 @@
+import { ReactElement } from "react";
+import { Keyboard } from "../../app";
+import { Image } from "../../ui";
+/**
+ * See {@link Action.CopyToClipboard.Props}
+ */
+export interface CopyToClipboardActionProps {
+    /**
+     * The contents that will be written to the clipboard as string.
+     */
+    content: string | number;
+    /**
+     * An optional title for the action.
+     */
+    title?: string;
+    /**
+     * A optional icon displayed for the item.
+     * @defaultValue {@link Icon.Clipboard}
+     */
+    icon?: Image.ImageLike;
+    /**
+     * The keyboard shortcut for the action.
+     */
+    shortcut?: Keyboard.Shortcut;
+    /**
+     * Callback when the content was copied to clipboard.
+     *
+     * @remarks
+     * This is handy when you want to act on the copied content, e.g. up-rank recently copied content.
+     */
+    onCopy?: (content: string | number) => void;
+}
+/**
+ * See {@link Action.CopyToClipboard}
+ */
+export declare function CopyToClipboardAction(props: CopyToClipboardActionProps): ReactElement<CopyToClipboardActionProps>;
+export declare namespace CopyToClipboardAction {
+    var displayName: string;
+}