@raycast/api 1.26.2 → 1.28.0

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,5 @@
+export * from "./renderer";
+export { apiCallbacks } from "./callbacks";
+export * from "./reconciler";
+export type { FormValueModel } from "./node-builders/forms";
+export { wrapImageIfNeeded } from "./node-builders/utils";

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

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

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 @@
+export {};

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 takes an action.
+ * 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"
+    }
+}

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

@@ -0,0 +1,16 @@
+/**
+ * A HUD will automatically hide the main window and show a compact message at the bottom of the screen.
+ *
+ * @param title - The title that will be displayed for the HUD.
+ * @returns A Promise that resolves when the HUD is shown.
+ *
+ * @example
+ * ```typescript
+ * import { showHUD } from "@raycast/api";
+ *
+ * export default async () => {
+ *   await showHUD("Hey there 👋");
+ * };
+ * ```
+ */
+export declare function showHUD(title: string): Promise<void>;

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

@@ -0,0 +1,3 @@
+export * from "./alert";
+export { showToast, Toast } from "./toast";
+export * from "./hud";

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

@@ -0,0 +1,171 @@
+import { Keyboard } from "../../app";
+/**
+ * Creates and shows a Toast with the given {@link Toast.Options}.
+ *
+ * @param options - The options to customize the Toast.
+ * @returns A Promise that resolves with the shown Toast. The Toast can be used to change or hide it.
+ *
+ * @example
+ * ```typescript
+ * import { showToast, Toast } from "@raycast/api";
+ *
+ * export default async () => {
+ *   const success = false;
+ *
+ *   if (success) {
+ *     await showToast({ title: "Dinner is ready", message: "Pizza margherita" });
+ *   } else {
+ *     await showToast({ style: Toast.Style.Failure, title: "Dinner isn't ready", message: "Pizza dropped on the floor" });
+ *   }
+ * };
+ * ```
+ *
+ * When showing an animated Toast, you can later on update it:
+ * @example
+ * ```typescript
+ * import { showToast, Toast } from "@raycast/api";
+ * import { setTimeout } from "timers/promises";
+ *
+ * export default async () => {
+ *   const toast = await showToast({ style: Toast.Style.Animated, title: "Uploading image" });
+ *
+ *   await setTimeout(1000);
+ *
+ *   toast.style = ToastStyle.Success;
+ *   toast.title = "Uploaded image";
+ *
+ *   await setTimeout(500);
+ *
+ *   await toast.hide()
+ * };
+ * ```
+ */
+export declare function showToast(options: Toast.Options): Promise<Toast>;
+export declare function showToast(style: Toast.Style, title: string, message?: string): Promise<Toast>;
+/**
+ * A Toast with a certain style, title, and message.
+ *
+ * @example
+ * ```typescript
+ * import { showToast, Toast } from "@raycast/api";
+ * import { setTimeout } from "timers/promises";
+ *
+ * export default async () => {
+ *   const toast = await showToast({ style: Toast.Style.Animated, title: "Uploading image" });
+ *
+ *   await setTimeout(1000);
+ *
+ *   toast.style = Toast.Style.Success;
+ *   toast.title = "Uploaded image";
+ * };
+ * ```
+ */
+export declare class Toast {
+    private options;
+    private id;
+    private callbacks;
+    /**
+     * Deprecated - Use `showToast` instead
+     */
+    constructor(props: Toast.Options);
+    get style(): Toast.Style;
+    set style(style: Toast.Style);
+    get title(): string;
+    set title(title: string);
+    get message(): string | undefined;
+    set message(message: string | undefined);
+    get primaryAction(): Toast.ActionOptions | undefined;
+    set primaryAction(action: Toast.ActionOptions | undefined);
+    get secondaryAction(): Toast.ActionOptions | undefined;
+    set secondaryAction(action: Toast.ActionOptions | undefined);
+    /**
+     * Shows the Toast.
+     *
+     * @returns A Promise that resolves when the toast is shown.
+     */
+    show(): Promise<void>;
+    /**
+     * Hides the Toast.
+     *
+     * @returns A Promise that resolves when toast is hidden.
+     */
+    hide(): Promise<void>;
+    private update;
+}
+export declare namespace Toast {
+    /**
+     * The options to create a {@link Toast}.
+     *
+     * @example
+     * ```typescript
+     * import { showToast, Toast } from "@raycast/api";
+     *
+     * export default async () => {
+     *   const options: Toast.Options = {
+     *     style: Toast.Style.Success,
+     *     title: "Finished cooking",
+     *     message: "Delicious pasta for lunch",
+     *     primaryAction: {
+     *       title: 'Do something',
+     *       onAction: () => {
+     *         console.log("The toast action has been triggered")
+     *       }
+     *     }
+     *   };
+     *   await showToast(options);
+     * };
+     * ```
+     */
+    interface Options {
+        /**
+         * The title of a Toast. Displayed on the top.
+         */
+        title: string;
+        /**
+         * An additional message for the Toast. Useful to show more information, e.g. an identifier of a newly created asset.
+         */
+        message?: string;
+        /**
+         * The style of a Toast.
+         */
+        style?: Style;
+        /**
+         * The primary Action the user can take when hovering on the Toast.
+         */
+        primaryAction?: ActionOptions;
+        /**
+         * The secondary Action the user can take when hovering on the Toast.
+         */
+        secondaryAction?: ActionOptions;
+    }
+    /**
+     * The options to create a {@link Toast} Action.
+     */
+    interface ActionOptions {
+        /**
+         * The title of the action.
+         */
+        title: string;
+        /**
+         * The keyboard shortcut for the action.
+         */
+        shortcut?: Keyboard.Shortcut;
+        /**
+         * A callback called when the action is triggered.
+         */
+        onAction: (toast: Toast) => void;
+    }
+    /**
+     * Defines the visual style of the Toast.
+     *
+     * @remarks
+     * Use {@link Toast.Style.Success} for confirmations and {@link Toast.Style.Failure} for displaying errors.
+     * Use {@link Toast.Style.Animated} when your Toast should be shown until a process is completed.
+     * You can hide it later by using {@link Toast.hide} or update the properties of an existing Toast.
+     */
+    enum Style {
+        Success = "SUCCESS",
+        Failure = "FAILURE",
+        Animated = "ANIMATED"
+    }
+}

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

