@raycast/api 1.27.0 → 1.29.0

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

@@ -0,0 +1,48 @@
+/**
+ * Holds data about the environment the command is running in. Use the global {@link environment} object to retrieve values.
+ */
+export interface Environment {
+    /**
+     * The version of the main Raycast app
+     */
+    raycastVersion: string;
+    /**
+     * The name of the extension, as specified in package.json
+     */
+    extensionName: string;
+    /**
+     * The name of the launched command, as specified in package.json
+     */
+    commandName: string;
+    /**
+     * The absolute path to the assets directory of the extension.
+     *
+     * @remarks
+     * This directory is used internally to load icons, images, and other bundled assets.
+     */
+    assetsPath: string;
+    /**
+     * The absolute path for the support directory of an extension. Use it to read and write files related to your extension or command.
+     */
+    supportPath: string;
+    /**
+     * Indicates whether the command is a development command (vs. an installed command from the Store).
+     */
+    isDevelopment: boolean;
+}
+/**
+ * Contains environment values such as the Raycast version, extension info, and paths.
+ *
+ * @example
+ * ```typescript
+ * import { environment } from "@raycast/api";
+ *
+ * console.log(`Raycast version: ${environment.raycastVersion}`);
+ * console.log(`Extension name: ${environment.extensionName}`);
+ * console.log(`Command name: ${environment.commandName}`);
+ * console.log(`Assets path: ${environment.assetsPath}`);
+ * console.log(`Support path: ${environment.supportPath}`);
+ * console.log(`Is development mode: ${environment.isDevelopment}`);
+ * ```
+ */
+export declare const environment: Environment;

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

@@ -0,0 +1,3 @@
+export * from "./environment";
+export * from "./preferences";
+export * from "./workspace";

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

@@ -0,0 +1,31 @@
+/**
+ * Values of preference items.
+ */
+export interface PreferenceValues {
+    [name: string]: any;
+}
+/**
+ * A function to access the preference values that have been passed to the command.
+ *
+ * @returns An object with the preference names as property key and the typed value as property value.
+ *
+ * @remarks
+ * Each preference name is mapped to its value and the defined default values are used as fallback values.
+ *
+ * @example
+ * ```typescript
+ * import { getPreferenceValues } from "@raycast/api";
+ *
+ * interface Preferences {
+ *   name: string;
+ *   bodyWeight?: string;
+ *   bodyHeight?: string;
+ * }
+ *
+ * export default async () => {
+ *   const preferences = getPreferenceValues<Preferences>();
+ *   console.log(preferences);
+ * };
+ * ```
+ */
+export declare function getPreferenceValues<Values extends PreferenceValues = PreferenceValues>(): Values;

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

@@ -0,0 +1,62 @@
+/**
+ * Gets the selected text of the frontmost application.
+ *
+ * @throws An error when no text is selected in the frontmost application.
+ * @returns A Promise that resolves with the selected text.
+ *
+ * @example
+ * ```typescript
+ * import { getSelectedText, Clipboard, showToast, Toast } from "@raycast/api";
+ *
+ * export default async () => {
+ *   try {
+ *     const selectedText = await getSelectedText();
+ *     const transformedText = selectedText.toUpperCase();
+ *     await Clipboard.paste(transformedText);
+ *   } catch (error) {
+ *     await showToast({
+ *       style: Toast.Style.Failure,
+ *       title: "Cannot transform text",
+ *       message: String(error)
+ *     });
+ *   }
+ * };
+ * ```
+ */
+export declare function getSelectedText(): Promise<string>;
+/**
+ * Holds data about a File System item. Use the {@link getSelectedFinderItems} method to retrieve values.
+ */
+export interface FileSystemItem {
+    /**
+     * The path to the item
+     */
+    path: string;
+}
+/**
+ * Gets the selected items from Finder.
+ *
+ * @throws An error when Finder is not the frontmost application.
+ * @returns A Promise that resolves with the selected file system items.
+ *
+ * @example
+ * ```typescript
+ * import { getSelectedFinderItems, Clipboard, showToast, Toast } from "@raycast/api";
+ *
+ * export default async () => {
+ *   try {
+ *     const selectedItems = await getSelectedFinderItems();
+ *     if (selectedItems.length) {
+ *       await Clipboard.paste(selectedItems[0].path);
+ *     }
+ *   } catch (error) {
+ *     await showToast({
+ *       style: Toast.Style.Failure,
+ *       title: "Cannot copy file path",
+ *       message: String(error)
+ *     });
+ *   }
+ * };
+ * ```
+ */
+export declare function getSelectedFinderItems(): Promise<FileSystemItem[]>;

