@raycast/api 1.27.0 → 1.29.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 {};