@@ -0,0 +1,88 @@
+/**
+ * List of built-in icons that can be used for actions or list items.
+ *
+ * @example
+ * ```typescript
+ * import { Icon, List } from "@raycast/api";
+ *
+ * export default function Command() {
+ *   return (
+ *     <List>
+ *       <List.Item title="Icon" icon={Icon.Circle} />
+ *     </List>
+ *   );
+ * };
+ * ```
+ */
+export declare enum Icon {
+    ArrowClockwise = "arrow-clockwise-16",
+    ArrowRight = "arrow-right-16",
+    Binoculars = "binoculars-16",
+    Bubble = "bubble-left-16",
+    Calendar = "calendar-16",
+    Checkmark = "checkmark-circle-16",
+    ChevronDown = "chevron-down-16",
+    ChevronUp = "chevron-up-16",
+    Circle = "circle-16",
+    Clipboard = "doc-on-clipboard-16",
+    Clock = "clock-16",
+    Desktop = "desktopcomputer-16",
+    Document = "doc-16",
+    Dot = "dot-16",
+    Download = "square-and-arrow-down-16",
+    Envelope = "envelope-16",
+    ExclamationMark = "exclamation-mark-triangle-16",
+    Eye = "eye-16",
+    EyeSlash = "eye-slash-16",
+    Finder = "finder-16",
+    Gear = "gearshape-16",
+    Globe = "globe-16",
+    Hammer = "hammer-16",
+    LevelMeter = "level-meter-16",
+    Link = "link-16",
+    List = "main-list-view-16",
+    MagnifyingGlass = "magnifyingglass-16",
+    MemoryChip = "memorychip-16",
+    Message = "message-16",
+    Pencil = "pencil-16",
+    Person = "person-crop-circle-16",
+    Phone = "phone-16",
+    Pin = "pin-16",
+    Plus = "plus-16",
+    Sidebar = "sidebar-right-16",
+    SpeakerArrowDown = "speaker-arrow-down-16",
+    SpeakerArrowUp = "speaker-arrow-up-16",
+    SpeakerSlash = "speaker-slash-16",
+    Star = "star-16",
+    Text = "text-alignleft-16",
+    TextDocument = "doc-plaintext-16",
+    QuestionMark = "questionmark-circle-16",
+    Terminal = "terminal-16",
+    Trash = "trash-16",
+    Upload = "square-and-arrow-up-16",
+    Video = "video-16",
+    Window = "macwindow-16",
+    XmarkCircle = "xmark-circle-16"
+}
+/**
+ * An icon as it's used in the Finder.
+ *
+ * @example
+ * ```typescript
+ * import { List } from "@raycast/api";
+ *
+ * export default function Command() {
+ *   return (
+ *     <List>
+ *       <List.Item title="File icon" icon={{ fileIcon: __filename }} />
+ *     </List>
+ *   );
+ * };
+ * ```
+ */
+export interface FileIcon {
+    /**
+     * The path to a file or folder to get its icon from.
+     */
+    fileIcon: string;
+}