package/types/api/hooks/index.d.ts

@@ -0,0 +1 @@
+export * from "./useNavigation";

package/types/api/hooks/useNavigation.d.ts

@@ -0,0 +1,66 @@
+import { ReactNode } from "react";
+/**
+ * Return type of the {@link useNavigation} hook to perform push and pop actions.
+ */
+export interface Navigation {
+    /**
+     * Push a new view component to the navigation stack.
+     *
+     * @param component - The React component to push to the navigation stack.
+     */
+    push: (component: ReactNode) => void;
+    /**
+     * Pop current view component from the navigation stack.
+     */
+    pop: () => void;
+}
+/**
+ * A hook that lets you push and pop view components in the navigation stack.
+ *
+ * @remarks
+ * You most likely won't use this hook too often. To push a new component, use the {@link PushAction}.
+ * When a user presses `ESC`, we automatically push to the previous component.
+ *
+ * @returns A {@link Navigation} object with {@link Navigation.push} and {@link Navigation.pop} functions.
+ * Use the functions to alter the navigation stack.
+ *
+ * @example
+ * ```typescript
+ * import { ActionPanel, Detail, useNavigation, Action } from "@raycast/api";
+ *
+ * function Ping() {
+ *   const { push } = useNavigation();
+ *
+ *   return (
+ *     <Detail
+ *       markdown="Ping"
+ *       actions={
+ *         <ActionPanel>
+ *           <Action title="Push" onAction={() => push(<Pong />)} />
+ *         </ActionPanel>
+ *       }
+ *     />
+ *   );
+ * }
+ *
+ * function Pong() {
+ *   const { pop } = useNavigation();
+ *
+ *   return (
+ *     <Detail
+ *       markdown="Pong"
+ *       actions={
+ *         <ActionPanel>
+ *           <Action title="Pop" onAction={pop} />
+ *         </ActionPanel>
+ *       }
+ *     />
+ *   );
+ * }
+ *
+ * export default function Command() {
+ *   return <Ping />;
+ * }
+ * ```
+ */
+export declare function useNavigation(): Navigation;

package/types/api/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./app";
+export * from "./components";
+export * from "./environment";
+export * from "./hooks";
+export * from "./ui";
+export * from "./deprecated";

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

@@ -0,0 +1 @@
+export {};

package/types/api/internal/components/ErrorBoundary.d.ts

@@ -0,0 +1 @@
+export {};

package/types/api/internal/components/Navigation.d.ts

@@ -0,0 +1 @@
+export {};

package/types/api/internal/components/Root.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,4 @@
+export * from "./portal";
+export * from "./ErrorBoundary";
+export * from "./Navigation";
+export * from "./Root";

package/types/api/internal/components/portal/components/portal/Portal.d.ts

@@ -0,0 +1,4 @@
+/// <reference types="react" />
+import type { PortalProps } from './types';
+declare const Portal: import("react").MemoExoticComponent<({ name: _providedName, hostName, handleOnMount, handleOnUnmount, children, }: PortalProps) => any>;
+export default Portal;

package/types/api/internal/components/portal/components/portal/index.d.ts

@@ -0,0 +1 @@
+export { default } from './Portal';

package/types/api/internal/components/portal/components/portalHost/PortalHost.d.ts

@@ -0,0 +1,4 @@
+import React from 'react';
+import type { PortalHostProps } from './types';
+declare const PortalHost: React.MemoExoticComponent<({ name }: PortalHostProps) => JSX.Element>;
+export default PortalHost;

package/types/api/internal/components/portal/components/portalHost/index.d.ts

@@ -0,0 +1 @@
+export { default } from './PortalHost';

package/types/api/internal/components/portal/components/portalProvider/PortalProvider.d.ts

@@ -0,0 +1,4 @@
+import React from 'react';
+import type { PortalProviderProps } from './types';
+declare const PortalProvider: React.MemoExoticComponent<({ children }: PortalProviderProps) => JSX.Element>;
+export default PortalProvider;

