@raycast/api 1.27.1 → 1.28.0

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

@@ -0,0 +1,297 @@
+import { ReactElement, ReactNode } from "react";
+import { Keyboard } from "../app";
+import { Image } from "../ui";
+import PropTypes from "prop-types";
+import { Action } from "./actions";
+/**
+ * Exposes a list of actions that can be performed by the user.
+ *
+ * @remarks
+ * Often items are context-aware, e.g. based on the selected list item. Actions can be grouped into semantic
+ * section and can have keyboard shortcuts assigned.
+ *
+ * The first and second action become the primary and secondary action. They automatically get the default keyboard shortcuts assigned.
+ * In {@link List} and {@link Detail}, this is `↵` for the primary and `⌘` `↵` for the secondary action. In {@link Form} it's `⌘` `↵` for the primary and
+ * `⌘` `⇧` `↵` for the secondary.
+ *
+ * @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 URL"
+ *               content="https://github.com/raycast/extensions/pull/1"
+ *             />
+ *           </ActionPanel>
+ *         }
+ *       />
+ *     </List>
+ *   );
+ * }
+ * ```
+ */
+export declare function ActionPanel(props: ActionPanel.Props): ReactElement<ActionPanel.Props>;
+export declare namespace ActionPanel {
+    var propTypes: {
+        title: PropTypes.Requireable<string>;
+    };
+    var displayName: string;
+}
+/**
+ * See {@link ActionPanel.Section}
+ */
+declare function ActionPanelSection(props: ActionPanel.Section.Props): ReactElement<ActionPanel.Section.Props>;
+declare namespace ActionPanelSection {
+    var propTypes: {
+        title: PropTypes.Requireable<string>;
+    };
+    var displayName: string;
+}
+/**
+ * See {@link ActionPanel.Submenu}
+ */
+declare function ActionPanelSubmenu(props: ActionPanel.Submenu.Props): ReactElement<Action.Props>;
+declare namespace ActionPanelSubmenu {
+    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>;
+            }>>;
+            /**
+             * Exposes a list of actions that can be performed by the user.
+             *
+             * @remarks
+             * Often items are context-aware, e.g. based on the selected list item. Actions can be grouped into semantic
+             * section and can have keyboard shortcuts assigned.
+             *
+             * The first and second action become the primary and secondary action. They automatically get the default keyboard shortcuts assigned.
+             * In {@link List} and {@link Detail}, this is `↵` for the primary and `⌘` `↵` for the secondary action. In {@link Form} it's `⌘` `↵` for the primary and
+             * `⌘` `⇧` `↵` for the secondary.
+             *
+             * @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 URL"
+             *               content="https://github.com/raycast/extensions/pull/1"
+             *             />
+             *           </ActionPanel>
+             *         }
+             *       />
+             *     </List>
+             *   );
+             * }
+             * ```
+             */
+            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>;
+        }>>>;
+    };
+    var displayName: string;
+}
+export declare namespace ActionPanel {
+    /**
+     * @deprecated Use `Action` instead.
+     */
+    const Item: typeof Action;
+    /**
+     * A group of visually separated items.
+     *
+     * @remarks
+     * Use sections if the {@link ActionPanel} contains a lot of actions to help guide the user to related actions.
+     * For example, create a section for all copy 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">
+     *             <ActionPanel.Section title="Copy">
+     *               <Action.CopyToClipboard title="Copy Pull Request Number" content="#1" />
+     *               <Action.CopyToClipboard
+     *                 title="Copy Pull Request URL"
+     *                 content="https://github.com/raycast/extensions/pull/1"
+     *               />
+     *               <Action.CopyToClipboard title="Copy Pull Request Title" content="Docs: Update API Reference" />
+     *             </ActionPanel.Section>
+     *             <ActionPanel.Section title="Danger zone">
+     *               <Action title="Close Pull Request" onAction={() => console.log("Close PR #1")} />
+     *             </ActionPanel.Section>
+     *           </ActionPanel>
+     *         }
+     *       />
+     *     </List>
+     *   );
+     * }
+     * ```
+     */
+    const Section: typeof ActionPanelSection;
+    /**
+     * An action that replaces the current ActionPanel with its children when selected.
+     *
+     * @remarks
+     * This is handy when an action needs to select from a range of options. For example, to add a label to a GitHub pull request
+     * or an assignee to a todo.
+     *
+     * @example
+     * ```typescript
+     * import { ActionPanel, Color, Icon, List, Action } 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">
+     *             <ActionPanel.Submenu title="Add Label">
+     *               <Action
+     *                 icon={{ source: Icon.Circle, tintColor: Color.Red }}
+     *                 title="Bug"
+     *                 onAction={() => console.log("Add bug label")}
+     *               />
+     *               <Action
+     *                 icon={{ source: Icon.Circle, tintColor: Color.Yellow }}
+     *                 title="Enhancement"
+     *                 onAction={() => console.log("Add enhancement label")}
+     *               />
+     *               <Action
+     *                 icon={{ source: Icon.Circle, tintColor: Color.Blue }}
+     *                 title="Help Wanted"
+     *                 onAction={() => console.log("Add help wanted label")}
+     *               />
+     *             </ActionPanel.Submenu>
+     *           </ActionPanel>
+     *         }
+     *       />
+     *     </List>
+     *   );
+     * }
+     * ```
+     */
+    const Submenu: typeof ActionPanelSubmenu;
+    /**
+     * Props of the {@link ActionPanel} React component.
+     */
+    interface Props {
+        /**
+         * Sections or Actions. If {@link Action} elements are specified, a default section is automatically created.
+         */
+        children?: ReactNode;
+        /**
+         * The title displayed at the top of the panel
+         */
+        title?: string;
+    }
+    /**
+     * Supported children for the {@link ActionPanel} components.
+     */
+    type Children = ReactElement<ActionPanel.Section.Props> | ReactElement<ActionPanel.Section.Props>[] | ActionPanel.Section.Children | null;
+    namespace Section {
+        /**
+         * Props of the {@link ActionPanel.Section} React component.
+         */
+        interface Props {
+            /**
+             * The item elements of the section.
+             */
+            children?: ReactNode;
+            /**
+             * Title displayed above the section
+             */
+            title?: string;
+        }
+        /**
+         * Supported children for the {@link ActionPanel.Section} component.
+         */
+        type Children = ReactElement<Action.Props> | ReactElement<Action.Props>[] | ReactElement<ActionPanel.Submenu.Props> | Array<ReactElement<ActionPanel.Submenu.Props>> | Array<ReactElement<ActionPanel.Submenu.Props> | ReactElement<Action.Props>> | null;
+    }
+    namespace Submenu {
+        /**
+         * Props of the {@link ActionPanel.Submenu} React component.
+         */
+        interface Props {
+            /**
+             * ID of the submenu.
+             * Make sure to assign each submenu a unique ID or a UUID will be auto-generated.
+             */
+            id?: string;
+            /**
+             * The title displayed for submenu.
+             */
+            title: string;
+            /**
+             * The icon displayed for the submenu.
+             */
+            icon?: Image.ImageLike;
+            /**
+             * The keyboard shortcut for the submenu.
+             */
+            shortcut?: Keyboard.Shortcut;
+            /**
+             * Items of the submenu.
+             *
+             * @example
+             * ```typescript
+             * <ActionPanel.Submenu title="Submenu">
+             *    <Action title="Just an action" />
+             * </ActionPanel.Submenu>
+             * ```
+             *
+             * @remarks
+             * If {@link Action} elements are specified, a default section is automatically created.\
+             * Use {@link ActionPanel.Submenu} as parent when specifying sub-menu's children to make code is more readable.
+             */
+            children?: ReactNode;
+        }
+        /**
+         * Supported children for the {@link ActionPanel.Submenu} components.
+         */
+        type Children = ActionPanel.Children;
+    }
+}
+export {};

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

