@raycast/api 1.42.2 → 1.43.0

package/api.d.ts

@@ -389,6 +389,10 @@ declare interface ActionProps {
      * Callback that is triggered when the item is selected.
      */
     onAction?: () => void;
+    /**
+     * Indicates whether the Action should be focused automatically when the parent ActionPanel (or Actionpanel.Submenu) opens.
+     */
+    autoFocus?: boolean;
 }
 
 /**
@@ -1914,11 +1918,11 @@ declare interface DropdownProps_2 {
      */
     defaultValue?: string;
     /**
-     * Grid sections or items. If Dropdown.Item elements are specified, a default section is automatically created.
+     * Dropdown sections or items. If Dropdown.Item elements are specified, a default section is automatically created.
      */
     children?: ReactNode;
     /**
-     * Callback triggered when the grid item selection changes.
+     * Callback triggered when the dropdown selection changes.
      */
     onChange?: (newValue: string) => void;
 }
@@ -2082,6 +2086,39 @@ export declare interface FileIcon {
     fileIcon: string;
 }
 
+/**
+ * See {@link Form.FilePicker}
+ */
+declare const FilePicker: ForwardRefExoticComponent<FilePickerProps & RefAttributes<FilePickerRef>>;
+
+/**
+ * See {@link Form.FilePicker.Props}
+ */
+declare interface FilePickerProps extends FormItemProps_2<string[]> {
+    /**
+     * Indicates whether it's possible to choose a file.
+     * @defaultValue `true`
+     */
+    canChooseFiles?: boolean;
+    /**
+     * Indicates whether it's possible to choose a directory.
+     * @defaultValue `false`
+     */
+    canChooseDirectories?: boolean;
+    /**
+     * Indicates whether the file picker displays files that are normally hidden from the user.
+     * @defaultValue `false`
+     */
+    showHiddenFiles?: boolean;
+    /**
+     * Indicates whether the user can select multiple items or only one.
+     * @defaultValue `true`
+     */
+    allowMultipleSelection?: boolean;
+}
+
+declare type FilePickerRef = FormItemRef;
+
 /**
  * Holds data about a File System item. Use the {@link getSelectedFinderItems} method to retrieve values.
  */
@@ -2686,6 +2723,77 @@ export declare namespace Form {
             export type Props = TagPickerItemProps;
         }
     }
+    /**
+     * A Ref Type for the {@link Form.FilePicker}.
+     * Use refs to control your Form by calling `Form.FilePicker.focus()` or `Form.FilePicker.reset()` functions.
+     *
+     * @example
+     * Using Ref to focus {@link Form.FilePicker}.
+     *
+     * ```typescript
+     * import { Form, ActionPanel, Action } from "@raycast/api";
+     * import { useRef } from "react";
+     *
+     * export default function Command() {
+     *   const filePickerRef = useRef<Form.FilePicker>(null);
+     *
+     *   return (
+     *     <Form
+     *       actions={
+     *         <ActionPanel>
+     *           <Action.SubmitForm
+     *             title="Submit"
+     *             onSubmit={(values) => {
+     *               filePickerRef.current?.focus();
+     *               console.log("Values", values);
+     *             }}
+     *           />
+     *         </ActionPanel>
+     *       }
+     *     >
+     *       <Form.FilePicker id="files" ref={filePickerRef} />
+     *     </Form>
+     *   );
+     * }
+     * ```
+     *
+     * @example
+     * Using Ref to reset {@link Form.FilePicker}.
+     *
+     * ```typescript
+     * import { Form, ActionPanel, Action } from "@raycast/api";
+     * import { useRef } from "react";
+     *
+     * export default function Command() {
+     *   const filePickerRef = useRef<Form.FilePicker>(null);
+     *
+     *   return (
+     *     <Form
+     *       actions={
+     *         <ActionPanel>
+     *           <Action.SubmitForm
+     *             title="Submit"
+     *             onSubmit={(values) => {
+     *               filePickerRef.current?.reset();
+     *               console.log("Values", values);
+     *             }}
+     *           />
+     *         </ActionPanel>
+     *       }
+     *     >
+     *       <Form.FilePicker id="files" ref={filePickerRef} />
+     *     </Form>
+     *   );
+     * }
+     * ```
+     */
+    export type FilePicker = FilePickerRef;
+    export namespace FilePicker {
+        /**
+         * Props of the {@link Form.TextField} React component.
+         */
+        export type Props = FilePickerProps;
+    }
 }
 
 /**
@@ -3368,6 +3476,117 @@ declare interface FormMembers {
      * ```
      */
     TextField: typeof TextField;