package/types/api/internal/components/portal/components/portalProvider/index.d.ts

@@ -0,0 +1 @@
+export { default } from './PortalProvider';

package/types/api/internal/components/portal/contexts/index.d.ts

@@ -0,0 +1 @@
+export { PortalDispatchContext, PortalStateContext } from './portal';

package/types/api/internal/components/portal/contexts/portal.d.ts

@@ -0,0 +1,5 @@
+/// <reference types="react" />
+import type { ActionTypes } from '../state';
+import type { PortalType } from '../types';
+export declare const PortalStateContext: import("react").Context<Record<string, PortalType[]>>;
+export declare const PortalDispatchContext: import("react").Context<import("react").Dispatch<ActionTypes>>;

package/types/api/internal/components/portal/hooks/index.d.ts

@@ -0,0 +1,2 @@
+export { usePortal } from './usePortal';
+export { usePortalState } from './usePortalState';

package/types/api/internal/components/portal/hooks/usePortal.d.ts

@@ -0,0 +1,8 @@
+import { ReactNode } from 'react';
+export declare const usePortal: (hostName?: string) => {
+    registerHost: () => void;
+    deregisterHost: () => void;
+    addPortal: (name: string, node: ReactNode) => void;
+    updatePortal: (name: string, node: ReactNode) => void;
+    removePortal: (name: string) => void;
+};

package/types/api/internal/components/portal/hooks/usePortalState.d.ts

@@ -0,0 +1 @@
+export declare const usePortalState: (hostName: string) => import("../types").PortalType[];

package/types/api/internal/components/portal/index.d.ts

@@ -0,0 +1,5 @@
+export { default as Portal } from './components/portal';
+export { default as PortalHost } from './components/portalHost';
+export { default as PortalProvider } from './components/portalProvider';
+export { usePortal } from './hooks/usePortal';
+export { enableLogging } from './utilities/logger';

package/types/api/internal/components/portal/state/constants.d.ts

@@ -0,0 +1,9 @@
+declare enum ACTIONS {
+    REGISTER_HOST = 0,
+    DEREGISTER_HOST = 1,
+    ADD_PORTAL = 2,
+    UPDATE_PORTAL = 3,
+    REMOVE_PORTAL = 4
+}
+declare const INITIAL_STATE: {};
+export { ACTIONS, INITIAL_STATE };

package/types/api/internal/components/portal/state/index.d.ts

@@ -0,0 +1,3 @@
+export { reducer } from './reducer';
+export { ACTIONS, INITIAL_STATE } from './constants';
+export type { ActionTypes } from './types';

package/types/api/internal/components/portal/state/reducer.d.ts

@@ -0,0 +1,3 @@
+import type { PortalType } from '../types';
+import type { ActionTypes } from './types';
+export declare const reducer: (state: Record<string, Array<PortalType>>, action: ActionTypes) => Record<string, PortalType[]>;

package/types/api/internal/components/portal/utilities/logger.d.ts

@@ -0,0 +1,9 @@
+interface PrintOptions {
+    component?: string;
+    method?: string;
+    params?: Record<string, any> | string | number | boolean;
+}
+declare type Print = (options: PrintOptions) => void;
+declare const enableLogging: () => void;
+declare let print: Print;
+export { print, enableLogging };

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

@@ -0,0 +1 @@
+export * from "./react";

package/types/api/internal/devtools/react.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,2 @@
+export * from "./useId";
+export * from "./useActionPanel";

package/types/api/internal/hooks/useActionPanel.d.ts

@@ -0,0 +1 @@
+export {};

package/types/api/internal/hooks/useId.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,6 @@
+export * from "./comm";
+export * from "./components";
+export * from "./devtools";
+export * from "./hooks";
+export * from "./rendering";
+export * from "./utils";

package/types/api/internal/rendering/callbacks.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,6 @@
+export * from "./renderer";
+export { apiCallbacks } from "./callbacks";
+export * from "./reconciler";
+export type { FormValueModel } from "./node-builders/forms";
+export { wrapImageIfNeeded } from "./node-builders/utils";
+export { specialKeys } from "./node-builders/keyboard";