@@ -0,0 +1,40 @@
+import { ReactElement, ReactNode } from "react";
+import { ActionsInterface, NavigationChildInterface } from "./types";
+import PropTypes from "prop-types";
+/**
+ * Renders a markdown (CommonMark) string.
+ *
+ * @remarks
+ * Typically used as a standalone view or when navigating from a {@link List}.
+ *
+ * @example
+ * ```typescript
+ * import { Detail } from "@raycast/api";
+ *
+ * export default function Command() {
+ *   return <Detail markdown="**Hello** _World_!" />;
+ * }
+ * ```
+ */
+export declare function Detail(props: Detail.Props): ReactElement<Detail.Props>;
+export declare namespace Detail {
+    var propTypes: {
+        navigationTitle: PropTypes.Requireable<string>;
+        isLoading: PropTypes.Requireable<boolean>;
+        markdown: PropTypes.Requireable<string>;
+    };
+    var displayName: string;
+}
+export declare namespace Detail {
+    /**
+     * Props of the {@link Detail} React component.
+     */
+    interface Props extends ActionsInterface, NavigationChildInterface {
+        /**
+         * The CommonMark string to be rendered.
+         */
+        markdown?: string | null;
+        /** @deprecated - Use the `markdown` prop instead */
+        children?: ReactNode;
+    }
+}