+    /**
+     * A form item with a button to open a dialog to pick some files and/or some directories (depending on its props).
+     *
+     * _While the user picked some items that existed, it might be possible for them to be deleted or changed when the `onSubmit` callback is called. Hence you should always make sure that the items exist before acting on them!_
+     *
+     * @example
+     * Uncontrolled file picker
+     *
+     * ```typescript
+     * import { ActionPanel, Form, Action } from "@raycast/api";
+     * import fs from "fs";
+     *
+     * export default function Command() {
+     *   return (
+     *     <Form
+     *       actions={
+     *         <ActionPanel>
+     *           <Action.SubmitForm title="Submit Name" onSubmit={(values) => {
+     *               const files = values.files.filter(
+     *                 file => fs.existsSync(values.file) && fs.lstatSync(values.file).isFile()
+     *               )
+     *               // do something with the files
+     *             } />
+     *         </ActionPanel>
+     *       }
+     *     >
+     *       <Form.FilePicker id="files" />
+     *     </Form>
+     *   );
+     * }
+     * ```
+     *
+     * @example
+     * Single selection file picker
+     *
+     * ```typescript
+     * import { ActionPanel, Form, Action } from "@raycast/api";
+     * import fs from "fs";
+     *
+     * export default function Command() {
+     *   return (
+     *     <Form
+     *       actions={
+     *         <ActionPanel>
+     *           <Action.SubmitForm title="Submit Name" onSubmit={(values) => {
+     *               const file = values.file[0]
+     *               if (fs.existsSync(file) && fs.lstatSync(file).isFile()) {
+     *                 // do something with the file
+     *               }
+     *             } />
+     *         </ActionPanel>
+     *       }
+     *     >
+     *       <Form.FilePicker id="file" allowMultipleSelection={false} />
+     *     </Form>
+     *   );
+     * }
+     * ```
+     *
+     * @example
+     * Directory picker
+     *
+     * ```typescript
+     * import { ActionPanel, Form, Action } from "@raycast/api";
+     * import fs from "fs";
+     *
+     * export default function Command() {
+     *   return (
+     *     <Form
+     *       actions={
+     *         <ActionPanel>
+     *           <Action.SubmitForm title="Submit Name" onSubmit={(values) => {
+     *               const file = values.file[0]
+     *               if (fs.existsSync(file) && fs.lstatSync(file).isDirectory()) {
+     *                 // do something with the directory
+     *               }
+     *             } />
+     *         </ActionPanel>
+     *       }
+     *     >
+     *       <Form.FilePicker id="file" allowMultipleSelection={false} canChooseDirectories canChooseFiles={false} />
+     *     </Form>
+     *   );
+     * }
+     * ```
+     *
+     * @example
+     * Controlled file picker
+     *
+     * ```typescript
+     * import { ActionPanel, Form, Action } from "@raycast/api";
+     * import { useState } from "react";
+     *
+     * export default function Command() {
+     *   const [files, setFiles] = useState<string[]>([]);
+     *
+     *   return (
+     *     <Form
+     *       actions={
+     *         <ActionPanel>
+     *           <Action.SubmitForm title="Submit Name" onSubmit={(values) => console.log(values)} />
+     *         </ActionPanel>
+     *       }
+     *     >
+     *       <Form.FilePicker id="files" value={files} onChange={setFiles} />
+     *     </Form>
+     *   );
+     * }
+     * ```
+     */
+    FilePicker: typeof FilePicker;
 }
 
 /**
@@ -4012,7 +4231,7 @@ declare interface GridProps extends ActionsInterface, NavigationChildInterface {
      * Callback triggered when the search bar text changes.
      *
      * @remarks
-     * Specifying this implicitly toggles `enableFiltering` to false. To enable native filtering when using `onSearchTextChange`, explicitly set `enableFiltering` to true.
+     * Specifying this implicitly toggles `filtering` to false. To enable native filtering when using `onSearchTextChange`, explicitly set `filtering` to true.
      */
     onSearchTextChange?: (text: string) => void;
 }