package/types/api/internal/rendering/logger.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,3 @@
+import { RaycastElement } from "./types";
+export declare function appendActionPanelChildElement(actionPanelElement: RaycastElement, childElement: RaycastElement): void;
+export declare function appendActionPanelSubmenuChildElement(actionPanelElement: RaycastElement, childElement: RaycastElement): void;

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,2 @@
+import { RaycastElement } from "./types";
+export declare function appendListChildElement(listElement: RaycastElement, childElement: RaycastElement): void;

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+export {};

package/types/api/internal/rendering/renderer.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+export * from "./ids";

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

@@ -0,0 +1,115 @@
+/**
+ * The standard colors. Use those colors for consistency.
+ *
+ * @remarks
+ * The colors automatically adapt to the Raycast theme (light or dark).
+ *
+ * @example
+ * ```typescript
+ * import { Color, Icon, List } from "@raycast/api";
+ *
+ * export default function Command() {
+ *  return (
+ *  <List>
+ *    <List.Item title="Blue" icon={{ source: Icon.Circle, tintColor: Color.Blue }} />
+ *    <List.Item title="Green" icon={{ source: Icon.Circle, tintColor: Color.Green }} />
+ *    <List.Item title="Brown" icon={{ source: Icon.Circle, tintColor: Color.Brown }} />
+ *    <List.Item title="Magenta" icon={{ source: Icon.Circle, tintColor: Color.Magenta }} />
+ *    <List.Item title="Orange" icon={{ source: Icon.Circle, tintColor: Color.Orange }} />
+ *    <List.Item title="Purple" icon={{ source: Icon.Circle, tintColor: Color.Purple }} />
+ *    <List.Item title="Red" icon={{ source: Icon.Circle, tintColor: Color.Red }} />
+ *    <List.Item title="Yellow" icon={{ source: Icon.Circle, tintColor: Color.Yellow }} />
+ *    <List.Item title="PrimaryText" icon={{ source: Icon.Circle, tintColor: Color.PrimaryText }} />
+ *    <List.Item title="SecondaryText" icon={{ source: Icon.Circle, tintColor: Color.SecondaryText }} />
+ *  </List>
+ *  );
+ * };
+ * ```
+ */
+export declare enum Color {
+    Blue = "raycast-blue",
+    Brown = "raycast-brown",
+    Green = "raycast-green",
+    Magenta = "raycast-magenta",
+    Orange = "raycast-orange",
+    Purple = "raycast-purple",
+    Red = "raycast-red",
+    Yellow = "raycast-yellow",
+    PrimaryText = "raycast-primary-text",
+    SecondaryText = "raycast-secondary-text"
+}
+export declare namespace Color {
+    /**
+     * Union type for the supported color types.
+     *
+     * {@link Color.Raw} will be dynamically adjusted to achieve high contrast with the Raycast user interface.
+     *
+     * @example
+     * ```typescript
+     * import { Color, Icon, List } from "@raycast/api";
+     *
+     * export default function Command() {
+     *   return (
+     *     <List>
+     *       <List.Item title="Built-in color" icon={{ source: Icon.Circle, tintColor: Color.Red }} />
+     *       <List.Item title="HEX" icon={{ source: Icon.Circle, tintColor: "#FF0000" }} />
+     *       <List.Item title="Short HEX" icon={{ source: Icon.Circle, tintColor: "#F00" }} />
+     *       <List.Item title="RGBA" icon={{ source: Icon.Circle, tintColor: "rgb(255, 0, 0)" }} />
+     *       <List.Item title="RGBA Percentage" icon={{ source: Icon.Circle, tintColor: "rgb(255, 0, 0, 1.0)" }} />
+     *       <List.Item title="HSL" icon={{ source: Icon.Circle, tintColor: "hsla(200, 20%, 33%, 0.2)" }} />
+     *       <List.Item title="Keywords" icon={{ source: Icon.Circle, tintColor: "red" }} />
+     *     </List>
+     *   );
+     * };
+     * ```
+     */
+    type ColorLike = Color | Color.Dynamic | Color.Raw;
+    /**
+     * A dynamic color applies different colors depending on the active Raycast theme.
+     *
+     * @example
+     * ```typescript
+     * import { Color, Icon, List } from "@raycast/api";
+     *
+     * export default function Command() {
+     *  return (
+     *  <List>
+     *    <List.Item title="Dynamic Tint Color" icon={{ source: Icon.Circle, tintColor: { light: "#FF01FF", dark: "#FFFF50", adjustContrast: true } }} />
+     *    <List.Item title="Dynamic Tint Color" icon={{ source: Icon.Circle, tintColor: { light: "#FF01FF", dark: "#FFFF50" } }} />
+     *  </List>
+     *  );
+     * };
+     * ```
+     */
+    interface Dynamic {
+        /**
+         * The color which is used in light theme.
+         */
+        light: Color.Raw;
+        /**
+         * The color which is used in dark theme.
+         */
+        dark: Color.Raw;
+        /**
+         * Enables dynamic contrast adjustment for light and dark theme color.
+         *
+         * @remarks
+         * Colors different to the built-in {@link Color} can be dynamically adjusted to achieve high contrast with the
+         * 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
+         */
+        adjustContrast?: boolean;
+    }
+    /**
+     * You can use any of the following color formats:
+     * - HEX, e.g `#FF0000`
+     * - Short HEX, e.g. `#F00`
+     * - RGBA, e.g. `rgb(255, 0, 0)`
+     * - RGBA Percentage, e.g. `rgb(255, 0, 0, 1.0)`
+     * - HSL, e.g. `hsla(200, 20%, 33%, 0.2)`
+     * - Keywords, e.g. `red`
+     */
+    type Raw = string;
+}

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

