@vicinae/api 0.16.4 → 0.16.6

package/dist/api/components/grid.d.ts

@@ -16,19 +16,63 @@ declare enum GridItemSize {
     Medium = "medium",// Fits 5 items per row.
     Large = "large"
 }
+/**
+ * Controls how the grid content should fit its allocated space.
+ */
 declare enum GridFit {
+    /**
+     * The content will be contained within the grid cell, with vertical/horizontal bars if its aspect ratio differs from the cell's
+     */
     Contain = "contain",
+    /**
+     * The content will be scaled proportionally so that it fill the entire cell; parts of the content could end up being cropped out.
+     */
     Fill = "fill"
 }
+/**
+ * A grid component is very similar to the {@link List} component, but is optimized to render items
+ * that are primarily represented as an icon or an image.
+ *
+ * Grids are commonly used to implement wallpaper, icon or emoji pickers.
+ *
+ * Grid can be organized in sections and define an arbitrary number of columns and aspect ratio.
+ *
+ * Grid can also render cells filled with a single color, which can be useful in order to implement color pickers.
+ *
+ * ![](../../../assets/grid.png)
+ *
+ * @category UI Components
+ */
 export declare namespace Grid {
     type BaseSection = {
+        /**
+         * Amount of space to keep free around the edges of each item.
+         * The real amount of space this translates to depends on the selected on the aspect ratio
+         * and the number of columns.
+         */
         inset?: GridInset;
         itemSize?: GridItemSize;
+        /**
+         * How many items to fit in a single row.
+         */
         columns?: number;
         fit?: GridFit;
+        /**
+         * Specific aspect ratio to enforce for every cell.
+         */
         aspectRatio?: Grid.AspectRatio;
     };
     export type Props = BaseSection & {
+        /**
+         * Amount of space to keep free around the edges of each item.
+         * The real amount of space this translates to depends on the selected on the aspect ratio
+         * and the number of columns.
+         */
+        inset?: GridInset;
+        itemSize?: GridItemSize;
+        columns?: number;
+        fit?: GridFit;
+        aspectRatio?: Grid.AspectRatio;
         actions?: React.ReactNode;
         children?: React.ReactNode;
         filtering?: boolean;
@@ -44,10 +88,18 @@ export declare namespace Grid {
         onSearchTextChange?: (text: string) => void;
         onSelectionChange?: (id: string) => void;
     };
+    /**
+     * A specific subsection of the grid.
+     * Each subsection can specificy its own number of columns and aspect ratio.
+     */
     export namespace Section {
         type Props = BaseSection & {
             title?: string;
             subtitle?: string;
+            /**
+             * The grid items that are part of this section.
+             * @see {@link Grid.Item}
+             */
             children?: ReactNode;
         };
     }
@@ -81,6 +133,9 @@ export declare namespace Grid {
     }
     export {};
 }
+/**
+ * @category UI Components
+ */
 export declare const Grid: React.FC<Grid.Props> & {
     Section: React.FC<Grid.Section.Props>;
     EmptyView: React.FC<import("./empty-view").EmptyViewProps>;

package/dist/api/components/grid.js

@@ -38,9 +38,18 @@ const aspectRatioMap = {
     "32/9": 32 / 9,
     "9/32": 9 / 32,
 };
+/**
+ * Controls how the grid content should fit its allocated space.
+ */
 var GridFit;
 (function (GridFit) {
+    /**
+     * The content will be contained within the grid cell, with vertical/horizontal bars if its aspect ratio differs from the cell's
+     */
     GridFit["Contain"] = "contain";
+    /**
+     * The content will be scaled proportionally so that it fill the entire cell; parts of the content could end up being cropped out.
+     */
     GridFit["Fill"] = "fill";
 })(GridFit || (GridFit = {}));
 const GridRoot = ({ searchBarAccessory, children, actions, inset, itemSize, fit = GridFit.Contain, aspectRatio = "1", ...props }) => {
@@ -98,6 +107,9 @@ const GridSection = ({ fit, aspectRatio, inset, ...props }) => {
     };
     return (0, jsx_runtime_1.jsx)("grid-section", { ...nativeProps });
 };
+/**
+ * @category UI Components
+ */
 exports.Grid = Object.assign(GridRoot, {
     Section: GridSection,
     EmptyView: empty_view_1.EmptyView,

package/dist/api/components/index.d.ts

@@ -1,4 +1,4 @@
-export * from "./list.js";
+export { List } from "./list.js";
 export * from "./grid.js";
 export * from "./detail.js";
 export * from "./action-pannel.js";

package/dist/api/components/index.js

@@ -14,7 +14,9 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./list.js"), exports);
+exports.List = void 0;
+var list_js_1 = require("./list.js");
+Object.defineProperty(exports, "List", { enumerable: true, get: function () { return list_js_1.List; } });
 __exportStar(require("./grid.js"), exports);
 __exportStar(require("./detail.js"), exports);
 __exportStar(require("./action-pannel.js"), exports);

package/dist/api/components/list.d.ts

@@ -1,24 +1,118 @@
-import React, { ReactNode } from "react";
+import type { ReactNode } from "react";
 import { type Image, type ImageLike, type SerializedImageLike } from "../image";
 import { type Color, type ColorLike, type SerializedColorLike } from "../color";
+/**
+ * A List component that can be used to render a list of items sharing a similar representation.
+ *
+ * This component comes with many quality of life features out of the box:
+ *
+ * - Items are fuzzy searched by default, without the need for explicit filtering logic
+ * - Items can be grouped in sections for clearer organization
+ * - Search can be throttled in order to provide typeahead experiences, ideal when dealing with remote data sources
+ * - Builtin loading indicator to show that something is loading
+ * - For a specific item, can render additonal markdown and metadata in a side panel
+ *
+ * ![](../../../assets/list.png)
+ *
+ * @category UI Components
+ */
 export declare namespace List {
     type Props = {
+        /**
+         * Action panel to use when no list item matches the current search query.
+         */
         actions?: React.ReactNode;
+        /**
+         * List items or sections to render inside this list.
+         */
         children?: React.ReactNode;
+        /**
+         * Whether to use Vicinae's builtin fuzzy filtering.
+         *
+         * This is turned on by default unless a `onSearchTextChange` handler is passed, indicating that
+         * custom filtering is desired.
+         */
         filtering?: boolean;
         /**
          * @deprecated use filtering
          */
         enableFiltering?: boolean;
+        /**
+         * If true, a loading indicator is shown right below the search bar to indicate loading activity.
+         */
         isLoading?: boolean;
+        /**
+         * Whether to show the current list item's detail, if any.
+         * If the current list item does not have a `detail`, this does nothing.
+         */
         isShowingDetail?: boolean;
+        /**
+         * Bind this prop to the value of the search text. This is used to turn the List into a [controlled component](https://react.dev/learn/sharing-state-between-components#controlled-and-uncontrolled-components).
+         */
         searchText?: string;
+        /**
+         * The placeholder to show in the search bar if there is no search query.
+         */
         searchBarPlaceholder?: string;
+        /**
+         * The navigation title to display on the bottom left of the status bar, next to the command icon.
+         * This defaults to the name of the command.
+         */
         navigationTitle?: string;
+        /**
+         * Accessory to show on the right of the search input.
+         * The list component only supports rendering a dropdown, in order to provide more filtering options.
+         *
+         * @see Dropdown
+         */
         searchBarAccessory?: ReactNode;
+        /**
+         * Throttle the search so that search text change events are sent after a short delay instead of instaneously.
+         * **Highly** recommended if you need to fetch data on every change.
+         * @default false
+         */
+        throttle?: boolean;
+        /**
+         * Called every time the user modifies the search text by typing or editing.
+         * This can be throttled using the `throttle` prop.
+         *
+         * @param text - The new search text
+         */
         onSearchTextChange?: (text: string) => void;
+        /**
+         * Called every time the currently selected item changes.
+         * Note that this does *not* fire when transitioning from having a selected item to none at all.
+         */
         onSelectionChange?: (id: string) => void;
     };
+    /**
+     * List items can be organized inside sections, in order to further categorize them.
+     *
+     * Note that item inside sections still benefit from automatic fuzzy filtering, but items remain grouped by
+     * section no matter their matching scores.
+     *
+     * A list can render sections and render items that are not inside any section.
+     * While this is generally considered bad design, it will work as list items placed outside sections
+     * will automatically be attached to an unnamed section.
+     *
+     * @example
+     * ```typescript
+     * export default MyCommand() {
+     * return (
+     *   <List>
+     *     <List.Section title="Section 1">
+     * 	     <List.Item title="Item 1" />
+     * 		   <List.Item title="Item 2" />
+     *     </List.Section />
+     *     <List.Section title="Section 2">
+     * 	     <List.Item title="Item 1" />
+     * 	     <List.Item title="Item 2" />
+     * 	   </List.Section />
+     *   </List>
+     * 	);
+     * }
+     * ```
+     */
     namespace Section {
         type Props = {
             title?: string;
@@ -26,24 +120,70 @@ export declare namespace List {
             children?: ReactNode;
         };
     }
+    /**
+     * An individual list item rendered in a fixed size row.
+     */
     namespace Item {
         type Props = {
             title: string;
+            /**
+             * Additional keywords the builtin filtering will consider when ranking items.
+             *
+             * Note that keywords match with a lower score than the title or subtitle fields.
+             *
+             * If builtin filtering is disabled, these are not used.
+             */
             keywords?: string[];
-            detail?: React.ReactNode;
+            /**
+             * Icon to show to the left of the item.
+             * @see {@link ImageLike}
+             */
             icon?: ImageLike | {
                 value: ImageLike | undefined | null;
                 tooltip: string;
             };
+            /**
+             * Unique identifier for this item.
+             * If not explicitly specified, Vicinae will create one automatically.
+             */
             id?: string;
+            /**
+             * Subtitle to show next to the title, using a dampened color.
+             */
             subtitle?: string;
+            /**
+             * Action panel to show when this item is selected.
+             */
             actions?: ReactNode;
             accessories?: List.Item.Accessory[];
+            /**
+             * Additional information to display in a side panel if it is the currently selected item.
+             * @see {@link List.Item.Detail}
+             */
+            detail?: React.ReactNode;
         };
+        /**
+         * Side panel which can be used to render markdown text and an optional metadata section.
+         * In order for a detail to be shown, the List's `isShowingDetail` prop should be set to `true` and the
+         * currently selected item should have a valid `detail` prop.
+         *
+         * ![](../../../assets/list-detail.png)
+         */
         namespace Detail {
             type Props = {
+                /**
+                 * Whether to show a loading indicator under the search bar.
+                 */
                 isLoading?: boolean;
+                /**
+                 * Markdown content to render in the main view.
+                 * @see {@link Detail}
+                 */
                 markdown?: string;
+                /**
+                 * Additional metadata.
+                 * @see Metadata
+                 */
                 metadata?: React.ReactNode;
             };
         }
@@ -82,10 +222,13 @@ export type SerializedAccessory = ({
     icon?: SerializedImageLike;
     tooltip?: string | null;
 };
-export declare const List: React.FC<List.Props> & {
-    Section: React.FC<List.Section.Props>;
-    EmptyView: React.FC<import("./empty-view").EmptyViewProps>;
-    Dropdown: React.FC<{
+/**
+ * @category UI Components
+ */
+export declare const List: import("react").FC<List.Props> & {
+    Section: import("react").FC<List.Section.Props>;
+    EmptyView: import("react").FC<import("./empty-view").EmptyViewProps>;
+    Dropdown: import("react").FC<{
         tooltip?: string;
         children?: ReactNode;
         defaultValue?: string;
@@ -99,26 +242,26 @@ export declare const List: React.FC<List.Props> & {
         onChange?: (newValue: string) => void;
         onSearchTextChange?: (text: string) => void;
     }> & {
-        Item: React.FC<{
+        Item: import("react").FC<{
             title: string;
             value: string;
             icon?: Image.ImageLike;
             keywords?: string[];
         }>;
-        Section: React.FC<{
+        Section: import("react").FC<{
             title?: string;
             children?: ReactNode;
         }>;
     };
-    Item: React.FC<List.Item.Props> & {
-        Detail: React.FC<List.Item.Detail.Props> & {
-            Metadata: React.FC<import("./metadata").MetadataProps> & {
-                Label: React.FC<import("./metadata").ListItemDetailMetadataLabelProps>;
-                Separator: React.FC<{}>;
-                TagList: React.FC<import("./tag").TagListProps> & {
-                    Item: React.FC<import("./tag").TagItemProps>;
+    Item: import("react").FC<List.Item.Props> & {
+        Detail: import("react").FC<List.Item.Detail.Props> & {
+            Metadata: import("react").FC<import("./metadata").MetadataProps> & {
+                Label: import("react").FC<import("./metadata").ListItemDetailMetadataLabelProps>;
+                Separator: import("react").FC<{}>;
+                TagList: import("react").FC<import("./tag").TagListProps> & {
+                    Item: import("react").FC<import("./tag").TagItemProps>;
                 };
-                Link: React.FC<{
+                Link: import("react").FC<{
                     title: string;
                     target: string;
                     text: string;

package/dist/api/components/list.js

@@ -4,7 +4,7 @@ exports.List = void 0;
 const jsx_runtime_1 = require("react/jsx-runtime");
 const react_1 = require("react");
 const image_1 = require("../image");
-const crypto_1 = require("crypto");
+const node_crypto_1 = require("node:crypto");
 const metadata_1 = require("./metadata");
 const empty_view_1 = require("./empty-view");
 const color_1 = require("../color");
@@ -49,7 +49,7 @@ const ListRoot = ({ searchBarAccessory, children, actions, ...props }) => {
     return ((0, jsx_runtime_1.jsxs)("list", { ...props, children: [searchBarAccessory, children, actions] }));
 };
 const ListItem = ({ detail, actions, icon, accessories, ...props }) => {
-    const id = (0, react_1.useRef)(props.id ?? (0, crypto_1.randomUUID)());
+    const id = (0, react_1.useRef)(props.id ?? (0, node_crypto_1.randomUUID)());
     // Icon
     let serializedIcon;
     if (icon && typeof icon === "object" && "value" in icon) {
@@ -71,6 +71,9 @@ const ListItemDetail = ({ metadata, ...props }) => {
 const ListSection = (props) => {
     return (0, jsx_runtime_1.jsx)("list-section", { ...props });
 };
+/**
+ * @category UI Components
+ */
 exports.List = Object.assign(ListRoot, {
     Section: ListSection,
     EmptyView: empty_view_1.EmptyView,

package/dist/api/components/menu-bar.d.ts

@@ -17,6 +17,9 @@ type MenuBarExtraItemProps = {
     tooltip?: string;
     onAction?: (event: any) => void;
 };
+/**
+ * @ignore
+ */
 export declare const MenuBarExtra: import("react").FC<MenuBarExtraProps> & {
     Item: import("react").FC<MenuBarExtraItemProps>;
     Submenu: import("react").FC<any>;

package/dist/api/components/menu-bar.js

@@ -17,6 +17,9 @@ const Section = () => {
 const Separator = () => {
     return (0, jsx_runtime_1.jsx)("separator", {});
 };
+/**
+ * @ignore
+ */
 exports.MenuBarExtra = Object.assign(Root, {
     Item,
     Submenu,

package/dist/api/components/metadata.d.ts

@@ -1,11 +1,15 @@
 import React from "react";
 import { type ImageLike } from "../image";
+import { type ColorLike } from "../color";
 export type MetadataProps = {
     children?: React.ReactNode;
 };
 export type ListItemDetailMetadataLabelProps = {
     title: string;
-    text: string;
+    text: string | {
+        color?: ColorLike;
+        value: string;
+    };
     icon?: ImageLike;
 };
 export type ListItemDetailMetadataSeparator = {};

package/dist/api/components/metadata.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Metadata = void 0;
 const jsx_runtime_1 = require("react/jsx-runtime");
 const image_1 = require("../image");
+const color_1 = require("../color");
 const tag_1 = require("./tag");
 const MetadataRoot = (props) => {
     return (0, jsx_runtime_1.jsx)("metadata", { ...props });
@@ -11,7 +12,18 @@ const MetadataLabel = (props) => {
     const serializedIcon = props.icon
         ? (0, image_1.serializeProtoImage)(props.icon)
         : props.icon;
-    return (0, jsx_runtime_1.jsx)("metadata-label", { ...props, icon: serializedIcon });
+    let serializedText;
+    if (props.text && typeof props.text === "object") {
+        serializedText = {
+            color: props.text.color ? (0, color_1.serializeColorLike)(props.text.color) : undefined,
+            value: props.text.value,
+        };
+    }
+    else {
+        serializedText = props.text;
+    }
+    const { text, ...restProps } = props;
+    return (0, jsx_runtime_1.jsx)("metadata-label", { ...restProps, icon: serializedIcon, text: serializedText });
 };
 const MetadataSeparator = () => {
     return (0, jsx_runtime_1.jsx)("metadata-separator", {});

package/dist/api/context/navigation-provider.d.ts

@@ -1,4 +1,7 @@
 import React, { ReactNode } from "react";
+/**
+ * @ignore
+ */
 export declare const NavigationProvider: React.FC<{
     root: ReactNode;
 }>;

package/dist/api/context/navigation-provider.js

@@ -11,6 +11,9 @@ const bus_1 = require("../bus");
 const View = ({ children }) => {
     return (0, jsx_runtime_1.jsx)("view", { children: children });
 };
+/**
+ * @ignore
+ */
 const NavigationProvider = ({ root }) => {
     const [navStack, setNavStack] = (0, react_1.useState)([root]);
     const pop = () => {

package/dist/api/controls.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @category Launcher Window
+ */
 export declare enum PopToRootType {
     /**
      * Translates to Immediate or Suspended depending on the
@@ -20,6 +23,8 @@ export declare enum PopToRootType {
  * by passing options to this function.
  *
  * @see closeWindow
+ *
+ * @category Launcher Window
  */
 export declare const showHUD: (title: string, options?: {
     clearRootSearch?: boolean;
@@ -28,20 +33,29 @@ export declare const showHUD: (title: string, options?: {
 /**
  * Close the vicinae launcher window immediately.
  * It is possible to override the `popToRoot` behavior defined in the settings using the options object.
+ *
+ * @category Launcher Window
  */
 export declare const closeMainWindow: (options?: {
     clearRootSearch?: boolean;
     popToRootType?: PopToRootType;
 }) => Promise<void>;
+/**
+ * @category Launcher Window
+ */
 export declare const clearSearchBar: () => Promise<void>;
 /**
  * Get the text that is currently selected by the user.
  * How this is implemented depends on the environment but all it does is usually
  * read the clipboard's primary selection buffer.
+ *
+ * @category Launcher Window
  */
 export declare const getSelectedText: () => Promise<string>;
 /**
  * Pop to the root of the navigation stack, optionally clearing the search bar.
+ *
+ * @category Launcher Window
  */
 export declare const popToRoot: (options?: {
     clearSearchBar?: boolean;

package/dist/api/controls.js

@@ -36,7 +36,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.popToRoot = exports.getSelectedText = exports.clearSearchBar = exports.closeMainWindow = exports.showHUD = exports.PopToRootType = void 0;
 const bus_1 = require("./bus");
 const ui = __importStar(require("./proto/ui"));
-//e
+/**
+ * @category Launcher Window
+ */
 var PopToRootType;
 (function (PopToRootType) {
     /**
@@ -65,6 +67,8 @@ const popToRootProtoMap = {
  * by passing options to this function.
  *
  * @see closeWindow
+ *
+ * @category Launcher Window
  */
 const showHUD = async (title, options) => {
     bus_1.bus.turboRequest("ui.showHud", {
@@ -77,6 +81,8 @@ exports.showHUD = showHUD;
 /**
  * Close the vicinae launcher window immediately.
  * It is possible to override the `popToRoot` behavior defined in the settings using the options object.
+ *
+ * @category Launcher Window
  */
 const closeMainWindow = async (options = {}) => {
     const { clearRootSearch = false, popToRootType = PopToRootType.Default } = options;
@@ -86,6 +92,9 @@ const closeMainWindow = async (options = {}) => {
     });
 };
 exports.closeMainWindow = closeMainWindow;
+/**
+ * @category Launcher Window
+ */
 const clearSearchBar = async () => {
     await bus_1.bus.turboRequest("ui.setSearchText", { text: "" });
 };
@@ -94,6 +103,8 @@ exports.clearSearchBar = clearSearchBar;
  * Get the text that is currently selected by the user.
  * How this is implemented depends on the environment but all it does is usually
  * read the clipboard's primary selection buffer.
+ *
+ * @category Launcher Window
  */
 const getSelectedText = async () => {
     const response = await bus_1.bus.turboRequest("ui.getSelectedText", {});
@@ -105,6 +116,8 @@ const getSelectedText = async () => {
 exports.getSelectedText = getSelectedText;
 /**
  * Pop to the root of the navigation stack, optionally clearing the search bar.
+ *
+ * @category Launcher Window
  */
 const popToRoot = async (options) => {
     await bus_1.bus.turboRequest("ui.popToRoot", {

package/dist/api/environment.d.ts

@@ -131,4 +131,15 @@ export interface Environment {
      */
     isRaycast: boolean;
 }
+/**
+ * General information about the running extension command, the vicinae version, the capabilities of
+ * the system we are running on, etc...
+ *
+ * @example
+ * ```typescript
+ * import { environment } from '@vicinae/api';
+ *
+ * console.log({ environment });
+ * ```
+ */
 export declare const environment: Environment;

package/dist/api/environment.js

@@ -12,4 +12,15 @@ var LaunchType;
      */
     LaunchType["Background"] = "background";
 })(LaunchType || (exports.LaunchType = LaunchType = {}));
+/**
+ * General information about the running extension command, the vicinae version, the capabilities of
+ * the system we are running on, etc...
+ *
+ * @example
+ * ```typescript
+ * import { environment } from '@vicinae/api';
+ *
+ * console.log({ environment });
+ * ```
+ */
 exports.environment = {};

package/dist/api/file-search.d.ts

@@ -15,6 +15,7 @@ import { FileInfo as ProtoFileInfo } from "./proto/file-search";
  * console.log(`Found ${results.length} files`);
  * ```
  *
+ * @category File Search
  * @public
  */
 export declare namespace FileSearch {

package/dist/api/file-search.js

@@ -18,6 +18,7 @@ const bus_1 = require("./bus");
  * console.log(`Found ${results.length} files`);
  * ```
  *
+ * @category File Search
  * @public
  */
 var FileSearch;

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

@@ -1,2 +1 @@
-export * from "./use-applications";
 export * from "./use-navigation";

package/dist/api/hooks/index.js

@@ -14,5 +14,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./use-applications"), exports);
 __exportStar(require("./use-navigation"), exports);

package/dist/api/hooks/use-imperative-form-handle.d.ts

@@ -1,3 +1,3 @@
-import { FormItemRef } from "../components/form";
-import { Ref } from "react";
-export declare const useImperativeFormHandle: (ref?: Ref<FormItemRef>) => [string];
+import type { Form } from "../components/form";
+import type { Ref } from "react";
+export declare const useImperativeFormHandle: (ref?: Ref<Form.ItemReference>) => [string];