@@ -4109,9 +4328,13 @@ export declare enum Icon {
     Checkmark = "check-circle-16",
     ChessPiece = "chess-piece-16",
     ChevronDown = "chevron-down-16",
+    ChevronDownSmall = "chevron-down-small-16",
     ChevronLeft = "chevron-left-16",
+    ChevronLeftSmall = "chevron-left-small-16",
     ChevronRight = "chevron-right-16",
+    ChevronRightSmall = "chevron-right-small-16",
     ChevronUp = "chevron-up-16",
+    ChevronUpSmall = "chevron-up-small-16",
     Circle = "circle-16",
     CircleEllipsis = "circle-ellipsis-16",
     CircleFilled = "circle-filled-16",
@@ -4207,6 +4430,7 @@ export declare enum Icon {
     Link = "link-16",
     List = "app-window-list-16",
     Livestream = "livestream-01-16",
+    LivestreamDisabled = "livestream-disabled-01-16",
     Lock = "lock-16",
     LockDisabled = "lock-disabled-16",
     LockUnlocked = "lock-unlocked-16",
@@ -6892,6 +7116,10 @@ declare interface SubmenuProps {
      * ```
      */
     onOpen?: () => void;
+    /**
+     * Indicates whether the ActionPanel.Submenu should be focused automatically when the parent ActionPanel (or Actionpanel.Submenu) opens.
+     */
+    autoFocus?: boolean;
 }
 
 declare interface SubmenuProps_2 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raycast/api",
-  "version": "1.42.2",
+  "version": "1.43.0",
   "description": "Build extensions for Raycast with React and Node.js.",
   "author": "Raycast Technologies Ltd.",
   "homepage": "https://developers.raycast.com",

package/types/index.d.ts

@@ -389,6 +389,10 @@ declare interface ActionProps {
      * Callback that is triggered when the item is selected.
      */
     onAction?: () => void;
+    /**
+     * Indicates whether the Action should be focused automatically when the parent ActionPanel (or Actionpanel.Submenu) opens.
+     */
+    autoFocus?: boolean;
 }
 
 /**
@@ -1914,11 +1918,11 @@ declare interface DropdownProps_2 {
      */
     defaultValue?: string;
     /**
-     * Grid sections or items. If Dropdown.Item elements are specified, a default section is automatically created.
+     * Dropdown sections or items. If Dropdown.Item elements are specified, a default section is automatically created.
      */
     children?: ReactNode;
     /**
-     * Callback triggered when the grid item selection changes.
+     * Callback triggered when the dropdown selection changes.
      */
     onChange?: (newValue: string) => void;
 }
@@ -2082,6 +2086,39 @@ export declare interface FileIcon {
     fileIcon: string;
 }
 
+/**
+ * See {@link Form.FilePicker}
+ */
+declare const FilePicker: ForwardRefExoticComponent<FilePickerProps & RefAttributes<FilePickerRef>>;
+
+/**
+ * See {@link Form.FilePicker.Props}
+ */
+declare interface FilePickerProps extends FormItemProps_2<string[]> {
+    /**
+     * Indicates whether it's possible to choose a file.
+     * @defaultValue `true`
+     */
+    canChooseFiles?: boolean;
+    /**
+     * Indicates whether it's possible to choose a directory.
+     * @defaultValue `false`
+     */
+    canChooseDirectories?: boolean;
+    /**
+     * Indicates whether the file picker displays files that are normally hidden from the user.
+     * @defaultValue `false`
+     */
+    showHiddenFiles?: boolean;
+    /**
+     * Indicates whether the user can select multiple items or only one.
+     * @defaultValue `true`
+     */
+    allowMultipleSelection?: boolean;
+}
+
+declare type FilePickerRef = FormItemRef;
+
 /**
  * Holds data about a File System item. Use the {@link getSelectedFinderItems} method to retrieve values.
  */
@@ -2686,6 +2723,77 @@ export declare namespace Form {
             export type Props = TagPickerItemProps;
         }
     }
+    /**
+     * A Ref Type for the {@link Form.FilePicker}.
+     * Use refs to control your Form by calling `Form.FilePicker.focus()` or `Form.FilePicker.reset()` functions.
+     *
+     * @example
+     * Using Ref to focus {@link Form.FilePicker}.
+     *
+     * ```typescript
+     * import { Form, ActionPanel, Action } from "@raycast/api";
+     * import { useRef } from "react";
+     *
+     * export default function Command() {
+     *   const filePickerRef = useRef<Form.FilePicker>(null);
+     *
+     *   return (
+     *     <Form
+     *       actions={
+     *         <ActionPanel>
+     *           <Action.SubmitForm
+     *             title="Submit"
+     *             onSubmit={(values) => {
+     *               filePickerRef.current?.focus();
+     *               console.log("Values", values);
+     *             }}
+     *           />
+     *         </ActionPanel>
+     *       }
+     *     >
+     *       <Form.FilePicker id="files" ref={filePickerRef} />
+     *     </Form>
+     *   );
+     * }
+     * ```
+     *
+     * @example
+     * Using Ref to reset {@link Form.FilePicker}.
+     *
+     * ```typescript
+     * import { Form, ActionPanel, Action } from "@raycast/api";
+     * import { useRef } from "react";
+     *
+     * export default function Command() {
+     *   const filePickerRef = useRef<Form.FilePicker>(null);
+     *
+     *   return (
+     *     <Form
+     *       actions={
+     *         <ActionPanel>
+     *           <Action.SubmitForm
+     *             title="Submit"
+     *             onSubmit={(values) => {
+     *               filePickerRef.current?.reset();
+     *               console.log("Values", values);
+     *             }}
+     *           />
+     *         </ActionPanel>
+     *       }
+     *     >
+     *       <Form.FilePicker id="files" ref={filePickerRef} />
+     *     </Form>
+     *   );
+     * }
+     * ```
+     */
+    export type FilePicker = FilePickerRef;
+    export namespace FilePicker {
+        /**
+         * Props of the {@link Form.TextField} React component.
+         */
+        export type Props = FilePickerProps;
+    }
 }
 
 /**
@@ -3368,6 +3476,117 @@ declare interface FormMembers {
      * ```
      */
     TextField: typeof TextField;
+    /**
+     * A form item with a button to open a dialog to pick some files and/or some directories (depending on its props).
+     *
+     * _While the user picked some items that existed, it might be possible for them to be deleted or changed when the `onSubmit` callback is called. Hence you should always make sure that the items exist before acting on them!_
+     *
+     * @example
+     * Uncontrolled file picker
+     *
+     * ```typescript
+     * import { ActionPanel, Form, Action } from "@raycast/api";
+     * import fs from "fs";
+     *
+     * export default function Command() {
+     *   return (
+     *     <Form
+     *       actions={
+     *         <ActionPanel>
+     *           <Action.SubmitForm title="Submit Name" onSubmit={(values) => {
+     *               const files = values.files.filter(
+     *                 file => fs.existsSync(values.file) && fs.lstatSync(values.file).isFile()
+     *               )
+     *               // do something with the files
+     *             } />
+     *         </ActionPanel>
+     *       }
+     *     >
+     *       <Form.FilePicker id="files" />
+     *     </Form>
+     *   );
+     * }
+     * ```
+     *
+     * @example
+     * Single selection file picker
+     *
+     * ```typescript
+     * import { ActionPanel, Form, Action } from "@raycast/api";
+     * import fs from "fs";
+     *
+     * export default function Command() {
+     *   return (
+     *     <Form
+     *       actions={
+     *         <ActionPanel>
+     *           <Action.SubmitForm title="Submit Name" onSubmit={(values) => {
+     *               const file = values.file[0]
+     *               if (fs.existsSync(file) && fs.lstatSync(file).isFile()) {
+     *                 // do something with the file
+     *               }
+     *             } />
+     *         </ActionPanel>
+     *       }
+     *     >
+     *       <Form.FilePicker id="file" allowMultipleSelection={false} />
+     *     </Form>
+     *   );
+     * }
+     * ```
+     *
+     * @example
+     * Directory picker
+     *
+     * ```typescript
+     * import { ActionPanel, Form, Action } from "@raycast/api";
+     * import fs from "fs";
+     *
+     * export default function Command() {
+     *   return (
+     *     <Form
+     *       actions={
+     *         <ActionPanel>
+     *           <Action.SubmitForm title="Submit Name" onSubmit={(values) => {
+     *               const file = values.file[0]
+     *               if (fs.existsSync(file) && fs.lstatSync(file).isDirectory()) {
+     *                 // do something with the directory
+     *               }
+     *             } />
+     *         </ActionPanel>
+     *       }
+     *     >
+     *       <Form.FilePicker id="file" allowMultipleSelection={false} canChooseDirectories canChooseFiles={false} />
+     *     </Form>
+     *   );
+     * }
+     * ```
+     *
+     * @example
+     * Controlled file picker
+     *
+     * ```typescript
+     * import { ActionPanel, Form, Action } from "@raycast/api";
+     * import { useState } from "react";
+     *
+     * export default function Command() {
+     *   const [files, setFiles] = useState<string[]>([]);
+     *
+     *   return (
+     *     <Form
+     *       actions={
+     *         <ActionPanel>
+     *           <Action.SubmitForm title="Submit Name" onSubmit={(values) => console.log(values)} />
+     *         </ActionPanel>
+     *       }
+     *     >
+     *       <Form.FilePicker id="files" value={files} onChange={setFiles} />
+     *     </Form>
+     *   );
+     * }
+     * ```
+     */
+    FilePicker: typeof FilePicker;
 }
 
 /**
@@ -4012,7 +4231,7 @@ declare interface GridProps extends ActionsInterface, NavigationChildInterface {
      * Callback triggered when the search bar text changes.
      *
      * @remarks
-     * Specifying this implicitly toggles `enableFiltering` to false. To enable native filtering when using `onSearchTextChange`, explicitly set `enableFiltering` to true.
+     * Specifying this implicitly toggles `filtering` to false. To enable native filtering when using `onSearchTextChange`, explicitly set `filtering` to true.
      */
     onSearchTextChange?: (text: string) => void;
 }
@@ -4109,9 +4328,13 @@ export declare enum Icon {
     Checkmark = "check-circle-16",
     ChessPiece = "chess-piece-16",
     ChevronDown = "chevron-down-16",
+    ChevronDownSmall = "chevron-down-small-16",
     ChevronLeft = "chevron-left-16",
+    ChevronLeftSmall = "chevron-left-small-16",
     ChevronRight = "chevron-right-16",
+    ChevronRightSmall = "chevron-right-small-16",
     ChevronUp = "chevron-up-16",
+    ChevronUpSmall = "chevron-up-small-16",
     Circle = "circle-16",
     CircleEllipsis = "circle-ellipsis-16",
     CircleFilled = "circle-filled-16",
@@ -4207,6 +4430,7 @@ export declare enum Icon {
     Link = "link-16",
     List = "app-window-list-16",
     Livestream = "livestream-01-16",
+    LivestreamDisabled = "livestream-disabled-01-16",
     Lock = "lock-16",
     LockDisabled = "lock-disabled-16",
     LockUnlocked = "lock-unlocked-16",
@@ -6892,6 +7116,10 @@ declare interface SubmenuProps {
      * ```
      */
     onOpen?: () => void;
+    /**
+     * Indicates whether the ActionPanel.Submenu should be focused automatically when the parent ActionPanel (or Actionpanel.Submenu) opens.
+     */
+    autoFocus?: boolean;
 }
 
 declare interface SubmenuProps_2 {