@@ -0,0 +1 @@
+export {};

package/types/api/ui/feedback/alert.d.ts

@@ -0,0 +1,97 @@
+import { Image } from "../image";
+/**
+ * Creates and shows a confirmation Alert with the given options.
+ *
+ * @param options - The options used to create the Alert.
+ * @returns A Promise that resolves to a boolean when the user triggers one of the actions.
+ * It will be `true` for the primary Action, `false` for the dismiss Action.
+ *
+ * @example
+ * ```typescript
+ * import { confirmAlert } from "@raycast/api";
+ *
+ * export default async () => {
+ *   if (await confirmAlert({ title: "Are you sure?" })) {
+ *     // do something
+ *   }
+ * };
+ * ```
+ */
+export declare function confirmAlert(options: Alert.Options): Promise<boolean>;
+export declare namespace Alert {
+    /**
+     * The options to create an {@link Alert}.
+     *
+     * @example
+     * ```typescript
+     * import { confimrAlert, Alert } from "@raycast/api";
+     *
+     * export default async () => {
+     *   const options: Alert.Options = {
+     *     title: "Finished cooking",
+     *     message: "Delicious pasta for lunch",
+     *     primaryAction: {
+     *       title: 'Do something',
+     *       onAction: () => {
+     *         // while you can register a handler for an action, it's more elegant
+     *         // to use the `if (await confirmAlert(...)) { ... }` pattern
+     *         console.log("The alert action has been triggered")
+     *       }
+     *     }
+     *   };
+     *   await confirmAlert(options);
+     * };
+     * ```
+     */
+    interface Options {
+        /**
+         * The icon of an alert to illustrate the action. Displayed on the top.
+         */
+        icon?: Image.ImageLike;
+        /**
+         * The title of an alert. Displayed below the icon.
+         */
+        title: string;
+        /**
+         * An additional message for an Alert. Useful to show more information, e.g. a confirmation message for a destructive action.
+         */
+        message?: string;
+        /**
+         * The primary Action the user can take.
+         */
+        primaryAction?: ActionOptions;
+        /**
+         * The Action to dismiss the alert. There usually shouldn't be any side effects when the user takes this action.
+         */
+        dismissAction?: ActionOptions;
+    }
+    /**
+     * The options to create an {@link Alert} Action.
+     */
+    interface ActionOptions {
+        /**
+         * The title of the action.
+         */
+        title: string;
+        /**
+         * The style of the action.
+         */
+        style?: ActionStyle;
+        /**
+         * A callback called when the action is triggered.
+         */
+        onAction?: () => void;
+    }
+    /**
+     * Defines the visual style of an Action of the Alert.
+     *
+     * @remarks
+     * Use {@link Alert.ActionStyle.Default} for confirmations of a positive action.
+     * Use {@link Alert.ActionStyle.Destructive} for confirmations of a destructive action (eg. deleting a file).
+     */
+    enum ActionStyle {
+        Default = "DEFAULT",
+        Cancel = "CANCEL",
+        Destructive = "DESTRUCTIVE"
+    }
+}